net-mesh 0.33.0

//! MeshNode: multi-peer mesh runtime composing all protocol layers.
//!
//! `MeshNode` is the composition layer that turns independent components
//! (encrypted sessions, router, failure detector) into a functioning mesh
//! node that can communicate with multiple peers simultaneously over a
//! single UDP socket.
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────┐
//! │                  MeshNode                   │
//! │                                             │
//! │  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
//! │  │ Session A│  │ Session B│  │ Session C│  │
//! │  └────┬─────┘  └────┬─────┘  └────┬─────┘  │
//! │       │              │              │       │
//! │  ┌────┴──────────────┴──────────────┴────┐  │
//! │  │          Receive Loop (single)        │  │
//! │  │  demux by source_addr → session       │  │
//! │  │  local → decrypt → queue              │  │
//! │  │  forward → router (no decrypt)        │  │
//! │  └───────────────┬───────────────────────┘  │
//! │                  │                          │
//! │  ┌───────────────┴───────────────────────┐  │
//! │  │         UDP Socket (shared)           │  │
//! │  └───────────────────────────────────────┘  │
//! └─────────────────────────────────────────────┘
//! ```

use std::collections::HashMap;
use std::net::SocketAddr;
use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};

use arc_swap::ArcSwapOption;
use std::sync::Arc;
use std::time::{Duration, Instant};

use async_trait::async_trait;
use bytes::Bytes;
use crossbeam_queue::SegQueue;
use dashmap::DashMap;
use tokio::sync::Notify;
use tokio::task::JoinHandle;

use super::crypto::{handshake_prologue, CryptoError, NoiseHandshake, SessionKeys, StaticKeypair};
use super::failure::{FailureDetector, FailureDetectorConfig, NodeStatus};
use super::identity::{
    EntityId, EntityKeypair, PermissionToken, RevocationRegistry, TokenCache, TokenChain,
    TokenScope,
};
use super::pool::PacketBuilder;

use super::behavior::broadcast::{
    RouteWithdrawal, WithdrawalSeqGate, SUBPROTOCOL_CAPABILITY_ANN, SUBPROTOCOL_ROUTE_WITHDRAW,
};
use super::behavior::capability::{
    CapabilityAnnouncement, CapabilityFilter, CapabilitySet, ScopeFilter, MAX_CAPABILITY_HOPS,
};
use super::behavior::loadbalance::HealthStatus;
use super::behavior::proximity::{
    EnhancedPingwave, PingwaveAdmission, ProximityConfig, ProximityGraph,
};
// SI-2a (SENSING_INTEREST_COALESCING_PLAN v4.3): the sensing plane's
// dispatch wiring. Imported as a module (not item-by-item) so every
// sensing type reads `sensing::…` at its use site — the plane is new
// enough that the provenance is worth the qualification.
use super::behavior::sensing;
use super::behavior::tag::Tag;
use super::channel::membership::{self, MembershipMsg, SUBPROTOCOL_CHANNEL_MEMBERSHIP};
use super::channel::{
    AckReason, AuthGuard, AuthVerdict, ChannelConfigRegistry, ChannelHash, ChannelId, ChannelName,
    ChannelPublisher, OnFailure, PublishConfig, PublishReport, SubscriberRoster,
};
use super::compute::SUBPROTOCOL_MIGRATION;
use super::protocol::{self, EventFrame, PacketFlags, HEADER_SIZE, MAGIC, TAG_SIZE};

/// Wire overhead added to the AEAD-encrypted payload by every Net
/// packet: the 64-byte header plus the 16-byte Poly1305 tag. Credit
/// accounting charges this against the sender's `tx_credit_remaining`
/// alongside the payload so the byte window matches the bandwidth
/// the sender actually pumps onto the link. The receiver's
/// `on_bytes_consumed` adds the same overhead, keeping sender and
/// receiver in lockstep.
const PACKET_WIRE_OVERHEAD: usize = HEADER_SIZE + TAG_SIZE;

/// Drainer wake interval for the pending-stream-grants queue. The
/// receive path enqueues `(peer_node_id, stream_id) → total_consumed`
/// on every accepted packet and notifies the drainer; the drainer
/// also self-wakes on this interval as a safety net so a single
/// inbound packet whose Notify fires during a contention race still
/// gets emitted within bounded time. Grants are authoritative —
/// every emission carries the receiver's full `total_consumed` —
/// so the slight delay between enqueue and emission only affects
/// freshness, not correctness. 1 ms keeps the worst-case
/// backpressure-clearing latency well under the SDK's
/// `send_with_retry` initial 5 ms backoff. See T1.1 in
/// `PERF_AUDIT_2026_05_19_NRPC.md`.
const STREAM_GRANT_DRAIN_INTERVAL: Duration = Duration::from_millis(1);

/// Tick interval for the timeout-driven retransmit loop (STREAM_RETRANSMIT
/// D-4). Half the reliability RTO (`ReliableStream::DEFAULT_RTO`, 50 ms)
/// so a timed-out packet is resent within ~1 RTO. This backstops tail
/// loss — the last packets dropped, with no later arrival to trigger a
/// receiver NACK.
const RETRANSMIT_TICK: Duration = Duration::from_millis(25);

/// Max fixed-size control events packed into one batched control
/// packet, per message type (STREAM_ACK_BATCHING B-2/B-3):
/// `floor(MAX_PAYLOAD_SIZE / (event-frame length prefix + payload))`.
/// At 24 B payloads this is ~289 grant/NACK events per packet — far
/// below `NetHeader::MAX_EVENTS_PER_PACKET` (2027), so the payload
/// budget is the binding constraint, never the event-count cap.
///
/// Only the grant path still chunks by this fixed count (grants are
/// fixed-size and their loop carries stream ids for post-send
/// accounting); every other control frame — including the variable-
/// size `StreamAckRanges` — is packed by actual size via
/// [`pack_control_events`].
const GRANT_EVENTS_PER_PACKET: usize =
    protocol::MAX_PAYLOAD_SIZE / (EventFrame::LEN_SIZE + STREAM_WINDOW_SIZE);

/// Capability tag advertising support for positive SACK-range ACKs
/// (`StreamAckRanges`, STREAM_ACK_BATCHING R-5). Auto-merged into
/// every capability announcement (same pattern as the `nrpc:` /
/// `ai-tool:` tags) unless
/// [`MeshNodeConfig::enable_stream_ack_ranges`] is off. Emission is
/// gated on the peer advertising this tag; receiving is
/// unconditional — the capability is optimization negotiation, not
/// authority.
///
/// **The tag only reaches a peer once this node actually broadcasts a
/// capability announcement.** A node advertises when the application
/// calls [`MeshNode::announce_capabilities`], and — for a node started
/// via [`MeshNode::start_arc`] — on the reannounce loop's cadence
/// (`capability_reannounce_interval`). A node started via the bare
/// [`MeshNode::start`] that never announces will not advertise this
/// tag, so its peers keep the legacy cumulative-ACK + NACK path toward
/// it (correct, just without the SACK-range optimisation). Deployments
/// that want SACK ranges to engage promptly should call
/// `announce_capabilities` after connecting (as the e2e tests do).
pub const ACK_RANGES_CAPABILITY_TAG: &str = "net.reliable.stream_ack_ranges@1";

/// TTL for the per-peer ack-ranges capability-gate cache. Capability
/// entries change on announcement cadence (seconds to minutes); the
/// drainer asks at up to 1 kHz per session, so gate lookups read
/// through this cache instead of taking the fold lock every cycle.
const ACK_RANGES_CAP_CACHE_TTL: Duration = Duration::from_secs(5);

/// Age bound for `ack_ranges_peer_cache` entries, enforced by the
/// heartbeat loop's sweep (review P2: the cache is insert-on-lookup,
/// so without a sweep, peer churn grows it without bound). Entries
/// belonging to peers with active gapped streams are refreshed every
/// [`ACK_RANGES_CAP_CACHE_TTL`]; anything older than this belongs to
/// a departed or long-idle peer, and evicting it costs that peer at
/// most one extra fold lookup on its next gate check.
const ACK_RANGES_CAP_CACHE_MAX_AGE: Duration = Duration::from_secs(40);

/// Control-plane emission counters (STREAM_ACK_BATCHING B-4).
///
/// The packets/events split makes the batching ratio observable:
/// `*_events_sent / *_packets_sent` is the achieved coalescing
/// factor (1.0 = no coalescing, pre-batching behavior). Relaxed
/// ordering everywhere — these are monotonic telemetry counters
/// with no cross-thread ordering contract.
#[derive(Debug, Default)]
pub struct ControlPlaneStats {
    /// `StreamWindow` control packets emitted (one per session per
    /// drain cycle post-batching, plus payload-budget spill).
    pub grant_packets_sent: AtomicU64,
    /// Individual `StreamWindow` grant events emitted.
    pub grant_events_sent: AtomicU64,
    /// `StreamNack` control packets emitted (drainer piggyback +
    /// the 25 ms proactive gap tick).
    pub nack_packets_sent: AtomicU64,
    /// Individual `StreamNack` events emitted.
    pub nack_events_sent: AtomicU64,
    /// `StreamReset` control packets emitted (H-3 give-up signal).
    pub reset_packets_sent: AtomicU64,
    /// Individual `StreamReset` events emitted.
    pub reset_events_sent: AtomicU64,
    /// Data packets re-sent by the reliability layer: NACK-driven
    /// fast retransmits + RTO-driven timeout retransmits.
    pub retransmit_packets_sent: AtomicU64,
    /// `StreamAckRanges` control packets emitted (R-4; capability-
    /// gated per peer).
    pub ack_range_packets_sent: AtomicU64,
    /// Individual `StreamAckRanges` events emitted.
    pub ack_range_events_sent: AtomicU64,
}

impl ControlPlaneStats {
    /// Count one emitted control packet carrying `events` events.
    #[inline]
    fn record_packet(packets: &AtomicU64, events_ctr: &AtomicU64, events: usize) {
        packets.fetch_add(1, Ordering::Relaxed);
        events_ctr.fetch_add(events as u64, Ordering::Relaxed);
    }
}

/// Upper bound on how long [`MeshNode::flush_stream_batch`] retries a
/// committed-prefix flush against a receiver that grants no credit.
/// After ANY packet of a multi-batch send is committed we can't surface
/// `Backpressure` (the caller would replay the whole slice → duplicates,
/// see #19), so we wait for a `StreamWindow` grant — but a receiver that
/// grants zero credit for longer than the session-dead horizon
/// (`NetConfig::DEFAULT_SESSION_TIMEOUT`, 30 s) is effectively gone.
/// Past this budget we surface a terminal `Transport` error (which the
/// caller does NOT replay) rather than spin forever (#4 follow-up).
const COMMITTED_FLUSH_STALL_BUDGET: Duration = Duration::from_secs(30);

/// Back off, then report whether the committed-prefix flush retry may
/// continue. Returns `Err(StreamError::Transport)` once `deadline` has
/// passed — a receiver that has granted no credit by then is treated as
/// dead, and a terminal (non-replayable) error is preferable to an
/// unbounded spin. Otherwise sleeps the current backoff, doubles it
/// (capped at `cap`), and returns `Ok`. Factored out of
/// `flush_stream_batch` so the bound is unit-testable under paused time.
async fn await_credit_or_stall(
    delay: &mut Duration,
    cap: Duration,
    deadline: tokio::time::Instant,
) -> Result<(), StreamError> {
    if tokio::time::Instant::now() >= deadline {
        return Err(StreamError::Transport(
            "stream credit stalled: receiver granted no credit within the send budget".to_string(),
        ));
    }
    tokio::time::sleep(*delay).await;
    *delay = (*delay * 2).min(cap);
    Ok(())
}

/// One entry in the per-mesh pending-grant queue. Captures the
/// AEAD session (for cipher + packet pool + next_control_tx_seq)
/// and the peer's wire address. The receive path already has both
/// resolved, so the drainer doesn't need to redo the peer lookup.
#[derive(Clone)]
struct PendingStreamGrant {
    session: Arc<NetSession>,
    peer_addr: SocketAddr,
    total_consumed: u64,
}

/// Group drained pending grants by session (STREAM_ACK_BATCHING B-1).
///
/// The session — not the peer address — owns the outbound AEAD
/// cipher, packet pool, and control-seq counter, so it is the unit a
/// batched control packet can be built against. Two sessions behind
/// one address (e.g. a rotation mid-drain) must NOT share a packet;
/// keying on the map key's `session_id` guarantees that. Pure so the
/// grouping-key contract is unit-testable.
#[allow(clippy::type_complexity)]
fn group_grants_by_session(
    drained: HashMap<(u64, u64), PendingStreamGrant>,
) -> HashMap<u64, (Arc<NetSession>, SocketAddr, Vec<(u64, u64)>)> {
    let mut by_session: HashMap<u64, (Arc<NetSession>, SocketAddr, Vec<(u64, u64)>)> =
        HashMap::new();
    for ((session_id, stream_id), grant) in drained {
        let PendingStreamGrant {
            session,
            peer_addr,
            total_consumed,
        } = grant;
        by_session
            .entry(session_id)
            .or_insert_with(|| (session.clone(), peer_addr, Vec::new()))
            .2
            .push((stream_id, total_consumed));
    }
    by_session
}

/// Capability gate for `StreamAckRanges` emission (STREAM_ACK_BATCHING
/// R-5): does the peer behind `session_id` advertise
/// [`ACK_RANGES_CAPABILITY_TAG`]? Resolution is session → node via
/// `session_id_to_node`, then a per-node tag lookup in the capability
/// fold, read through a [`ACK_RANGES_CAP_CACHE_TTL`] cache (the
/// drainer asks at up to 1 kHz per session; the fold lookup takes the
/// fold's read lock). Unknown node or no tag ⇒ `false` — the legacy
/// cumulative-ACK + NACK path is always safe.
fn peer_supports_ack_ranges(
    cache: &DashMap<u64, (bool, Instant)>,
    session_id_to_node: &DashMap<u64, u64>,
    capability_fold: &super::behavior::fold::Fold<super::behavior::fold::CapabilityFold>,
    session_id: u64,
) -> bool {
    let Some(node_id) = session_id_to_node.get(&session_id).map(|e| *e.value()) else {
        return false;
    };
    if let Some(hit) = cache.get(&node_id) {
        if hit.value().1.elapsed() < ACK_RANGES_CAP_CACHE_TTL {
            return hit.value().0;
        }
    }
    let supports = super::behavior::fold::capability::capability_tags_for(capability_fold, node_id)
        .iter()
        .any(|t| t == ACK_RANGES_CAPABILITY_TAG);
    cache.insert(node_id, (supports, Instant::now()));
    supports
}

/// Drop `ack_ranges_peer_cache` entries not refreshed within
/// `max_age` — the heartbeat-tick backstop that keeps the
/// insert-on-lookup cache bounded under peer churn (targeted removal
/// at dead-peer eviction handles the common case; this catches peers
/// that never reach eviction, e.g. a session that was replaced by a
/// re-handshake). O(cache) per tick; cache size ≤ peers seen within
/// the age window.
fn sweep_ack_ranges_cache(cache: &DashMap<u64, (bool, Instant)>, max_age: Duration) {
    cache.retain(|_, (_, cached_at)| cached_at.elapsed() < max_age);
}

/// Build the control events for one drained session batch
/// (B-2/B-3/R-4): the grant events paired with their stream id (the
/// id rides along so the drainer can find each stream again for the
/// post-send accounting), the piggybacked NACK events for gapped
/// streams, and — when the peer advertises support — the SACK-range
/// events.
///
/// Pure build step: it does NOT bump `credit_grants_sent`. That
/// counter means "grant datagram sent"; the drainer bumps it per
/// covered stream only after the chunk carrying that stream's grant
/// clears `send_to`. Pre-fix the bump ran here at build time and
/// overcounted whenever the send failed.
#[allow(clippy::type_complexity)]
fn build_session_control_events(
    session: &Arc<NetSession>,
    grants: &[(u64, u64)],
    emit_ack_ranges: bool,
) -> (Vec<(u64, Bytes)>, Vec<Bytes>, Vec<Bytes>) {
    let mut grant_entries: Vec<(u64, Bytes)> = Vec::with_capacity(grants.len());
    let mut nack_events: Vec<Bytes> = Vec::new();
    let mut ack_events: Vec<Bytes> = Vec::new();
    for &(stream_id, total_consumed) in grants {
        // One `try_stream` + ONE reliability lock per stream: read the
        // cumulative ack, the piggyback NACK, and (when the peer
        // advertises support) the SACK ranges from a SINGLE consistent
        // snapshot. The three control frames a cycle emits for this
        // stream therefore always agree — pre-fix each was read under
        // its own lock, so a head-fill landing mid-build could pair a
        // stale grant/NACK with a fresher SACK (or a NACK for a gap
        // that had already healed). The codec invariant "every range
        // strictly above `ack_seq`" holds because both come from this
        // one snapshot. A missing / non-reliable stream contributes a
        // zero cumulative ack (H-9) and no gap frames.
        let (ack_seq, nack, ranges) = session
            .try_stream(stream_id)
            .map(|s| {
                s.with_reliability(|r| {
                    let ranges = if emit_ack_ranges {
                        r.build_ack_ranges(MAX_ACK_RANGES)
                    } else {
                        Vec::new()
                    };
                    (r.rx_ack_seq(), r.build_nack(), ranges)
                })
            })
            .unwrap_or((0, None, Vec::new()));
        let payload = StreamWindow {
            stream_id,
            total_consumed,
            ack_seq,
        }
        .encode();
        grant_entries.push((stream_id, Bytes::copy_from_slice(&payload)));
        // Piggyback a retransmit NACK (STREAM_RETRANSMIT D-2): a
        // grant is enqueued on every accepted packet, so an
        // out-of-order arrival (which creates the gap) reliably
        // triggers a NACK here; tail loss (no later arrival) is
        // covered by the timeout retransmit loop.
        if let Some(nack) = nack {
            let payload = StreamNack {
                stream_id,
                next_expected: nack.next_expected,
                missing_bitmap: nack.missing_bitmap,
            }
            .encode();
            nack_events.push(Bytes::copy_from_slice(&payload));
        }
        // R-4: positive SACK ranges for a gapped stream, to peers that
        // advertise support. A gapless stream returns no ranges and
        // costs nothing here.
        if !ranges.is_empty() {
            let msg = StreamAckRanges {
                stream_id,
                ack_seq,
                ranges,
            };
            ack_events.push(Bytes::from(msg.encode()));
        }
    }
    (grant_entries, nack_events, ack_events)
}

/// Greedily split `events` into consecutive chunks (as index ranges)
/// that each fit `MAX_PAYLOAD_SIZE` once framed (STREAM_ACK_BATCHING
/// B-2/B-3/R-4). Framed size is exactly [`EventFrame::calculate_size`]
/// (`sum(LEN_SIZE + len)`), computed incrementally here.
///
/// Unlike a fixed `chunks(N)` split sized for the *worst-case* event,
/// this fills each datagram by actual event size — so variable-size
/// `StreamAckRanges` events (1..=`MAX_ACK_RANGES` ranges, 32..=272 B)
/// no longer ride a packet budgeted at the 272 B worst case and ship
/// ~85% empty (review ACKCHUNK/H5). Fixed-size grant/NACK/reset events
/// pack identically to the old `chunks(N)`. An event that alone
/// exceeds the budget still gets its own chunk — `build_subprotocol`
/// enforces the hard cap — but the fixed-schema control frames here
/// are all far below it.
fn pack_control_events(events: &[Bytes]) -> Vec<std::ops::Range<usize>> {
    let mut chunks: Vec<std::ops::Range<usize>> = Vec::new();
    let mut start = 0usize;
    let mut acc = 0usize;
    for (i, e) in events.iter().enumerate() {
        let framed = EventFrame::LEN_SIZE + e.len();
        // Close the current chunk before `i` if adding this event
        // would overflow — but only when the chunk already holds at
        // least one event (`i > start`), so an oversized lone event
        // still ships alone rather than producing an empty chunk.
        if i > start && acc + framed > protocol::MAX_PAYLOAD_SIZE {
            chunks.push(start..i);
            start = i;
            acc = 0;
        }
        acc += framed;
    }
    if start < events.len() {
        chunks.push(start..events.len());
    }
    chunks
}

/// Emit `events` as one or more batched control packets on `session`
/// to `addr`, size-packed by [`pack_control_events`], bumping
/// `(packets_ctr, events_ctr)` once per datagram that clears the
/// socket (STREAM_ACK_BATCHING B-2/B-3/R-4).
///
/// One shared emit path for the drainer's piggyback NACK/SACK packets
/// and the retransmit tick's reset/NACK/SACK packets — previously six
/// near-identical copies of the
/// chunk→`next_control_tx_seq`→`build_subprotocol`→`send_to`→count
/// sequence that had already drifted in their send-failure handling
/// (review EMITLOOP/G1). A failed `send_to` is logged and that
/// datagram skipped; the peer re-requests on its next tick and the
/// RTO backstops. The grant path stays bespoke — it also runs
/// per-stream `note_grant_sent` accounting keyed on the covered ids.
#[allow(clippy::too_many_arguments)]
async fn emit_control_chunks(
    socket: &NetSocket,
    builder: &mut super::pool::ThreadLocalPooledBuilder<'_>,
    session: &NetSession,
    addr: SocketAddr,
    events: &[Bytes],
    subprotocol_id: u16,
    packets_ctr: &AtomicU64,
    events_ctr: &AtomicU64,
) {
    for range in pack_control_events(events) {
        let chunk = &events[range];
        let seq = session.next_control_tx_seq();
        let packet = builder.build_subprotocol(
            CONTROL_STREAM_ID,
            seq,
            chunk,
            PacketFlags::NONE,
            subprotocol_id,
        );
        if socket.send_to(&packet, addr).await.is_ok() {
            ControlPlaneStats::record_packet(packets_ctr, events_ctr, chunk.len());
        }
    }
}

/// Total wire bytes for a single Net packet carrying `payload_bytes`
/// of AEAD-encrypted content. Saturating at `u32::MAX` so a
/// pathological `payload_bytes` can't silently wrap the credit math.
#[inline]
fn wire_bytes_for_payload(payload_bytes: usize) -> u32 {
    payload_bytes
        .saturating_add(PACKET_WIRE_OVERHEAD)
        .min(u32::MAX as usize) as u32
}
use super::reroute::ReroutePolicy;
use super::route::{RoutingHeader, ROUTING_HEADER_SIZE, ROUTING_MAGIC};
use super::router::{NetRouter, RouterConfig};
use super::session::{NetSession, TxAdmit, CONTROL_STREAM_ID};
use super::stream::{Stream, StreamConfig, StreamError, StreamStats};
use super::subnet::{DropReason, SubnetGateway, SubnetId, SubnetPolicy};
use super::subprotocol::stream_window::{
    StreamAckRanges, StreamNack, StreamReset, StreamWindow, MAX_ACK_RANGES, STREAM_WINDOW_SIZE,
    SUBPROTOCOL_STREAM_ACK, SUBPROTOCOL_STREAM_NACK, SUBPROTOCOL_STREAM_RESET,
    SUBPROTOCOL_STREAM_WINDOW,
};
use super::subprotocol::MigrationSubprotocolHandler;
use super::transport::{NetSocket, PacketReceiver, ParsedPacket, SocketBufferConfig};
use super::Visibility;
use tokio::sync::oneshot;

use crate::adapter::{Adapter, ShardPollResult};
use crate::error::AdapterError;
use crate::event::{Batch, StoredEvent};

/// Inbound event queues (same type as NetAdapter uses).
type InboundQueues = Arc<DashMap<u16, SegQueue<StoredEvent>>>;

/// One slot in [`MeshNode::fold_generations`]: a monotonic
/// counter plus the wall-clock micros at which it was last
/// bumped. The background GC loop evicts slots whose
/// `last_touched_us` is more than [`FOLD_GENERATION_GC_MAX_AGE`]
/// behind `now`.
struct FoldGenerationEntry {
    counter: AtomicU64,
    last_touched_us: AtomicU64,
}

impl FoldGenerationEntry {
    fn new() -> Self {
        Self {
            counter: AtomicU64::new(0),
            last_touched_us: AtomicU64::new(super::current_timestamp_micros()),
        }
    }
}

/// Cadence at which the fold-generation GC sweep runs.
const FOLD_GENERATION_GC_INTERVAL: Duration = Duration::from_secs(300);

/// Maximum age of a `fold_generations` entry before the sweep
/// evicts it. 1 hour is generous enough that a publisher that
/// re-publishes against the same `(kind, class)` slot once per
/// `DEFAULT_TTL` (30 s for reservations, 60 s for capability,
/// 300 s for routing) never loses its counter; tight enough that
/// a publisher that abandons a `class` (e.g. a one-shot
/// `ResourceId`) reclaims its slot within a bounded window.
const FOLD_GENERATION_GC_MAX_AGE: Duration = Duration::from_secs(3600);

/// Convert a u64 node_id to a 32-byte graph NodeId.
///
/// The proximity graph uses 32-byte ed25519 public keys as NodeId.
/// For nodes where we only have the derived u64 node_id, we zero-pad
/// it to 32 bytes. This preserves uniqueness for topology tracking
/// without requiring the full public key exchange.
fn node_id_to_graph_id(node_id: u64) -> [u8; 32] {
    let mut id = [0u8; 32];
    id[0..8].copy_from_slice(&node_id.to_le_bytes());
    id
}

/// Inverse of `node_id_to_graph_id`: read the u64 back from the first 8
/// bytes of a 32-byte proximity `NodeId`. Assumes the id was produced by
/// `node_id_to_graph_id` (which is how every peer in this codebase is
/// seeded into the graph).
#[expect(
    clippy::unwrap_used,
    reason = "input is &[u8; 32]; slicing [0..8] then .try_into::<[u8; 8]>() is statically infallible"
)]
fn graph_id_to_node_id(graph_id: &[u8; 32]) -> u64 {
    u64::from_le_bytes(graph_id[0..8].try_into().unwrap())
}

/// Set of peer addresses whose packets should be silently dropped.
///
/// Used by test harnesses to simulate network partitions. When a peer's
/// address is in this set, both inbound and outbound packets are dropped
/// as if the network link is severed.
pub type PartitionFilter = Arc<dashmap::DashSet<SocketAddr>>;

/// Waiter map for incoming `PunchIntroduce` messages keyed by the
/// counterpart endpoint's `node_id`. Value is `(generation,
/// expected coordinator node id, punch_id, oneshot sender)`. Used
/// by the rendezvous-coordinated punch flow to bind introduce
/// delivery to the relay the local node sent `PunchRequest` to.
/// `punch_id` is the wire correlation token the request carried —
/// a `PunchReject` resolves the waiter only when it echoes the
/// same id (cubic P2: `target` alone conflates concurrent
/// requests; a delayed reject for a superseded request must not
/// fail its replacement). Waiters installed without a request
/// (`await_punch_introduce`) hold the never-minted sentinel `0`.
#[cfg(feature = "nat-traversal")]
type PendingPunchIntroduces =
    Arc<DashMap<u64, (u64, u64, u32, oneshot::Sender<PunchIntroduceOutcome>)>>;

/// Waiter map for incoming `PunchAck` messages keyed by the sender
/// endpoint's `node_id`. Value is `(generation, expected coordinator
/// node id, oneshot sender)`. Used by `connect_direct`'s
/// `SinglePunch` path to confirm the counterpart's side of the punch.
#[cfg(feature = "nat-traversal")]
type PendingPunchAcks = Arc<
    DashMap<
        u64,
        (
            u64,
            u64,
            oneshot::Sender<super::traversal::rendezvous::PunchAck>,
        ),
    >,
>;

/// Outcome delivered to a `request_punch` waiter. The rendezvous
/// coordinator either mediates (an introduce arrives) or refuses (a
/// reject arrives). Both resolve the same pending-introduce waiter so
/// the requester unblocks in one place; a timeout is still the third
/// outcome, handled by `request_punch` itself.
#[cfg(feature = "nat-traversal")]
#[derive(Debug, Clone, Copy)]
enum PunchIntroduceOutcome {
    /// The coordinator mediated: here's the counterpart's reflex.
    Introduce(super::traversal::rendezvous::PunchIntroduce),
    /// The coordinator refused with a typed reason.
    Rejected(super::traversal::rendezvous::RejectReason),
}

/// Rendezvous abuse budgets (`NAT_TRAVERSAL_V2_PLAN.md` Stage 2,
/// closing review Finding 5). Three independent limiters:
///
/// - `requests` — coordinator per-requester fixed-window budget on
///   `PunchRequest`, keyed by the requester's `node_id`.
/// - `trains` — responder per-source fixed-window budget on
///   keep-alive trains scheduled from *unsolicited* introduces, keyed
///   by the introducing peer's `node_id`. (Replaces Stage 1's
///   temporary `unsolicited_introduce_rate` cap.)
/// - `concurrent_trains` — global count of outstanding unsolicited
///   trains, capped so a Sybil set of sources each under its per-source
///   budget can't multiply the aggregate.
///
/// Both windowed maps use the same lazy fixed-window scheme as the
/// subscribe-auth throttle: a `(count, window_start)` pair per key,
/// reset on the first charge past the window end.
#[cfg(feature = "nat-traversal")]
#[derive(Debug, Default)]
struct RendezvousBudgets {
    requests: DashMap<u64, (u32, Instant)>,
    trains: DashMap<u64, (u32, Instant)>,
    concurrent_trains: std::sync::atomic::AtomicUsize,
}

#[cfg(feature = "nat-traversal")]
impl RendezvousBudgets {
    /// Charge one unit against a fixed-window map. Returns `true` (and
    /// records the charge) when `key` is under `max` for the current
    /// window; `false` when exhausted. `max == 0` disables the limit.
    fn charge(map: &DashMap<u64, (u32, Instant)>, key: u64, window: Duration, max: u32) -> bool {
        if max == 0 {
            return true;
        }
        let now = Instant::now();
        let mut entry = map.entry(key).or_insert((0, now));
        let (count, window_start) = entry.value_mut();
        if now.duration_since(*window_start) >= window {
            *count = 0;
            *window_start = now;
        }
        if *count >= max {
            return false;
        }
        *count += 1;
        true
    }

    /// Coordinator side: charge a `PunchRequest` from `requester`.
    fn charge_request(&self, requester: u64, window: Duration, max: u32) -> bool {
        Self::charge(&self.requests, requester, window, max)
    }

    /// Responder side: charge an unsolicited keep-alive train from
    /// `source`.
    fn charge_train(&self, source: u64, window: Duration, max: u32) -> bool {
        Self::charge(&self.trains, source, window, max)
    }

    /// Try to reserve one of the `max` global concurrent-train slots.
    /// Returns an RAII [`TrainSlot`] that releases the slot on drop, or
    /// `None` when the ceiling is reached. `max == 0` disables the
    /// ceiling (always grants an untracked slot).
    fn try_train_slot(self: &Arc<Self>, max: usize) -> Option<TrainSlot> {
        use std::sync::atomic::Ordering;
        if max == 0 {
            return Some(TrainSlot { budgets: None });
        }
        // Compare-and-swap loop: only claim a slot if we stay ≤ max.
        let mut cur = self.concurrent_trains.load(Ordering::Relaxed);
        loop {
            if cur >= max {
                return None;
            }
            match self.concurrent_trains.compare_exchange_weak(
                cur,
                cur + 1,
                Ordering::AcqRel,
                Ordering::Relaxed,
            ) {
                Ok(_) => {
                    return Some(TrainSlot {
                        budgets: Some(self.clone()),
                    })
                }
                Err(observed) => cur = observed,
            }
        }
    }
}

/// Per-peer throttle for the background direct-path upgrade
/// (`NAT_TRAVERSAL_V2_PLAN.md` Stage 3). Prevents a pathological pair
/// from re-punching on every scan: a failure backs off exponentially, a
/// success stops further attempts (the session is now direct), and a
/// busy-defer retries after a short delay.
#[cfg(feature = "nat-traversal")]
#[derive(Debug, Clone, Copy)]
struct UpgradeCacheEntry {
    /// Earliest instant a fresh attempt is allowed.
    next_eligible: Instant,
    /// Consecutive failures — drives the exponential backoff.
    failures: u32,
    /// Once a direct session is established there is nothing left to
    /// upgrade; stop attempting.
    done: bool,
}

/// RAII reservation for one global unsolicited-train slot. Holding it
/// keeps the slot counted; dropping it (when the punch scheduler's
/// observer task ends) releases the slot. `budgets == None` is the
/// disabled-ceiling case — nothing to release.
#[cfg(feature = "nat-traversal")]
struct TrainSlot {
    budgets: Option<Arc<RendezvousBudgets>>,
}

#[cfg(feature = "nat-traversal")]
impl Drop for TrainSlot {
    fn drop(&mut self) {
        if let Some(b) = &self.budgets {
            b.concurrent_trains
                .fetch_sub(1, std::sync::atomic::Ordering::AcqRel);
        }
    }
}

/// Cancellation-safe rollback for a freshly registered peer
/// session + addr map + routing entry.
///
/// `handle_routed_handshake` schedules its msg2 send on a
/// background task, so the rollback path must survive task drop.
/// A fire-and-forget `tokio::spawn` whose only rollback was inside
/// the spawned future's error arm would skip the rollback if that
/// future was cancelled (runtime shutdown, parent task abort)
/// before the send completed — the responder would keep session
/// keys the initiator never received the matching msg2 for,
/// wedged forever with no idle sweeper to reap it.
///
/// This guard moves the rollback into `Drop`, which runs
/// synchronously whenever the spawned future is dropped. The
/// successful-send arm calls `commit()` to consume the guard
/// without invoking `Drop` (`std::mem::forget`); cancellation,
/// panic, or any non-success path lets the guard drop naturally,
/// and `Drop` reverts all three registrations.
struct PeerRegistrationGuard {
    peer_node_id: u64,
    /// Session-id of the registered peer; the rollback uses this to
    /// drop the `session_id_to_node` reverse-index entry alongside
    /// the other peer-keyed maps (PERF_AUDIT §2.4).
    registered_session_id: u64,
    registered_next_hop: SocketAddr,
    peers: Arc<DashMap<u64, PeerInfo>>,
    peer_addrs: Arc<DashMap<u64, SocketAddr>>,
    session_id_to_node: Arc<DashMap<u64, u64>>,
    router: Arc<NetRouter>,
}

impl PeerRegistrationGuard {
    /// Mark the registration as durable. Drops `self` *without*
    /// running the rollback — the post-handshake send completed
    /// successfully, so the registrations should stay in place.
    fn commit(self) {
        // `mem::forget` skips `Drop`. The Arc fields would
        // normally decrement on drop, but since we want them
        // alive (they're shared with the rest of the bus), we
        // need to drop them manually before forgetting the
        // wrapper. SAFETY: reading the Arc fields out of the
        // struct via `ptr::read` and forgetting the rest is the
        // standard cancel-Drop pattern.
        let me = std::mem::ManuallyDrop::new(self);
        #[expect(
            clippy::multiple_unsafe_ops_per_block,
            reason = "three ptr::read calls form a single semantic op (consume ManuallyDrop fields together so they drop normally)"
        )]
        // SAFETY: `me` is `ManuallyDrop`, so its fields won't be
        // dropped automatically. We read them out and let them
        // drop normally, which decrements the Arc strong counts
        // — exactly what would happen on a non-guarded path.
        unsafe {
            let _peers = std::ptr::read(&me.peers);
            let _peer_addrs = std::ptr::read(&me.peer_addrs);
            let _session_id_to_node = std::ptr::read(&me.session_id_to_node);
            let _router = std::ptr::read(&me.router);
        }
    }
}

impl Drop for PeerRegistrationGuard {
    fn drop(&mut self) {
        // Match the original inline rollback's semantics: only
        // remove entries whose addr / next-hop still equals the
        // value we wrote. A concurrent retry for the same peer
        // may have already replaced them with a fresh, valid
        // registration — we must not overwrite that.
        self.peers.remove_if(&self.peer_node_id, |_, pi| {
            pi.addr == self.registered_next_hop
        });
        self.peer_addrs.remove_if(&self.peer_node_id, |_, addr| {
            *addr == self.registered_next_hop
        });
        // PERF_AUDIT §2.4: drop the reverse-index entry only when
        // it still points at our registered node_id. A concurrent
        // retry that installed a fresh session under the same
        // peer_node_id would have replaced it; we must not undo
        // that successful registration.
        self.session_id_to_node
            .remove_if(&self.registered_session_id, |_, n| *n == self.peer_node_id);
        self.router
            .routing_table()
            .remove_route_if_next_hop_is(self.peer_node_id, self.registered_next_hop);
    }
}

/// Outcome of the routed-handshake key-rotation gate.
///
/// The gate runs inside `peers.entry(peer_node_id)`'s write guard so
/// the decision and the subsequent insert are atomic; see
/// `MeshNode::handle_routed_handshake` for the call site.
#[derive(Debug, PartialEq, Eq)]
enum RoutedRotationOutcome {
    /// A live session for the same `peer_node_id` is already
    /// established with the SAME `remote_static_pub` — drop the
    /// inbound msg1 as a replay. NKpsk0's responder uses a fresh
    /// ephemeral on each reply, so without this guard a captured
    /// msg1 replayed by a passive attacker would derive new session
    /// keys and silently swap them in, breaking AEAD verification
    /// on the legitimate peer's subsequent packets.
    DropReplay,
    /// A live session for the same `peer_node_id` exists with a
    /// DIFFERENT `remote_static_pub`. Refuse the rotation: the
    /// existing session is still within `session_timeout`. Pre-fix
    /// this branch unconditionally overwrote the live session,
    /// opening a trivial DoS — anyone holding the PSK and any valid
    /// Noise static could swap session keys for any peer that ever
    /// handshook on a routed path. A legitimate peer rotating its
    /// static must wait for its existing session to time out before
    /// the new keys are accepted.
    RefuseFresh,
    /// A same-static re-handshake arrived (would normally rotate),
    /// but the existing session is **live and busy** — it has open
    /// application streams or unacked in-flight reliable data. Swapping
    /// now would drop that in-flight state with no retransmit on the
    /// new session (`NAT_TRAVERSAL_V2_PLAN.md` C3, responder half).
    /// Refuse like `RefuseFresh` (drop msg1); the initiator's upgrade
    /// fails cleanly and retries, and the relay-routed session stays
    /// intact. Bounded: once the session goes quiescent — or idle past
    /// `session_timeout`, so a genuinely dead path recovering after a
    /// NAT rebind isn't blocked — a later re-handshake rotates.
    DeferBusy,
    /// No conflict (or the existing session has timed out). The
    /// caller should construct a fresh session and insert it under
    /// the same entry guard.
    AcceptRotation,
}

/// Decide whether an inbound routed handshake is allowed to install
/// new session keys for `peer_node_id`.
///
/// `new_ephemeral` is the initiator's ephemeral public key from msg1
/// (first 32 bytes of the NKpsk0 wire payload, in the clear). When the
/// existing session was built from msg1 with the SAME ephemeral the
/// inbound msg1 is bit-for-bit a replay — a fresh responder ephemeral
/// otherwise derives a NEW key pair every time, silently swapping
/// session keys out from under the legitimate initiator. When the
/// static matches but the ephemeral differs the same peer is
/// legitimately re-initiating (fresh msg1 with a new ephemeral, which
/// only the holder of the static + PSK can produce); accept the
/// rotation.
fn routed_rotation_outcome(
    existing: &PeerInfo,
    new_static: &[u8; 32],
    new_ephemeral: &[u8; 32],
    session_timeout: Duration,
) -> RoutedRotationOutcome {
    if existing.remote_static_pub == *new_static {
        // Same peer (by static). Distinguish exact-replay msg1
        // from legitimate re-handshake using the initiator's
        // ephemeral.
        if existing.last_initiator_ephemeral.as_ref() == Some(new_ephemeral) {
            return RoutedRotationOutcome::DropReplay;
        }
        // Legitimate re-handshake. Normally rotates — but if the
        // existing session is live (not idle past `session_timeout`)
        // and busy (open streams or unacked in-flight data), defer:
        // swapping now would drop that in-flight state (C3). Keying
        // liveness on `is_timed_out` bounds the deferral to
        // `session_timeout` — a genuinely dead path (e.g. the peer's
        // NAT rebound) stops delivering inbound, times out, and the
        // next re-handshake rotates, so recovery is never blocked
        // for longer than a fresh-static rotation would be.
        let live = !existing.session.is_timed_out(session_timeout);
        let busy = existing.session.has_open_streams() || existing.session.has_unacked();
        if live && busy {
            return RoutedRotationOutcome::DeferBusy;
        }
        return RoutedRotationOutcome::AcceptRotation;
    }
    if existing.session.is_timed_out(session_timeout) {
        RoutedRotationOutcome::AcceptRotation
    } else {
        RoutedRotationOutcome::RefuseFresh
    }
}

/// A subscribe token chain retained after it cleared the root-anchored
/// gate, plus a one-shot flag recording whether its (immutable) link
/// signatures have already been ed25519-verified.
///
/// The publish fan-out re-checks every admitted subscriber's chain on
/// every packet. Once the signatures verify the first time, subsequent
/// re-checks take `verify_authorizes_presigned`, which skips the
/// ed25519 work (a signature on an immutable token can't change) but
/// still re-evaluates time bounds, revocation floors, root anchoring,
/// and scope — all of which *can* change between publishes. So a
/// high-fanout, deep-delegation channel stops paying N × up-to-8
/// signature verifies per packet without weakening any live policy
/// check.
struct RetainedChain {
    chain: TokenChain,
    signatures_verified: AtomicBool,
}

impl RetainedChain {
    fn new(chain: TokenChain) -> Self {
        Self {
            chain,
            signatures_verified: AtomicBool::new(false),
        }
    }
}

/// Shared context for the packet dispatch loop.
///
/// `Clone`: every field is an `Arc` handle or a small config copy,
/// so a clone is ~a round of refcount bumps. The SI-6.1 trailing-
/// edge reconciliation task captures a clone — a boundary sleeper
/// outlives the dispatch call that scheduled it, so it cannot
/// borrow.
#[derive(Clone)]
struct DispatchCtx {
    local_node_id: u64,
    peers: Arc<DashMap<u64, PeerInfo>>,
    addr_to_node: Arc<DashMap<SocketAddr, u64>>,
    /// Node-id → addr map shared with the reroute policy. Must be kept in
    /// sync with `peers` on every registration so the reroute policy can
    /// resolve failed peers.
    peer_addrs: Arc<DashMap<u64, SocketAddr>>,
    router: Arc<NetRouter>,
    failure_detector: Arc<FailureDetector>,
    inbound: InboundQueues,
    /// Per-channel-hash dispatch hook for nRPC. See the matching
    /// field on `MeshNode`. Gated on `cortex` because the nRPC
    /// dispatcher type lives there and the `--features net`-only
    /// build doesn't compile the cortex layer.
    #[cfg(feature = "cortex")]
    // Keyed by the wire `u16` hash that rides on
    // `NetHeader::channel_hash` — that's what the inbound dispatch
    // path has cheaply available at packet decode time. Each
    // bucket stores a list of `(canonical ChannelHash, dispatcher)`
    // entries so wire-bucket collisions don't cross dispatch lines;
    // the canonical `u32` hash is what each dispatcher is keyed on.
    // The `Vec` cost is paid only once per wire-bucket hit, and at
    // typical sizing there is exactly one entry per bucket.
    rpc_inbound_dispatchers: Arc<
        DashMap<
            u16,
            Vec<(
                ChannelHash,
                crate::adapter::net::cortex::RpcInboundDispatcher,
            )>,
        >,
    >,
    num_shards: u16,
    /// Optional subprotocol handler for migration messages.
    ///
    /// `ArcSwapOption` so [`Self::set_migration_handler`] can install
    /// at runtime via `&self` — the SDK's `DaemonRuntime::start`
    /// hands in a handler after the mesh has been constructed but
    /// before user migration traffic lands, which is otherwise
    /// awkward because a started `Mesh` is shared by `Arc`.
    migration_handler: Arc<ArcSwapOption<MigrationSubprotocolHandler>>,
    /// Optional replication inbound router. See the matching
    /// field doc on `MeshNode`.
    #[cfg(feature = "redex")]
    replication_inbound_router:
        Arc<parking_lot::RwLock<Option<Arc<dyn super::redex::ReplicationInboundRouter>>>>,
    /// Optional MeshDB inbound router. See the matching field doc
    /// on `MeshNode`. Same `parking_lot::RwLock<Option<Arc<dyn ...>>>`
    /// shape as the replication router; the hot path takes a
    /// single read lock per `SUBPROTOCOL_MESHDB` packet.
    #[cfg(feature = "meshdb")]
    meshdb_inbound_router:
        Arc<parking_lot::RwLock<Option<Arc<dyn super::behavior::meshdb::MeshDbInboundRouter>>>>,
    /// Optional fold-framework channel router. See the matching
    /// field doc on `MeshNode`. One read lock per
    /// `SUBPROTOCOL_FOLD` packet on the inbound path; absent
    /// router means fold packets are dropped silently (mirrors
    /// the meshdb router's behaviour).
    fold_router:
        Arc<parking_lot::RwLock<Option<Arc<dyn super::behavior::fold::FoldChannelRouter>>>>,
    /// Optional greedy-LRU observer. See the matching field doc on
    /// `MeshNode`. The hot path takes a single read lock on every
    /// standard-event packet; uncontended reads under
    /// `parking_lot::RwLock` are single-digit-nanoseconds.
    #[cfg(feature = "dataforts")]
    greedy_observer: Arc<parking_lot::RwLock<Option<Arc<dyn super::dataforts::GreedyObserver>>>>,
    /// Optional blob-transfer engine (FairScheduler transport). The
    /// `SUBPROTOCOL_BLOB_TRANSFER` control branch and the
    /// `is_transfer_stream_id` data divert consult it. `None` until a
    /// node calls `serve_blob_transfer`.
    #[cfg(feature = "dataforts")]
    blob_transfer_engine:
        Arc<parking_lot::RwLock<Option<Arc<super::dataforts::blob::transfer::BlobTransferEngine>>>>,
    /// In-flight initiator handshakes; dispatch completes them when a
    /// matching routed msg2 arrives.
    pending_handshakes: Arc<DashMap<u64, PendingHandshake>>,
    /// In-flight DIRECT initiator handshakes, keyed by the peer's
    /// socket address. The initiator registers a oneshot here
    /// BEFORE sending msg1; the dispatch loop's direct-handshake
    /// branch looks up the source, forwards the parsed payload
    /// bytes through the oneshot, and removes the entry.
    ///
    /// Polling `socket_arc.recv_from` directly from
    /// `try_handshake_initiator` would race the dispatch receive
    /// loop spawned by `start()` — tokio dispatches each datagram
    /// to exactly one waiter, so the handshake response could be
    /// swallowed by either side. If no entry matches the source
    /// (e.g., the
    /// responder side or pre-start invocations), the dispatcher
    /// falls through to its drop-direct-handshake behaviour.
    pending_direct_initiators: Arc<DashMap<SocketAddr, oneshot::Sender<Bytes>>>,
    /// Our Noise static keypair — needed to construct responder state
    /// when a routed msg1 arrives for us.
    static_keypair: StaticKeypair,
    /// PSK shared across the mesh.
    psk: [u8; 32],
    /// Socket for sending outbound subprotocol responses.
    socket: Arc<NetSocket>,
    /// Proximity graph for topology awareness.
    proximity_graph: Arc<ProximityGraph>,
    /// Partition filter — packets from blocked addresses are dropped.
    partition_filter: PartitionFilter,
    /// RT-5: honor + cascade inbound route withdrawals.
    enable_route_withdraw: bool,
    /// RT-5: seq for cascaded withdrawals this node re-authors.
    route_withdraw_seq: Arc<AtomicU64>,
    /// RT-5: per-dest damping for cascaded withdrawals.
    route_withdraw_damper: Arc<DashMap<(u64, Option<u64>), std::time::Instant>>,
    /// RT-5: inbound-withdrawal seq ordering gate.
    route_withdraw_gate: Arc<WithdrawalSeqGate>,
    /// RT-5: count of dispatch-path cascade tasks currently in
    /// flight, capped at `MAX_INFLIGHT_ROUTE_WITHDRAW_CASCADES` so a
    /// distinct-dest withdrawal storm can't pin the receive loop
    /// (Finding 4).
    route_withdraw_cascades_inflight: Arc<AtomicUsize>,
    /// SI-2a: gate for the 0x0C02 dispatch arm — mirrors
    /// `enable_route_withdraw`. Off = the frame drops with zero
    /// work, exactly like an unknown subprotocol id (plan §5, "the
    /// plane ships dark").
    enable_sensing_coalescing: bool,
    /// SI-2a: local cap on accepted soft-state lifetimes. See the
    /// matching `MeshNodeConfig` field.
    sensing_interest_ttl: Duration,
    /// SI-2a: the per-hop interest table. See the matching field on
    /// `MeshNode`.
    sensing_interest_table: Arc<parking_lot::Mutex<sensing::InterestTable>>,
    /// SI-2a: sensing-plane counters. See the matching field on
    /// `MeshNode`.
    sensing_counters: Arc<sensing::SensingCounters>,
    /// SI-2a: over-cap refusal tally. See the matching field on
    /// `MeshNode`.
    sensing_over_cap: Arc<AtomicU64>,
    /// SI-2a: the owner root this node's sensing plane serves. See
    /// the matching field on `MeshNode`.
    sensing_local_root: sensing::AudienceScopeCommitment,
    /// SI-2: whether `sensing_local_root` was EXPLICITLY supplied by
    /// the operator (`config.sensing_owner_root.is_some()`) — the
    /// fleet-scope deviation's opt-in. Only then does the dispatch
    /// arm admit a pinned peer's fleet-root claim (see the
    /// fleet-membership admission in
    /// [`MeshNode::handle_sensing_interest_frame`]); a default-rooted
    /// node keeps the strict entity-root rule.
    sensing_fleet_scope: bool,
    /// SI-2a: upstream-propagation damper. See the matching field on
    /// `MeshNode`.
    sensing_upstream_damper: Arc<DashMap<(u64, [u8; 32]), std::time::Instant>>,
    /// SI-2a: the sensing-leader intake slot. See the matching field
    /// on `MeshNode`.
    #[cfg(feature = "redex")]
    sensing_leader: Arc<parking_lot::Mutex<Option<sensing::SensingLeader>>>,
    /// SI-6.1 closure: per-capability leading+trailing-edge gate for
    /// fold-driven leader reconciliation. See the matching field on
    /// `MeshNode`.
    #[cfg(feature = "redex")]
    sensing_fold_coalescer: Arc<DashMap<[u8; 32], SensingFoldGate>>,
    /// SI-2b: this node's OWN entity commitment. The candidate
    /// snapshot's §4.10 authorization reads each declarer's
    /// TOFU-pinned entity root from `peer_entity_ids`, which never
    /// contains self — this is the root reported when the local
    /// node is itself a declarer. Distinct from
    /// `sensing_local_root`, which may be an operator-supplied
    /// fleet root.
    #[cfg(feature = "redex")]
    sensing_local_entity_root: sensing::AudienceScopeCommitment,
    /// SI-3: the origin-emission scheduler slot. See the matching
    /// field on `MeshNode`; the dispatch arm feeds it when a
    /// `ProviderRegistration` targets this node.
    sensing_emitter: Arc<parking_lot::Mutex<Option<sensing::OriginEmitter>>>,
    /// SI-3: wakes the emitter loop after intake changed a schedule.
    sensing_emitter_notify: Arc<tokio::sync::Notify>,
    /// SI-3: this node's signing identity, for one-shot refusal
    /// beats authored on the intake path (streams sign in the
    /// emitter loop).
    signing_identity: Arc<EntityKeypair>,
    /// SI-3: the node's own announce generation
    /// (`MeshNode::capability_version`) — stamped into attestations
    /// at evaluation time (§3.4).
    capability_version: Arc<AtomicU64>,
    /// SI-3c: the 0x0C03 intake's §4.6 observer gate. See the
    /// matching field on `MeshNode`.
    sensing_observer_gate: Arc<parking_lot::Mutex<sensing::IncarnationSeqGate>>,
    /// SI-4a: continuity factor k for this hop's upstream cells
    /// (plan §4.5, `config.continuity_factor`).
    sensing_continuity_factor: u32,
    /// SI-4b: bumps whenever a LOCAL branch projection changes —
    /// the §4.9 overlay change signal (SI-6's scheduler-bridge
    /// wake-up seam). Subscribe via
    /// `MeshNode::subscribe_sensing_overlay_changes`.
    sensing_overlay_changed: Arc<tokio::sync::watch::Sender<u64>>,
    /// SI-4 review P0: provider-free digest expectations. See the
    /// matching field on `MeshNode`.
    sensing_capability_interests: CapabilityInterestExpectations,
    /// SI-3c: the verified-observation seam (latest + refusals +
    /// provider epochs). See the matching field on `MeshNode`.
    sensing_observations: Arc<parking_lot::Mutex<SensingObservations>>,
    /// Pending StreamWindow grants enqueue by the receive path,
    /// drained by `MeshNode::spawn_stream_grant_drainer_loop`. T1.1
    /// from `PERF_AUDIT_2026_05_19_NRPC.md`.
    pending_stream_grants: Arc<parking_lot::Mutex<HashMap<(u64, u64), PendingStreamGrant>>>,
    /// Wakes the grant drainer on enqueue.
    pending_stream_grants_notify: Arc<Notify>,
    /// Control-plane emission counters, shared with the mesh's
    /// drainer/retransmit loops. Dispatch counts NACK-driven
    /// retransmit sends here (STREAM_ACK_BATCHING B-4).
    control_stats: Arc<ControlPlaneStats>,
    /// Settings for sessions we create during inbound dispatch (relayed
    /// handshake responder completes here).
    packet_pool_size: usize,
    default_reliable: bool,
    /// Idle/heartbeat window for an established session. Used by the
    /// routed-handshake rotation gate to refuse swapping a live
    /// session's keys until the existing session has gone silent for
    /// at least this long. See `routed_rotation_outcome`.
    session_timeout: Duration,
    /// Subscriber roster for channel fan-out.
    roster: Arc<SubscriberRoster>,
    /// Channel config registry used to authorize incoming Subscribe.
    /// `None` disables channel-level ACL checks (any caller accepted).
    channel_configs: Option<Arc<ChannelConfigRegistry>>,
    /// In-flight Subscribe/Unsubscribe requests awaiting an Ack, keyed by nonce.
    pending_membership_acks: Arc<DashMap<u64, (u64, oneshot::Sender<MembershipAck>)>>,
    /// In-flight reflex probes keyed by the responder's `node_id`.
    /// Populated by `MeshNode::probe_reflex`; the dispatch branch
    /// for `SUBPROTOCOL_REFLEX` completes the oneshot with the
    /// decoded observed-address on response receipt. Only one
    /// probe per peer is in flight at a time — a second call
    /// replaces the pending entry and the previous caller sees
    /// `ReflexTimeout`.
    #[cfg(feature = "nat-traversal")]
    pending_reflex_probes:
        Arc<DashMap<u64, (u64, tokio::sync::oneshot::Sender<std::net::SocketAddr>)>>,
    /// Waiters for incoming `PunchIntroduce` messages, keyed by
    /// the counterpart endpoint's `node_id` (the `peer` field in
    /// the introduce). The value tuple is `(generation, expected
    /// coordinator node, oneshot sender)`. The coordinator binding
    /// is the session peer the local node *expects* to forward the
    /// introduce (the relay it sent `PunchRequest` to). Without
    /// this binding any session peer could send a forged introduce
    /// for any in-flight target and steer the local node's punch
    /// flow at an attacker-chosen reflex address.
    #[cfg(feature = "nat-traversal")]
    pending_punch_introduces: PendingPunchIntroduces,
    /// Waiters for incoming `PunchAck` messages, keyed by the
    /// sender's `node_id` (the `from_peer` field in the ack).
    /// `connect_direct`'s `SinglePunch` path awaits on this map
    /// to confirm the peer completed their side of the punch.
    /// The value tuple is `(generation, expected coordinator node,
    /// oneshot sender)`. The coordinator forwards the
    /// counterpart's ack to us; binding to that node id at insert
    /// time prevents any other session peer from forging a
    /// `PunchAck { from_peer: counterpart, ... }` and resolving
    /// the local node's connect_direct future with attacker-chosen
    /// payload.
    #[cfg(feature = "nat-traversal")]
    pending_punch_acks: PendingPunchAcks,
    /// Keep-alive observers, keyed by the `SocketAddr` of the
    /// counterpart's `peer_reflex`. The value pairs the expected
    /// counterpart `node_id` with the oneshot. The receive loop
    /// fires (and removes) the observer only for a `Keepalive`
    /// whose `sender_node_id` matches that expected id; a stray or
    /// spoofed keep-alive from the right source addr but the wrong
    /// sender is left in place so it can't burn an in-flight punch.
    /// The endpoint's punch-scheduling task consumes the fired
    /// oneshot to decide when to emit a `PunchAck`.
    #[cfg(feature = "nat-traversal")]
    punch_observers: Arc<
        DashMap<
            SocketAddr,
            (
                u64,
                tokio::sync::oneshot::Sender<super::traversal::rendezvous::Keepalive>,
            ),
        >,
    >,
    /// Rendezvous abuse budgets. See the matching field doc on
    /// `MeshNode` (`rendezvous_budgets`).
    #[cfg(feature = "nat-traversal")]
    rendezvous_budgets: Arc<RendezvousBudgets>,
    /// NAT-traversal tunables (probe timeouts, punch cadence,
    /// classification deadlines). Shared with `MeshNode` by value
    /// since `TraversalConfig` is `Clone` and small. The dispatch
    /// path only reads it — no need for an Arc.
    #[cfg(feature = "nat-traversal")]
    traversal_config: super::traversal::TraversalConfig,
    /// Max distinct channels a single peer may subscribe to.
    max_channels_per_peer: usize,
    /// Capability fold shared with `MeshNode`. Inbound
    /// `SUBPROTOCOL_CAPABILITY_ANN` packets land here via the
    /// bridge's `translate_announcement`.
    capability_fold: Arc<super::behavior::fold::Fold<super::behavior::fold::CapabilityFold>>,
    /// Per-peer ack-ranges capability-gate cache, shared with the
    /// drainer/retransmit loops. The dispatch handler invalidates a
    /// peer's entry the instant a fresh `SUBPROTOCOL_CAPABILITY_ANN`
    /// is folded, so the next gate check re-resolves through the fold
    /// instead of serving a verdict cached before the announcement
    /// landed (STREAM_ACK_BATCHING R-5; see
    /// [`peer_supports_ack_ranges`]).
    ack_ranges_peer_cache: Arc<DashMap<u64, (bool, Instant)>>,
    /// Generation-keyed LRU cache of synthesized
    /// `Arc<CapabilitySet>` per node. Backs the per-packet greedy
    /// admission scope (mesh.rs `process_data_packet`) and other
    /// callers that previously paid 3-5 µs + ~100 allocs every
    /// time they needed a node's parsed capability set. Per
    /// PERF_AUDIT_2026_06_10_FULL_CRATE.md §4.1. Gated on
    /// `dataforts` because the greedy-observer read in
    /// `process_data_packet` is its only consumer — an ungated
    /// field is dead code under `-D warnings` for non-dataforts
    /// feature combinations.
    #[cfg(feature = "dataforts")]
    capability_set_cache: Arc<super::behavior::fold::capability_bridge::CapabilitySetCache>,
    /// Dedup cache for multi-hop capability announcements, keyed by
    /// `(origin_node_id, version)`. Written by the dispatch handler
    /// before indexing + forwarding so a `(origin, version)` tuple
    /// is processed at most once per node.
    /// Per-(node_id, version, is_direct) dedup of capability
    /// announcements. The `is_direct` axis (`hop_count == 0`)
    /// keeps a forwarded ann's dedup from suppressing the same
    /// peer's later direct announcement — the TOFU pin runs only
    /// on the direct path, so a forwarder cannot poison the
    /// dedup table for a peer's `(node_id, version)` and stop
    /// the victim's `peer_entity_ids` mapping from populating.
    /// Two diamond-arrived forwarded anns still dedup against
    /// each other (both `is_direct == false`); two diamond-
    /// arrived direct anns is a non-sequitur (`from_node ==
    /// ann.node_id` on the direct path, so there's only one peer
    /// that can produce one).
    seen_announcements: Arc<DashMap<(u64, u64, bool), std::time::Instant>>,
    /// Whether inbound `CapabilityAnnouncement` packets without a
    /// signature are dropped. Validity is not enforced yet.
    require_signed_capabilities: bool,
    /// This node's subnet (copy of `config.subnet`).
    local_subnet: SubnetId,
    /// Policy applied to each inbound `CapabilityAnnouncement` to
    /// derive the sender's subnet. `None` disables tracking.
    local_subnet_policy: Option<Arc<SubnetPolicy>>,
    /// Per-peer subnet map, written by the capability-announcement
    /// dispatch and read by the subscribe gate + publish fan-out.
    peer_subnets: Arc<DashMap<u64, SubnetId>>,
    /// See the matching field doc on `MeshNode`. Cloned in at
    /// dispatch-start time; the inline `subnet_visible` call site
    /// in `authorize_subscribe` records forward/drop decisions
    /// through this gateway when present.
    subnet_gateway: Option<Arc<SubnetGateway>>,
    /// Per-peer entity-id map, written by the capability-
    /// announcement dispatch after signature verification. Load-
    /// bearing for channel auth.
    peer_entity_ids: Arc<DashMap<u64, EntityId>>,
    /// Reverse index: wire `origin_hash` → publisher's `node_id`.
    /// Populated alongside `peer_entity_ids` at TOFU pin time on
    /// a first-write-wins basis — an established claimant can't
    /// be displaced by a different node grinding a colliding u64.
    /// Used by the greedy-chain admission gate to resolve the
    /// publisher's caps without consulting the last-hop peer.
    origin_hash_to_node: Arc<DashMap<u64, u64>>,
    /// Reverse index: `session_id → node_id`. Populated on every
    /// peer insert (connect / accept / routed-msg1 dispatch),
    /// removed on every peer eviction (failure-detector callback,
    /// sweep loop). Lets the routed-local dispatch path resolve a
    /// session_id to its peer node_id in O(1) — pre-fix the
    /// `peers.iter().find(|e| session_id matches)` scan at
    /// `dispatch_packet`'s routed branch ran on the single receive
    /// task, so an O(peers) scan per routed data packet serialized
    /// ingress on relay-heavy topologies (PERF_AUDIT §2.4).
    session_id_to_node: Arc<DashMap<u64, u64>>,
    /// Shared token cache, populated by subscriber-presented tokens
    /// plus caller-side pre-installs. `None` disables the
    /// `require_token` path — unset is equivalent to "no token is
    /// ever valid."
    token_cache: Option<Arc<TokenCache>>,
    /// Verified subscribe token chains, keyed by `(node_id,
    /// channel_hash)`. `authorize_subscribe` stores the chain a peer
    /// presented once it passes the root-anchored gate; the periodic
    /// `sweep_expired_subscribers` re-verifies the stored chain against
    /// current time + revocation so an expired or revoked credential
    /// gets the subscriber evicted without the peer re-presenting.
    /// Entries are dropped on unsubscribe / roster removal.
    subscriber_chains: Arc<DashMap<(u64, ChannelHash), RetainedChain>>,
    /// Per-packet authorization fast path. `authorize_subscribe`
    /// writes on success (via `allow_channel`) so the publish
    /// fan-out can use the bloom filter + verified cache to admit
    /// or drop subscribers in constant time.
    auth_guard: Arc<AuthGuard>,
    /// Per-peer auth-failure state (for the subscribe rate limit).
    auth_failures: Arc<DashMap<u64, AuthFailureState>>,
    /// Failures-per-window threshold from the parent config.
    max_auth_failures_per_window: u16,
    /// Rolling window length for auth-failure counting.
    auth_failure_window: Duration,
    /// How long a peer stays throttled after tripping the threshold.
    auth_throttle_duration: Duration,
}

/// Result passed through the pending-ack oneshot.
#[derive(Debug, Clone)]
pub(crate) struct MembershipAck {
    pub accepted: bool,
    pub reason: Option<AckReason>,
}

/// Configuration for a MeshNode.
#[derive(Debug, Clone)]
pub struct MeshNodeConfig {
    /// Local bind address
    pub bind_addr: SocketAddr,
    /// Pre-shared key (32 bytes, shared across the mesh)
    pub psk: [u8; 32],
    /// Heartbeat interval for failure detection
    pub heartbeat_interval: Duration,
    /// Session timeout
    pub session_timeout: Duration,
    /// Number of shards for inbound event routing
    pub num_shards: u16,
    /// Packet pool size per session
    pub packet_pool_size: usize,
    /// Default reliability mode
    pub default_reliable: bool,
    /// Use the Linux batched-ingress receive path (`recvmmsg` via a dedicated
    /// thread + batched channel) for the steady-state receive loop, instead of
    /// the per-packet `recv_buf_from` path.
    ///
    /// **Runtime flag, present only under the `batched-ingress` build feature**
    /// — the build feature decides whether the batching path is compiled in at
    /// all; this flag decides whether it's used at runtime. **Default `false`**
    /// and a no-op off Linux. Batched ingress collapses receive syscalls under
    /// sustained high-throughput load, but routes every inbound packet through
    /// a cross-thread channel hop — which can add latency to low-concurrency
    /// traffic (e.g. nRPC unary) that the per-packet path doesn't pay. Per
    /// NRPC_RECV_LOOP_BATCHING_PLAN this stays opt-in until the c128 throughput
    /// and unary-latency measurement justifies flipping the default; the flag
    /// exists so that measurement can A/B the two paths on the real mesh loop.
    #[cfg(feature = "batched-ingress")]
    pub batched_ingress: bool,
    /// Handshake timeout per attempt
    pub handshake_timeout: Duration,
    /// Handshake retries
    pub handshake_retries: usize,
    /// Socket buffer config
    pub socket_buffers: SocketBufferConfig,
    /// Max queue depth per stream for the fair scheduler.
    pub max_queue_depth: usize,
    /// Fair scheduling quantum (packets per stream per round).
    pub fair_quantum: usize,
    /// Idle timeout before a stream is evicted from its session. A
    /// stream with no send or receive activity for this long is dropped
    /// on the heartbeat-loop sweep. Protects against unbounded
    /// `StreamState` growth under workloads that hash into stream ids.
    pub stream_idle_timeout: Duration,
    /// Hard cap on the number of streams per session. When exceeded,
    /// the least-recently-active stream is evicted via the same path as
    /// `close_stream` (logged with `reason=cap_exceeded`).
    pub max_streams: usize,
    /// Max channels a single peer may subscribe to via
    /// `SUBPROTOCOL_CHANNEL_MEMBERSHIP`. Extra Subscribe requests are
    /// rejected with `AckReason::TooManyChannels`. Protects the roster
    /// from a peer that spams subscriptions.
    pub max_channels_per_peer: usize,
    /// Timeout for `subscribe_channel` / `unsubscribe_channel` to wait
    /// for an `Ack` before returning `AdapterError::Timeout`.
    pub membership_ack_timeout: Duration,
    /// Drop inbound `CapabilityAnnouncement` packets whose signature
    /// is missing. Defaults to `true` because the cap data feeds
    /// channel-auth (`can_publish` / `can_subscribe` cap filters)
    /// and subnet visibility — an unsigned announcement is
    /// attacker-controlled input, and accepting it silently meant a
    /// peer could claim any caps or subnet just by announcing. The
    /// dispatch path still applies a second belt-and-braces guard
    /// on individual auth-load-bearing state updates
    /// (`peer_entity_ids`, `peer_subnets`), so explicitly setting
    /// this to `false` for discovery-only deployments is
    /// defensible; flipping this on simply makes the rejection
    /// happen up-front instead of silently no-oping the state
    /// writes downstream.
    pub require_signed_capabilities: bool,
    /// How often the capability index sweeps expired entries. Low
    /// values waste CPU; high values keep stale peers queryable past
    /// their TTL.
    pub capability_gc_interval: Duration,
    /// How often this node re-announces its own capabilities to keep its
    /// entry alive. Capability entries carry a TTL (default 300 s) and the
    /// fold sweeper evicts them on expiry, so without a periodic
    /// re-announce a node's own self-entry ages out of its LOCAL fold —
    /// after which its callee-side nRPC capability gate
    /// (`may_execute(self, …)`) finds no self-entry and denies every
    /// inbound call — AND out of every PEER's fold, so it stops being
    /// discoverable (`find_service_nodes` returns empty). Both happen ~one
    /// TTL after the last announce. The loop re-broadcasts with a TTL of
    /// `2 ×` this interval, so a single missed re-announce can't expire
    /// the entry. `Duration::MAX` disables the loop (for nodes that
    /// re-announce on their own cadence). Default 150 s (→ 300 s TTL,
    /// matching the announce default).
    ///
    /// The loop runs only for nodes started via [`MeshNode::start_arc`]
    /// (the SDK / FFI path) — re-broadcasting needs an owned `Arc`. A bare
    /// [`MeshNode::start`] omits it.
    pub capability_reannounce_interval: Duration,
    /// Emit positive SACK-range ACKs (`StreamAckRanges`) to peers that
    /// advertise [`ACK_RANGES_CAPABILITY_TAG`], and merge that tag
    /// into this node's own capability announcements
    /// (STREAM_ACK_BATCHING R-5). Disabling turns the feature off
    /// wire-wide for this node's sends and advertisements; receiving
    /// stays unconditional. Default `true`.
    ///
    /// Note: `true` makes the node *willing* to advertise and emit, but
    /// the tag only propagates when the node actually broadcasts a
    /// capability announcement — see [`ACK_RANGES_CAPABILITY_TAG`] for
    /// exactly when that happens. Two default-config nodes that never
    /// announce fall back to the legacy path; call
    /// [`MeshNode::announce_capabilities`] to engage SACK ranges.
    pub enable_stream_ack_ranges: bool,
    /// This node's subnet. Defaults to [`SubnetId::GLOBAL`] — "no
    /// restriction." Visibility checks compare against this value on
    /// both the publish and subscribe paths.
    pub subnet: SubnetId,
    /// Policy applied to inbound [`CapabilityAnnouncement`]s to
    /// derive each peer's subnet. `None` disables per-peer subnet
    /// tracking; every peer is treated as `GLOBAL`, which in
    /// practice means `Visibility::SubnetLocal` channels ship only
    /// when both sides are `GLOBAL`.
    pub subnet_policy: Option<Arc<SubnetPolicy>>,
    /// Visibility applied on publish when a channel has **no**
    /// registered config in the local
    /// [`ChannelConfigRegistry`]. Defaults to
    /// [`Visibility::Global`] — simple deployments without a
    /// registry publish unrestricted, which is the lowest-
    /// friction default for single-subnet meshes.
    ///
    /// Security-conservative deployments (fleets where forgetting
    /// to register a channel should not silently leak messages
    /// across subnets) set this to
    /// [`Visibility::SubnetLocal`]. The publish path reads it on
    /// every fanout, so toggling it propagates without a restart.
    ///
    /// This is **only** the fallback for unregistered channels —
    /// a channel with an explicit registry entry always uses
    /// its configured visibility.
    pub default_visibility: Visibility,
    /// Minimum time between successive
    /// [`MeshNode::announce_capabilities`] broadcasts from this
    /// origin. Calls within the window coalesce: the local index
    /// and `local_announcement` are updated so self-queries + late-
    /// joiner session-open pushes reflect the latest caps, and one
    /// trailing-edge flush re-broadcasts the newest announcement at
    /// window end (RT-1; needs [`MeshNode::start_arc`], else the
    /// in-window broadcast is dropped as before). Rate-limits apps
    /// that re-announce in tight loops.
    pub min_announce_interval: Duration,
    /// Debounce window for the change-driven announcer (RT-3,
    /// REALTIME_ROUTING_AND_DISCOVERY_PLAN). When a local
    /// capability mutation fires the RT-2 change signal — a
    /// `serve_tool` register/unregister or nRPC service
    /// register/deregister — the announcer waits this long for the
    /// burst to settle, then broadcasts once. A service registering
    /// 20 tools at startup produces one announcement, not 20.
    ///
    /// `Duration::MAX` disables the announcer (capability changes
    /// then propagate only via explicit
    /// [`MeshNode::announce_capabilities`] calls, session-open
    /// pushes, and the re-announce keep-alive). Like the keep-alive
    /// loop, the announcer runs only for nodes started via
    /// [`MeshNode::start_arc`]. Default 100 ms.
    pub announce_debounce: Duration,
    /// Minimum gap between event-triggered pingwaves (RT-4,
    /// REALTIME_ROUTING_AND_DISCOVERY_PLAN). Topology changes —
    /// session open, failure-detector recovery, a change-driven
    /// capability announce — emit a pingwave immediately instead of
    /// waiting for the next heartbeat tick, so remote routing
    /// tables converge at flood speed. This gap coalesces churn
    /// storms: events inside the gap are silently absorbed (the
    /// pingwave carries whole-node state, and the heartbeat tick
    /// remains the anti-entropy floor that repairs anything
    /// missed). `Duration::MAX` disables event pingwaves entirely.
    /// Default 250 ms.
    pub event_pingwave_min_gap: Duration,
    /// Emit + honor poison-reverse route withdrawals (RT-5,
    /// REALTIME_ROUTING_AND_DISCOVERY_PLAN,
    /// `SUBPROTOCOL_ROUTE_WITHDRAW`). When the failure detector
    /// marks a direct peer Failed, this node floods "that peer is
    /// unreachable via me"; receivers drop exactly their
    /// `(dest, next_hop = sender)` route, promote an alternate when
    /// one exists, and cascade their own withdrawal when none does.
    /// Convergence after failure detection drops from the
    /// `3 × session_timeout` age-out to one flood. `false` restores
    /// pre-RT-5 behavior on both the emit and receive side: a node
    /// with this disabled — like a peer new enough to have the
    /// dispatch-loop unknown-subprotocol guard — drops inbound
    /// withdrawals cleanly and ages routes out instead. Default
    /// `true`.
    pub enable_route_withdraw: bool,
    /// Enable the capability-sensing interest plane (SI-2a,
    /// SENSING_INTEREST_COALESCING_PLAN §5 `enable_sensing_coalescing`).
    /// When on, this node dispatches inbound
    /// [`sensing::SUBPROTOCOL_SENSING_INTEREST`] (0x0C02) frames into
    /// its per-hop [`sensing::InterestTable`], propagates coalesced
    /// interest aggregates upstream toward `next_hop(provider)`, and
    /// accepts [`MeshNode::register_sensing_interest`] calls. When
    /// off — **the default: v1 ships dark** — the node does ZERO
    /// sensing work: inbound 0x0C02 frames drop at the dispatch arm
    /// exactly like an unknown subprotocol id (no decode, no
    /// counters), local registration calls are refused, and the
    /// heartbeat sweep skips the (empty) table.
    pub enable_sensing_coalescing: bool,
    /// Sensing soft-state lifetime (plan §5 `sensing_interest_ttl`):
    /// interest rows refresh at ttl/2 and drop after 2 missed
    /// refreshes. This is also the LOCAL bound on what inbound
    /// registrations may ask for — a downstream requesting a longer
    /// ttl is capped to this value, so a hostile peer cannot pin
    /// table rows past the operator's soft-state horizon. Default
    /// 30 s.
    pub sensing_interest_ttl: Duration,
    /// Per-downstream inbound interest cap (plan §5
    /// `max_interests_per_peer`): the amplification bound on how
    /// many `(interest, provider)` rows one downstream — one peer
    /// session, or this node's own LOCAL registrations — may hold in
    /// the table. Registrations past the cap are refused
    /// ([`sensing::RegisterOutcome::OverCap`]); refreshes of existing
    /// rows are never capped. Default 512.
    pub max_interests_per_peer: usize,
    /// Attestation cadence floor (plan §5 `attestation_cadence_floor`):
    /// requested sample intervals below this receive a structured
    /// refusal instead of a stream. The config knob lands with SI-2a
    /// so deployments are tunable from the first dark-launch build;
    /// the origin emitter that enforces it is SI-3 wiring. Default
    /// 50 ms ([`sensing::DEFAULT_ATTESTATION_CADENCE_FLOOR`]).
    pub attestation_cadence_floor: Duration,
    /// `k` in the continuity suspicion window (plan §5
    /// `continuity_factor`): `continuity_window = k ×
    /// max(promised_cadence, own D)` — plan §4.5. Threaded into the
    /// sensing-leader role's relay machinery
    /// ([`MeshNode::assume_sensing_leader`]); the relay-delivery hop
    /// rule that consumes it on the plain forwarding path is SI-4
    /// wiring. Default 3.
    pub continuity_factor: u32,
    /// The owner-root commitment this node's sensing plane serves
    /// (plan §4.10 — the v1 owner-root-only boundary). `None` (the
    /// default) means the node is its own owner: the root is
    /// [`sensing::AudienceScopeCommitment::owner_root`] of this
    /// node's own [`EntityId`]. A fleet operating under one owner
    /// sets every member's value to the owner entity's commitment,
    /// so members accept sensing registrations from sessions that
    /// prove that root.
    ///
    /// **SI-2a deviation note (documented):** this knob is not in
    /// the plan §5 table. It exists because the tree does not yet
    /// model node ownership — a peer's session-proven root is
    /// derived from its TOFU-pinned entity identity, so without an
    /// operator-supplied owner root no two distinct nodes could ever
    /// share a scope. Delegation proofs (scoped-capabilities
    /// follow-up, plan §4.10) subsume this knob later.
    ///
    /// **SI-2 extension (the multi-hop half):** setting this knob
    /// EXPLICITLY also opts the node into the fleet-membership
    /// admission — a TOFU-pinned session whose frames claim exactly
    /// this root is admitted as serving it, which is what lets a
    /// coalescing hop (whose own entity can never prove the fleet
    /// root) re-register demand upstream. See the admission notes on
    /// the 0x0C02 dispatch arm; default-rooted nodes keep the strict
    /// entity-root rule.
    pub sensing_owner_root: Option<sensing::AudienceScopeCommitment>,
    /// SI-3: the §4.6 origin incarnation this node's sensing plane
    /// signs attestations under. The caller owns persistence:
    /// derive the value with [`sensing::next_incarnation`] over a
    /// real [`sensing::IncarnationPersistence`] BEFORE constructing
    /// the node (increment-before-participation), exactly like the
    /// entity keypair is loaded by the caller. `Some` is TRUSTED
    /// caller input — MeshNode itself never proves the persistence
    /// claim (SI-3 review disposition; a stronger typed API may
    /// come with host integration).
    ///
    /// `None` (the default) is **fail-closed** (plan §4.6): the
    /// node never signs or emits readiness attestations — inbound
    /// interests targeting it still register table rows, but the
    /// streams stay dark and consumers project Unknown through
    /// continuity. A node that emitted under a non-persisted epoch
    /// could replay `(incarnation, seq)` pairs after a restart,
    /// which downstream observer gates poison as equivocation —
    /// silence is strictly safer than that.
    pub sensing_incarnation: Option<sensing::Incarnation>,
    /// Period between `TokenCache` expiry sweeps. A subscriber
    /// whose token expires mid-subscription is evicted from the
    /// [`SubscriberRoster`] and revoked from the [`AuthGuard`]
    /// within one sweep interval. Set to [`Duration::MAX`] (or any
    /// value longer than the mesh's lifetime) to disable the
    /// sweep — publishes will still re-check the guard, so this
    /// mainly affects how quickly stale tokens drop off the
    /// roster.
    pub token_sweep_interval: Duration,
    /// Authorization-failure threshold per peer per window. A peer
    /// that exceeds this count across a rolling
    /// [`Self::auth_failure_window`] gets throttled — subsequent
    /// subscribes short-circuit with `AckReason::RateLimited` for
    /// [`Self::auth_throttle_duration`] without running the
    /// cap-filter + ed25519 path. Set to `u16::MAX` to disable.
    pub max_auth_failures_per_window: u16,
    /// Rolling window over which failed subscribes are counted for
    /// the throttle check above. Default: 60 s.
    pub auth_failure_window: Duration,
    /// How long a peer stays throttled after tripping the
    /// failure threshold. Default: 30 s.
    pub auth_throttle_duration: Duration,
    /// Override the mesh's public-facing `SocketAddr` — the
    /// address peers see this node as reachable at. When `Some`,
    /// the classifier's background sweep is skipped entirely and
    /// the node immediately advertises `NatClass::Open` with the
    /// supplied `SocketAddr` on its capability announcements.
    ///
    /// Intended for:
    ///
    /// - **Port-forwarded servers.** An operator who has manually
    ///   configured a port forward knows the external address
    ///   directly; setting this short-circuits the multi-peer
    ///   classification that wouldn't discover anything new.
    /// - **Stage-4 port mapping (UPnP / NAT-PMP / PCP).** A
    ///   successful mapping installation records the mapped
    ///   external `ip:port` here, so subsequent peers see the
    ///   node as `Open` without the classifier needing to probe
    ///   for a reflex.
    ///
    /// Framing (plan §4): this is an optimization surface, not a
    /// connectivity requirement — a node with no override still
    /// reaches every peer through routed-handshake. Stored on
    /// `MeshNodeConfig` so both programmatic callers and future
    /// port-mapping runtime writers have a single site to update.
    ///
    /// Default: `None` (use classifier observations).
    #[cfg(feature = "nat-traversal")]
    pub reflex_override: Option<SocketAddr>,
    /// Attempt to install a UPnP-IGD / NAT-PMP / PCP port
    /// mapping on the operator's router at [`MeshNode::start`]
    /// time, lifting this node to `NatClass::Open` with the
    /// router's external `SocketAddr` when the mapping succeeds.
    ///
    /// Off by default because port mapping modifies state on a
    /// device the operator owns — some deployments explicitly
    /// disable router control from software, and the mesh should
    /// never silently change that.
    ///
    /// When set, `start()` spawns a `PortMapperTask` that:
    ///
    /// 1. Probes NAT-PMP (1 s), falls back to UPnP (2 s).
    /// 2. On install success: calls [`MeshNode::set_reflex_override`]
    ///    with the mapped external address.
    /// 3. Renews on [`super::traversal::TraversalConfig::port_mapping_renewal`]
    ///    cadence (default 30 min).
    /// 4. On 3 consecutive renewal failures: calls
    ///    [`MeshNode::clear_reflex_override`] and exits.
    /// 5. On mesh shutdown: removes the mapping (best-effort).
    ///
    /// **Optimization, not correctness.** Setting this to
    /// `true` on a network without UPnP / NAT-PMP support is
    /// safe — the task exits cleanly after one failed probe
    /// cycle and the classifier takes over as usual.
    ///
    /// Requires the `port-mapping` cargo feature. Reading this
    /// field on a build without the feature is always `false`
    /// at runtime.
    ///
    /// Default: `false`.
    #[cfg(feature = "port-mapping")]
    pub try_port_mapping: bool,

    /// Enable the background **direct-path upgrade**
    /// (`NAT_TRAVERSAL_V2_PLAN.md` Stage 3): once a session to a peer
    /// is established via a relay, opportunistically re-handshake over
    /// a direct/punched path and migrate the session, cutting relay
    /// hops out of the data plane.
    ///
    /// **Optimization, not correctness.** The data plane never waits on
    /// the upgrade — traffic rides the relay until (and unless) a direct
    /// path is established, then migrates transparently. The swap is
    /// guarded by the migration contract: only the lower-node-id end
    /// initiates (no crossing-handshake race), the install is
    /// compare-and-swap'd against a racing rotation, and a session with
    /// open streams / unacked in-flight data defers rather than dropping
    /// that state.
    ///
    /// **Default `false`.** This is new session-migration behavior; the
    /// flag exists so it can be enabled per-deployment (and by the
    /// integration tests) and validated against the real-NAT harness
    /// (Stage 4) before any consideration of flipping the default.
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub auto_direct_upgrade: bool,
}

impl MeshNodeConfig {
    /// Create with minimal required fields.
    pub fn new(bind_addr: SocketAddr, psk: [u8; 32]) -> Self {
        Self {
            bind_addr,
            psk,
            heartbeat_interval: Duration::from_secs(5),
            session_timeout: Duration::from_secs(30),
            num_shards: 4,
            packet_pool_size: 64,
            default_reliable: false,
            #[cfg(feature = "batched-ingress")]
            batched_ingress: false,
            handshake_timeout: Duration::from_secs(5),
            handshake_retries: 3,
            socket_buffers: SocketBufferConfig::for_testing(),
            max_queue_depth: 1024,
            fair_quantum: 16,
            stream_idle_timeout: Duration::from_secs(300),
            max_streams: 4096,
            max_channels_per_peer: 1024,
            membership_ack_timeout: Duration::from_secs(5),
            require_signed_capabilities: true,
            capability_gc_interval: Duration::from_secs(60),
            capability_reannounce_interval: Duration::from_secs(150),
            enable_stream_ack_ranges: true,
            subnet: SubnetId::GLOBAL,
            subnet_policy: None,
            default_visibility: Visibility::Global,
            min_announce_interval: Duration::from_secs(10),
            announce_debounce: Duration::from_millis(100),
            event_pingwave_min_gap: Duration::from_millis(250),
            enable_route_withdraw: true,
            enable_sensing_coalescing: false,
            sensing_interest_ttl: Duration::from_secs(30),
            max_interests_per_peer: 512,
            attestation_cadence_floor: sensing::DEFAULT_ATTESTATION_CADENCE_FLOOR,
            continuity_factor: 3,
            sensing_owner_root: None,
            sensing_incarnation: None,
            token_sweep_interval: Duration::from_secs(30),
            max_auth_failures_per_window: 16,
            auth_failure_window: Duration::from_secs(60),
            auth_throttle_duration: Duration::from_secs(30),
            #[cfg(feature = "nat-traversal")]
            reflex_override: None,
            #[cfg(feature = "port-mapping")]
            try_port_mapping: false,
            #[cfg(feature = "nat-traversal")]
            auto_direct_upgrade: false,
        }
    }

    /// Enable the background direct-path upgrade. See
    /// [`MeshNodeConfig::auto_direct_upgrade`] for semantics and the
    /// migration-safety guarantees.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub fn with_auto_direct_upgrade(mut self, enabled: bool) -> Self {
        self.auto_direct_upgrade = enabled;
        self
    }

    /// Set the reflex override — the public `SocketAddr` this
    /// node advertises to peers. See
    /// [`MeshNodeConfig::reflex_override`] for semantics.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub fn with_reflex_override(mut self, external: SocketAddr) -> Self {
        self.reflex_override = Some(external);
        self
    }

    /// Opt into opportunistic UPnP-IGD / NAT-PMP / PCP port
    /// mapping at `start()` time. See
    /// [`MeshNodeConfig::try_port_mapping`] for lifecycle
    /// semantics.
    ///
    /// Requires the `port-mapping` cargo feature.
    #[cfg(feature = "port-mapping")]
    pub fn with_try_port_mapping(mut self, enabled: bool) -> Self {
        self.try_port_mapping = enabled;
        self
    }

    /// Set heartbeat interval.
    pub fn with_heartbeat_interval(mut self, interval: Duration) -> Self {
        self.heartbeat_interval = interval;
        self
    }

    /// Set session timeout.
    pub fn with_session_timeout(mut self, timeout: Duration) -> Self {
        self.session_timeout = timeout;
        self
    }

    /// Set number of shards.
    pub fn with_num_shards(mut self, n: u16) -> Self {
        self.num_shards = n;
        self
    }

    /// Opt into the Linux batched-ingress receive path. See
    /// [`MeshNodeConfig::batched_ingress`] for the latency/throughput
    /// trade-off and why it defaults off. No-op off Linux. Requires the
    /// `batched-ingress` build feature.
    #[cfg(feature = "batched-ingress")]
    pub fn with_batched_ingress(mut self, enabled: bool) -> Self {
        self.batched_ingress = enabled;
        self
    }

    /// Set handshake timing.
    pub fn with_handshake(mut self, retries: usize, timeout: Duration) -> Self {
        self.handshake_retries = retries;
        self.handshake_timeout = timeout;
        self
    }

    /// Require inbound `CapabilityAnnouncement` packets to carry a
    /// signature. Unsigned announcements are dropped silently (a
    /// trace is emitted).
    pub fn with_require_signed_capabilities(mut self, require: bool) -> Self {
        self.require_signed_capabilities = require;
        self
    }

    /// Set the capability-index GC sweep interval.
    pub fn with_capability_gc_interval(mut self, interval: Duration) -> Self {
        self.capability_gc_interval = interval;
        self
    }

    /// Set the capability self-re-announce interval. See
    /// [`Self::capability_reannounce_interval`]. `Duration::MAX` disables
    /// the loop.
    pub fn with_capability_reannounce_interval(mut self, interval: Duration) -> Self {
        self.capability_reannounce_interval = interval;
        self
    }

    /// Enable/disable SACK-range ACK emission + advertisement. See
    /// [`Self::enable_stream_ack_ranges`].
    pub fn with_stream_ack_ranges(mut self, enable: bool) -> Self {
        self.enable_stream_ack_ranges = enable;
        self
    }

    /// Set the minimum interval between outbound capability-
    /// announcement broadcasts. See [`Self::min_announce_interval`].
    pub fn with_min_announce_interval(mut self, interval: Duration) -> Self {
        self.min_announce_interval = interval;
        self
    }

    /// Set the change-driven announcer's debounce window. See
    /// [`Self::announce_debounce`]. `Duration::MAX` disables the
    /// announcer.
    pub fn with_announce_debounce(mut self, debounce: Duration) -> Self {
        self.announce_debounce = debounce;
        self
    }

    /// Set the minimum gap between event-triggered pingwaves. See
    /// [`Self::event_pingwave_min_gap`]. `Duration::MAX` disables
    /// event pingwaves.
    pub fn with_event_pingwave_min_gap(mut self, gap: Duration) -> Self {
        self.event_pingwave_min_gap = gap;
        self
    }

    /// Enable/disable poison-reverse route withdrawals. See
    /// [`Self::enable_route_withdraw`].
    pub fn with_route_withdraw(mut self, enable: bool) -> Self {
        self.enable_route_withdraw = enable;
        self
    }

    /// Enable/disable the capability-sensing interest plane. See
    /// [`Self::enable_sensing_coalescing`]. Default `false` — v1
    /// ships dark.
    pub fn with_sensing_coalescing(mut self, enable: bool) -> Self {
        self.enable_sensing_coalescing = enable;
        self
    }

    /// Set the sensing soft-state lifetime. See
    /// [`Self::sensing_interest_ttl`].
    pub fn with_sensing_interest_ttl(mut self, ttl: Duration) -> Self {
        self.sensing_interest_ttl = ttl;
        self
    }

    /// Set the per-downstream sensing interest cap. See
    /// [`Self::max_interests_per_peer`].
    pub fn with_max_interests_per_peer(mut self, cap: usize) -> Self {
        self.max_interests_per_peer = cap;
        self
    }

    /// Set the attestation cadence floor. See
    /// [`Self::attestation_cadence_floor`].
    pub fn with_attestation_cadence_floor(mut self, floor: Duration) -> Self {
        self.attestation_cadence_floor = floor;
        self
    }

    /// Set `k` in the continuity suspicion window. See
    /// [`Self::continuity_factor`].
    pub fn with_continuity_factor(mut self, k: u32) -> Self {
        self.continuity_factor = k;
        self
    }

    /// Set the owner-root commitment the sensing plane serves. See
    /// [`Self::sensing_owner_root`].
    pub fn with_sensing_owner_root(mut self, root: sensing::AudienceScopeCommitment) -> Self {
        self.sensing_owner_root = Some(root);
        self
    }

    /// Set the origin incarnation the sensing plane signs under.
    /// See [`Self::sensing_incarnation`] — derive it with
    /// [`sensing::next_incarnation`] over real persistence; the
    /// origin role stays fail-closed dark without it.
    pub fn with_sensing_incarnation(mut self, incarnation: sensing::Incarnation) -> Self {
        self.sensing_incarnation = Some(incarnation);
        self
    }

    /// Set the token-expiry sweep interval. See
    /// [`Self::token_sweep_interval`].
    pub fn with_token_sweep_interval(mut self, interval: Duration) -> Self {
        self.token_sweep_interval = interval;
        self
    }

    /// Tune the per-peer authorization-failure rate limit. See
    /// [`Self::max_auth_failures_per_window`].
    pub fn with_auth_failure_limit(
        mut self,
        max_per_window: u16,
        window: Duration,
        throttle: Duration,
    ) -> Self {
        self.max_auth_failures_per_window = max_per_window;
        self.auth_failure_window = window;
        self.auth_throttle_duration = throttle;
        self
    }

    /// Pin this node to a specific subnet.
    pub fn with_subnet(mut self, subnet: SubnetId) -> Self {
        self.subnet = subnet;
        self
    }

    /// Derive each peer's subnet locally by applying this policy to
    /// their inbound [`CapabilityAnnouncement`]s. Mesh-wide policy
    /// consistency is assumed; mismatched policies lead to
    /// asymmetric views of peer subnets.
    pub fn with_subnet_policy(mut self, policy: Arc<SubnetPolicy>) -> Self {
        self.subnet_policy = Some(policy);
        self
    }

    /// Override the visibility applied to publishes on channels
    /// that have **no** registered config. Defaults to
    /// [`Visibility::Global`] — messages flow unrestricted when
    /// no registry entry exists. Flip to
    /// [`Visibility::SubnetLocal`] for fail-closed deployments
    /// where forgetting to register a channel should confine
    /// messages to the local subnet rather than broadcasting
    /// them mesh-wide.
    ///
    /// No effect on channels that *do* have a registry entry —
    /// their configured visibility always wins.
    pub fn with_default_visibility(mut self, visibility: Visibility) -> Self {
        self.default_visibility = visibility;
        self
    }
}

/// Peer connection info.
struct PeerInfo {
    /// Node ID (derived from keypair or assigned)
    node_id: u64,
    /// Address used for direct sends. For peers reached via a relay, this
    /// is the relay's address — packets to the destination go there first.
    addr: SocketAddr,
    /// Encrypted session
    session: Arc<NetSession>,
    /// The peer's Noise static public key (X25519, 32 bytes). Captured
    /// during the handshake and surfaced via
    /// [`MeshNode::peer_static_x25519`] so the identity-envelope path
    /// can seal daemon keypairs to a peer that the session already
    /// trusts. Zero-filled when the session was built without a real
    /// handshake (test paths).
    remote_static_pub: [u8; 32],
    /// Initiator's Noise ephemeral public key from the msg1 that built
    /// this session. NKpsk0 places this in the clear at the front of
    /// msg1. The responder side records it here so the replay guard in
    /// `routed_rotation_outcome` can distinguish a captured-and-
    /// replayed msg1 (same E_i) from a legitimate re-handshake by the
    /// same peer (fresh E_i). `None` when this `PeerInfo` was installed
    /// from the INITIATOR side (where the field is moot — the rotation
    /// gate only fires on the responder side) or from a test path
    /// without a real handshake.
    last_initiator_ephemeral: Option<[u8; 32]>,
}

/// In-flight initiator handshake. The dispatch loop consumes this when a
/// routed msg2 arrives for `peer_node_id`: it pulls the Noise state out,
/// runs `read_message`, derives the session keys, and signals the
/// awaiting `connect_via` caller via the oneshot.
///
/// Keyed in `pending_handshakes` by `peer_node_id as u32 as u64` because
/// the routing header's `src_id` field is only 32 bits — msg2's routing
/// header carries the truncated value, so the dispatch loop can only
/// look up by that. The full `u64` is stored here for peer registration.
struct PendingHandshake {
    noise: NoiseHandshake,
    tx: oneshot::Sender<Result<SessionKeys, CryptoError>>,
}

/// 32-bit "routing identity" projection of a `u64` node_id, used as the
/// key across the routing plane (routing header's `src_id` is `u32`).
/// Encoded back into a `u64` as the low 32 bits, high bits zero, so the
/// same projection is visible on both sides of a routed packet.
#[inline]
fn routing_id(node_id: u64) -> u64 {
    (node_id as u32) as u64
}

/// 64-bit origin-hash projection used as the `AuthGuard` key.
///
/// A prior version truncated to `u32` so the key matched the
/// routing-plane's 32-bit `src_id`, but truncating to 32 bits
/// birthday-collides at ~65 k peers — inside the practical reach of
/// a medium mesh — and lets one subscriber's grant admit a different
/// subscriber's packets. The fan-out fast path keys on the full
/// 64-bit `node_id` (the value it already has in hand), which pushes
/// the collision floor out of reach. The `src_id` field on wire
/// packets is not consulted for authorization.
#[inline]
fn subscriber_origin_hash(node_id: u64) -> u64 {
    node_id
}

/// Soft cap on the number of distinct services kept in
/// `MeshNode::rpc_route_cache`. Past this size, `rpc_route_for_service`
/// still returns a correct freshly-built `Arc<RpcRoute>` for the
/// caller — it just skips the insert, so subsequent calls for the
/// same overflow service rebuild rather than hitting the cache.
///
/// The cap exists to make the worst-case memory bounded even if a
/// caller flows attacker-controlled or otherwise high-cardinality
/// `service` strings into the nRPC entry points. Well-behaved
/// production workloads register a small fixed set of services per
/// node (typically <10), so 256 leaves a wide margin before the
/// fail-soft path engages and is small enough that even at the cap
/// the map's resident set is trivial (≈256 × small struct + two
/// short `String`s per entry).
#[cfg(feature = "cortex")]
pub(super) const RPC_ROUTE_CACHE_SOFT_CAP: usize = 256;

/// Per-service nRPC routing primitives, cached on `MeshNode` to
/// avoid the per-call `format!` + `ChannelName::new` + xxhash
/// derivation on every `Mesh::call` / `_streaming` / `_typed`.
///
/// Both the request channel (`<service>.requests`) and the reply
/// channel (`<service>.replies.<self_origin>`) are deterministic
/// functions of `service` (the reply channel additionally depends
/// on the node's own `self_origin`, which is constant for the
/// node's lifetime). Computing them once per service and reusing
/// the `Arc<RpcRoute>` saves ~5 allocations and ~2 µs per call.
///
/// Constructed lazily on first lookup via
/// `MeshNode::rpc_route_for_service`; held in the
/// `rpc_route_cache: DashMap<String, Arc<RpcRoute>>` field, bounded
/// by [`RPC_ROUTE_CACHE_SOFT_CAP`].
#[cfg(feature = "cortex")]
pub(super) struct RpcRoute {
    /// `<service>.requests` channel name. Held for the `CANCEL`
    /// emission path (`UnaryCallGuard` needs the name to construct
    /// the cancel publisher).
    pub request_channel: ChannelName,
    /// `ChannelId::new(request_channel.clone()).hash()` —
    /// pre-computed so the publish path doesn't re-hash.
    pub request_channel_hash: ChannelHash,
    /// `MeshNode::publish_stream_id(&request_channel_id)` —
    /// pre-derived stream id for per-channel ordering within a
    /// session.
    pub request_stream_id: u64,
    /// `<service>.replies.<self_origin:016x>` channel name.
    pub reply_channel: ChannelName,
    /// `reply_channel.hash()` — pre-computed for the reply
    /// subscription check.
    pub reply_hash: ChannelHash,
}

/// Replace a zero `Duration` with a 1 s floor.
/// `tokio::time::interval` panics on a zero period; this is the
/// guard every `spawn_*_loop` call site applies before handing the
/// caller-configured interval to tokio. A legitimate "disable this
/// timer" sentinel is `Duration::MAX`, documented on the relevant
/// config fields — `Duration::ZERO` is just pathological input.
///
/// The floor is deliberately coarse (1 s, not 1 ms): a mis-configured
/// zero-interval used to spin the maintenance loop at 1 kHz, calling
/// `index.gc()` + `seen.retain()` a thousand times a second and
/// burning a whole core. 1 Hz keeps the loop obviously alive for
/// observability without an appreciable CPU cost, and is still
/// finer than the default intervals (capability GC ≈ announcement
/// TTL, token sweep 30 s), so it never masks a legitimate
/// fine-grained config — those values are already well above 1 s.
/// Parse an inbound migration payload just far enough to decide
/// whether it's a migration-initiating message that needs a
/// `ComputeNotSupported` response. Returns the encoded reply for
/// `TakeSnapshot` / `SnapshotReady`; `None` for decode failures or
/// mid-migration message types (which arrive only inside an
/// already-live migration and so can't reach a node with no
/// handler at all).
///
/// Used by the mesh dispatch loop when `ctx.migration_handler` is
/// `None` — a bare `Mesh` with no `DaemonRuntime` attached still
/// responds to migration attempts instead of silently dropping
/// them, so the source surfaces `MigrationFailureReason::ComputeNotSupported`
/// promptly rather than timing out.
fn synthesize_compute_not_supported_reply(payload: &[u8]) -> Option<Bytes> {
    use crate::adapter::net::compute::orchestrator::wire as mig_wire;
    use crate::adapter::net::compute::{MigrationFailureReason, MigrationMessage};

    let msg = mig_wire::decode(payload).ok()?;
    let origin = match msg {
        MigrationMessage::TakeSnapshot { daemon_origin, .. }
        | MigrationMessage::SnapshotReady { daemon_origin, .. } => daemon_origin,
        _ => return None,
    };
    let reply = MigrationMessage::MigrationFailed {
        daemon_origin: origin,
        reason: MigrationFailureReason::ComputeNotSupported,
    };
    mig_wire::encode(&reply).ok().map(Bytes::from)
}

#[inline]
fn nonzero_interval(d: Duration) -> Duration {
    if d.is_zero() {
        Duration::from_secs(1)
    } else {
        d
    }
}

/// TTL the capability re-announce loop stamps on its broadcasts.
///
/// The loop ticks every `reannounce_interval`, but
/// [`MeshNode::announce_capabilities_with`] rate-limits the actual network
/// broadcast to at most once per `min_announce_interval`. So the cadence
/// peers *actually* see a refresh at is `max(reannounce_interval,
/// min_announce_interval)`, not `reannounce_interval`. We stamp `2 ×` that
/// effective cadence so a peer entry survives one missed broadcast; using the
/// bare `reannounce_interval` would let peer entries expire whenever it is
/// configured below `min_announce_interval` (the broadcast is throttled away,
/// but the TTL was sized as if it weren't). Floored at 1 s because the
/// announce TTL is truncated to whole seconds on the wire.
#[inline]
fn capability_reannounce_ttl(
    reannounce_interval: Duration,
    min_announce_interval: Duration,
) -> Duration {
    reannounce_interval
        .max(min_announce_interval)
        .saturating_mul(2)
        .max(Duration::from_secs(1))
}

/// Race a punch-observer `oneshot::Receiver` against a deadline
/// and handle cleanup of the shared `punch_observers` map with
/// the correct semantics for each outcome. Returns `true` when a
/// keep-alive fired the observer (caller should emit a `PunchAck`),
/// `false` otherwise.
///
/// The keep-alive's `sender_node_id` is validated by the receive
/// loop *before* it fires this oneshot — only a packet whose sender
/// matches the awaited counterpart consumes the observer (see the
/// `remove_if` in `dispatch_packet`). So a `true` here already means
/// "a keep-alive from the right peer arrived"; the caller no longer
/// re-checks the sender. Crucially, a stray/spoofed keep-alive from
/// the right source addr but the wrong sender id is left in the map
/// by the receive loop rather than consuming the observer, so it
/// can't burn an in-flight punch — a later valid keep-alive still
/// fires this oneshot.
///
/// Three outcomes, each with a distinct cleanup rule:
///
/// - **`Ok(Ok(_ka))`** — a validated keep-alive arrived and the
///   receive loop fired our sender. Returns `true`. The receive
///   loop already consumed the map entry via `remove_if` when it
///   fired the oneshot, so no cleanup needed here.
/// - **`Ok(Err(_))`** — our sender was dropped without firing.
///   This happens when a newer observer replaced ours in the
///   map (`DashMap::insert` drops the old value, which wakes
///   our `rx` with `RecvError`). Returning without removing the
///   key is load-bearing: removing would evict the replacement
///   observer that's now legitimately in the map.
/// - **`Err(_)`** — the deadline expired. Our sender is still
///   in the map — if it had been replaced we'd be in the
///   `Ok(Err)` branch above, not here. Remove our stale entry
///   so a late keep-alive doesn't find it.
///
/// History: earlier revisions collapsed `Ok(Err)` and `Err(_)`
/// into a single `remove`-in-both-cases arm, which evicted
/// replacement observers. cubic flagged this as a P2. The
/// three-arm split is tested in `await_punch_observer_outcome`'s
/// unit tests below.
#[cfg(feature = "nat-traversal")]
async fn await_punch_observer_outcome(
    obs_rx: tokio::sync::oneshot::Receiver<super::traversal::rendezvous::Keepalive>,
    deadline: Duration,
    punch_observers: &DashMap<
        SocketAddr,
        (
            u64,
            tokio::sync::oneshot::Sender<super::traversal::rendezvous::Keepalive>,
        ),
    >,
    peer_reflex: SocketAddr,
) -> bool {
    match tokio::time::timeout(deadline, obs_rx).await {
        // Observer fired with a sender-validated keep-alive.
        Ok(Ok(_ka)) => true,
        // Sender was dropped — almost certainly replaced by a
        // newer observer for the same peer_reflex. Leaving the
        // map alone is correct: the replacement's sender is the
        // current value and a remove would evict it.
        Ok(Err(_)) => false,
        // Deadline fired with our sender still in the map. Evict
        // so a late keep-alive doesn't find a stale entry.
        Err(_) => {
            punch_observers.remove(&peer_reflex);
            false
        }
    }
}

/// RAII single-flight gate over an `AtomicBool`.
///
/// [`SweepGuard::try_enter`] returns `Some(guard)` iff the flag was
/// previously clear (and atomically sets it); dropping the guard
/// clears it. [`MeshNode::reclassify_nat`] uses it to honor its
/// documented "at most one sweep at a time" contract: a second,
/// concurrent entry observes the flag already set and bails out as a
/// no-op rather than racing the in-flight sweep on the shared
/// `pending_reflex_probes` map.
#[cfg(feature = "nat-traversal")]
struct SweepGuard<'a>(&'a std::sync::atomic::AtomicBool);

#[cfg(feature = "nat-traversal")]
impl<'a> SweepGuard<'a> {
    /// Try to enter the single-flight section. `Some` on success
    /// (flag was clear, now set); `None` if a sweep is already
    /// running. `Acquire` on the swap so the entering sweep's reads
    /// happen-after the prior sweep's `Release` on drop.
    fn try_enter(flag: &'a std::sync::atomic::AtomicBool) -> Option<Self> {
        if flag.swap(true, std::sync::atomic::Ordering::Acquire) {
            None
        } else {
            Some(Self(flag))
        }
    }
}

#[cfg(feature = "nat-traversal")]
impl Drop for SweepGuard<'_> {
    fn drop(&mut self) {
        self.0.store(false, std::sync::atomic::Ordering::Release);
    }
}

/// Compute the three keep-alive send offsets (relative to the
/// scheduler task's spawn instant) for a punch whose synchronized
/// fire time is `fire_at_ms` (Unix epoch ms), given the current
/// wall-clock `now_ms` and the punch `deadline`.
///
/// The lead (`fire_at_ms - now_ms`) is:
///
/// - **clamped to `deadline`** — `fire_at_ms` is a
///   coordinator-supplied value, and a malicious or buggy
///   coordinator can name a fire time arbitrarily far in the
///   future. A lead beyond `deadline` is useless (the observer task
///   gives up then), and leaving it unbounded would park the
///   keep-alive sender task — which holds a socket handle + payload
///   — for that whole duration, with `start + offset` risking an
///   `Instant` overflow. Clamping bounds the sender task's lifetime
///   to within ~250 ms of the observer's: the `+100/+250 ms` spacing
///   below is applied *after* the clamp, so at the clamp extreme the
///   last keep-alive fires at `deadline + 250 ms` — still bounded and
///   panic-free, just not exactly co-terminous with the observer.
/// - **floored at zero** by the saturating subtraction — a lead in
///   the past (clock skew, slow path) collapses to "fire
///   immediately."
///
/// The +100 ms / +250 ms spacing (plan §3) is applied after the
/// clamp; saturating adds keep the arithmetic panic-free even at
/// the `Duration::MAX` extreme.
#[cfg(feature = "nat-traversal")]
fn keepalive_send_offsets(fire_at_ms: u64, now_ms: u64, deadline: Duration) -> [Duration; 3] {
    let base_lead = Duration::from_millis(fire_at_ms.saturating_sub(now_ms)).min(deadline);
    [
        base_lead,
        base_lead.saturating_add(Duration::from_millis(100)),
        base_lead.saturating_add(Duration::from_millis(250)),
    ]
}

/// Rolling-window auth-failure tracker, one entry per peer.
/// Lives behind a per-key `Mutex` so updates from concurrent
/// subscribes don't race each other on the same peer's counter.
#[derive(Debug, Default)]
struct AuthFailureState {
    /// Failures accumulated inside the current window.
    failures: u16,
    /// Start of the window. Resets to `Instant::now()` once
    /// `auth_failure_window` has elapsed since the current window
    /// opened.
    window_start: Option<std::time::Instant>,
    /// If set, the peer is throttled until this instant and every
    /// subscribe short-circuits with `RateLimited`.
    throttled_until: Option<std::time::Instant>,
}

/// Evict subscribers whose tokens have expired. Walks the roster by
/// peer and, for every `require_token` channel they hold, runs the
/// full token-cache check. Expired entries are revoked in the
/// [`AuthGuard`] and removed from the [`SubscriberRoster`].
///
/// Skip conditions (short-circuits to no-op):
///
/// - No `token_cache`: `require_token` channels reject every
///   subscribe anyway, so the roster contains no token-gated
///   entries.
/// - No `channel_configs`: nothing to check `require_token`
///   against, so every roster entry is treated as open and left
///   alone.
///
/// Pulled into a free fn (not a method) so the sweep loop can
/// call it without capturing `&self` through the async closure.
fn sweep_expired_subscribers(
    roster: &SubscriberRoster,
    guard: &AuthGuard,
    token_cache: Option<&Arc<TokenCache>>,
    peer_entity_ids: &DashMap<u64, EntityId>,
    channel_configs: Option<&Arc<ChannelConfigRegistry>>,
    subscriber_chains: &DashMap<(u64, ChannelHash), RetainedChain>,
) {
    let (Some(cache), Some(configs)) = (token_cache, channel_configs) else {
        return;
    };
    let revocation = cache.revocation().as_ref();
    let skew = cache.clock_skew_secs();
    // Snapshot (node_id, entity_id) pairs so we don't hold the
    // DashMap read guard across the chain checks below.
    let peers: Vec<(u64, EntityId)> = peer_entity_ids
        .iter()
        .map(|e| (*e.key(), e.value().clone()))
        .collect();
    for (node_id, entity_id) in peers {
        for channel_id in roster.channels_for(node_id) {
            let name = channel_id.name();
            let Some(cfg) = configs.get_by_name(name.as_str()) else {
                continue;
            };
            if !cfg.token_required() {
                continue;
            }
            // Re-verify the chain the subscriber presented at subscribe
            // time against the *current* clock + revocation floors.
            // Anything that fails — expiry, a revoked root or link, a
            // root that's no longer in `token_roots` — evicts the
            // subscriber. A missing stored chain (e.g. process restarted
            // and lost the in-memory map) also evicts: fail closed and
            // force a re-subscribe that re-presents.
            // The periodic sweep is the cold authoritative re-check; it
            // always re-verifies signatures (full `reverify_subscribe`)
            // rather than trusting the publish path's cached flag.
            let authorized = subscriber_chains
                .get(&(node_id, name.hash()))
                .is_some_and(|r| cfg.reverify_subscribe(&r.chain, &entity_id, revocation, skew));
            if !authorized {
                guard.revoke_channel(subscriber_origin_hash(node_id), name);
                roster.remove(&channel_id, node_id);
                subscriber_chains.remove(&(node_id, name.hash()));
                tracing::debug!(
                    node_id = format!("{:#x}", node_id),
                    channel = name.as_str(),
                    "auth: evicted subscriber with expired/invalid/revoked token chain",
                );
            }
        }
    }
}

/// Default TTL for the routing header we stamp on routed handshake
/// packets. Far above any realistic relay chain; the routing layer
/// drops at zero.
const DEFAULT_HANDSHAKE_TTL: u8 = 16;

/// Maximum hop count a pingwave may carry on receipt. Pingwaves with
/// `hop_count >= MAX_HOPS` are dropped — they install no route, no
/// graph edge, and are not re-broadcast. TTL bounds forwarding at the
/// emitter; `MAX_HOPS` is the receive-time counterpart that prevents
/// an inflated-hop-count advertisement (malicious or buggy) from
/// populating the routing table with an arbitrarily-distant entry.
/// Value sized to accommodate the largest plausibly-useful mesh depth
/// while still bounding count-to-infinity worst cases.
const MAX_HOPS: u8 = 16;

/// Maximum number of `heat:blob:<hex>=<rate>` reserved tags
/// accepted from a single peer announcement before the
/// substrate-side filter starts dropping the overflow. Blob-heat
/// isn't gated by a `causal:` claim like chain-heat is (the blob
/// is content-addressed, so a forged hash claim doesn't grant
/// privileges), but the gravity migration controller consumes
/// the rate — without a cap, a peer spraying thousands of forged
/// heat tags forces every healthy node to attempt that many
/// `adapter.prefetch` calls. The cap bounds the amplification:
/// at most this many blob-heat tags from any one announcement
/// reach the capability index. 256 is comfortable for realistic
/// per-node hot-blob counts (manifests with thousands of chunks
/// would emit heat per chunk, but in practice a node's working
/// set is well under this bound).
const MAX_BLOB_HEAT_TAGS_PER_ANNOUNCE: usize = 256;

/// How `MeshNode::install_peer` should touch the
/// `addr_to_node` reverse index. Direct handshakes are the sole
/// owner of `peer_addr → peer_node_id` for the connection's
/// lifetime; routed handshakes may share `peer_addr` with a
/// relay's own peer entry (true multi-hop case) and must not
/// clobber it.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum AddrInstallMode {
    /// Direct handshake (`connect`): unconditional
    /// `addr_to_node[peer_addr] = peer_node_id`.
    DirectOverwrite,
    /// Routed handshake (`connect_via`): `or_insert(...)` —
    /// keeps any prior mapping intact. For the degenerate
    /// single-hop case (relay == final dest, the CLI remote-
    /// attach pattern) the slot is empty and the destination's
    /// `node_id` lands; for true multi-hop the relay's entry
    /// stays.
    RoutedPreserve,
}

/// Origin-side capability-announce rate-limit state
/// (REALTIME_ROUTING_AND_DISCOVERY_PLAN RT-1). One mutex guards
/// both fields so the broadcast-or-defer decision and the
/// deferred-slot claim are atomic: without that, two concurrent
/// in-window announces could both schedule a trailing-edge flush,
/// or a flush could race a fresh announce and double-send.
struct AnnounceGate {
    /// When the most recent outbound announcement broadcast
    /// actually hit the wire (leading edge of the rate-limit
    /// window). `None` = never broadcast, or reset by the
    /// reflex-override paths to force the next call through.
    last_broadcast_at: Option<std::time::Instant>,
    /// A trailing-edge flush task is scheduled for the end of the
    /// current window. While set, further in-window announces
    /// coalesce into that pending flush (which always broadcasts
    /// the *latest* `local_announcement`) instead of spawning
    /// more tasks.
    deferred_scheduled: bool,
    /// Monotonic id of the current deferral, bumped each time a slot
    /// is claimed. The spawned flush task captures this at spawn and
    /// re-checks it before broadcasting, so a task orphaned by a
    /// rate-limit-floor reset (which clears `deferred_scheduled`)
    /// cannot later consume a DIFFERENT deferral's claim and fire
    /// inside a fresh window (RT-1 review Finding 12).
    deferral_generation: u64,
}

/// Signal-carrying wrapper around the `nrpc:` local-service set
/// (RT-2). `serve_rpc` inserts and `ServeHandle::drop` removes
/// through the shared `Arc`, so the local-caps change signal has to
/// live inside the collection — a call-site bump could be forgotten
/// by the next registration path (same reasoning as
/// `Fold::signal_changed` and `ToolMetadataRegistry`).
#[cfg(feature = "cortex")]
pub(super) struct LocalServiceRegistry {
    set: dashmap::DashSet<String>,
    change_signal: Arc<tokio::sync::watch::Sender<u64>>,
}

#[cfg(feature = "cortex")]
impl LocalServiceRegistry {
    fn new(change_signal: Arc<tokio::sync::watch::Sender<u64>>) -> Self {
        Self {
            set: dashmap::DashSet::new(),
            change_signal,
        }
    }

    /// Insert a service name. Bumps the local-caps generation only
    /// when the name is new — an idempotent re-serve is not a
    /// capability change and must not wake the announcer.
    pub(super) fn insert(&self, service: String) -> bool {
        let inserted = self.set.insert(service);
        if inserted {
            self.change_signal.send_modify(|g| *g = g.wrapping_add(1));
        }
        inserted
    }

    /// Remove a service name. Bumps only when it was present.
    pub(super) fn remove(&self, service: &str) -> Option<String> {
        let removed = self.set.remove(service);
        if removed.is_some() {
            self.change_signal.send_modify(|g| *g = g.wrapping_add(1));
        }
        removed
    }

    pub(super) fn is_empty(&self) -> bool {
        self.set.is_empty()
    }

    /// Cloned name list for the announce-path tag merge. Announces
    /// are rare relative to lookups; the allocation keeps the
    /// DashSet's guard types out of the public surface.
    pub(super) fn snapshot(&self) -> Vec<String> {
        self.set.iter().map(|s| s.clone()).collect()
    }
}

/// RT-4 (REALTIME_ROUTING_AND_DISCOVERY_PLAN): emit one origin
/// pingwave to every connected peer NOW — outside the heartbeat
/// tick — so a topology change propagates at flood speed instead of
/// waiting up to `heartbeat_interval` per hop.
///
/// Free function (not a `MeshNode` method) because the
/// failure-detector `on_recovery` callback needs to emit before
/// `Self` exists in `MeshNode::new`; both it and
/// [`MeshNode::emit_event_pingwave`] share this one implementation.
///
/// Gated by `min_gap` against the shared `gate`: the first event in a
/// window emits immediately (leading edge); events inside the window
/// are coalesced into ONE trailing-edge emission scheduled for the
/// window's end, so an absorbed topology change still converges at
/// flood speed instead of waiting for the heartbeat tick (RT-4 review
/// Finding 10 — the pre-fix leading-edge-only gate silently dropped
/// in-window events, the same pattern RT-1 fixed for announces). The
/// heartbeat tick remains the anti-entropy floor. `Duration::MAX`
/// disables.
///
/// `resend` requests the second flood round that closes the
/// session-open bookkeeping race (below); only the direct
/// `connect`/`accept` session-open callers pass `true`. Recovery and
/// change-announce emissions pass `false` — the race can't occur for
/// them (the peer is already registered), so a second mesh-wide flood
/// would be pure duplicate traffic. The sends run on a spawned task
/// so callers — including sync callbacks — never block on socket I/O.
fn spawn_event_pingwave(
    gate: &Arc<parking_lot::Mutex<EventPingwaveGate>>,
    min_gap: Duration,
    proximity_graph: &Arc<ProximityGraph>,
    socket: &Arc<NetSocket>,
    peers: &Arc<DashMap<u64, PeerInfo>>,
    partition_filter: &PartitionFilter,
    resend: bool,
) {
    if min_gap == Duration::MAX {
        return;
    }
    enum Action {
        EmitNow,
        Defer(Duration),
        Coalesced,
    }
    let now = std::time::Instant::now();
    let action = {
        let mut g = gate.lock();
        match g.last_emit {
            Some(t) if now.saturating_duration_since(t) < min_gap => {
                if g.deferred_scheduled {
                    Action::Coalesced
                } else {
                    g.deferred_scheduled = true;
                    Action::Defer(min_gap - now.saturating_duration_since(t))
                }
            }
            _ => {
                g.last_emit = Some(now);
                Action::EmitNow
            }
        }
    };
    match action {
        Action::Coalesced => {}
        Action::EmitNow => {
            // Leading edge: `resend` callers send two rounds.
            let rounds = if resend { 2 } else { 1 };
            tokio::spawn(flood_event_pingwave_rounds(
                rounds,
                proximity_graph.clone(),
                socket.clone(),
                peers.clone(),
                partition_filter.clone(),
            ));
        }
        Action::Defer(delay) => {
            // Trailing edge: one coalesced catch-up round at window
            // end. No second round — by the time this fires (≥
            // min_gap after the leading edge) any post-handshake
            // bookkeeping has long settled.
            let gate = gate.clone();
            let proximity_graph = proximity_graph.clone();
            let socket = socket.clone();
            let peers = peers.clone();
            let filter = partition_filter.clone();
            tokio::spawn(async move {
                tokio::time::sleep(delay).await;
                {
                    let mut g = gate.lock();
                    g.deferred_scheduled = false;
                    g.last_emit = Some(std::time::Instant::now());
                }
                flood_event_pingwave_rounds(1, proximity_graph, socket, peers, filter).await;
            });
        }
    }
}

/// Flood `rounds` fresh (fresh-seq) event pingwaves to every
/// non-partitioned connected peer, re-snapshotting peers each round.
/// Round 2 (when requested) exists because a session-open emission
/// races the OTHER side's post-handshake bookkeeping: the responder
/// finishes its handshake on the initiator's final message and emits
/// immediately, but the initiator installs the `addr_to_node` entry
/// only after sending that message — on a fast link round 1 can
/// arrive before the entry exists and be dropped by the DV
/// unregistered-source gate. The re-flood lands after the bookkeeping
/// has settled; the fresh seq keeps receivers that processed round 1
/// from dedup-dropping round 2's refresh.
async fn flood_event_pingwave_rounds(
    rounds: u8,
    proximity_graph: Arc<ProximityGraph>,
    socket: Arc<NetSocket>,
    peers: Arc<DashMap<u64, PeerInfo>>,
    filter: PartitionFilter,
) {
    for round in 0..rounds {
        if round > 0 {
            tokio::time::sleep(EVENT_PINGWAVE_RESEND_DELAY).await;
        }
        let pw_bytes = proximity_graph
            .create_pingwave(HealthStatus::Healthy)
            .to_bytes();
        // Snapshot before awaiting — same shard-guard discipline as
        // the heartbeat loop's send pass.
        let targets: Vec<SocketAddr> = peers
            .iter()
            .filter_map(|e| {
                let addr = e.value().addr;
                if filter.contains(&addr) {
                    None
                } else {
                    Some(addr)
                }
            })
            .collect();
        for addr in targets {
            // Raw UDP, unencrypted — same as the heartbeat tick's
            // pingwave emission; topology is public.
            let _ = socket.send_to(&pw_bytes, addr).await;
        }
    }
}

/// Leading-edge + trailing-edge gate for event pingwaves (RT-4).
#[derive(Default)]
struct EventPingwaveGate {
    /// When the most recent pingwave actually emitted (leading edge
    /// of the current `event_pingwave_min_gap` window).
    last_emit: Option<std::time::Instant>,
    /// A trailing-edge catch-up emission is already scheduled for the
    /// end of the current window; further in-window events coalesce
    /// into it instead of scheduling more tasks.
    deferred_scheduled: bool,
}

/// Settle delay before an event pingwave's second flood round —
/// long enough for the remote side's post-handshake bookkeeping to
/// land (microseconds in practice), short enough to stay firmly
/// "flood speed" next to the multi-second heartbeat tick.
const EVENT_PINGWAVE_RESEND_DELAY: Duration = Duration::from_millis(50);

/// RT-5: a node re-floods its own withdrawal of the same dest at
/// most once per this window. Cascades and flaps are bounded by it;
/// there is no flood seen-cache because each hop re-authors its own
/// withdrawal ("dest unreachable via ME") rather than forwarding
/// someone else's.
const ROUTE_WITHDRAW_DAMP_WINDOW: Duration = Duration::from_secs(1);

/// RT-5 review Finding 4: ceiling on concurrently in-flight
/// dispatch-path cascade tasks. The per-dest damper bounds same-dest
/// re-floods, but a peer that forges pingwaves for many distinct
/// fake origins (installing `(fake_dest via attacker)` routes) then
/// withdraws them would otherwise drive one full-graph `path_to`
/// scan + cascade flood per dest. Cascades run off the receive loop
/// on spawned tasks; this caps how many run at once. Over the cap the
/// route is still dropped and anti-entropy repairs the missing
/// alternate/cascade, so the only cost of the bound is slower
/// convergence under a cascade storm — never a correctness loss.
const MAX_INFLIGHT_ROUTE_WITHDRAW_CASCADES: usize = 64;

/// Damper admission for one route-withdrawal flood, keyed by
/// `(dest, exclude)`.
///
/// `exclude` is the split-horizon neighbor a cascade was learned from,
/// so `(dest, exclude)` fixes the intended recipient set (every peer but
/// `dest` and `exclude`). Keying on `dest` alone collapsed two DISTINCT
/// recipient sets: a cascade learned from B (excludes B, notifies C)
/// would suppress a later cascade learned from C (must notify B) inside
/// the window, so B never heard about the loss (RT-5 review P2).
///
/// Returns `true` (and stamps `now`) iff no flood for this key has
/// stamped within [`ROUTE_WITHDRAW_DAMP_WINDOW`]. Split out from the
/// flood so the keying is unit-testable without a socket.
fn route_withdraw_damp_admit(
    damper: &DashMap<(u64, Option<u64>), std::time::Instant>,
    key: (u64, Option<u64>),
    now: std::time::Instant,
) -> bool {
    let mut fresh = false;
    damper
        .entry(key)
        .and_modify(|t| {
            if now.saturating_duration_since(*t) >= ROUTE_WITHDRAW_DAMP_WINDOW {
                *t = now;
                fresh = true;
            }
        })
        .or_insert_with(|| {
            fresh = true;
            now
        });
    fresh
}

/// RT-5 (REALTIME_ROUTING_AND_DISCOVERY_PLAN): flood a poison-reverse
/// [`RouteWithdrawal`] — "`dest` is unreachable via ME" — to every
/// connected peer except `dest` itself and `exclude` (split horizon
/// toward the peer we learned the loss from). Damper-gated on
/// `(dest, exclude)`; a suppressed flood returns early.
///
/// Free `async` function so both entry points share one implementation:
/// the failure-detector `on_failure` closure (which runs before `Self`
/// exists in `MeshNode::new`) fires it via [`spawn_route_withdrawal_flood`]
/// on a detached task, while the dispatch-path cascade `await`s it
/// DIRECTLY inside its in-flight-capped task so the AEAD-build + send
/// work is counted against the cap instead of escaping into an untracked
/// child (RT-5 review P2). The target snapshot is taken synchronously
/// (cheap `Arc` clones); only the per-peer build + send await.
async fn run_route_withdrawal_flood(
    seq_counter: Arc<AtomicU64>,
    damper: Arc<DashMap<(u64, Option<u64>), std::time::Instant>>,
    socket: Arc<NetSocket>,
    peers: Arc<DashMap<u64, PeerInfo>>,
    partition_filter: PartitionFilter,
    dest: u64,
    exclude: Option<u64>,
) {
    let now = std::time::Instant::now();
    if !route_withdraw_damp_admit(&damper, (dest, exclude), now) {
        return;
    }
    // Opportunistic bound: the damper only grows with distinct
    // `(dest, exclude)` pairs; a churn storm across many dests still
    // can't grow it past this sweep.
    if damper.len() > 1024 {
        damper.retain(|_, t| now.saturating_duration_since(*t) < ROUTE_WITHDRAW_DAMP_WINDOW);
    }

    // Snapshot targets (Arc clones only) — cheap even at high peer
    // counts. The withdrawal's own `seq` is authored once here so
    // every peer sees the same value (per-dest ordering gate input).
    let mut targets: Vec<(SocketAddr, Arc<NetSession>)> = Vec::new();
    for entry in peers.iter() {
        let peer_id = *entry.key();
        if peer_id == dest || Some(peer_id) == exclude {
            continue;
        }
        let addr = entry.value().addr;
        if partition_filter.contains(&addr) {
            continue;
        }
        targets.push((addr, entry.value().session.clone()));
    }
    if targets.is_empty() {
        return;
    }
    let payload = RouteWithdrawal {
        dest,
        seq: seq_counter.fetch_add(1, Ordering::Relaxed),
    }
    .to_bytes();
    let stream_id = SUBPROTOCOL_ROUTE_WITHDRAW as u64;
    let events = [Bytes::copy_from_slice(&payload)];
    for (addr, session) in targets {
        let seq = session.get_or_create_stream(stream_id).next_tx_seq();
        let packet = {
            let mut builder = session.thread_local_pool().get();
            builder.build_subprotocol(
                stream_id,
                seq,
                &events,
                PacketFlags::NONE,
                SUBPROTOCOL_ROUTE_WITHDRAW,
            )
        };
        let _ = socket.send_to(&packet, addr).await;
    }
}

/// Fire-and-forget wrapper over [`run_route_withdrawal_flood`] for sync
/// callers — the failure-detector `on_failure` callback, which must not
/// block on socket I/O. The cascade path awaits the flood directly (see
/// that fn's note on the in-flight cap), so it does NOT use this.
fn spawn_route_withdrawal_flood(
    seq_counter: &Arc<AtomicU64>,
    damper: &Arc<DashMap<(u64, Option<u64>), std::time::Instant>>,
    socket: &Arc<NetSocket>,
    peers: &Arc<DashMap<u64, PeerInfo>>,
    partition_filter: &PartitionFilter,
    dest: u64,
    exclude: Option<u64>,
) {
    tokio::spawn(run_route_withdrawal_flood(
        seq_counter.clone(),
        damper.clone(),
        socket.clone(),
        peers.clone(),
        partition_filter.clone(),
        dest,
        exclude,
    ));
}

/// SI-2a: minimum gap between upstream sensing-interest updates for
/// one `(provider, interest digest)` branch. The trailing-edge
/// mechanism chosen for this slice is the **plain min-gap damper**
/// (the RT-5 withdrawal-damper shape, documented option in the SI-2
/// slice notes) rather than the RT-1/RT-3 deferred-trailing-edge
/// gate: the [`sensing::InterestTable`] already diffs every mutation
/// against `last_advertised`, so "exactly one update per derived
/// change" holds structurally and the damper only bounds churn
/// storms. An update suppressed inside the gap is repaired by the
/// downstream's next registration/refresh (soft state);
/// `Deregister` frames bypass the damper — a branch death must
/// propagate.
const SENSING_UPSTREAM_MIN_GAP: Duration = Duration::from_millis(100);

/// SI-4 review P0: fan one batch of leader-relay deliveries out to
/// the REAL destinations. The leader's relay works on semantic
/// attestations; the wire form is this hop's latest cache — matched
/// on (incarnation, seq) so a torn race skips (the next beat
/// repairs) and "relays forward identical signed bytes" holds for
/// the leader path too. `Peer` deliveries ride the envelope stream
/// their bearing selects; `Local` deliveries feed the node's own
/// consumer overlay.
#[cfg(feature = "redex")]
#[allow(clippy::too_many_arguments)]
fn dispatch_sensing_leader_deliveries(
    socket: &Arc<NetSocket>,
    peers: &Arc<DashMap<u64, PeerInfo>>,
    addr_to_node: &Arc<DashMap<SocketAddr, u64>>,
    router: &Arc<NetRouter>,
    partition_filter: &PartitionFilter,
    local_node_id: u64,
    observations: &Arc<parking_lot::Mutex<SensingObservations>>,
    overlay: &Arc<tokio::sync::watch::Sender<u64>>,
    factor: u32,
    deliveries: Vec<sensing::Delivery>,
    now: Instant,
) {
    let mut overlay_moved = false;
    for delivery in deliveries {
        let branch = delivery.attestation.branch();
        let wire = {
            let observations = observations.lock();
            observations.latest.get(&branch).and_then(|cached| {
                ((cached.origin_incarnation, cached.seq)
                    == (
                        delivery.attestation.origin_incarnation,
                        delivery.attestation.seq,
                    ))
                    .then(|| cached.clone())
            })
        };
        let Some(wire) = wire else {
            continue;
        };
        match delivery.to {
            sensing::DownstreamId::Peer(node) => {
                let stream_id = if delivery.continuity_bearing {
                    sensing::SUBPROTOCOL_READINESS_ATTESTATION as u64
                } else {
                    sensing::SENSING_PROVISIONAL_STREAM
                };
                if let Ok(bytes) = sensing::encode_attestation(&wire) {
                    spawn_sensing_frame_send(
                        socket,
                        peers,
                        addr_to_node,
                        router,
                        partition_filter,
                        local_node_id,
                        node,
                        stream_id,
                        sensing::SUBPROTOCOL_READINESS_ATTESTATION,
                        bytes,
                    );
                }
            }
            sensing::DownstreamId::Local => {
                let interval = wire.promised_cadence;
                overlay_moved |= observations.lock().feed_consumer_cell(
                    &branch,
                    &wire,
                    delivery.continuity_bearing,
                    interval,
                    factor,
                    now,
                );
            }
            // The leader's own table never holds a Leader row.
            sensing::DownstreamId::Leader => {}
        }
    }
    if overlay_moved {
        overlay.send_modify(|generation| {
            *generation = generation.wrapping_add(1);
        });
    }
}

/// SI-3 closure item 4: the wire-interval bound. A zero interval
/// demands an infinite-rate stream; an interval beyond the local
/// soft-state lifetime cannot produce a meaningful continuity
/// stream (the row expires between beats) — both are refused at
/// every intake (`0 < D ≤ sensing_interest_ttl`), so no remote
/// value ever reaches `Instant + Duration` scheduling unchecked.
fn sensing_interval_in_bounds(interval: Duration, ttl: Duration) -> bool {
    !interval.is_zero() && interval <= ttl
}

/// SI-3c: hard cap on the latest-per-branch observation store. Every
/// stored entry answered a branch this hop actually held rows for
/// (the solicited check), so honest population is bounded by the
/// interest table; the cap only guards the lag between a row's death
/// and its reclamation (closure item 6 — branch death reclaims on
/// the sweep/deregister/partition paths, so the cap is a backstop,
/// never the steady state). A NEW branch over the cap is dropped
/// (never an eviction cascade) — the origin re-sends within one
/// cadence.
const MAX_SENSING_OBSERVATIONS: usize = 4096;

/// SI-4a: one downstream's delivery schedule on one branch — the
/// frozen SI-0f `DeliverySlot` semantics on real sessions: status
/// edges flush immediately; unchanged beats travel at the
/// downstream's own D; `pending` marks a newer-than-delivered beat
/// waiting for the schedule (flushed by the sweep's poll).
#[derive(Clone, Copy)]
struct SensingDeliverySlot {
    last_status: Option<sensing::AttestedStatus>,
    last_delivered: Option<(sensing::Incarnation, u64)>,
    next_due: Instant,
    pending: bool,
}

/// SI-3c + closure items 3/6, grown by SI-4a into the relay
/// delivery seam behind the 0x0C03 intake (the frozen SI-0f
/// `SensingRelay` semantics on the mesh's own state).
#[derive(Default)]
struct SensingObservations {
    /// Latest ADMITTED ordinary attestation per branch — warm-start
    /// status. Refusal beats never land here (closure item 6): they
    /// are cadence-request-relative CONTROL responses, not a
    /// provider-wide readiness observation, and must not warm-start
    /// surviving downstreams.
    latest: HashMap<sensing::ProviderInterestKey, sensing::ReadinessAttestation>,
    /// Latest admitted refusal beat per branch, kept apart from
    /// `latest` (closure item 6), age-stamped. A fully-partitioned
    /// branch dies the moment its refusal lands, so the record
    /// survives branch death as a TOMBSTONE (the refused consumer's
    /// only trace of why) and the sweep reclaims it once it is
    /// older than `sensing_interest_ttl` with no live branch behind
    /// it — bounded lifetime, never cap-then-drop-forever.
    refusals: HashMap<sensing::ProviderInterestKey, (sensing::ReadinessAttestation, Instant)>,
    /// Last admitted `(incarnation, generation)` per origin
    /// (closure item 3): a move on EITHER axis invalidates every
    /// cached floor for that origin before the new epoch's state
    /// applies — a floor learned under an older boot or capability
    /// definition must not keep refusing registrations.
    provider_epochs: HashMap<u64, (sensing::Incarnation, u64)>,
    /// SI-4a: this hop's OWN continuity toward each branch's origin
    /// (§4.4 hop rule input, §4.5 clock-free stream suspicion). The
    /// incoming envelope flag feeds the cell — a provisional
    /// forward never establishes — and the OUTGOING bearing derives
    /// from this cell, never from the incoming flag alone.
    upstream: HashMap<sensing::ProviderInterestKey, sensing::ObservationCell>,
    /// SI-4a: per-(branch, downstream) delivery schedules.
    /// Reclaimed with the branch; per-downstream rows that die
    /// while the branch survives leave inert slots the sweep GCs.
    slots: HashMap<(sensing::ProviderInterestKey, sensing::DownstreamId), SensingDeliverySlot>,
    /// SI-4b: the LOCAL consumer overlay — one `ObservationCell`
    /// per branch this node's own `Local` row watches (the frozen
    /// SI-0f `SensingConsumer` semantics; plan §3.5/§4.9). Fed at
    /// the Local delivery point with the hop's OUTGOING bearing, so
    /// the local consumer obeys the same hop rule as any peer.
    consumer_cells: HashMap<sensing::ProviderInterestKey, sensing::ObservationCell>,
}

impl SensingObservations {
    /// Branch death at this hop by WITHDRAWAL (sweep expiry,
    /// deregister — nobody is left to care): drop everything the
    /// branch pinned, including the origin's epoch record once its
    /// last branch is gone (closure item 6 — cap-then-drop-forever
    /// is not acceptable; the store must breathe with the table).
    fn reclaim_branch(&mut self, key: &sensing::ProviderInterestKey) {
        self.refusals.remove(key);
        self.reclaim_status(key);
    }

    /// Branch death by REFUSAL PARTITION: the warm-start status and
    /// epoch memory go, but the just-stored refusal stays as the
    /// tombstone documenting the outcome (struct docs) — the sweep
    /// ages it out.
    fn reclaim_status(&mut self, key: &sensing::ProviderInterestKey) {
        self.latest.remove(key);
        // SI-4a/b: a dead branch delivers to nobody — its continuity
        // cell, every delivery slot, and the local consumer cell
        // reclaim with it.
        self.upstream.remove(key);
        self.slots.retain(|(branch, _), _| branch != key);
        self.consumer_cells.remove(key);
        self.reclaim_orphan_epochs([key.provider]);
    }

    /// SI-4b: feed one admitted beat into the LOCAL consumer cell
    /// for a branch (lazily registered at the Local row's own D)
    /// and report whether the branch's PROJECTION moved — the
    /// overlay change signal's input (§4.9 "the fold change signal
    /// fires on overlay updates").
    fn feed_consumer_cell(
        &mut self,
        branch: &sensing::ProviderInterestKey,
        attestation: &sensing::ReadinessAttestation,
        bearing: bool,
        own_interval: Duration,
        factor: u32,
        now: Instant,
    ) -> bool {
        let cell = self
            .consumer_cells
            .entry(branch.clone())
            .or_insert_with(|| sensing::ObservationCell::register(now, own_interval, factor));
        // SI-4 review P1: the consumer's own D can change across
        // re-registrations — re-anchor the window without resetting
        // continuity.
        cell.update_interval(own_interval);
        // SI-6 review P1: movement is judged on the SCHEDULER-
        // relevant tuple, not readiness alone — a Ready→Ready beat
        // with a changed signed start estimate (or a generation
        // move) reverses candidate economics and must wake the
        // scheduler.
        let before = sensing_scheduler_view(cell);
        cell.on_admitted_beat(
            now,
            sensing::DeliveredBeat {
                attested_status: attestation.status,
                estimated_start: attestation.estimated_start,
                source_incarnation: attestation.origin_incarnation,
                capability_generation: attestation.capability_generation,
                seq: attestation.seq,
                promised_cadence: attestation.promised_cadence,
                continuity_bearing: bearing,
            },
        );
        sensing_scheduler_view(cell) != before
    }

    /// Second closure round, item 3: drop epoch records whose
    /// provider has nothing left behind them — no warm-start
    /// observation and no refusal tombstone. Runs on every
    /// reclamation path INCLUDING tombstone age-out, so
    /// `provider_epochs` can never outlive everything that
    /// justified it (churn across distinct providers stays
    /// bounded).
    fn reclaim_orphan_epochs(&mut self, providers: impl IntoIterator<Item = u64>) {
        for provider in providers {
            if !self.latest.keys().any(|k| k.provider == provider)
                && !self.refusals.keys().any(|k| k.provider == provider)
            {
                self.provider_epochs.remove(&provider);
            }
        }
    }

    /// SI-5 (§4.8): force-expire every observation this hop holds
    /// toward one provider — a failure-detector edge, an RT-5
    /// withdrawal, or an epoch supersession. Cross-digest cells must
    /// not keep vouching for a provider whose path or epoch died
    /// until their own next beat happens to arrive. Returns the
    /// disrupted upstream branches (the caller refreshes the table's
    /// hop-rule input) and whether a visible projection changed (the
    /// overlay signal's input). Recovery is the ordinary soft-state
    /// machinery: the next admitted continuity-bearing beat
    /// re-establishes.
    fn disrupt_provider(
        &mut self,
        provider: u64,
        reason: sensing::DisruptReason,
    ) -> (Vec<sensing::ProviderInterestKey>, bool) {
        let mut branches = Vec::new();
        for (key, cell) in self.upstream.iter_mut() {
            if key.provider == provider && cell.continuity() != sensing::Continuity::Expired {
                cell.disrupt(reason);
                branches.push(key.clone());
            }
        }
        let mut overlay_moved = false;
        for (key, cell) in self.consumer_cells.iter_mut() {
            if key.provider == provider {
                let before = cell.projected();
                cell.disrupt(reason);
                overlay_moved |= cell.projected() != before;
            }
        }
        (branches, overlay_moved)
    }

    /// SI-4 re-review item 5: the branch's aggregate D changed
    /// through a TABLE mutation (registration, refresh, refusal
    /// partition, deregistration, expiry) — re-anchor the hop's own
    /// continuity window IMMEDIATELY, never at the next beat: on a
    /// quiet stream the old deadline would otherwise keep optimism
    /// alive too long (loose→strict) or expire continuity too early
    /// (strict→loose).
    fn update_upstream_interval(
        &mut self,
        branch: &sensing::ProviderInterestKey,
        aggregate: Option<Duration>,
    ) {
        if let (Some(cell), Some(interval)) = (self.upstream.get_mut(branch), aggregate) {
            cell.update_interval(interval);
        }
    }

    /// SI-4 re-review item 5, consumer half: the LOCAL watch's own D
    /// changed (Local re-registration or a provider-free expectation
    /// refresh at a different D) — re-anchor the overlay cell now.
    fn update_consumer_interval(
        &mut self,
        branch: &sensing::ProviderInterestKey,
        interval: Duration,
    ) {
        if let Some(cell) = self.consumer_cells.get_mut(branch) {
            cell.update_interval(interval);
        }
    }

    /// [`Self::update_consumer_interval`] across every branch of one
    /// interest — the digest-level provider-free expectation covers
    /// any provider the leader resolved.
    fn update_consumer_intervals(
        &mut self,
        interest: &sensing::CapabilityInterestKey,
        interval: Duration,
    ) {
        for (key, cell) in self.consumer_cells.iter_mut() {
            if &key.interest == interest {
                cell.update_interval(interval);
            }
        }
    }
}

/// SI-6 review P1: the SCHEDULER-relevant view of one consumer cell
/// — everything an admitted beat can carry that changes
/// `SensedCandidates` (projection, the signed start estimate, the
/// capability generation). Movement in ANY component wakes the
/// scheduler; route estimates and fold membership ride the same
/// unified generation through their own event bumps, and the budget
/// stays caller-owned.
fn sensing_scheduler_view(
    cell: &sensing::ObservationCell,
) -> (sensing::ProjectedReadiness, Option<Duration>, u64) {
    let observation = cell.observation();
    (
        cell.projected(),
        observation.and_then(|obs| obs.estimated_start),
        observation
            .map(|obs| obs.capability_generation)
            .unwrap_or(0),
    )
}

/// SI-5 review P1: whether this node holds a LIVE, genuinely DIRECT
/// session to `node`. Presence in `peers` is NOT that: a
/// `connect_via` destination stores the RELAY's address in its
/// `PeerInfo`, so it lingers in the map while being reachable only
/// through the relay — and a Failed direct peer lingers for
/// transient-partition recovery. Directness is the
/// `promotable_direct_hop` discriminator — the session address must
/// map BACK to the node in `addr_to_node` — and liveness is the
/// failure detector's verdict where the caller has one (`None`
/// inside the detector's own callback, where the failed peer is
/// already handled by identity).
fn sensing_live_direct_session(
    peers: &DashMap<u64, PeerInfo>,
    addr_to_node: &DashMap<SocketAddr, u64>,
    failure_detector: Option<&FailureDetector>,
    node: u64,
) -> bool {
    let Some(addr) = peers.get(&node).map(|p| p.value().addr) else {
        return false;
    };
    sensing_addr_is_live_direct(addr_to_node, failure_detector, node, addr)
}

/// The address-level core of [`sensing_live_direct_session`]
/// (unit-witnessed): DIRECT iff the session address reverse-maps to
/// the node itself; LIVE iff the detector — where the caller has
/// one — does not hold it Failed or Suspected.
fn sensing_addr_is_live_direct(
    addr_to_node: &DashMap<SocketAddr, u64>,
    failure_detector: Option<&FailureDetector>,
    node: u64,
    addr: SocketAddr,
) -> bool {
    if addr_to_node.get(&addr).map(|e| *e.value()) != Some(node) {
        return false;
    }
    match failure_detector {
        Some(detector) => !matches!(
            detector.status(node),
            NodeStatus::Failed | NodeStatus::Suspected
        ),
        None => true,
    }
}

/// SI-5 (§4.8): per-provider failure-plane disruption — force-expire
/// every observation this hop holds toward `provider` (its upstream
/// continuity cells AND the local consumer overlay), refresh the
/// table's hop-rule input so subsequent forwards go provisional, and
/// fire the overlay signal when a visible projection changed. The
/// leader relay's own cells are the caller's `#[cfg(redex)]` hook
/// (`SensingRelay::disrupt_provider`) — the second-relay lesson.
/// Recovery needs no bespoke machinery: the next admitted
/// continuity-bearing beat re-establishes, and registrations re-ride
/// whatever route the failure plane promoted (ttl/2 anti-entropy).
fn disrupt_sensing_provider(
    table: &parking_lot::Mutex<sensing::InterestTable>,
    observations: &parking_lot::Mutex<SensingObservations>,
    overlay: &tokio::sync::watch::Sender<u64>,
    provider: u64,
    reason: sensing::DisruptReason,
) {
    let (branches, overlay_moved) = observations.lock().disrupt_provider(provider, reason);
    if !branches.is_empty() {
        let mut table = table.lock();
        for branch in &branches {
            table.set_upstream_continuity(branch, sensing::Continuity::Expired);
        }
    }
    if overlay_moved {
        overlay.send_modify(|generation| {
            *generation = generation.wrapping_add(1);
        });
    }
}

/// SI-5 (§4.8): honor one mesh-table upstream consequence produced
/// by an EVENT-DRIVEN row removal (peer failure, leader-demand
/// death): a dead branch reclaims its observations, retires the
/// local emission stream (stamped — a racing registration
/// survives), and deregisters upstream (bypassing the damper, as
/// every branch death does); a loosened aggregate re-anchors the
/// branch's continuity window immediately (the upstream re-send
/// rides the next refresh — no spec cache at this hop).
#[allow(clippy::too_many_arguments)]
fn apply_sensing_removal_action(
    observations: &parking_lot::Mutex<SensingObservations>,
    emitter: &parking_lot::Mutex<Option<sensing::OriginEmitter>>,
    emitter_stamp: Option<u64>,
    socket: &Arc<NetSocket>,
    peers: &Arc<DashMap<u64, PeerInfo>>,
    addr_to_node: &Arc<DashMap<SocketAddr, u64>>,
    router: &Arc<NetRouter>,
    partition_filter: &PartitionFilter,
    local_node_id: u64,
    key: &sensing::ProviderInterestKey,
    action: sensing::UpstreamAction,
) {
    match action {
        sensing::UpstreamAction::Deregister => {
            observations.lock().reclaim_branch(key);
            if key.provider == local_node_id {
                if let (Some(emitter), Some(stamp)) = (emitter.lock().as_mut(), emitter_stamp) {
                    emitter.retire_if_stale(&key.interest.interest_digest, stamp);
                }
            } else {
                let frame = sensing::SensingInterestFrame::Deregister {
                    interest_digest: key.interest.interest_digest,
                    target: Some(key.provider),
                };
                if let Ok(bytes) = sensing::encode_interest_frame(&frame) {
                    spawn_sensing_frame_send(
                        socket,
                        peers,
                        addr_to_node,
                        router,
                        partition_filter,
                        local_node_id,
                        key.provider,
                        sensing::SUBPROTOCOL_SENSING_INTEREST as u64,
                        sensing::SUBPROTOCOL_SENSING_INTEREST,
                        bytes,
                    );
                }
            }
        }
        sensing::UpstreamAction::Register { strictest } => {
            observations
                .lock()
                .update_upstream_interval(key, Some(strictest));
        }
        sensing::UpstreamAction::None => {}
    }
}

/// SI-5 (§4.8 downstream loss): a failed peer's mesh-table rows drop
/// NOW — derived aggregates recompute, dead branches reclaim +
/// deregister upstream, and local emission streams retire with their
/// last interest — never waiting for the ttl sweep.
#[allow(clippy::too_many_arguments)]
fn remove_sensing_downstream(
    table: &parking_lot::Mutex<sensing::InterestTable>,
    observations: &parking_lot::Mutex<SensingObservations>,
    emitter: &parking_lot::Mutex<Option<sensing::OriginEmitter>>,
    socket: &Arc<NetSocket>,
    peers: &Arc<DashMap<u64, PeerInfo>>,
    addr_to_node: &Arc<DashMap<SocketAddr, u64>>,
    router: &Arc<NetRouter>,
    partition_filter: &PartitionFilter,
    local_node_id: u64,
    failed: u64,
    now: Instant,
) {
    // Closure item 7 discipline: stamp BEFORE the table mutation the
    // retire decisions rest on.
    let emitter_stamp = emitter.lock().as_ref().map(|e| e.stamp());
    let actions = table
        .lock()
        .remove_downstream(sensing::DownstreamId::Peer(failed), now);
    for (key, action) in actions {
        apply_sensing_removal_action(
            observations,
            emitter,
            emitter_stamp,
            socket,
            peers,
            addr_to_node,
            router,
            partition_filter,
            local_node_id,
            &key,
            action,
        );
    }
}

/// SI-5 (§4.8) at the leader: a failed consumer's leader-relay rows
/// drop. A branch that lost its LAST consumer retires the mesh
/// Leader row — and with it the upstream demand or the local
/// stream; a merely-loosened branch re-registers the Leader row at
/// the survivors' aggregate now (window re-anchored, item 5) while
/// the upstream re-send rides the next consumer refresh (the
/// sweep's loosened-aggregate rule).
#[cfg(feature = "redex")]
#[allow(clippy::too_many_arguments)]
fn remove_sensing_leader_consumer(
    leader: &parking_lot::Mutex<Option<sensing::SensingLeader>>,
    table: &parking_lot::Mutex<sensing::InterestTable>,
    observations: &parking_lot::Mutex<SensingObservations>,
    emitter: &parking_lot::Mutex<Option<sensing::OriginEmitter>>,
    socket: &Arc<NetSocket>,
    peers: &Arc<DashMap<u64, PeerInfo>>,
    addr_to_node: &Arc<DashMap<SocketAddr, u64>>,
    router: &Arc<NetRouter>,
    partition_filter: &PartitionFilter,
    local_node_id: u64,
    local_root: sensing::AudienceScopeCommitment,
    ttl: Duration,
    failed: u64,
    now: Instant,
) {
    let actions = {
        let mut slot = leader.lock();
        match slot.as_mut() {
            Some(leader) => leader.remove_downstream(sensing::DownstreamId::Peer(failed), now),
            None => return,
        }
    };
    for (branch, action) in actions {
        match action {
            sensing::UpstreamAction::Deregister => {
                // The leader's demand for this branch died with its
                // last consumer — retire the mesh Leader row through
                // the ordinary event-driven consequences.
                let emitter_stamp = emitter.lock().as_ref().map(|e| e.stamp());
                let mesh_actions = table.lock().deregister(
                    &branch.interest.interest_digest,
                    Some(branch.provider),
                    sensing::DownstreamId::Leader,
                    now,
                );
                for (key, mesh_action) in mesh_actions {
                    apply_sensing_removal_action(
                        observations,
                        emitter,
                        emitter_stamp,
                        socket,
                        peers,
                        addr_to_node,
                        router,
                        partition_filter,
                        local_node_id,
                        &key,
                        mesh_action,
                    );
                }
            }
            sensing::UpstreamAction::Register { strictest } => {
                let (outcome, aggregate) = {
                    let mut table = table.lock();
                    let outcome = table.register(
                        &branch,
                        sensing::DownstreamId::Leader,
                        strictest,
                        ttl,
                        local_root,
                        now,
                    );
                    (outcome, table.aggregate(&branch, now))
                };
                if matches!(outcome, sensing::RegisterOutcome::Registered(_)) {
                    observations
                        .lock()
                        .update_upstream_interval(&branch, aggregate);
                }
            }
            sensing::UpstreamAction::None => {}
        }
    }
}

/// SI-6 (§4.9): one interest's two-level readiness overlay — the
/// LOCAL result-mode aggregate plus the per-(provider, generation)
/// observations behind it. A read-time JOIN over the consumer cells
/// and the proximity plane, never fold state (see
/// [`MeshNode::sensing_readiness_overlay`]).
#[derive(Debug, Clone)]
pub struct SensingReadinessOverlay {
    /// The §3.5 consumer-local aggregate.
    pub aggregate: sensing::AggregateView,
    /// The observations behind it, keyed `(provider,
    /// capability_generation)` and sorted for determinism.
    pub candidates: Vec<((u64, u64), sensing::ReadinessObservation)>,
}

/// SI-4 re-review items 8/9 (named per the sign-off's mechanical
/// note): one provider-free digest expectation. The `audience` is
/// the security-load-bearing field — intake admits a returning
/// proof through the watch ONLY when the verified signer's pinned
/// entity derives this owner root; a positional tuple hid that.
#[derive(Clone, Copy)]
struct CapabilityInterestExpectation {
    /// The consumer's own requested D.
    requested_sample_interval: Duration,
    /// Soft-state expiry (`registration + min(ttl, local horizon)`).
    expires_at: Instant,
    /// The owner root this expectation solicits (item 8).
    audience: sensing::AudienceScopeCommitment,
}

/// Shared handle to the provider-free expectation map — bounded at
/// `max_interests_per_peer` (item 9), swept with the heartbeat.
type CapabilityInterestExpectations =
    Arc<parking_lot::Mutex<HashMap<sensing::CapabilityInterestKey, CapabilityInterestExpectation>>>;

/// SI-2a: admit-or-drop for one upstream interest update (see
/// [`SENSING_UPSTREAM_MIN_GAP`]). Same entry/and_modify shape as the
/// RT-5 withdrawal damper, including the opportunistic size sweep —
/// the map only grows with distinct live branches, and a hostile
/// registration storm across many digests can't grow it past the
/// retain.
fn sensing_upstream_damper_admits(
    damper: &DashMap<(u64, [u8; 32]), std::time::Instant>,
    provider: u64,
    interest_digest: [u8; 32],
    min_gap: Duration,
) -> bool {
    let now = std::time::Instant::now();
    let mut fresh = false;
    damper
        .entry((provider, interest_digest))
        .and_modify(|t| {
            if now.saturating_duration_since(*t) >= min_gap {
                *t = now;
                fresh = true;
            }
        })
        .or_insert_with(|| {
            fresh = true;
            now
        });
    if damper.len() > 4096 {
        damper.retain(|_, t| now.saturating_duration_since(*t) < SENSING_UPSTREAM_MIN_GAP);
    }
    fresh
}

/// Second closure round, item 2: the damper gap must never exceed
/// the refresh budget of the row it protects — a fixed 100 ms gap
/// suppressed every ttl/2 refresh of a valid `ttl < 100 ms` row
/// until the upstream row expired. The effective gap is
/// `min(SENSING_UPSTREAM_MIN_GAP, soft_state_ttl / 2)`, so the
/// mandated ttl/2 refresh always passes (never an arbitrary
/// minimum ttl instead).
fn sensing_effective_min_gap(soft_state_ttl: Duration) -> Duration {
    SENSING_UPSTREAM_MIN_GAP.min(soft_state_ttl / 2)
}

/// SI-6.1 closure: one capability's fold-reconciliation gate. NOT
/// the registration damper above — that is explicitly a leading-
/// edge min-gap filter, and a REJECTED registration refresh is
/// repaired by the next ttl/2 refresh, while a rejected fold
/// reconciliation is a lost semantic state transition (nothing
/// re-drives it before soft-state repair). This gate is the
/// RT-1/RT-3 leading-plus-trailing shape: first change runs
/// immediately, an in-window change schedules exactly ONE
/// fresh-snapshot boundary run, further in-window changes coalesce
/// into it.
#[cfg(feature = "redex")]
struct SensingFoldGate {
    /// When a reconciliation for this capability last RAN.
    last_run: std::time::Instant,
    /// Monotonic token source: each `Defer` mints the NEXT value as
    /// the scheduled sleeper's ownership token (SI-6.1 re-review).
    generation: u64,
    /// The token of the boundary run currently scheduled, if any.
    /// `None` = no sleeper owns a run (never scheduled, already run,
    /// or subsumed by an out-of-window `RunNow`). A sleeper reclaims
    /// ONLY when its captured token still matches — so a stale
    /// sleeper from a superseded window cannot steal a newer
    /// window's pending run.
    pending: Option<u64>,
}

/// SI-6.1 closure: the three outcomes of one fold change hitting a
/// capability's gate.
#[cfg(feature = "redex")]
enum SensingFoldGateDecision {
    /// First change, or out of window: reconcile immediately.
    RunNow,
    /// In-window with nothing scheduled: the caller must schedule
    /// exactly one fresh-snapshot reconciliation after `remaining`,
    /// and pass `token` back to [`sensing_fold_gate_reclaim`] so the
    /// run is bound to THIS window.
    Defer { remaining: Duration, token: u64 },
    /// In-window with a boundary run already scheduled: this change
    /// coalesces into it (the boundary run's snapshot will see it).
    Coalesced,
}

#[cfg(feature = "redex")]
fn sensing_fold_gate_admit(
    coalescer: &DashMap<[u8; 32], SensingFoldGate>,
    digest: [u8; 32],
    min_gap: Duration,
) -> SensingFoldGateDecision {
    let now = std::time::Instant::now();
    let mut decision = SensingFoldGateDecision::RunNow;
    coalescer
        .entry(digest)
        .and_modify(|gate| {
            let elapsed = now.saturating_duration_since(gate.last_run);
            if elapsed >= min_gap {
                gate.last_run = now;
                // A still-sleeping boundary run is SUBSUMED by this
                // fresh out-of-window run (scheduler jitter can hold
                // a sleeper past its boundary): INVALIDATE its token
                // so a delayed wake — even one that races a later
                // window's `Defer` — reclaims nothing. Exactly-one
                // stays exact across successive windows.
                gate.pending = None;
                decision = SensingFoldGateDecision::RunNow;
            } else if gate.pending.is_some() {
                decision = SensingFoldGateDecision::Coalesced;
            } else {
                gate.generation = gate.generation.wrapping_add(1);
                let token = gate.generation;
                gate.pending = Some(token);
                decision = SensingFoldGateDecision::Defer {
                    remaining: min_gap - elapsed,
                    token,
                };
            }
        })
        .or_insert_with(|| SensingFoldGate {
            last_run: now,
            generation: 0,
            pending: None,
        });
    // Bounded like the registration damper: keys are capability ids
    // with live leader interests plus retired stragglers, swept
    // opportunistically. A pending gate is never dropped — its
    // sleeper still owns a boundary run.
    if coalescer.len() > 4096 {
        coalescer.retain(|_, gate| {
            gate.pending.is_some() || now.saturating_duration_since(gate.last_run) < min_gap
        });
    }
    decision
}

/// The boundary sleeper's claim on its scheduled run: exactly ONE
/// trailing reconciliation per window. Returns whether THIS sleeper
/// — identified by the `token` it captured at `Defer` time — still
/// owns its pending run. It does not when the run was subsumed by an
/// out-of-window `RunNow` (token invalidated) OR a later window has
/// since minted a fresh token (`pending == Some(newer)` ≠ this
/// sleeper's `token`) — the SI-6.1 re-review stale-sleeper race.
#[cfg(feature = "redex")]
fn sensing_fold_gate_reclaim(
    coalescer: &DashMap<[u8; 32], SensingFoldGate>,
    digest: &[u8; 32],
    token: u64,
) -> bool {
    coalescer
        .get_mut(digest)
        .map(|mut gate| {
            if gate.pending == Some(token) {
                gate.pending = None;
                gate.last_run = std::time::Instant::now();
                true
            } else {
                false
            }
        })
        .unwrap_or(false)
}

/// SI-2a: send one encoded sensing payload (0x0C02 interest frame
/// or, since SI-3, 0x0C03 attestation) toward `next_hop(target)`
/// over the encrypted per-peer subprotocol path — the
/// `spawn_route_withdrawal_flood` shape, single-target. Both legs
/// are HOP-BY-HOP link state (plan §4.3/§4.4): the frame is
/// encrypted to the next hop's session (which registers this node
/// as ITS downstream / applies its own relay rules and
/// re-propagates), never end-to-end.
///
/// Resolution order: a held session toward `target` wins (its
/// recorded addr is the link we already use for it — the relay's
/// addr for `connect_via` peers, which is exactly the right hop);
/// otherwise the pingwave-learned route. No route = drop silently —
/// soft state, the next registration retries and the sweep's expiry
/// bounds the stale window.
#[allow(clippy::too_many_arguments)]
fn spawn_sensing_frame_send(
    socket: &Arc<NetSocket>,
    peers: &Arc<DashMap<u64, PeerInfo>>,
    addr_to_node: &Arc<DashMap<SocketAddr, u64>>,
    router: &Arc<NetRouter>,
    partition_filter: &PartitionFilter,
    local_node_id: u64,
    target: u64,
    stream_id: u64,
    subprotocol: u16,
    payload: Vec<u8>,
) {
    let next_addr = peers
        .get(&target)
        .map(|p| p.value().addr)
        .or_else(|| router.routing_table().lookup(target));
    let Some(addr) = next_addr else {
        return;
    };
    if partition_filter.contains(&addr) {
        return;
    }
    // The hop's session is keyed by the node behind that addr — the
    // same reverse resolution the dispatch arm trusts inbound.
    let Some(hop_node) = addr_to_node.get(&addr).map(|e| *e.value()) else {
        return;
    };
    if hop_node == local_node_id {
        return;
    }
    let Some(session) = peers.get(&hop_node).map(|e| e.value().session.clone()) else {
        return;
    };
    let socket = socket.clone();
    tokio::spawn(async move {
        let events = [Bytes::from(payload)];
        // SI-4a: the stream id is the hop-authored ENVELOPE — for
        // 0x0C03 it carries the §4.4 continuity-bearing flag (see
        // `sensing::SENSING_PROVISIONAL_STREAM`).
        let seq = session.get_or_create_stream(stream_id).next_tx_seq();
        let packet = {
            let mut builder = session.thread_local_pool().get();
            builder.build_subprotocol(stream_id, seq, &events, PacketFlags::NONE, subprotocol)
        };
        let _ = socket.send_to(&packet, addr).await;
    });
}

/// SI-2b: assemble the Layer-1 candidate snapshot for one
/// capability id from the LIVE planes (plan §4.7/§4.10) — shared by
/// the 0x0C02 dispatch arm's leader intake and
/// [`MeshNode::sensing_candidate_snapshot`], so both views of the
/// candidate set are the same computation.
///
/// The seams (see [`sensing::snapshot`]):
/// - declarers: ONE `with_state` pass over the capability fold
///   ([`sensing::extract_declarers`] — the v1 tag/name structural
///   match), entity roots resolved from the TOFU pin map after the
///   fold lock drops (self resolves to `local_entity_root`);
/// - authorization: declarer's pinned root == `local_owner_root`
///   (§4.10 v1);
/// - reachability: self, OR a live direct session, OR a routing
///   table hit;
/// - route estimate: the [`sensing::proximity_route_estimate`]
///   ladder over the pingwave-learned proximity graph.
#[cfg(feature = "redex")]
#[allow(clippy::too_many_arguments)]
fn sensing_candidate_snapshot_from_parts(
    capability_fold: &super::behavior::fold::Fold<super::behavior::fold::CapabilityFold>,
    proximity_graph: &ProximityGraph,
    router: &NetRouter,
    peers: &DashMap<u64, PeerInfo>,
    peer_entity_ids: &DashMap<u64, EntityId>,
    local_node_id: u64,
    local_entity_root: sensing::AudienceScopeCommitment,
    local_owner_root: &sensing::AudienceScopeCommitment,
    capability_id: &sensing::CapabilityId,
) -> Vec<sensing::CandidateProvider> {
    let declarers = sensing::extract_declarers(capability_fold, capability_id, |node_id| {
        if node_id == local_node_id {
            Some(local_entity_root)
        } else {
            peer_entity_ids
                .get(&node_id)
                .map(|entry| sensing::AudienceScopeCommitment::owner_root(entry.value()))
        }
    });
    sensing::build_candidate_snapshot(
        &declarers,
        local_owner_root,
        |node_id| sensing::proximity_route_estimate(proximity_graph, node_id),
        |node_id| {
            node_id == local_node_id
                || peers.contains_key(&node_id)
                || router.routing_table().lookup(node_id).is_some()
        },
    )
}

/// Why [`MeshNode::register_sensing_interest`] refused a local
/// registration (SI-2a).
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum SensingRegistrationError {
    /// `enable_sensing_coalescing` is off — the plane ships dark
    /// (plan §5) and refuses local registrations too, so a disabled
    /// node emits nothing.
    Disabled,
    /// The spec failed the v1 owner-scope validation (plan §4.10) —
    /// e.g. its audience commitment names a root other than this
    /// node's own sensing root.
    Scope(sensing::ScopeError),
    /// SI-3 closure item 4: the requested sample interval is out of
    /// bounds — `0 < D ≤ sensing_interest_ttl`. A zero interval
    /// would demand an infinite-rate stream; an interval beyond the
    /// soft-state lifetime cannot produce a meaningful continuity
    /// stream (the row expires between beats).
    Interval {
        /// The out-of-bounds request.
        requested: Duration,
        /// The local maximum (`sensing_interest_ttl`).
        max: Duration,
    },
    /// Second closure round, item 2: `soft_state_ttl == 0` is
    /// refused — a zero-ttl row is dead on arrival and only
    /// manufactures reclamation corner cases.
    ZeroTtl,
    /// Second closure round, item 5: the origin is at
    /// [`sensing::MAX_LIVE_SENSING_STREAMS`] live streams — the
    /// registration was rolled back; retry after capacity frees.
    /// SI-4 re-review item 9 reuses the variant for a NEW
    /// provider-free expectation over `max_interests_per_peer`
    /// (existing-key refreshes stay admitted at capacity) — the
    /// retry-after-frees contract is identical.
    AtCapacity,
}

impl std::fmt::Display for SensingRegistrationError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Disabled => f.write_str("sensing coalescing is disabled on this node"),
            Self::Scope(error) => write!(f, "sensing scope validation refused: {error}"),
            Self::Interval { requested, max } => write!(
                f,
                "sample interval {requested:?} out of bounds (0 < D <= {max:?})"
            ),
            Self::ZeroTtl => f.write_str("zero soft-state ttl — the row would be dead on arrival"),
            Self::AtCapacity => {
                f.write_str("origin at live-stream capacity — registration rolled back")
            }
        }
    }
}

impl std::error::Error for SensingRegistrationError {}

/// Multi-peer mesh node.
///
/// Composes `NetSession` (per-peer encryption), `NetRouter` (forwarding),
/// and `FailureDetector` (heartbeat monitoring) behind a single UDP socket.
pub struct MeshNode {
    /// This node's identity (ed25519, for signing and node_id derivation).
    /// Used in Phase 3 for subprotocol message signing. `Arc` so
    /// signing tasks (the SI-3 attestation emitter) can hold it
    /// without cloning key material; deref coercion keeps
    /// `&self.identity` call sites unchanged.
    identity: Arc<EntityKeypair>,
    /// Noise static keypair (Curve25519, for handshakes)
    static_keypair: StaticKeypair,
    /// Derived node ID
    node_id: u64,
    /// Configuration
    config: MeshNodeConfig,
    /// Shared UDP socket
    socket: Arc<NetSocket>,
    /// Per-peer sessions keyed by node_id. Keying by node_id (rather than
    /// SocketAddr) is required for relayed sessions: if A connects to C via
    /// relay B, both peers share B's wire address, so a SocketAddr-keyed map
    /// would overwrite B's session with C's.
    peers: Arc<DashMap<u64, PeerInfo>>,
    /// Reverse lookup for dispatch: incoming source address → node_id. Only
    /// populated for directly-connected peers; relayed peers are resolved by
    /// session_id during dispatch.
    addr_to_node: Arc<DashMap<SocketAddr, u64>>,
    /// Router for forwarding decisions
    router: Arc<NetRouter>,
    /// Failure detector
    failure_detector: Arc<FailureDetector>,
    /// Inbound event queues (shared with receive loop)
    inbound: InboundQueues,
    /// Per-channel-hash dispatch hook for nRPC. When an inbound
    /// event's `channel_hash` matches a registered dispatcher,
    /// the event is routed there directly instead of landing in
    /// the per-shard `inbound` queue. Lookup is one DashMap get
    /// per packet on the hot path; absent registrations skip the
    /// branch entirely.
    #[cfg(feature = "cortex")]
    // Keyed by the wire `u16` hash that rides on
    // `NetHeader::channel_hash` — that's what the inbound dispatch
    // path has cheaply available at packet decode time. Each
    // bucket stores a list of `(canonical ChannelHash, dispatcher)`
    // entries so wire-bucket collisions don't cross dispatch lines;
    // the canonical `u32` hash is what each dispatcher is keyed on.
    // The `Vec` cost is paid only once per wire-bucket hit, and at
    // typical sizing there is exactly one entry per bucket.
    rpc_inbound_dispatchers: Arc<
        DashMap<
            u16,
            Vec<(
                ChannelHash,
                crate::adapter::net::cortex::RpcInboundDispatcher,
            )>,
        >,
    >,
    /// Pending oneshots for in-flight `Mesh::call` invocations.
    /// Shared with the per-Mesh `RpcClientFold` so RESPONSE events
    /// arriving on reply channels complete the right call's
    /// awaiting future.
    #[cfg(feature = "cortex")]
    rpc_client_pending: Arc<crate::adapter::net::cortex::RpcClientPending>,
    /// Independent fetch_add counter used by `RoutingPolicy::
    /// RoundRobin` and `Random` to pick the next target node.
    /// Sequential is correct here — the cursor is local-only and
    /// never leaves the process, so predictability from another
    /// peer is not a concern. (Distinct from `mint_random_call_id`,
    /// which generates the per-call correlation token that DOES
    /// cross the wire and so must be unpredictable.)
    #[cfg(feature = "cortex")]
    rpc_round_robin_cursor: Arc<std::sync::atomic::AtomicU64>,
    /// Tracks `(target_node_id, xxh3(service))` pairs we've already
    /// established a reply-channel subscription for. `Mesh::call`
    /// consults this to skip the round-trip subscribe on
    /// subsequent calls to the same (target, service).
    ///
    /// **PERF_AUDIT §3.5** — pre-fix this was a global
    /// `parking_lot::Mutex<Vec<(u64, String)>>` that every
    /// concurrent RPC caller took on every `call` to do an
    /// `iter().any(|(t, s)| ... && s == service)` String compare.
    /// All callers serialized on it. Now it's a `DashMap` keyed by
    /// `(target, xxh3_64(service))` — the membership check is a
    /// shard-local read (no global lock), and the key is two `u64`s
    /// (no String alloc on the probe). The xxh3 cost is `~10 ns` on
    /// the service bytes once per call.
    ///
    /// The value is the full service name: xxh3 is NOT
    /// collision-free, and a hash-only hit that skipped the
    /// subscribe for a *different* service would silently drop
    /// that service's replies (the reply channel embeds the
    /// service name). The hot path verifies the stored name on a
    /// hash hit; a collision therefore degrades to an idempotent
    /// re-subscribe instead of a correctness bug.
    #[cfg(feature = "cortex")]
    rpc_reply_subscriptions: Arc<dashmap::DashMap<(u64, u64), Arc<str>>>,
    /// nRPC services the local node currently handles (registered
    /// via `Mesh::serve_rpc`, deregistered when the `ServeHandle`
    /// drops). `announce_capabilities` merges these as
    /// `nrpc:<service>` tags into the announced `CapabilitySet`,
    /// so other nodes' capability indexes can find this node via
    /// `Mesh::find_service_nodes(name)`.
    #[cfg(feature = "cortex")]
    rpc_local_services: Arc<LocalServiceRegistry>,
    /// Local-only registry of AI-tool descriptors for every
    /// `serve_tool` registration on this node. Drives the
    /// auto-merge in [`announce_capabilities_with`] (adds the
    /// `ai-tool:<name>` tag + the `ToolCapability` + the
    /// description / streaming / tags metadata keys) and the
    /// future `tool.metadata.fetch` RPC handler. Empty by default
    /// — populated only when an SDK consumer calls `serve_tool`.
    #[cfg(feature = "tool")]
    tool_registry: Arc<crate::adapter::net::cortex::tool::ToolMetadataRegistry>,
    /// Caller-side per-service nRPC metrics. Updated by
    /// `Mesh::call` via the `mesh_rpc_metrics::CallMetricsGuard`
    /// RAII shim; read out via `Self::rpc_metrics_snapshot` for
    /// Prometheus exposure or custom observability.
    #[cfg(feature = "cortex")]
    rpc_metrics: Arc<crate::adapter::net::mesh_rpc_metrics::RpcMetricsRegistry>,
    /// Per-service nRPC route cache. Each entry holds the
    /// pre-computed `ChannelName` / `ChannelId` / `ChannelHash` /
    /// `stream_id` for both the request channel
    /// (`<service>.requests`) and the reply channel
    /// (`<service>.replies.<self_origin>`). Both are functions of
    /// `service` (and the node's constant `self_origin` for the
    /// reply side), so the build cost — 2 `format!` + 2
    /// `ChannelName::new` + 2 xxhash + `publish_stream_id`
    /// derivation — only pays on the first call per service.
    /// Subsequent calls do one `DashMap::get(&str)` + `Arc::clone`,
    /// saving ~5 allocations per `Mesh::call`.
    #[cfg(feature = "cortex")]
    rpc_route_cache: Arc<DashMap<String, Arc<RpcRoute>>>,
    /// Optional caller-side nRPC observer. Fired from `Mesh::call`
    /// on each call boundary (success / server-error / timeout /
    /// transport error). `Arc<ArcSwapOption<...>>` so a hot-path
    /// load is one `ArcSwap::load` + `is_none()` short-circuit
    /// when no observer is installed. See
    /// `cortex::rpc_observer::RpcObserver`.
    ///
    /// The inner type is `RpcObserverHandle` (= `Arc<dyn RpcObserver>`),
    /// which means the cell stores `Option<Arc<Arc<dyn RpcObserver>>>` —
    /// a double-`Arc`. This is a structural limitation of `arc_swap`:
    /// `RefCnt for Arc<T>` requires `T: Sized`, so `ArcSwapOption<dyn ..>`
    /// doesn't compile. The extra indirection is one allocation per
    /// install + one extra `Deref` per hot-path load; both are cheap
    /// relative to the observer firing path itself.
    #[cfg(feature = "cortex")]
    rpc_observer: Arc<ArcSwapOption<crate::adapter::net::cortex::rpc_observer::RpcObserverHandle>>,
    /// Substrate-level cancel-token registry. One per mesh; shared
    /// by every call shape (`call` / `call_service` / `call_streaming`
    /// / `call_client_stream` / `call_duplex`) so a single
    /// `mesh.cancel(token)` aborts the matching in-flight call
    /// regardless of which shape opened it.
    ///
    /// Wraps the lock-free [`crate::adapter::net::cancel_registry::CancelRegistry`]
    /// pattern; see that module for the CR-13 (cancel-before-register)
    /// and Q18 (orphan-TTL GC) race fixes.
    #[cfg(feature = "cortex")]
    cancel_registry: Arc<crate::adapter::net::cancel_registry::CancelRegistry>,
    /// Optional migration subprotocol handler — same `ArcSwapOption`
    /// surface as on `MeshNode`, propagated into the dispatch
    /// context so the packet-receive loop stays lock-free.
    migration_handler: Arc<ArcSwapOption<MigrationSubprotocolHandler>>,
    /// In-flight routed-handshake initiators, keyed by the responder's
    /// node_id. Populated by `connect_via`; consumed by the dispatch
    /// loop when the matching msg2 arrives.
    pending_handshakes: Arc<DashMap<u64, PendingHandshake>>,
    /// In-flight direct-handshake initiators, keyed by the peer's
    /// `SocketAddr`. Populated by `try_handshake_initiator` BEFORE
    /// sending msg1; consumed by the dispatch loop when a matching
    /// direct handshake response arrives. See the matching field
    /// on `DispatchCtx` for context.
    pending_direct_initiators: Arc<DashMap<SocketAddr, oneshot::Sender<Bytes>>>,
    /// Proximity graph — topology awareness from pingwave propagation
    proximity_graph: Arc<ProximityGraph>,
    /// Automatic reroute policy
    reroute_policy: Arc<ReroutePolicy>,
    /// Node ID → SocketAddr map (shared with reroute policy)
    peer_addrs: Arc<DashMap<u64, SocketAddr>>,
    /// Partition filter for simulating network splits
    partition_filter: PartitionFilter,
    /// Per-channel subscriber roster (daemon-layer fan-out).
    roster: Arc<SubscriberRoster>,
    /// Channel config registry consulted by incoming `Subscribe` packets
    /// for ACL decisions. When `None`, ACL is bypassed and all subscribes
    /// are accepted — used by tests and by nodes that don't run channels.
    channel_configs: Option<Arc<ChannelConfigRegistry>>,
    /// In-flight Subscribe/Unsubscribe requests keyed by nonce.
    pending_membership_acks: Arc<DashMap<u64, (u64, oneshot::Sender<MembershipAck>)>>,
    /// In-flight reflex probes keyed by the responder's `node_id`.
    /// Shared with `DispatchCtx` via `Arc` clone so the dispatcher
    /// can complete oneshots without routing back through
    /// `MeshNode`. Details on the field's usage in the
    /// `DispatchCtx` docstring.
    #[cfg(feature = "nat-traversal")]
    pending_reflex_probes: Arc<DashMap<u64, (u64, oneshot::Sender<std::net::SocketAddr>)>>,
    /// In-flight rendezvous handshakes keyed by the *counterpart*
    /// endpoint's `node_id` — i.e. the `peer` field in the
    /// incoming `PunchIntroduce`. The coordinator-side fanout
    /// (stage 3b) drops `PunchIntroduce` messages silently when
    /// no waiter is installed; endpoint callers that want to
    /// observe an introduce install an entry here via the
    /// stage-3c surface before calling the coordinator.
    #[cfg(feature = "nat-traversal")]
    pending_punch_introduces: PendingPunchIntroduces,
    /// In-flight punch acknowledgements keyed by the *sender*
    /// endpoint's `node_id` — i.e. the `from_peer` field on the
    /// arriving `PunchAck`. `connect_direct` awaits this map on
    /// the `SinglePunch` path so `punches_succeeded` only bumps
    /// when the peer actually confirmed the punch.
    #[cfg(feature = "nat-traversal")]
    pending_punch_acks: PendingPunchAcks,
    /// Monotonic counter for waiter generations used by the
    /// three `pending_*` maps above. Each insert stamps its
    /// entry with a unique `gen`; removal is a `remove_if` check
    /// that the entry's gen matches ours. Without this, a
    /// timeout cleanup racing a concurrent replacement could
    /// evict the new waiter — a cubic-flagged P1 bug
    /// (`connect_direct` + `request_punch` both affected).
    #[cfg(feature = "nat-traversal")]
    next_waiter_gen: Arc<std::sync::atomic::AtomicU64>,
    /// Wire correlation tokens for outbound `PunchRequest`s.
    /// Distinct from `next_waiter_gen` (a local-only guard): this
    /// value rides the wire and is echoed by `PunchReject` so the
    /// requester can tell a reject for ITS request from a delayed
    /// reject for a superseded concurrent request to the same
    /// target (cubic P2). Starts at 1 — `0` is the reserved
    /// no-request sentinel used by `await_punch_introduce`
    /// waiters. u32 wraparound is harmless: collisions would need
    /// two in-flight requests 2^32 mints apart.
    #[cfg(feature = "nat-traversal")]
    next_punch_id: Arc<std::sync::atomic::AtomicU32>,
    /// Keep-alive observers for in-progress punches, keyed by
    /// the `SocketAddr` we're watching for inbound traffic (the
    /// counterpart's `peer_reflex`). The value pairs the expected
    /// counterpart `node_id` with the oneshot; the receive loop
    /// fires the oneshot only on a keep-alive whose `sender_node_id`
    /// matches that id (a wrong-sender packet is left in place, not
    /// consumed), and the punch-scheduler task reacts by emitting a
    /// `PunchAck`.
    #[cfg(feature = "nat-traversal")]
    punch_observers: Arc<
        DashMap<
            SocketAddr,
            (
                u64,
                oneshot::Sender<super::traversal::rendezvous::Keepalive>,
            ),
        >,
    >,
    /// Rendezvous abuse budgets (coordinator per-requester,
    /// responder per-source, global concurrent-train ceiling) —
    /// `NAT_TRAVERSAL_V2_PLAN.md` Stage 2, closing review Finding 5.
    /// See [`RendezvousBudgets`].
    #[cfg(feature = "nat-traversal")]
    rendezvous_budgets: Arc<RendezvousBudgets>,
    /// Per-peer throttle for the background direct-path upgrade
    /// (Stage 3). See [`UpgradeCacheEntry`].
    #[cfg(feature = "nat-traversal")]
    upgrade_cache: Arc<DashMap<u64, UpgradeCacheEntry>>,
    /// Single-flight gate for the classification sweep.
    /// [`Self::reclassify_nat`] sets this on entry and clears it on
    /// exit (via an RAII [`SweepGuard`]); a concurrent entry while a
    /// sweep is already in flight is a no-op, as that method's doc
    /// promises. Without it, an operator / FFI `reclassify_nat` call
    /// racing the background classify loop would collide on
    /// `pending_reflex_probes` (keyed by peer id) and starve one of
    /// the sweeps. Plain `AtomicBool` (not `Arc`) — only ever touched
    /// through `&self` inside `reclassify_nat`.
    #[cfg(feature = "nat-traversal")]
    nat_classifying: std::sync::atomic::AtomicBool,
    /// Current NAT classification, encoded via
    /// [`super::traversal::classify::NatClass::as_u8`]. Starts as
    /// `Unknown` (`0`) and is updated by the classification sweep
    /// spawned in [`Self::start`]. Stored atomically so the
    /// announce-capabilities hot path can read without locking.
    #[cfg(feature = "nat-traversal")]
    nat_class: Arc<std::sync::atomic::AtomicU8>,
    /// Current reflex address (this node's public-facing
    /// `SocketAddr` as observed by remote peers), or `None` until
    /// the classification sweep has produced at least one reflex
    /// observation. Piggybacks on outbound `CapabilityAnnouncement`
    /// payloads so peers can attempt a direct connect without a
    /// separate discovery round-trip.
    #[cfg(feature = "nat-traversal")]
    reflex_addr: Arc<ArcSwapOption<SocketAddr>>,
    /// Runtime flag: `true` when the current `reflex_addr` came
    /// from an operator-set or port-mapper-installed override,
    /// `false` when it came from classification observations.
    /// When `true`, the classifier sweep short-circuits and
    /// `reflex_addr` stays pinned until
    /// [`Self::clear_reflex_override`] is called.
    ///
    /// Separate from `MeshNodeConfig::reflex_override` because the
    /// config is moved into `MeshNode` at construction time and
    /// can't be mutated afterward. A stage-4b `PortMapper` task
    /// installs a mapping mid-session; this atomic is what lets
    /// a `&self` setter turn the override on without racing the
    /// announce-capabilities path.
    #[cfg(feature = "nat-traversal")]
    reflex_override_active: Arc<std::sync::atomic::AtomicBool>,
    /// Publication barrier held briefly during any code path
    /// that touches more than one of `nat_class`, `reflex_addr`,
    /// and `reflex_override_active` as a group. The three atomics
    /// underneath are still lock-free for single-field readers
    /// (`nat_class()`, `reflex_addr()`, and the traversal-loop
    /// branches that only check one value), but the setters
    /// (`set_reflex_override`, `clear_reflex_override`) and the
    /// classifier commit (`commit_reclassify_observations`) write
    /// the triple under this lock, and readers that need a
    /// consistent snapshot (`announce_capabilities_with` emits
    /// `nat_class` AND `reflex_addr` into the same outbound
    /// announcement) read the triple under this lock too.
    ///
    /// A cubic P1 review flagged that reading the three atomics
    /// independently let a concurrent announce publish a torn
    /// state — e.g., a just-cleared override with reflex=None
    /// paired with the still-Open NAT class, or a just-set
    /// override's new reflex paired with the pre-override
    /// Unknown class. This mutex closes that window; writers
    /// serialize against each other and against the multi-field
    /// read in announce.
    #[cfg(feature = "nat-traversal")]
    traversal_publish_mu: Arc<parking_lot::Mutex<()>>,
    /// Traversal tunables — probe timeouts, classification
    /// deadline, punch cadence, and port-mapping renewal interval.
    /// Defaults match `docs/NAT_TRAVERSAL_PLAN.md`. Exposed via
    /// `MeshBuilder` setters in stage 5; internal-only today.
    #[cfg(feature = "nat-traversal")]
    traversal_config: super::traversal::TraversalConfig,
    /// Cumulative counters for `connect_direct` outcomes. Every
    /// punch attempt, success, and relay fallback is recorded
    /// here; read via [`Self::traversal_stats`]. Observability
    /// surface, not control — the traversal behavior doesn't read
    /// this.
    #[cfg(feature = "nat-traversal")]
    traversal_stats: Arc<super::traversal::TraversalStats>,
    /// Capability fold populated by inbound
    /// `SUBPROTOCOL_CAPABILITY_ANN` packets and the local
    /// `announce_capabilities` path. Self-applies so single-node
    /// queries return us too. Registered with this node's
    /// internal [`super::behavior::fold::FoldRegistry`] (installed
    /// as the [`Self::fold_router`] router by default).
    capability_fold: Arc<super::behavior::fold::Fold<super::behavior::fold::CapabilityFold>>,
    /// Per PERF_AUDIT §4.1: generation-keyed snapshot of synthesized
    /// `Arc<CapabilitySet>` per node, shared with `DispatchCtx` so
    /// the per-packet greedy admission path (and other hot callers)
    /// don't re-parse + re-allocate the full capability set every
    /// call. Gated on `dataforts` with its sole consumer (the
    /// greedy-observer read in `process_data_packet`).
    #[cfg(feature = "dataforts")]
    capability_set_cache: Arc<super::behavior::fold::capability_bridge::CapabilitySetCache>,
    /// Reservation fold, mirroring [`Self::capability_fold`]
    /// at the per-resource granularity. Always allocated so the
    /// aggregator's reservation summarizer + future
    /// `MeshNode::reservation_fold()` callers don't have to
    /// discriminate on presence. Inbound reservation
    /// announcements flow through the same `SUBPROTOCOL_FOLD`
    /// dispatch as capability announcements.
    reservation_fold: Arc<super::behavior::fold::Fold<super::behavior::fold::ReservationFold>>,
    /// Island-topology fold (Thunderdome gang-claim scheduler).
    /// Folds each host's self-announced GPU-island record — gpu set,
    /// host, warm models, and the live load / p50-latency axes —
    /// keyed by `IslandId`. Inbound island announcements flow through
    /// the same `SUBPROTOCOL_FOLD` dispatch as capability +
    /// reservation announcements; the gang scheduler reads it
    /// alongside the capability fold for the numeric-filter step. See
    /// `docs/plans/MESH_SCHEDULER_GANG_CLAIM_PLAN.md`.
    island_fold: Arc<super::behavior::fold::Fold<super::behavior::fold::IslandTopologyFold>>,
    /// Hosts MeshOS currently observes as Unreachable. The gang matcher
    /// ([`Self::match_islands`]) prunes these from the candidate set so a
    /// dead node's islands / capabilities are never offered (MeshOS ↔
    /// Scheduler Projection 4). Lock-free `ArcSwap` so the match hot path
    /// reads it with a single load; replaced per liveness tick via
    /// [`Self::set_liveness_down`]. Empty by default (no node down).
    liveness_down: Arc<arc_swap::ArcSwap<std::collections::HashSet<super::behavior::fold::NodeId>>>,
    /// Dedup cache for multi-hop capability announcements. Keyed by
    /// `(origin_node_id, version)` — the same discriminator
    /// `CapabilityIndex` uses to skip stale announcements. Entries
    /// are evicted by the capability GC loop once their
    /// announcement's effective lifetime (2× `ttl_secs`) has
    /// elapsed. Mirrors the `seen_pingwaves` cache in
    /// [`ProximityGraph`].
    /// Per-(node_id, version, is_direct) dedup of capability
    /// announcements. The `is_direct` axis (`hop_count == 0`)
    /// keeps a forwarded ann's dedup from suppressing the same
    /// peer's later direct announcement — the TOFU pin runs only
    /// on the direct path, so a forwarder cannot poison the
    /// dedup table for a peer's `(node_id, version)` and stop
    /// the victim's `peer_entity_ids` mapping from populating.
    /// Two diamond-arrived forwarded anns still dedup against
    /// each other (both `is_direct == false`); two diamond-
    /// arrived direct anns is a non-sequitur (`from_node ==
    /// ann.node_id` on the direct path, so there's only one peer
    /// that can produce one).
    seen_announcements: Arc<DashMap<(u64, u64, bool), std::time::Instant>>,
    /// Origin-side announce rate-limit state. Compared against
    /// `config.min_announce_interval` on every `announce_capabilities_with`
    /// call; within-window calls coalesce to a local self-index
    /// update plus one trailing-edge flush at window end, so a
    /// rate-limited change is delayed by at most one window —
    /// never silently dropped until the re-announce keep-alive
    /// (RT-1).
    announce_gate: Arc<parking_lot::Mutex<AnnounceGate>>,
    /// Serializes the synchronous critical section of
    /// `announce_from_baseline` — the user-caps read/write, the
    /// `capability_version` bump, and the `local_announcement` store.
    /// Without it, two concurrent announces (e.g. the RT-3 loop and an
    /// explicit call) could clobber each other's baseline or publish
    /// versions and stored announcements out of order (RT-1/RT-3
    /// review Findings 8 + 11). Held only across the sync build, never
    /// across the peer broadcast.
    announce_mu: parking_lot::Mutex<()>,
    /// Local-origin capability change signal (RT-2). The generation
    /// bumps whenever THIS node's announced surface changes — a
    /// `serve_tool` register/unregister or an nRPC service
    /// register/deregister — and never on inbound peer
    /// announcements (those land in `capability_fold`, which this
    /// signal deliberately does not watch). That local-only
    /// property is what makes it safe to drive a change-driven
    /// announcer without echo storms. Subscribe via
    /// [`Self::subscribe_local_caps_changes`].
    local_caps_changed: Arc<tokio::sync::watch::Sender<u64>>,
    /// Timestamp of the most recent event-triggered pingwave
    /// (RT-4). Shared with the failure-detector `on_recovery`
    /// closure; compared against `config.event_pingwave_min_gap`
    /// so churn storms coalesce instead of flooding.
    event_pingwave_gate: Arc<parking_lot::Mutex<EventPingwaveGate>>,
    /// Monotonic sequence for outbound route withdrawals (RT-5).
    /// Shared with the failure-detector `on_failure` closure.
    route_withdraw_seq: Arc<AtomicU64>,
    /// Per-dest damping for outbound route withdrawals (RT-5):
    /// this node re-floods its own withdrawal of the same dest at
    /// most once per `ROUTE_WITHDRAW_DAMP_WINDOW`. Bounds cascade /
    /// flap storms without a flood seen-cache (each hop re-authors
    /// its withdrawal, so there is no flood identity to dedup on).
    route_withdraw_damper: Arc<DashMap<(u64, Option<u64>), std::time::Instant>>,
    /// Inbound-withdrawal ordering gate: strictly-newer seq per
    /// (sender, dest). Purged per sender on (re-)handshake and
    /// dead-peer eviction so a fresh incarnation's reset counter
    /// isn't mistaken for stale.
    route_withdraw_gate: Arc<WithdrawalSeqGate>,
    /// In-flight dispatch-path cascade tasks (RT-5 review Finding 4).
    /// Shared into `DispatchCtx`; caps how many `path_to`+cascade
    /// tasks run at once so a distinct-dest withdrawal storm can't
    /// pin the receive loop.
    route_withdraw_cascades_inflight: Arc<AtomicUsize>,
    /// SI-2a: the per-hop sensing interest table (plan §4.3),
    /// constructed with `max_interests_per_peer`. Shared with
    /// `DispatchCtx` (inbound registrations) and the heartbeat loop
    /// (ttl expiry sweep). Empty — and therefore free — while
    /// `enable_sensing_coalescing` is off.
    sensing_interest_table: Arc<parking_lot::Mutex<sensing::InterestTable>>,
    /// SI-2a: sensing-plane counters (protocol-invalid, scope
    /// refusals, …). Shared with `DispatchCtx`; SI-7 grows the full
    /// stats surface.
    sensing_counters: Arc<sensing::SensingCounters>,
    /// SI-2a: over-cap refusal tally — inbound registrations the
    /// table refused with [`sensing::RegisterOutcome::OverCap`]. A
    /// dispatch-plane surface (the table itself reports per-call);
    /// SI-7 folds it into the full stats story.
    sensing_over_cap: Arc<AtomicU64>,
    /// SI-2a: the owner-root commitment this node's sensing plane
    /// serves (plan §4.10): `config.sensing_owner_root`, defaulting
    /// to this node's own entity commitment. Precomputed once so the
    /// dispatch hot path never rehashes it.
    sensing_local_root: sensing::AudienceScopeCommitment,
    /// SI-2a: min-gap damper for upstream interest propagation,
    /// keyed `(provider, interest digest)`. The RT-5 damper shape —
    /// see [`sensing_upstream_damper_admits`] for why the plain
    /// min-gap was chosen over the RT-1/RT-3 deferred-trailing-edge
    /// gate for this slice.
    sensing_upstream_damper: Arc<DashMap<(u64, [u8; 32]), std::time::Instant>>,
    /// SI-2a: the sensing-leader intake slot (plan §4.1). `None`
    /// until [`MeshNode::assume_sensing_leader`] installs the role;
    /// inbound leader-addressed `CapabilityRegistration` frames drop
    /// while the slot is empty (this node is not the leader — soft
    /// state, the consumer re-registers with the real leader).
    /// `redex`-gated with `sensing::rendezvous`: the leader role
    /// rides the RedEX election, never a second election subsystem.
    #[cfg(feature = "redex")]
    sensing_leader: Arc<parking_lot::Mutex<Option<sensing::SensingLeader>>>,
    /// SI-6.1 closure: per-capability leading+trailing-edge gate for
    /// fold-driven leader reconciliation (see [`SensingFoldGate`]).
    /// A DEDICATED map, deliberately not the registration damper: a
    /// rejected registration refresh is repaired by the next ttl/2
    /// refresh, while a rejected fold reconciliation is a lost
    /// semantic state transition — it must instead coalesce into
    /// exactly one boundary run.
    #[cfg(feature = "redex")]
    sensing_fold_coalescer: Arc<DashMap<[u8; 32], SensingFoldGate>>,
    /// SI-3: the origin-emission scheduler
    /// ([`sensing::OriginEmitter`]). `Some` only when the plane is
    /// enabled AND [`MeshNodeConfig::sensing_incarnation`] was
    /// supplied — the fail-closed §4.6 rule; `None` keeps the origin
    /// role dark while relay/table behavior stays intact. Lock
    /// order: never held together with the interest-table lock
    /// (take table reads first, drop, then the emitter).
    sensing_emitter: Arc<parking_lot::Mutex<Option<sensing::OriginEmitter>>>,
    /// SI-3: wakes the emitter loop when a registration, poke, or
    /// refusal changed the schedule (`Notify` stores one permit, so
    /// a signal during a tick is never lost).
    sensing_emitter_notify: Arc<tokio::sync::Notify>,
    /// SI-3: capability integrations by capability id (plan §4.4 —
    /// one narrow trait per integration). Registered via
    /// [`MeshNode::register_readiness_evaluator`]; a targeted
    /// interest with no registered evaluator streams
    /// `ProviderUnknown { TemporarilyUnevaluable }`.
    sensing_evaluators:
        Arc<DashMap<sensing::CapabilityId, Arc<dyn sensing::ReadinessEvaluator + Send + Sync>>>,
    /// SI-3c: §4.6 strictly-newer admission over what each origin
    /// SIGNED — the [`sensing::IncarnationSeqGate`] (SI-1c) getting
    /// its first live consumer. Keys on the transcript digest, so
    /// equivocation detection binds exactly the signed bytes.
    sensing_observer_gate: Arc<parking_lot::Mutex<sensing::IncarnationSeqGate>>,
    /// SI-4b: the §4.9 overlay change signal — bumps whenever a
    /// LOCAL branch projection changes (intake edge or continuity
    /// expiry). The SI-6 scheduler bridge subscribes via
    /// [`MeshNode::subscribe_sensing_overlay_changes`].
    sensing_overlay_changed: Arc<tokio::sync::watch::Sender<u64>>,
    /// SI-4 review P0: this node's PROVIDER-FREE interest
    /// registrations (`MeshNode::register_capability_interest`) —
    /// digest-level [`CapabilityInterestExpectation`]s. A returning
    /// leader fan-out for a registered digest is solicited even
    /// though no provider-keyed row exists (the consumer never chose
    /// the provider) — but ONLY from a signer whose pinned entity
    /// derives the expectation's owner root (SI-4 re-review item 8:
    /// a distinct signer that merely knows the digest is refused).
    /// Bounded at `max_interests_per_peer` (item 9); soft state:
    /// refreshed by re-registration, expired by the sweep.
    sensing_capability_interests: CapabilityInterestExpectations,
    /// SI-3c: the verified observation seam (decode → solicited
    /// check → signature → seq gate → here): latest admitted status
    /// per branch, refusal control responses kept apart (closure
    /// item 6), and per-origin epoch memory for floor invalidation
    /// (closure item 3). Reclaims with the interest table (branch
    /// death on sweep/deregister/partition); bounded by
    /// [`MAX_SENSING_OBSERVATIONS`] as a backstop. SI-4's relay
    /// delivery machinery (per-provider caches keyed on the full
    /// [`sensing::ProviderObservationKey`], packing, down-sampling,
    /// hop rule) subsumes the `latest` half.
    sensing_observations: Arc<parking_lot::Mutex<SensingObservations>>,
    /// Most recent `CapabilityAnnouncement` this node published.
    /// Pushed to new peers right after `accept` / `connect`
    /// completes, so late joiners pick up our caps without waiting
    /// for a re-announce. `None` until the first `announce_*` call.
    local_announcement: Arc<ArcSwapOption<CapabilityAnnouncement>>,
    /// User-supplied capability baseline — the pre-augmentation set
    /// the most recent `announce_capabilities` call published. The
    /// `announce_chain` / `announce_chain_range` / `withdraw_chain`
    /// helpers mutate this baseline + re-broadcast via
    /// `announce_capabilities`, so chain tags layer on top of the
    /// last user-supplied view without re-augmenting the nrpc / nat
    /// tags that `announce_capabilities_with` overlays at broadcast
    /// time. `None` until the first `announce_*` call.
    user_caps: Arc<parking_lot::RwLock<Option<CapabilitySet>>>,
    /// Optional per-node replication inbound router. `Redex`
    /// installs one of these via [`Self::set_replication_inbound_router`]
    /// when the first replicated channel opens; subsequent
    /// `SUBPROTOCOL_REDEX` inbound frames route through it to
    /// the right per-channel runtime task. `None` when no
    /// replicated channels exist on this node; in that case
    /// inbound `SUBPROTOCOL_REDEX` frames are dropped (the
    /// substrate ignores them rather than spawning per-channel
    /// state on demand).
    ///
    /// `parking_lot::RwLock` (rather than `ArcSwapOption`) — the
    /// `dyn ReplicationInboundRouter` trait object behind the
    /// `Arc` is `!Sized`, which `arc_swap`'s `RefCnt` bound
    /// rejects. The dispatch hot path takes a read lock on
    /// every inbound `SUBPROTOCOL_REDEX` frame; reader-favored
    /// + uncontended reads keep this in single-digit-nanoseconds.
    #[cfg(feature = "redex")]
    replication_inbound_router:
        Arc<parking_lot::RwLock<Option<Arc<dyn super::redex::ReplicationInboundRouter>>>>,
    /// Optional MeshDB inbound router. The MeshDB transport
    /// installs one of these via [`Self::set_meshdb_inbound_router`]
    /// to receive `SUBPROTOCOL_MESHDB` frames (both inbound
    /// requests for a server-side query handler and inbound
    /// responses for in-flight federated calls). `None` when
    /// MeshDB is not enabled; in that case the dispatch loop
    /// takes a single `parking_lot::RwLock` read and drops the
    /// frame.
    ///
    /// Same `parking_lot::RwLock<Option<Arc<dyn ...>>>` shape as
    /// the replication router for the same reason — `dyn Trait`
    /// is `!Sized` and `ArcSwapOption` doesn't accept it.
    #[cfg(feature = "meshdb")]
    meshdb_inbound_router:
        Arc<parking_lot::RwLock<Option<Arc<dyn super::behavior::meshdb::MeshDbInboundRouter>>>>,
    /// Optional fold-framework channel router. Installed via
    /// [`Self::set_fold_router`]; the inbound dispatch arm for
    /// [`super::behavior::fold::SUBPROTOCOL_FOLD`] routes every
    /// event in a fold packet through this router after
    /// resolving the publisher's [`EntityId`] from
    /// [`Self::peer_entity_ids`]. `None` = fold packets dropped
    /// silently.
    fold_router:
        Arc<parking_lot::RwLock<Option<Arc<dyn super::behavior::fold::FoldChannelRouter>>>>,
    /// Per-`(kind, class)` monotonic generation counter for fold
    /// announcements emitted by this node. The publisher helpers
    /// bump this on every send so the wire envelope carries the
    /// next generation without callers threading the counter
    /// themselves. Sharded by `(kind, class)` so concurrent
    /// publishes to different folds (or different classes within
    /// a fold) don't contend.
    ///
    /// Each entry carries a `last_touched_us` timestamp so the
    /// background sweep
    /// ([`Self::spawn_fold_generation_gc_loop`]) can evict
    /// counters whose owning fold-entry has long since expired —
    /// ReservationFold's per-`resource_id` shard space is
    /// effectively unbounded, and without GC the counter map
    /// would grow over a node's lifetime.
    ///
    /// In-memory only — restarts reset the counters; receivers
    /// re-accept the first post-restart announcement at
    /// generation 1 because the stale entry is past the runtime
    /// TTL by the time the publisher comes back.
    fold_generations: Arc<DashMap<(u16, u64), FoldGenerationEntry>>,
    /// Optional greedy-LRU observer. `Redex` installs one of these
    /// via [`Self::set_greedy_observer`] when the operator calls
    /// `Redex::enable_greedy_dataforts(mesh, cfg)`; subsequent
    /// inbound standard-event packets fan out through the observer
    /// (in addition to the per-shard queue push the application's
    /// tail drains from). `None` when greedy is not enabled; in
    /// that case the hot path takes a single `parking_lot::RwLock`
    /// read and falls through to the queue push.
    ///
    /// Same `parking_lot::RwLock<Option<Arc<dyn ...>>>` shape as
    /// the replication router for the same reason — `dyn Trait` is
    /// `!Sized` and `ArcSwapOption` doesn't accept it.
    #[cfg(feature = "dataforts")]
    greedy_observer: Arc<parking_lot::RwLock<Option<Arc<dyn super::dataforts::GreedyObserver>>>>,
    /// Optional blob-transfer engine (FairScheduler transport plan).
    /// Installed by [`Self::serve_blob_transfer`]; drives on-demand
    /// cross-peer blob fetch over reliable scheduled streams.
    #[cfg(feature = "dataforts")]
    blob_transfer_engine:
        Arc<parking_lot::RwLock<Option<Arc<super::dataforts::blob::transfer::BlobTransferEngine>>>>,
    /// Monotonic version counter used when stamping our own
    /// announcements. `CapabilityIndex::index` skips older versions,
    /// so this must move forward across restarts if the caller wants
    /// their announcements accepted.
    capability_version: Arc<AtomicU64>,
    /// This node's subnet. Copy of `config.subnet`, hoisted to the
    /// top level because the publish + subscribe hot paths read it
    /// without going through the config struct.
    local_subnet: SubnetId,
    /// Subnet policy applied to inbound `CapabilityAnnouncement`s.
    /// `None` disables per-peer subnet tracking.
    local_subnet_policy: Option<Arc<SubnetPolicy>>,
    /// Per-peer subnet map. Keys are `node_id`; values are the
    /// subnet derived from each peer's most recent announcement via
    /// `local_subnet_policy`. Unknown peers default to
    /// [`SubnetId::GLOBAL`] at read time.
    peer_subnets: Arc<DashMap<u64, SubnetId>>,
    /// Optional `SubnetGateway` instance for this node — installed
    /// alongside `channel_configs` in [`Self::set_channel_configs`]
    /// when the operator supplies a registry. Shares the registry
    /// `Arc` with the substrate's channel-auth path, so the gateway
    /// sees the same visibility config the publish + subscribe
    /// hot paths consult.
    ///
    /// Powers the `net gateway stats|export|exports` operator
    /// surface. Counter increments (`record_forward` /
    /// `record_drop`) fire from the inline `subnet_visible`
    /// call sites when the gateway is present.
    ///
    /// `None` for nodes that haven't installed a channel-config
    /// registry — those nodes accept every subscribe and skip the
    /// subnet-visibility gate entirely.
    subnet_gateway: Option<Arc<SubnetGateway>>,
    /// Process-level registry of live aggregator groups,
    /// installed lazily so callers that don't run aggregators
    /// pay nothing. Operator CLI verbs
    /// (`net aggregator spawn / ls / scale`) and the Deck
    /// AGGREGATORS panel both read through this. See
    /// [`Self::aggregator_registry`] and
    /// [`Self::set_aggregator_registry`].
    ///
    /// Gated on `cortex` — the registry handle types live in
    /// `behavior::aggregator`, which only compiles when the
    /// cortex-gated `mesh_rpc` + `cortex::rpc` surface is
    /// available.
    #[cfg(feature = "cortex")]
    aggregator_registry: Option<Arc<super::behavior::aggregator::AggregatorRegistry>>,
    /// Per-peer entity-id map. Keys are `node_id`; values are the
    /// 32-byte ed25519 public key carried on the peer's most recent
    /// `CapabilityAnnouncement`. Load-bearing for channel auth —
    /// without it, `require_token` channels can't match a token's
    /// `subject` to the subscribing peer.
    peer_entity_ids: Arc<DashMap<u64, EntityId>>,
    /// Reverse index: publisher's wire `origin_hash` →
    /// publisher's `node_id`. Populated alongside
    /// `peer_entity_ids` at TOFU pin time on a first-write-wins
    /// basis: an established slot is never displaced by a later
    /// claimant, so an adversary grinding a colliding keypair
    /// (~2^32 work for a full-u64 collision) cannot dislodge a
    /// legitimate publisher.
    origin_hash_to_node: Arc<DashMap<u64, u64>>,
    /// Reverse index `session_id → node_id` shared with
    /// `DispatchCtx`. See the matching field doc there
    /// (PERF_AUDIT §2.4).
    session_id_to_node: Arc<DashMap<u64, u64>>,
    /// Shared token cache used by the channel-auth path. When
    /// `None`, `can_publish` / `can_subscribe` fall back to a
    /// fresh empty cache — which means `require_token` channels
    /// always reject. SDK builders wire this up from the caller's
    /// `Identity`.
    token_cache: Option<Arc<TokenCache>>,
    /// Verified subscribe token chains, keyed by `(node_id,
    /// channel_hash)`. Shared with `MeshNode`; see the field of the
    /// same name there.
    subscriber_chains: Arc<DashMap<(u64, ChannelHash), RetainedChain>>,
    /// This node's own publish credentials, keyed by `channel_hash`.
    /// Installed via [`MeshNode::set_publish_chain`] for channels where
    /// the node's PUBLISH grant was *delegated* (owner → … → this node)
    /// rather than issued directly — the publish path prefers a held
    /// chain here over a single directly-granted token from the
    /// `TokenCache`, so a delegated publisher isn't fail-closed.
    /// Local to the publish path; not threaded into `DispatchCtx`.
    published_chains: Arc<DashMap<ChannelHash, TokenChain>>,
    /// Per-packet authorization fast path. Populated when a
    /// subscribe clears `authorize_subscribe`; consulted on every
    /// publish fan-out via `check_fast`. The bloom filter + verified
    /// cache keep authorization at O(1) without per-packet
    /// signature verification. See
    /// [`docs/CHANNEL_AUTH_GUARD_PLAN.md`](../../../../docs/CHANNEL_AUTH_GUARD_PLAN.md).
    auth_guard: Arc<AuthGuard>,
    /// Per-peer auth-failure tracker. Counts failed
    /// `authorize_subscribe` attempts per `auth_failure_window` and
    /// throttles bursts — peers that exceed
    /// `max_auth_failures_per_window` short-circuit with
    /// `RateLimited` for `auth_throttle_duration` without running
    /// the cap-filter + ed25519 verify path. Successful subscribes
    /// clear the counter for that peer.
    auth_failures: Arc<DashMap<u64, AuthFailureState>>,
    /// Background tasks
    tasks: Arc<tokio::sync::Mutex<Vec<JoinHandle<()>>>>,
    /// Shutdown flag
    shutdown: Arc<AtomicBool>,
    /// Shutdown notifier
    shutdown_notify: Arc<Notify>,
    /// Pending StreamWindow grants awaiting emission, keyed by
    /// `(session_id, stream_id)`. The receive path inserts the
    /// latest `total_consumed` here per accepted packet; the
    /// per-mesh drainer task ([`Self::spawn_stream_grant_drainer_loop`])
    /// pops the map and emits the grants batched per session —
    /// multi-event control frames, one packet per
    /// [`GRANT_EVENTS_PER_PACKET`] chunk (STREAM_ACK_BATCHING B-1/
    /// B-2). Latest-wins overwrite semantics make this safe —
    /// grants are authoritative (each carries the full
    /// `total_consumed`) so a later push subsumes any pending
    /// earlier one for the same stream. T1.1 from
    /// `PERF_AUDIT_2026_05_19_NRPC.md`.
    pending_stream_grants: Arc<parking_lot::Mutex<HashMap<(u64, u64), PendingStreamGrant>>>,
    /// Wakes the drainer task whenever a new pending grant lands.
    /// The drainer also self-wakes on a short interval timer so a
    /// missed notify (e.g. the drainer was already iterating when
    /// the notify fired) still flushes within bounded time.
    pending_stream_grants_notify: Arc<Notify>,
    /// Control-plane emission counters (STREAM_ACK_BATCHING B-4):
    /// batched grant/NACK/reset packet+event counts + reliability
    /// retransmit sends. Shared with the drainer, the retransmit
    /// loop, and the dispatch context.
    control_stats: Arc<ControlPlaneStats>,
    /// Per-peer cache for the ack-ranges capability gate (R-5):
    /// `node_id → (supports, checked_at)`. See
    /// [`peer_supports_ack_ranges`].
    ack_ranges_peer_cache: Arc<DashMap<u64, (bool, Instant)>>,
    /// Whether the node has been started
    started: AtomicBool,
    /// Weak self-reference, set by [`Self::start_arc`] when the node is
    /// driven through an `Arc`. The capability re-announce loop upgrades it
    /// each tick to call `announce_capabilities` (the broadcast goes
    /// through `&self` per-peer sends, so it needs an owned `Arc`). Unset
    /// on a bare [`Self::start`] of a non-`Arc` node, in which case the
    /// loop is a no-op. Set-once.
    /// Weak self-handle set by [`Self::start_arc`]. Wrapped in `Arc`
    /// so the `self_weak`-dependent background loops (re-announce
    /// keep-alive, RT-3 change announcer) can hold the *holder* and
    /// re-read it each iteration instead of snapshotting it at spawn.
    /// That makes a bare [`Self::start`] followed by a later
    /// [`Self::start_arc`] work — the loops pick up the weak once it
    /// is set, rather than parking forever (RT-3 review Finding 7).
    self_weak: Arc<std::sync::OnceLock<std::sync::Weak<MeshNode>>>,
    /// Number of `accept()` calls currently awaiting
    /// `handshake_responder`. A simple `started.load(Acquire)`
    /// guard at `accept` entry is a TOCTOU — `start()` could fire
    /// between the check and the `handshake_responder` poll, after
    /// which the dispatcher would race the responder for inbound
    /// msg1 packets and silently swallow them. The counter closes
    /// the race: `accept()` increments on entry, decrements on
    /// exit, and `start()` refuses while any `accept()` is in
    /// flight.
    accept_in_flight: std::sync::atomic::AtomicUsize,
}

impl MeshNode {
    /// Get the Noise static public key (for peers to connect to this node).
    pub fn public_key(&self) -> &[u8; 32] {
        &self.static_keypair.public
    }

    /// Whether [`Self::shutdown`] has been invoked on this node.
    ///
    /// Exposed for tests and for FFI callers that want to verify a
    /// shutdown actually landed (rather than being a silent no-op
    /// because extra `Arc` references were outstanding, as an earlier
    /// `net_mesh_shutdown` variant did).
    pub fn is_shutdown(&self) -> bool {
        self.shutdown.load(Ordering::Acquire)
    }

    /// Create a new mesh node.
    ///
    /// Binds a UDP socket but does not connect to any peers yet.
    /// Call `connect()` to establish sessions with peers, then
    /// `start()` to begin the receive loop.
    pub async fn new(
        identity: EntityKeypair,
        config: MeshNodeConfig,
    ) -> Result<Self, AdapterError> {
        let node_id = identity.node_id();
        let static_keypair = StaticKeypair::generate();

        let socket = NetSocket::with_config(config.bind_addr, config.socket_buffers)
            .await
            .map_err(|e| AdapterError::Connection(format!("bind failed: {}", e)))?;
        let socket = Arc::new(socket);

        let router_config = RouterConfig {
            local_id: node_id,
            // Router binds to an ephemeral port for its send loop. It uses
            // this socket only for forwarding packets — the main socket
            // handles all receives.
            bind_addr: SocketAddr::from(([127, 0, 0, 1], 0)),
            max_queue_depth: config.max_queue_depth,
            fair_quantum: config.fair_quantum,
            ..Default::default()
        };
        let router = NetRouter::new(router_config)
            .await
            .map_err(|e| AdapterError::Connection(format!("router bind failed: {}", e)))?;

        let router = Arc::new(router);

        // Configure route staleness. Routes learned from pingwaves age
        // out if a fresh pingwave hasn't refreshed them in this window;
        // direct routes are refreshed by the heartbeat loop, so they
        // stay fresh as long as the session is alive.
        router
            .routing_table()
            .set_max_route_age(config.session_timeout.saturating_mul(3));

        let peer_addrs: Arc<DashMap<u64, SocketAddr>> = Arc::new(DashMap::new());

        // Hoist `peers` and `addr_to_node` out of the struct literal so
        // the failure-detector `on_failure` callback below can evict
        // dead peers from them. A previous implementation removed the
        // failed peer from the reroute policy, roster, subnet map,
        // entity-id map, and capability index — but left the PeerInfo
        // (including its session) in `peers` indefinitely. Subsequent
        // `send_to_peer` calls would then route through a dead session
        // and silently drop packets via UDP until an application-layer
        // timeout fired.
        let peers: Arc<DashMap<u64, PeerInfo>> = Arc::new(DashMap::new());
        let addr_to_node: Arc<DashMap<SocketAddr, u64>> = Arc::new(DashMap::new());

        // Create proximity graph for topology awareness.
        //
        // Peers are seeded into the graph via `node_id_to_graph_id(peer_node_id)`
        // (see `connect`/`accept`). The local node must use the *same*
        // encoding or path lookups between local and peers would miss —
        // `entity_id().as_bytes()` would put this node under a different
        // key than what peers see for it.
        let graph_node_id = node_id_to_graph_id(node_id);
        let proximity_graph = Arc::new(ProximityGraph::new(
            graph_node_id,
            ProximityConfig::default(),
        ));

        // Create reroute policy with proximity graph for topology-aware alternates
        let reroute_policy = Arc::new(
            ReroutePolicy::new(router.routing_table().clone(), peer_addrs.clone())
                .with_proximity_graph(proximity_graph.clone()),
        );

        // Subscriber roster for channel fan-out; also wired into the
        // failure-detector `on_failure` callback so that a peer going
        // Failed is removed from every channel it was subscribed to.
        let roster: Arc<SubscriberRoster> = Arc::new(SubscriberRoster::new());

        // Peer-subnet map (Stage D). Populated when inbound
        // `SUBPROTOCOL_CAPABILITY_ANN` packets arrive and the local
        // `SubnetPolicy` derives a subnet for the sender. Created
        // here so the failure callback can evict stale entries on
        // session loss — otherwise reconnects would silently reuse
        // the old subnet until the next announcement arrived.
        let peer_subnets: Arc<DashMap<u64, SubnetId>> = Arc::new(DashMap::new());
        // Peer entity-id map (Stage E). Populated from each inbound
        // `CapabilityAnnouncement`. Evicted alongside `peer_subnets`
        // on session failure so a reconnect doesn't silently reuse
        // the old identity.
        let peer_entity_ids: Arc<DashMap<u64, EntityId>> = Arc::new(DashMap::new());
        // Reverse index keyed on the publisher's wire `origin_hash`.
        // Populated alongside `peer_entity_ids` at TOFU pin time;
        // cleared by the failure-detector callback below.
        let origin_hash_to_node: Arc<DashMap<u64, u64>> = Arc::new(DashMap::new());

        // PERF_AUDIT §2.4: reverse index `session_id → node_id`.
        // Hoisted so the failure-detector callback can clear the
        // dead peer's entry alongside the other peer-keyed maps;
        // populated by every peer insert site (connect / accept /
        // routed-msg1 dispatch) and removed by every peer eviction
        // (sweep loop). Lets the routed-local dispatch path resolve
        // a packet's `session_id` to its peer in O(1) rather than
        // scanning all peers per inbound data packet.
        let session_id_to_node: Arc<DashMap<u64, u64>> = Arc::new(DashMap::new());

        // Capability fold — hoisted out of the struct literal so
        // the failure-detector `on_failure` callback can hold a
        // clone. Without this eviction, a failed peer's advertised
        // reflex would linger in the fold and the rendezvous
        // coordinator could hand it to a PunchRequest initiator
        // even though the peer is known dead (TEST_COVERAGE_PLAN
        // §P1-5 / TRANSPORT-adjacent bug: three-way agreement
        // between the failure detector, the routing table, and
        // capability state on peer-death).
        //
        // The fold is registered in a per-node FoldRegistry that
        // we install as the channel router for SUBPROTOCOL_FOLD.
        // Test code that wants to override this can still call
        // set_fold_router(Some(other)) — the override replaces
        // the default registry whole.
        let capability_fold: Arc<
            super::behavior::fold::Fold<super::behavior::fold::CapabilityFold>,
        > = Arc::new(super::behavior::fold::Fold::new());
        // Per PERF_AUDIT §4.1: generation-keyed LRU snapshot of the
        // parsed capability set per node. Sized for typical mesh
        // sizes; tunable later if operator load demands it.
        #[cfg(feature = "dataforts")]
        let capability_set_cache =
            Arc::new(super::behavior::fold::capability_bridge::CapabilitySetCache::new());
        let reservation_fold: Arc<
            super::behavior::fold::Fold<super::behavior::fold::ReservationFold>,
        > = Arc::new(super::behavior::fold::Fold::new());
        let island_fold: Arc<
            super::behavior::fold::Fold<super::behavior::fold::IslandTopologyFold>,
        > = Arc::new(super::behavior::fold::Fold::new());
        let fold_registry = Arc::new(super::behavior::fold::FoldRegistry::new());
        fold_registry.register(capability_fold.clone());
        fold_registry.register(reservation_fold.clone());
        fold_registry.register(island_fold.clone());
        let fold_router: Arc<
            parking_lot::RwLock<Option<Arc<dyn super::behavior::fold::FoldChannelRouter>>>,
        > = Arc::new(parking_lot::RwLock::new(Some(
            fold_registry.clone() as Arc<dyn super::behavior::fold::FoldChannelRouter>
        )));

        // Wire failure detector with reroute callbacks + roster eviction.
        //
        // Note: the `peers` / `addr_to_node` / `peer_addrs` maps are
        // *not* evicted here. Keeping the session entry lets a
        // transient-partition recovery work — once `b`'s heartbeats
        // resume, the packet-dispatch path matches them against the
        // retained session_id, calls `failure_detector.heartbeat`,
        // and the detector's `on_recovery` callback undoes the
        // reroute. Permanent failures are swept separately by the
        // heartbeat loop (see `spawn_heartbeat` — once a peer has
        // been `Failed` for longer than the cleanup window and has
        // not produced any traffic, the loop drops the entry from
        // `peers` / `addr_to_node` / `peer_addrs`).
        let rp_failure = reroute_policy.clone();
        let rp_recovery = reroute_policy.clone();
        let roster_failure = roster.clone();
        let peer_subnets_failure = peer_subnets.clone();
        let peer_entity_ids_failure = peer_entity_ids.clone();
        let origin_hash_to_node_failure = origin_hash_to_node.clone();
        let capability_fold_failure = capability_fold.clone();
        // Created here (not in the struct literal) so the failure
        // callback can drop a dead peer's retained subscribe chains —
        // otherwise the entries leak until an explicit unsubscribe that
        // a failed peer never sends, and the sweep can't reclaim them
        // (it only visits peers still in `peer_entity_ids`, which the
        // callback below clears).
        let subscriber_chains: Arc<DashMap<(u64, ChannelHash), RetainedChain>> =
            Arc::new(DashMap::new());
        let subscriber_chains_failure = subscriber_chains.clone();
        // RT-4: event-pingwave gate + the clones the `on_recovery`
        // closure captures (it runs before `Self` exists, so it
        // can't call `emit_event_pingwave`).
        let partition_filter: PartitionFilter = Arc::new(dashmap::DashSet::new());
        let event_pingwave_gate: Arc<parking_lot::Mutex<EventPingwaveGate>> =
            Arc::new(parking_lot::Mutex::new(EventPingwaveGate::default()));
        let event_pingwave_min_gap = config.event_pingwave_min_gap;
        let event_pingwave_gate_recovery = event_pingwave_gate.clone();
        let proximity_graph_recovery = proximity_graph.clone();
        let socket_recovery = socket.clone();
        let peers_recovery = peers.clone();
        let partition_filter_recovery = partition_filter.clone();
        // RT-5: route-withdrawal state + the clones the `on_failure`
        // closure captures.
        let route_withdraw_seq: Arc<AtomicU64> = Arc::new(AtomicU64::new(0));
        let route_withdraw_damper: Arc<DashMap<(u64, Option<u64>), std::time::Instant>> =
            Arc::new(DashMap::new());
        let enable_route_withdraw = config.enable_route_withdraw;
        let route_withdraw_seq_failure = route_withdraw_seq.clone();
        let route_withdraw_damper_failure = route_withdraw_damper.clone();
        let socket_failure = socket.clone();
        let peers_failure = peers.clone();
        let partition_filter_failure = partition_filter.clone();
        let proximity_graph_failure = proximity_graph.clone();

        // SI-2a hoists, moved ahead of the failure detector for SI-5
        // (§4.8): a Failed peer is a sensing event, so the detector's
        // callback needs the sensing seams before it is constructed.
        // The struct literal below reuses these bindings. The v1
        // owner-root boundary (plan §4.10): the operator-supplied
        // fleet root, or this node's own entity commitment when the
        // node is its own owner.
        let sensing_local_root = config
            .sensing_owner_root
            .unwrap_or_else(|| sensing::AudienceScopeCommitment::owner_root(identity.entity_id()));
        let sensing_interest_table = Arc::new(parking_lot::Mutex::new(
            sensing::InterestTable::new(config.max_interests_per_peer),
        ));
        // SI-3: the origin role exists only with BOTH the plane
        // enabled and a caller-persisted incarnation (fail-closed,
        // see the `sensing_incarnation` knob docs).
        //
        // Closure item 4: config-normalize the cadence floor —
        // `0 < floor ≤ sensing_interest_ttl`. A zero floor would
        // admit a zero cadence (hot loop); a floor beyond the
        // soft-state lifetime cannot serve a continuity stream.
        // (A zero ttl is operator pathology — every row would
        // expire instantly — so it is left alone rather than
        // "fixed" here.)
        let sensing_cadence_floor = {
            let floor = if config.attestation_cadence_floor.is_zero() {
                sensing::DEFAULT_ATTESTATION_CADENCE_FLOOR
            } else {
                config.attestation_cadence_floor
            };
            if config.sensing_interest_ttl.is_zero() {
                floor
            } else {
                floor.min(config.sensing_interest_ttl)
            }
        };
        let sensing_emitter = Arc::new(parking_lot::Mutex::new(
            match (config.enable_sensing_coalescing, config.sensing_incarnation) {
                (true, Some(incarnation)) => Some(sensing::OriginEmitter::new(
                    node_id,
                    incarnation,
                    sensing_cadence_floor,
                )),
                _ => None,
            },
        ));
        let sensing_observations: Arc<parking_lot::Mutex<SensingObservations>> =
            Arc::new(parking_lot::Mutex::new(SensingObservations::default()));
        let sensing_overlay_changed = Arc::new(tokio::sync::watch::channel(0u64).0);
        #[cfg(feature = "redex")]
        let sensing_leader: Arc<parking_lot::Mutex<Option<sensing::SensingLeader>>> =
            Arc::new(parking_lot::Mutex::new(None));
        let sensing_table_failure = sensing_interest_table.clone();
        let sensing_observations_failure = sensing_observations.clone();
        let sensing_overlay_failure = sensing_overlay_changed.clone();
        let sensing_emitter_failure = sensing_emitter.clone();
        #[cfg(feature = "redex")]
        let sensing_leader_failure = sensing_leader.clone();
        let sensing_router_failure = router.clone();
        let sensing_addr_to_node_failure = addr_to_node.clone();
        let enable_sensing_failure = config.enable_sensing_coalescing;
        let sensing_overlay_recovery = sensing_overlay_changed.clone();
        let enable_sensing_recovery = config.enable_sensing_coalescing;
        #[cfg(feature = "redex")]
        let sensing_local_root_failure = sensing_local_root;
        #[cfg(feature = "redex")]
        let sensing_interest_ttl_failure = config.sensing_interest_ttl;
        let local_node_id_failure = node_id;

        // Direct-path upgrade throttle cache (Stage 3) — created here
        // (not in the struct literal) so the failure callback can drop
        // a dead peer's entry. Without that drop the cache grows
        // without bound under peer churn, and a peer that regresses
        // direct→relay and reconnects under the same node_id stays
        // pinned to the relay by a stale terminal `done` from its
        // previous session. Same rationale as `capability_fold` /
        // `subscriber_chains` above.
        #[cfg(feature = "nat-traversal")]
        let upgrade_cache: Arc<DashMap<u64, UpgradeCacheEntry>> = Arc::new(DashMap::new());
        #[cfg(feature = "nat-traversal")]
        let upgrade_cache_failure = upgrade_cache.clone();
        let failure_detector = FailureDetector::with_config(FailureDetectorConfig {
            timeout: config.session_timeout,
            miss_threshold: 3,
            suspicion_threshold: 2,
            cleanup_interval: Duration::from_secs(60),
        })
        .on_failure(move |node_id| {
            // SI-5 (§4.8): a Failed peer is a sensing event on BOTH
            // sides — run BEFORE the reroute policy below mutates
            // route state, so "next_hop(P) went through the failed
            // peer" is judged against the routes the streams were
            // actually riding.
            if enable_sensing_failure {
                let now = Instant::now();
                // As PROVIDER — direct, or multi-hop through the
                // failed peer: its observations expire (path
                // failure); the local aggregate recomputes through
                // the overlay signal; re-registration rides the
                // ttl/2 refresh over whatever route gets promoted.
                let failed_addr = peers_failure.get(&node_id).map(|p| p.value().addr);
                let providers: std::collections::HashSet<u64> = {
                    let observations = sensing_observations_failure.lock();
                    observations
                        .upstream
                        .keys()
                        .chain(observations.consumer_cells.keys())
                        .map(|key| key.provider)
                        .collect()
                };
                #[cfg(feature = "redex")]
                let providers = {
                    let mut providers = providers;
                    if let Some(leader) = sensing_leader_failure.lock().as_ref() {
                        providers.extend(leader.relay.branch_providers());
                    }
                    providers
                };
                for provider in providers {
                    let through_failed = provider == node_id
                        || match sensing_router_failure.routing_table().lookup(provider) {
                            Some(next_hop) => failed_addr == Some(next_hop),
                            // No route AND no live, genuinely DIRECT
                            // session: reachability is simply gone
                            // (the route age-out can beat the
                            // failure edge — same verdict). SI-5
                            // review P1: a relayed PeerInfo is NOT a
                            // direct session — the reverse mapping
                            // decides. (No detector handle inside
                            // its own callback; the failed peer
                            // itself is the identity arm above.)
                            None => !sensing_live_direct_session(
                                &peers_failure,
                                &sensing_addr_to_node_failure,
                                None,
                                provider,
                            ),
                        };
                    if !through_failed {
                        continue;
                    }
                    disrupt_sensing_provider(
                        &sensing_table_failure,
                        &sensing_observations_failure,
                        &sensing_overlay_failure,
                        provider,
                        sensing::DisruptReason::PathFailed,
                    );
                    #[cfg(feature = "redex")]
                    if let Some(leader) = sensing_leader_failure.lock().as_mut() {
                        leader
                            .relay
                            .disrupt_provider(provider, sensing::DisruptReason::PathFailed);
                    }
                }
                // As DOWNSTREAM: its rows drop, aggregates
                // recompute, dead branches deregister upstream, and
                // local emission streams retire with their last
                // interest — event-driven, never the ttl sweep.
                remove_sensing_downstream(
                    &sensing_table_failure,
                    &sensing_observations_failure,
                    &sensing_emitter_failure,
                    &socket_failure,
                    &peers_failure,
                    &sensing_addr_to_node_failure,
                    &sensing_router_failure,
                    &partition_filter_failure,
                    local_node_id_failure,
                    node_id,
                    now,
                );
                #[cfg(feature = "redex")]
                remove_sensing_leader_consumer(
                    &sensing_leader_failure,
                    &sensing_table_failure,
                    &sensing_observations_failure,
                    &sensing_emitter_failure,
                    &socket_failure,
                    &peers_failure,
                    &sensing_addr_to_node_failure,
                    &sensing_router_failure,
                    &partition_filter_failure,
                    local_node_id_failure,
                    sensing_local_root_failure,
                    sensing_interest_ttl_failure,
                    node_id,
                    now,
                );
                // SI-6 review P1: a failure edge is scheduler-
                // relevant even when no projection moved — bump the
                // unified generation unconditionally.
                sensing_overlay_failure.send_modify(|generation| {
                    *generation = generation.wrapping_add(1);
                });
            }
            rp_failure.on_failure(node_id);
            let removed = roster_failure.remove_peer(node_id);
            if !removed.is_empty() {
                tracing::debug!(
                    node_id = format!("{:#x}", node_id),
                    channels = removed.len(),
                    "roster: evicted failed peer from channels"
                );
            }
            peer_subnets_failure.remove(&node_id);
            // Pull `entity_id` BEFORE removing it so we know which
            // origin_hash slot to demote / drop. A node disappearing
            // releases its claim on the wire hash.
            let removed_entity_id = peer_entity_ids_failure.remove(&node_id).map(|(_, eid)| eid);
            if let Some(eid) = removed_entity_id {
                // Same key the inbound announcement handler uses —
                // the full 64-bit `EntityId::origin_hash()` since the
                // `WIRE_ORIGIN_HASH_64BIT` cutover. Slot is
                // `Option<NodeId>`; drop iff the evicted node is
                // the current claimant (a separate publisher
                // grinding the same hash would not displace it on
                // insert, so it's not in the slot here).
                let origin_hash = eid.origin_hash();
                origin_hash_to_node_failure
                    .remove_if(&origin_hash, |_, claimant| *claimant == node_id);
            }
            // Drop the dead peer's cached capabilities + reflex.
            // Without this, a rendezvous coordinator could still
            // hand a PunchRequest initiator the failed peer's
            // (stale) reflex, leading to wasted punch attempts
            // against a dead address. The three maps above
            // (routes, subnets, entity-ids) are all cleared on
            // failure; the capability fold is now consistent
            // with them.
            capability_fold_failure.evict_node(node_id, "failure-detector");
            // Drop any retained subscribe token chains for this peer.
            // The sweep can no longer reach them (it iterates
            // `peer_entity_ids`, just cleared above), and a failed peer
            // never sends the unsubscribe that would otherwise remove
            // them — so without this they leak for the node's lifetime,
            // and a reused `node_id` could re-validate a stale chain.
            subscriber_chains_failure.retain(|(nid, _), _| *nid != node_id);
            // RT-5: tell the mesh this peer is unreachable via us —
            // receivers drop their `(node_id, via=us)` routes within
            // one flood instead of waiting for the 3× session_timeout
            // age-out sweep.
            //
            // Pessimistically UNCONDITIONAL on an authoritative
            // direct-peer failure (RT-5 addendum review P1). The prior
            // gate suppressed the flood whenever the proximity graph
            // still offered a topological alternate to the failed peer.
            // But at the instant of detection that alternate can be a
            // stale SOFT-STATE path that has not yet aged out: in a
            // fully-connected triangle A/B/C, when A dies both B and C
            // still hold the pingwave-derived indirect edges B→C→A and
            // C→B→A, so both suppressed their withdrawal and could route
            // B→C and C→B on the same dead snapshot — nobody told
            // upstream that A was gone until graph/route expiry. A
            // pre-failure graph snapshot is not evidence the failed
            // destination is live. So we withdraw on the failure, remove
            // the now-dead direct edge, and let a subsequent FRESH
            // pingwave re-advertise reachability if the peer really
            // remains reachable through another path — `rp_failure` still
            // reroutes us locally in the meantime.
            if enable_route_withdraw {
                spawn_route_withdrawal_flood(
                    &route_withdraw_seq_failure,
                    &route_withdraw_damper_failure,
                    &socket_failure,
                    &peers_failure,
                    &partition_filter_failure,
                    node_id,
                    None,
                );
            }
            // Remove our now-dead direct edge to the failed peer so a
            // stale `(self → node_id)` edge can't keep masquerading as a
            // live hop in later `path_to` queries; a real fresh pingwave
            // re-inserts it if the peer comes back through some path.
            proximity_graph_failure.remove_edge(
                node_id_to_graph_id(local_node_id_failure),
                node_id_to_graph_id(node_id),
            );
            // Drop the dead peer's direct-path upgrade throttle entry,
            // in lockstep with the maps above (see the `upgrade_cache`
            // creation comment).
            #[cfg(feature = "nat-traversal")]
            upgrade_cache_failure.remove(&node_id);
        })
        .on_recovery(move |node_id| {
            rp_recovery.on_recovery(node_id);
            // RT-4: a healed partition is a topology change — tell
            // the mesh at flood speed instead of waiting for the
            // next heartbeat tick. The recovered peer's OWN
            // pingwaves resume on its heartbeats; this one refreshes
            // routes THROUGH us for third parties.
            spawn_event_pingwave(
                &event_pingwave_gate_recovery,
                event_pingwave_min_gap,
                &proximity_graph_recovery,
                &socket_recovery,
                &peers_recovery,
                &partition_filter_recovery,
                // Recovery: no session-open race, so no second round.
                false,
            );
            // SI-6 review P1: a recovery edge is scheduler-relevant
            // (routes and pins return) — bump the unified
            // scheduler-input generation.
            if enable_sensing_recovery {
                sensing_overlay_recovery.send_modify(|generation| {
                    *generation = generation.wrapping_add(1);
                });
            }
        });

        let pending_handshakes: Arc<DashMap<u64, PendingHandshake>> = Arc::new(DashMap::new());
        let pending_direct_initiators: Arc<DashMap<SocketAddr, oneshot::Sender<Bytes>>> =
            Arc::new(DashMap::new());

        // Hoist the subnet knobs before `config` is moved into the
        // struct literal; the publish + subscribe paths read these
        // without going back through `config`.
        let local_subnet = config.subnet;
        let local_subnet_policy = config.subnet_policy.clone();
        // Pre-apply the reflex override so the node starts in
        // `Open` + `reflex_addr = Some(override)` state before
        // the first capability announcement leaves the box. Skips
        // the classifier sweep — operators with manually-forwarded
        // ports (or stage-4 port mapping) don't need multi-peer
        // probing to discover what they already know.
        #[cfg(feature = "nat-traversal")]
        let initial_reflex_override = config.reflex_override;

        // Local-origin capability change signal (RT-2). One shared
        // sender, injected into every local registry whose mutations
        // change what `announce_capabilities` would emit — the
        // registries fire it internally so a mutation path can't
        // forget to. Inbound peer announcements never touch these
        // registries, so the signal is echo-safe by construction.
        let local_caps_changed = Arc::new(tokio::sync::watch::channel(0u64).0);

        Ok(Self {
            identity: Arc::new(identity),
            static_keypair,
            node_id,
            config,
            socket,
            peers,
            addr_to_node,
            router,
            failure_detector: Arc::new(failure_detector),
            inbound: Arc::new(DashMap::new()),
            #[cfg(feature = "cortex")]
            rpc_inbound_dispatchers: Arc::new(DashMap::new()),
            #[cfg(feature = "cortex")]
            rpc_client_pending: Arc::new(crate::adapter::net::cortex::RpcClientPending::new()),
            #[cfg(feature = "cortex")]
            rpc_round_robin_cursor: Arc::new(std::sync::atomic::AtomicU64::new(0)),
            #[cfg(feature = "cortex")]
            rpc_reply_subscriptions: Arc::new(dashmap::DashMap::new()),
            #[cfg(feature = "cortex")]
            rpc_local_services: Arc::new(LocalServiceRegistry::new(local_caps_changed.clone())),
            #[cfg(feature = "tool")]
            tool_registry: Arc::new(
                crate::adapter::net::cortex::tool::ToolMetadataRegistry::with_change_signal(
                    local_caps_changed.clone(),
                ),
            ),
            local_caps_changed,
            #[cfg(feature = "cortex")]
            rpc_metrics: Arc::new(crate::adapter::net::mesh_rpc_metrics::RpcMetricsRegistry::new()),
            #[cfg(feature = "cortex")]
            rpc_route_cache: Arc::new(DashMap::new()),
            #[cfg(feature = "cortex")]
            rpc_observer: Arc::new(ArcSwapOption::empty()),
            #[cfg(feature = "cortex")]
            cancel_registry: Arc::new(crate::adapter::net::cancel_registry::CancelRegistry::new()),
            migration_handler: Arc::new(ArcSwapOption::empty()),
            pending_handshakes,
            pending_direct_initiators,
            proximity_graph,
            reroute_policy,
            peer_addrs,
            partition_filter,
            event_pingwave_gate,
            route_withdraw_seq,
            route_withdraw_damper,
            route_withdraw_gate: Arc::new(WithdrawalSeqGate::new()),
            route_withdraw_cascades_inflight: Arc::new(AtomicUsize::new(0)),
            sensing_interest_table,
            sensing_counters: Arc::new(sensing::SensingCounters::default()),
            sensing_over_cap: Arc::new(AtomicU64::new(0)),
            sensing_local_root,
            sensing_upstream_damper: Arc::new(DashMap::new()),
            #[cfg(feature = "redex")]
            sensing_leader,
            #[cfg(feature = "redex")]
            sensing_fold_coalescer: Arc::new(DashMap::new()),
            sensing_emitter,
            sensing_emitter_notify: Arc::new(tokio::sync::Notify::new()),
            sensing_evaluators: Arc::new(DashMap::new()),
            sensing_observer_gate: Arc::new(parking_lot::Mutex::new(
                sensing::IncarnationSeqGate::new(),
            )),
            sensing_overlay_changed,
            sensing_capability_interests: Arc::new(parking_lot::Mutex::new(HashMap::new())),
            sensing_observations,
            roster,
            channel_configs: None,
            pending_membership_acks: Arc::new(DashMap::new()),
            #[cfg(feature = "nat-traversal")]
            pending_reflex_probes: Arc::new(DashMap::new()),
            #[cfg(feature = "nat-traversal")]
            pending_punch_introduces: Arc::new(DashMap::new()),
            #[cfg(feature = "nat-traversal")]
            pending_punch_acks: Arc::new(DashMap::new()),
            #[cfg(feature = "nat-traversal")]
            next_waiter_gen: Arc::new(std::sync::atomic::AtomicU64::new(1)),
            #[cfg(feature = "nat-traversal")]
            next_punch_id: Arc::new(std::sync::atomic::AtomicU32::new(1)),
            #[cfg(feature = "nat-traversal")]
            nat_classifying: std::sync::atomic::AtomicBool::new(false),
            #[cfg(feature = "nat-traversal")]
            punch_observers: Arc::new(DashMap::new()),
            #[cfg(feature = "nat-traversal")]
            rendezvous_budgets: Arc::new(RendezvousBudgets::default()),
            #[cfg(feature = "nat-traversal")]
            upgrade_cache,
            #[cfg(feature = "nat-traversal")]
            nat_class: Arc::new(std::sync::atomic::AtomicU8::new(
                if initial_reflex_override.is_some() {
                    super::traversal::classify::NatClass::Open.as_u8()
                } else {
                    super::traversal::classify::NatClass::Unknown.as_u8()
                },
            )),
            #[cfg(feature = "nat-traversal")]
            reflex_addr: Arc::new(match initial_reflex_override {
                Some(addr) => ArcSwapOption::from_pointee(addr),
                None => ArcSwapOption::empty(),
            }),
            #[cfg(feature = "nat-traversal")]
            reflex_override_active: Arc::new(std::sync::atomic::AtomicBool::new(
                initial_reflex_override.is_some(),
            )),
            #[cfg(feature = "nat-traversal")]
            traversal_publish_mu: Arc::new(parking_lot::Mutex::new(())),
            #[cfg(feature = "nat-traversal")]
            traversal_config: super::traversal::TraversalConfig::default(),
            #[cfg(feature = "nat-traversal")]
            traversal_stats: Arc::new(super::traversal::TraversalStats::new()),
            capability_fold,
            #[cfg(feature = "dataforts")]
            capability_set_cache,
            reservation_fold,
            island_fold,
            liveness_down: Arc::new(arc_swap::ArcSwap::from_pointee(
                std::collections::HashSet::new(),
            )),
            seen_announcements: Arc::new(DashMap::new()),
            announce_mu: parking_lot::Mutex::new(()),
            announce_gate: Arc::new(parking_lot::Mutex::new(AnnounceGate {
                last_broadcast_at: None,
                deferred_scheduled: false,
                deferral_generation: 0,
            })),
            local_announcement: Arc::new(ArcSwapOption::empty()),
            user_caps: Arc::new(parking_lot::RwLock::new(None)),
            #[cfg(feature = "redex")]
            replication_inbound_router: Arc::new(parking_lot::RwLock::new(None)),
            #[cfg(feature = "meshdb")]
            meshdb_inbound_router: Arc::new(parking_lot::RwLock::new(None)),
            fold_router,
            fold_generations: Arc::new(DashMap::new()),
            #[cfg(feature = "dataforts")]
            greedy_observer: Arc::new(parking_lot::RwLock::new(None)),
            #[cfg(feature = "dataforts")]
            blob_transfer_engine: Arc::new(parking_lot::RwLock::new(None)),
            capability_version: Arc::new(AtomicU64::new(0)),
            local_subnet,
            local_subnet_policy,
            peer_subnets,
            // Gateway is installed lazily by `set_channel_configs`;
            // a node without an installed registry has no gateway
            // and skips the visibility gate entirely.
            subnet_gateway: None,
            // Aggregator registry is installed lazily via
            // `set_aggregator_registry`; nodes that never run an
            // aggregator never allocate the HashMap. Cortex-gated
            // because the `AggregatorRegistry` type rides the
            // cortex-only `mesh_rpc` / `cortex::rpc` surface.
            #[cfg(feature = "cortex")]
            aggregator_registry: None,
            peer_entity_ids,
            origin_hash_to_node,
            session_id_to_node,
            token_cache: None,
            subscriber_chains,
            published_chains: Arc::new(DashMap::new()),
            auth_guard: Arc::new(AuthGuard::new()),
            auth_failures: Arc::new(DashMap::new()),
            tasks: Arc::new(tokio::sync::Mutex::new(Vec::new())),
            shutdown: Arc::new(AtomicBool::new(false)),
            shutdown_notify: Arc::new(Notify::new()),
            pending_stream_grants: Arc::new(parking_lot::Mutex::new(HashMap::new())),
            pending_stream_grants_notify: Arc::new(Notify::new()),
            control_stats: Arc::new(ControlPlaneStats::default()),
            ack_ranges_peer_cache: Arc::new(DashMap::new()),
            started: AtomicBool::new(false),
            self_weak: Arc::new(std::sync::OnceLock::new()),
            accept_in_flight: std::sync::atomic::AtomicUsize::new(0),
        })
    }

    /// Get this node's ID.
    pub fn node_id(&self) -> u64 {
        self.node_id
    }

    /// This node's `origin_hash` — the 8-byte BLAKE2s of its entity public
    /// key, and the value the bus stamps on this node's outbound RPCs. A
    /// remote handler sees it as `RpcContext::caller_origin`, so it is the
    /// stable identifier to admit in a caller-scoped authorization check
    /// (distinct from [`node_id`](Self::node_id)).
    pub fn origin_hash(&self) -> u64 {
        self.identity.entity_id().origin_hash()
    }

    /// The per-packet authorization fast path. Writes land here on
    /// successful subscribe (via `AuthGuard::allow_channel`) and
    /// reads happen on every publish fan-out. Exposed primarily for
    /// tests + operator observability; production code should reach
    /// for `register_channel` / `subscribe_channel` instead.
    pub fn auth_guard(&self) -> &Arc<AuthGuard> {
        &self.auth_guard
    }

    /// The shared `TokenCache` installed on this node, if any. Only
    /// populated when a caller registered one via
    /// [`Self::set_token_cache`]. Exposed for tests that need to
    /// assert the cache is *not* populated as a side effect of a
    /// rejected subscribe.
    pub fn token_cache(&self) -> Option<&Arc<TokenCache>> {
        self.token_cache.as_ref()
    }

    /// Number of retained subscribe token chains. A verified chain is
    /// stored here only after a subscribe passes the root-anchored
    /// gate; the sweep and publish re-check consult it. Exposed for
    /// tests that assert a rejected subscribe retains nothing.
    pub fn subscriber_chain_count(&self) -> usize {
        self.subscriber_chains.len()
    }

    /// Get this node's ed25519 entity id (derived from the
    /// keypair handed to `MeshNode::new`). 32 bytes. Used by
    /// `CapabilityAnnouncement` + channel-auth path.
    pub fn entity_id(&self) -> &EntityId {
        self.identity.entity_id()
    }

    /// This node's ed25519 identity keypair — the one handed to
    /// `MeshNode::new`. In-process surfaces that must sign *as the
    /// node* (e.g. the payments caller flow binding quotes and
    /// invocation proofs to the node identity) borrow it here; it
    /// never crosses a language boundary. Same exposure precedent as
    /// `compute::host` and `behavior::deck`.
    pub fn entity_keypair(&self) -> &EntityKeypair {
        &self.identity
    }

    /// Look up a peer's pinned `entity_id`, if the TOFU binding
    /// has been established. Returns `None` before we've received
    /// a signature-verified `CapabilityAnnouncement` from the peer.
    /// Exposed primarily for tests + operator observability; the
    /// channel-auth subscribe gate consults this map internally.
    pub fn peer_entity_id(&self, node_id: u64) -> Option<EntityId> {
        self.peer_entity_ids
            .get(&node_id)
            .map(|e| e.value().clone())
    }

    /// The peer's socket address, if we have an active session
    /// with them. Used by the migration subprotocol to route
    /// orchestrator-originated messages (e.g. `TakeSnapshot`) to
    /// the source node by its `node_id`.
    pub fn peer_addr(&self, node_id: u64) -> Option<SocketAddr> {
        self.peers.get(&node_id).map(|e| e.value().addr)
    }

    // ── SI-2a: capability-sensing interest plane ──────────────────
    // SENSING_INTEREST_COALESCING_PLAN v4.3 — the first slice wiring
    // the sensing substrate (`behavior::sensing`) onto live MeshNode
    // dispatch. Everything below is inert while
    // `enable_sensing_coalescing` is off (the plane ships dark).

    /// Register this node's OWN interest in one resolved provider
    /// branch (SI-2a; the `LOCAL` row of plan §4.3) and propagate
    /// the coalesced aggregate upstream toward `next_hop(provider)`.
    ///
    /// Candidate RESOLUTION (capability selector → provider set) is
    /// SI-2b wiring — callers of this slice name the provider branch
    /// explicitly. The spec is validated exactly as a downstream's
    /// registration would be (plan §4.10): an interest whose
    /// audience commitment names a root other than this node's own
    /// sensing root is refused, with the same counter discipline.
    /// `soft_state_ttl` is capped at
    /// [`MeshNodeConfig::sensing_interest_ttl`].
    ///
    /// On any admitted (or refreshed) registration toward a REMOTE
    /// provider, the current coalesced aggregate is (re-)sent
    /// upstream, min-gap damped — an anti-entropy edge on top of the
    /// §4.3 trailing-edge rule, so a caller's retry repairs a lost
    /// frame instead of silently trusting first delivery. Refresh
    /// cadence (ttl/2 re-registration) is the caller's loop in this
    /// slice.
    ///
    /// Returns the table's own outcome — including
    /// [`sensing::RegisterOutcome::OverCap`] when this node's LOCAL
    /// rows hit `max_interests_per_peer` — or a
    /// [`SensingRegistrationError`] when the plane is disabled or
    /// the spec fails scope validation.
    pub fn register_sensing_interest(
        &self,
        spec: &sensing::InterestSpec,
        provider: u64,
        requested_sample_interval: Duration,
        soft_state_ttl: Duration,
    ) -> Result<sensing::RegisterOutcome, SensingRegistrationError> {
        if !self.config.enable_sensing_coalescing {
            return Err(SensingRegistrationError::Disabled);
        }
        // Closure item 4: `0 < D ≤ sensing_interest_ttl` — the same
        // bound the wire arms enforce.
        if !sensing_interval_in_bounds(requested_sample_interval, self.config.sensing_interest_ttl)
        {
            return Err(SensingRegistrationError::Interval {
                requested: requested_sample_interval,
                max: self.config.sensing_interest_ttl,
            });
        }
        // Round 2, item 2: a zero ttl is dead on arrival.
        if soft_state_ttl.is_zero() {
            return Err(SensingRegistrationError::ZeroTtl);
        }
        // A local registration proves the local root by construction
        // (session == claimed == local); the shared validation path
        // still runs so an audience mismatch is refused exactly like
        // a downstream's would be.
        let proven_root = sensing::validate_subscriber_scope(
            &self.sensing_local_root,
            &self.sensing_local_root,
            &self.sensing_local_root,
            &spec.audience,
            &self.sensing_counters,
        )
        .map_err(SensingRegistrationError::Scope)?;
        let key = sensing::ProviderInterestKey::new(spec.key(), provider);
        let ttl = soft_state_ttl.min(self.config.sensing_interest_ttl);
        let now = Instant::now();
        let (outcome, aggregate) = {
            let mut table = self.sensing_interest_table.lock();
            let outcome = table.register(
                &key,
                sensing::DownstreamId::Local,
                requested_sample_interval,
                ttl,
                proven_root,
                now,
            );
            (outcome, table.aggregate(&key, now))
        };
        if matches!(outcome, sensing::RegisterOutcome::Registered(_)) {
            // SI-4 re-review item 5: a (re-)registration can move
            // both the branch aggregate (this hop's continuity
            // window) and the Local watch's own D (the overlay
            // cell's window) — re-anchor both immediately, never at
            // the next beat.
            let mut observations = self.sensing_observations.lock();
            observations.update_upstream_interval(&key, aggregate);
            observations.update_consumer_interval(&key, requested_sample_interval);
        }
        if matches!(outcome, sensing::RegisterOutcome::Registered(_)) && provider == self.node_id {
            // SI-3: the node registered interest in ITSELF — feed
            // the origin emitter directly (no wire hop). An emitter
            // refusal partitions this hop's rows exactly like the
            // dispatch path, but the refusal answer is the returned
            // outcome — a Local downstream has no wire to ride.
            if let Some(strictest) = aggregate {
                let refusal = {
                    let mut slot = self.sensing_emitter.lock();
                    match slot.as_mut() {
                        // Fail-closed origin role: row stands,
                        // stream stays dark (knob docs).
                        None => None,
                        Some(emitter) => emitter.register(spec, strictest, now).err(),
                    }
                };
                match refusal {
                    None => self.sensing_emitter_notify.notify_one(),
                    Some(sensing::StreamRefusal::AtCapacity) => {
                        // Round 2, item 5: surface capacity honestly
                        // — roll back the just-inserted Local row
                        // and tell the caller; a dark row would
                        // report success for a stream that will
                        // never exist. Retry after capacity frees.
                        let _ = self.sensing_interest_table.lock().deregister(
                            &key.interest.interest_digest,
                            Some(provider),
                            sensing::DownstreamId::Local,
                            now,
                        );
                        return Err(SensingRegistrationError::AtCapacity);
                    }
                    Some(sensing::StreamRefusal::Cadence(refusal)) => {
                        self.sensing_counters
                            .cadence_refusals
                            .fetch_add(1, Ordering::Relaxed);
                        // Closure item 7: snapshot BEFORE the table
                        // mutation the retire decision rests on.
                        let stamp = self
                            .sensing_emitter
                            .lock()
                            .as_ref()
                            .map(|emitter| emitter.stamp());
                        let partition = self.sensing_interest_table.lock().on_refusal(
                            &key,
                            refusal.minimum_supported,
                            now,
                        );
                        {
                            let mut slot = self.sensing_emitter.lock();
                            if let Some(emitter) = slot.as_mut() {
                                match partition.upstream {
                                    sensing::UpstreamAction::Register { strictest } => {
                                        let _ = emitter.register(spec, strictest, now);
                                    }
                                    sensing::UpstreamAction::Deregister => {
                                        if let Some(stamp) = stamp {
                                            emitter.retire_if_stale(
                                                &key.interest.interest_digest,
                                                stamp,
                                            );
                                        }
                                    }
                                    sensing::UpstreamAction::None => {}
                                }
                            }
                        }
                        self.sensing_emitter_notify.notify_one();
                        return Ok(sensing::RegisterOutcome::RefusedByCachedFloor {
                            minimum_supported: refusal.minimum_supported,
                        });
                    }
                }
            }
        } else if matches!(outcome, sensing::RegisterOutcome::Registered(_)) {
            // SI-4 review P1 (Local warm-start): a Local row joining
            // an already-cached relay branch warm-starts exactly
            // like a peer — once, on row creation, always
            // provisional.
            {
                let mut observations = self.sensing_observations.lock();
                let slot_key = (key.clone(), sensing::DownstreamId::Local);
                if !observations.slots.contains_key(&slot_key) {
                    if let Some(cached) = observations.latest.get(&key).cloned() {
                        observations.slots.insert(
                            slot_key,
                            SensingDeliverySlot {
                                last_status: Some(cached.status),
                                last_delivered: Some((cached.origin_incarnation, cached.seq)),
                                next_due: now + requested_sample_interval,
                                pending: false,
                            },
                        );
                        let moved = observations.feed_consumer_cell(
                            &key,
                            &cached,
                            false,
                            requested_sample_interval,
                            self.config.continuity_factor,
                            now,
                        );
                        drop(observations);
                        if moved {
                            self.sensing_overlay_changed.send_modify(|generation| {
                                *generation = generation.wrapping_add(1);
                            });
                        }
                    }
                }
            }
            if let Some(strictest) = aggregate {
                if sensing_upstream_damper_admits(
                    &self.sensing_upstream_damper,
                    provider,
                    *key.interest.interest_digest.as_bytes(),
                    sensing_effective_min_gap(ttl),
                ) {
                    let frame = sensing::SensingInterestFrame::provider_registration(
                        spec, provider, strictest, ttl,
                    );
                    if let Ok(bytes) = sensing::encode_interest_frame(&frame) {
                        spawn_sensing_frame_send(
                            &self.socket,
                            &self.peers,
                            &self.addr_to_node,
                            &self.router,
                            &self.partition_filter,
                            self.node_id,
                            provider,
                            sensing::SUBPROTOCOL_SENSING_INTEREST as u64,
                            sensing::SUBPROTOCOL_SENSING_INTEREST,
                            bytes,
                        );
                    }
                }
            }
        }
        Ok(outcome)
    }

    /// SI-4 review P0: register (or refresh) a PROVIDER-FREE
    /// capability interest (plan §4.1) — the consumer half of the
    /// rendezvous path. Records the digest-level expectation that
    /// makes returning leader fan-outs solicited at this hop
    /// (proofs may arrive for ANY provider the leader resolved —
    /// the consumer never chose one), and sends the
    /// `CapabilityRegistration` frame toward `leader` (min-gap
    /// damped). Soft state: re-call at ttl/2; the sweep expires the
    /// expectation and its consumer cells.
    ///
    /// The leader id is the caller's for now — computing it via the
    /// §4.1 rendezvous requires scope-membership plumbing that
    /// rides a later slice.
    pub fn register_capability_interest(
        &self,
        spec: &sensing::InterestSpec,
        leader: u64,
        requested_sample_interval: Duration,
        soft_state_ttl: Duration,
    ) -> Result<(), SensingRegistrationError> {
        if !self.config.enable_sensing_coalescing {
            return Err(SensingRegistrationError::Disabled);
        }
        if !sensing_interval_in_bounds(requested_sample_interval, self.config.sensing_interest_ttl)
        {
            return Err(SensingRegistrationError::Interval {
                requested: requested_sample_interval,
                max: self.config.sensing_interest_ttl,
            });
        }
        if soft_state_ttl.is_zero() {
            return Err(SensingRegistrationError::ZeroTtl);
        }
        sensing::validate_subscriber_scope(
            &self.sensing_local_root,
            &self.sensing_local_root,
            &self.sensing_local_root,
            &spec.audience,
            &self.sensing_counters,
        )
        .map_err(SensingRegistrationError::Scope)?;
        let ttl = soft_state_ttl.min(self.config.sensing_interest_ttl);
        let key = spec.key();
        {
            let mut interests = self.sensing_capability_interests.lock();
            // SI-4 re-review item 9: the expectation map is bounded
            // by the same amplification cap as the table's
            // per-downstream rows. Existing-key refreshes stay
            // admitted at capacity; only NEW keys are refused —
            // retry after one expires.
            if !interests.contains_key(&key)
                && interests.len() >= self.config.max_interests_per_peer
            {
                return Err(SensingRegistrationError::AtCapacity);
            }
            // SI-4 re-review item 8: the expectation retains the
            // audience it solicits — intake admits only signers
            // whose pinned entity derives this owner root.
            interests.insert(
                key.clone(),
                CapabilityInterestExpectation {
                    requested_sample_interval,
                    expires_at: Instant::now() + ttl,
                    audience: spec.audience,
                },
            );
        }
        // SI-4 re-review item 5: a refreshed expectation can change
        // the consumer's D — every overlay cell under the digest
        // re-anchors immediately, never at the next beat.
        self.sensing_observations
            .lock()
            .update_consumer_intervals(&key, requested_sample_interval);
        if sensing_upstream_damper_admits(
            &self.sensing_upstream_damper,
            leader,
            *key.interest_digest.as_bytes(),
            sensing_effective_min_gap(ttl),
        ) {
            let frame = sensing::SensingInterestFrame::capability_registration(
                spec,
                requested_sample_interval,
                ttl,
                self.node_id,
            );
            if let Ok(bytes) = sensing::encode_interest_frame(&frame) {
                spawn_sensing_frame_send(
                    &self.socket,
                    &self.peers,
                    &self.addr_to_node,
                    &self.router,
                    &self.partition_filter,
                    self.node_id,
                    leader,
                    sensing::SUBPROTOCOL_SENSING_INTEREST as u64,
                    sensing::SUBPROTOCOL_SENSING_INTEREST,
                    bytes,
                );
            }
        }
        Ok(())
    }

    /// SI-3: install (or replace) the [`sensing::ReadinessEvaluator`]
    /// for one capability id (plan §4.4 — one narrow trait per
    /// integration). Implementations should be cheap and
    /// non-blocking (they run on the emission path), but they are
    /// invoked OUTSIDE the emitter lock (closure item 5) — an
    /// evaluator may safely call back into `MeshNode`, including
    /// [`Self::notify_sensing_state_changed`]. Interests targeting
    /// this node for a capability WITHOUT an evaluator stream
    /// `ProviderUnknown { TemporarilyUnevaluable }` — an explicit
    /// "targeted but cannot answer" beats silence.
    ///
    /// Registration is independent of the origin role being active:
    /// evaluators may be installed before `start()` or while the
    /// plane is dark; they take effect whenever emission runs.
    pub fn register_readiness_evaluator(
        &self,
        capability_id: sensing::CapabilityId,
        evaluator: Arc<dyn sensing::ReadinessEvaluator + Send + Sync>,
    ) {
        self.sensing_evaluators.insert(capability_id, evaluator);
    }

    /// SI-3: remove a capability's evaluator. Live streams for it
    /// fall back to `ProviderUnknown { TemporarilyUnevaluable }` at
    /// their next beat. Returns whether one was installed.
    pub fn unregister_readiness_evaluator(&self, capability_id: &sensing::CapabilityId) -> bool {
        self.sensing_evaluators.remove(capability_id).is_some()
    }

    /// SI-3: the integration's status-edge hook (plan §4.4 "status
    /// edges immediate with min-gap"): local state affecting
    /// `capability_id` changed — pull every live stream on that
    /// capability forward to now, min-gapped at the cadence floor,
    /// and wake the emitter loop. A no-op while the origin role is
    /// dark or no stream targets the capability.
    pub fn notify_sensing_state_changed(&self, capability_id: &sensing::CapabilityId) {
        let moved = {
            let mut slot = self.sensing_emitter.lock();
            match slot.as_mut() {
                Some(emitter) => emitter.poke(capability_id, Instant::now()),
                None => false,
            }
        };
        if moved {
            self.sensing_emitter_notify.notify_one();
        }
    }

    /// SI-3: whether the origin role is active — the plane is
    /// enabled AND a persisted incarnation was supplied (fail-closed
    /// otherwise; see [`MeshNodeConfig::sensing_incarnation`]).
    pub fn sensing_origin_active(&self) -> bool {
        self.sensing_emitter.lock().is_some()
    }

    /// SI-3: live emission streams on this origin (tests +
    /// observability).
    pub fn sensing_live_streams(&self) -> usize {
        self.sensing_emitter
            .lock()
            .as_ref()
            .map(|emitter| emitter.live_streams())
            .unwrap_or(0)
    }

    /// SI-3c: the latest ADMITTED attestation this hop holds for one
    /// branch — decoded, solicited, signature-verified against the
    /// origin's pinned entity, and strictly-newer at the §4.6
    /// observer gate. SI-4's relay caches subsume this seam.
    pub fn sensing_latest_attestation(
        &self,
        key: &sensing::ProviderInterestKey,
    ) -> Option<sensing::ReadinessAttestation> {
        self.sensing_observations.lock().latest.get(key).cloned()
    }

    /// SI-3 closure item 6: the latest admitted REFUSAL beat for one
    /// branch — a cadence-request-relative control response, kept
    /// apart from the warm-start observation store so it can never
    /// masquerade as provider-wide readiness.
    pub fn sensing_latest_refusal(
        &self,
        key: &sensing::ProviderInterestKey,
    ) -> Option<sensing::ReadinessAttestation> {
        self.sensing_observations
            .lock()
            .refusals
            .get(key)
            .map(|(attestation, _)| attestation.clone())
    }

    /// SI-3c: how many branches hold an admitted observation (tests
    /// and observability). Reclaims with the interest table, so a
    /// drained table drains this too (closure item 6).
    pub fn sensing_observation_count(&self) -> usize {
        self.sensing_observations.lock().latest.len()
    }

    /// Second closure round, item 3: how many origins hold an epoch
    /// record (tests and observability). Drains with the
    /// observation/tombstone maps — an epoch can never outlive
    /// everything that justified it.
    pub fn sensing_provider_epoch_count(&self) -> usize {
        self.sensing_observations.lock().provider_epochs.len()
    }

    /// SI-4a: this hop's OWN continuity toward a branch's origin —
    /// the §4.4 hop rule's input (tests and observability). `None`
    /// until the first admitted beat creates the cell.
    pub fn sensing_upstream_continuity(
        &self,
        key: &sensing::ProviderInterestKey,
    ) -> Option<sensing::Continuity> {
        self.sensing_observations
            .lock()
            .upstream
            .get(key)
            .map(sensing::ObservationCell::continuity)
    }

    /// SI-4b: the LOCAL consumer's continuity-gated projection for
    /// one branch (plan §3.4/§4.5). `Unknown` for an unwatched
    /// branch — the conservative default.
    pub fn sensing_projected(
        &self,
        key: &sensing::ProviderInterestKey,
    ) -> sensing::ProjectedReadiness {
        self.sensing_observations
            .lock()
            .consumer_cells
            .get(key)
            .map(sensing::ObservationCell::projected)
            .unwrap_or(sensing::ProjectedReadiness::Unknown)
    }

    /// SI-4b: per-provider projections (plus provider start
    /// estimates) for one capability interest — the Layer-1
    /// aggregate's input (§3.5; the frozen `SensingConsumer`
    /// surface).
    pub fn sensing_branch_projections(
        &self,
        interest: &sensing::CapabilityInterestKey,
    ) -> Vec<(u64, sensing::ProjectedReadiness, Option<Duration>)> {
        self.sensing_observations
            .lock()
            .consumer_cells
            .iter()
            .filter(|(key, _)| &key.interest == interest)
            .map(|(key, cell)| {
                (
                    key.provider,
                    cell.projected(),
                    cell.observation().and_then(|obs| obs.estimated_start),
                )
            })
            .collect()
    }

    /// SI-4b: the LOCAL result-mode aggregate for one interest
    /// (plan §3.5 — local by definition: viability is
    /// consumer-relative through `budget`). Branch views join the
    /// consumer cells with LIVE route estimates from the proximity
    /// plane; `search_complete` is the caller's resolution state
    /// (open-world selectors are never complete, §3.5).
    /// SI-4 review P1 (completeness): a bare completeness flag over
    /// only-materialized cells would mistake a MISSING expected
    /// provider for NotReady evidence. Completeness is therefore
    /// claimable only WITH the resolved expected population:
    /// `Some(expected)` inserts providers with no observation yet
    /// as Unknown branches (so the potential-count rule sees them)
    /// and enables completeness; `None` refuses complete/NotReady
    /// projection outright (open-world selectors additionally never
    /// complete, §3.5 — enforced inside `project_aggregate`).
    pub fn sensing_aggregate_view(
        &self,
        spec: &sensing::InterestSpec,
        budget: &sensing::ConsumerLatencyBudget,
        resolved_population: Option<&[u64]>,
    ) -> sensing::AggregateView {
        let branches = self.sensing_branch_views(&spec.key(), resolved_population);
        sensing::project_aggregate(
            &spec.providers,
            spec.result_mode,
            budget,
            &branches,
            resolved_population.is_some(),
        )
    }

    /// The §3.5 branch views for one interest — consumer-cell
    /// projections joined with LIVE route estimates, filtered and
    /// completed by the resolved population (SI-4 re-review item 7:
    /// `Some(set)` includes ONLY set members and inserts missing
    /// ones as Unknown). Shared by [`Self::sensing_aggregate_view`]
    /// and the SI-6 scheduler seams so aggregate, overlay, and
    /// candidate order can never disagree on their inputs.
    fn sensing_branch_views(
        &self,
        interest: &sensing::CapabilityInterestKey,
        resolved_population: Option<&[u64]>,
    ) -> Vec<sensing::BranchView> {
        let mut branches: Vec<sensing::BranchView> = self
            .sensing_branch_projections(interest)
            .into_iter()
            .map(
                |(provider, projection, estimated_start)| sensing::BranchView {
                    provider,
                    projection,
                    estimated_start,
                    route_estimate: sensing::proximity_route_estimate(
                        &self.proximity_graph,
                        provider,
                    ),
                },
            )
            .collect();
        if let Some(expected) = resolved_population {
            branches.retain(|branch| expected.contains(&branch.provider));
            for provider in expected {
                if !branches.iter().any(|branch| branch.provider == *provider) {
                    branches.push(sensing::BranchView {
                        provider: *provider,
                        projection: sensing::ProjectedReadiness::Unknown,
                        estimated_start: None,
                        route_estimate: sensing::proximity_route_estimate(
                            &self.proximity_graph,
                            *provider,
                        ),
                    });
                }
            }
        }
        branches
    }

    /// SI-6 (§4.9): the TWO-LEVEL readiness overlay for one interest
    /// — the LOCAL aggregate plus the per-(provider, generation)
    /// observations behind it, joined AT READ TIME from the consumer
    /// cells, route state, and the resolved population. Deliberately
    /// never embedded into the capability fold entries: readiness is
    /// consumer-relative (§3.5) and mutating fold state would break
    /// the CRDT-grade AP semantics the liveness gate preserves; the
    /// entry-level suspension flag stays reserved for UNCONDITIONAL
    /// loss — one conditional observation never suspends the entry.
    pub fn sensing_readiness_overlay(
        &self,
        spec: &sensing::InterestSpec,
        budget: &sensing::ConsumerLatencyBudget,
        resolved_population: Option<&[u64]>,
    ) -> SensingReadinessOverlay {
        let interest = spec.key();
        let candidates: Vec<((u64, u64), sensing::ReadinessObservation)> = {
            let observations = self.sensing_observations.lock();
            let mut candidates: Vec<((u64, u64), sensing::ReadinessObservation)> = observations
                .consumer_cells
                .iter()
                .filter(|(key, _)| {
                    key.interest == interest
                        // SI-6 review P1: the candidates half rides
                        // the SAME resolved-population seam as the
                        // aggregate — a retained out-of-population
                        // cell must not appear behind an aggregate
                        // that excluded it. Missing expected
                        // providers stay absent here (they are
                        // Unknown branches in the aggregate, not
                        // observations).
                        && resolved_population
                            .is_none_or(|expected| expected.contains(&key.provider))
                })
                .filter_map(|(key, cell)| {
                    cell.observation().map(|observation| {
                        (
                            (key.provider, observation.capability_generation),
                            *observation,
                        )
                    })
                })
                .collect();
            candidates.sort_by_key(|(key, _)| *key);
            candidates
        };
        SensingReadinessOverlay {
            aggregate: self.sensing_aggregate_view(spec, budget, resolved_population),
            candidates,
        }
    }

    /// SI-6: the Projection-6 sensed candidate delta for one
    /// interest, assembled from this node's OWN overlay (the same
    /// branch views the aggregate projects). The scheduler-bridge
    /// projection is pure; this is its node-level input join.
    pub fn sensed_candidates(
        &self,
        spec: &sensing::InterestSpec,
        budget: &sensing::ConsumerLatencyBudget,
        resolved_population: Option<&[u64]>,
    ) -> super::behavior::scheduler_bridge::SensedCandidates {
        let branches = self.sensing_branch_views(&spec.key(), resolved_population);
        super::behavior::scheduler_bridge::project_sensed_candidates(&branches, budget)
    }

    /// SI-4b: subscribe to the §4.9 overlay change signal — since
    /// the SI-6 review, the UNIFIED scheduler-input generation (see
    /// [`Self::subscribe_sensing_scheduler_inputs`], the same
    /// underlying watch).
    pub fn subscribe_sensing_overlay_changes(&self) -> tokio::sync::watch::Receiver<u64> {
        self.sensing_overlay_changed.subscribe()
    }

    /// SI-6 review P1: the UNIFIED scheduler-input generation — one
    /// watch covering every plane that can change
    /// [`super::behavior::scheduler_bridge::SensedCandidates`]:
    /// observation movement on the SCHEDULER-relevant tuple
    /// (projection, signed start estimate, generation), continuity
    /// expiry and failure-plane disruption, discrete route/topology
    /// events (session open, recovery, failure edges, route
    /// withdrawals), and capability-fold membership (including the
    /// SI-6.1 leader reconciliation). Continuous route-EWMA drift is
    /// deliberately NOT event-bumped — bumping per pingwave sample
    /// would fire at heartbeat rate; it is sampled at re-match.
    /// Budget changes are the caller's own input. Alias of
    /// [`Self::subscribe_sensing_overlay_changes`] — one underlying
    /// generation.
    pub fn subscribe_sensing_scheduler_inputs(&self) -> tokio::sync::watch::Receiver<u64> {
        self.sensing_overlay_changed.subscribe()
    }

    /// SI-3c: whether this hop's observer gate poisoned an origin's
    /// incarnation for one interest digest (equivocation — two
    /// payloads on one `(incarnation, seq)`). Tests + observability.
    pub fn sensing_observer_poisoned(
        &self,
        origin: u64,
        digest: sensing::Digest256,
    ) -> Option<sensing::Incarnation> {
        self.sensing_observer_gate.lock().poisoned(origin, digest)
    }

    /// A handle to the sensing-plane counters (SI-2a observability;
    /// SI-7 grows the full stats surface).
    pub fn sensing_counters(&self) -> Arc<sensing::SensingCounters> {
        self.sensing_counters.clone()
    }

    /// How many inbound sensing registrations the table refused with
    /// [`sensing::RegisterOutcome::OverCap`] (the per-peer
    /// amplification bound, plan §5).
    pub fn sensing_over_cap_refusals(&self) -> u64 {
        self.sensing_over_cap.load(Ordering::Relaxed)
    }

    /// Number of `(interest, provider)` branch keys currently in
    /// this hop's sensing interest table.
    pub fn sensing_interest_count(&self) -> usize {
        self.sensing_interest_table.lock().len()
    }

    /// Whether the sensing interest table holds no rows at all — the
    /// zero-idle-cost criterion (plan §8), and the dark-launch
    /// invariant while `enable_sensing_coalescing` is off.
    pub fn sensing_table_is_empty(&self) -> bool {
        self.sensing_interest_table.lock().is_empty()
    }

    /// Live downstream ids for one sensing branch key (tests +
    /// observability).
    pub fn sensing_downstreams(
        &self,
        key: &sensing::ProviderInterestKey,
    ) -> Vec<sensing::DownstreamId> {
        self.sensing_interest_table
            .lock()
            .downstreams(key, Instant::now())
    }

    /// One downstream's sensing table row for a branch key (tests +
    /// observability) — carries the session-proven root the row was
    /// admitted under (plan §4.10).
    pub fn sensing_downstream_entry(
        &self,
        key: &sensing::ProviderInterestKey,
        downstream: sensing::DownstreamId,
    ) -> Option<sensing::DownstreamEntry> {
        self.sensing_interest_table
            .lock()
            .downstream_entry(key, downstream)
            .copied()
    }

    /// The owner-root commitment this node's sensing plane serves
    /// (plan §4.10): [`MeshNodeConfig::sensing_owner_root`], or this
    /// node's own entity commitment by default.
    pub fn sensing_local_root(&self) -> sensing::AudienceScopeCommitment {
        self.sensing_local_root
    }

    /// Install the sensing-leader role on this node (plan §4.1),
    /// enabling the leader-addressed `CapabilityRegistration` intake
    /// on the 0x0C02 dispatch arm. Built from this node's config
    /// (owner root, `continuity_factor`, `max_interests_per_peer`)
    /// with the default bounded-exploration policy. Returns `false`
    /// (installing nothing) while `enable_sensing_coalescing` is
    /// off; idempotent — re-assuming replaces the role with a fresh
    /// (empty) one, exactly the soft-state re-registration contract
    /// of leader failover (§4.1).
    ///
    /// `redex`-gated with `sensing::rendezvous`: the role rides the
    /// RedEX election. WHO assumes it — the §4.1 rendezvous at the
    /// proximity-centrality key — is election wiring in a later
    /// slice; this slice provides the intake seam.
    #[cfg(feature = "redex")]
    pub fn assume_sensing_leader(&self) -> bool {
        if !self.config.enable_sensing_coalescing {
            return false;
        }
        let leader = sensing::SensingLeader::new(
            self.sensing_local_root,
            sensing::CandidatePolicy::default(),
            self.config.continuity_factor,
            self.config.max_interests_per_peer,
            self.config.sensing_interest_ttl,
        );
        *self.sensing_leader.lock() = Some(leader);
        true
    }

    /// Coalesced interest rows held by this node's sensing-leader
    /// role — `None` when the role is not installed (tests +
    /// observability).
    #[cfg(feature = "redex")]
    pub fn sensing_leader_interest_count(&self) -> Option<usize> {
        self.sensing_leader
            .lock()
            .as_ref()
            .map(|leader| leader.interest_count())
    }

    /// SI-7: this node's sensing-leader load snapshot (interests ×
    /// branches × downstream rows) — `None` when the role is not
    /// installed. Operators watch the leader hotspot through this
    /// (plan §7).
    #[cfg(feature = "redex")]
    pub fn sensing_leader_load(&self) -> Option<sensing::SensingLeaderLoad> {
        self.sensing_leader
            .lock()
            .as_ref()
            .map(|leader| leader.load(Instant::now()))
    }

    /// Active branch providers this node's sensing-leader role
    /// resolved for one coalesced interest — `None` when the role is
    /// not installed, empty when the interest is unknown (tests +
    /// observability; the SI-2b resolver's output surface).
    #[cfg(feature = "redex")]
    pub fn sensing_leader_branches(
        &self,
        key: &sensing::CapabilityInterestKey,
    ) -> Option<Vec<u64>> {
        self.sensing_leader
            .lock()
            .as_ref()
            .map(|leader| leader.branches(key))
    }

    /// Live downstream ids the sensing-leader role's OWN relay table
    /// holds for one resolved branch — the per-consumer demand the
    /// leader coalesces before this hop's single `Local` row (tests
    /// + observability; `None` when the role is not installed).
    #[cfg(feature = "redex")]
    pub fn sensing_leader_branch_downstreams(
        &self,
        key: &sensing::ProviderInterestKey,
    ) -> Option<Vec<sensing::DownstreamId>> {
        self.sensing_leader
            .lock()
            .as_ref()
            .map(|leader| leader.relay.table.downstreams(key, Instant::now()))
    }

    /// SI-2b: the Layer-1 candidate snapshot for `capability_id`
    /// over this node's LIVE planes (plan §4.7/§4.10) — the exact
    /// rows the leader intake feeds
    /// [`sensing::resolve_candidates`]:
    ///
    /// - **declarers** — fold nodes whose capability set
    ///   structurally matches the capability id (one `with_state`
    ///   pass; see [`sensing::declares_capability`] for the
    ///   documented v1 tag/name match);
    /// - **authorized** — the declarer's TOFU-pinned entity root
    ///   equals this node's sensing owner root (§4.10 v1; the same
    ///   pin the dispatch arm derives session roots from);
    /// - **reachable** — self, a live direct session, or a routing
    ///   table hit;
    /// - **route_estimate** — the
    ///   [`sensing::proximity_route_estimate`] fallback ladder over
    ///   the proximity graph;
    /// - **tags** — the declarer's folded assertions with the
    ///   declarer's own pinned root as provenance; **groups** —
    ///   empty until the `GroupRef` fold surface lands.
    ///
    /// `redex`-gated with the leader intake it feeds (the role
    /// rides the RedEX election).
    #[cfg(feature = "redex")]
    pub fn sensing_candidate_snapshot(
        &self,
        capability_id: &sensing::CapabilityId,
    ) -> Vec<sensing::CandidateProvider> {
        sensing_candidate_snapshot_from_parts(
            &self.capability_fold,
            &self.proximity_graph,
            &self.router,
            &self.peers,
            &self.peer_entity_ids,
            self.node_id,
            sensing::AudienceScopeCommitment::owner_root(self.identity.entity_id()),
            &self.sensing_local_root,
            capability_id,
        )
    }

    /// Test-only helper — TOFU-pin `entity_id` for `node_id` exactly
    /// as a signature-verified DIRECT capability announcement would
    /// (first write wins, mirroring the dispatch pin). Lets fixtures
    /// model fold declarers that are not live sessions: the SI-2b
    /// candidate snapshot reads this pin for §4.10 authorization.
    #[doc(hidden)]
    pub fn test_pin_peer_entity(&self, node_id: u64, entity_id: EntityId) {
        self.peer_entity_ids.entry(node_id).or_insert(entity_id);
    }

    /// Test/debug accessor for the live [`NetSession`] to a peer.
    /// Integration tests use it to drive session-level state (e.g. open
    /// a stream to make a session "busy" for the upgrade C3 gate).
    #[doc(hidden)]
    #[cfg(feature = "nat-traversal")]
    pub fn peer_session_for_test(&self, node_id: u64) -> Option<Arc<NetSession>> {
        self.peers.get(&node_id).map(|e| e.value().session.clone())
    }

    /// Build a [`MigrationIdentityContext`](crate::adapter::net::subprotocol::MigrationIdentityContext)
    /// bound to this node.
    ///
    /// The context's closures capture this node's long-term Noise
    /// static private key (for the envelope-open path) and an
    /// `Arc`-clone of the peer map (for the peer-static lookup used
    /// by the source-side seal path). The private key is wrapped in
    /// a `StaticSecret` inside the `unseal_snapshot` closure, which
    /// is `zeroize`-on-drop — the key is never surfaced as a
    /// readable field on the returned value.
    ///
    /// Used by the SDK's compute runtime to wire identity-envelope
    /// support into the migration dispatcher without handing the
    /// key across the crate boundary. The previous shape exposed
    /// `static_x25519_priv() -> [u8; 32]` as a `pub` method, which
    /// leaked long-term secret material to any SDK caller — any
    /// code with an `Arc<Mesh>` could copy the node's identity key
    /// out and impersonate it indefinitely.
    pub fn migration_identity_context(
        &self,
    ) -> crate::adapter::net::subprotocol::MigrationIdentityContext {
        use crate::adapter::net::state::snapshot::StateSnapshot;
        use crate::adapter::net::subprotocol::MigrationIdentityContext;

        // Construct once; `StaticSecret` zeroizes on drop, so the
        // key is wiped when the last owner of the Arc'd closure is
        // dropped. Rebuilding the StaticSecret on every call would
        // copy the raw bytes through a short-lived stack variable —
        // bounded exposure is fine but once-at-construction is
        // strictly less.
        let priv_secret = x25519_dalek::StaticSecret::from(self.static_keypair.private);
        let unseal_snapshot = Arc::new(
            move |snapshot: &StateSnapshot|
                  -> Result<Option<_>, crate::adapter::net::identity::EnvelopeError> {
                snapshot.open_identity_envelope(&priv_secret)
            },
        );

        let peers = self.peers.clone();
        let peer_static_lookup = Arc::new(move |node_id: u64| {
            peers.get(&node_id).and_then(|e| {
                let pk = e.value().remote_static_pub;
                if pk == [0u8; 32] {
                    None
                } else {
                    Some(pk)
                }
            })
        });

        MigrationIdentityContext {
            unseal_snapshot,
            peer_static_lookup,
        }
    }

    /// The peer's Noise static X25519 public key, captured during
    /// the handshake that established the session. Load-bearing for
    /// daemon migration: the source uses this key as the seal
    /// recipient on the `IdentityEnvelope`, so the only party that
    /// can unseal the daemon's ed25519 seed is the peer whose
    /// static private key completed the Noise handshake.
    ///
    /// Returns `None` if we have no session with `node_id`, or if
    /// the underlying handshake produced a zero-filled static
    /// pubkey (a sentinel for test-only code paths that construct
    /// `SessionKeys` without running a real handshake).
    pub fn peer_static_x25519(&self, node_id: u64) -> Option<[u8; 32]> {
        let entry = self.peers.get(&node_id)?;
        let pk = entry.value().remote_static_pub;
        // Zero-filled → "not available." Real handshakes populate
        // this from `snow`'s post-handshake `get_remote_static`,
        // which returns 32 bytes of non-identity-zero X25519 pubkey.
        if pk == [0u8; 32] {
            None
        } else {
            Some(pk)
        }
    }

    /// Look up a peer's assigned subnet, if one has been recorded.
    /// Only populated from signature-verified
    /// `CapabilityAnnouncement`s — unsigned announcements do not
    /// write here even when a node is running with
    /// `require_signed_capabilities = false`. Exposed for tests +
    /// operator observability; `subnet_visible` consults this map
    /// on the publish / subscribe fan-out path.
    pub fn peer_subnet(&self, node_id: u64) -> Option<SubnetId> {
        self.peer_subnets.get(&node_id).map(|e| *e.value())
    }

    /// This node's own `SubnetId` — the value supplied via
    /// `MeshNodeConfig::subnet` (or `SubnetId::GLOBAL` when none was
    /// configured). Stable for the node's lifetime; the substrate
    /// doesn't reassign the local subnet at runtime.
    pub fn local_subnet(&self) -> SubnetId {
        self.local_subnet
    }

    /// Read-only handle to the `SubnetPolicy` that derived this
    /// node's `local_subnet`, when one was supplied. `None` when
    /// the local subnet came from `MeshNodeConfig::subnet`
    /// directly without going through a policy. Operator tools
    /// surface this to explain "why is this node in subnet X."
    pub fn local_subnet_policy(&self) -> Option<&Arc<SubnetPolicy>> {
        self.local_subnet_policy.as_ref()
    }

    /// Snapshot of every `(node_id, subnet_id)` pair the local
    /// node has cached from signature-verified capability
    /// announcements. Sorted by `node_id` for stable output. Used
    /// by operator tooling (`net subnet ls` / `subnet tree`) to
    /// enumerate the mesh's subnet topology from a single
    /// vantage point — anything not yet announced (or announced
    /// unsigned) is invisible here, matching `peer_subnet`'s
    /// "signed-only" contract.
    pub fn known_subnets(&self) -> Vec<(u64, SubnetId)> {
        let mut out: Vec<(u64, SubnetId)> = self
            .peer_subnets
            .iter()
            .map(|e| (*e.key(), *e.value()))
            .collect();
        out.sort_by_key(|(node_id, _)| *node_id);
        out
    }

    /// Get the local bind address.
    pub fn local_addr(&self) -> SocketAddr {
        self.socket.local_addr()
    }

    /// Get the router (for adding routes, checking stats).
    pub fn router(&self) -> &Arc<NetRouter> {
        &self.router
    }

    /// Get the failure detector.
    pub fn failure_detector(&self) -> &Arc<FailureDetector> {
        &self.failure_detector
    }

    /// Set the migration subprotocol handler.
    ///
    /// Can be called before or after `start()`. When set, inbound
    /// packets with `subprotocol_id == 0x0500` are dispatched to
    /// this handler instead of being queued as events. Idempotent
    /// w.r.t. replacing the handler — a second call swaps in the
    /// new one atomically.
    ///
    /// Use [`Self::clear_migration_handler`] to uninstall (returns
    /// the mesh to the no-handler state where inbound migration
    /// packets hit the `ComputeNotSupported` fallback). Needed by
    /// `DaemonRuntime::shutdown` and by `start`'s lost-race
    /// cleanup path — the mesh must not hold a live handler
    /// pointing at a runtime that is no longer serving daemons.
    pub fn set_migration_handler(&self, handler: Arc<MigrationSubprotocolHandler>) {
        self.migration_handler.store(Some(handler));
    }

    /// Uninstall the migration subprotocol handler. After this
    /// call, inbound migration subprotocol packets hit the
    /// no-handler fallback and synthesise `ComputeNotSupported`
    /// for migration-initiating messages (other message types are
    /// dropped).
    ///
    /// Used by the SDK's `DaemonRuntime::start` to clean up after
    /// losing the install-vs-CAS race against a concurrent
    /// `shutdown`: if `start` installed a handler but its CAS to
    /// `Ready` lost to `shutdown`'s state flip, the mesh would
    /// otherwise be left with a live handler owned by a runtime
    /// that's already been torn down.
    pub fn clear_migration_handler(&self) {
        self.migration_handler.store(None);
    }

    /// Returns `true` iff a migration subprotocol handler is
    /// currently installed on this mesh. Used primarily by tests
    /// that need to observe the ordering of handler installation
    /// against other runtime state transitions — the `ArcSwap` load
    /// itself is a public API surface regardless.
    pub fn has_migration_handler(&self) -> bool {
        self.migration_handler.load().is_some()
    }

    /// Block packets from/to a peer address (simulates network partition).
    pub fn block_peer(&self, addr: SocketAddr) {
        self.partition_filter.insert(addr);
    }

    /// Unblock a peer address (simulates partition healing).
    pub fn unblock_peer(&self, addr: &SocketAddr) {
        self.partition_filter.remove(addr);
    }

    /// Check if a peer is blocked.
    pub fn is_blocked(&self, addr: &SocketAddr) -> bool {
        self.partition_filter.contains(addr)
    }

    /// Get the proximity graph.
    pub fn proximity_graph(&self) -> &Arc<ProximityGraph> {
        &self.proximity_graph
    }

    /// Get the reroute policy (for checking reroute stats in tests).
    pub fn reroute_policy(&self) -> &Arc<ReroutePolicy> {
        &self.reroute_policy
    }

    /// Number of connected peers.
    pub fn peer_count(&self) -> usize {
        self.peers.len()
    }

    /// Connect to a peer. Performs a Noise NKpsk0 handshake as initiator.
    ///
    /// The peer must be listening and ready to accept the handshake.
    /// Returns the peer's node ID on success.
    pub async fn connect(
        &self,
        peer_addr: SocketAddr,
        peer_pubkey: &[u8; 32],
        peer_node_id: u64,
    ) -> Result<u64, AdapterError> {
        let keys = self
            .handshake_initiator(peer_addr, peer_pubkey, peer_node_id)
            .await?;

        // Shared peer install (NetSession + router + peers +
        // peer_addrs + addr_to_node). Direct-mode overwrites
        // addr_to_node — `peer_addr` IS the peer's wire address.
        self.install_peer(
            peer_node_id,
            peer_addr,
            keys,
            AddrInstallMode::DirectOverwrite,
        );

        // Direct-handshake-only post-install wiring. Routed
        // handshakes (`connect_via`) intentionally skip these:
        // pingwave / failure_detector are for live 1-hop peers
        // and the routed responder may not actually be 1-hop on
        // the wire; push_local_announcement is the initiator's
        // capability broadcast and routes through different
        // machinery in the routed case.
        let peer_graph_id = node_id_to_graph_id(peer_node_id);
        let pw = EnhancedPingwave::new(peer_graph_id, 0, 1).with_load(0, HealthStatus::Healthy);
        self.proximity_graph.on_pingwave(pw, peer_addr);
        self.failure_detector.heartbeat(peer_node_id, peer_addr);
        self.push_local_announcement(peer_addr).await;
        // RT-4: a new session is a topology change - flood our
        // pingwave now so third parties learn the new edge at
        // flood speed, not on the next heartbeat tick. Session open
        // races the peer's post-handshake bookkeeping, so resend.
        self.emit_event_pingwave(true);

        Ok(peer_node_id)
    }

    /// Shared peer-install bookkeeping for both [`Self::connect`]
    /// (direct) and [`Self::connect_via`] (routed). Wraps the
    /// negotiated `keys` in a [`NetSession`], registers the
    /// route + peer entry + reverse address index. The
    /// `addr_mode` determines how `addr_to_node` is touched —
    /// see [`AddrInstallMode`] for the rationale per caller.
    ///
    /// Unconditional last-writer-wins: any existing session for the
    /// peer is replaced. For the compare-and-swap variant used by the
    /// NAT-traversal direct-path upgrade, see
    /// [`Self::install_peer_cas`].
    fn install_peer(
        &self,
        peer_node_id: u64,
        peer_addr: SocketAddr,
        keys: SessionKeys,
        addr_mode: AddrInstallMode,
    ) {
        // `None` expected → unconditional install; always returns true.
        self.install_peer_cas(peer_node_id, peer_addr, keys, addr_mode, None);
    }

    /// Peer-install with an optional compare-and-swap against the
    /// current session_id (`NAT_TRAVERSAL_V2_PLAN.md` C2).
    ///
    /// When `expected_prior_session_id` is `Some(sid)`, the install
    /// proceeds only if the peer's current session_id equals `sid` —
    /// i.e. nothing replaced the session since the caller observed it.
    /// A background direct-path upgrade uses this so that a racing
    /// inbound rotation (which the upgrade's handshake didn't know
    /// about) wins and is NOT clobbered — the last-writer-wins
    /// nondeterminism is removed from the upgrade path specifically.
    /// The check + insert are atomic under the DashMap entry's shard
    /// write lock.
    ///
    /// Returns `true` if the session was installed, `false` if the CAS
    /// check failed (the caller should treat its upgrade as lost and
    /// leave the current session — typically the working relay path —
    /// intact).
    fn install_peer_cas(
        &self,
        peer_node_id: u64,
        peer_addr: SocketAddr,
        keys: SessionKeys,
        addr_mode: AddrInstallMode,
        expected_prior_session_id: Option<u64>,
    ) -> bool {
        use dashmap::mapref::entry::Entry;

        let remote_static_pub = keys.remote_static_pub;
        let session = Arc::new(NetSession::new(
            keys,
            peer_addr,
            self.config.packet_pool_size,
            self.config.default_reliable,
        ));
        // Capture session_id before the session is moved into
        // PeerInfo so we can populate the reverse index
        // (PERF_AUDIT §2.4).
        let session_id = session.session_id();
        let new_entry = PeerInfo {
            node_id: peer_node_id,
            addr: peer_addr,
            session,
            remote_static_pub,
            // Initiator-side: replay-guard is a responder-side
            // concern, leave empty.
            last_initiator_ephemeral: None,
        };

        // CAS + insert atomically under the entry's shard write lock.
        // On a failed CAS we mutate nothing (no route, no reverse
        // index) and bail, so a lost upgrade leaves the working
        // session untouched.
        let displaced: Option<PeerInfo> = match self.peers.entry(peer_node_id) {
            Entry::Occupied(mut occ) => {
                if let Some(expected) = expected_prior_session_id {
                    if occ.get().session.session_id() != expected {
                        return false;
                    }
                }
                Some(occ.insert(new_entry))
            }
            Entry::Vacant(vac) => {
                if expected_prior_session_id.is_some() {
                    // CAS expected a prior session, but it's gone (torn
                    // down). Abort rather than resurrect a session the
                    // upgrade didn't intend to create.
                    return false;
                }
                vac.insert(new_entry);
                None
            }
        };

        self.router.add_route(peer_node_id, peer_addr);
        self.peer_addrs.insert(peer_node_id, peer_addr);
        // Old direct address of a re-handshaking peer, captured
        // before `displaced` is consumed below (RT-5: address
        // migration for multi-hop routes, see the DirectOverwrite
        // arm).
        let displaced_addr = displaced.as_ref().map(|d| d.addr);
        // PERF_AUDIT §2.4: reverse-index update. Routed-local
        // dispatch reads this in O(1) instead of scanning peers
        // for a matching session_id. If this insert replaced an
        // existing session (same peer re-handshaking), evict the
        // displaced session_id's entry first — otherwise every
        // re-handshake leaks one stale reverse-index entry
        // forever. Eviction before insert keeps the fresh mapping
        // even in the (cryptographically improbable) case where
        // the new handshake derived the same session_id.
        if let Some(old) = &displaced {
            self.session_id_to_node
                .remove_if(&old.session.session_id(), |_, n| *n == peer_node_id);
            // C4 hygiene (`NAT_TRAVERSAL_V2_PLAN.md`): drop the
            // displaced session's stale reverse-addr mapping when its
            // addr differs from the new one (a relay→direct swap leaves
            // the old relay addr behind otherwise). Guard on ownership
            // so we never evict an entry another peer legitimately owns
            // (e.g. a shared relay addr).
            if old.addr != peer_addr {
                self.addr_to_node
                    .remove_if(&old.addr, |_, n| *n == peer_node_id);
            }
        }
        self.session_id_to_node.insert(session_id, peer_node_id);
        // A fresh session incarnation restarts the peer's
        // withdrawal seq counter — purge its gate history so its
        // first post-handshake withdrawals aren't mistaken for
        // stale (RT-5 ordering gate).
        self.route_withdraw_gate.forget_sender(peer_node_id);
        match addr_mode {
            AddrInstallMode::DirectOverwrite => {
                // Re-handshake from a NEW direct address (NAT
                // rebind): repoint any multi-hop routes still
                // carrying this peer's previous address, and drop
                // the stale reverse-index entry. Equal-metric
                // pingwave refreshes never rewrite an installed
                // `next_hop`, so without this migration those routes
                // keep the old address forever and address-keyed ops
                // — notably the RT-5 withdrawal match
                // (`remove_route_if_next_hop_is`) — silently miss
                // them, degrading withdrawals to age-out for this
                // peer (RT-5 review Finding 6).
                if let Some(old_addr) = displaced_addr {
                    if old_addr != peer_addr {
                        self.router
                            .routing_table()
                            .migrate_next_hop(old_addr, peer_addr);
                        self.addr_to_node
                            .remove_if(&old_addr, |_, n| *n == peer_node_id);
                    }
                }
                self.addr_to_node.insert(peer_addr, peer_node_id);
            }
            AddrInstallMode::RoutedPreserve => {
                self.addr_to_node.entry(peer_addr).or_insert(peer_node_id);
            }
        }
        true
    }

    /// Accept a connection from a peer. Performs Noise NKpsk0 as responder.
    ///
    /// Waits for an incoming handshake packet and completes the handshake.
    /// Returns the peer's address and assigns the given node_id.
    ///
    /// # Ordering contract
    ///
    /// `accept()` MUST be called before [`Self::start()`]. Once
    /// `start()` has spawned the dispatch loop, the dispatcher
    /// consumes every inbound UDP datagram from the shared socket;
    /// `try_handshake_responder` polls the same socket directly and
    /// races the dispatcher for incoming msg1 packets. Because no
    /// per-pending-responder registry exists today (initiator-side
    /// handshakes use one — see `pending_direct_initiators` at
    /// `mesh.rs:~1216`; the responder side is a deferred design item),
    /// a `start() → accept()` ordering produces a swallowed msg1 and
    /// a hang. To prevent that hang silently turning into a debugging
    /// nightmare, calling `accept()` after `start()` now returns an
    /// explicit error rather than spinning forever.
    pub async fn accept(&self, peer_node_id: u64) -> Result<(SocketAddr, u64), AdapterError> {
        use std::sync::atomic::Ordering as AtOrd;

        // Race-free entry guard. Increment `accept_in_flight`
        // BEFORE checking `started`. `start()` checks
        // `accept_in_flight` after its CAS and refuses, so the
        // windows are ordered: accept either sees `started=true`
        // and bails OUT (so accept_in_flight goes back to 0 and
        // start sees 0), or `start` sees accept_in_flight > 0 and
        // refuses to run. Reasoning is symmetric to a
        // reader-writer SeqCst handshake: the SeqCst total order
        // on these two atomics makes "either accept observes
        // start and bails, or start observes accept and refuses"
        // mutually exclusive. A bare `started.load(Acquire)` check
        // would be a TOCTOU: `start()` could fire between the
        // check and `handshake_responder`'s recv_from, after
        // which the dispatcher would race the responder for
        // msg1.
        //
        // RAII guard `AcceptGuard` decrements on drop so any
        // early-return (Err from handshake_responder, panic in
        // session construction, future cancellation) doesn't
        // leak the in-flight count.
        struct AcceptGuard<'a>(&'a std::sync::atomic::AtomicUsize);
        impl Drop for AcceptGuard<'_> {
            fn drop(&mut self) {
                // SeqCst (not AcqRel): the mutual-exclusion proof
                // in `start`'s doc-comment relies on a SeqCst
                // total order across BOTH atomics. AcqRel RMWs do
                // not participate in the SC total order, so on
                // weakly-ordered cores (AArch64 / RISC-V) `start`
                // could read the pre-increment 0 in
                // `accept_in_flight` while `accept` simultaneously
                // reads `started == false` — exactly the race the
                // counter was added to prevent.
                self.0.fetch_sub(1, AtOrd::SeqCst);
            }
        }

        self.accept_in_flight.fetch_add(1, AtOrd::SeqCst);
        let _guard = AcceptGuard(&self.accept_in_flight);

        if self.started.load(AtOrd::SeqCst) {
            return Err(AdapterError::Fatal(
                "Mesh::accept called after start() — the dispatch loop is already \
                 consuming inbound packets and would race the responder handshake. \
                 Call accept() for every peer BEFORE invoking start()."
                    .into(),
            ));
        }
        let (keys, peer_addr) = self.handshake_responder(peer_node_id).await?;

        let remote_static_pub = keys.remote_static_pub;
        let session = Arc::new(NetSession::new(
            keys,
            peer_addr,
            self.config.packet_pool_size,
            self.config.default_reliable,
        ));
        // PERF_AUDIT §2.4: capture session_id before move into
        // PeerInfo so we can populate the reverse index after the
        // insert.
        let session_id = session.session_id();

        self.router.add_route(peer_node_id, peer_addr);

        let displaced = self.peers.insert(
            peer_node_id,
            PeerInfo {
                node_id: peer_node_id,
                addr: peer_addr,
                session,
                remote_static_pub,
                // `accept` runs before `start()`, so the routed-
                // dispatch replay guard is moot; leave empty.
                last_initiator_ephemeral: None,
            },
        );
        self.addr_to_node.insert(peer_addr, peer_node_id);

        self.peer_addrs.insert(peer_node_id, peer_addr);
        // Re-handshake from a new direct address: migrate multi-hop
        // routes off the peer's previous address and drop its stale
        // reverse-index entry — see the matching comment in
        // `install_peer`'s DirectOverwrite arm (RT-5 review
        // Finding 6).
        if let Some(old_addr) = displaced.as_ref().map(|d| d.addr) {
            if old_addr != peer_addr {
                self.router
                    .routing_table()
                    .migrate_next_hop(old_addr, peer_addr);
                self.addr_to_node
                    .remove_if(&old_addr, |_, n| *n == peer_node_id);
            }
        }
        // PERF_AUDIT §2.4: evict the displaced session's reverse-
        // index entry before installing the fresh one — see the
        // matching comment in `install_peer`.
        if let Some(old) = displaced {
            self.session_id_to_node
                .remove_if(&old.session.session_id(), |_, n| *n == peer_node_id);
        }
        self.session_id_to_node.insert(session_id, peer_node_id);
        // See the matching comment in `install_peer` — fresh
        // incarnation, fresh withdrawal-seq gate history.
        self.route_withdraw_gate.forget_sender(peer_node_id);

        let peer_graph_id = node_id_to_graph_id(peer_node_id);
        let pw = EnhancedPingwave::new(peer_graph_id, 0, 1).with_load(0, HealthStatus::Healthy);
        self.proximity_graph.on_pingwave(pw, peer_addr);

        self.failure_detector.heartbeat(peer_node_id, peer_addr);

        // See the matching comment in `connect`.
        self.push_local_announcement(peer_addr).await;
        // RT-4: a new session is a topology change - flood our
        // pingwave now so third parties learn the new edge at
        // flood speed, not on the next heartbeat tick. Session open
        // races the peer's post-handshake bookkeeping, so resend.
        self.emit_event_pingwave(true);

        Ok((peer_addr, peer_node_id))
    }

    /// Start the receive loop and heartbeat tasks.
    ///
    /// Must be called after `connect()` / `accept()` to begin processing
    /// inbound packets.
    ///
    /// Refuses (no-op return) if any `accept()` call is currently
    /// in flight. Symmetric to `accept`'s contract: either
    /// `accept` observes `started=true` and bails (in-flight
    /// count goes to 0, then `start` proceeds), or `start`
    /// observes `accept_in_flight > 0` and refuses. The SeqCst
    /// orderings make this mutually exclusive. Without this
    /// counter check, `start` could fire between `accept`'s
    /// `started.load` and its `handshake_responder` poll, after
    /// which the dispatcher would race the responder for the
    /// inbound msg1.
    ///
    /// Note: this does NOT enable the periodic capability re-announce
    /// (which keeps the node's entry alive in its own and peers' folds
    /// past one TTL) — that needs an owned `Arc` to re-broadcast. Drive
    /// the node through [`Self::start_arc`] (as the SDK / FFI do) to get
    /// it; a bare `start` is for short-lived / test nodes.
    pub fn start(&self) {
        use std::sync::atomic::Ordering as AtOrd;
        if self.started.swap(true, AtOrd::SeqCst) {
            return; // already started
        }
        // After flipping `started`, observe `accept_in_flight`.
        // If any accept is mid-handshake, roll back and refuse.
        // The accept side either saw our SeqCst store before
        // its load (and bailed cleanly) or saw it after (and
        // we see its incremented counter). Spurious "concurrent
        // start + accept" is rare in production (start is
        // typically called once at boot), but the rollback
        // keeps semantics honest.
        if self.accept_in_flight.load(AtOrd::SeqCst) > 0 {
            // Roll back the flag so a subsequent `start()` after
            // accept finishes can succeed normally.
            self.started.store(false, AtOrd::SeqCst);
            tracing::warn!(
                "MeshNode::start() called while an accept() is in flight — \
                 refusing to start the dispatch loop to avoid racing the \
                 responder handshake. Retry start() after accept() returns."
            );
            return;
        }

        let recv_handle = self.spawn_receive_loop();
        let heartbeat_handle = self.spawn_heartbeat_loop();
        let stream_grant_drainer_handle = self.spawn_stream_grant_drainer_loop();
        let retransmit_handle = self.spawn_retransmit_loop();
        let router_handle = match self.router.start() {
            Some(h) => h,
            None => {
                tracing::warn!(
                    "MeshNode::start called while the router dispatch loop \
                     was already running; ignoring the duplicate start. \
                     This usually indicates start() was invoked twice."
                );
                return;
            }
        };
        let capability_gc_handle = self.spawn_capability_gc_loop();
        let capability_reannounce_handle = self.spawn_capability_reannounce_loop();
        let capability_announce_on_change_handle = self.spawn_capability_announce_on_change_loop();
        let fold_generation_gc_handle = self.spawn_fold_generation_gc_loop();
        // SI-3: `None` while the origin role is dark (plane off or
        // no persisted incarnation — fail-closed, §4.6).
        let sensing_emitter_handle = self.spawn_sensing_emitter_loop();
        let token_sweep_handle = self.spawn_token_sweep_loop();
        // Port-mapping task is opt-in — only spawned when the
        // operator set `try_port_mapping(true)`. Real client is
        // the `SequentialMapper` (NAT-PMP first, UPnP fallback
        // — stage 4b-4). Construction is async because LAN-IP
        // resolution needs a UDP socket bind, so we spawn an
        // outer task that resolves the sequencer then drives
        // the port-mapper task inline. If OS gateway discovery
        // AND LAN-IP resolution both fail, we fall back to the
        // `NullPortMapper` — the task exits quickly without
        // side effects, identical to an unavailable-router
        // environment.
        #[cfg(feature = "port-mapping")]
        let port_mapping_handle = if self.config.try_port_mapping {
            use super::traversal::portmap::{
                sequential_mapper_from_os, MappingSink, NullPortMapper, PortMapperClient,
                PortMapperTask,
            };
            let traversal_stats = self.traversal_stats.clone();
            let reflex_addr = self.reflex_addr.clone();
            let nat_class = self.nat_class.clone();
            let reflex_override_active = self.reflex_override_active.clone();
            let publish_mu = self.traversal_publish_mu.clone();
            let shutdown = self.shutdown.clone();
            let shutdown_notify = self.shutdown_notify.clone();
            let internal_port = self.config.bind_addr.port();
            let renewal = self.traversal_config.port_mapping_renewal;
            Some(tokio::spawn(async move {
                let client: Box<dyn PortMapperClient> = match sequential_mapper_from_os().await {
                    Some(seq) => Box::new(seq),
                    None => {
                        tracing::debug!(
                            "port-mapping: OS gateway + LAN IP resolution failed; \
                                 falling back to NullPortMapper",
                        );
                        Box::new(NullPortMapper::new())
                    }
                };
                let sink = MappingSink::new(
                    traversal_stats,
                    reflex_addr,
                    nat_class,
                    reflex_override_active,
                    publish_mu,
                );
                let task = PortMapperTask::new(
                    client,
                    sink,
                    internal_port,
                    renewal,
                    shutdown,
                    shutdown_notify,
                );
                task.run().await;
            }))
        } else {
            None
        };

        // Store handles — can't block here, but we need them for shutdown
        let tasks = self.tasks.clone();
        tokio::spawn(async move {
            let mut tasks = tasks.lock().await;
            tasks.push(recv_handle);
            tasks.push(heartbeat_handle);
            tasks.push(stream_grant_drainer_handle);
            tasks.push(retransmit_handle);
            tasks.push(router_handle);
            tasks.push(capability_gc_handle);
            tasks.push(capability_reannounce_handle);
            tasks.push(capability_announce_on_change_handle);
            tasks.push(fold_generation_gc_handle);
            if let Some(h) = sensing_emitter_handle {
                tasks.push(h);
            }
            tasks.push(token_sweep_handle);
            #[cfg(feature = "port-mapping")]
            if let Some(h) = port_mapping_handle {
                tasks.push(h);
            }
        });
    }

    /// Start the node through its `Arc`, enabling the periodic capability
    /// re-announce on top of everything [`Self::start`] does. The
    /// re-announce re-broadcasts this node's capabilities every
    /// [`MeshNodeConfig::capability_reannounce_interval`], keeping its
    /// entry alive in its own fold (so its callee-side nRPC gate doesn't
    /// expire its own services) AND in every peer's fold (so it stays
    /// discoverable) past one announcement TTL. Production entry points
    /// (the SDK, the FFI) call this; a bare [`Self::start`] omits the
    /// re-announce (fine for short-lived / test nodes). Idempotent.
    pub fn start_arc(self: &Arc<Self>) {
        // Store the weak before `start` spawns the re-announce loop, which
        // captures it. `set` only fails if already set (a re-start) — the
        // existing weak is equally valid, so ignore the result.
        let _ = self.self_weak.set(Arc::downgrade(self));
        self.start();
        // Background direct-path upgrade scan loop (Stage 3). The loop
        // itself no-ops unless `auto_direct_upgrade` is set, so spawning
        // unconditionally is cheap; keeping it here means any Arc-held
        // node started via `start_arc` gets upgrades when enabled.
        // Detached like the other lifecycle loops — it exits on
        // `shutdown_notify`.
        #[cfg(feature = "nat-traversal")]
        let _upgrade_loop_handle = self.spawn_direct_upgrade_loop();
    }

    /// Spawn the NAT classification loop. Waits until at least 2
    /// peers are connected, fires the initial sweep, then re-checks
    /// periodically so a mid-session NAT rebind (e.g. gateway
    /// reboot) gets picked up without operator intervention.
    ///
    /// Separate from [`Self::start`] because the loop needs an
    /// `Arc<MeshNode>` to call [`Self::reclassify_nat`] across
    /// `.await` points. Callers that hold a `MeshNode` behind an
    /// `Arc` (SDK, FFI, all production paths) can spawn this
    /// alongside `start` to get continuous classification; callers
    /// that don't can call [`Self::reclassify_nat`] manually via
    /// the `&self` surface.
    ///
    /// The loop is best-effort — it never returns an error surface
    /// to the node, and a failed sweep leaves the previous
    /// classification intact. Exits on `shutdown_notify`.
    #[cfg(feature = "nat-traversal")]
    pub fn spawn_nat_classify_loop(self: &Arc<Self>) -> JoinHandle<()> {
        let node = Arc::clone(self);
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        let reclassify_interval = self.traversal_config.classify_deadline.saturating_mul(12);

        tokio::spawn(async move {
            // Poll loop: wait for ≥2 peers before the first sweep.
            // The routed-handshake path seeds `peers` as each
            // connect/accept lands, so the wait is bounded by how
            // fast the operator hands us peers — not something we
            // can tune from here.
            let mut poll = tokio::time::interval(Duration::from_millis(200));
            poll.tick().await; // skip the immediate first tick
            loop {
                if shutdown.load(Ordering::Acquire) {
                    return;
                }
                tokio::select! {
                    _ = shutdown_notify.notified() => return,
                    _ = poll.tick() => {
                        if node.peers.len() >= 2 {
                            break;
                        }
                    }
                }
            }

            // Initial classification sweep — produces the first
            // `nat:*` tag value that any subsequent announce can
            // emit. Callers that want the tag on their very first
            // announce should `await` this future before calling
            // `announce_capabilities`.
            node.reclassify_nat().await;

            // Periodic re-check. `classify_deadline × 12` is long
            // enough to be cheap (probe traffic is cheap but not
            // free) and short enough that a gateway reboot is
            // reflected in outbound announcements within ~1 min of
            // the next re-announce.
            let mut tick = tokio::time::interval(nonzero_interval(reclassify_interval));
            tick.tick().await; // skip the immediate tick
            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    _ = tick.tick() => {
                        node.reclassify_nat().await;
                    }
                    _ = shutdown_notify.notified() => break,
                }
            }
        })
    }

    /// Spawn a port-mapping task driven by `client`. Drives the
    /// UPnP-IGD / NAT-PMP / PCP lifecycle per
    /// `docs/PORT_MAPPING_PLAN.md`:
    ///
    /// 1. Probe the client; on failure, exit without side
    ///    effects.
    /// 2. On probe success, install a mapping for this mesh's
    ///    bind port. On install success, pin the reflex override
    ///    to the mapped external address — same publish order
    ///    as [`Self::set_reflex_override`].
    /// 3. Renew every
    ///    [`super::traversal::TraversalConfig::port_mapping_renewal`];
    ///    3-strike consecutive failures revoke + clear override.
    /// 4. On shutdown, remove the mapping (best-effort), clear
    ///    the override, and exit.
    ///
    /// Callers that want `MeshNode::start` to auto-spawn a
    /// [`super::traversal::portmap::NullPortMapper`] (the
    /// stage-4b-1 default) should set
    /// [`MeshNodeConfig::try_port_mapping`] to `true`; this
    /// method is the explicit-client path used by stages 4b-4+
    /// (real sequencer) and by unit tests that inject mocks.
    ///
    /// Requires the `port-mapping` cargo feature.
    ///
    /// Takes `&self` (not `&Arc<Self>`) because the task body
    /// only needs `Arc`-clones of specific fields
    /// (`traversal_stats`, `reflex_addr`, `nat_class`,
    /// `reflex_override_active`, `shutdown`, `shutdown_notify`),
    /// not the whole `MeshNode`. Callable from `start()` without
    /// forcing the entire `start()` surface to consume an
    /// `Arc<Self>`.
    #[cfg(feature = "port-mapping")]
    pub fn spawn_port_mapping_loop(
        &self,
        client: Box<dyn super::traversal::portmap::PortMapperClient>,
    ) -> JoinHandle<()> {
        use super::traversal::portmap::{MappingSink, PortMapperTask};
        let sink = MappingSink::new(
            self.traversal_stats.clone(),
            self.reflex_addr.clone(),
            self.nat_class.clone(),
            self.reflex_override_active.clone(),
            self.traversal_publish_mu.clone(),
        );
        let internal_port = self.config.bind_addr.port();
        let renewal = self.traversal_config.port_mapping_renewal;
        let task = PortMapperTask::new(
            client,
            sink,
            internal_port,
            renewal,
            self.shutdown.clone(),
            self.shutdown_notify.clone(),
        );
        tokio::spawn(task.run())
    }

    /// Spawn a periodic sweep that evicts expired entries from the
    /// capability index plus stale `(origin, version)` tuples from
    /// the multi-hop dedup cache. Interval from
    /// `config.capability_gc_interval` (default 60 s). Exits on
    /// `shutdown_notify`.
    /// Spawn the seen-announcements dedup-cache GC loop. The
    /// per-(node_id, version, is_direct) dedup map grows
    /// monotonically as cap-anns arrive; without periodic eviction
    /// it would retain every observation across the node's lifetime.
    /// Eviction window is 2× the announcement TTL so a re-announce's
    /// bumped version isn't confused with the previous one.
    /// Interval from `config.capability_gc_interval` (default 60s).
    fn spawn_capability_gc_loop(&self) -> JoinHandle<()> {
        let seen = self.seen_announcements.clone();
        let interval = self.config.capability_gc_interval;
        let dedup_retention =
            std::time::Duration::from_secs(2 * u64::from(CapabilityAnnouncement::DEFAULT_TTL_SECS));
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();

        tokio::spawn(async move {
            if interval == Duration::MAX {
                let _ = shutdown_notify.notified().await;
                return;
            }
            let mut tick = tokio::time::interval(nonzero_interval(interval));
            tick.tick().await;
            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    _ = tick.tick() => {
                        seen.retain(|_, instant| instant.elapsed() < dedup_retention);
                    }
                    _ = shutdown_notify.notified() => break,
                }
            }
        })
    }

    /// Spawn the periodic capability re-announce loop.
    ///
    /// Capability fold entries carry a TTL (default 300 s) and the
    /// background sweeper evicts them on expiry. Without a periodic
    /// re-announce, a node's own self-entry ages out of its LOCAL fold
    /// ~one TTL after its last announce — after which its callee-side nRPC
    /// capability gate (`may_execute(self, …)`) finds no self-entry and
    /// denies every inbound call (the failure the c128 nRPC bench tripped
    /// once it ran past one TTL) — AND out of every PEER's fold, so it
    /// stops being discoverable.
    ///
    /// Every [`MeshNodeConfig::capability_reannounce_interval`] the loop
    /// re-broadcasts the current capability set via `announce_capabilities`,
    /// refreshing both the local self-index and peers' folds. The TTL it
    /// stamps comes from [`capability_reannounce_ttl`]: `2 ×` the *effective*
    /// broadcast cadence, which is `max(reannounce_interval,
    /// min_announce_interval)` — because `announce_capabilities_with`
    /// rate-limits the network broadcast to `min_announce_interval`, so a
    /// reannounce interval set *below* it cannot actually push to peers any
    /// faster. Stamping `2 × reannounce_interval` there would let peer
    /// entries expire before the throttle releases the next broadcast; folding
    /// the throttle into the TTL keeps them alive. (The local self-index is
    /// refreshed every call regardless of the throttle, so this only matters
    /// for peers.) `Duration::MAX` disables the loop.
    ///
    /// Re-broadcasting needs an owned `Arc` (the per-peer sends go through
    /// `&self`), so the loop upgrades the `Weak` stored by [`Self::start_arc`]
    /// each tick — using a `Weak` (not `Arc`) so the task doesn't keep the
    /// node alive. The loop holds the shared `self_weak` OnceLock (not a
    /// snapshot) and re-reads it each tick, so a bare [`Self::start`]
    /// followed by a later [`Self::start_arc`] enables re-announce rather
    /// than parking the loop forever (RT-3 review Finding 7); until the
    /// weak is set the tick is a harmless no-op.
    fn spawn_capability_reannounce_loop(&self) -> JoinHandle<()> {
        let interval = self.config.capability_reannounce_interval;
        let min_announce = self.config.min_announce_interval;
        let self_weak = self.self_weak.clone();
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        tokio::spawn(async move {
            // Config-disabled → nothing to do (independent of start mode).
            if interval == Duration::MAX {
                let _ = shutdown_notify.notified().await;
                return;
            }
            let ttl = capability_reannounce_ttl(interval, min_announce);
            let mut tick = tokio::time::interval(nonzero_interval(interval));
            // Skip the immediate t=0 tick — the initial announce (if any)
            // already laid the entry down; this loop only refreshes it.
            tick.tick().await;
            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    _ = tick.tick() => {
                        // Re-read the weak each tick: `None` = not started
                        // via `start_arc` (yet); keep ticking so a later
                        // `start_arc` enables the loop.
                        let Some(weak) = self_weak.get() else { continue };
                        let Some(node) = weak.upgrade() else { break };
                        // Decision 8, trigger 2: if the observed
                        // reflex drifted from the published one since
                        // the last announce, run one classification
                        // sweep first so tag + reflex ship together.
                        // No drift → no sweep (cadence guard).
                        #[cfg(feature = "nat-traversal")]
                        node.reclassify_if_reflex_drifted().await;
                        // Re-announce the CURRENT baseline (None) — do
                        // not snapshot-and-overwrite, which would
                        // clobber a concurrent explicit announce
                        // (Finding 8).
                        if let Err(e) = node.announce_from_baseline(None, ttl, true).await {
                            tracing::debug!(error = %e, "capability re-announce failed");
                        }
                    }
                    _ = shutdown_notify.notified() => break,
                }
            }
        })
    }

    /// Spawn the change-driven capability announcer (RT-3,
    /// REALTIME_ROUTING_AND_DISCOVERY_PLAN). Parks on the RT-2
    /// local-caps change signal; on a bump it waits
    /// `announce_debounce` for the burst to settle, marks the
    /// latest generation seen, and broadcasts once via the normal
    /// announce path (so the RT-1 rate limiter + trailing-edge
    /// flush still apply). Capability changes made after `start`
    /// thus propagate mesh-wide without an explicit
    /// `announce_capabilities` call.
    ///
    /// The signal fires only on LOCAL-origin mutations (see
    /// `subscribe_local_caps_changes`) — inbound peer announcements
    /// never wake this loop, which is what prevents a mesh-wide
    /// echo storm. The `changed()` subscription is taken at spawn
    /// time: registrations made before `start` are the initial
    /// explicit announce's job, same as today.
    ///
    /// The loop holds the shared `self_weak` OnceLock and re-reads it
    /// each cycle rather than snapshotting it at spawn, so a bare
    /// [`Self::start`] followed by a later [`Self::start_arc`] enables
    /// the announcer instead of parking it forever (RT-3 review
    /// Finding 7). A change that fires before the weak is set is NOT
    /// consumed: the loop parks (re-checking every
    /// [`Self::CHANGE_ANNOUNCE_START_ARC_POLL`]) until `start_arc` installs
    /// the weak, then announces the current baseline — so a mutation
    /// landing between a bare `start()` and a later `start_arc()`
    /// survives instead of being marked-seen-and-dropped (RT-3 review
    /// P2). Consuming before the weak check dropped it permanently.
    ///
    /// Announce TTL matches the re-announce keep-alive's
    /// (`capability_reannounce_ttl`) so a change-driven entry
    /// survives until the keep-alive refreshes it.
    ///
    /// Poll cadence for the "wait until `start_arc` installs the weak"
    /// park. Only ticks when a change is pending AND the node was
    /// bare-`start()`ed without `start_arc` yet — a narrow, transient
    /// window — so the cost is a single sleeping timer, and the announce
    /// latency after `start_arc` is bounded by this.
    const CHANGE_ANNOUNCE_START_ARC_POLL: Duration = Duration::from_millis(200);

    fn spawn_capability_announce_on_change_loop(&self) -> JoinHandle<()> {
        let debounce = self.config.announce_debounce;
        let reannounce_interval = self.config.capability_reannounce_interval;
        let min_announce = self.config.min_announce_interval;
        let self_weak = self.self_weak.clone();
        let mut change_rx = self.local_caps_changed.subscribe();
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        tokio::spawn(async move {
            // Config-disabled → nothing to do (independent of start mode).
            if debounce == Duration::MAX {
                let _ = shutdown_notify.notified().await;
                return;
            }
            // With the keep-alive disabled, fall back to the explicit
            // announce path's default TTL (300 s) rather than
            // `capability_reannounce_ttl(MAX, ..)` saturating to MAX.
            let ttl = if reannounce_interval == Duration::MAX {
                Duration::from_secs(300)
            } else {
                capability_reannounce_ttl(reannounce_interval, min_announce)
            };
            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    changed = change_rx.changed() => {
                        if changed.is_err() {
                            // Sender dropped — node is gone.
                            return;
                        }
                        // Resolve the node BEFORE consuming the change.
                        // A mutation that lands between a bare `start()`
                        // and a later `start_arc()` must survive for
                        // start_arc's announcer — the old order called
                        // `borrow_and_update` first, marking it seen, so
                        // when `self_weak` was still `None` the change
                        // was dropped permanently (until the next
                        // reannounce or another mutation). Park here,
                        // WITHOUT consuming, re-checking the weak until
                        // start_arc installs it.
                        let node = loop {
                            match self_weak.get() {
                                Some(weak) => match weak.upgrade() {
                                    Some(node) => break node,
                                    None => return, // node dropped
                                },
                                None => {
                                    tokio::select! {
                                        _ = tokio::time::sleep(
                                            Self::CHANGE_ANNOUNCE_START_ARC_POLL) => {}
                                        _ = shutdown_notify.notified() => return,
                                    }
                                }
                            }
                        };
                        // Debounce: let the burst settle so N rapid
                        // registrations coalesce into one broadcast.
                        tokio::select! {
                            _ = tokio::time::sleep(debounce) => {}
                            _ = shutdown_notify.notified() => return,
                        }
                        // Mark everything that landed during the wait +
                        // debounce as seen — it's covered by the announce
                        // below. Later bumps get their own cycle
                        // (missed-wakeup-safe generation).
                        let _ = change_rx.borrow_and_update();
                        // Re-announce the CURRENT baseline (None) so a
                        // concurrent explicit announce isn't clobbered
                        // by a stale snapshot (Finding 8); the merged
                        // tool/nrpc tags are re-derived inside.
                        if let Err(e) = node.announce_from_baseline(None, ttl, true).await {
                            tracing::debug!(
                                error = %e,
                                "change-driven capability announce failed"
                            );
                        }
                        // RT-4: piggyback an event pingwave so the
                        // fresh capability_hash / capability_version
                        // reach multi-hop nodes one flood earlier
                        // than the announcement propagates. Not a
                        // session open — no bookkeeping race — so a
                        // single round, no resend.
                        node.emit_event_pingwave(false);
                    }
                    _ = shutdown_notify.notified() => return,
                }
            }
        })
    }

    /// Spawn the fold-generation GC loop. Walks
    /// [`Self::fold_generations`] on a [`FOLD_GENERATION_GC_INTERVAL`]
    /// cadence and evicts entries whose `last_touched_us` is
    /// more than [`FOLD_GENERATION_GC_MAX_AGE`] behind `now`.
    /// Bounds the counter map's memory for folds with
    /// unbounded class space (e.g. `ReservationFold` keyed on
    /// `resource_id`).
    fn spawn_fold_generation_gc_loop(&self) -> JoinHandle<()> {
        let generations = self.fold_generations.clone();
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        tokio::spawn(async move {
            let mut tick = tokio::time::interval(FOLD_GENERATION_GC_INTERVAL);
            // Skip the immediate first tick — sweeping an empty
            // map is a no-op anyway, but the consistent shape
            // mirrors the other GC loops.
            tick.tick().await;
            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    _ = tick.tick() => {
                        let cutoff_us = super::current_timestamp_micros()
                            .saturating_sub(FOLD_GENERATION_GC_MAX_AGE.as_micros() as u64);
                        generations.retain(|_, e| {
                            e.last_touched_us.load(Ordering::Relaxed) >= cutoff_us
                        });
                    }
                    _ = shutdown_notify.notified() => break,
                }
            }
        })
    }

    /// SI-3: spawn the origin-emission loop (plan §4.4). Sleeps
    /// until the emitter's earliest due beat (or a
    /// `sensing_emitter_notify` wake — registration, status-edge
    /// poke, refusal), collects due beats, evaluates, signs, and
    /// fans each to the branch's live PEER downstreams. `Local`
    /// downstreams are skipped — the local overlay/aggregate
    /// application is SI-4. A branch whose downstream list emptied
    /// retires its stream on the spot (zero idle emission — the
    /// sweep and deregister paths retire too; this is the backstop
    /// that runs even between sweeps, because `downstreams()`
    /// filters expired rows itself).
    ///
    /// Two-phase emission (closure item 5): `collect_due` reserves
    /// seq + schedule under the emitter lock; the user evaluator
    /// runs strictly OUTSIDE it, so an evaluator that calls back
    /// into MeshNode (notify hook, introspection) cannot deadlock
    /// the non-reentrant mutex. Retirement uses the beat's
    /// collect-phase stamp (`retire_if_stale`, closure item 7), so
    /// a registration landing between the table read and the retire
    /// is never darkened.
    ///
    /// `None` when the origin role is dark (plane off or no
    /// persisted incarnation — fail-closed, §4.6).
    fn spawn_sensing_emitter_loop(&self) -> Option<JoinHandle<()>> {
        if self.sensing_emitter.lock().is_none() {
            return None;
        }
        let emitter = self.sensing_emitter.clone();
        let notify = self.sensing_emitter_notify.clone();
        let evaluators = self.sensing_evaluators.clone();
        let table = self.sensing_interest_table.clone();
        #[cfg(feature = "redex")]
        let sensing_leader = self.sensing_leader.clone();
        let identity = self.identity.clone();
        let capability_version = self.capability_version.clone();
        let socket = self.socket.clone();
        let peers = self.peers.clone();
        let addr_to_node = self.addr_to_node.clone();
        let router = self.router.clone();
        let partition_filter = self.partition_filter.clone();
        let local_node_id = self.node_id;
        let observations = self.sensing_observations.clone();
        let overlay = self.sensing_overlay_changed.clone();
        let factor = self.config.continuity_factor;
        let counters = self.sensing_counters.clone();
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        Some(tokio::spawn(async move {
            while !shutdown.load(Ordering::Acquire) {
                let next = { emitter.lock().as_ref().and_then(|e| e.next_due()) };
                let now = Instant::now();
                match next {
                    // Fully idle: zero emission until something
                    // registers or pokes.
                    None => {
                        tokio::select! {
                            _ = notify.notified() => continue,
                            _ = shutdown_notify.notified() => break,
                        }
                    }
                    Some(due) if due > now => {
                        tokio::select! {
                            _ = tokio::time::sleep(due - now) => {}
                            _ = notify.notified() => {}
                            _ = shutdown_notify.notified() => break,
                        }
                        // Re-derive the schedule after any wake —
                        // a notify may have pulled a beat earlier
                        // OR retired the stream we were waiting on.
                        continue;
                    }
                    Some(_) => {}
                }
                // Generation is read at collection time (§3.4) —
                // one read serves every beat in this tick.
                let generation = capability_version.load(Ordering::Relaxed);
                // Phase 1 (under the emitter lock): reserve seq +
                // re-arm schedules. NO user code runs in here.
                let beats = {
                    let mut slot = emitter.lock();
                    let Some(origin) = slot.as_mut() else { break };
                    origin.collect_due(now, generation)
                };
                for beat in beats {
                    let digest = beat.key().interest_digest;
                    let stamp = beat.stamp();
                    let branch =
                        sensing::ProviderInterestKey::new(beat.key().clone(), local_node_id);
                    let downstreams = { table.lock().downstreams(&branch, now) };
                    if downstreams.is_empty() {
                        // Stamped retire (closure item 7): a
                        // registration that landed after collect
                        // bumped the stream's stamp past the beat's
                        // and survives this.
                        if let Some(origin) = emitter.lock().as_mut() {
                            origin.retire_if_stale(&digest, stamp);
                        }
                        continue;
                    }
                    let mut local_interval: Option<Duration> = None;
                    let mut leader_row = false;
                    let peer_downstreams: Vec<u64> = downstreams
                        .into_iter()
                        .filter_map(|downstream| match downstream {
                            sensing::DownstreamId::Peer(node) => Some(node),
                            // SI-4 review P1 (self-provider watch):
                            // the origin's own Local row consumes
                            // the SAME signed beats below.
                            sensing::DownstreamId::Local => {
                                local_interval = Some(
                                    table
                                        .lock()
                                        .downstream_entry(&branch, sensing::DownstreamId::Local)
                                        .map(|row| row.requested_sample_interval)
                                        .unwrap_or(Duration::from_millis(50)),
                                );
                                None
                            }
                            // SI-4 re-review P0 (leader-as-
                            // provider): a co-located leader that
                            // resolved THIS node consumes the same
                            // signed beats — its relay fans them to
                            // the real consumer rows below.
                            sensing::DownstreamId::Leader => {
                                leader_row = true;
                                None
                            }
                        })
                        .collect();
                    // Phase 2 (NO emitter lock): run the user
                    // evaluator, then seal — `into_unsigned` is
                    // pure. Clone the Arc out of the map entry
                    // before evaluating so the shard guard drops
                    // first.
                    let evaluation = evaluators
                        .get(&beat.key().capability_id)
                        .map(|entry| entry.value().clone())
                        .map(|evaluator| evaluator.evaluate(&beat.request()));
                    let unsigned = beat.into_unsigned(evaluation);
                    let Ok(signed) = sensing::sign_attestation(&identity, unsigned) else {
                        continue;
                    };
                    // SI-7: one signed origin beat produced — fanned
                    // to every downstream below, never multiplied by
                    // watcher count (the coalescing economic claim).
                    counters
                        .attestations_emitted
                        .fetch_add(1, Ordering::Relaxed);
                    // SI-4 review P1: the self-provider Local watch
                    // consumes the signed beat through the SAME
                    // attestation + continuity semantics as any
                    // consumer — the origin's own live stream is
                    // continuity-bearing by definition. The wire
                    // cache insert also serves the leader fan-out
                    // below, which resolves its identical signed
                    // bytes from `latest` on (incarnation, seq).
                    if local_interval.is_some() || leader_row {
                        observations
                            .lock()
                            .latest
                            .insert(branch.clone(), signed.clone());
                    }
                    if let Some(interval) = local_interval {
                        let moved = {
                            let mut observations = observations.lock();
                            observations
                                .feed_consumer_cell(&branch, &signed, true, interval, factor, now)
                        };
                        if moved {
                            overlay.send_modify(|generation| {
                                *generation = generation.wrapping_add(1);
                            });
                        }
                    }
                    // SI-4 re-review P0: locally signed beats
                    // dispatch three-way like any delivery — the
                    // Leader row hands the beat to the leader
                    // relay, whose fan-out goes out as real frames.
                    #[cfg(feature = "redex")]
                    if leader_row {
                        if let Ok(semantic) =
                            sensing::semantic_attestation(&branch.interest, &signed)
                        {
                            let deliveries = {
                                let mut slot = sensing_leader.lock();
                                match slot.as_mut() {
                                    Some(leader) => leader.on_attestation(now, &semantic, true),
                                    None => Vec::new(),
                                }
                            };
                            dispatch_sensing_leader_deliveries(
                                &socket,
                                &peers,
                                &addr_to_node,
                                &router,
                                &partition_filter,
                                local_node_id,
                                &observations,
                                &overlay,
                                factor,
                                deliveries,
                                now,
                            );
                        }
                    }
                    #[cfg(not(feature = "redex"))]
                    let _ = leader_row;
                    if peer_downstreams.is_empty() {
                        continue;
                    }
                    let Ok(bytes) = sensing::encode_attestation(&signed) else {
                        continue;
                    };
                    for node in peer_downstreams {
                        spawn_sensing_frame_send(
                            &socket,
                            &peers,
                            &addr_to_node,
                            &router,
                            &partition_filter,
                            local_node_id,
                            node,
                            sensing::SUBPROTOCOL_READINESS_ATTESTATION as u64,
                            sensing::SUBPROTOCOL_READINESS_ATTESTATION,
                            bytes.clone(),
                        );
                    }
                }
            }
        }))
    }

    /// Spawn a periodic sweep that evicts subscribers whose tokens
    /// have expired. Walks the roster by peer (via
    /// `peer_entity_ids`) and, for every `require_token` channel the
    /// peer is subscribed to, runs the full token-cache check. An
    /// expired or invalid entry causes:
    ///
    /// 1. Revocation in the [`AuthGuard`] (so the next publish
    ///    fan-out sees the denial instantly, before the next
    ///    sweep tick).
    /// 2. Removal from the [`SubscriberRoster`] (so `members()`
    ///    returns the pruned list).
    ///
    /// Interval from `config.token_sweep_interval` (default 30 s).
    /// Skipped when the `channel_configs` registry is `None` — a
    /// node without a registry has no `require_token` channels to
    /// begin with. Similarly, skipped when `token_cache` is `None`.
    fn spawn_token_sweep_loop(&self) -> JoinHandle<()> {
        let roster = self.roster.clone();
        let guard = self.auth_guard.clone();
        let cache = self.token_cache.clone();
        let peer_entity_ids = self.peer_entity_ids.clone();
        let channel_configs = self.channel_configs.clone();
        let subscriber_chains = self.subscriber_chains.clone();
        let interval = self.config.token_sweep_interval;
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();

        tokio::spawn(async move {
            // `Duration::MAX` is the documented sentinel for
            // "disable the periodic sweep" — callers rely on
            // the lazy expiry check in `publish` instead.
            // `tokio::time::interval(Duration::MAX)` panics
            // when its `Instant::now() + period` overflows, so
            // we skip the tick machinery entirely and just wait
            // for shutdown.
            if interval == Duration::MAX {
                let _ = shutdown_notify.notified().await;
                return;
            }
            // Same zero-guard as `spawn_capability_gc_loop` —
            // tokio panics if the period is zero.
            let mut tick = tokio::time::interval(nonzero_interval(interval));
            // First tick fires immediately; skip it so we don't
            // sweep empty state before any subscribes have landed.
            tick.tick().await;
            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    _ = tick.tick() => {
                        sweep_expired_subscribers(
                            &roster,
                            &guard,
                            cache.as_ref(),
                            &peer_entity_ids,
                            channel_configs.as_ref(),
                            &subscriber_chains,
                        );
                    }
                    _ = shutdown_notify.notified() => break,
                }
            }
        })
    }

    /// Spawn the main receive loop.
    ///
    /// This is the heart of the mesh node. Every packet from every peer
    /// arrives here. The loop:
    /// 1. Looks up the session by source address
    /// 2. For local packets: decrypts and queues events
    /// 3. For forwarded packets: passes to router (no decryption)
    /// 4. For heartbeats: updates failure detector
    fn spawn_receive_loop(&self) -> JoinHandle<()> {
        let socket = self.socket.socket_arc();
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        // Only read where the batched path can actually run (Linux + feature);
        // elsewhere the per-packet path is the only option.
        #[cfg(all(target_os = "linux", feature = "batched-ingress"))]
        let batched_ingress = self.config.batched_ingress;

        let ctx = DispatchCtx {
            local_node_id: self.node_id,
            peers: self.peers.clone(),
            addr_to_node: self.addr_to_node.clone(),
            peer_addrs: self.peer_addrs.clone(),
            router: self.router.clone(),
            failure_detector: self.failure_detector.clone(),
            inbound: self.inbound.clone(),
            #[cfg(feature = "cortex")]
            rpc_inbound_dispatchers: self.rpc_inbound_dispatchers.clone(),
            num_shards: self.config.num_shards,
            migration_handler: self.migration_handler.clone(),
            #[cfg(feature = "redex")]
            replication_inbound_router: self.replication_inbound_router.clone(),
            #[cfg(feature = "meshdb")]
            meshdb_inbound_router: self.meshdb_inbound_router.clone(),
            fold_router: self.fold_router.clone(),
            #[cfg(feature = "dataforts")]
            greedy_observer: self.greedy_observer.clone(),
            #[cfg(feature = "dataforts")]
            blob_transfer_engine: self.blob_transfer_engine.clone(),
            pending_handshakes: self.pending_handshakes.clone(),
            pending_direct_initiators: self.pending_direct_initiators.clone(),
            static_keypair: self.static_keypair.clone(),
            psk: self.config.psk,
            socket: self.socket.clone(),
            proximity_graph: self.proximity_graph.clone(),
            partition_filter: self.partition_filter.clone(),
            enable_route_withdraw: self.config.enable_route_withdraw,
            route_withdraw_seq: self.route_withdraw_seq.clone(),
            route_withdraw_damper: self.route_withdraw_damper.clone(),
            route_withdraw_gate: self.route_withdraw_gate.clone(),
            route_withdraw_cascades_inflight: self.route_withdraw_cascades_inflight.clone(),
            enable_sensing_coalescing: self.config.enable_sensing_coalescing,
            sensing_interest_ttl: self.config.sensing_interest_ttl,
            sensing_interest_table: self.sensing_interest_table.clone(),
            sensing_counters: self.sensing_counters.clone(),
            sensing_over_cap: self.sensing_over_cap.clone(),
            sensing_local_root: self.sensing_local_root,
            sensing_fleet_scope: self.config.sensing_owner_root.is_some(),
            sensing_upstream_damper: self.sensing_upstream_damper.clone(),
            #[cfg(feature = "redex")]
            sensing_leader: self.sensing_leader.clone(),
            #[cfg(feature = "redex")]
            sensing_fold_coalescer: self.sensing_fold_coalescer.clone(),
            #[cfg(feature = "redex")]
            sensing_local_entity_root: sensing::AudienceScopeCommitment::owner_root(
                self.identity.entity_id(),
            ),
            sensing_emitter: self.sensing_emitter.clone(),
            sensing_emitter_notify: self.sensing_emitter_notify.clone(),
            signing_identity: self.identity.clone(),
            capability_version: self.capability_version.clone(),
            sensing_observer_gate: self.sensing_observer_gate.clone(),
            sensing_continuity_factor: self.config.continuity_factor,
            sensing_overlay_changed: self.sensing_overlay_changed.clone(),
            sensing_capability_interests: self.sensing_capability_interests.clone(),
            sensing_observations: self.sensing_observations.clone(),
            pending_stream_grants: self.pending_stream_grants.clone(),
            pending_stream_grants_notify: self.pending_stream_grants_notify.clone(),
            control_stats: self.control_stats.clone(),
            packet_pool_size: self.config.packet_pool_size,
            default_reliable: self.config.default_reliable,
            session_timeout: self.config.session_timeout,
            roster: self.roster.clone(),
            channel_configs: self.channel_configs.clone(),
            pending_membership_acks: self.pending_membership_acks.clone(),
            #[cfg(feature = "nat-traversal")]
            pending_reflex_probes: self.pending_reflex_probes.clone(),
            #[cfg(feature = "nat-traversal")]
            pending_punch_introduces: self.pending_punch_introduces.clone(),
            #[cfg(feature = "nat-traversal")]
            pending_punch_acks: self.pending_punch_acks.clone(),
            #[cfg(feature = "nat-traversal")]
            punch_observers: self.punch_observers.clone(),
            #[cfg(feature = "nat-traversal")]
            rendezvous_budgets: self.rendezvous_budgets.clone(),
            #[cfg(feature = "nat-traversal")]
            traversal_config: self.traversal_config.clone(),
            max_channels_per_peer: self.config.max_channels_per_peer,
            capability_fold: self.capability_fold.clone(),
            ack_ranges_peer_cache: self.ack_ranges_peer_cache.clone(),
            #[cfg(feature = "dataforts")]
            capability_set_cache: self.capability_set_cache.clone(),
            seen_announcements: self.seen_announcements.clone(),
            require_signed_capabilities: self.config.require_signed_capabilities,
            local_subnet: self.local_subnet,
            local_subnet_policy: self.local_subnet_policy.clone(),
            peer_subnets: self.peer_subnets.clone(),
            subnet_gateway: self.subnet_gateway.clone(),
            peer_entity_ids: self.peer_entity_ids.clone(),
            origin_hash_to_node: self.origin_hash_to_node.clone(),
            session_id_to_node: self.session_id_to_node.clone(),
            token_cache: self.token_cache.clone(),
            subscriber_chains: self.subscriber_chains.clone(),
            auth_guard: self.auth_guard.clone(),
            auth_failures: self.auth_failures.clone(),
            max_auth_failures_per_window: self.config.max_auth_failures_per_window,
            auth_failure_window: self.config.auth_failure_window,
            auth_throttle_duration: self.config.auth_throttle_duration,
        };

        // Local receiver abstraction so the select! loop body below is
        // written once across the per-packet path and the Linux batched-
        // ingress path. The `recv()` contract is identical (one packet at a
        // time, arrival order); only construction differs.
        enum IngressReceiver {
            Single(PacketReceiver),
            #[cfg(all(target_os = "linux", feature = "batched-ingress"))]
            Batched(super::transport::BatchedPacketReceiver),
        }
        impl IngressReceiver {
            #[inline]
            async fn recv(&mut self) -> std::io::Result<(Bytes, SocketAddr)> {
                match self {
                    IngressReceiver::Single(r) => r.recv().await,
                    #[cfg(all(target_os = "linux", feature = "batched-ingress"))]
                    IngressReceiver::Batched(r) => r.recv().await,
                }
            }

            /// Whether a `ConnectionReset` from `recv()` means the receiver is
            /// permanently dead and the loop must stop. True only for the
            /// batched receiver, whose `recv()` returns `ConnectionReset` once
            /// its backing thread has exited (and on every call thereafter, so
            /// looping would busy-spin). For the per-packet receiver a
            /// `ConnectionReset` is a transient socket error (e.g. an ICMP
            /// port-unreachable surfaced on the next recv) to log and tolerate.
            #[inline]
            fn reset_is_fatal(&self) -> bool {
                match self {
                    IngressReceiver::Single(_) => false,
                    #[cfg(all(target_os = "linux", feature = "batched-ingress"))]
                    IngressReceiver::Batched(_) => true,
                }
            }
        }

        tokio::spawn(async move {
            // Opt-in (default off) batched ingress on Linux; everywhere else,
            // and when the flag is off, the per-packet path is unchanged. See
            // MeshNodeConfig::batched_ingress for the latency/throughput
            // trade-off this gates.
            let mut receiver = {
                #[cfg(all(target_os = "linux", feature = "batched-ingress"))]
                {
                    if batched_ingress {
                        IngressReceiver::Batched(super::transport::BatchedPacketReceiver::new(
                            socket,
                        ))
                    } else {
                        IngressReceiver::Single(PacketReceiver::new(socket))
                    }
                }
                // No batched path here: either not Linux, or the
                // `batched-ingress` feature isn't built in.
                #[cfg(not(all(target_os = "linux", feature = "batched-ingress")))]
                {
                    IngressReceiver::Single(PacketReceiver::new(socket))
                }
            };
            // A ConnectionReset is fatal only for the batched receiver (its
            // recv thread died); for the per-packet path it's transient. Decide
            // once by receiver variant rather than re-checking the flag.
            let reset_is_fatal = receiver.reset_is_fatal();

            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    result = receiver.recv() => {
                        match result {
                            Ok((data, source)) => {
                                Self::dispatch_packet(data, source, &ctx);
                            }
                            // Batched receiver: a ConnectionReset means its recv
                            // thread exited (transport.rs) and every future
                            // recv() will also fail — stop rather than busy-spin.
                            // The per-packet path treats it as transient (below).
                            Err(e)
                                if reset_is_fatal
                                    && e.kind() == std::io::ErrorKind::ConnectionReset =>
                            {
                                if !shutdown.load(Ordering::Acquire) {
                                    tracing::warn!(
                                        "mesh batch receiver thread exited, stopping receiver"
                                    );
                                }
                                break;
                            }
                            Err(e) => {
                                if !shutdown.load(Ordering::Acquire) {
                                    tracing::warn!(error = %e, "mesh receive error");
                                }
                            }
                        }
                    }
                    _ = shutdown_notify.notified() => {
                        break;
                    }
                }
            }
        })
    }

    /// Dispatch a single received packet.
    ///
    /// This is the routing decision point:
    /// - Handshake packets are ignored (handled during connect/accept)
    /// - Heartbeat packets update the failure detector
    /// - Data packets are decrypted if local, forwarded if not
    fn dispatch_packet(data: Bytes, source: SocketAddr, ctx: &DispatchCtx) {
        // Partition filter: silently drop packets from blocked peers
        if ctx.partition_filter.contains(&source) {
            return;
        }

        // Pre-session keep-alive recognition. Keep-alives are
        // 14-byte packets with `KEEPALIVE_MAGIC` at offset 0. The
        // receive loop fires any observer watching `source` and
        // returns — these packets never continue down the
        // session-decrypt path because no session exists between
        // the peers at punch time. See
        // `traversal::rendezvous`'s module docstring for the
        // wire layout rationale.
        //
        // Ordered BEFORE the pingwave check because both reach
        // into `data[0..2]`; keep-alives are shorter (14 vs 72)
        // so the length guard disambiguates without cost.
        #[cfg(feature = "nat-traversal")]
        if data.len() == super::traversal::rendezvous::KEEPALIVE_LEN {
            if let Some(ka) = super::traversal::rendezvous::decode_keepalive(&data) {
                // Fire (and consume) the observer only when the
                // keep-alive's claimed sender matches the counterpart
                // this observer is waiting for — the expected node id
                // is stored alongside the oneshot. A stray or spoofed
                // keep-alive from the right source addr but the wrong
                // (or zeroed) sender id leaves the observer in place,
                // armed for a later valid keep-alive, instead of
                // burning the punch attempt; the source-addr key alone
                // is not an authenticator. Validating here, *before*
                // removal, is what keeps a single bad first packet
                // from permanently failing an otherwise-good punch.
                if let Some((_, (_expected, tx))) = ctx
                    .punch_observers
                    .remove_if(&source, |_, (expected, _)| ka.sender_node_id == *expected)
                {
                    let _ = tx.send(ka);
                }
                return;
            }
        }

        // Check for pingwave. Pingwaves are a fixed 72-byte wire format
        // that does NOT carry the Net header magic. We reject anything
        // that starts with `MAGIC` so a legitimate Net packet that happens
        // to be 72 bytes is never mis-handled (defense in depth — the
        // current Net packet layout has an 80-byte minimum, but relying
        // on that is fragile). The leading-MAGIC check does not
        // authenticate pingwaves against a spoofing attacker; that is a
        // separate protocol concern.
        if data.len() == EnhancedPingwave::SIZE && u16::from_le_bytes([data[0], data[1]]) != MAGIC {
            if let Some(pw) = EnhancedPingwave::from_bytes(&data) {
                let origin_nid = graph_id_to_node_id(&pw.origin_id);

                // DV loop-avoidance rule 1: origin self-check. Drop
                // any pingwave claiming `origin_id == self_id`. This
                // defends against (a) a buggy peer echoing our own
                // origin back at us, and (b) a stale buffered
                // pingwave from a partitioned-then-healed peer.
                if origin_nid == ctx.local_node_id {
                    return;
                }

                // DV loop-avoidance rule 2: MAX_HOPS cap. TTL bounds
                // forwarding; MAX_HOPS bounds install. A pingwave
                // claiming an inflated hop_count can't populate a
                // usable route or graph edge.
                if pw.hop_count >= MAX_HOPS {
                    return;
                }

                // DV loop-avoidance rule 4: only accept pingwaves
                // from registered direct peers. An unknown source
                // addr means either (a) a stale packet from before
                // a handshake was torn down, (b) a peer that never
                // handshaked, or (c) an attacker injecting forged
                // pingwaves. In all three cases we refuse to install
                // route or graph state — otherwise an unauthenticated
                // sender could poison our routing table by claiming
                // to be a next-hop for arbitrary origins.
                let from_node_id = match ctx.addr_to_node.get(&source) {
                    Some(e) => *e.value(),
                    None => return,
                };

                // Metric for the indirect route `(origin, via=source)`:
                // `hop_count + 2`. The `+2` keeps direct routes
                // (metric 1) strictly better than any pingwave route —
                // `add_route_with_metric` preserves the better entry.
                // Captured from the ORIGINAL hop_count before `pw` is
                // moved into admission (which advances it on forward).
                let metric = (pw.hop_count as u16).saturating_add(2);

                // Hand to the proximity graph to dedup + update nodes +
                // edges. `source` is guaranteed registered at this
                // point, so `from_graph_id` faithfully attributes
                // the edge to the forwarding peer's node_id.
                //
                // Admission MUST precede the route install: a duplicate
                // / byte-identical replay is rejected here BEFORE any
                // routing mutation, so it cannot resurrect a route (or
                // edge) that a withdrawal just removed (RT-5 review). We
                // install/refresh the route only for an ACCEPTED
                // pingwave, and forward only an accepted-and-live one.
                let from_graph_id = node_id_to_graph_id(from_node_id);
                let admission = ctx
                    .proximity_graph
                    .admit_pingwave_from(pw, from_graph_id, source);
                let fwd_pw = match admission {
                    PingwaveAdmission::RejectedDuplicate => return,
                    PingwaveAdmission::AcceptedNoForward => {
                        ctx.router
                            .routing_table()
                            .add_route_with_metric(origin_nid, source, metric);
                        return;
                    }
                    PingwaveAdmission::AcceptedAndForward(fwd_pw) => {
                        ctx.router
                            .routing_table()
                            .add_route_with_metric(origin_nid, source, metric);
                        fwd_pw
                    }
                };
                {
                    let fwd_bytes = fwd_pw.to_bytes();
                    let socket = ctx.socket.clone();
                    let peers = ctx.peers.clone();
                    let filter = ctx.partition_filter.clone();
                    let router = ctx.router.clone();
                    // DV loop-avoidance rule 3: split horizon on
                    // re-broadcast. If we installed `(origin_nid,
                    // next_hop=X)` — i.e. we'd use X to reach the
                    // origin — don't re-advertise the origin on the
                    // link to X. Prevents X from learning "we can
                    // reach origin in N+1 hops" and installing a
                    // backward loop.
                    tokio::spawn(async move {
                        let next_hop = router.routing_table().lookup(origin_nid);
                        for entry in peers.iter() {
                            let addr = entry.value().addr;
                            if addr == source {
                                continue; // never send back to sender
                            }
                            if Some(addr) == next_hop {
                                continue; // split horizon: that's our path to origin
                            }
                            if filter.contains(&addr) {
                                continue;
                            }
                            let _ = socket.send_to(&fwd_bytes, addr).await;
                        }
                    });
                }
                return;
            }
        }

        let local_node_id = ctx.local_node_id;
        let peers = &ctx.peers;
        let router = &ctx.router;
        let failure_detector = &ctx.failure_detector;
        // Distinguish routed packets from direct packets.
        //
        // Bytes 0-1 of a direct Net packet are [`MAGIC`] (`0x4E45`);
        // bytes 0-1 of a routing header are [`ROUTING_MAGIC`]
        // (`0x5254`). Anything else is malformed and dropped. The
        // previous discriminator ("anything that isn't MAGIC is
        // routed") mis-classified routed packets whenever the
        // recipient's own `node_id` had low-16-bits equal to
        // `MAGIC` — 1-in-65 536 node_ids — silently dropping
        // routed traffic at the AEAD layer.
        let first2 = if data.len() >= 2 {
            u16::from_le_bytes([data[0], data[1]])
        } else {
            0
        };
        let is_routed =
            first2 == ROUTING_MAGIC && data.len() >= ROUTING_HEADER_SIZE + protocol::HEADER_SIZE;
        let is_direct = first2 == MAGIC;
        if !is_routed && !is_direct {
            // Malformed / unrecognized prefix — drop silently.
            return;
        }

        if is_routed {
            // Routed packet: parse routing header, decide forward or local
            if let Some(routing_header) = RoutingHeader::from_bytes(&data[..ROUTING_HEADER_SIZE]) {
                if routing_header.dest_id == local_node_id {
                    // For us — strip routing header, process the inner Net packet.
                    // The inner packet is encrypted with the *sender's* session key
                    // (not the relay's), so we look up the session by session_id
                    // in the inner header, not by source address.
                    let inner = data.slice(ROUTING_HEADER_SIZE..);
                    let parsed = match ParsedPacket::parse(inner, source) {
                        Some(p) => p,
                        None => return,
                    };
                    // Heartbeats are link-local and don't make sense over
                    // the routing layer — drop.
                    if parsed.header.flags.is_heartbeat() {
                        return;
                    }
                    // Routed handshake arrival. Strip routing header and
                    // hand to the responder/msg2 dispatcher.
                    if parsed.header.flags.is_handshake() {
                        Self::handle_routed_handshake(&parsed, &routing_header, source, ctx);
                        return;
                    }
                    // PERF_AUDIT §2.4 — O(1) reverse-index lookup
                    // (`session_id → node_id`) instead of the prior
                    // O(peers) `iter().find(session_id matches)` scan.
                    // `dispatch_packet` runs on the single receive
                    // task, so the scan serialized ingress at relay
                    // peer counts. The reverse index is populated
                    // alongside `peers.insert` at every registration
                    // site (connect / accept / routed-msg1) and
                    // cleared alongside `peers.remove` in the sweep
                    // loop, so a hit here resolves to the same
                    // `(node_id, session)` pair the scan would have
                    // returned.
                    //
                    // Defensive cross-check: confirm the resolved
                    // entry's session actually carries the matching
                    // session_id. A stale reverse-index entry (the
                    // peer was re-handshaken under the same node_id
                    // but a new session_id, and the rollback /
                    // eviction race left us pointing at the new
                    // entry while the inbound packet was for the
                    // old) would otherwise route the packet to the
                    // wrong session and AEAD would fail open as a
                    // silent drop. The check keeps behavior aligned
                    // with the pre-fix scan, which would have
                    // returned None in the same scenario.
                    let session_id = parsed.header.session_id;
                    let matched = ctx
                        .session_id_to_node
                        .get(&session_id)
                        .map(|e| *e.value())
                        .and_then(|node_id| {
                            peers
                                .get(&node_id)
                                .map(|e| (node_id, e.value().session.clone()))
                        })
                        .filter(|(_, session)| session.session_id() == session_id);
                    if let Some((peer_node_id, session)) = matched {
                        Self::process_local_packet(parsed, peer_node_id, &session, ctx);
                        session.touch();
                    }
                } else {
                    // Not for us — forward without decrypting (header-only
                    // routing). We send via the main socket so the
                    // receiving node sees `source` = our bound addr,
                    // which it can use as a reply path. `router.start()`'s
                    // internal scheduler has a separate ephemeral socket
                    // and would make `source` unusable for replies.
                    if routing_header.is_expired() {
                        return;
                    }
                    let next_hop = match router.routing_table().lookup(routing_header.dest_id) {
                        Some(addr) => addr,
                        None => return,
                    };
                    if ctx.partition_filter.contains(&next_hop) {
                        return;
                    }
                    let mut fwd_header = routing_header;
                    fwd_header.forward();
                    // Fast path (PERF_AUDIT §2.5 — port of perf #18
                    // already in router.rs:728): when the inbound
                    // `data` is sole-owned (the typical case for UDP
                    // packets just received from the socket), patch
                    // the routing header bytes in place. Refcount
                    // bump only — no fresh allocation, no body
                    // memcpy. Pre-fix this allocated a fresh
                    // BytesMut the size of the entire packet and
                    // memcpy'd the whole body (~8 KB) per forward;
                    // for a relay node moving high pps, this was
                    // bandwidth-class waste. Slow path stays the
                    // pre-fix allocation strategy for the rare case
                    // where someone holds an outstanding clone.
                    let forwarded = match data.try_into_mut() {
                        Ok(mut mut_data) => {
                            fwd_header.write_at(&mut mut_data[..ROUTING_HEADER_SIZE]);
                            mut_data.freeze()
                        }
                        Err(orig_data) => {
                            let mut new_data = bytes::BytesMut::with_capacity(orig_data.len());
                            new_data.extend_from_slice(&fwd_header.to_bytes());
                            new_data.extend_from_slice(&orig_data[ROUTING_HEADER_SIZE..]);
                            new_data.freeze()
                        }
                    };
                    let socket = ctx.socket.clone();
                    tokio::spawn(async move {
                        let _ = socket.send_to(&forwarded, next_hop).await;
                    });
                }
            }
            return;
        }

        // Direct packet (no routing header) — standard path.
        //
        // `session_id` is the authoritative logical-peer key. `addr_to_node`
        // gives a fast path when source addr maps to exactly one session,
        // but we must still validate session_id against the resolved peer
        // and fall back to a session_id scan if it doesn't match. Otherwise
        // two peers that share a wire address (e.g., a direct peer and a
        // relay-peer reachable via the same relay addr) would collide.
        let parsed = match ParsedPacket::parse(data, source) {
            Some(p) => p,
            None => return,
        };

        if parsed.header.flags.is_handshake() {
            // If a direct initiator has registered an oneshot
            // keyed by this source, forward the parsed payload
            // bytes through it. Otherwise (no entry, e.g.
            // responder side or unsolicited handshake) fall
            // through to drop. Without this routing, polling
            // `socket_arc.recv_from` directly from
            // `try_handshake_initiator` would race this dispatch
            // loop — tokio routes a UDP datagram to exactly one
            // waiter — and the response could be swallowed by
            // either consumer.
            if let Some((_, tx)) = ctx.pending_direct_initiators.remove(&source) {
                let _ = tx.send(parsed.payload);
            }
            return;
        }

        let session_id = parsed.header.session_id;
        let matched = ctx
            .addr_to_node
            .get(&source)
            .map(|e| *e.value())
            .and_then(|nid| peers.get(&nid))
            .filter(|p| p.session.session_id() == session_id)
            .map(|p| (p.value().node_id, p.value().session.clone()))
            .or_else(|| {
                peers
                    .iter()
                    .find(|e| e.value().session.session_id() == session_id)
                    .map(|e| (e.value().node_id, e.value().session.clone()))
            });
        let (peer_node_id, session) = match matched {
            Some(x) => x,
            None => return,
        };

        if parsed.header.flags.is_heartbeat() {
            // `verify_and_touch_heartbeat` fuses AEAD verify with
            // `session.touch()` so a future caller can't reorder
            // them or forget to touch on success — the type
            // system enforces verify-then-touch atomically.
            // Fast-pathing the heartbeat without verifying the
            // AEAD tag would let an attacker with the cleartext
            // `session_id` (visible on every prior data packet)
            // and the source UDP address spoof heartbeats from
            // `peer_addr`, indefinitely defeating session-idle
            // timeout and injecting false
            // `failure_detector.heartbeat(...)` notifications.
            // The failure-detector callback is mesh-specific
            // (legacy adapter has no such observer) and stays
            // here, after a successful verify.
            if !session.verify_and_touch_heartbeat(&parsed) {
                return;
            }
            failure_detector.heartbeat(peer_node_id, source);
            return;
        }

        Self::process_local_packet(parsed, peer_node_id, &session, ctx);
        session.touch();
    }

    /// Handle a routed handshake packet that arrived at this node.
    ///
    /// Two cases, discriminated by whether we have a pending initiator
    /// state for `routing_header.src_id`:
    ///
    /// 1. **msg2 for an in-flight initiator.** We started a `connect_via`
    ///    earlier and registered a `PendingHandshake` keyed by the
    ///    responder's node_id. The arriving packet completes that
    ///    initiator state — we run `read_message`, derive keys, and
    ///    signal the caller via the oneshot.
    ///
    /// 2. **msg1 from a new initiator.** We build a responder state with
    ///    the prologue derived from `(routing_header.src_id, self.node_id)`,
    ///    read msg1, write msg2, and send msg2 back via the routing
    ///    table (reversing src/dest in the routing header). On success
    ///    we register the new peer with the routing-path addr (the
    ///    immediate upstream `source`) so that subsequent routed data
    ///    finds a session.
    fn handle_routed_handshake(
        parsed: &ParsedPacket,
        routing_header: &RoutingHeader,
        source: SocketAddr,
        ctx: &DispatchCtx,
    ) {
        // Routing id of the remote party: what we see in the routing
        // header's 32-bit src_id, zero-extended into u64 so it can sit
        // alongside full node_ids in maps without ambiguity.
        let peer_routing_id = routing_header.src_id as u64;

        // Case 1: msg2 for an in-flight initiator. Look up pending state
        // by routing id (that's how it was keyed on insert).
        if let Some((_, pending)) = ctx.pending_handshakes.remove(&peer_routing_id) {
            let PendingHandshake { mut noise, tx } = pending;
            let result = (|| -> Result<SessionKeys, CryptoError> {
                noise.read_message(&parsed.payload)?;
                noise.into_session_keys()
            })();
            let _ = tx.send(result);
            return;
        }

        // Case 2: msg1 from a new initiator.
        //
        // Prologue binds (peer_routing_id, self_routing_id) — same u32
        // projection the initiator used. Full u64 identities don't
        // fit in the routing header (src_id is u32), so we bind what
        // both sides CAN see, and carry the full src node_id inside
        // the Noise payload where it's AEAD-authenticated.
        let self_routing_id = routing_id(ctx.local_node_id);
        let prologue = handshake_prologue(peer_routing_id, self_routing_id);
        let mut noise =
            match NoiseHandshake::responder_with_prologue(&ctx.psk, &ctx.static_keypair, &prologue)
            {
                Ok(n) => n,
                Err(e) => {
                    tracing::warn!(error = %e, "routed handshake: responder build failed");
                    return;
                }
            };
        // Capture the initiator's ephemeral (first 32 bytes of
        // NKpsk0 msg1, in the clear) BEFORE read_message
        // consumes the wire bytes. The replay guard in
        // `routed_rotation_outcome` matches both static and
        // ephemeral; same static + same ephemeral = exact replay
        // (passive attacker resending captured bytes); same
        // static + fresh ephemeral = legitimate re-handshake.
        if parsed.payload.len() < 32 {
            tracing::warn!(
                "routed handshake: msg1 too short ({}); NKpsk0 msg1 must carry a 32-byte ephemeral prefix",
                parsed.payload.len()
            );
            return;
        }
        let mut initiator_ephemeral = [0u8; 32];
        initiator_ephemeral.copy_from_slice(&parsed.payload[..32]);
        let msg1_payload = match noise.read_message(&parsed.payload) {
            Ok(p) => p,
            Err(e) => {
                tracing::warn!(error = %e, "routed handshake: read_message failed (msg1 tampered or wrong PSK)");
                return;
            }
        };

        // Extract the initiator's full u64 node_id from the decrypted
        // payload. Verify its routing id matches the one we got on the
        // wire — a mismatch means the payload was crafted for a
        // different address than what arrived.
        if msg1_payload.len() < 8 {
            tracing::warn!(
                "routed handshake: msg1 payload too short ({}); need 8 bytes of src node_id",
                msg1_payload.len()
            );
            return;
        }
        #[expect(
            clippy::unwrap_used,
            reason = "msg1_payload.len() >= 8 guard above; [..8].try_into::<[u8; 8]>() is infallible"
        )]
        let peer_node_id = u64::from_le_bytes(msg1_payload[..8].try_into().unwrap());
        if routing_id(peer_node_id) != peer_routing_id {
            tracing::warn!(
                payload = format!("{:#x}", peer_node_id),
                routing = format!("{:#x}", peer_routing_id),
                "routed handshake: src_node_id in payload does not match routing header"
            );
            return;
        }

        let msg2 = match noise.write_message(&[]) {
            Ok(m) => m,
            Err(e) => {
                tracing::warn!(error = %e, "routed handshake: write_message failed");
                return;
            }
        };
        let keys = match noise.into_session_keys() {
            Ok(k) => k,
            Err(e) => {
                tracing::warn!(error = %e, "routed handshake: key extraction failed");
                return;
            }
        };

        // Build the msg2 packet: Net header (handshake flag) + Noise
        // bytes, wrapped in a routing header with dest = FULL peer
        // node_id (from payload). The initiator's local_node_id check
        // on arrival matches the full u64, so we must put the full
        // value here.
        let mut builder = PacketBuilder::new(&[0u8; 32], 0);
        let inner = builder.build_handshake(&msg2);
        let reply_routing = RoutingHeader::new(
            peer_node_id,
            ctx.local_node_id as u32,
            DEFAULT_HANDSHAKE_TTL,
        );
        let mut routed = bytes::BytesMut::with_capacity(ROUTING_HEADER_SIZE + inner.len());
        routed.extend_from_slice(&reply_routing.to_bytes());
        routed.extend_from_slice(&inner);

        // Pick the next hop for the reply. Prefer the routing table
        // (same path the routed handshake arrived on, symmetrically).
        // Fall back to `source` (the immediate upstream that sent us
        // msg1) — that's a direct peer by construction and guaranteed
        // to have a route back.
        let next_hop = ctx
            .router
            .routing_table()
            .lookup(peer_node_id)
            .unwrap_or(source);

        // Register the new peer. The wire `addr` we record is `source`
        // — the immediate upstream peer that forwarded msg1. That is
        // NOT necessarily the final responder's addr (for multi-hop it
        // isn't), but it's the correct place for future routed data
        // to flow through. Direct data uses this addr; routed data
        // uses the routing table.
        //
        // Registration happens BEFORE the send so that even if the
        // spawned send task is cancelled or panics post-send, the
        // initiator that just derived matching keys finds us.
        //
        // Replay guard + rotation gate, atomic via `peers.entry()`.
        //
        // Pre-fix this was `peers.get()` followed by `peers.insert()`,
        // which had two distinct bugs:
        //
        // 1. (#6) The read-guard from `get()` was dropped before the
        //    `insert()`. Two concurrent routed handshakes for the same
        //    `peer_node_id` could both pass the `existing.remote_static_pub`
        //    check and race the insert; the loser's `pending_handshakes`
        //    state stayed armed waiting for a msg2 that was now bound to
        //    the winner's session, until the per-call `handshake_timeout`
        //    fired.
        //
        // 2. (#3) When the existing entry's `remote_static_pub` differed
        //    from the inbound msg1's, the code unconditionally fell
        //    through and overwrote the live session with attacker-derived
        //    keys. The legitimate initiator still held the old keys, so
        //    every subsequent AEAD-protected packet failed open and was
        //    silently dropped — a trivial DoS against any node that ever
        //    handshook on a routed path, requiring only the PSK and a
        //    second valid Noise static. The rotation gate now refuses
        //    rotation while the existing session is still within
        //    `session_timeout`. Once the live session has gone silent
        //    long enough to be considered dead, a fresh handshake from
        //    the legitimate peer (or a permitted key rotation) installs
        //    the new keys cleanly.
        //
        // The replay guard fires for the SAME `remote_static_pub`:
        // NKpsk0's responder uses a fresh ephemeral on each reply, so
        // a captured-and-replayed msg1 derives different session keys
        // every time. Without this guard the live session's keys would
        // get overwritten on every replay.
        let remote_static_pub = keys.remote_static_pub;
        // The non-installing arms (DropReplay / RefuseFresh)
        // return early; the AcceptRotation / Vacant arms each
        // yield the freshly-installed session_id, captured in
        // `registered_session_id` for the post-match reverse-index
        // update (PERF_AUDIT §2.4).
        let registered_session_id: u64 = match ctx.peers.entry(peer_node_id) {
            dashmap::mapref::entry::Entry::Occupied(mut occ) => {
                match routed_rotation_outcome(
                    occ.get(),
                    &remote_static_pub,
                    &initiator_ephemeral,
                    ctx.session_timeout,
                ) {
                    RoutedRotationOutcome::DropReplay => {
                        tracing::warn!(
                            peer_node_id,
                            "routed handshake: dropping msg1 — live session already \
                             established for this peer with matching remote_static_pub \
                             AND identical initiator ephemeral (replay guard)"
                        );
                        return;
                    }
                    RoutedRotationOutcome::RefuseFresh => {
                        tracing::warn!(
                            peer_node_id,
                            "routed handshake: refusing key rotation — existing \
                             session is still within session_timeout. New keys \
                             can be installed once the live session has gone \
                             silent for at least session_timeout (rotation gate)"
                        );
                        return;
                    }
                    RoutedRotationOutcome::DeferBusy => {
                        tracing::debug!(
                            peer_node_id,
                            "routed handshake: deferring key rotation — existing \
                             session is live and busy (open streams / unacked \
                             in-flight data). Swapping now would drop that state; \
                             the initiator retries once the session is quiescent \
                             (direct-path upgrade C3 busy gate)"
                        );
                        return;
                    }
                    RoutedRotationOutcome::AcceptRotation => {
                        // PERF_AUDIT §2.4: the rotation displaces
                        // the existing session — evict its reverse-
                        // index entry, otherwise every accepted
                        // rotation leaks one stale entry forever.
                        let displaced_session_id = occ.get().session.session_id();
                        ctx.session_id_to_node
                            .remove_if(&displaced_session_id, |_, n| *n == peer_node_id);
                        let session = Arc::new(NetSession::new(
                            keys,
                            source,
                            ctx.packet_pool_size,
                            ctx.default_reliable,
                        ));
                        let session_id = session.session_id();
                        occ.insert(PeerInfo {
                            node_id: peer_node_id,
                            addr: source,
                            session,
                            remote_static_pub,
                            last_initiator_ephemeral: Some(initiator_ephemeral),
                        });
                        session_id
                    }
                }
            }
            dashmap::mapref::entry::Entry::Vacant(vac) => {
                let session = Arc::new(NetSession::new(
                    keys,
                    source,
                    ctx.packet_pool_size,
                    ctx.default_reliable,
                ));
                let session_id = session.session_id();
                vac.insert(PeerInfo {
                    node_id: peer_node_id,
                    addr: source,
                    session,
                    remote_static_pub,
                    last_initiator_ephemeral: Some(initiator_ephemeral),
                });
                session_id
            }
        };
        ctx.peer_addrs.insert(peer_node_id, source);
        ctx.router.add_route(peer_node_id, source);
        ctx.session_id_to_node
            .insert(registered_session_id, peer_node_id);
        // Fresh session incarnation (Vacant or accepted rotation) →
        // the peer's withdrawal seq counter restarts, so purge its
        // gate history, exactly as the direct `connect`/`accept`
        // install paths do. Without this, a peer reconnecting through
        // a relay (`connect_via`) has its reset-sequence withdrawals
        // rejected as stale until the gate ages them out (cubic P2).
        ctx.route_withdraw_gate.forget_sender(peer_node_id);

        // Spawn the send. If it fails, roll back all three registrations
        // (peer session, peer-addr map, and routing table entry). Leaving
        // the route behind would silently blackhole future routed traffic
        // for `peer_node_id` through an addr we never confirmed was
        // reachable; removing peers without removing the route would also
        // inject a stale entry into rerouting decisions.
        //
        // Route rollback is conditional on the current entry still
        // pointing at `source` — if a concurrent handshake for the same
        // `peer_node_id` already installed a newer (valid) route, we must
        // not overwrite it.
        //
        // A Drop guard owns the rollback. The send marks the
        // guard `completed` only on success; cancellation, panic,
        // or any non-success drops the guard, which runs the
        // rollback. Drop is invoked synchronously when the spawned
        // future is dropped (whether by cancellation or normal
        // completion), so the rollback is no longer dependent on
        // the future actually awaiting through to its error arm.
        // A fire-and-forget `tokio::spawn` with rollback only
        // inside the spawned future on socket-send error would
        // skip the rollback if the runtime was shutting down or
        // the task was cancelled before the send completed,
        // leaving the peer/session/route in an unsendable state.
        let socket = ctx.socket.clone();
        let payload = routed.freeze();
        let guard = PeerRegistrationGuard {
            peer_node_id,
            registered_session_id,
            registered_next_hop: source,
            peers: ctx.peers.clone(),
            peer_addrs: ctx.peer_addrs.clone(),
            session_id_to_node: ctx.session_id_to_node.clone(),
            router: ctx.router.clone(),
        };
        tokio::spawn(async move {
            match socket.send_to(&payload, next_hop).await {
                Ok(_) => {
                    // `commit` consumes the guard via `mem::forget`,
                    // so the rollback Drop is skipped and the
                    // registrations stay in place.
                    guard.commit();
                }
                Err(e) => {
                    tracing::warn!(
                        peer = format!("{:#x}", peer_node_id),
                        error = %e,
                        "routed handshake: msg2 send failed; unregistering peer"
                    );
                    // `guard` drops at end of scope, running the
                    // rollback.
                }
            }
        });
    }

    /// Process a locally-destined packet: decrypt and queue events.
    ///
    /// This is the same logic as `NetAdapter::process_packet` but extracted
    /// to work with the multi-session dispatch.
    /// PERF_AUDIT §2.8 — two-tier resolution of the peer behind an
    /// accepted data packet's session, for the grant path.
    ///
    /// Tier 1: `session.cached_node_id()` (one Relaxed load),
    /// cross-checked against the live peer entry's session_id so a
    /// stale cache can never misroute a grant. Tier 2:
    /// `addr_to_node` → `peers`; the O(peers) scan is the last
    /// resort for the legitimate session-id-mismatch case
    /// (relay-shared source address). Any successful FALLBACK
    /// resolution publishes the node id back onto the session so
    /// the next packet takes tier 1 — without that publish,
    /// sessions whose traffic never traverses the cortex RPC
    /// dispatch hook (the only other `cache_node_id` caller) pay
    /// the fallback chain per packet forever and the fast path is
    /// dead for plain reliable streams (the exact shape b45bc44b8
    /// originally shipped with; pinned by
    /// `grant_peer_resolution_self_primes_node_id_cache`).
    #[inline]
    fn resolve_grant_peer(
        peers: &DashMap<u64, PeerInfo>,
        addr_to_node: &DashMap<SocketAddr, u64>,
        session: &NetSession,
    ) -> Option<(SocketAddr, Arc<NetSession>)> {
        session
            .cached_node_id()
            .and_then(|nid| {
                peers.get(&nid).and_then(|p| {
                    (p.value().session.session_id() == session.session_id())
                        .then(|| (p.value().addr, p.value().session.clone()))
                })
            })
            .or_else(|| {
                let peer_addr = session.peer_addr();
                let resolved = addr_to_node
                    .get(&peer_addr)
                    .and_then(|node_id| {
                        peers.get(&*node_id).and_then(|p| {
                            (p.value().session.session_id() == session.session_id()).then(|| {
                                (p.value().node_id, p.value().addr, p.value().session.clone())
                            })
                        })
                    })
                    .or_else(|| {
                        peers
                            .iter()
                            .find(|e| e.value().session.session_id() == session.session_id())
                            .map(|e| (e.value().node_id, e.value().addr, e.value().session.clone()))
                    });
                resolved.map(|(nid, addr, sess)| {
                    session.cache_node_id(nid);
                    (addr, sess)
                })
            })
    }

    fn process_local_packet(
        mut parsed: ParsedPacket,
        from_node: u64,
        session: &NetSession,
        ctx: &DispatchCtx,
    ) {
        let inbound = &ctx.inbound;
        let num_shards = ctx.num_shards;
        // Validate payload length
        if !parsed.header.flags.is_handshake()
            && !parsed.header.flags.is_heartbeat()
            && !parsed.is_valid_length()
        {
            return;
        }

        // Decrypt payload. Per crypto-session perf #128, route
        // through `decrypt_to_bytes` which prefers the in-place
        // path when the inbound `Bytes` has refcount == 1 (the
        // common case for freshly-received packets — the parser
        // produces the only outstanding handle until decrypt
        // lands). Falls back to the allocating `decrypt` when the
        // buffer is shared.
        let aad = parsed.header.aad();
        let counter = u64::from_le_bytes(parsed.header.nonce[4..12].try_into().unwrap_or([0u8; 8]));
        let rx_cipher = session.rx_cipher();
        let payload = std::mem::take(&mut parsed.payload);
        // Per crypto-session perf #132: the legacy two-step (pre-
        // decrypt `is_valid_rx_counter` + post-decrypt
        // `update_rx_counter`) took two parking_lot Mutex acquisitions
        // per inbound packet. `try_admit_rx_counter` validates and
        // commits under a single lock; replays land at admit and are
        // rejected there (paying AEAD on the rare replay is cheaper
        // than a redundant lock on every non-replay). AEAD failure
        // still drops the packet before we touch the window, so a
        // tampered counter never advances `rx_counter`.
        let decrypted = match rx_cipher.decrypt_to_bytes(counter, &aad, payload) {
            Ok(d) => {
                if !rx_cipher.try_admit_rx_counter(counter) {
                    return;
                }
                d
            }
            Err(_) => return,
        };

        // Check subprotocol — migration messages are sent as single event frames
        if parsed.header.subprotocol_id == SUBPROTOCOL_MIGRATION {
            // `ArcSwapOption::load` — lock-free on the hot path.
            let handler_guard = ctx.migration_handler.load();
            if let Some(handler) = handler_guard.as_ref() {
                // Extract the payload(s) from the event frame wrapper.
                //
                // Iterate every event in the frame and log a
                // warning for the (anomalous) multi-event case.
                // The protocol design is single-event-per-frame,
                // but the wire format permits multi-event — a
                // hostile (or buggy) peer batching multiple
                // migration messages into one frame must not
                // silently lose every message past the first;
                // operators need to see the protocol violation
                // rather than a silent stall.
                let events = EventFrame::read_events(decrypted, parsed.header.event_count);
                if events.is_empty() {
                    return;
                }
                if events.len() > 1 {
                    tracing::warn!(
                        n = events.len(),
                        from_node = from_node,
                        "migration subprotocol received multi-event frame \
                         (protocol design is single-event per frame); \
                         processing each message in order"
                    );
                }

                for payload in events {
                    match handler.handle_message(&payload, from_node) {
                        Ok(outbound) => {
                            // BFS queue: self-destined messages loop back
                            // through the dispatcher in-place; any output
                            // the loopback produces joins the same queue
                            // so remote-bound follow-ups reach the socket.
                            //
                            // The 2-node case where orchestrator and
                            // source/target share a node uses this path —
                            // `peers.get(&local_node_id)` is None, so the
                            // loopback short-circuit is the only way a
                            // self-destined wire message gets dispatched.
                            //
                            // The in-place queue preserves all
                            // downstream messages. A
                            // `tokio::spawn`ed fire-and-forget
                            // loopback would discard
                            // `handle_message`'s return value,
                            // and any outbound it produced —
                            // including remote-bound messages
                            // that should have ridden the wire —
                            // would disappear, wedging state
                            // transitions whenever a self-bounce
                            // chained into a further reply.
                            //
                            // Handler work is synchronous and cheap; doing
                            // it on the receive-loop task is fine.
                            //
                            // Depth-cap the self-bounce drain so a buggy
                            // handler (or attacker-influenced state inside
                            // a "trusted" handler) that always emits a
                            // self-bound follow-up cannot spin this loop
                            // synchronously on the dispatch task and
                            // starve every other peer's packets. A
                            // correct migration handler converges in a
                            // small, bounded number of self-bounces.
                            const MAX_MIGRATION_LOOPBACK_DEPTH: usize = 32;
                            let mut pending: std::collections::VecDeque<_> = outbound.into();
                            let mut loopback_count: usize = 0;
                            while let Some(msg) = pending.pop_front() {
                                if msg.dest_node == ctx.local_node_id {
                                    loopback_count += 1;
                                    if loopback_count > MAX_MIGRATION_LOOPBACK_DEPTH {
                                        tracing::warn!(
                                            depth = loopback_count,
                                            from_node = from_node,
                                            cap = MAX_MIGRATION_LOOPBACK_DEPTH,
                                            "migration handler loopback exceeded \
                                             MAX_MIGRATION_LOOPBACK_DEPTH; dropping \
                                             remaining queue to keep the dispatch \
                                             task responsive to other peers. A \
                                             correct handler should converge in a \
                                             small bounded number of self-bounces.",
                                        );
                                        break;
                                    }
                                    match handler.handle_message(&msg.payload, ctx.local_node_id) {
                                        Ok(more) => pending.extend(more),
                                        Err(e) => {
                                            tracing::warn!(
                                                error = %e,
                                                "migration handler loopback error",
                                            );
                                        }
                                    }
                                    continue;
                                }
                                let dest_session = ctx
                                    .peers
                                    .get(&msg.dest_node)
                                    .map(|e| (e.value().addr, e.value().session.clone()));

                                if let Some((dest_addr, dest_sess)) = dest_session {
                                    // Respect partition filter on outbound path
                                    if ctx.partition_filter.contains(&dest_addr) {
                                        continue;
                                    }
                                    let socket = ctx.socket.clone();
                                    let payload = Bytes::from(msg.payload);
                                    tokio::spawn(async move {
                                        let pool = dest_sess.thread_local_pool();
                                        let mut builder = pool.get();
                                        let seq = {
                                            let stream = dest_sess
                                                .get_or_create_stream(SUBPROTOCOL_MIGRATION as u64);
                                            stream.next_tx_seq()
                                        };
                                        let events = vec![payload];
                                        let packet = builder.build_subprotocol(
                                            SUBPROTOCOL_MIGRATION as u64,
                                            seq,
                                            &events,
                                            PacketFlags::NONE,
                                            SUBPROTOCOL_MIGRATION,
                                        );
                                        let _ = socket.send_to(&packet, dest_addr).await;
                                    });
                                }
                            }
                        }
                        Err(e) => {
                            tracing::warn!(error = %e, "migration handler error");
                        }
                    }
                } // end multi-event payload loop
                return; // handler processed it
            }
            // No handler set — synthesize a `ComputeNotSupported`
            // reply so the source doesn't silently time out. Parses
            // the inbound far enough to extract `daemon_origin` for
            // the reply envelope, then drops. Only responds to the
            // two migration-initiating messages (`TakeSnapshot`,
            // `SnapshotReady`) — other inbound types arrive only
            // mid-migration, and a migration can't be mid-state
            // against a node that has no compute runtime.
            //
            // Iterate every event in the frame so a multi-event
            // migration packet (protocol violation, but possible
            // on the wire) gets one reply per request rather than
            // one for the first and silent drops for the rest.
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            for payload in events {
                if let Some(reply) = synthesize_compute_not_supported_reply(&payload) {
                    let dest_session = ctx
                        .peers
                        .get(&from_node)
                        .map(|e| (e.value().addr, e.value().session.clone()));
                    if let Some((dest_addr, dest_sess)) = dest_session {
                        if !ctx.partition_filter.contains(&dest_addr) {
                            let socket = ctx.socket.clone();
                            tokio::spawn(async move {
                                let pool = dest_sess.thread_local_pool();
                                let mut builder = pool.get();
                                let seq = {
                                    let stream = dest_sess
                                        .get_or_create_stream(SUBPROTOCOL_MIGRATION as u64);
                                    stream.next_tx_seq()
                                };
                                let events = vec![reply];
                                let packet = builder.build_subprotocol(
                                    SUBPROTOCOL_MIGRATION as u64,
                                    seq,
                                    &events,
                                    PacketFlags::NONE,
                                    SUBPROTOCOL_MIGRATION,
                                );
                                let _ = socket.send_to(&packet, dest_addr).await;
                            });
                        }
                    }
                }
            }
            return;
        }

        // Stream-window credit grant: apply to the named stream's
        // `tx_credit_remaining` without touching the inbound event
        // queue. The grant payload is an event frame carrying a
        // 12-byte `StreamWindow` message.
        //
        // Iterate the full event vector and apply each grant. The
        // codec supports multi-event frames, and `StreamWindow` is
        // fixed-size at 16 bytes — there's no codec ambiguity.
        // Using `events.into_iter().next()` would drop every
        // grant past the first when a peer batched multiple
        // stream credits into one event-frame packet, stalling
        // those streams until the sender retransmitted
        // (`apply_authoritative_grant` is monotonic so retransmits
        // eventually catch up — efficiency loss, not data loss).
        if parsed.header.subprotocol_id == SUBPROTOCOL_STREAM_WINDOW {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            for payload in events {
                match StreamWindow::decode(&payload) {
                    Ok(grant) => {
                        // Quarantine guard: a grant that arrives for a
                        // stream closed within `GRANT_QUARANTINE_WINDOW`
                        // is dropped, even if the stream has already been
                        // reopened with the same id. Without this the
                        // in-flight grant from the *previous* lifetime
                        // would spuriously credit the new `StreamState`
                        // and let the sender exceed its intended window.
                        // Grants for closed / unknown streams are also
                        // dropped silently — the sender will time out on
                        // its own.
                        if session.is_grant_quarantined(grant.stream_id) {
                            tracing::debug!(
                                stream_id = format!("{:#x}", grant.stream_id),
                                "dropping StreamWindow grant for recently-closed stream"
                            );
                        } else if let Some(state) = session.try_stream(grant.stream_id) {
                            state.apply_authoritative_grant(grant.total_consumed);
                            // Prune the retransmit window up to the peer's
                            // cumulative ack (H-9) — stops acked packets
                            // from lingering, timing out, and spuriously
                            // resending (or, post-H-3, spuriously failing).
                            state.with_reliability(|r| r.on_ack(grant.ack_seq));
                        }
                    }
                    Err(e) => {
                        tracing::debug!(error = %e, "malformed StreamWindow grant");
                    }
                }
            }
            return;
        }

        // Retransmit NACK (STREAM_RETRANSMIT D-3): the peer is missing
        // sequences on a stream we're sending it. Pull the matching
        // retransmit descriptors via `on_nack` and rebuild + resend each
        // with a FRESH AEAD counter — the descriptor stashed the
        // pre-encryption inputs precisely so a resend isn't a stale-
        // counter replay (which the receiver's replay window would
        // reject). `dispatch_packet` is sync, so encrypt the wire bytes
        // here (under the session's builder) and hand the awaiting sends
        // to a spawned task.
        if parsed.header.subprotocol_id == SUBPROTOCOL_STREAM_NACK {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            let mut packets: Vec<Bytes> = Vec::new();
            for payload in events {
                let sn = match StreamNack::decode(&payload) {
                    Ok(sn) => sn,
                    Err(e) => {
                        tracing::debug!(error = %e, "malformed StreamNack");
                        continue;
                    }
                };
                // Don't resurrect a recently-closed stream's send state.
                if session.is_grant_quarantined(sn.stream_id) {
                    continue;
                }
                let Some(state) = session.try_stream(sn.stream_id) else {
                    continue;
                };
                let nack = super::protocol::NackPayload {
                    next_expected: sn.next_expected,
                    missing_bitmap: sn.missing_bitmap,
                };
                let descriptors = state.with_reliability(|r| r.on_nack(&nack));
                if descriptors.is_empty() {
                    continue;
                }
                let pool = session.thread_local_pool();
                let mut builder = pool.get();
                for d in &descriptors {
                    // PERF_AUDIT §2.10: `builder.build` already
                    // returns owned `Bytes`; the pre-fix
                    // `Bytes::copy_from_slice(&p)` added a second
                    // allocation + full-packet memcpy per
                    // retransmit. Loss-path only, but the burst
                    // fires exactly when the link is stressed.
                    let p = builder.build(d.stream_id, d.seq, &d.events, d.flags);
                    packets.push(p);
                }
            }
            if !packets.is_empty() {
                let socket = ctx.socket.clone();
                let dest = parsed.source;
                let control_stats = ctx.control_stats.clone();
                tokio::spawn(async move {
                    for p in packets {
                        if socket.send_to(&p, dest).await.is_ok() {
                            control_stats
                                .retransmit_packets_sent
                                .fetch_add(1, Ordering::Relaxed);
                        }
                    }
                });
            }
            return;
        }

        // Positive SACK-range ACK (STREAM_ACK_BATCHING R-5): the peer
        // positively acknowledges out-of-order received runs on a
        // stream we're sending it. Remove those packets from the
        // retransmit window so the RTO backstop resends only the
        // genuinely missing ones — pre-R-3 a single lost head packet
        // RTO-flooded every tracked packet behind it and collapsed
        // cwnd. Accepted unconditionally: the capability gate applies
        // to EMISSION only (negotiation, not authority).
        if parsed.header.subprotocol_id == SUBPROTOCOL_STREAM_ACK {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            for payload in events {
                let ack = match StreamAckRanges::decode(&payload) {
                    Ok(a) => a,
                    Err(e) => {
                        tracing::debug!(error = %e, "malformed StreamAckRanges");
                        continue;
                    }
                };
                // Don't resurrect a recently-closed stream's send state.
                if session.is_grant_quarantined(ack.stream_id) {
                    continue;
                }
                let Some(state) = session.try_stream(ack.stream_id) else {
                    continue;
                };
                state.with_reliability(|r| r.on_ack_ranges(ack.ack_seq, &ack.ranges));
            }
            return;
        }

        // Stream reset (STREAM_RETRANSMIT H-3): the sender gave up
        // retransmitting this stream. Fail any pending blob-transfer read
        // on it now (distinct error) instead of waiting for the caller's
        // timeout, and drop the local receive-stream state.
        if parsed.header.subprotocol_id == SUBPROTOCOL_STREAM_RESET {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            for payload in events {
                let Ok(reset) = StreamReset::decode(&payload) else {
                    continue;
                };
                #[cfg(feature = "dataforts")]
                if super::dataforts::blob::is_transfer_stream_id(reset.stream_id) {
                    if let Some(engine) = ctx.blob_transfer_engine.read().as_ref() {
                        engine.on_reset(reset.stream_id);
                    }
                }
                session.close_stream(reset.stream_id);
            }
            return;
        }

        // Channel membership: Subscribe / Unsubscribe / Ack.
        //
        // Iterate every event in the frame. `events.into_iter()
        // .next()` would drop every membership op past the first
        // when a peer batched multiple Subscribe/Unsubscribe
        // events into one frame. Each membership op is
        // independent and idempotent on the receiver, so
        // iterating is structurally safe.
        if parsed.header.subprotocol_id == SUBPROTOCOL_CHANNEL_MEMBERSHIP {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            if events.is_empty() {
                return;
            }
            // PERF_AUDIT §2.9: `from_node` is the resolved peer
            // node_id the dispatch site already looked up via
            // session_id — no need to re-scan `peers` here.
            for payload in events {
                Self::handle_membership_message(&payload, from_node, ctx);
            }
            return;
        }

        // Capability announcement: signed, versioned capability metadata.
        // Feeds the local `CapabilityIndex`; never responded to.
        //
        // Iterate every event in the frame. `events.into_iter()
        // .next()` would drop every announcement past the first
        // when a peer batched multiple capability updates into
        // one frame. Each announcement is independently signed
        // and version-skip safe on the index side, so iterating
        // is structurally safe.
        if parsed.header.subprotocol_id == SUBPROTOCOL_CAPABILITY_ANN {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            if events.is_empty() {
                return;
            }
            // PERF_AUDIT §2.9: use the parameter — see comment in
            // the membership branch above.
            for payload in events {
                Self::handle_capability_announcement(&payload, from_node, ctx);
            }
            return;
        }

        // Route withdrawal (RT-5): poison-reverse "dest unreachable
        // via the sender". Session-authenticated by construction —
        // the `via` leg is `from_node`, resolved from the decrypting
        // session, never a wire field. Each event is independent
        // and idempotent, so iterating the frame is safe.
        if parsed.header.subprotocol_id == SUBPROTOCOL_ROUTE_WITHDRAW {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            for payload in events {
                Self::handle_route_withdrawal(&payload, from_node, ctx);
            }
            return;
        }

        // Sensing interest (SI-2a, SENSING_INTEREST_COALESCING_PLAN
        // §4.2/§4.3): hop-by-hop interest registrations on 0x0C02.
        // Session-authenticated by construction — the sender is
        // `from_node`, the AEAD-resolved session peer, never a wire
        // field. Dark by default: with `enable_sensing_coalescing`
        // off the frame drops here with ZERO further work (no
        // decode, no counters) — the same degradation an unknown
        // subprotocol id gets (plan §5, "the plane ships dark").
        // Each event is one strict-decoded frame; registrations are
        // independent and idempotent soft-state refreshes, so
        // iterating the frame is structurally safe.
        if parsed.header.subprotocol_id == sensing::SUBPROTOCOL_SENSING_INTEREST {
            if !ctx.enable_sensing_coalescing {
                return;
            }
            // NodeId-0 sentinel guard, as the REDEX/meshdb arms: a
            // caller that defaulted `from_node` because session
            // resolution failed must not register table rows.
            if from_node == 0 {
                return;
            }
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            for payload in events {
                Self::handle_sensing_interest_frame(&payload, from_node, ctx);
            }
            return;
        }

        // Capability sensing (SI-3, SENSING_INTEREST_COALESCING_PLAN
        // §4.4/§4.6): origin-signed readiness attestations on 0x0C03.
        // Same gates as the 0x0C02 arm: dark plane and sentinel-zero
        // senders drop with zero work.
        if parsed.header.subprotocol_id == sensing::SUBPROTOCOL_READINESS_ATTESTATION {
            if !ctx.enable_sensing_coalescing {
                return;
            }
            if from_node == 0 {
                return;
            }
            // SI-4a: the §4.4 continuity-bearing flag rides the
            // hop-authored session envelope — the stream id.
            // SI-4 review P2: match BOTH declared streams
            // explicitly and drop everything else as malformed —
            // unknown envelope metadata must never default to
            // optimistic continuity.
            let stream_id = parsed.header.stream_id;
            let provisional = if stream_id == sensing::SUBPROTOCOL_READINESS_ATTESTATION as u64 {
                false
            } else if stream_id == sensing::SENSING_PROVISIONAL_STREAM {
                true
            } else {
                ctx.sensing_counters
                    .protocol_invalid
                    .fetch_add(1, Ordering::Relaxed);
                tracing::debug!(
                    from_node = format!("{:#x}", from_node),
                    stream_id,
                    "sensing: unknown 0x0C03 envelope stream dropped"
                );
                return;
            };
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            for payload in events {
                Self::handle_sensing_attestation_frame(&payload, from_node, provisional, ctx);
            }
            return;
        }

        // Replication: per-channel runtime tasks own the
        // per-channel state. The router (installed by `Redex`
        // via `MeshNode::set_replication_inbound_router`) maps
        // `ChannelId → ReplicationRuntimeHandle` and dispatches
        // each decoded `Inbound::*` synchronously. `None` router
        // = no replicated channels on this node = drop.
        #[cfg(feature = "redex")]
        if parsed.header.subprotocol_id == super::redex::SUBPROTOCOL_REDEX {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            if events.is_empty() {
                return;
            }
            let router_guard = ctx.replication_inbound_router.read();
            let Some(router) = router_guard.as_ref() else {
                // No replicated channels — drop silently.
                return;
            };
            // R-25: reject sentinel-zero from_node — `NodeId == 0`
            // is a valid id (MeshNodeConfig::new accepts the
            // [0u8; 32] PSK), so a caller that defaulted to `0`
            // because session resolution failed would otherwise be
            // indistinguishable from a legitimate node-0 peer.
            if from_node == 0 {
                return;
            }
            for payload in events {
                Self::dispatch_replication_payload(&payload, from_node, router.as_ref());
            }
            return;
        }

        // Blob transfer control plane (FairScheduler transport plan):
        // a `TransferControl::Request` initiating an on-demand fetch.
        // The engine spawns a serving task that streams the chunk back
        // on the requester's transfer stream-id. `None` engine = this
        // node doesn't serve transfers = drop. The bulk DATA does NOT
        // ride this subprotocol — it rides reliable event-plane streams
        // and is diverted to the engine by `is_transfer_stream_id` in
        // `process_local_packet` (so it gets in-order retransmit).
        #[cfg(feature = "dataforts")]
        if parsed.header.subprotocol_id == super::dataforts::blob::SUBPROTOCOL_BLOB_TRANSFER {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            if events.is_empty() {
                return;
            }
            let engine_guard = ctx.blob_transfer_engine.read();
            let Some(engine) = engine_guard.as_ref() else {
                return;
            };
            if from_node == 0 {
                return;
            }
            let stream_id = parsed.header.stream_id;
            for payload in events {
                engine.on_request(from_node, stream_id, &payload);
            }
            return;
        }

        // MeshDB: federated query traffic on `SUBPROTOCOL_MESHDB`.
        // Both directions (requests caller → server, responses
        // server → caller) ride the same subprotocol slot; the
        // `MeshDbInboundRouter::try_route` decodes the tagged
        // frame and demuxes. `None` router = no MeshDB transport
        // installed = drop the frame silently (matches the
        // replication path's behaviour for unrouted channels).
        #[cfg(feature = "meshdb")]
        if parsed.header.subprotocol_id == super::behavior::meshdb::SUBPROTOCOL_MESHDB {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            if events.is_empty() {
                return;
            }
            let router_guard = ctx.meshdb_inbound_router.read();
            let Some(router) = router_guard.as_ref() else {
                // No router → drop silently.
                return;
            };
            // Mirror the REDEX guard: NodeId == 0 is the sentinel
            // for "session is up but the caller didn't pass a
            // resolved node_id"; reject so an unauthenticated
            // sender can't impersonate node-0.
            if from_node == 0 {
                return;
            }
            for payload in events {
                if let Err(e) = router.try_route(from_node, &payload) {
                    tracing::debug!(error = %e, from_node, "meshdb: drop frame");
                }
            }
            return;
        }

        // Fold framework: signed-announcement traffic on
        // `SUBPROTOCOL_FOLD`. Every event in the packet is one
        // `SignedAnnouncement<P>` postcard envelope; the
        // installed `FoldChannelRouter` (typically a
        // `FoldRegistry`) decodes + verifies + dispatches each
        // to its registered `Fold<K>` by the envelope's `kind`
        // u16. `None` router = drop silently, mirroring meshdb /
        // replication.
        //
        // Publisher resolution: the inbound session's `node_id`
        // maps to an `EntityId` via the local `peer_entity_ids`
        // DashMap. Without a known entity for the session we
        // can't verify signatures — drop the frame and let
        // operators notice the missing handshake via the usual
        // peer-bring-up diagnostics.
        if parsed.header.subprotocol_id == super::behavior::fold::SUBPROTOCOL_FOLD {
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            if events.is_empty() {
                return;
            }
            let router_guard = ctx.fold_router.read();
            let Some(router) = router_guard.as_ref() else {
                return;
            };
            if from_node == 0 {
                return;
            }
            let Some(publisher) = ctx
                .peer_entity_ids
                .get(&from_node)
                .map(|e| e.value().clone())
            else {
                // Session is up but no EntityId recorded — should
                // be impossible in steady state (the handshake
                // populates both maps together). Drop to be safe;
                // an unauthenticated `try_route` would forge the
                // publisher claim.
                tracing::debug!(from_node, "fold: missing peer EntityId, drop frame");
                return;
            };
            for payload in events {
                if let Err(e) = router.try_route(&publisher, &payload) {
                    tracing::debug!(error = %e, from_node, "fold: drop frame");
                }
            }
            return;
        }

        // Reflex probe: request → observer echoes the UDP-source
        // SocketAddr of the requester. Response → completes the
        // requester's pending oneshot. Both directions ride the
        // same subprotocol; dispatch is length-based
        // (see `traversal::reflex::decode`).
        #[cfg(feature = "nat-traversal")]
        if parsed.header.subprotocol_id == super::traversal::SUBPROTOCOL_REFLEX {
            use super::traversal::reflex;
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            if events.is_empty() {
                return;
            }
            // PERF_AUDIT §2.9: use the parameter — same shape as
            // the membership/capability branches. The zero-check
            // guard below still fires for the (vanishingly rare)
            // PSK-zero node case.
            if from_node == 0 {
                return;
            }

            // Iterate every event in the frame.
            // `events.into_iter().next()` would drop every reflex
            // message past the first when a peer batched multiple
            // probes into one packet. Reflex Request/Response are
            // each independent so multi-event handling is
            // structurally safe.
            for payload in events {
                let Some(msg) = reflex::decode(&payload) else {
                    continue;
                };
                match msg {
                    reflex::ReflexMsg::Request => {
                        // Echo back the requester's public address. We
                        // use `PeerInfo.addr` — the source recorded at
                        // handshake / key-rotation time (`addr: source`
                        // in the routed-handshake path), NOT the live
                        // UDP source of this reflex packet. NAT-rewrite
                        // is applied by the time packets reach our
                        // socket, so for a peer whose NAT mapping is
                        // stable this equals a STUN server's "observed
                        // source."
                        //
                        // Tradeoff (code review 2026-06-21, Finding
                        // B5): the handshake addr is authenticated, so
                        // an on-path attacker can't make us report a
                        // spoofed reflex by forging a UDP source. The
                        // cost is that a *mid-session NAT rebind*
                        // without a re-handshake yields a stale reflex
                        // until the session re-establishes. Echoing the
                        // live `source` would track rebinds but be
                        // spoofable; the spoof-resistant cached addr is
                        // the deliberate choice.
                        let Some((dest_addr, dest_sess)) = ctx
                            .peers
                            .get(&from_node)
                            .map(|e| (e.value().addr, e.value().session.clone()))
                        else {
                            continue;
                        };
                        if ctx.partition_filter.contains(&dest_addr) {
                            continue;
                        }
                        let response = reflex::encode_response(dest_addr);
                        let socket = ctx.socket.clone();
                        tokio::spawn(async move {
                            let pool = dest_sess.thread_local_pool();
                            let mut builder = pool.get();
                            let seq = {
                                let stream = dest_sess.get_or_create_stream(
                                    super::traversal::SUBPROTOCOL_REFLEX as u64,
                                );
                                stream.next_tx_seq()
                            };
                            let events = vec![response];
                            let packet = builder.build_subprotocol(
                                super::traversal::SUBPROTOCOL_REFLEX as u64,
                                seq,
                                &events,
                                PacketFlags::NONE,
                                super::traversal::SUBPROTOCOL_REFLEX,
                            );
                            let _ = socket.send_to(&packet, dest_addr).await;
                        });
                    }
                    reflex::ReflexMsg::Response(observed) => {
                        // Complete the pending probe (if any). A probe
                        // that already timed out has no oneshot entry;
                        // the late response is dropped silently.
                        if let Some((_, (_gen, tx))) = ctx.pending_reflex_probes.remove(&from_node)
                        {
                            let _ = tx.send(observed);
                        }
                    }
                }
            }
            return;
        }

        // Rendezvous coordinator: on `PunchRequest` from peer A,
        // look up target B's reflex in the capability index and
        // send `PunchIntroduce` to both sides with the shared
        // `fire_at` timestamp. Plan §3 — the three-message dance
        // for synchronized hole-punch.
        //
        // `PunchIntroduce` and `PunchAck` inbound wiring lands in
        // stage 3c (endpoint role); stage 3b only handles the
        // coordinator branch so the unit under test is the
        // fan-out itself.
        #[cfg(feature = "nat-traversal")]
        if parsed.header.subprotocol_id == super::traversal::SUBPROTOCOL_RENDEZVOUS {
            use super::traversal::rendezvous;
            let events = EventFrame::read_events(decrypted, parsed.header.event_count);
            if events.is_empty() {
                return;
            }
            // PERF_AUDIT §2.9: use the parameter — same shape as
            // the reflex branch above.
            if from_node == 0 {
                return;
            }

            // Iterate every event in the frame.
            // `events.into_iter().next()` would drop every
            // rendezvous message past the first when a peer
            // batched PunchRequest / PunchIntroduce / PunchAck
            // into one packet. Each is independent — no
            // cross-event ordering dependency — so multi-event
            // handling is structurally safe.
            for payload in events {
                let Some(msg) = rendezvous::decode(&payload) else {
                    continue;
                };
                match msg {
                    rendezvous::RendezvousMsg::PunchRequest(req) => {
                        Self::handle_punch_request(from_node, req, ctx);
                    }
                    rendezvous::RendezvousMsg::PunchIntroduce(intro) => {
                        // Endpoint side of the rendezvous. Complete
                        // any installed observer waiter (for tests /
                        // explicit awaits), then schedule the
                        // keep-alive train + observer. The
                        // `PunchAck` fires only once the observer
                        // sees inbound traffic from `peer_reflex`
                        // (or — on localhost — at the punch_deadline
                        // fallback). Plan §3 endpoint semantics.
                        //
                        // Bind the introduce to the recorded
                        // coordinator. Pre-binding, any session peer
                        // could forge a PunchIntroduce for any peer
                        // the local node was currently waiting on
                        // (target id learned via session-establishment
                        // traffic patterns) and steer the local
                        // node's punch flow at an attacker-chosen
                        // reflex. The legit coordinator's later
                        // introduce found the entry already removed
                        // and was silently dropped.
                        let took = ctx
                            .pending_punch_introduces
                            .remove_if(&intro.peer, |_, (_gen, expected_coord, _pid, _)| {
                                *expected_coord == from_node
                            });
                        if let Some((_, (_gen, _expected, _pid, tx))) = took {
                            // Initiator role: we asked for this punch,
                            // so the introduce is trusted — it's bound
                            // to the coordinator we recorded when we
                            // sent the PunchRequest. Complete the
                            // waiter (unblocks `request_punch`) and
                            // fire our own keep-alive train. Initiator
                            // trains aren't budget-gated — they're
                            // self-initiated and self-limited by the
                            // connect_direct flow (no train slot).
                            let _ = tx.send(PunchIntroduceOutcome::Introduce(intro));
                            Self::schedule_punch(from_node, intro, ctx, None);
                            continue;
                        }
                        if ctx.pending_punch_introduces.contains_key(&intro.peer) {
                            // A waiter exists but the coordinator
                            // mismatched. Drop without completing
                            // and without scheduling a punch — this
                            // is the forged-introduce path.
                            tracing::trace!(
                                from = from_node,
                                target = intro.peer,
                                "rendezvous: PunchIntroduce from non-coordinator session peer; dropping"
                            );
                            continue;
                        }
                        // Unsolicited introduce — the responder role
                        // (B never called `request_punch`), or a
                        // forged direct introduce from an authenticated
                        // session peer. `intro.peer_reflex` is wire-
                        // supplied and, unguarded, would steer our
                        // keep-alive train at an attacker-named victim
                        // (review Finding 4). Validate it against the
                        // counterpart's cached signed reflex and charge
                        // the responder budgets before firing; the
                        // returned slot is held for the train's
                        // lifetime (Finding 5).
                        let Some(slot) =
                            Self::unsolicited_introduce_permitted(&intro, from_node, ctx)
                        else {
                            continue;
                        };
                        Self::schedule_punch(from_node, intro, ctx, Some(slot));
                    }
                    rendezvous::RendezvousMsg::PunchAck(ack) => {
                        if ack.to_peer == ctx.local_node_id {
                            // Final recipient: complete the correlation
                            // oneshot keyed by `from_peer`. A late ack
                            // for an abandoned `connect_direct` is
                            // dropped silently.
                            //
                            // Bind to the recorded coordinator. The
                            // ack always reaches the final recipient
                            // via the coordinator's forwarding role
                            // (`forward_punch_ack`); the original
                            // sender's session-peer identity is
                            // intentionally NOT the wire sender at
                            // this hop. Pre-binding, any session
                            // peer could ship a forged
                            // `PunchAck { from_peer: counterpart, .. }`
                            // and resolve the local connect_direct
                            // future with attacker-chosen payload.
                            let took = ctx
                                .pending_punch_acks
                                .remove_if(&ack.from_peer, |_, (_gen, expected_coord, _)| {
                                    *expected_coord == from_node
                                });
                            if let Some((_, (_gen, _expected, tx))) = took {
                                let _ = tx.send(ack);
                            } else if ctx.pending_punch_acks.contains_key(&ack.from_peer) {
                                tracing::trace!(
                                    from = from_node,
                                    claimed = ack.from_peer,
                                    "rendezvous: PunchAck not forwarded by recorded coordinator; dropping"
                                );
                                continue;
                            }
                        } else {
                            // Coordinator role: forward verbatim to
                            // `to_peer` via our session with that
                            // peer. The forwarded ack keeps the same
                            // bytes — `from_peer` still points at the
                            // original sender, which is what the
                            // recipient correlates on.
                            Self::forward_punch_ack(ack, ctx);
                        }
                    }
                    rendezvous::RendezvousMsg::PunchReject(rej) => {
                        // Requester side: the coordinator refused to
                        // mediate. Resolve the pending-introduce waiter
                        // (keyed by the target we named) with the typed
                        // reason so `request_punch` fails fast instead
                        // of waiting out `punch_deadline`.
                        //
                        // Bind to the recorded coordinator, exactly like
                        // the introduce path: only the relay we sent the
                        // PunchRequest to may reject it. Otherwise any
                        // session peer could forge a reject and abort a
                        // legitimate in-flight punch (a cheap DoS on the
                        // optimization).
                        //
                        // ALSO require the punch_id echo to match the
                        // waiter's (cubic P2): two concurrent
                        // request_punch calls to the same target replace
                        // each other's waiter, and a delayed reject for
                        // the superseded request must not fail its
                        // replacement. A mismatched id leaves the waiter
                        // in place — the replacement request gets its
                        // own answer (or its own timeout). Introduces
                        // deliberately stay id-free: a late introduce
                        // carries equally-valid reflex data for the
                        // replacement request, so conflation is benign
                        // there (full ack/introduce correlation is the
                        // deferred stage-6 punch_id work).
                        let took = ctx.pending_punch_introduces.remove_if(
                            &rej.target,
                            |_, (_gen, expected_coord, pid, _)| {
                                *expected_coord == from_node && *pid == rej.punch_id
                            },
                        );
                        if let Some((_, (_gen, _expected, _pid, tx))) = took {
                            let _ = tx.send(PunchIntroduceOutcome::Rejected(rej.reason));
                        } else {
                            tracing::trace!(
                                from = from_node,
                                target = rej.target,
                                punch_id = rej.punch_id,
                                reason = rej.reason.kind(),
                                "rendezvous: PunchReject with no matching waiter / \
                                 non-coordinator sender / stale punch_id; dropping"
                            );
                        }
                    }
                }
            }
            return;
        }

        // Forward-compat guard: the event plane is `subprotocol_id
        // == 0`; every control subprotocol above carries a non-zero
        // id and `return`s once handled. A non-zero id that reaches
        // here is a subprotocol this build does not know — a newer
        // peer's future subprotocol, or one behind a disabled
        // feature. Drop it rather than mis-parsing its opaque payload
        // as application events (which would charge credit, emit a
        // StreamWindow grant, and surface undecodable `StoredEvent`s
        // to app consumers). This is the "old node silently ignores
        // an unknown subprotocol" degradation the RT-5 docs promise;
        // it just was never enforced (RT-5 review Finding 3).
        if parsed.header.subprotocol_id != 0 {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                subprotocol_id = format!("{:#06x}", parsed.header.subprotocol_id),
                "dispatch: unknown subprotocol id dropped (forward-compat)"
            );
            return;
        }

        // Standard event path: parse event frames and queue.
        //
        // Credit accounting charges the full on-wire size (Net
        // header + AEAD tag + payload) so sender and receiver stay
        // symmetric — the sender debits the same quantity via
        // `wire_bytes_for_payload` on admission.
        let payload_bytes = (decrypted.len() + PACKET_WIRE_OVERHEAD) as u64;
        let events = EventFrame::read_events(decrypted, parsed.header.event_count);

        let stream_id = parsed.header.stream_id;
        let shard_id = if num_shards > 0 {
            (stream_id % num_shards as u64) as u16
        } else {
            0
        };

        // Credit-window bookkeeping: charge only *accepted* inbound
        // bytes against the stream's RxCreditState. `on_receive`
        // returns `false` for duplicates (already-acked sequences)
        // and for sequences past the Reliable receive window —
        // crediting those would refund send credit for
        // retransmissions / replays, letting a chatty peer inflate
        // `tx_credit_remaining` past what it actually pushed through
        // the protocol. Accounting runs at receive time (not drain
        // time); this closes the v1 gap where a single serial sender
        // ran `Transport(io::Error)` into a full kernel buffer. A
        // separately slow daemon is still backstopped by the
        // existing shard-queue-depth limits.
        let grant_bytes = {
            // Create the receive-side stream reliable when the packet is
            // RELIABLE-flagged, so it tracks SACK and can NACK lost
            // sequences. The sender's reliability is a property of the
            // traffic (the flag), not the receiver's default_reliable.
            let reliable_pkt = parsed.header.flags.contains(PacketFlags::RELIABLE);
            let stream = session
                .get_or_create_stream_for_packet(stream_id, ctx.default_reliable || reliable_pkt);
            let accepted = stream.with_reliability(|r| r.on_receive(parsed.header.sequence));
            if accepted {
                stream.update_rx_seq(parsed.header.sequence);
                stream.on_bytes_consumed(payload_bytes)
            } else {
                None
            }
        };

        if let Some(total_consumed) = grant_bytes {
            // Resolve the sending peer.
            //
            // PERF_AUDIT §2.8 — see `Self::resolve_grant_peer`:
            // tier-1 cached-node-id load (session-id cross-checked),
            // `addr_to_node` second tier, O(peers) scan last resort,
            // and the fallback publishes the cache so subsequent
            // packets take tier 1.
            let peer = Self::resolve_grant_peer(&ctx.peers, &ctx.addr_to_node, session);
            if let Some((peer_addr, peer_session)) = peer {
                if !ctx.partition_filter.contains(&peer_addr) {
                    // Enqueue for the per-mesh drainer
                    // (`spawn_stream_grant_drainer_loop`). Same-key
                    // overwrites — the latest `total_consumed` wins
                    // because grants are authoritative. Single
                    // `Notify::notify_one` after the insert wakes
                    // the drainer if it's currently sleeping;
                    // sticky-permit semantics make a wake during an
                    // in-flight drain safe (drainer will see the
                    // new entry on its next cycle).
                    {
                        let mut guard = ctx.pending_stream_grants.lock();
                        guard.insert(
                            (peer_session.session_id(), stream_id),
                            PendingStreamGrant {
                                session: peer_session,
                                peer_addr,
                                total_consumed,
                            },
                        );
                    }
                    ctx.pending_stream_grants_notify.notify_one();
                }
            }
        }

        // nRPC dispatch hook: if a dispatcher is registered for the
        // inbound packet's `channel_hash`, route every event from
        // this packet directly to the dispatcher and skip the
        // shard-inbound push. RPC needs per-channel routing
        // (events for `<service>.requests` drive the server fold;
        // events for `<service>.replies.<origin>` drive the
        // client fold) which the shard queue can't provide because
        // it strips the channel name on ingress.
        //
        // Hot-path cost: one DashMap get per packet. Absent
        // registrations skip the loop entirely. The bucket
        // ordinarily holds exactly one `(canonical, dispatcher)`
        // entry; wire-bucket collisions between independently-
        // registered canonical channels fan-out to each registered
        // canonical entry, with the canonical hash passed verbatim
        // so dispatchers self-disambiguate on the receive side.
        #[cfg(feature = "cortex")]
        if let Some(entry) = ctx.rpc_inbound_dispatchers.get(&parsed.header.channel_hash) {
            // Snapshot the dispatchers + canonical hashes so the
            // DashMap shard lock is released before invoking user
            // code — the dispatcher closure may take other locks
            // (mpsc sends, fold mutexes) and holding a DashMap
            // shard guard across that risks lock-ordering hazards.
            //
            // The bucket ordinarily holds exactly one entry; lift
            // that case out of the heap so the per-packet fast path
            // doesn't allocate. The N-entry fallback (wire-bucket
            // collision between independently-registered canonical
            // channels) collects into a Vec — paid once per packet
            // when collisions actually exist.
            enum Snapshot {
                Single(
                    ChannelHash,
                    crate::adapter::net::cortex::RpcInboundDispatcher,
                ),
                Many(
                    Vec<(
                        ChannelHash,
                        crate::adapter::net::cortex::RpcInboundDispatcher,
                    )>,
                ),
            }
            let snapshot = match entry.as_slice() {
                [] => {
                    drop(entry);
                    return;
                }
                [only] => {
                    let (c, d) = only.clone();
                    Snapshot::Single(c, d)
                }
                many => Snapshot::Many(many.to_vec()),
            };
            drop(entry);
            let origin_hash = parsed.header.origin_hash;
            // S-4 part 2: resolve the wire-session peer's NodeId so
            // the cortex RPC client fold can bind RESPONSE delivery
            // to the recorded target. Fast path: `addr_to_node` →
            // peers; fall back to a session_id scan. If neither
            // path resolves a NodeId we drop the event rather than
            // fall through to sentinel `0` — a loopback test fold
            // that registered with `target=0` would otherwise have
            // the deliver gate satisfied unconditionally, mixing
            // unrelated real-peer events into a loopback expecting
            // only its own. Real production callbacks register
            // with non-zero targets and already fail closed on a
            // mismatch; the drop here closes the loopback hole
            // without affecting production routing.
            let session_id = session.session_id();
            // Per-packet session→NodeId resolution. Fast path is a
            // single Relaxed atomic load against the per-session
            // cache populated by the first successful resolution;
            // see `NetSession::cached_node_id` for the rationale
            // (discovery-routing perf #108). Cache miss runs the
            // legacy chain (`addr_to_node` lookup + session_id
            // verification, then full peer scan on stale addr) and
            // publishes the result for subsequent packets.
            let from_node = session.cached_node_id().or_else(|| {
                let resolved = ctx
                    .addr_to_node
                    .get(&session.peer_addr())
                    .and_then(|nid| {
                        ctx.peers.get(&*nid).and_then(|p| {
                            (p.value().session.session_id() == session_id).then_some(*nid)
                        })
                    })
                    .or_else(|| {
                        ctx.peers
                            .iter()
                            .find(|e| e.value().session.session_id() == session_id)
                            .map(|e| e.value().node_id)
                    });
                if let Some(nid) = resolved {
                    session.cache_node_id(nid);
                }
                resolved
            });
            let Some(from_node) = from_node else {
                tracing::warn!(
                    target: "mesh.rpc",
                    session_id = session_id,
                    peer_addr = ?session.peer_addr(),
                    "dropping cortex-RPC event: wire session has no resolvable NodeId; \
                     refusing to deliver under sentinel binding"
                );
                return;
            };
            match snapshot {
                Snapshot::Single(canonical, disp) => {
                    for event_data in events.into_iter() {
                        disp(crate::adapter::net::cortex::RpcInboundEvent {
                            channel_hash: canonical,
                            origin_hash,
                            from_node,
                            payload: event_data,
                        });
                    }
                }
                Snapshot::Many(pairs) => {
                    for event_data in events.into_iter() {
                        for (canonical, disp) in &pairs {
                            disp(crate::adapter::net::cortex::RpcInboundEvent {
                                channel_hash: *canonical,
                                origin_hash,
                                from_node,
                                payload: event_data.clone(),
                            });
                        }
                    }
                }
            }
            return;
        }

        // Greedy-LRU observer hook. Non-exclusive (in contrast to
        // the nRPC dispatcher above): if installed, fans every
        // event into the greedy runtime in addition to the
        // application's tail. Greedy is best-effort — failures log
        // + drop inside the runtime; the queue push below is
        // never blocked or skipped on the observer's behalf.
        //
        // Hot-path cost: one `RwLock` read per packet (single-digit
        // ns under parking_lot when uncontended) + one O(1)
        // `addr_to_node` lookup + one capability_index lookup per
        // event when the observer is installed. The runtime
        // itself spawns a tokio task per event to absorb the
        // async dispatch.
        // Blob-transfer data divert (FairScheduler transport plan):
        // reliable event-plane data on a transfer stream-id goes to the
        // transfer engine's reassembly — NOT the event bus. `on_receive`
        // deduped + windowed this packet but does NOT order it (it
        // accepts out-of-order sequences for SACK), so we hand the
        // engine the packet's `sequence` and it reorders by it (header =
        // seq 0, data = seq 1..N). The transfer stream-id convention
        // (bit 61 set, bit 48 clear) makes this a couple of bitops on
        // the hot path.
        #[cfg(feature = "dataforts")]
        if super::dataforts::blob::is_transfer_stream_id(stream_id) {
            let engine_guard = ctx.blob_transfer_engine.read();
            if let Some(engine) = engine_guard.as_ref() {
                engine.on_data(stream_id, parsed.header.sequence, events);
            }
            return;
        }

        #[cfg(feature = "dataforts")]
        let greedy = ctx.greedy_observer.read().clone();

        // Resolve the publisher's capability set so the runtime's
        // scope / intent / colocation gates have something to
        // evaluate against. The wire `origin_hash` is the
        // publisher's `EntityId::origin_hash()` value (full u64
        // since the `WIRE_ORIGIN_HASH_64BIT` cutover); the
        // `origin_hash_to_node` reverse index resolves it back to
        // the publisher's `node_id`.
        //
        // Failure modes:
        //
        // - *Vacant* slot — no announcement has propagated yet
        //   (benign cap-propagation race). Fall back to empty
        //   caps so the observer admits the event under the
        //   default-Mesh scope. Events from new publishers reach
        //   the cache while their first announcement is in
        //   flight.
        //
        // The pre-cutover "ambiguous slot" arm is gone — accidental
        // u64 collisions are 2^-32 (effectively impossible) and
        // adversarial collisions take ~2^32 work per target, and
        // populate first-write-wins so a legitimate publisher's
        // claim isn't displaced. See `docs/plans/WIRE_ORIGIN_HASH_64BIT.md`.
        //
        // Snapshotted once per packet rather than per-event; every
        // event in the same packet shares the same publisher.
        #[cfg(feature = "dataforts")]
        let chain_caps: Option<
            std::sync::Arc<crate::adapter::net::behavior::capability::CapabilitySet>,
        > = if greedy.is_some() {
            let origin_hash: u64 = parsed.header.origin_hash;
            let publisher_node = ctx.origin_hash_to_node.get(&origin_hash).map(|v| *v);
            // Per PERF_AUDIT §4.1: route through the generation-keyed
            // cache instead of re-synthesizing per packet. A 30-tag
            // capability set parses to ~3-5 µs + ~100 allocs per
            // synthesize; a cache hit returns an Arc::clone (~ns).
            // The cache is generation-invalidated by the fold's
            // change_tx, so an inbound `SUBPROTOCOL_CAPABILITY_ANN`
            // bumps it correctly.
            Some(match publisher_node {
                Some(nid) => ctx
                    .capability_set_cache
                    .get_or_synthesize(&ctx.capability_fold, nid),
                None => std::sync::Arc::new(
                    crate::adapter::net::behavior::capability::CapabilitySet::new(),
                ),
            })
        } else {
            None
        };

        // Delivery-order contract (H-8): events are pushed in ARRIVAL
        // order, each tagged with the packet's `seq`. The reliability
        // layer guarantees gap-free eventual delivery (retransmit), but
        // NOT ordering at this point — an out-of-order arrival or a
        // retransmit lands here in the order it hit the wire. Consumers
        // needing strict order reassemble by `StoredEvent::seq` (see the
        // blob-transfer engine's reorder buffer); ones that frame their
        // own ordering (nRPC keys on EventMeta/call_id) or tolerate
        // reordering ignore it.
        let queue = inbound.entry(shard_id).or_default();
        let seq = parsed.header.sequence;
        for (i, event_data) in events.into_iter().enumerate() {
            #[cfg(feature = "dataforts")]
            if let (Some(observer), Some(caps)) = (&greedy, &chain_caps) {
                observer.observe_event(
                    parsed.header.channel_hash,
                    parsed.header.origin_hash,
                    caps.clone(),
                    event_data.clone(),
                );
            }
            use std::fmt::Write;
            let mut event_id = String::with_capacity(24);
            let _ = write!(event_id, "{}:{}", seq, i);
            queue.push(StoredEvent::new(event_id, event_data, seq, shard_id));
        }
    }

    /// Control-plane emission counters (STREAM_ACK_BATCHING B-4):
    /// batched grant/NACK/reset packet+event counts and reliability
    /// retransmit sends. Cheap Arc clone; counters use Relaxed
    /// ordering (monotonic telemetry, no cross-thread contract).
    pub fn control_plane_stats(&self) -> Arc<ControlPlaneStats> {
        self.control_stats.clone()
    }

    /// Drain the per-mesh pending-grant queue and emit the drained
    /// grants **batched per session** (STREAM_ACK_BATCHING B-1/B-2):
    /// one `StreamWindow` packet per session per drain cycle carrying
    /// up to [`GRANT_EVENTS_PER_PACKET`] grant events (plus payload-
    /// budget spill), and one `StreamNack` packet per session for any
    /// piggybacked NACKs. Replaces the post-T1.1 one-packet-per-
    /// stream shape — with S busy streams to a peer that was up to
    /// 2·S AEAD encrypts + `sendto`s per millisecond; now it is
    /// O(sessions). The pre-T1.1-v2 shape was worse still: one
    /// spawn/encrypt/send per accepted inbound packet
    /// (`PERF_AUDIT_2026_05_19_NRPC.md` T1.1). The drainer wakes on
    /// either `pending_stream_grants_notify` or the
    /// `STREAM_GRANT_DRAIN_INTERVAL` self-wake timer, swaps the
    /// queue, and emits serially. Authoritative-grant semantics mean
    /// a single emission per stream subsumes any pending earlier
    /// values for that stream; the receive path's latest-wins
    /// overwrite delivers the freshest `total_consumed` the drainer
    /// needs.
    fn spawn_stream_grant_drainer_loop(&self) -> JoinHandle<()> {
        let socket = self.socket.clone();
        let partition_filter = self.partition_filter.clone();
        let pending = self.pending_stream_grants.clone();
        let notify = self.pending_stream_grants_notify.clone();
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        let control_stats = self.control_stats.clone();
        // R-4/R-5 emission gate inputs: config kill-switch + the
        // per-peer capability cache and its resolution maps.
        let ack_ranges_enabled = self.config.enable_stream_ack_ranges;
        let ack_cache = self.ack_ranges_peer_cache.clone();
        let session_id_to_node = self.session_id_to_node.clone();
        let capability_fold = self.capability_fold.clone();

        tokio::spawn(async move {
            while !shutdown.load(Ordering::Acquire) {
                // Wait for either a fresh enqueue or the drain
                // interval, whichever fires first. The interval
                // wake is a safety net for the case where a Notify
                // signal raced ahead of the enqueue itself (Notify
                // has sticky-permits semantics, so a `notify_one`
                // followed by another `notify_one` before any
                // `.notified()` await collapses to a single wake —
                // a borderline-pathological case but worth covering
                // since the cost is just a 1 ms sleep).
                tokio::select! {
                    _ = notify.notified() => {}
                    _ = tokio::time::sleep(STREAM_GRANT_DRAIN_INTERVAL) => {}
                    _ = shutdown_notify.notified() => {
                        if shutdown.load(Ordering::Acquire) {
                            break;
                        }
                    }
                }

                // Swap the pending map out under a brief lock. New
                // enqueues after the swap go into a fresh empty
                // map; the next drainer cycle picks them up.
                let drained = std::mem::take(&mut *pending.lock());
                if drained.is_empty() {
                    continue;
                }

                // B-1: group by session — the session owns the AEAD
                // cipher, packet pool, and control-seq counter, so it
                // is the unit a batched packet can be built against.
                for (session_id, (session, peer_addr, grants)) in group_grants_by_session(drained) {
                    if partition_filter.contains(&peer_addr) {
                        continue;
                    }
                    // R-5: resolve the peer's SACK-range support once
                    // per session per cycle (cached; see
                    // `peer_supports_ack_ranges`).
                    let emit_ack_ranges = ack_ranges_enabled
                        && peer_supports_ack_ranges(
                            &ack_cache,
                            &session_id_to_node,
                            &capability_fold,
                            session_id,
                        );
                    // Build every grant event — plus the piggybacked
                    // NACK events (STREAM_RETRANSMIT D-2) for streams
                    // with gaps — up front, then emit multi-event
                    // frames: one packet per chunk instead of one (or
                    // two) per stream (B-2/B-3). The decode side has
                    // always iterated the full event vector, so old
                    // peers apply every batched grant/NACK.
                    let (grant_entries, nack_events, ack_events) =
                        build_session_control_events(&session, &grants, emit_ack_ranges);
                    let pool = session.thread_local_pool();
                    let mut builder = pool.get();
                    for chunk in grant_entries.chunks(GRANT_EVENTS_PER_PACKET) {
                        // `Bytes` clone is a refcount bump — the chunk
                        // carries (stream_id, event) pairs so the
                        // post-send accounting below can find each
                        // covered stream.
                        let events: Vec<Bytes> = chunk.iter().map(|(_, e)| e.clone()).collect();
                        let seq = session.next_control_tx_seq();
                        let packet = builder.build_subprotocol(
                            CONTROL_STREAM_ID,
                            seq,
                            &events,
                            PacketFlags::NONE,
                            SUBPROTOCOL_STREAM_WINDOW,
                        );
                        if let Err(e) = socket.send_to(&packet, peer_addr).await {
                            tracing::debug!(error = %e, "StreamWindow grant send failed");
                            continue;
                        }
                        // The chunk cleared the socket: bump each
                        // covered stream's grants-sent counter now.
                        // The counter means "grant datagram sent",
                        // not "grant built" — a failed `send_to` must
                        // not count (post-`sendto` datagram loss was
                        // never distinguishable anyway). Same contract
                        // as the pre-batching one-packet-per-stream
                        // shape, where the bump sat after the send.
                        for (stream_id, _) in chunk {
                            if let Some(state) = session.try_stream(*stream_id) {
                                state.note_grant_sent();
                            }
                        }
                        ControlPlaneStats::record_packet(
                            &control_stats.grant_packets_sent,
                            &control_stats.grant_events_sent,
                            chunk.len(),
                        );
                    }
                    emit_control_chunks(
                        &socket,
                        &mut builder,
                        &session,
                        peer_addr,
                        &nack_events,
                        SUBPROTOCOL_STREAM_NACK,
                        &control_stats.nack_packets_sent,
                        &control_stats.nack_events_sent,
                    )
                    .await;
                    emit_control_chunks(
                        &socket,
                        &mut builder,
                        &session,
                        peer_addr,
                        &ack_events,
                        SUBPROTOCOL_STREAM_ACK,
                        &control_stats.ack_range_packets_sent,
                        &control_stats.ack_range_events_sent,
                    )
                    .await;
                }
            }
        })
    }

    /// Timeout-driven retransmit (STREAM_RETRANSMIT D-4). Every
    /// [`RETRANSMIT_TICK`], walk peers' reliable streams for packets whose
    /// RTO has elapsed and resend them (rebuilt with a fresh AEAD counter,
    /// sent direct). This recovers tail loss — the NACK path only fires
    /// when a *later* packet arrives out of order, so the final dropped
    /// packets of a stream have nothing to trigger a NACK. Descriptors
    /// past `max_retries` are dropped from the window by `get_timed_out`.
    fn spawn_retransmit_loop(&self) -> JoinHandle<()> {
        let peers = self.peers.clone();
        let socket = self.socket.clone();
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        let control_stats = self.control_stats.clone();
        // R-4/R-5 proactive SACK-range emission gate inputs.
        let ack_ranges_enabled = self.config.enable_stream_ack_ranges;
        let ack_cache = self.ack_ranges_peer_cache.clone();
        let session_id_to_node = self.session_id_to_node.clone();
        let capability_fold = self.capability_fold.clone();

        tokio::spawn(async move {
            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    _ = tokio::time::sleep(RETRANSMIT_TICK) => {}
                    _ = shutdown_notify.notified() => {
                        if shutdown.load(Ordering::Acquire) {
                            break;
                        }
                    }
                }

                // Snapshot the due retransmits per peer WITHOUT holding
                // the `peers` DashMap guard across the socket awaits
                // below (that could deadlock against a concurrent peer
                // insert/remove on the same shard).
                let mut work: Vec<(
                    SocketAddr,
                    Arc<NetSession>,
                    Vec<Arc<super::RetransmitDescriptor>>,
                )> = Vec::new();
                for peer in peers.iter() {
                    let due = peer.value().session.collect_timed_out_retransmits();
                    if !due.is_empty() {
                        work.push((peer.value().addr, peer.value().session.clone(), due));
                    }
                }
                for (addr, session, due) in work {
                    let pool = session.thread_local_pool();
                    let mut builder = pool.get();
                    for d in due {
                        let packet = builder.build(d.stream_id, d.seq, &d.events, d.flags);
                        if socket.send_to(&packet, addr).await.is_ok() {
                            control_stats
                                .retransmit_packets_sent
                                .fetch_add(1, Ordering::Relaxed);
                        }
                    }
                }

                // H-3: any stream whose reliable layer gave up
                // retransmitting → tell the peer to fail its pending read
                // now (a `StreamReset`) instead of stalling to a timeout.
                let mut resets: Vec<(SocketAddr, Arc<NetSession>, Vec<u64>)> = Vec::new();
                for peer in peers.iter() {
                    let failed = peer.value().session.take_failed_stream_ids();
                    if !failed.is_empty() {
                        resets.push((peer.value().addr, peer.value().session.clone(), failed));
                    }
                }
                for (addr, session, failed) in resets {
                    let pool = session.thread_local_pool();
                    let mut builder = pool.get();
                    // B-3: all failed streams of a session share one
                    // reset packet (plus payload-budget spill); the
                    // receive path iterates every event in the frame.
                    let reset_events: Vec<Bytes> = failed
                        .into_iter()
                        .map(|stream_id| {
                            Bytes::copy_from_slice(&StreamReset { stream_id }.encode())
                        })
                        .collect();
                    emit_control_chunks(
                        &socket,
                        &mut builder,
                        &session,
                        addr,
                        &reset_events,
                        SUBPROTOCOL_STREAM_RESET,
                        &control_stats.reset_packets_sent,
                        &control_stats.reset_events_sent,
                    )
                    .await;
                }

                // H-4 + R-4: receiver-side proactive gap recovery. One
                // walk per peer collects each gapped stream's report
                // (NACK + SACK ranges from a single reliability-lock
                // snapshot; review TICK2X/I4 — was two separate walks
                // that double-locked every stream and could snapshot
                // the range index at two different instants). The NACK
                // re-requests a hole with no further arrivals (tail
                // loss / sender paused on credit) within a tick instead
                // of waiting the sender's RTO; the SACK (capability-
                // gated per peer, R-5) re-advertises received runs so
                // one head loss doesn't leave the sender's RTO to guess.
                // The grant-piggybacked emission only fires on new
                // arrivals, so this covers the quiet case. Duplicate
                // NACKs are harmless (`on_nack` resends are bounded by
                // `max_retries` and deduped by the receiver).
                struct TickGaps {
                    addr: SocketAddr,
                    session: Arc<NetSession>,
                    reports: Vec<super::session::GapReport>,
                }
                let mut work: Vec<TickGaps> = Vec::new();
                for peer in peers.iter() {
                    let session = &peer.value().session;
                    // SACK ranges only for peers that advertise support
                    // (R-5); a non-advertising peer's report skips the
                    // range build entirely (`want_ranges = false`).
                    let want_ranges = ack_ranges_enabled
                        && peer_supports_ack_ranges(
                            &ack_cache,
                            &session_id_to_node,
                            &capability_fold,
                            session.session_id(),
                        );
                    let reports = session.collect_gap_reports(want_ranges, MAX_ACK_RANGES);
                    if !reports.is_empty() {
                        work.push(TickGaps {
                            addr: peer.value().addr,
                            session: session.clone(),
                            reports,
                        });
                    }
                }
                for TickGaps {
                    addr,
                    session,
                    reports,
                } in work
                {
                    let pool = session.thread_local_pool();
                    let mut builder = pool.get();
                    // B-3: one NACK packet per session per tick (plus
                    // payload-budget spill) — same multi-event framing
                    // as the drainer's piggybacked NACKs.
                    let nack_events: Vec<Bytes> = reports
                        .iter()
                        .map(|r| {
                            Bytes::copy_from_slice(
                                &StreamNack {
                                    stream_id: r.stream_id,
                                    next_expected: r.nack.next_expected,
                                    missing_bitmap: r.nack.missing_bitmap,
                                }
                                .encode(),
                            )
                        })
                        .collect();
                    emit_control_chunks(
                        &socket,
                        &mut builder,
                        &session,
                        addr,
                        &nack_events,
                        SUBPROTOCOL_STREAM_NACK,
                        &control_stats.nack_packets_sent,
                        &control_stats.nack_events_sent,
                    )
                    .await;
                    // R-4: positive SACK ranges for the gapped streams
                    // whose report carried them (only capable peers).
                    let ack_events: Vec<Bytes> = reports
                        .into_iter()
                        .filter(|r| !r.ranges.is_empty())
                        .map(|r| {
                            Bytes::from(
                                StreamAckRanges {
                                    stream_id: r.stream_id,
                                    ack_seq: r.ack_seq,
                                    ranges: r.ranges,
                                }
                                .encode(),
                            )
                        })
                        .collect();
                    emit_control_chunks(
                        &socket,
                        &mut builder,
                        &session,
                        addr,
                        &ack_events,
                        SUBPROTOCOL_STREAM_ACK,
                        &control_stats.ack_range_packets_sent,
                        &control_stats.ack_range_events_sent,
                    )
                    .await;
                }
            }
        })
    }

    /// Spawn heartbeat sender for all peers.
    fn spawn_heartbeat_loop(&self) -> JoinHandle<()> {
        let socket = self.socket.clone();
        let peers = self.peers.clone();
        let addr_to_node = self.addr_to_node.clone();
        let peer_addrs = self.peer_addrs.clone();
        let session_id_to_node = self.session_id_to_node.clone();
        let ack_ranges_peer_cache = self.ack_ranges_peer_cache.clone();
        let route_withdraw_gate = self.route_withdraw_gate.clone();
        let failure_detector = self.failure_detector.clone();
        // SI-2a: sensing soft-state expiry rides this loop's tick —
        // the same cadence as the route/proximity sweeps. Zero work
        // while the plane is dark (flag off = table untouched, hence
        // empty).
        let enable_sensing_coalescing = self.config.enable_sensing_coalescing;
        let sensing_interest_table = self.sensing_interest_table.clone();
        let sensing_emitter = self.sensing_emitter.clone();
        let sensing_observations = self.sensing_observations.clone();
        let sensing_interest_ttl = self.config.sensing_interest_ttl;
        let sensing_overlay_changed = self.sensing_overlay_changed.clone();
        let continuity_factor = self.config.continuity_factor;
        let sensing_capability_interests = self.sensing_capability_interests.clone();
        // SI-2: the leader role's own soft state (per-consumer rows
        // in its relay table, drained interests) expires on the same
        // tick — an abandoned leader must converge to empty
        // (`SensingLeader::sweep`, plan §4.1).
        #[cfg(feature = "redex")]
        let sensing_leader = self.sensing_leader.clone();
        let local_node_id = self.node_id;
        let interval = self.config.heartbeat_interval;
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        let partition_filter = self.partition_filter.clone();
        let proximity_graph = self.proximity_graph.clone();
        let router = self.router.clone();
        // Sweep routes that haven't been refreshed for 3× the session
        // timeout. Direct routes are refreshed by this loop's own
        // pingwave emission; indirect (pingwave-learned) routes age out
        // here if their origin goes silent.
        let max_route_age = self.config.session_timeout.saturating_mul(3);
        // Dead-peer eviction threshold: a peer that has been Failed
        // for this long with no observed traffic is considered
        // permanently gone and dropped from `peers`. Until then we
        // keep the session entry so a transient-partition recovery
        // (the heartbeat the peer sends on the heal triggers
        // `failure_detector.heartbeat`, which `on_recovery`'s the
        // reroute) can succeed — evicting immediately on the first
        // Failed transition would require a full re-handshake to
        // come back. The 30× multiplier gives partitions plenty of
        // time to heal (at the default 30 s session_timeout that's
        // a 15-minute cleanup delay; at test-tight 300 ms timeouts
        // it's 9 s, still comfortably longer than typical test
        // partition-heal windows).
        let dead_peer_timeout = self.config.session_timeout.saturating_mul(30);
        // Stream lifecycle: drop idle streams past `stream_idle_timeout`
        // and enforce `max_streams` cap via LRU.
        let stream_idle_timeout = self.config.stream_idle_timeout;
        let max_streams = self.config.max_streams;

        tokio::spawn(async move {
            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    _ = tokio::time::sleep(interval) => {
                        // Create a pingwave for this heartbeat cycle
                        let pw = proximity_graph.create_pingwave(HealthStatus::Healthy);
                        let pw_bytes = pw.to_bytes();

                        // Snapshot the peer set into a Vec before
                        // awaiting any send — pre-fix the loop held
                        // a DashMap shard `Ref` guard across each
                        // `socket.send_to(...).await` (twice per peer:
                        // heartbeat then pingwave), blocking every
                        // other task that touched the same shard
                        // (`peers.insert` from `connect`/`accept`/
                        // `handle_routed_handshake`, `peers.get` from
                        // the data path, etc.) for the cumulative
                        // round-trip of N×2 sends per heartbeat tick.
                        // `Session::build_heartbeat` routes through
                        // `thread_local_pool` (same pool the data path
                        // uses) so heartbeats and data share a single
                        // `tx_counter`; constructing a fresh
                        // `PacketBuilder::new(&[0u8; 32],
                        // session.session_id())` per heartbeat would
                        // (a) use the wrong key so the receiver's AEAD
                        // verify would reject every tag, and (b) reuse
                        // counter=0 across heartbeats so the replay
                        // window would reject every heartbeat after
                        // the first.
                        let snapshot: Vec<(SocketAddr, Arc<NetSession>)> = peers
                            .iter()
                            .filter_map(|entry| {
                                let peer_addr = entry.value().addr;
                                if partition_filter.contains(&peer_addr) {
                                    None
                                } else {
                                    Some((peer_addr, entry.value().session.clone()))
                                }
                            })
                            .collect();
                        for (peer_addr, session) in snapshot {
                            let packet = session.build_heartbeat();
                            let _ = socket.send_to(&packet, peer_addr).await;
                            // Pingwave (raw UDP — not encrypted, topology is public)
                            let _ = socket.send_to(&pw_bytes, peer_addr).await;
                        }

                        // Drop routes whose `updated_at` is past the age
                        // limit. Small scan of the routing table; cheap.
                        router.routing_table().sweep_stale(max_route_age);

                        // Age out proximity graph edges in lockstep
                        // with the routing table. If the peer that
                        // used to relay pingwaves for an origin went
                        // silent, both the (peer→origin) edge and the
                        // routing-table entry that depended on it
                        // disappear on the same tick.
                        proximity_graph.sweep_stale_edges(max_route_age);

                        // SI-2a: expire sensing interest soft state
                        // (plan §4.3 — rows drop after 2 missed
                        // ttl/2 refreshes) and honor the derived
                        // upstream consequences. A branch whose last
                        // downstream died deregisters upstream
                        // toward `next_hop(provider)` — the sweep is
                        // the ONLY row-expiry path, so a table that
                        // empties emptied here. A merely-LOOSENED
                        // aggregate (`Register`) is not re-sent from
                        // the sweep in SI-2a: re-registration needs
                        // the full spec (this hop keeps no spec
                        // cache), and the stale stricter D upstream
                        // is conservative — the next downstream
                        // refresh repairs it.
                        if enable_sensing_coalescing {
                            // SI-2: sweep the leader role first —
                            // expired consumer rows drop and fully
                            // abandoned interests drain, so the
                            // leader's coalescing state and this
                            // hop's own Local rows (below) expire on
                            // the same clock.
                            #[cfg(feature = "redex")]
                            {
                                // SI-4 review P0: drive the leader
                                // relay's own clock too — its
                                // down-sampled catch-ups fan out as
                                // real frames.
                                let deliveries = {
                                    let mut slot = sensing_leader.lock();
                                    match slot.as_mut() {
                                        Some(leader) => {
                                            leader.sweep(Instant::now());
                                            leader.poll(Instant::now())
                                        }
                                        None => Vec::new(),
                                    }
                                };
                                if !deliveries.is_empty() {
                                    dispatch_sensing_leader_deliveries(
                                        &socket,
                                        &peers,
                                        &addr_to_node,
                                        &router,
                                        &partition_filter,
                                        local_node_id,
                                        &sensing_observations,
                                        &sensing_overlay_changed,
                                        continuity_factor,
                                        deliveries,
                                        Instant::now(),
                                    );
                                }
                            }
                            // Closure item 7: the stamp snapshot
                            // precedes the expiry read the retire
                            // decisions rest on.
                            let emitter_stamp =
                                sensing_emitter.lock().as_ref().map(|e| e.stamp());
                            let actions =
                                sensing_interest_table.lock().expire(Instant::now());
                            for (key, action) in actions {
                                // Closure item 6: a dead branch
                                // reclaims its observations with
                                // the table.
                                if action == sensing::UpstreamAction::Deregister {
                                    sensing_observations.lock().reclaim_branch(&key);
                                }
                                // SI-4 re-review item 5: a loosened
                                // aggregate re-anchors the surviving
                                // branch's continuity window NOW —
                                // an expiry-shrunk demand must not
                                // keep the stricter deadline on a
                                // quiet stream.
                                if let sensing::UpstreamAction::Register { strictest } = action {
                                    sensing_observations
                                        .lock()
                                        .update_upstream_interval(&key, Some(strictest));
                                }
                                if key.provider == local_node_id {
                                    // SI-3: this node is the origin —
                                    // the last row's expiry retires
                                    // the emission stream (zero idle
                                    // emission, plan §4.7), unless a
                                    // registration raced in after
                                    // the snapshot.
                                    if action == sensing::UpstreamAction::Deregister {
                                        if let (Some(emitter), Some(stamp)) =
                                            (sensing_emitter.lock().as_mut(), emitter_stamp)
                                        {
                                            emitter.retire_if_stale(
                                                &key.interest.interest_digest,
                                                stamp,
                                            );
                                        }
                                    }
                                    continue;
                                }
                                if action == sensing::UpstreamAction::Deregister {
                                    let frame = sensing::SensingInterestFrame::Deregister {
                                        interest_digest: key.interest.interest_digest,
                                        target: Some(key.provider),
                                    };
                                    if let Ok(bytes) = sensing::encode_interest_frame(&frame) {
                                        spawn_sensing_frame_send(
                                            &socket,
                                            &peers,
                                            &addr_to_node,
                                            &router,
                                            &partition_filter,
                                            local_node_id,
                                            key.provider,
                                            sensing::SUBPROTOCOL_SENSING_INTEREST as u64,
                                            sensing::SUBPROTOCOL_SENSING_INTEREST,
                                        bytes,
                                        );
                                    }
                                }
                            }

                            // Closure item 6: age out refusal
                            // TOMBSTONES — records that outlived
                            // their partitioned branch (struct
                            // docs) — once older than the soft-
                            // state lifetime with no live branch
                            // behind them. Two-phase so the
                            // observation and table locks stay
                            // sequential, never nested.
                            let sweep_now = Instant::now();
                            let aged: Vec<sensing::ProviderInterestKey> = {
                                let observations = sensing_observations.lock();
                                observations
                                    .refusals
                                    .iter()
                                    .filter(|(_, (_, stored_at))| {
                                        sweep_now.duration_since(*stored_at)
                                            >= sensing_interest_ttl
                                    })
                                    .map(|(key, _)| key.clone())
                                    .collect()
                            };
                            if !aged.is_empty() {
                                let dead: Vec<sensing::ProviderInterestKey> = {
                                    let table = sensing_interest_table.lock();
                                    aged.into_iter()
                                        .filter(|key| !table.has_entry(key))
                                        .collect()
                                };
                                let mut observations = sensing_observations.lock();
                                let providers: Vec<u64> =
                                    dead.iter().map(|key| key.provider).collect();
                                for key in dead {
                                    observations.refusals.remove(&key);
                                }
                                // Round 2, item 3: a tombstone was
                                // the last thing pinning its
                                // provider's epoch — reclaim it
                                // too, or provider_epochs outlives
                                // everything.
                                observations.reclaim_orphan_epochs(providers);
                            }

                            // SI-4a poll (the frozen SI-0f
                            // `SensingRelay::poll` on the mesh):
                            // expire upstream continuity windows,
                            // refresh the table's hop-rule input,
                            // and flush pending down-sampled beats
                            // whose schedule came due. Three
                            // sequential lock phases — never
                            // nested.
                            let poll_now = Instant::now();
                            let mut overlay_moved = false;
                            let (continuities, pending) = {
                                let mut observations = sensing_observations.lock();
                                let mut continuities = Vec::new();
                                for (branch, cell) in observations.upstream.iter_mut() {
                                    cell.expire_if_due(poll_now);
                                    continuities.push((branch.clone(), cell.continuity()));
                                }
                                // SI-4b: local consumer cells run
                                // the same clock — an expiry that
                                // moves a projection (Ready →
                                // Unknown) fires the overlay
                                // signal.
                                for cell in observations.consumer_cells.values_mut() {
                                    let before = cell.projected();
                                    cell.expire_if_due(poll_now);
                                    overlay_moved |= cell.projected() != before;
                                }
                                // SI-4 review P1: EVERY slot is
                                // checked for row liveness — a
                                // downstream that deregistered
                                // after an ordinary delivery left a
                                // non-pending slot leaking as long
                                // as the branch stayed alive.
                                let slot_keys: Vec<(
                                    (sensing::ProviderInterestKey, sensing::DownstreamId),
                                    bool,
                                )> = observations
                                    .slots
                                    .iter()
                                    .map(|(key, slot)| (key.clone(), slot.pending))
                                    .collect();
                                (continuities, slot_keys)
                            };
                            let mut live_pending = Vec::new();
                            let mut dead_slots = Vec::new();
                            {
                                let mut table = sensing_interest_table.lock();
                                for (branch, continuity) in continuities {
                                    table.set_upstream_continuity(&branch, continuity);
                                }
                                for ((branch, downstream), pending) in pending {
                                    match table.downstream_entry(&branch, downstream) {
                                        Some(row) if row.expires_at > poll_now => {
                                            if pending {
                                                live_pending.push((
                                                    branch,
                                                    downstream,
                                                    row.requested_sample_interval,
                                                ));
                                            }
                                        }
                                        // The row died while the
                                        // branch survives: the slot
                                        // is inert — GC it, pending
                                        // or not.
                                        _ => dead_slots.push((branch, downstream)),
                                    }
                                }
                            }
                            let mut flushes: Vec<(u64, Vec<u8>, bool)> = Vec::new();
                            #[cfg(feature = "redex")]
                            let mut leader_feeds: Vec<(
                                sensing::ProviderInterestKey,
                                sensing::ReadinessAttestation,
                                bool,
                            )> = Vec::new();
                            {
                                let mut observations = sensing_observations.lock();
                                for key in dead_slots {
                                    observations.slots.remove(&key);
                                }
                                for (branch, downstream, interval) in live_pending {
                                    let bearing = observations
                                        .upstream
                                        .get(&branch)
                                        .map(|cell| {
                                            cell.continuity()
                                                == sensing::Continuity::Established
                                        })
                                        .unwrap_or(false);
                                    let Some(cached) =
                                        observations.latest.get(&branch).cloned()
                                    else {
                                        continue;
                                    };
                                    let Some(slot) = observations
                                        .slots
                                        .get_mut(&(branch.clone(), downstream))
                                    else {
                                        continue;
                                    };
                                    let newer = slot.last_delivered.is_none_or(|prev| {
                                        (cached.origin_incarnation, cached.seq) > prev
                                    });
                                    if slot.pending && newer && poll_now >= slot.next_due {
                                        slot.last_status = Some(cached.status);
                                        slot.last_delivered =
                                            Some((cached.origin_incarnation, cached.seq));
                                        slot.next_due = poll_now + interval;
                                        slot.pending = false;
                                        match downstream {
                                            sensing::DownstreamId::Peer(node) => {
                                                if let Ok(bytes) =
                                                    sensing::encode_attestation(&cached)
                                                {
                                                    flushes.push((node, bytes, bearing));
                                                }
                                            }
                                            // SI-4b: the local
                                            // consumer's due catch-
                                            // up feeds its cell.
                                            sensing::DownstreamId::Local => {
                                                overlay_moved |= observations
                                                    .feed_consumer_cell(
                                                        &branch,
                                                        &cached,
                                                        bearing,
                                                        interval,
                                                        continuity_factor,
                                                        poll_now,
                                                    );
                                            }
                                            // SI-4 review P0: the
                                            // leader row's catch-up
                                            // hands the cached beat
                                            // to the leader relay.
                                            #[cfg(feature = "redex")]
                                            sensing::DownstreamId::Leader => {
                                                leader_feeds.push((
                                                    branch.clone(),
                                                    cached.clone(),
                                                    bearing,
                                                ));
                                            }
                                            #[cfg(not(feature = "redex"))]
                                            sensing::DownstreamId::Leader => {}
                                        }
                                    }
                                }
                            }
                            #[cfg(feature = "redex")]
                            for (branch, cached, bearing) in leader_feeds {
                                let Ok(semantic) = sensing::semantic_attestation(
                                    &branch.interest,
                                    &cached,
                                ) else {
                                    continue;
                                };
                                let deliveries = {
                                    let mut slot = sensing_leader.lock();
                                    match slot.as_mut() {
                                        Some(leader) => leader.on_attestation(
                                            poll_now, &semantic, bearing,
                                        ),
                                        None => Vec::new(),
                                    }
                                };
                                dispatch_sensing_leader_deliveries(
                                    &socket,
                                    &peers,
                                    &addr_to_node,
                                    &router,
                                    &partition_filter,
                                    local_node_id,
                                    &sensing_observations,
                                    &sensing_overlay_changed,
                                    continuity_factor,
                                    deliveries,
                                    poll_now,
                                );
                            }
                            if overlay_moved {
                                sensing_overlay_changed.send_modify(|generation| {
                                    *generation = generation.wrapping_add(1);
                                });
                            }
                            for (node, bytes, bearing) in flushes {
                                let stream_id = if bearing {
                                    sensing::SUBPROTOCOL_READINESS_ATTESTATION as u64
                                } else {
                                    sensing::SENSING_PROVISIONAL_STREAM
                                };
                                spawn_sensing_frame_send(
                                    &socket,
                                    &peers,
                                    &addr_to_node,
                                    &router,
                                    &partition_filter,
                                    local_node_id,
                                    node,
                                    stream_id,
                                    sensing::SUBPROTOCOL_READINESS_ATTESTATION,
                                    bytes,
                                );
                            }

                            // SI-4 review P0 + P1 (local
                            // lifecycle) + re-review item 6: expire
                            // provider-free digest expectations,
                            // then sweep EVERY materialized branch
                            // against what still justifies it. A
                            // consumer cell survives on a live
                            // Local row OR a live digest watch; the
                            // rest of a branch's observation state
                            // (latest, upstream cell, slots, epoch
                            // share) survives on ANY live table row
                            // or a live watch — provider-free
                            // branches have no provider-keyed row
                            // at this hop, so without this pass no
                            // later table-expiry event would ever
                            // clean them and watch churn would
                            // permanently consume
                            // MAX_SENSING_OBSERVATIONS. Removals
                            // fire the overlay signal when a
                            // visible projection disappeared.
                            let live_interests: std::collections::HashSet<
                                sensing::CapabilityInterestKey,
                            > = {
                                let mut interests =
                                    sensing_capability_interests.lock();
                                interests
                                    .retain(|_, expectation| {
                                        expectation.expires_at > poll_now
                                    });
                                interests.keys().cloned().collect()
                            };
                            let branch_keys: std::collections::HashSet<
                                sensing::ProviderInterestKey,
                            > = {
                                let observations = sensing_observations.lock();
                                observations
                                    .latest
                                    .keys()
                                    .chain(observations.upstream.keys())
                                    .chain(observations.consumer_cells.keys())
                                    .chain(
                                        observations
                                            .slots
                                            .keys()
                                            .map(|(branch, _)| branch),
                                    )
                                    .cloned()
                                    .collect()
                            };
                            let mut dead_branches = Vec::new();
                            let mut dead_cells = Vec::new();
                            {
                                let table = sensing_interest_table.lock();
                                for key in branch_keys {
                                    if live_interests.contains(&key.interest) {
                                        continue;
                                    }
                                    if table.downstreams(&key, poll_now).is_empty() {
                                        // No watch, no rows: nothing
                                        // justifies ANY of the
                                        // branch's state.
                                        dead_branches.push(key);
                                        continue;
                                    }
                                    let local_live = table
                                        .downstream_entry(
                                            &key,
                                            sensing::DownstreamId::Local,
                                        )
                                        .is_some_and(|row| {
                                            row.expires_at > poll_now
                                        });
                                    if !local_live {
                                        // Relay duty continues; only
                                        // the local consumer view
                                        // lost its justification.
                                        dead_cells.push(key);
                                    }
                                }
                            }
                            if !dead_branches.is_empty() || !dead_cells.is_empty() {
                                let mut projection_dropped = false;
                                let mut observations = sensing_observations.lock();
                                for key in dead_branches {
                                    projection_dropped |= observations
                                        .consumer_cells
                                        .contains_key(&key);
                                    observations.reclaim_branch(&key);
                                }
                                for key in dead_cells {
                                    projection_dropped |= observations
                                        .consumer_cells
                                        .remove(&key)
                                        .is_some();
                                }
                                drop(observations);
                                if projection_dropped {
                                    sensing_overlay_changed.send_modify(|generation| {
                                        *generation = generation.wrapping_add(1);
                                    });
                                }
                            }
                        }

                        // Bound the ack-ranges capability-gate cache
                        // (review P2: insert-on-lookup, so peer churn
                        // would otherwise grow it without bound).
                        // Entries for peers with active gapped streams
                        // refresh every ACK_RANGES_CAP_CACHE_TTL; a
                        // swept-but-live peer merely pays one fold
                        // lookup on its next gate check.
                        sweep_ack_ranges_cache(
                            &ack_ranges_peer_cache,
                            ACK_RANGES_CAP_CACHE_MAX_AGE,
                        );

                        // Sweep idle streams per-session and enforce the
                        // per-session `max_streams` cap. Each session is
                        // independent; large deployments with many peers
                        // each with many streams pay O(P + total_streams).
                        for entry in peers.iter() {
                            entry.value().session.evict_idle_streams(
                                stream_idle_timeout,
                                max_streams,
                                "idle_timeout",
                            );
                        }

                        // Dead-peer eviction: walk peers in Failed
                        // state whose session has been inactive for
                        // longer than `dead_peer_timeout`. The
                        // failure-detector `on_failure` callback
                        // does not evict `peers` itself — see the
                        // note in `MeshNode::new` — so this sweep is
                        // the single point where a permanently-gone
                        // peer's session / address mapping drops.
                        // Short-term partitions stay in `peers` long
                        // enough for `on_recovery` to fire when the
                        // heartbeats resume.
                        //
                        // Drive `check_all()` first: the failure
                        // detector only transitions `Healthy → Suspected
                        // → Failed` when its state machine runs. Without
                        // this call, `failed_nodes()` would always be
                        // empty outside tests and the sweep would be a
                        // silent no-op even for permanently-dead peers
                        // (cubic code review P1).
                        let _ = failure_detector.check_all();
                        let failed = failure_detector.failed_nodes();
                        for node_id in failed {
                            let still_silent = match peers.get(&node_id) {
                                Some(e) => e.value().session.is_timed_out(dead_peer_timeout),
                                None => false,
                            };
                            if !still_silent {
                                continue;
                            }
                            if let Some((_, old_info)) = peers.remove(&node_id) {
                                let old_addr = old_info.addr;
                                let old_session_id = old_info.session.session_id();
                                addr_to_node
                                    .remove_if(&old_addr, |_, n| *n == node_id);
                                peer_addrs
                                    .remove_if(&node_id, |_, addr| *addr == old_addr);
                                // PERF_AUDIT §2.4: drop the reverse
                                // `session_id → node_id` entry only if it
                                // still points at this node_id. A
                                // concurrent re-handshake under the same
                                // node_id would have installed a fresh
                                // session_id; we must not erase that.
                                session_id_to_node
                                    .remove_if(&old_session_id, |_, n| *n == node_id);
                                // Targeted ack-ranges gate-cache drop,
                                // in lockstep with the other per-peer
                                // maps. A reconnect under the same
                                // node_id re-resolves through the fold
                                // on its first gate check.
                                ack_ranges_peer_cache.remove(&node_id);
                                tracing::info!(
                                    node_id = format!("{:#x}", node_id),
                                    "evicted permanently-dead peer from peer map",
                                );
                            }
                            // Also drop the failure-detector entry so
                            // a later reconnect under the same node_id
                            // starts from a clean slate — and the
                            // withdrawal-seq gate history for the same
                            // reason (RT-5 ordering gate).
                            failure_detector.remove(node_id);
                            route_withdraw_gate.forget_sender(node_id);
                        }
                    }
                    _ = shutdown_notify.notified() => {
                        break;
                    }
                }
            }
        })
    }

    /// Send a batch of events to a specific peer by address.
    pub async fn send_to_peer(
        &self,
        peer_addr: SocketAddr,
        batch: &Batch,
    ) -> Result<(), AdapterError> {
        // Partition filter: silently drop sends to blocked peers
        if self.partition_filter.contains(&peer_addr) {
            return Ok(());
        }

        let node_id = self
            .addr_to_node
            .get(&peer_addr)
            .map(|e| *e.value())
            .ok_or_else(|| AdapterError::Connection("unknown peer".into()))?;
        let peer = self
            .peers
            .get(&node_id)
            .ok_or_else(|| AdapterError::Connection("unknown peer".into()))?;

        let session = &peer.session;
        let stream_id = batch.shard_id as u64;

        let reliable = {
            let stream = session.get_or_create_stream(stream_id);
            stream.with_reliability(|r| r.needs_ack())
        };

        let pool = session.thread_local_pool();
        let mut builder = pool.get();

        let mut current_batch: Vec<Bytes> = Vec::with_capacity(64);
        let mut current_size = 0usize;

        for event in &batch.events {
            let event_bytes = event.raw.clone();
            let frame_size = EventFrame::LEN_SIZE + event_bytes.len();

            if current_size + frame_size > protocol::MAX_PAYLOAD_SIZE && !current_batch.is_empty() {
                let seq = {
                    let stream = session.get_or_create_stream(stream_id);
                    stream.next_tx_seq()
                };
                let flags = if reliable {
                    PacketFlags::RELIABLE
                } else {
                    PacketFlags::NONE
                };
                let packet = builder.build(stream_id, seq, &current_batch, flags);
                self.socket
                    .send_to(&packet, peer_addr)
                    .await
                    .map_err(|e| AdapterError::Connection(format!("send failed: {}", e)))?;

                current_batch.clear();
                current_size = 0;
            }

            current_batch.push(event_bytes);
            current_size += frame_size;
        }

        if !current_batch.is_empty() {
            let seq = {
                let stream = session.get_or_create_stream(stream_id);
                stream.next_tx_seq()
            };
            let flags = if reliable {
                PacketFlags::RELIABLE
            } else {
                PacketFlags::NONE
            };
            let packet = builder.build(stream_id, seq, &current_batch, flags);
            self.socket
                .send_to(&packet, peer_addr)
                .await
                .map_err(|e| AdapterError::Connection(format!("send failed: {}", e)))?;
        }

        // builder is dropped here — auto-released back to the pool
        drop(builder);
        session.touch();
        Ok(())
    }

    /// Send a batch of events to a destination node via the routing table.
    ///
    /// The events are encrypted with the destination's session key and
    /// a routing header is prepended so intermediate nodes can forward
    /// without decrypting. The packet is sent to the next hop from the
    /// routing table, not directly to the destination.
    ///
    /// Requires:
    /// - A session with `dest_node_id` (for encryption)
    /// - A route to `dest_node_id` in the routing table (for next hop)
    pub async fn send_routed(&self, dest_node_id: u64, batch: &Batch) -> Result<(), AdapterError> {
        // Find the session for the destination (needed for encryption)
        let (dest_addr, session) = self
            .peers
            .get(&dest_node_id)
            .map(|e| (e.value().addr, e.value().session.clone()))
            .ok_or_else(|| {
                AdapterError::Connection(format!("no session for node {:#x}", dest_node_id))
            })?;

        // Find the next hop from the routing table
        let next_hop = self
            .router
            .routing_table()
            .lookup(dest_node_id)
            .unwrap_or(dest_addr); // fall back to direct if no route

        let stream_id = batch.shard_id as u64;
        let reliable = {
            let stream = session.get_or_create_stream(stream_id);
            stream.with_reliability(|r| r.needs_ack())
        };

        let pool = session.thread_local_pool();
        let mut builder = pool.get();

        // Build routing header
        let routing_header = RoutingHeader::new(dest_node_id, self.node_id as u32, 8);
        let routing_bytes = routing_header.to_bytes();

        let mut current_batch: Vec<Bytes> = Vec::with_capacity(64);
        let mut current_size = 0usize;

        for event in &batch.events {
            let event_bytes = event.raw.clone();
            let frame_size = EventFrame::LEN_SIZE + event_bytes.len();

            if current_size + frame_size > protocol::MAX_PAYLOAD_SIZE && !current_batch.is_empty() {
                let seq = {
                    let stream = session.get_or_create_stream(stream_id);
                    stream.next_tx_seq()
                };
                let flags = if reliable {
                    PacketFlags::RELIABLE
                } else {
                    PacketFlags::NONE
                };
                // Build encrypted packet, then prepend routing header
                let net_packet = builder.build(stream_id, seq, &current_batch, flags);
                let mut routed =
                    bytes::BytesMut::with_capacity(ROUTING_HEADER_SIZE + net_packet.len());
                routed.extend_from_slice(&routing_bytes);
                routed.extend_from_slice(&net_packet);

                self.socket
                    .send_to(&routed, next_hop)
                    .await
                    .map_err(|e| AdapterError::Connection(format!("send failed: {}", e)))?;

                current_batch.clear();
                current_size = 0;
            }

            current_batch.push(event_bytes);
            current_size += frame_size;
        }

        if !current_batch.is_empty() {
            let seq = {
                let stream = session.get_or_create_stream(stream_id);
                stream.next_tx_seq()
            };
            let flags = if reliable {
                PacketFlags::RELIABLE
            } else {
                PacketFlags::NONE
            };
            let net_packet = builder.build(stream_id, seq, &current_batch, flags);
            let mut routed = bytes::BytesMut::with_capacity(ROUTING_HEADER_SIZE + net_packet.len());
            routed.extend_from_slice(&routing_bytes);
            routed.extend_from_slice(&net_packet);

            self.socket
                .send_to(&routed, next_hop)
                .await
                .map_err(|e| AdapterError::Connection(format!("send failed: {}", e)))?;
        }

        drop(builder);
        session.touch();
        Ok(())
    }

    // ── Channel membership API ─────────────────────────────────────────

    /// Access the per-channel subscriber roster. Used by `ChannelPublisher`
    /// to enumerate subscribers; exposed for diagnostics.
    pub fn roster(&self) -> &Arc<SubscriberRoster> {
        &self.roster
    }

    /// Register a per-channel-hash inbound dispatcher for nRPC.
    ///
    /// When the mesh's inbound dispatch sees a packet whose
    /// `NetHeader::channel_hash` matches `channel_hash`, it routes
    /// every event in the packet to `dispatcher` and skips the
    /// per-shard inbound queue. Used by `Mesh::serve_rpc` /
    /// `Mesh::call` to receive RPC events without polling the
    /// shard queue.
    ///
    /// Returns the previous dispatcher (if any) so callers can
    /// detect a slot collision (typically a programming error —
    /// two `serve_rpc` registrations for the same service on the
    /// same node, or a hash collision between two different
    /// channel names; the latter is bounded at ~1/65536 per pair).
    ///
    /// **Hot-path cost.** One DashMap get per inbound packet.
    /// Absent registrations skip the conditional entirely.
    #[cfg(feature = "cortex")]
    pub fn register_rpc_inbound(
        &self,
        channel_hash: ChannelHash,
        dispatcher: crate::adapter::net::cortex::RpcInboundDispatcher,
    ) -> Option<crate::adapter::net::cortex::RpcInboundDispatcher> {
        // The dispatcher map is indexed by the wire `u16` hash for
        // O(1) lookup on the inbound packet path; each bucket holds
        // a list of `(canonical ChannelHash, dispatcher)` entries so
        // wire-bucket collisions between independently-registered
        // canonical channels don't share a dispatcher slot. Replace
        // any existing entry for the same canonical hash; otherwise
        // append.
        let wire = channel_hash as u16;
        let mut entry = self.rpc_inbound_dispatchers.entry(wire).or_default();
        for (existing_canonical, existing_disp) in entry.iter_mut() {
            if *existing_canonical == channel_hash {
                return Some(std::mem::replace(existing_disp, dispatcher));
            }
        }
        entry.push((channel_hash, dispatcher));
        None
    }

    /// Remove the registered dispatcher for `channel_hash`. Returns
    /// the prior dispatcher if one was registered. After removal,
    /// inbound events for `channel_hash` resume landing in the
    /// per-shard inbound queue.
    #[cfg(feature = "cortex")]
    pub fn unregister_rpc_inbound(
        &self,
        channel_hash: ChannelHash,
    ) -> Option<crate::adapter::net::cortex::RpcInboundDispatcher> {
        let wire = channel_hash as u16;
        let removed = {
            let mut entry = self.rpc_inbound_dispatchers.get_mut(&wire)?;
            let pos = entry.iter().position(|(c, _)| *c == channel_hash)?;
            let (_, removed) = entry.remove(pos);
            removed
        };
        // Release the wire-bucket slot only if it's *still* empty when
        // the shard lock comes back under our hand. A naive "check
        // is_empty, drop the guard, then `remove`" would race with a
        // concurrent `register_rpc_inbound` for a different canonical
        // sharing the same wire bucket — that thread would push its
        // entry between our drop and remove, and we'd then delete its
        // freshly-registered dispatcher. `remove_if` evaluates its
        // predicate while holding the shard lock, so the empty-check
        // and remove are atomic.
        self.rpc_inbound_dispatchers
            .remove_if(&wire, |_, v| v.is_empty());
        Some(removed)
    }

    /// Cheap probe: is a dispatcher already registered for this
    /// canonical channel hash? Used by the caller-side
    /// `ensure_reply_subscription` to skip a redundant registration
    /// when multiple targets serve the same service (they share
    /// one reply channel + one dispatcher per caller).
    #[cfg(feature = "cortex")]
    pub fn rpc_inbound_dispatcher_registered(&self, channel_hash: ChannelHash) -> bool {
        self.rpc_inbound_dispatchers
            .get(&(channel_hash as u16))
            .map(|entry| entry.iter().any(|(c, _)| *c == channel_hash))
            .unwrap_or(false)
    }

    /// Per-Mesh shared `RpcClientPending` — accessor for the
    /// `mesh_rpc::Mesh::call` glue. Pending oneshots awaiting
    /// RESPONSE events live here.
    #[cfg(feature = "cortex")]
    pub(super) fn rpc_client_pending_arc(
        &self,
    ) -> Arc<crate::adapter::net::cortex::RpcClientPending> {
        self.rpc_client_pending.clone()
    }

    /// Independent rotation counter for `RoutingPolicy::RoundRobin`
    /// / `Random`. See the field's doc-comment on `MeshNode` for
    /// the rationale (avoid concurrent `select_target` calls
    /// observing the same value).
    #[cfg(feature = "cortex")]
    pub(super) fn rpc_round_robin_cursor_arc(&self) -> Arc<std::sync::atomic::AtomicU64> {
        self.rpc_round_robin_cursor.clone()
    }

    /// Tracks already-established (target, service) reply
    /// subscriptions. Accessor for `mesh_rpc::Mesh::call`'s
    /// lazy-subscribe path. Keyed by `(target, xxh3_64(service))`
    /// with the full service name as the collision-verified value
    /// (see the field doc).
    #[cfg(feature = "cortex")]
    pub(super) fn rpc_reply_subscriptions_arc(
        &self,
    ) -> Arc<dashmap::DashMap<(u64, u64), Arc<str>>> {
        self.rpc_reply_subscriptions.clone()
    }

    /// This node's `origin_hash` (8-byte BLAKE2s of the entity
    /// public key). Accessor for `mesh_rpc::Mesh::serve_rpc` /
    /// `Mesh::call` to stamp on outgoing REQUEST / RESPONSE meta
    /// headers.
    #[cfg(feature = "cortex")]
    pub(super) fn public_key_origin_hash(&self) -> u64 {
        self.identity.entity_id().origin_hash()
    }

    /// Per-service nRPC route lookup with lazy build.
    ///
    /// Hot path: one `DashMap::get(&str)` + `Arc::clone` — no
    /// allocations on the cached-hit case.
    ///
    /// Cold path (first call per service): runs `format!` ×2 +
    /// `ChannelName::new` ×2 (which validates the name) +
    /// `ChannelId::new` + `publish_stream_id` derivation, then
    /// either inserts the `Arc<RpcRoute>` into the cache or — past
    /// [`RPC_ROUTE_CACHE_SOFT_CAP`] — returns the built `Arc`
    /// without caching it. Returns `Err(reason)` if either channel
    /// name fails validation (caller maps to `RpcError::NoRoute`).
    ///
    /// Soft cap rationale: callers pass `service: &str` that, in
    /// principle, can flow from outside (typed-RPC traits make it
    /// effectively static, but the raw-call surface does not enforce
    /// that). The cap keeps memory worst-case bounded while leaving
    /// the steady-state path (few distinct services per node)
    /// untouched.
    #[cfg(feature = "cortex")]
    pub(super) fn rpc_route_for_service(&self, service: &str) -> Result<Arc<RpcRoute>, String> {
        if let Some(r) = self.rpc_route_cache.get(service) {
            return Ok(Arc::clone(r.value()));
        }
        // Cold path. Build first (this is the fallible step — name
        // validation), then decide whether to insert.
        let route = Arc::new(self.build_rpc_route(service)?);
        // Soft cap. We re-check membership inside the cap branch
        // because another caller may have populated this service
        // between our initial `get` and here; in that case
        // `entry().or_insert_with` returns their `Arc` and our
        // freshly-built one is dropped — both encode the same
        // bytes, so either is correct, but reusing the cached one
        // keeps the cache canonical.
        //
        // Over the cap we deliberately skip caching but still
        // return a correct route. A racing inserter could push us
        // marginally over the cap; that's by design — the cap is
        // soft, and a sharp boundary would require an extra lock
        // we don't want on the hot path.
        if self.rpc_route_cache.len() < RPC_ROUTE_CACHE_SOFT_CAP {
            let entry = self
                .rpc_route_cache
                .entry(service.to_string())
                .or_insert_with(|| Arc::clone(&route));
            Ok(Arc::clone(entry.value()))
        } else {
            Ok(route)
        }
    }

    /// Cold-path constructor for [`RpcRoute`]. Pulled out of
    /// `rpc_route_for_service` so the cache management logic stays
    /// readable and so tests can exercise the build path
    /// independently of cache state.
    #[cfg(feature = "cortex")]
    fn build_rpc_route(&self, service: &str) -> Result<RpcRoute, String> {
        let request_channel = ChannelName::new(&format!("{service}.requests"))
            .map_err(|e| format!("invalid service name: {e}"))?;
        let request_channel_id = ChannelId::new(request_channel.clone());
        let request_channel_hash = request_channel_id.hash();
        let request_stream_id = Self::publish_stream_id(&request_channel_id);
        let self_origin = self.public_key_origin_hash();
        let reply_channel = ChannelName::new(&format!("{service}.replies.{self_origin:016x}"))
            .map_err(|e| format!("invalid reply channel name: {e}"))?;
        let reply_hash = reply_channel.hash();
        Ok(RpcRoute {
            request_channel,
            request_channel_hash,
            request_stream_id,
            reply_channel,
            reply_hash,
        })
    }

    /// Registry of nRPC services this node currently serves.
    /// `mesh_rpc::serve_rpc` adds entries; `ServeHandle::Drop`
    /// removes them. `announce_capabilities` reads this to
    /// auto-merge `nrpc:<service>` tags. Mutations bump the
    /// local-caps change signal (RT-2) from inside the registry.
    #[cfg(feature = "cortex")]
    pub(super) fn rpc_local_services_arc(&self) -> Arc<LocalServiceRegistry> {
        self.rpc_local_services.clone()
    }

    /// Subscribe to the local-origin capability change signal
    /// (RT-2). The generation bumps on every mutation of this
    /// node's OWN announced surface — `serve_tool`
    /// register/unregister, nRPC service register/deregister —
    /// and never on inbound peer announcements. `watch<u64>`
    /// generation counter, so a subscriber that was busy during a
    /// bump still observes it on the next `changed()` (missed-
    /// wakeup-safe, same contract as `Fold::subscribe_changes`).
    pub fn subscribe_local_caps_changes(&self) -> tokio::sync::watch::Receiver<u64> {
        self.local_caps_changed.subscribe()
    }

    /// Current local-caps generation — cheap staleness check for
    /// consumers that poll opportunistically instead of holding a
    /// receiver.
    pub fn local_caps_generation(&self) -> u64 {
        *self.local_caps_changed.borrow()
    }

    /// Test seam: fire the RT-2 local-caps change signal as if a local
    /// registry mutation happened, without standing up the cortex/tool
    /// registries. Drives the change-driven announce loop in unit tests.
    #[cfg(test)]
    pub(crate) fn test_bump_local_caps_changed(&self) {
        self.local_caps_changed
            .send_modify(|g| *g = g.wrapping_add(1));
    }

    /// Monotonic capability-version counter — the version stamped into
    /// the most recent `CapabilityAnnouncement`. Every
    /// `announce_capabilities_with` call bumps it, broadcast and
    /// rate-limit-coalesced alike.
    ///
    /// NOTE: this is NOT a pure count of announce *calls*.
    /// `index_self_with_local_services` (invoked by `serve_rpc`
    /// on the cortex path) also bumps the same counter without a
    /// broadcast — a "sync, no broadcast" self-index. So on an
    /// RPC-serving node the delta over a window can exceed the number
    /// of announces (RT-3 review Finding 13). Tests that treat the
    /// delta as an announce-call count (e.g. proving the RT-3 debounce
    /// collapses a burst into one announce) are only exact on nodes
    /// that never `serve_rpc`. The over-bump is harmless at runtime:
    /// the counter's only wire role is a monotonic version where
    /// receivers keep the highest per node_id.
    pub fn capability_announce_version(&self) -> u64 {
        self.capability_version.load(Ordering::Relaxed)
    }

    /// RT-4: emit an event-triggered pingwave to all connected
    /// peers, rate-limited by `config.event_pingwave_min_gap`.
    /// Called on topology changes (session open, recovery, a
    /// change-driven announce) so routing converges at flood speed;
    /// the heartbeat tick remains the anti-entropy floor.
    ///
    /// `resend` requests the second flood round that closes the
    /// session-open bookkeeping race — pass `true` only from
    /// `connect`/`accept`, where the race exists. Other topology
    /// events (change-driven announce) pass `false` to avoid a
    /// duplicate mesh-wide flood.
    fn emit_event_pingwave(&self, resend: bool) {
        spawn_event_pingwave(
            &self.event_pingwave_gate,
            self.config.event_pingwave_min_gap,
            &self.proximity_graph,
            &self.socket,
            &self.peers,
            &self.partition_filter,
            resend,
        );
        // SI-6 review P1: every event-pingwave moment IS a discrete
        // topology change (session open, recovery, change-driven
        // announce) — scheduler-relevant route economics may have
        // moved, so the unified scheduler-input generation bumps
        // with it.
        if self.config.enable_sensing_coalescing {
            self.sensing_overlay_changed.send_modify(|generation| {
                *generation = generation.wrapping_add(1);
            });
        }
    }

    /// Local-only tool-descriptor registry. SDK-side `serve_tool`
    /// inserts here on registration + removes on Drop; the
    /// `announce_capabilities_with` path reads from it to auto-merge
    /// `ai-tool:<name>` tags, the typed `ToolCapability`, and the
    /// description / streaming / tags metadata keys. Also drives the
    /// `tool.metadata.fetch` RPC handler (A-2b) which answers
    /// "what's the full schema for tool X on this node?".
    #[cfg(feature = "tool")]
    pub fn tool_registry(&self) -> &Arc<crate::adapter::net::cortex::tool::ToolMetadataRegistry> {
        &self.tool_registry
    }

    /// Walk the capability fold for every `ToolCapability` carried
    /// in a published `CapabilitySet`, reconstruct a
    /// [`ToolDescriptor`](crate::adapter::net::cortex::tool::ToolDescriptor)
    /// per (tool_id, version), and return the deduped list with
    /// `node_count` filled in.
    ///
    /// One in-memory pass over the fold; no network. The fold is the
    /// source-of-truth for cross-node tool discovery (substrate
    /// announce merge in A-2a publishes `ToolCapability` + schema
    /// metadata + the `ai-tool:<id>` tag on every announce).
    ///
    /// `matcher` is the standard
    /// [`TagMatcher`](super::behavior::fold::capability_aggregation::TagMatcher)
    /// — an entry is included if ANY of its tags match. Pass `None`
    /// to skip pre-filtering. The classic use case is region-scoping
    /// the discovery (`Some(TagMatcher::Prefix { value: "region.eu".into() })`).
    ///
    /// Schema hydration: schemas live in `CapabilitySet::metadata`
    /// (too large for tag wire-format); the tag-decoded
    /// `ToolCapability` carries `input_schema = None` / `output_schema = None`
    /// until this method fills them from the membership's metadata
    /// map using the
    /// [`ToolCapability::input_schema_metadata_key`](super::behavior::capability::ToolCapability::input_schema_metadata_key)
    /// / `output_schema_metadata_key` keys.
    #[cfg(feature = "tool")]
    pub fn list_tools(
        &self,
        matcher: Option<&super::behavior::fold::capability_aggregation::TagMatcher>,
    ) -> Vec<crate::adapter::net::cortex::tool::ToolDescriptor> {
        use std::collections::{HashMap, HashSet};

        use super::behavior::tag::Tag;
        use super::behavior::tag_codec::tools_from_tags;
        use super::behavior::ToolCapability;
        use crate::adapter::net::cortex::tool::ToolDescriptor;

        // Validate the matcher up front — surface a structured panic
        // here rather than burying it inside the fold walk, where the
        // diagnostic would be one stack frame deeper. Mirrors the
        // existing capability_aggregation contract: caller is expected
        // to have run `TagMatcher::validate(&matcher)?` ahead of this
        // call if the matcher is user-supplied.
        if let Some(m) = matcher {
            if let Err(e) = m.validate() {
                panic!(
                    "MeshNode::list_tools given a matcher this binary can't \
                     evaluate: {e}",
                );
            }
        }

        // (tool_id, version) → (descriptor, contributing node ids).
        // `HashSet<u64>` so a node serving the same (id, version)
        // across multiple class entries counts once.
        type Bucket = (ToolDescriptor, HashSet<u64>);
        let mut buckets: HashMap<(String, String), Bucket> = HashMap::new();

        self.capability_fold.with_state(|state| {
            for ((_class, node_id), entry) in state.entries.iter() {
                let membership = &entry.payload;
                if let Some(matcher) = matcher {
                    if !matcher.matches_any(&membership.tags) {
                        continue;
                    }
                }
                // Parse tags → reconstruct `Vec<ToolCapability>`.
                // Tag::parse rejects malformed strings; we skip those.
                let parsed_tags: Vec<Tag> = membership
                    .tags
                    .iter()
                    .filter_map(|s| Tag::parse(s).ok())
                    .collect();
                let tools = tools_from_tags(&parsed_tags);
                if tools.is_empty() {
                    continue;
                }
                let metadata = &membership.metadata;
                for mut cap in tools {
                    // Hydrate schemas from metadata. The tag codec
                    // doesn't carry them; the announce path stashes
                    // them on `CapabilitySet::metadata` under these
                    // keys (see `capability::CapabilitySet::add_tool`).
                    if cap.input_schema.is_none() {
                        if let Some(s) =
                            metadata.get(&ToolCapability::input_schema_metadata_key(&cap.tool_id))
                        {
                            cap.input_schema = Some(s.clone());
                        }
                    }
                    if cap.output_schema.is_none() {
                        if let Some(s) =
                            metadata.get(&ToolCapability::output_schema_metadata_key(&cap.tool_id))
                        {
                            cap.output_schema = Some(s.clone());
                        }
                    }
                    let descriptor = ToolDescriptor::from_capability(&cap, metadata);
                    let key = (descriptor.tool_id.clone(), descriptor.version.clone());
                    // Latest-wins on the descriptor fields (excluding
                    // node_count, which we fill after the walk). Two
                    // nodes serving the same (id, version) but with
                    // diverging metadata (description text drift, tag
                    // additions) get the latest-seen view. Equivalent
                    // to "take whichever entry the fold walked last";
                    // not deterministic across runs but the fields
                    // are operator-controlled metadata, not contract.
                    use std::collections::hash_map::Entry;
                    let bucket = match buckets.entry(key) {
                        Entry::Occupied(e) => {
                            let bucket = e.into_mut();
                            bucket.0 = descriptor;
                            bucket
                        }
                        Entry::Vacant(e) => e.insert((descriptor, HashSet::new())),
                    };
                    bucket.1.insert(*node_id);
                }
            }
        });

        let mut out: Vec<ToolDescriptor> = buckets
            .into_iter()
            .map(|(_, (mut desc, nodes))| {
                desc.node_count = nodes.len() as u32;
                desc
            })
            .collect();
        // Stable order — agents iterating `list_tools` in a loop
        // (re-rendering UI, comparing snapshots) should see the same
        // shape from one call to the next when the underlying fold
        // hasn't changed.
        out.sort_by(|a, b| a.tool_id.cmp(&b.tool_id).then(a.version.cmp(&b.version)));
        out
    }

    /// Subscribe to a stream of
    /// [`ToolListChange`](crate::adapter::net::cortex::tool::ToolListChange)
    /// events that reflect every dynamic addition / removal /
    /// publisher-count change in the local capability fold's tool
    /// view, filtered by `matcher` (same semantic as
    /// [`Self::list_tools`]).
    ///
    /// The returned
    /// [`ToolListWatch`](crate::adapter::net::cortex::tool::ToolListWatch)
    /// is a `futures::Stream<Item = ToolListChange>`. The first
    /// event fires AFTER the initial snapshot — callers that need
    /// the baseline shape should call `list_tools` first and then
    /// start the watch.
    ///
    /// Event-driven: the task parks on the capability fold's
    /// change signal (`Fold::subscribe_changes`) and re-diffs
    /// only when the fold actually mutates (a local `serve_tool`,
    /// an inbound peer announcement, an eviction, or a TTL expiry)
    /// — no periodic walk on an idle fold. Change-detection latency
    /// is bounded by fold-apply latency, not a poll interval.
    ///
    /// `interval`:
    /// - `None` — pure event-driven; the task only wakes on a fold
    ///   change. An idle fold does zero periodic work.
    /// - `Some(d)` — event-driven plus a debounce *ceiling*: a
    ///   safety-net re-diff fires at least every `d` even absent a
    ///   change signal. Use this only if you want a hard upper
    ///   bound on staleness independent of the signal path.
    ///
    /// Lifecycle:
    /// - Dropping the
    ///   [`ToolListWatch`](crate::adapter::net::cortex::tool::ToolListWatch)
    ///   stops the task on its next wake (the task observes the
    ///   closed sender and exits).
    /// - The watch handle never errors: a dropped fold (impossible
    ///   while the `MeshNode` arc is alive) would simply end the
    ///   stream. Decode-style errors don't exist here — the
    ///   underlying walk is in-memory and infallible.
    #[cfg(feature = "tool")]
    pub fn watch_tools(
        self: &Arc<Self>,
        matcher: Option<super::behavior::fold::capability_aggregation::TagMatcher>,
        interval: Option<Duration>,
    ) -> crate::adapter::net::cortex::tool::ToolListWatch {
        use crate::adapter::net::cortex::tool::{ToolDescriptor, ToolListChange, ToolListWatch};
        use std::collections::HashMap;
        // Bounded capacity — a slow consumer backpressures the
        // diff task (which awaits in `send`) instead of letting
        // ToolListChange events accumulate without bound.
        let (tx, rx) = tokio::sync::mpsc::channel::<ToolListChange>(256);
        // Cancel signal so a consumer can stop the diff task even
        // when it's parked on the change signal with nothing reading
        // the receiver. The task holds `cancel_task`; the returned
        // `ToolListWatch` holds `cancel` and exposes `.cancel()` /
        // `.cancel_handle()`. `notify_one` stores a permit, so a
        // cancel racing the diff phase is still caught on the next
        // `select!`.
        let cancel = std::sync::Arc::new(Notify::new());
        let cancel_task = cancel.clone();
        // Subscribe to the fold's change signal BEFORE taking the
        // baseline snapshot. A mutation landing between the snapshot
        // and the subscribe would otherwise be lost (the receiver
        // would start past that change's generation); subscribing
        // first guarantees any such change re-fires `changed()` and
        // we re-diff — at worst a redundant pass that finds nothing.
        let mut change_rx = self.capability_fold.subscribe_changes();
        // Take the initial baseline snapshot SYNCHRONOUSLY before
        // returning the watch handle. Without this, a caller that
        // does `let w = watch_tools(...); announce_a_tool().await` can
        // race the spawned task — the announce may land before the
        // task's first `list_tools` call, leaving the new tool in
        // the baseline (and silently skipping the `Added` event).
        let initial_snapshot: HashMap<(String, String), ToolDescriptor> = self
            .list_tools(matcher.as_ref())
            .into_iter()
            .map(|d| ((d.tool_id.clone(), d.version.clone()), d))
            .collect();
        let node = self.clone();
        let matcher_for_task = matcher;
        // `Some(d)` arms a debounce-ceiling timer; `None` leaves the
        // loop purely change-driven (no periodic wakeups).
        let ceiling = interval;
        tokio::spawn(async move {
            let mut prev = initial_snapshot;
            let mut ticker = ceiling.map(|d| {
                let mut t = tokio::time::interval(d);
                t.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
                t
            });
            // Consume the immediate first tick — the snapshot was
            // just taken, so the ceiling clock starts from "now".
            if let Some(t) = ticker.as_mut() {
                t.tick().await;
            }
            loop {
                // Wake on either a fold change or (if armed) the
                // debounce-ceiling tick. With no ceiling, the timer
                // arm is a never-resolving future, so only fold
                // changes drive the loop.
                tokio::select! {
                    r = change_rx.changed() => {
                        // Err means the fold's change-sender dropped
                        // — impossible while `node` (which owns the
                        // fold Arc) is alive, but exit cleanly if so.
                        if r.is_err() {
                            return;
                        }
                    }
                    _ = async {
                        match ticker.as_mut() {
                            Some(t) => {
                                t.tick().await;
                            }
                            None => std::future::pending::<()>().await,
                        }
                    } => {}
                    // Explicit cancel (FFI close, or `ToolListWatch::cancel`).
                    // Returning drops `tx`, which unblocks any consumer
                    // parked in a synchronous recv with `None`.
                    _ = cancel_task.notified() => {
                        return;
                    }
                    // Receiver dropped (the `ToolListWatch` was dropped
                    // without an explicit cancel) — stop promptly
                    // instead of waiting for the next fold change.
                    _ = tx.closed() => {
                        return;
                    }
                }
                if tx.is_closed() {
                    return;
                }
                let next: HashMap<(String, String), ToolDescriptor> = node
                    .list_tools(matcher_for_task.as_ref())
                    .into_iter()
                    .map(|d| ((d.tool_id.clone(), d.version.clone()), d))
                    .collect();
                // Added: in next, not in prev.
                for (key, desc) in next.iter() {
                    if !prev.contains_key(key)
                        && tx.send(ToolListChange::Added(desc.clone())).await.is_err()
                    {
                        return;
                    }
                }
                // Removed: in prev, not in next.
                for (key, desc) in prev.iter() {
                    if !next.contains_key(key)
                        && tx
                            .send(ToolListChange::Removed(desc.clone()))
                            .await
                            .is_err()
                    {
                        return;
                    }
                }
                // NodeCountChanged: in both, but counts differ. (Any
                // other field drift surfaces via this event too —
                // descriptor carries the latest view.)
                for (key, new_desc) in next.iter() {
                    if let Some(old_desc) = prev.get(key) {
                        if new_desc.node_count != old_desc.node_count
                            && tx
                                .send(ToolListChange::NodeCountChanged {
                                    descriptor: new_desc.clone(),
                                    prev_node_count: old_desc.node_count,
                                })
                                .await
                                .is_err()
                        {
                            return;
                        }
                    }
                }
                prev = next;
            }
        });
        ToolListWatch {
            receiver: rx,
            cancel,
        }
    }

    /// Per-Mesh caller-side nRPC metrics registry. Accessor for
    /// `mesh_rpc::Mesh::call` to bump counters on each outgoing
    /// call.
    #[cfg(feature = "cortex")]
    pub(super) fn rpc_metrics_arc(
        &self,
    ) -> Arc<crate::adapter::net::mesh_rpc_metrics::RpcMetricsRegistry> {
        self.rpc_metrics.clone()
    }

    /// Snapshot of caller-side nRPC metrics. Cheap (one DashMap
    /// iteration); call on every Prometheus scrape. Format with
    /// `RpcMetricsSnapshot::prometheus_text`.
    #[cfg(feature = "cortex")]
    pub fn rpc_metrics_snapshot(
        &self,
    ) -> crate::adapter::net::mesh_rpc_metrics::RpcMetricsSnapshot {
        self.rpc_metrics.snapshot()
    }

    /// Install (or clear with `None`) the caller-side nRPC
    /// observer. Replaces any previously-installed observer.
    /// Cheap to load on the hot path — the dispatch path checks
    /// for an installed observer via one `ArcSwap::load` and
    /// short-circuits when `None`. Observers run inline on the
    /// dispatch task; implementations must be cheap (push into
    /// a bounded ring or mpsc, not block).
    ///
    /// See `cortex::rpc_observer::RpcObserver` for the trait
    /// shape and the captured event metadata.
    #[cfg(feature = "cortex")]
    pub fn set_rpc_observer(
        &self,
        observer: Option<crate::adapter::net::cortex::rpc_observer::RpcObserverHandle>,
    ) {
        // Inner `Arc::new` is the double-Arc the field doc calls
        // out — arc_swap's `RefCnt for Arc<T>` requires `T: Sized`,
        // so we cannot store a bare `Arc<dyn RpcObserver>`.
        self.rpc_observer.store(observer.map(Arc::new));
    }

    /// Hot-path load of the currently-installed nRPC observer,
    /// if any. Cheap — one `ArcSwap::load`. The dispatch path
    /// calls this on every completed boundary and short-
    /// circuits when `None`.
    #[cfg(feature = "cortex")]
    pub fn rpc_observer(
        &self,
    ) -> Option<crate::adapter::net::cortex::rpc_observer::RpcObserverHandle> {
        // `load_full()` returns `Option<Arc<Arc<dyn RpcObserver>>>`
        // (see field doc). Clone the inner `Arc<dyn ..>` so the
        // caller holds a flat handle.
        self.rpc_observer.load_full().map(|arc| (*arc).clone())
    }

    /// Reserve a fresh cancel token. Pass on a subsequent call
    /// via [`crate::adapter::net::mesh_rpc::CallOptions::cancel_token`];
    /// later, call [`Self::cancel`] from anywhere to abort the
    /// in-flight task. Tokens are monotonically-increasing,
    /// process-global, never reused. An unused reservation is
    /// harmless — the registry only allocates an entry on the
    /// first paired `register` or `cancel`.
    #[cfg(feature = "cortex")]
    pub fn reserve_cancel_token(&self) -> u64 {
        self.cancel_registry.reserve_token()
    }

    /// Abort the in-flight call associated with `token`.
    /// Idempotent — no-op if the token was never used, the call
    /// already resolved, or `token == 0` (the "no token"
    /// sentinel).
    ///
    /// Race-safe: a cancel that arrives BEFORE the call's
    /// `register` runs (the gap between
    /// [`Self::reserve_cancel_token`] and call construction)
    /// latches a pre-cancel flag on the orphan entry; the
    /// subsequent register pre-arms the cancel signal so the
    /// call short-circuits to
    /// [`crate::adapter::net::mesh_rpc::RpcError::Cancelled`]
    /// without ever publishing the REQUEST.
    ///
    /// Triggers a Drop-on-cancel CANCEL frame on the wire via
    /// the call-shape-specific guards (UnaryCallGuard /
    /// ClientStreamCallRaw::Drop / DuplexCallRaw::Drop). See
    /// `crate::adapter::net::cancel_registry` for the registry
    /// implementation.
    #[cfg(feature = "cortex")]
    pub fn cancel(&self, token: u64) {
        self.cancel_registry.cancel(token);
    }

    /// Internal accessor for the per-mesh cancel registry. Used
    /// by the call shapes in `mesh_rpc.rs` to register / release
    /// the cancel-notify for in-flight calls.
    #[cfg(feature = "cortex")]
    pub(crate) fn cancel_registry(
        &self,
    ) -> &Arc<crate::adapter::net::cancel_registry::CancelRegistry> {
        &self.cancel_registry
    }

    /// Number of in-flight calls currently registered with the
    /// cancel registry. Diagnostic — exposed so integration tests
    /// can deterministically poll for call setup completion
    /// instead of guessing with `sleep`. Includes orphan
    /// cancel-only entries that haven't aged out yet.
    #[cfg(feature = "cortex")]
    pub fn cancel_registry_len(&self) -> usize {
        self.cancel_registry.len()
    }

    /// Fire the installed `RpcObserver` (if any) with an
    /// outbound call event. No-op when no observer is wired.
    /// Called from `mesh_rpc::Mesh::call` at every exit
    /// branch.
    #[cfg(feature = "cortex")]
    pub(crate) fn fire_rpc_observer_outbound(
        &self,
        callee: u64,
        method: &str,
        latency_ms: u32,
        status: crate::adapter::net::cortex::rpc_observer::RpcCallStatus,
        request_bytes: u32,
        response_bytes: u32,
    ) {
        if let Some(obs) = self.rpc_observer() {
            let evt = crate::adapter::net::cortex::rpc_observer::RpcCallEvent {
                caller: self.node_id(),
                callee,
                method: method.to_string(),
                latency_ms,
                status,
                request_bytes,
                response_bytes,
                direction: crate::adapter::net::cortex::rpc_observer::RpcDirection::Outbound,
                ts_unix_ms: crate::adapter::net::cortex::rpc_observer::unix_now_ms(),
            };
            obs.on_call(evt);
        }
    }

    /// Bridge from session-layer `node_id: u64` to entity-layer
    /// `[u8; 32]` (the ed25519 public key, used as the
    /// `ProximityGraph` key). `mesh_rpc`'s `LowestLatency` policy
    /// and `filter_unhealthy` option use this to look up
    /// proximity / health data per RPC candidate.
    ///
    /// Returns `None` for nodes the local mesh has not yet seen
    /// an `IdentityEnvelope` from (typically: a node we know
    /// about via capability announcement but haven't completed
    /// a handshake with). Callers treat `None` as "no
    /// proximity-derivable signal," not as "node is dead."
    #[cfg(feature = "cortex")]
    pub(super) fn entity_id_for_node(&self, node_id: u64) -> Option<[u8; 32]> {
        self.peer_entity_ids
            .get(&node_id)
            .map(|e| *e.value().as_bytes())
    }

    /// Install a `ChannelConfigRegistry` whose `can_subscribe` /
    /// `can_publish` rules are consulted for incoming Subscribe
    /// messages. Also constructs a [`SubnetGateway`] over the
    /// same registry + this node's `local_subnet`; the gateway
    /// is read by `MeshNode::gateway()` and powers the
    /// `net gateway` operator surface.
    ///
    /// When unset (the default), all subscribes are accepted, the
    /// subnet-visibility gate is skipped, and `gateway()` returns
    /// `None`. Full capability/token-based authorization additionally
    /// requires a `TokenCache` — see [`Self::set_token_cache`].
    ///
    /// Call this BEFORE [`Self::start`] — the dispatch context is
    /// captured at start time, so a registry installed after start
    /// won't be visible to the receive loop.
    pub fn set_channel_configs(&mut self, configs: Arc<ChannelConfigRegistry>) {
        let gateway = Arc::new(SubnetGateway::new(self.local_subnet, configs.clone()));
        self.channel_configs = Some(configs);
        self.subnet_gateway = Some(gateway);
    }

    /// Read-only handle to this node's [`SubnetGateway`], or
    /// `None` when no `ChannelConfigRegistry` has been installed
    /// (see [`Self::set_channel_configs`]). Operator tooling
    /// (`net gateway stats|exports`) consults this to read the
    /// forwarded/dropped counters and export table.
    pub fn gateway(&self) -> Option<&Arc<SubnetGateway>> {
        self.subnet_gateway.as_ref()
    }

    /// Read-only handle to this node's installed
    /// `ChannelConfigRegistry`, or `None` when no registry has
    /// been installed via [`Self::set_channel_configs`].
    /// Operator tooling (`net channel ls|visibility`) reads
    /// this to enumerate configured channels.
    pub fn channel_configs(&self) -> Option<&Arc<ChannelConfigRegistry>> {
        self.channel_configs.as_ref()
    }

    /// Install a shared `AggregatorRegistry` on the node. Once
    /// installed, operator CLI verbs
    /// (`net aggregator spawn / ls / scale`) and the Deck
    /// AGGREGATORS panel can read + mutate live aggregator
    /// groups through it. Call this BEFORE [`Self::start`] —
    /// installing after the receive loop is live races against
    /// channel-publish initialization. The `debug_assert!` makes
    /// the constraint observable in tests; release builds carry
    /// the doc-comment contract only.
    #[cfg(feature = "cortex")]
    pub fn set_aggregator_registry(
        &mut self,
        registry: Arc<super::behavior::aggregator::AggregatorRegistry>,
    ) {
        debug_assert!(
            !self.started.load(std::sync::atomic::Ordering::SeqCst),
            "set_aggregator_registry must be called before MeshNode::start; \
             installing after the receive loop is live races channel-publish init",
        );
        self.aggregator_registry = Some(registry);
    }

    /// Read-only handle to this node's installed
    /// [`AggregatorRegistry`](super::behavior::aggregator::AggregatorRegistry),
    /// or `None` when no registry has been installed via
    /// [`Self::set_aggregator_registry`]. Nodes that don't run
    /// aggregators leave this empty — callers should treat the
    /// `None` case as "no aggregators registered" and skip
    /// rendering / acting.
    #[cfg(feature = "cortex")]
    pub fn aggregator_registry(
        &self,
    ) -> Option<&Arc<super::behavior::aggregator::AggregatorRegistry>> {
        self.aggregator_registry.as_ref()
    }

    /// Install a shared `TokenCache` used by the channel-auth path.
    /// When set, `authorize_subscribe` and `publish_many` consult
    /// it via `ChannelConfig::can_subscribe` / `can_publish`.
    /// Subscribers that present a token on the wire have their
    /// token installed into this cache (after signature
    /// verification) before the ACL check runs.
    ///
    /// When unset, `require_token` channels always reject —
    /// without a cache there's no way to validate presented tokens
    /// or find pre-cached ones.
    pub fn set_token_cache(&mut self, cache: Arc<TokenCache>) {
        self.token_cache = Some(cache);
    }

    /// Ask `publisher_node_id` to add this node to `channel`'s subscriber set.
    ///
    /// Blocks until the publisher's `Ack` arrives or
    /// `membership_ack_timeout` elapses. Returns `Ok(())` iff the publisher
    /// accepted the subscribe; `AckReason` failures surface as
    /// `AdapterError::Connection`. No token is presented — use
    /// [`Self::subscribe_channel_with_token`] for channels with
    /// `require_token` set. Mode defaults to `Broadcast` (every published
    /// event delivered to this subscriber); use
    /// [`Self::subscribe_channel_in_queue_group`] for work-distribution.
    pub async fn subscribe_channel(
        &self,
        publisher_node_id: u64,
        channel: ChannelName,
    ) -> Result<(), AdapterError> {
        self.send_membership_request(publisher_node_id, channel, true, None, None)
            .await
    }

    /// Subscribe with a single pre-issued [`PermissionToken`] — the
    /// common case where the channel owner granted the subscriber
    /// directly (a one-link chain). For a delegated credential
    /// (owner → … → subscriber) use
    /// [`Self::subscribe_channel_with_chain`].
    ///
    /// The publisher verifies the chain roots at one of the channel's
    /// `token_roots` and binds to the subscriber's entity before
    /// admitting the subscribe.
    pub async fn subscribe_channel_with_token(
        &self,
        publisher_node_id: u64,
        channel: ChannelName,
        token: PermissionToken,
    ) -> Result<(), AdapterError> {
        self.subscribe_channel_with_chain(publisher_node_id, channel, TokenChain::single(token))
            .await
    }

    /// Subscribe presenting a full delegation [`TokenChain`]
    /// (root-to-leaf). Use when the subscriber's grant was delegated
    /// rather than issued directly by the channel owner: the chain's
    /// root link must be signed by one of the channel's `token_roots`
    /// and the leaf must be bound to this node's entity. See
    /// [`TokenChain::verify_authorizes`] for the full contract the
    /// publisher applies.
    pub async fn subscribe_channel_with_chain(
        &self,
        publisher_node_id: u64,
        channel: ChannelName,
        chain: TokenChain,
    ) -> Result<(), AdapterError> {
        self.send_membership_request(
            publisher_node_id,
            channel,
            true,
            Some(chain.to_bytes()),
            None,
        )
        .await
    }

    /// Install this node's own PUBLISH credential for `channel` as a
    /// (possibly delegated, multi-link) [`TokenChain`].
    ///
    /// Use this when the node's right to publish was *delegated*
    /// (owner → … → this node) rather than granted directly by the
    /// channel owner: the publish-side ACL builds a single-link chain
    /// from the local `TokenCache`, whose issuer is the delegator (not
    /// a channel root), so a delegated grant would otherwise fail the
    /// root-anchor check and the node couldn't publish. The held chain
    /// is preferred over the cache fallback on the publish path; its
    /// leaf must be bound to this node's entity. Re-verified against the
    /// current clock + revocation on every publish, so an expired or
    /// revoked held chain fails closed like any other.
    pub fn set_publish_chain(&self, channel: &ChannelName, chain: TokenChain) {
        self.published_chains.insert(channel.hash(), chain);
    }

    /// Subscribe in the named queue group: every published event is
    /// delivered to exactly ONE member of the group, distributed
    /// round-robin across members. The publisher's roster carries
    /// the mode; the same `(channel, queue_group)` pair across
    /// multiple subscribers forms one work-distribution pool. Used
    /// by request/response patterns (nRPC) and any one-of-N
    /// job-distribution shape.
    pub async fn subscribe_channel_in_queue_group(
        &self,
        publisher_node_id: u64,
        channel: ChannelName,
        queue_group: String,
    ) -> Result<(), AdapterError> {
        self.send_membership_request(publisher_node_id, channel, true, None, Some(queue_group))
            .await
    }

    /// Queue-group subscribe with a pre-issued
    /// [`PermissionToken`]. Same auth flow as
    /// [`Self::subscribe_channel_with_token`], queue-group
    /// semantics from [`Self::subscribe_channel_in_queue_group`].
    pub async fn subscribe_channel_in_queue_group_with_token(
        &self,
        publisher_node_id: u64,
        channel: ChannelName,
        queue_group: String,
        token: PermissionToken,
    ) -> Result<(), AdapterError> {
        self.send_membership_request(
            publisher_node_id,
            channel,
            true,
            Some(TokenChain::single(token).to_bytes()),
            Some(queue_group),
        )
        .await
    }

    /// Ask `publisher_node_id` to remove this node from `channel`'s
    /// subscriber set. Mirror of `subscribe_channel`. Mode-agnostic
    /// — unsubscribe finds the peer in whichever mode they're in.
    pub async fn unsubscribe_channel(
        &self,
        publisher_node_id: u64,
        channel: ChannelName,
    ) -> Result<(), AdapterError> {
        self.send_membership_request(publisher_node_id, channel, false, None, None)
            .await
    }

    async fn send_membership_request(
        &self,
        publisher_node_id: u64,
        channel: ChannelName,
        subscribe: bool,
        token: Option<Vec<u8>>,
        queue_group: Option<String>,
    ) -> Result<(), AdapterError> {
        let peer_addr = {
            let peer = self.peers.get(&publisher_node_id).ok_or_else(|| {
                AdapterError::Connection(format!(
                    "no session to publisher {:#x}",
                    publisher_node_id
                ))
            })?;
            peer.addr
        };

        // Random nonces: a process-global sequential counter lets
        // any session peer that observes one nonce predict the next
        // ones and ship spoofed `Ack{nonce: N+k, accepted: false}`
        // frames at small offsets, satisfying a victim's in-flight
        // Subscribe/Unsubscribe with a forged denial. random u64
        // has 2^-64 collision probability per call and is
        // unguessable from another session.
        let mut nonce_bytes = [0u8; 8];
        if let Err(e) = getrandom::fill(&mut nonce_bytes) {
            return Err(AdapterError::Connection(format!(
                "membership nonce generation failed: {e}"
            )));
        }
        let nonce = u64::from_le_bytes(nonce_bytes);
        let msg = if subscribe {
            MembershipMsg::Subscribe {
                channel: channel.clone(),
                nonce,
                token,
                queue_group,
            }
        } else {
            MembershipMsg::Unsubscribe {
                channel: channel.clone(),
                nonce,
            }
        };
        let bytes = membership::encode(&msg);

        let (tx, rx) = oneshot::channel::<MembershipAck>();
        // Bind to publisher_node_id — the node we're sending the
        // Subscribe/Unsubscribe to is the only legitimate Ack source.
        self.pending_membership_acks
            .insert(nonce, (publisher_node_id, tx));

        // Scoped send; if it fails, drop the pending entry so memory
        // doesn't accumulate.
        if let Err(e) = self
            .send_subprotocol(peer_addr, SUBPROTOCOL_CHANNEL_MEMBERSHIP, &bytes)
            .await
        {
            self.pending_membership_acks.remove(&nonce);
            return Err(e);
        }

        let ack = match tokio::time::timeout(self.config.membership_ack_timeout, rx).await {
            Ok(Ok(ack)) => ack,
            Ok(Err(_)) => {
                self.pending_membership_acks.remove(&nonce);
                return Err(AdapterError::Connection(
                    "membership ack channel closed".into(),
                ));
            }
            Err(_) => {
                self.pending_membership_acks.remove(&nonce);
                return Err(AdapterError::Connection(format!(
                    "membership ack timeout ({:?}) for channel {}",
                    self.config.membership_ack_timeout, channel
                )));
            }
        };

        if !ack.accepted {
            return Err(AdapterError::Connection(format!(
                "membership request rejected: {:?}",
                ack.reason
            )));
        }
        Ok(())
    }

    /// Dispatch an inbound Subscribe / Unsubscribe / Ack on the
    /// membership subprotocol.
    fn handle_membership_message(payload: &[u8], from_node: u64, ctx: &DispatchCtx) {
        let msg = match membership::decode(payload) {
            Ok(m) => m,
            Err(e) => {
                tracing::warn!(error = %e, "membership decode failed");
                return;
            }
        };

        match msg {
            MembershipMsg::Subscribe {
                channel,
                nonce,
                token,
                queue_group,
            } => {
                let (accepted, reason) =
                    Self::authorize_subscribe(&channel, from_node, token.as_deref(), ctx);
                if accepted {
                    // Populate the AuthGuard fast path so publish
                    // fan-out can admit this subscriber in <10 ns
                    // without re-walking the ACL. Mirrors the
                    // `roster.add_with_mode` below — both are
                    // keyed on the channel name so they stay
                    // consistent. Auth is mode-agnostic: a
                    // subscriber's queue-group choice doesn't
                    // change which capability tokens authorize the
                    // channel.
                    ctx.auth_guard
                        .allow_channel(subscriber_origin_hash(from_node), &channel);
                    let id = ChannelId::new(channel);
                    let mode = match queue_group {
                        None => crate::adapter::net::channel::SubscriptionMode::Broadcast,
                        Some(name) => crate::adapter::net::channel::SubscriptionMode::QueueGroup(
                            crate::adapter::net::channel::QueueGroupName::new(name),
                        ),
                    };
                    ctx.roster.add_with_mode(id, from_node, mode);
                    Self::clear_auth_failures(from_node, ctx);
                } else if !matches!(
                    reason,
                    Some(AckReason::TooManyChannels) | Some(AckReason::RateLimited)
                ) {
                    // Count auth-rule rejections toward the
                    // failure budget. Resource limits
                    // (TooManyChannels) and throttle short-
                    // circuits (RateLimited) don't — the former
                    // is orthogonal, the latter is the *result*
                    // of past failures and would double-count.
                    Self::record_auth_failure(from_node, ctx);
                }
                Self::send_membership_ack(from_node, nonce, accepted, reason, ctx);
            }
            MembershipMsg::Unsubscribe { channel, nonce } => {
                // Revoke from the fast path first so any in-flight
                // publish stops admitting this subscriber even
                // before the roster update is visible.
                ctx.auth_guard
                    .revoke_channel(subscriber_origin_hash(from_node), &channel);
                let id = ChannelId::new(channel);
                // Drop the retained subscribe chain so it can't be
                // re-validated by the sweep and doesn't leak memory.
                ctx.subscriber_chains.remove(&(from_node, id.hash()));
                ctx.roster.remove(&id, from_node);
                // Unsubscribe is always accepted — idempotent even if the
                // peer wasn't actually subscribed.
                Self::send_membership_ack(from_node, nonce, true, None, ctx);
            }
            MembershipMsg::Ack {
                nonce,
                accepted,
                reason,
            } => {
                // Peer-auth gate. The pending entry records the
                // publisher we sent Subscribe/Unsubscribe to —
                // only that node is authorized to ack. Without
                // this check, any session peer that guessed the
                // nonce (sequential, before this fix) could ship
                // a forged Ack.
                let took = ctx
                    .pending_membership_acks
                    .remove_if(&nonce, |_, (expected, _)| *expected == from_node);
                if let Some((_, (_expected, tx))) = took {
                    let _ = tx.send(MembershipAck { accepted, reason });
                } else if ctx.pending_membership_acks.contains_key(&nonce) {
                    tracing::trace!(
                        nonce,
                        from = from_node,
                        "membership ack from non-publisher session peer; dropping"
                    );
                } else {
                    tracing::debug!(
                        nonce,
                        "membership ack with no pending request (duplicate or timed out)"
                    );
                }
            }
        }
    }

    /// Dispatch an inbound `CapabilityAnnouncement` into the local
    /// capability index. Drops announcements that:
    /// - fail to decode (malformed bytes),
    /// - carry a `node_id` that doesn't match the session's peer
    ///   (a peer can only announce for itself),
    /// - are missing a signature when
    ///   `require_signed_capabilities` is on,
    /// - carry a signature that fails verification against the
    ///   announcement's own `entity_id` (Stage E upgrade).
    ///
    /// `node_id` and `entity_id` are independent values on the
    /// wire; we pin `node_id → entity_id` on first sight so a
    /// later announcement claiming a different `entity_id` for the
    /// same `node_id` won't silently rebind identity.
    /// Decode + route a single `SUBPROTOCOL_REDEX` event payload
    /// to the per-channel runtime via the installed
    /// [`super::redex::ReplicationInboundRouter`]. The payload's
    /// 3-byte header (`subprotocol_id u16 LE + dispatch_code u8`)
    /// keys the [`super::redex::Inbound`] variant constructed from
    /// the rest. Malformed payloads (bad subprotocol id, unknown
    /// dispatch code, truncated body) are dropped silently —
    /// reliable-stream + the peer's heartbeat cycle recovers
    /// observable state without them.
    #[cfg(feature = "redex")]
    fn dispatch_replication_payload(
        payload: &[u8],
        from_node: u64,
        router: &dyn super::redex::ReplicationInboundRouter,
    ) {
        use super::redex::{
            Inbound, SyncHeartbeat, SyncNack, SyncRequest, SyncResponse, DISPATCH_SYNC_HEARTBEAT,
            DISPATCH_SYNC_NACK, DISPATCH_SYNC_REQUEST, DISPATCH_SYNC_RESPONSE,
        };
        if payload.len() < 3 {
            return;
        }
        // dispatch_code lives at byte 2 (after subprotocol_id u16 LE).
        // Each wire type's `from_bytes` validates the full 3-byte
        // header internally; we just peek to choose the decoder.
        let dispatch_code = payload[2];
        let (channel_id, event) = match dispatch_code {
            DISPATCH_SYNC_HEARTBEAT => match SyncHeartbeat::from_bytes(payload) {
                Ok(msg) => (
                    msg.channel_id,
                    Inbound::Heartbeat {
                        from: from_node,
                        msg,
                    },
                ),
                Err(_) => return,
            },
            DISPATCH_SYNC_REQUEST => match SyncRequest::from_bytes(payload) {
                Ok(msg) => (
                    msg.channel_id,
                    Inbound::SyncRequest {
                        from: from_node,
                        msg,
                    },
                ),
                Err(_) => return,
            },
            DISPATCH_SYNC_RESPONSE => match SyncResponse::from_bytes(payload) {
                Ok(msg) => (
                    msg.channel_id,
                    Inbound::SyncResponse {
                        from: from_node,
                        msg,
                    },
                ),
                Err(_) => return,
            },
            DISPATCH_SYNC_NACK => match SyncNack::from_bytes(payload) {
                Ok(msg) => (
                    msg.channel_id,
                    Inbound::SyncNack {
                        from: from_node,
                        msg,
                    },
                ),
                Err(_) => return,
            },
            // Reserved range `0x24..0x2F` lands here when a future
            // peer uses a code we haven't taught yet — silently
            // drop per the opaque-forwarding contract from
            // `SUBPROTOCOLS.md`.
            _ => return,
        };
        // Try to route. Full-buffer rejection / unknown channel
        // return `Err(event)`; both shapes are "drop silently"
        // here — reliable-stream / heartbeat cycle recovers.
        let _ = router.try_route(channel_id, event);
    }

    /// True iff `hop` is a safe next-hop to promote a route through
    /// on the withdrawal path (RT-5): a genuinely-direct, live
    /// session whose address is not the withdrawing sender's.
    ///
    /// `addr` is the address recorded for `hop` (its `PeerInfo.addr`
    /// or `peer_addrs` entry); `via_addr` is the withdrawing peer's
    /// session address. Rejects (a) a hop the failure detector marks
    /// Failed/Suspected — the retained-Failed-peer maps would
    /// otherwise let us install an un-displaceable metric-1 route to
    /// a dead peer; (b) a relayed hop, whose `addr` is the relay's
    /// and does not map back to `hop` in the reverse index; and (c)
    /// any hop whose address equals the withdrawing sender's, which
    /// would re-install exactly the route we just dropped.
    fn promotable_direct_hop(
        addr_to_node: &DashMap<SocketAddr, u64>,
        failure_detector: &FailureDetector,
        hop: u64,
        addr: SocketAddr,
        via_addr: SocketAddr,
    ) -> bool {
        if addr == via_addr {
            return false;
        }
        if addr_to_node.get(&addr).map(|e| *e.value()) != Some(hop) {
            return false;
        }
        !matches!(
            failure_detector.status(hop),
            NodeStatus::Failed | NodeStatus::Suspected
        )
    }

    /// Try to install a proximity-graph alternate route to `dest`
    /// whose first hop is a live, direct peer other than the
    /// withdrawing `from_node`. Returns true iff a route was
    /// installed. Runs the O(E) `path_to` scan, so callers invoke it
    /// off the receive loop (RT-5 review Finding 4).
    #[allow(clippy::too_many_arguments)]
    fn try_promote_graph_alternate(
        proximity_graph: &ProximityGraph,
        router: &NetRouter,
        peer_addrs: &DashMap<u64, SocketAddr>,
        addr_to_node: &DashMap<SocketAddr, u64>,
        failure_detector: &FailureDetector,
        dest: u64,
        from_node: u64,
        via_addr: SocketAddr,
    ) -> bool {
        // Exclude the withdrawing peer as a first hop: the UNRESTRICTED
        // shortest path to `dest` may still start with `from_node` (it
        // withdrew only its OWN route, other edges through it can
        // survive), and taking the shortest path alone would bail here
        // and cascade even when a longer route through a DIFFERENT
        // direct peer exists (RT-5 review P2). The `(from_node, dest)`
        // edge itself was already removed by the caller, so no path can
        // reach `dest` through the withdrawn hop.
        let Some(path) = proximity_graph.path_to_excluding_first_hop(
            &node_id_to_graph_id(dest),
            &node_id_to_graph_id(from_node),
        ) else {
            return false;
        };
        // path[0] is self, path[1] the first hop.
        let Some(first_hop) = path.get(1).map(graph_id_to_node_id) else {
            return false;
        };
        // Excluding the first-hop edge means `path[1]` can no longer be
        // `from_node`; keep the guard as a cheap invariant assertion.
        if first_hop == from_node {
            return false;
        }
        let Some(addr) = peer_addrs.get(&first_hop).map(|a| *a.value()) else {
            return false;
        };
        // Same LIVE + DIRECT gate as the direct path, keyed on the
        // first hop — a relayed or Failed first hop must fall through
        // to the cascade.
        if !Self::promotable_direct_hop(addr_to_node, failure_detector, first_hop, addr, via_addr) {
            return false;
        }
        // Metric mirrors the pingwave-install convention (hops beyond
        // the first + 2): here path.len()-2 intermediate hops + 2.
        let metric = (path.len() as u16).saturating_sub(2).saturating_add(2);
        router
            .routing_table()
            .add_route_with_metric(dest, addr, metric);
        true
    }

    /// RT-5 receive side: the session peer `from_node` declared it
    /// no longer forwards toward `dest`. Drop exactly our
    /// `(dest, next_hop = from_node)` route and the matching
    /// proximity edge, promote an alternate when one exists, and
    /// cascade our own withdrawal when it does not.
    fn handle_route_withdrawal(payload: &[u8], from_node: u64, ctx: &DispatchCtx) {
        if !ctx.enable_route_withdraw {
            return;
        }
        let Some(w) = RouteWithdrawal::from_bytes(payload) else {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                "route-withdraw: malformed payload dropped"
            );
            return;
        };
        let dest = w.dest;
        // Nonsense guards: a withdrawal about ourselves (we always
        // reach ourselves) or about the sender itself (liveness of
        // the direct link is the failure detector's verdict, not
        // the peer's own claim to poison).
        if dest == ctx.local_node_id || dest == from_node {
            return;
        }
        // The `via` leg is the sender's session address — resolved
        // locally, never taken from the wire.
        let Some(via_addr) = ctx.peers.get(&from_node).map(|p| p.value().addr) else {
            return;
        };
        // Ordering gate (cubic review P2): admit only a strictly-
        // newer seq per (sender, dest), so a delayed / duplicated
        // OLDER withdrawal can't tear down a route this sender has
        // since re-withdrawn-and-superseded. Checked after the
        // peer-resolution guard so only live-session senders write
        // gate state. Withdraw vs. pingwave re-advertise has no
        // shared counter; that residual window stays anti-entropy-
        // repaired (plan §6).
        if !ctx.route_withdraw_gate.admit(from_node, dest, w.seq) {
            return;
        }
        // The sender no longer forwards toward `dest`, so alternates
        // must not be synthesized through it either. Unconditional:
        // the edge can exist even when our routing table points
        // elsewhere.
        ctx.proximity_graph
            .remove_edge(node_id_to_graph_id(from_node), node_id_to_graph_id(dest));
        // Drop exactly (dest, next_hop == sender). If our route to
        // dest goes elsewhere, nothing changed for us and the
        // cascade stops here — that scoping is what makes the
        // whole scheme loop-safe.
        let route_dropped = ctx
            .router
            .routing_table()
            .remove_route_if_next_hop_is(dest, via_addr);
        // SI-5 (§4.8): losing our route toward `dest` expires every
        // observation we hold from it — continuity is a claim about
        // the live stream's path, and the stream now rides an
        // unknown one. The sensing consequence keys on
        // REACHABILITY, not only on the exact (dest, via) pair:
        // when our route was via the sender (just dropped) or had
        // ALREADY aged out racing this frame — and no live direct
        // session stands in — the withdrawal confirms the path
        // died. Beats over the promoted alternate (below) or the
        // anti-entropy refresh re-establish hop-by-hop.
        if ctx.enable_sensing_coalescing
            && (route_dropped
                || (ctx.router.routing_table().lookup(dest).is_none()
                    // SI-5 review P1: a relayed PeerInfo is NOT a
                    // live direct session — the reverse mapping and
                    // the failure detector decide.
                    && !sensing_live_direct_session(
                        &ctx.peers,
                        &ctx.addr_to_node,
                        Some(&ctx.failure_detector),
                        dest,
                    )))
        {
            disrupt_sensing_provider(
                &ctx.sensing_interest_table,
                &ctx.sensing_observations,
                &ctx.sensing_overlay_changed,
                dest,
                sensing::DisruptReason::PathFailed,
            );
            #[cfg(feature = "redex")]
            if let Some(leader) = ctx.sensing_leader.lock().as_mut() {
                leader
                    .relay
                    .disrupt_provider(dest, sensing::DisruptReason::PathFailed);
            }
            // SI-6 review P1: a route/topology event is scheduler-
            // relevant even when no projection moved — bump the
            // unified generation unconditionally.
            ctx.sensing_overlay_changed.send_modify(|generation| {
                *generation = generation.wrapping_add(1);
            });
        }
        if !route_dropped {
            return;
        }
        tracing::debug!(
            dest = format!("{:#x}", dest),
            via = format!("{:#x}", from_node),
            "route-withdraw: dropped route"
        );
        // Promote an alternate instead of waiting for traffic to
        // fail: a DIRECT session wins; otherwise synthesize from
        // the proximity graph through a different first hop.
        //
        // Two properties every promotion must hold, or it does more
        // harm than the age-out it replaces:
        //
        //  - LIVE: `peers` / `addr_to_node` / `peer_addrs` retain
        //    Failed peers for transient-partition recovery (see the
        //    note in the failure-detector closure), so a naive
        //    promotion resurrects a metric-1 route to a dead peer
        //    that no higher-metric pingwave can ever displace — a
        //    black hole until the age-out sweep. Gate on the failure
        //    detector: never promote a hop it considers Failed or
        //    Suspected.
        //  - DIRECT and not the sender: a relayed (`connect_via`)
        //    peer entry records the RELAY's address — possibly the
        //    withdrawing sender itself — so promoting it would
        //    re-install exactly the route we just dropped. Only a
        //    direct session's address maps back to the hop in the
        //    reverse index.
        if let Some(peer) = ctx.peers.get(&dest) {
            let addr = peer.value().addr;
            drop(peer);
            if Self::promotable_direct_hop(
                &ctx.addr_to_node,
                &ctx.failure_detector,
                dest,
                addr,
                via_addr,
            ) {
                ctx.router.routing_table().add_route(dest, addr);
                return;
            }
        }
        // No direct alternate. What remains — the O(E) proximity-
        // graph `path_to` scan for a relayed alternate, and (if none)
        // the cascade flood — is the expensive tail a forged-origin
        // withdrawal storm would use to pin the single receive loop.
        // Move it onto a bounded spawned task so the dispatch loop
        // returns now, and cap concurrency so the storm can't spawn
        // unboundedly (RT-5 review Finding 4). The route is already
        // dropped; if we shed this task under load, anti-entropy
        // repairs the alternate/cascade.
        let inflight = ctx.route_withdraw_cascades_inflight.clone();
        if inflight.fetch_add(1, Ordering::AcqRel) >= MAX_INFLIGHT_ROUTE_WITHDRAW_CASCADES {
            inflight.fetch_sub(1, Ordering::AcqRel);
            tracing::debug!(
                dest = format!("{:#x}", dest),
                "route-withdraw: cascade shed (over in-flight cap); anti-entropy repairs"
            );
            return;
        }
        let proximity_graph = ctx.proximity_graph.clone();
        let router = ctx.router.clone();
        let peer_addrs = ctx.peer_addrs.clone();
        let addr_to_node = ctx.addr_to_node.clone();
        let failure_detector = ctx.failure_detector.clone();
        let route_withdraw_seq = ctx.route_withdraw_seq.clone();
        let route_withdraw_damper = ctx.route_withdraw_damper.clone();
        let socket = ctx.socket.clone();
        let peers = ctx.peers.clone();
        let partition_filter = ctx.partition_filter.clone();
        tokio::spawn(async move {
            let promoted = Self::try_promote_graph_alternate(
                &proximity_graph,
                &router,
                &peer_addrs,
                &addr_to_node,
                &failure_detector,
                dest,
                from_node,
                via_addr,
            );
            if !promoted {
                // No alternate: cascade our own withdrawal so upstream
                // nodes stop routing through us. Split horizon: never
                // back toward the peer that told us. AWAITED here (not
                // spawned) so the flood's build+send work is held under
                // this task's in-flight permit — a spawned child would
                // decrement the counter immediately and let unbounded
                // per-dest floods escape the cap (RT-5 review P2).
                run_route_withdrawal_flood(
                    route_withdraw_seq,
                    route_withdraw_damper,
                    socket,
                    peers,
                    partition_filter,
                    dest,
                    Some(from_node),
                )
                .await;
            }
            inflight.fetch_sub(1, Ordering::AcqRel);
        });
    }

    /// SI-2a receive side (SENSING_INTEREST_COALESCING_PLAN §4.2/
    /// §4.3/§4.10): one strict-decoded sensing-interest frame from an
    /// authenticated session peer.
    ///
    /// Authority: the sender's owner root is derived from its
    /// TOFU-pinned entity identity — `peer_entity_ids`, the same
    /// `node_id → EntityId` resolution channel auth and the fold
    /// dispatch arm ride — via
    /// [`sensing::AudienceScopeCommitment::owner_root`]; wire scope
    /// fields are cross-checked against it, never load-bearing. A
    /// session with no pinned entity cannot prove any root, so its
    /// frames drop (the fold arm's rule).
    ///
    /// **Fleet-membership admission (SI-2, the multi-hop half of the
    /// `sensing_owner_root` deviation).** No per-node key can prove
    /// operator fleet ownership — the tree has no ownership model —
    /// so under the strict entity-root rule no relay (and no
    /// consumer that is not itself the owner entity) could ever
    /// re-register upstream: `A → R → next_hop(P)` would die at R's
    /// first hop. When the operator has EXPLICITLY configured
    /// `sensing_owner_root` (the same out-of-band ownership
    /// assertion the receive-side deviation already trusts) and a
    /// pinned sender's wire claim names EXACTLY that root, the
    /// session is admitted as serving the fleet root. Bounded by the
    /// mesh PSK + the TOFU pin; a claim of any OTHER root still
    /// follows the strict rule (an unbacked claim stays
    /// protocol-invalid); default-rooted nodes never admit.
    /// Scoped-capabilities subsumes this with real delegation proofs.
    ///
    /// Per variant:
    /// - `CapabilityRegistration` (leader-addressed): handed to the
    ///   installed [`sensing::SensingLeader`] intake. The leader role
    ///   rides the RedEX election, so ONLY this branch is
    ///   `redex`-gated — the arm itself compiles under plain `net`,
    ///   where leader-addressed frames drop (no election → no leader
    ///   role on this build; provider-leg relaying still works).
    ///   The candidate snapshot is assembled from the LIVE
    ///   fold/proximity/routing planes (SI-2b), and — SI-2's closing
    ///   seam — each branch the leader resolves (or refreshes)
    ///   becomes this hop's OWN `Local` row in the per-hop table,
    ///   whose derived aggregate then propagates upstream toward
    ///   `next_hop(provider)` exactly as
    ///   [`MeshNode::register_sensing_interest`] does. Without that
    ///   seam the leader's coalesced demand would never reach the
    ///   provider direction on the wire.
    /// - `ProviderRegistration` (provider-addressed): full intake —
    ///   [`sensing::SensingInterestFrame::validate_provider_registration`]
    ///   re-derives the COMPLETE digest (counter discipline inside),
    ///   [`sensing::validate_subscriber_scope`] enforces the v1
    ///   owner boundary — then the table registers the sender's row
    ///   and the derived-aggregate delta (RT-1 trailing edge, §4.3)
    ///   propagates upstream toward `next_hop(target)`. A hop that
    ///   IS the target provider has no upstream (the origin emitter
    ///   consuming its rows is SI-3).
    /// - `Deregister`: removes only the SENDER's own rows (a peer
    ///   may always withdraw its own demand — no scope check
    ///   applies), propagating `Deregister` upstream when a branch's
    ///   last downstream died. A removal that merely LOOSENS the
    ///   aggregate is not re-registered upstream in SI-2a (that
    ///   needs the full spec; the stale stricter D upstream is
    ///   conservative and the next downstream refresh repairs it).
    fn handle_sensing_interest_frame(payload: &[u8], from_node: u64, ctx: &DispatchCtx) {
        // Strict decode (wire.rs, 4 KiB cap, trailing bytes
        // rejected): a failure is malformed protocol input — count
        // and drop silently, like the unknown-subprotocol drop.
        let Ok(frame) = sensing::decode_interest_frame(payload) else {
            ctx.sensing_counters
                .protocol_invalid
                .fetch_add(1, Ordering::Relaxed);
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                len = payload.len(),
                "sensing: undecodable 0x0C02 payload dropped"
            );
            return;
        };
        let Some(sender_entity) = ctx
            .peer_entity_ids
            .get(&from_node)
            .map(|e| e.value().clone())
        else {
            tracing::debug!(
                from_node = format!("{:#x}", from_node),
                "sensing: no pinned EntityId for sender, drop frame"
            );
            return;
        };
        // Strict v1 rule: the root the session's pinned entity
        // proves cryptographically.
        let entity_root = sensing::AudienceScopeCommitment::owner_root(&sender_entity);
        // Fleet-membership admission (see the method docs): a pinned
        // sender claiming EXACTLY the fleet root this hop was
        // operator-configured to serve is admitted as serving it.
        // Everything else — any other claim, or a default-rooted
        // receiver — keeps the strict entity-derived root, so an
        // unbacked claim still lands in `WireClaimMismatch`.
        let claimed_scope = match &frame {
            sensing::SensingInterestFrame::CapabilityRegistration { audience_scope, .. }
            | sensing::SensingInterestFrame::ProviderRegistration { audience_scope, .. } => {
                Some(*audience_scope)
            }
            sensing::SensingInterestFrame::Deregister { .. } => None,
        };
        let session_root =
            if ctx.sensing_fleet_scope && claimed_scope == Some(ctx.sensing_local_root) {
                ctx.sensing_local_root
            } else {
                entity_root
            };
        let now = Instant::now();

        match &frame {
            sensing::SensingInterestFrame::CapabilityRegistration {
                capability_id,
                requested_sample_interval,
                soft_state_ttl,
                ..
            } => {
                // Closure item 4 + round 2 item 2: bound the wire
                // interval before any work — `0 < D ≤
                // sensing_interest_ttl` — and refuse zero-ttl rows
                // (dead on arrival).
                if !sensing_interval_in_bounds(*requested_sample_interval, ctx.sensing_interest_ttl)
                    || soft_state_ttl.is_zero()
                {
                    tracing::trace!(
                        from_node = format!("{:#x}", from_node),
                        interval_ms = requested_sample_interval.as_millis() as u64,
                        ttl_ms = soft_state_ttl.as_millis() as u64,
                        "sensing: out-of-bounds interval/ttl dropped"
                    );
                    return;
                }
                // The leader intake rides the RedEX election, so
                // only the redex build has a leader role to feed.
                #[cfg(not(feature = "redex"))]
                let _ = (capability_id, requested_sample_interval, soft_state_ttl);
                #[cfg(feature = "redex")]
                {
                    // Slot empty: this node is not the leader — drop
                    // (soft state; the consumer re-registers with
                    // the real leader) without paying for a
                    // snapshot.
                    if ctx.sensing_leader.lock().is_none() {
                        return;
                    }
                    // SI-2b: the REAL candidate snapshot, assembled
                    // BEFORE re-taking the leader lock so the fold/
                    // proximity/routing reads never nest inside it.
                    // The frame's capability-id claim seeds the
                    // snapshot; the claim is bound by the digest
                    // re-derivation inside `register_from_frame`,
                    // so a lying claim is rejected there and only
                    // ever wastes this read. (A leader uninstalled
                    // between the two lock takes just drops the
                    // frame — the same soft-state contract.)
                    let snapshot = sensing_candidate_snapshot_from_parts(
                        &ctx.capability_fold,
                        &ctx.proximity_graph,
                        &ctx.router,
                        &ctx.peers,
                        &ctx.peer_entity_ids,
                        ctx.local_node_id,
                        ctx.sensing_local_entity_root,
                        &ctx.sensing_local_root,
                        capability_id,
                    );
                    let mut slot = ctx.sensing_leader.lock();
                    let Some(leader) = slot.as_mut() else {
                        return;
                    };
                    // Rejections carry their own counter discipline
                    // inside `register_from_frame`; refusal
                    // *responses* to the consumer are SI-3 wiring.
                    let registration = match leader.register_from_frame(
                        &frame,
                        from_node,
                        &session_root,
                        &ctx.sensing_local_root,
                        &ctx.sensing_counters,
                        &snapshot,
                        now,
                    ) {
                        Ok(registration) => registration,
                        Err(rejection) => {
                            // SI-7: the §4.7 each-mode amplification
                            // guard fired — surface it distinctly from
                            // the scope/digest refusals its siblings
                            // already count.
                            if matches!(
                                rejection,
                                sensing::FrameRejection::Resolution(
                                    sensing::ResolutionRefusal::SelectorTooBroad { .. }
                                )
                            ) {
                                ctx.sensing_counters
                                    .broad_selector_refusals
                                    .fetch_add(1, Ordering::Relaxed);
                            }
                            tracing::debug!(
                                from_node = format!("{:#x}", from_node),
                                rejection = %rejection,
                                "sensing: leader intake refused registration"
                            );
                            return;
                        }
                    };
                    // SI-7 coalescing efficacy (local surface): every
                    // admitted registration counts; the ones that
                    // JOINED an existing interest are the merges, and
                    // a fresh resolution's active set is the candidate
                    // fan-out this leader opened.
                    ctx.sensing_counters
                        .interests_registered
                        .fetch_add(1, Ordering::Relaxed);
                    if registration.newly_resolved {
                        ctx.sensing_counters
                            .candidate_fanout_total
                            .fetch_add(registration.branches.len() as u64, Ordering::Relaxed);
                    } else {
                        ctx.sensing_counters
                            .interests_coalesced
                            .fetch_add(1, Ordering::Relaxed);
                    }
                    // SI-4 review P0: the leader relay's warm-starts
                    // for the registering consumer go out as REAL
                    // provisional frames (§4.4 anti-entropy on the
                    // provider-free path).
                    if !registration.warm_starts.is_empty() {
                        dispatch_sensing_leader_deliveries(
                            &ctx.socket,
                            &ctx.peers,
                            &ctx.addr_to_node,
                            &ctx.router,
                            &ctx.partition_filter,
                            ctx.local_node_id,
                            &ctx.sensing_observations,
                            &ctx.sensing_overlay_changed,
                            ctx.sensing_continuity_factor,
                            registration.warm_starts.clone(),
                            now,
                        );
                    }
                    // SI-2 closing seam: the leader's coalesced
                    // demand per resolved branch — the strictest D
                    // across ALL consumers its relay table holds —
                    // becomes this hop's OWN `Local` row, so the
                    // per-hop table (and from it the upstream
                    // trailing edge toward `next_hop(provider)`)
                    // sees the leader as a first-class subscriber.
                    // Demand thus merges at the leader BEFORE the
                    // provider hop: N consumers → one Local row →
                    // one upstream registration.
                    //
                    // SI-3 sign-off residual: demand derives ONLY
                    // from the branches THIS registration was
                    // admitted on, and ONLY from actual table
                    // aggregates. The former
                    // `unwrap_or(requested_sample_interval)`
                    // fallback reconstructed demand for branches
                    // whose registration was REFUSED (a partial
                    // admission's rowless branches read back as the
                    // refused request) and pushed it upstream
                    // anyway.
                    let branch_demands: Vec<(u64, Duration)> = registration
                        .admitted_branches
                        .iter()
                        .filter_map(|provider| {
                            let branch = sensing::ProviderInterestKey::new(
                                registration.interest.clone(),
                                *provider,
                            );
                            leader
                                .relay
                                .table
                                .aggregate(&branch, now)
                                .map(|strictest| (*provider, strictest))
                        })
                        .collect();
                    drop(slot);
                    if branch_demands.is_empty() {
                        return;
                    }
                    // Re-derive the spec for the upstream frames —
                    // `register_from_frame` already validated it, so
                    // this cannot fail (and if it somehow does, the
                    // drop is the ordinary soft-state contract).
                    let Ok(spec) = frame.validated_spec(&ctx.sensing_counters) else {
                        return;
                    };
                    let ttl = (*soft_state_ttl).min(ctx.sensing_interest_ttl);
                    for (provider, strictest_demand) in branch_demands {
                        let key = sensing::ProviderInterestKey::new(
                            registration.interest.clone(),
                            provider,
                        );
                        let (outcome, aggregate) = {
                            let mut table = ctx.sensing_interest_table.lock();
                            // SI-4 review P0: the leader's coalesced
                            // demand is the LEADER row — distinct
                            // from a node-local application watch,
                            // so returning proofs dispatch to the
                            // leader relay's fan-out, never to the
                            // node's own consumer overlay.
                            let outcome = table.register(
                                &key,
                                sensing::DownstreamId::Leader,
                                strictest_demand,
                                ttl,
                                ctx.sensing_local_root,
                                now,
                            );
                            (outcome, table.aggregate(&key, now))
                        };
                        if !matches!(outcome, sensing::RegisterOutcome::Registered(_)) {
                            continue;
                        }
                        // SI-4 re-review item 5: the Leader row's
                        // demand can move the branch aggregate —
                        // re-anchor the hop's continuity window
                        // immediately.
                        ctx.sensing_observations
                            .lock()
                            .update_upstream_interval(&key, aggregate);
                        // SI-4 re-review P0: the leader resolved
                        // THIS node as provider — there is no
                        // upstream hop; the Leader row feeds the
                        // origin emitter directly, exactly like a
                        // Local self-registration, and the emitter
                        // loop dispatches its signed beats to the
                        // leader relay's fan-out.
                        if provider == ctx.local_node_id {
                            Self::feed_sensing_origin(
                                ctx,
                                &key,
                                &spec,
                                sensing::DownstreamId::Leader,
                                now,
                            );
                            continue;
                        }
                        // Anti-entropy on every admitted refresh,
                        // min-gap damped — the exact
                        // `register_sensing_interest` shape, so a
                        // lost upstream frame is repaired by the
                        // consumer's next ttl/2 refresh.
                        let Some(strictest) = aggregate else {
                            continue;
                        };
                        if !sensing_upstream_damper_admits(
                            &ctx.sensing_upstream_damper,
                            provider,
                            *key.interest.interest_digest.as_bytes(),
                            sensing_effective_min_gap(ttl),
                        ) {
                            continue;
                        }
                        let upstream = sensing::SensingInterestFrame::provider_registration(
                            &spec, provider, strictest, ttl,
                        );
                        if let Ok(bytes) = sensing::encode_interest_frame(&upstream) {
                            spawn_sensing_frame_send(
                                &ctx.socket,
                                &ctx.peers,
                                &ctx.addr_to_node,
                                &ctx.router,
                                &ctx.partition_filter,
                                ctx.local_node_id,
                                provider,
                                sensing::SUBPROTOCOL_SENSING_INTEREST as u64,
                                sensing::SUBPROTOCOL_SENSING_INTEREST,
                                bytes,
                            );
                        }
                    }
                }
            }
            sensing::SensingInterestFrame::ProviderRegistration { audience_scope, .. } => {
                let Ok(validated) = frame.validate_provider_registration(&ctx.sensing_counters)
                else {
                    return;
                };
                // Closure item 4 + round 2 item 2: bound the wire
                // interval — `0 < D ≤ sensing_interest_ttl` — before
                // it can reach the table aggregate or emitter
                // scheduling, and refuse zero-ttl rows (dead on
                // arrival).
                if !sensing_interval_in_bounds(
                    validated.requested_sample_interval,
                    ctx.sensing_interest_ttl,
                ) || validated.soft_state_ttl.is_zero()
                {
                    tracing::trace!(
                        from_node = format!("{:#x}", from_node),
                        interval_ms = validated.requested_sample_interval.as_millis() as u64,
                        ttl_ms = validated.soft_state_ttl.as_millis() as u64,
                        "sensing: out-of-bounds interval/ttl dropped"
                    );
                    return;
                }
                let Ok(proven_root) = sensing::validate_subscriber_scope(
                    &session_root,
                    audience_scope,
                    &ctx.sensing_local_root,
                    &validated.spec.audience,
                    &ctx.sensing_counters,
                ) else {
                    return;
                };
                let key = sensing::ProviderInterestKey::new(validated.spec.key(), validated.target);
                // Cap the accepted lifetime at the local soft-state
                // horizon (plan §5) so a downstream can't pin rows.
                let ttl = validated.soft_state_ttl.min(ctx.sensing_interest_ttl);
                let outcome = ctx.sensing_interest_table.lock().register(
                    &key,
                    sensing::DownstreamId::Peer(from_node),
                    validated.requested_sample_interval,
                    ttl,
                    proven_root,
                    now,
                );
                match outcome {
                    sensing::RegisterOutcome::Registered(action) => {
                        // The target provider itself has no upstream —
                        // there the registration feeds the origin
                        // emitter instead (SI-3).
                        if validated.target == ctx.local_node_id {
                            // SI-7 coalescing-efficacy headline (plan
                            // §4.1): this node is the PROVIDER. For a
                            // provider-free interest, a second DISTINCT
                            // upstream on the branch means two leaders
                            // resolved the same interest here — the
                            // residual divergent resolution the future
                            // gate weighs. Provider-targeted
                            // (`Node`/`Nodes`) registrations are
                            // excluded: multiple direct surveillants
                            // are intended, not a coalescing failure.
                            if validated.spec.providers.is_provider_free() {
                                ctx.sensing_counters
                                    .provider_free_registrations
                                    .fetch_add(1, Ordering::Relaxed);
                                let distinct_upstreams = ctx
                                    .sensing_interest_table
                                    .lock()
                                    .downstreams(&key, now)
                                    .into_iter()
                                    .filter(|downstream| {
                                        matches!(downstream, sensing::DownstreamId::Peer(_))
                                    })
                                    .count();
                                if distinct_upstreams >= 2 {
                                    ctx.sensing_counters
                                        .divergent_resolution_merge_miss
                                        .fetch_add(1, Ordering::Relaxed);
                                }
                            }
                            Self::feed_sensing_origin(
                                ctx,
                                &key,
                                &validated.spec,
                                sensing::DownstreamId::Peer(from_node),
                                now,
                            );
                            return;
                        }
                        // A registration can't kill the last
                        // downstream, but honor the action shape
                        // exhaustively anyway.
                        if action == sensing::UpstreamAction::Deregister {
                            Self::send_sensing_deregister_upstream(ctx, &key);
                            return;
                        }
                        // SI-4a warm-start (§4.4), disciplined by
                        // the SI-4 review (P1): ONLY a NEWLY
                        // CREATED downstream row is warm-started —
                        // a refresh resend must never restart a
                        // live delivery clock, clear pending work,
                        // or record itself as a live delivery
                        // (under D = ttl with ttl/2 refreshes that
                        // starved the downstream to permanent
                        // provisional Unknown). The send is ALWAYS
                        // provisional; the downstream's gate
                        // absorbs duplicates as StaleSeq.
                        let cached = {
                            let mut observations = ctx.sensing_observations.lock();
                            let slot_key = (key.clone(), sensing::DownstreamId::Peer(from_node));
                            if observations.slots.contains_key(&slot_key) {
                                None
                            } else {
                                let cached = observations.latest.get(&key).cloned();
                                if let Some(cached) = &cached {
                                    observations.slots.insert(
                                        slot_key,
                                        SensingDeliverySlot {
                                            last_status: Some(cached.status),
                                            last_delivered: Some((
                                                cached.origin_incarnation,
                                                cached.seq,
                                            )),
                                            next_due: now + validated.requested_sample_interval,
                                            pending: false,
                                        },
                                    );
                                }
                                cached
                            }
                        };
                        if let Some(cached) = cached {
                            if let Ok(bytes) = sensing::encode_attestation(&cached) {
                                spawn_sensing_frame_send(
                                    &ctx.socket,
                                    &ctx.peers,
                                    &ctx.addr_to_node,
                                    &ctx.router,
                                    &ctx.partition_filter,
                                    ctx.local_node_id,
                                    from_node,
                                    sensing::SENSING_PROVISIONAL_STREAM,
                                    sensing::SUBPROTOCOL_READINESS_ATTESTATION,
                                    bytes,
                                );
                            }
                        }
                        // SI-3 closure (item 2's principle at the
                        // damper seam): anti-entropy on EVERY
                        // admitted registration/refresh at the
                        // CURRENT aggregate, min-gap damped — the
                        // exact `register_sensing_interest` / leader-
                        // seam shape. The previous trailing-edge-only
                        // send lost a damper-suppressed transition
                        // forever (`register()` had already committed
                        // `last_advertised`, so later refreshes
                        // diffed to `None`) AND let upstream rows
                        // starve to ttl expiry in leaderless relay
                        // chains (§4.3 refreshes rows at ttl/2 —
                        // every hop must re-send, not just the
                        // first). The damper bounds the re-send rate;
                        // the receiving hop's register is an
                        // idempotent refresh.
                        let Some(strictest) =
                            ctx.sensing_interest_table.lock().aggregate(&key, now)
                        else {
                            return;
                        };
                        // SI-4 re-review item 5: the aggregate moved
                        // with this registration — re-anchor the
                        // hop's continuity window now, not at the
                        // next beat.
                        ctx.sensing_observations
                            .lock()
                            .update_upstream_interval(&key, Some(strictest));
                        if !sensing_upstream_damper_admits(
                            &ctx.sensing_upstream_damper,
                            validated.target,
                            *key.interest.interest_digest.as_bytes(),
                            sensing_effective_min_gap(ttl),
                        ) {
                            return;
                        }
                        let upstream = sensing::SensingInterestFrame::provider_registration(
                            &validated.spec,
                            validated.target,
                            strictest,
                            ttl,
                        );
                        if let Ok(bytes) = sensing::encode_interest_frame(&upstream) {
                            spawn_sensing_frame_send(
                                &ctx.socket,
                                &ctx.peers,
                                &ctx.addr_to_node,
                                &ctx.router,
                                &ctx.partition_filter,
                                ctx.local_node_id,
                                validated.target,
                                sensing::SUBPROTOCOL_SENSING_INTEREST as u64,
                                sensing::SUBPROTOCOL_SENSING_INTEREST,
                                bytes,
                            );
                        }
                    }
                    sensing::RegisterOutcome::OverCap => {
                        ctx.sensing_over_cap.fetch_add(1, Ordering::Relaxed);
                        tracing::debug!(
                            from_node = format!("{:#x}", from_node),
                            "sensing: registration refused over per-peer cap"
                        );
                    }
                    sensing::RegisterOutcome::RefusedByCachedFloor { minimum_supported } => {
                        tracing::debug!(
                            from_node = format!("{:#x}", from_node),
                            floor_ms = minimum_supported.as_millis() as u64,
                            "sensing: registration refused by cached provider floor"
                        );
                        // SI-3: when THIS node is the origin, it can
                        // author + sign the refusal response itself
                        // (one-shot, rides the attestation plane).
                        // A RELAY's cached-floor refusal stays local
                        // (§4.4 no-round-trip): a relay cannot sign
                        // an attestation for a foreign origin —
                        // re-sending the origin's cached refusal is
                        // SI-4's latest-per-key anti-entropy.
                        if validated.target == ctx.local_node_id {
                            ctx.sensing_counters
                                .cadence_refusals
                                .fetch_add(1, Ordering::Relaxed);
                            let generation = ctx.capability_version.load(Ordering::Relaxed);
                            let beat = {
                                let mut slot = ctx.sensing_emitter.lock();
                                slot.as_mut().map(|emitter| {
                                    emitter.refusal_beat(
                                        &validated.spec,
                                        sensing::CadenceRefusal { minimum_supported },
                                        generation,
                                    )
                                })
                            };
                            if let Some(beat) = beat {
                                Self::send_sensing_refusal_beat(ctx, beat, [from_node]);
                            }
                        }
                    }
                }
            }
            sensing::SensingInterestFrame::Deregister {
                interest_digest,
                target,
            } => {
                // Closure item 7: stamp snapshot BEFORE the table
                // mutation the retire decisions rest on.
                let emitter_stamp = ctx.sensing_emitter.lock().as_ref().map(|e| e.stamp());
                let actions = ctx.sensing_interest_table.lock().deregister(
                    interest_digest,
                    *target,
                    sensing::DownstreamId::Peer(from_node),
                    now,
                );
                for (key, action) in actions {
                    // Closure item 6: a dead branch reclaims its
                    // observations with the table.
                    if action == sensing::UpstreamAction::Deregister {
                        ctx.sensing_observations.lock().reclaim_branch(&key);
                    }
                    // SI-4 re-review item 5: a loosened aggregate
                    // re-anchors the surviving branch's continuity
                    // window immediately (the upstream RE-SEND is
                    // still refresh-repaired — no spec cache here).
                    if let sensing::UpstreamAction::Register { strictest } = action {
                        ctx.sensing_observations
                            .lock()
                            .update_upstream_interval(&key, Some(strictest));
                    }
                    if key.provider == ctx.local_node_id {
                        // SI-3: this node is the origin — the last
                        // downstream's death retires the emission
                        // stream (zero idle emission, plan §4.7),
                        // unless a registration raced in after the
                        // snapshot.
                        if action == sensing::UpstreamAction::Deregister {
                            if let (Some(emitter), Some(stamp)) =
                                (ctx.sensing_emitter.lock().as_mut(), emitter_stamp)
                            {
                                emitter.retire_if_stale(&key.interest.interest_digest, stamp);
                            }
                        }
                        continue;
                    }
                    if action == sensing::UpstreamAction::Deregister {
                        Self::send_sensing_deregister_upstream(ctx, &key);
                    }
                    // Register (loosened aggregate): the upstream
                    // re-send stays skipped in SI-2a — see the
                    // method docs.
                }
            }
        }
    }

    /// SI-3: a `ProviderRegistration` targeting THIS node admitted
    /// (or refreshed) a downstream row — feed the origin emitter at
    /// the row's post-registration strictest aggregate. With no
    /// emitter installed (plane off or no persisted incarnation)
    /// the row stands but the stream stays dark — the fail-closed
    /// §4.6 rule (see the `sensing_incarnation` knob docs).
    ///
    /// At live-stream capacity (second closure round, item 5) the
    /// registering `downstream`'s row is ROLLED BACK instead of
    /// left dark — a standing row would tell the downstream its
    /// registration succeeded. The removal is silent by design:
    /// no §4.4 wire semantics exist for capacity and no seq slot
    /// is minted to invent one; the downstream's next ttl/2
    /// refresh retries after capacity frees.
    ///
    /// Lock discipline: table read first, dropped, then the emitter
    /// — never nested (see the `sensing_emitter` field docs).
    fn feed_sensing_origin(
        ctx: &DispatchCtx,
        key: &sensing::ProviderInterestKey,
        spec: &sensing::InterestSpec,
        downstream: sensing::DownstreamId,
        now: Instant,
    ) {
        let Some(strictest) = ctx.sensing_interest_table.lock().aggregate(key, now) else {
            return;
        };
        let outcome = {
            let mut slot = ctx.sensing_emitter.lock();
            let Some(emitter) = slot.as_mut() else {
                return;
            };
            // Closure item 7: the stamp snapshot must precede the
            // table mutation the retire decision rests on.
            emitter
                .register(spec, strictest, now)
                .map_err(|refusal| (refusal, emitter.stamp()))
        };
        let (refusal, stamp) = match outcome {
            Ok(()) => {
                ctx.sensing_emitter_notify.notify_one();
                return;
            }
            Err((sensing::StreamRefusal::AtCapacity, _)) => {
                let _ = ctx.sensing_interest_table.lock().deregister(
                    &key.interest.interest_digest,
                    Some(key.provider),
                    downstream,
                    now,
                );
                tracing::debug!(
                    digest = ?key.interest.interest_digest,
                    "sensing: origin at live-stream capacity, registration rolled back"
                );
                return;
            }
            Err((sensing::StreamRefusal::Cadence(refusal), stamp)) => (refusal, stamp),
        };
        // §4.4 origin-hop refusal: partition this hop's downstreams
        // on M, answer every refused peer with the one-shot signed
        // refusal beat, and keep the surviving aggregate streaming.
        ctx.sensing_counters
            .cadence_refusals
            .fetch_add(1, Ordering::Relaxed);
        let partition =
            ctx.sensing_interest_table
                .lock()
                .on_refusal(key, refusal.minimum_supported, now);
        let generation = ctx.capability_version.load(Ordering::Relaxed);
        let beat = {
            let mut slot = ctx.sensing_emitter.lock();
            let Some(emitter) = slot.as_mut() else {
                return;
            };
            let beat = emitter.refusal_beat(spec, refusal, generation);
            match partition.upstream {
                // Survivors' aggregate is ≥ M ≥ floor by
                // construction, so a cadence refusal is impossible
                // here; a capacity refusal leaves the stream dark
                // until the survivors' next refresh retries.
                sensing::UpstreamAction::Register { strictest } => {
                    let _ = emitter.register(spec, strictest, now);
                }
                sensing::UpstreamAction::Deregister => {
                    emitter.retire_if_stale(&key.interest.interest_digest, stamp);
                }
                sensing::UpstreamAction::None => {}
            }
            beat
        };
        ctx.sensing_emitter_notify.notify_one();
        #[cfg(feature = "redex")]
        let leader_refused = partition.refused.contains(&sensing::DownstreamId::Leader);
        let signed_refusal = Self::send_sensing_refusal_beat(ctx, beat, {
            partition.refused.into_iter().filter_map(|d| match d {
                sensing::DownstreamId::Peer(node) => Some(node),
                sensing::DownstreamId::Local | sensing::DownstreamId::Leader => None,
            })
        });
        // SI-4 re-review item 4: a refused Leader row at the LOCAL
        // origin (leader-as-provider) partitions the leader relay's
        // real consumer rows with the same locally signed refusal —
        // survivors re-register through the ordinary feed path
        // (their aggregate is ≥ M ≥ the floor, so no re-refusal
        // recursion is possible).
        #[cfg(feature = "redex")]
        if leader_refused {
            if let Some(bytes) = signed_refusal {
                Self::apply_sensing_leader_refusal(
                    ctx,
                    key,
                    refusal.minimum_supported,
                    &bytes,
                    now,
                );
            }
        }
        #[cfg(not(feature = "redex"))]
        let _ = signed_refusal;
    }

    /// SI-3c: the 0x0C03 verified intake (plan §4.2/§4.6) — the
    /// admission seam SI-4's relay machinery builds its per-provider
    /// caches on. Pipeline, fail-closed at every step:
    ///
    /// 1. **Strict decode** (4 KiB cap, no trailing bytes) —
    ///    failures are protocol-invalid input.
    /// 2. **Solicited check**: the attestation must answer a branch
    ///    this hop holds LIVE rows for — unsolicited streams are
    ///    never verified or cached (cache-poisoning surface, and it
    ///    keeps the observation store bounded by the table).
    /// 3. **Authorship**: signature over the §4.2 transcript against
    ///    the origin's TOFU-pinned entity. v1 seam bound: the origin
    ///    must be pinned at THIS hop (adjacent, or previously
    ///    announced); an unpinned origin drops — relays that hold
    ///    subscriptions always pinned their upstream hop, and the
    ///    full multi-hop verification story rides SI-4's forwarding
    ///    (identical signed bytes, §4.2).
    /// 4. **Tagged-field validation** (second closure round,
    ///    item 1): a refusal's floor M (`promised_cadence` under
    ///    the reason tag) is bounded like every wire interval
    ///    BEFORE the gate — a signed-but-malformed refusal must
    ///    not consume sequence admission or move provider state on
    ///    its way to being dropped.
    /// 5. **Ordering** (§4.6): strictly-newer admission per
    ///    `(origin, incarnation, interest)` on the
    ///    [`sensing::IncarnationSeqGate`] — SI-1c's gate getting its
    ///    first live consumer. The fingerprint is the transcript
    ///    digest, so equivocation detection keys on exactly what the
    ///    origin signed; an equivocation poisons the incarnation AND
    ///    counts as protocol-invalid (security-relevant).
    /// 6. **Epoch transition** (closure items 3 + round-2 item 4):
    ///    MONOTONIC per-origin (incarnation, generation) —
    ///    advancing invalidates cached floors; a stale epoch
    ///    neither regresses nor invalidates.
    /// 7. **Refusal reaction** (§4.4): an admitted
    ///    `SamplingIntervalUnsupported` beat partitions this hop's
    ///    downstreams on M, forwards the origin's SIGNED refusal
    ///    bytes verbatim to each partitioned-out peer, and honors a
    ///    branch death upstream. The surviving-aggregate upstream
    ///    re-registration is skipped exactly like the sweep's
    ///    loosened-aggregate case (no spec cache at this hop) — the
    ///    next downstream refresh repairs it.
    /// 8. **Store**: latest admitted attestation per branch;
    ///    refusals in their own control-response map.
    fn handle_sensing_attestation_frame(
        payload: &[u8],
        from_node: u64,
        provisional: bool,
        ctx: &DispatchCtx,
    ) {
        let Ok(attestation) = sensing::decode_attestation(payload) else {
            ctx.sensing_counters
                .protocol_invalid
                .fetch_add(1, Ordering::Relaxed);
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                len = payload.len(),
                "sensing: undecodable 0x0C03 payload dropped"
            );
            return;
        };
        let interest = sensing::CapabilityInterestKey {
            capability_id: attestation.capability_id.clone(),
            interest_digest: attestation.interest_digest,
        };
        let branch = sensing::ProviderInterestKey::new(interest, attestation.origin);
        let now = Instant::now();
        // SI-4 review P0: a PROVIDER-FREE registration solicits
        // proofs from any provider the leader resolved — the
        // digest-level expectation admits what no provider-keyed
        // row can. The audience it retains is checked against the
        // VERIFIED signer below (re-review item 8).
        let watch_candidate: Option<(Duration, sensing::AudienceScopeCommitment)> = {
            let interests = ctx.sensing_capability_interests.lock();
            interests.get(&branch.interest).and_then(|expectation| {
                (expectation.expires_at > now)
                    .then_some((expectation.requested_sample_interval, expectation.audience))
            })
        };
        let has_rows = !ctx
            .sensing_interest_table
            .lock()
            .downstreams(&branch, now)
            .is_empty();
        if watch_candidate.is_none() && !has_rows {
            tracing::trace!(
                origin = format!("{:#x}", attestation.origin),
                "sensing: unsolicited attestation dropped"
            );
            return;
        }
        let Some(origin_entity) = ctx
            .peer_entity_ids
            .get(&attestation.origin)
            .map(|e| e.value().clone())
        else {
            tracing::debug!(
                origin = format!("{:#x}", attestation.origin),
                "sensing: no pinned EntityId for attestation origin, drop"
            );
            return;
        };
        if let Err(error) = sensing::verify_attestation(&attestation, &origin_entity) {
            ctx.sensing_counters
                .protocol_invalid
                .fetch_add(1, Ordering::Relaxed);
            tracing::debug!(
                origin = format!("{:#x}", attestation.origin),
                error = %error,
                "sensing: attestation signature verification failed"
            );
            return;
        }
        // SI-4 re-review item 8: a digest expectation solicits ONLY
        // the audience it names — the VERIFIED origin's pinned
        // entity must derive the expectation's owner root (the v1
        // single-owner relation; the distinct-device fleet relation
        // stays outside sensing). A signer that merely knows the
        // digest loses the watch justification — an authorization
        // refusal, not protocol-invalid input — and stops here
        // unless a provider-keyed row solicits it independently.
        let digest_watch: Option<Duration> = match watch_candidate {
            Some((interval, audience)) => {
                if sensing::AudienceScopeCommitment::owner_root(&origin_entity) == audience {
                    Some(interval)
                } else {
                    ctx.sensing_counters
                        .scope_refusals
                        .fetch_add(1, Ordering::Relaxed);
                    tracing::debug!(
                        origin = format!("{:#x}", attestation.origin),
                        "sensing: signer does not derive the watch's owner root, \
                         watch justification refused"
                    );
                    None
                }
            }
            None => None,
        };
        if digest_watch.is_none() && !has_rows {
            return;
        }
        // Second closure round, item 1 (fail-closed ordering): every
        // TAGGED field is validated BEFORE the observer gate and the
        // epoch transition — a signed-but-malformed refusal must not
        // consume sequence admission or move provider state on its
        // way to being dropped. Under the refusal tag, the signed
        // promised_cadence means the floor M — bound it like every
        // other wire interval.
        let is_refusal =
            attestation.status_reason == sensing::StatusReason::SamplingIntervalUnsupported;
        if is_refusal
            && !sensing_interval_in_bounds(attestation.promised_cadence, ctx.sensing_interest_ttl)
        {
            ctx.sensing_counters
                .protocol_invalid
                .fetch_add(1, Ordering::Relaxed);
            tracing::debug!(
                origin = format!("{:#x}", attestation.origin),
                floor_ms = attestation.promised_cadence.as_millis() as u64,
                "sensing: refusal beat with out-of-bounds floor dropped"
            );
            return;
        }
        let fingerprint = sensing::Digest256::from_bytes(attestation.transcript_digest());
        let admission = ctx.sensing_observer_gate.lock().admit(
            attestation.origin,
            attestation.interest_digest,
            attestation.origin_incarnation,
            attestation.seq,
            fingerprint,
        );
        if admission == sensing::Admission::Equivocation {
            ctx.sensing_counters
                .protocol_invalid
                .fetch_add(1, Ordering::Relaxed);
            tracing::warn!(
                origin = format!("{:#x}", attestation.origin),
                incarnation = attestation.origin_incarnation.get(),
                seq = attestation.seq,
                "sensing: equivocating attestation — incarnation poisoned"
            );
            return;
        }
        if !admission.is_admitted() {
            ctx.sensing_counters
                .attestations_gated
                .fetch_add(1, Ordering::Relaxed);
            tracing::trace!(
                origin = format!("{:#x}", attestation.origin),
                admission = ?admission,
                "sensing: stale attestation dropped at observer gate"
            );
            return;
        }
        // Closure item 3, hardened by round 2 item 4: provider
        // epochs are MONOTONIC. The observer gate is per (origin,
        // digest) but the epoch record is per origin, so a delayed
        // old-incarnation beat on a FRESH digest passes its
        // digest-local gate — it must neither regress the
        // provider-wide epoch nor flush valid floors. Advance only
        // on a strictly newer epoch — lexicographic (incarnation,
        // generation), so incarnation dominates (generation
        // restarts under a new incarnation) — and invalidate
        // cached floors exactly then (§4.4/§4.8). A stale-epoch
        // beat DROPS at the standing gate below before any state
        // mutation (SI-5 review P0): its digest-local gate admitted
        // it, but the provider-wide epoch supersedes that
        // admission.
        let epoch = (
            attestation.origin_incarnation,
            attestation.capability_generation,
        );
        // SI-5 review P0: the provider-wide epoch comparison has
        // THREE explicit outcomes — advance (disrupt siblings, then
        // process the arriving branch), equal (process normally),
        // and STALE (drop before any state mutation). The old
        // advance/no-op shape let a globally stale beat fall through
        // to normal intake: the observer gate is per (origin,
        // digest), so a delayed old-incarnation (or old-generation)
        // beat on a SIBLING digest still admitted, and a
        // continuity-bearing one re-Established the branch the
        // supersession had just force-expired — a valid-but-obsolete
        // signed Ready restoring optimism the provider's newer boot
        // or capability definition globally invalidated.
        enum EpochStanding {
            Fresh,
            Advanced((sensing::Incarnation, u64)),
            Stale,
        }
        let standing = {
            let mut observations = ctx.sensing_observations.lock();
            match observations
                .provider_epochs
                .get(&attestation.origin)
                .copied()
            {
                None => {
                    // First sight of this origin — nothing was
                    // cached under an older epoch, no invalidation.
                    observations
                        .provider_epochs
                        .insert(attestation.origin, epoch);
                    EpochStanding::Fresh
                }
                Some(current) if epoch > current => {
                    observations
                        .provider_epochs
                        .insert(attestation.origin, epoch);
                    EpochStanding::Advanced(current)
                }
                Some(current) if epoch == current => EpochStanding::Fresh,
                Some(_) => EpochStanding::Stale,
            }
        };
        if matches!(standing, EpochStanding::Stale) {
            // Not protocol-invalid (a delayed valid packet) and not
            // a refusal — just obsolete: nothing under a superseded
            // epoch may touch latest, cells, forwarding, or the
            // overlay.
            ctx.sensing_counters
                .attestations_superseded
                .fetch_add(1, Ordering::Relaxed);
            tracing::trace!(
                origin = format!("{:#x}", attestation.origin),
                incarnation = attestation.origin_incarnation.get(),
                generation = attestation.capability_generation,
                "sensing: globally stale epoch dropped"
            );
            return;
        }
        if let EpochStanding::Advanced(previous) = standing {
            ctx.sensing_interest_table
                .lock()
                .invalidate_provider_floors(attestation.origin);
            // SI-4 re-review (the second-relay lesson, undeclared
            // adjacent defect found while carrying item 4 over):
            // the leader relay caches floors in its OWN table — a
            // provider epoch advance must invalidate them there
            // too, or the leader keeps refusing sub-M consumers
            // against a floor the restarted provider no longer
            // asserts.
            #[cfg(feature = "redex")]
            if let Some(leader) = ctx.sensing_leader.lock().as_mut() {
                leader
                    .relay
                    .table
                    .invalidate_provider_floors(attestation.origin);
            }
            // SI-5 (§4.8 items 3+4): an epoch move supersedes EVERY
            // observation this hop holds from the origin — a
            // cross-digest cell must not keep vouching under the old
            // boot (incarnation) or the old definition (generation)
            // until its own next beat happens to arrive. The
            // ARRIVING beat re-establishes/resets its own branch
            // through the ordinary cell semantics right below; the
            // interests and branches themselves survive (§4.8 —
            // they never bound the epoch).
            let reason = if attestation.origin_incarnation > previous.0 {
                sensing::DisruptReason::IncarnationSuperseded
            } else {
                sensing::DisruptReason::GenerationChanged
            };
            disrupt_sensing_provider(
                &ctx.sensing_interest_table,
                &ctx.sensing_observations,
                &ctx.sensing_overlay_changed,
                attestation.origin,
                reason,
            );
            #[cfg(feature = "redex")]
            if let Some(leader) = ctx.sensing_leader.lock().as_mut() {
                leader.relay.disrupt_provider(attestation.origin, reason);
            }
        }
        if is_refusal {
            // Closure item 6: a refusal is a cadence-request-
            // relative CONTROL response, never warm-start status —
            // it lands in the refusals map, apart from `latest`,
            // and BEFORE the partition so a fully-refused branch
            // keeps the tombstone documenting its outcome.
            {
                let mut observations = ctx.sensing_observations.lock();
                if observations.refusals.len() < MAX_SENSING_OBSERVATIONS
                    || observations.refusals.contains_key(&branch)
                {
                    observations
                        .refusals
                        .insert(branch.clone(), (attestation.clone(), now));
                } else {
                    tracing::debug!(
                        origin = format!("{:#x}", attestation.origin),
                        "sensing: refusal store at cap, new branch dropped"
                    );
                }
            }
            let partition = ctx.sensing_interest_table.lock().on_refusal(
                &branch,
                attestation.promised_cadence,
                now,
            );
            // SI-4 re-review item 4: a refused Leader row partitions
            // the leader relay's REAL per-consumer rows FIRST — the
            // exact signed refusal reaches every refused consumer,
            // and the surviving consumers re-register a fresh Leader
            // row at their aggregate, which supersedes the stale
            // branch-death consequence below.
            #[cfg(feature = "redex")]
            if partition.refused.contains(&sensing::DownstreamId::Leader) {
                Self::apply_sensing_leader_refusal(
                    ctx,
                    &branch,
                    attestation.promised_cadence,
                    payload,
                    now,
                );
            }
            for downstream in &partition.refused {
                let sensing::DownstreamId::Peer(node) = downstream else {
                    continue;
                };
                // Forward the origin's SIGNED bytes verbatim —
                // relays never author attestations (§4.2).
                spawn_sensing_frame_send(
                    &ctx.socket,
                    &ctx.peers,
                    &ctx.addr_to_node,
                    &ctx.router,
                    &ctx.partition_filter,
                    ctx.local_node_id,
                    *node,
                    sensing::SUBPROTOCOL_READINESS_ATTESTATION as u64,
                    sensing::SUBPROTOCOL_READINESS_ATTESTATION,
                    payload.to_vec(),
                );
            }
            if partition.upstream == sensing::UpstreamAction::Deregister {
                // Re-check liveness: the leader's surviving
                // consumers may have re-registered above — the
                // branch is then alive again and must not be torn
                // down under the pre-partition consequence.
                let still_dead = ctx
                    .sensing_interest_table
                    .lock()
                    .downstreams(&branch, now)
                    .is_empty();
                if still_dead {
                    if branch.provider != ctx.local_node_id {
                        Self::send_sensing_deregister_upstream(ctx, &branch);
                    }
                    // The partition emptied the branch — the
                    // warm-start status and epoch memory reclaim
                    // now; the refusal tombstone above ages out via
                    // the sweep.
                    ctx.sensing_observations.lock().reclaim_status(&branch);
                    return;
                }
            }
            // SI-4 re-review item 5: the partition (and any leader
            // re-registration above) moved the surviving aggregate —
            // re-anchor the hop's continuity window immediately.
            let aggregate = ctx.sensing_interest_table.lock().aggregate(&branch, now);
            ctx.sensing_observations
                .lock()
                .update_upstream_interval(&branch, aggregate);
            return;
        }
        // SI-4a: the frozen SI-0f relay semantics on real sessions.
        // Feed this hop's OWN continuity cell from the admitted beat
        // — the INCOMING envelope flag feeds the cell (a provisional
        // forward never establishes) — then derive the OUTGOING
        // bearing from our continuity (the §4.4 hop rule) and
        // schedule per-downstream forwards: status edges flush
        // immediately; unchanged beats travel at each downstream's
        // own D; forwards are the identical signed bytes.
        let beat = sensing::DeliveredBeat {
            attested_status: attestation.status,
            estimated_start: attestation.estimated_start,
            source_incarnation: attestation.origin_incarnation,
            capability_generation: attestation.capability_generation,
            seq: attestation.seq,
            promised_cadence: attestation.promised_cadence,
            continuity_bearing: !provisional,
        };
        let own_interval = ctx
            .sensing_interest_table
            .lock()
            .aggregate(&branch, now)
            .unwrap_or(attestation.promised_cadence);
        let continuity = {
            let mut observations = ctx.sensing_observations.lock();
            if observations.latest.len() >= MAX_SENSING_OBSERVATIONS
                && !observations.latest.contains_key(&branch)
            {
                tracing::debug!(
                    origin = format!("{:#x}", attestation.origin),
                    "sensing: observation store at cap, new branch dropped"
                );
                return;
            }
            observations
                .latest
                .insert(branch.clone(), attestation.clone());
            let factor = ctx.sensing_continuity_factor;
            let cell = observations
                .upstream
                .entry(branch.clone())
                .or_insert_with(|| sensing::ObservationCell::register(now, own_interval, factor));
            // SI-4 review P1: the aggregate D moves with downstream
            // churn — re-anchor the window on every beat, never
            // resetting continuity.
            cell.update_interval(own_interval);
            cell.on_admitted_beat(now, beat);
            cell.continuity()
        };
        // SI-4 review P1 (solicited/expiry race): the branch can
        // expire between the solicited check and the store — the
        // sweep would never see a branch-death event for the state
        // just inserted, permanently consuming cap. Recheck before
        // forwarding; if the branch vanished, reclaim and stop (an
        // expiry AFTER this recheck is caught by the normal sweep,
        // which now sees the state).
        let still_solicited = digest_watch.is_some_and(|_| {
            ctx.sensing_capability_interests
                .lock()
                .get(&branch.interest)
                .is_some_and(|expectation| expectation.expires_at > Instant::now())
        }) || !ctx
            .sensing_interest_table
            .lock()
            .downstreams(&branch, Instant::now())
            .is_empty();
        if !still_solicited {
            ctx.sensing_observations.lock().reclaim_branch(&branch);
            return;
        }
        ctx.sensing_interest_table
            .lock()
            .set_upstream_continuity(&branch, continuity);
        let bearing = continuity == sensing::Continuity::Established;
        Self::schedule_sensing_forwards(ctx, &branch, &attestation, payload, bearing, now);
        // SI-4 review P0: a provider-free digest watch consumes the
        // beat directly at the consumer's own D — no provider-keyed
        // row exists to schedule through.
        if let Some(interval) = digest_watch {
            let moved = ctx.sensing_observations.lock().feed_consumer_cell(
                &branch,
                &attestation,
                bearing,
                interval,
                ctx.sensing_continuity_factor,
                now,
            );
            if moved {
                ctx.sensing_overlay_changed.send_modify(|generation| {
                    *generation = generation.wrapping_add(1);
                });
            }
        }
    }

    /// SI-4a: per-downstream forwarding of one admitted beat (the
    /// frozen SI-0f `SensingRelay::on_attestation` scheduling on the
    /// mesh's own state). Status edges flush to every live PEER
    /// downstream immediately; unchanged beats go only to
    /// downstreams whose schedule is due; the rest mark `pending`
    /// for the sweep's poll. `Local` rows are the SI-4b consumer
    /// overlay's intake — skipped here.
    fn schedule_sensing_forwards(
        ctx: &DispatchCtx,
        branch: &sensing::ProviderInterestKey,
        attestation: &sensing::ReadinessAttestation,
        payload: &[u8],
        bearing: bool,
        now: Instant,
    ) {
        let rows: Vec<(sensing::DownstreamId, Duration)> = {
            let table = ctx.sensing_interest_table.lock();
            table
                .downstreams(branch, now)
                .into_iter()
                .filter_map(|downstream| {
                    table
                        .downstream_entry(branch, downstream)
                        .map(|row| (downstream, row.requested_sample_interval))
                })
                .collect()
        };
        let mut forwards: Vec<u64> = Vec::new();
        let mut overlay_moved = false;
        let mut feed_leader = false;
        {
            let mut observations = ctx.sensing_observations.lock();
            for (downstream, interval) in rows {
                let slot = observations
                    .slots
                    .entry((branch.clone(), downstream))
                    .or_insert(SensingDeliverySlot {
                        last_status: None,
                        last_delivered: None,
                        next_due: now,
                        pending: false,
                    });
                let edge = slot.last_status != Some(attestation.status);
                let due = now >= slot.next_due;
                if edge || due {
                    slot.last_status = Some(attestation.status);
                    slot.last_delivered = Some((attestation.origin_incarnation, attestation.seq));
                    slot.next_due = now + interval;
                    slot.pending = false;
                    match downstream {
                        sensing::DownstreamId::Peer(node) => forwards.push(node),
                        // SI-4b: the Local row IS this node's own
                        // consumer — its delivery point feeds the
                        // overlay cell with the hop's OUTGOING
                        // bearing (the same §4.4 rule any peer
                        // gets).
                        sensing::DownstreamId::Local => {
                            overlay_moved |= observations.feed_consumer_cell(
                                branch,
                                attestation,
                                bearing,
                                interval,
                                ctx.sensing_continuity_factor,
                                now,
                            );
                        }
                        // SI-4 review P0: the leader row's delivery
                        // point hands the beat to the leader relay,
                        // which fans it to the REAL consumer rows.
                        sensing::DownstreamId::Leader => feed_leader = true,
                    }
                } else {
                    slot.pending = true;
                }
            }
        }
        if overlay_moved {
            ctx.sensing_overlay_changed.send_modify(|generation| {
                *generation = generation.wrapping_add(1);
            });
        }
        #[cfg(feature = "redex")]
        if feed_leader {
            if let Ok(semantic) = sensing::semantic_attestation(&branch.interest, attestation) {
                let deliveries = {
                    let mut slot = ctx.sensing_leader.lock();
                    match slot.as_mut() {
                        Some(leader) => leader.on_attestation(now, &semantic, bearing),
                        None => Vec::new(),
                    }
                };
                dispatch_sensing_leader_deliveries(
                    &ctx.socket,
                    &ctx.peers,
                    &ctx.addr_to_node,
                    &ctx.router,
                    &ctx.partition_filter,
                    ctx.local_node_id,
                    &ctx.sensing_observations,
                    &ctx.sensing_overlay_changed,
                    ctx.sensing_continuity_factor,
                    deliveries,
                    now,
                );
            }
        }
        #[cfg(not(feature = "redex"))]
        let _ = feed_leader;
        let stream_id = if bearing {
            sensing::SUBPROTOCOL_READINESS_ATTESTATION as u64
        } else {
            sensing::SENSING_PROVISIONAL_STREAM
        };
        // SI-7: relay fan-out volume — the origin's SIGNED bytes go
        // out verbatim to each downstream (plan §4.2).
        if !forwards.is_empty() {
            ctx.sensing_counters
                .attestations_forwarded
                .fetch_add(forwards.len() as u64, Ordering::Relaxed);
        }
        for node in forwards {
            spawn_sensing_frame_send(
                &ctx.socket,
                &ctx.peers,
                &ctx.addr_to_node,
                &ctx.router,
                &ctx.partition_filter,
                ctx.local_node_id,
                node,
                stream_id,
                sensing::SUBPROTOCOL_READINESS_ATTESTATION,
                payload.to_vec(),
            );
        }
    }

    /// SI-3: sign one refusal beat and fan it to the given peers
    /// (0x0C03). Signing is ~13 µs (SI-1d) — fine inline on the
    /// dispatch path for a refusal, which is rare by construction.
    /// Returns the encoded SIGNED bytes so a co-located leader
    /// partition can forward the exact same refusal to its own
    /// consumer rows (SI-4 re-review item 4).
    fn send_sensing_refusal_beat(
        ctx: &DispatchCtx,
        beat: sensing::UnsignedAttestation,
        peers: impl IntoIterator<Item = u64>,
    ) -> Option<Vec<u8>> {
        let Ok(signed) = sensing::sign_attestation(&ctx.signing_identity, beat) else {
            return None;
        };
        let Ok(bytes) = sensing::encode_attestation(&signed) else {
            return None;
        };
        for node in peers {
            spawn_sensing_frame_send(
                &ctx.socket,
                &ctx.peers,
                &ctx.addr_to_node,
                &ctx.router,
                &ctx.partition_filter,
                ctx.local_node_id,
                node,
                sensing::SUBPROTOCOL_READINESS_ATTESTATION as u64,
                sensing::SUBPROTOCOL_READINESS_ATTESTATION,
                bytes.clone(),
            );
        }
        Some(bytes)
    }

    /// SI-6.1: a capability-fold change reached this hop — when the
    /// leader role is active, reconcile every affected interest
    /// against a FRESH candidate snapshot, honor the reported branch
    /// consequences (torn-down providers retire their mesh Leader
    /// rows + upstream demand; newly eligible ones open them), and
    /// bump the unified scheduler-input generation when anything
    /// scheduler-relevant moved.
    ///
    /// SI-6.1 closure (review): the per-capability gate is a
    /// LEADING-plus-TRAILING-edge coalescer
    /// ([`sensing_fold_gate_admit`]), never the registration damper.
    /// Every announcement scans ALL capability ids with live
    /// interests, so an unrelated announcement stamps this
    /// capability's gate — under a plain min-gap damper the REAL
    /// membership change arriving inside the window was silently
    /// rejected with nothing re-driving it before soft-state repair.
    /// Now: first change reconciles immediately; an in-window change
    /// schedules exactly one fresh-snapshot reconciliation at the
    /// window boundary (a spawned sleeper holding a `ctx` clone);
    /// further in-window changes coalesce into that boundary run.
    #[cfg(feature = "redex")]
    fn reconcile_sensing_leader_fold(ctx: &DispatchCtx, now: Instant) {
        let capability_ids: Vec<sensing::CapabilityId> = {
            let slot = ctx.sensing_leader.lock();
            match slot.as_ref() {
                Some(leader) => leader.interest_capability_ids(),
                None => return,
            }
        };
        let mut moved = false;
        for capability_id in capability_ids {
            let key_digest = *blake3::hash(capability_id.as_str().as_bytes()).as_bytes();
            match sensing_fold_gate_admit(
                &ctx.sensing_fold_coalescer,
                key_digest,
                SENSING_UPSTREAM_MIN_GAP,
            ) {
                SensingFoldGateDecision::RunNow => {
                    moved |= Self::reconcile_sensing_leader_fold_one(ctx, &capability_id, now);
                }
                SensingFoldGateDecision::Defer { remaining, token } => {
                    let ctx = ctx.clone();
                    tokio::spawn(async move {
                        tokio::time::sleep(remaining).await;
                        // Exactly one boundary run per window: reclaim
                        // with the token THIS window minted, so a
                        // fresh out-of-window subsumption OR a later
                        // window's own pending run (which a delayed
                        // wake could otherwise steal) leaves this
                        // sleeper with nothing to do.
                        if !sensing_fold_gate_reclaim(
                            &ctx.sensing_fold_coalescer,
                            &key_digest,
                            token,
                        ) {
                            return;
                        }
                        if Self::reconcile_sensing_leader_fold_one(
                            &ctx,
                            &capability_id,
                            Instant::now(),
                        ) {
                            ctx.sensing_overlay_changed.send_modify(|generation| {
                                *generation = generation.wrapping_add(1);
                            });
                        }
                    });
                }
                SensingFoldGateDecision::Coalesced => {}
            }
        }
        if moved {
            ctx.sensing_overlay_changed.send_modify(|generation| {
                *generation = generation.wrapping_add(1);
            });
        }
    }

    /// One capability's fresh snapshot + reconcile + branch
    /// consequences; returns whether anything scheduler-relevant
    /// moved. Runs on the dispatch path (leading edge) and on the
    /// boundary sleeper (trailing edge) — BOTH snapshot at their own
    /// run time, so a trailing run sees every in-window change it
    /// coalesced.
    #[cfg(feature = "redex")]
    fn reconcile_sensing_leader_fold_one(
        ctx: &DispatchCtx,
        capability_id: &sensing::CapabilityId,
        now: Instant,
    ) -> bool {
        let snapshot = sensing_candidate_snapshot_from_parts(
            &ctx.capability_fold,
            &ctx.proximity_graph,
            &ctx.router,
            &ctx.peers,
            &ctx.peer_entity_ids,
            ctx.local_node_id,
            ctx.sensing_local_entity_root,
            &ctx.sensing_local_root,
            capability_id,
        );
        let reconciliation = {
            let mut slot = ctx.sensing_leader.lock();
            match slot.as_mut() {
                Some(leader) => leader.reconcile_with_snapshot(capability_id, &snapshot, now),
                None => return false,
            }
        };
        let emitter_stamp = ctx.sensing_emitter.lock().as_ref().map(|e| e.stamp());
        for branch in reconciliation.torn_down {
            let mesh_actions = ctx.sensing_interest_table.lock().deregister(
                &branch.interest.interest_digest,
                Some(branch.provider),
                sensing::DownstreamId::Leader,
                now,
            );
            for (key, action) in mesh_actions {
                apply_sensing_removal_action(
                    &ctx.sensing_observations,
                    &ctx.sensing_emitter,
                    emitter_stamp,
                    &ctx.socket,
                    &ctx.peers,
                    &ctx.addr_to_node,
                    &ctx.router,
                    &ctx.partition_filter,
                    ctx.local_node_id,
                    &key,
                    action,
                );
            }
        }
        for (branch, spec) in reconciliation.added {
            let strictest = {
                let slot = ctx.sensing_leader.lock();
                slot.as_ref()
                    .and_then(|leader| leader.relay.table.aggregate(&branch, now))
            };
            let Some(strictest) = strictest else {
                continue;
            };
            let ttl = ctx.sensing_interest_ttl;
            let outcome = ctx.sensing_interest_table.lock().register(
                &branch,
                sensing::DownstreamId::Leader,
                strictest,
                ttl,
                ctx.sensing_local_root,
                now,
            );
            if !matches!(outcome, sensing::RegisterOutcome::Registered(_)) {
                continue;
            }
            ctx.sensing_observations
                .lock()
                .update_upstream_interval(&branch, Some(strictest));
            if branch.provider == ctx.local_node_id {
                Self::feed_sensing_origin(ctx, &branch, &spec, sensing::DownstreamId::Leader, now);
            } else {
                let upstream = sensing::SensingInterestFrame::provider_registration(
                    &spec,
                    branch.provider,
                    strictest,
                    ttl,
                );
                if let Ok(bytes) = sensing::encode_interest_frame(&upstream) {
                    spawn_sensing_frame_send(
                        &ctx.socket,
                        &ctx.peers,
                        &ctx.addr_to_node,
                        &ctx.router,
                        &ctx.partition_filter,
                        ctx.local_node_id,
                        branch.provider,
                        sensing::SUBPROTOCOL_SENSING_INTEREST as u64,
                        sensing::SUBPROTOCOL_SENSING_INTEREST,
                        bytes,
                    );
                }
            }
        }
        reconciliation.changed
    }

    /// Leader row was refused at floor M — partition the leader
    /// relay's REAL per-consumer rows, forward the provider's exact
    /// signed refusal bytes to each refused consumer, and
    /// re-register the surviving aggregate as a fresh Leader row
    /// (feeding the origin emitter when this node IS the provider,
    /// or authoring the upstream `ProviderRegistration` from the
    /// leader's cached spec otherwise). The re-registration bypasses
    /// the damper deliberately: a refusal usually lands inside the
    /// min-gap of the registration that provoked it, and a
    /// suppressed survivor transition would strand the surviving
    /// consumers until their next ttl/2 refresh (the SI-3 closure's
    /// damper-consumed-transition shape).
    #[cfg(feature = "redex")]
    fn apply_sensing_leader_refusal(
        ctx: &DispatchCtx,
        branch: &sensing::ProviderInterestKey,
        minimum_supported: Duration,
        signed_refusal: &[u8],
        now: Instant,
    ) {
        let partition = {
            let mut slot = ctx.sensing_leader.lock();
            match slot.as_mut() {
                Some(leader) => leader.on_refusal(branch, minimum_supported, now),
                None => return,
            }
        };
        for downstream in &partition.refused {
            let sensing::DownstreamId::Peer(node) = downstream else {
                continue;
            };
            // The origin's EXACT signed bytes — the leader never
            // authors refusals for a foreign origin (§4.2).
            spawn_sensing_frame_send(
                &ctx.socket,
                &ctx.peers,
                &ctx.addr_to_node,
                &ctx.router,
                &ctx.partition_filter,
                ctx.local_node_id,
                *node,
                sensing::SUBPROTOCOL_READINESS_ATTESTATION as u64,
                sensing::SUBPROTOCOL_READINESS_ATTESTATION,
                signed_refusal.to_vec(),
            );
        }
        let sensing::UpstreamAction::Register { strictest } = partition.upstream else {
            return;
        };
        let Some(spec) = partition.spec else {
            return;
        };
        // Survivors re-register the mesh Leader row at their
        // aggregate (strictest ≥ M by construction, so the cached
        // floor cannot re-refuse it). `register()`'s internal diff
        // commits the advertised transition — this caller then
        // actually sends, so sender-commits holds.
        let ttl = ctx.sensing_interest_ttl;
        let (outcome, mesh_aggregate) = {
            let mut table = ctx.sensing_interest_table.lock();
            let outcome = table.register(
                branch,
                sensing::DownstreamId::Leader,
                strictest,
                ttl,
                ctx.sensing_local_root,
                now,
            );
            (outcome, table.aggregate(branch, now))
        };
        if !matches!(outcome, sensing::RegisterOutcome::Registered(_)) {
            return;
        }
        if branch.provider == ctx.local_node_id {
            Self::feed_sensing_origin(ctx, branch, &spec, sensing::DownstreamId::Leader, now);
            return;
        }
        let Some(current) = mesh_aggregate else {
            return;
        };
        let upstream = sensing::SensingInterestFrame::provider_registration(
            &spec,
            branch.provider,
            current,
            ttl,
        );
        if let Ok(bytes) = sensing::encode_interest_frame(&upstream) {
            spawn_sensing_frame_send(
                &ctx.socket,
                &ctx.peers,
                &ctx.addr_to_node,
                &ctx.router,
                &ctx.partition_filter,
                ctx.local_node_id,
                branch.provider,
                sensing::SUBPROTOCOL_SENSING_INTEREST as u64,
                sensing::SUBPROTOCOL_SENSING_INTEREST,
                bytes,
            );
        }
    }

    /// SI-2a: propagate a branch death upstream — the last
    /// downstream row for `key` died at this hop, so `next_hop
    /// (provider)` must drop this node's row too (plan §4.3: "a
    /// relay drops the entry when its last downstream row dies").
    /// Bypasses the min-gap damper: a deregistration must never be
    /// coalesced away.
    fn send_sensing_deregister_upstream(ctx: &DispatchCtx, key: &sensing::ProviderInterestKey) {
        let frame = sensing::SensingInterestFrame::Deregister {
            interest_digest: key.interest.interest_digest,
            target: Some(key.provider),
        };
        if let Ok(bytes) = sensing::encode_interest_frame(&frame) {
            spawn_sensing_frame_send(
                &ctx.socket,
                &ctx.peers,
                &ctx.addr_to_node,
                &ctx.router,
                &ctx.partition_filter,
                ctx.local_node_id,
                key.provider,
                sensing::SUBPROTOCOL_SENSING_INTEREST as u64,
                sensing::SUBPROTOCOL_SENSING_INTEREST,
                bytes,
            );
        }
    }

    fn handle_capability_announcement(payload: &[u8], from_node: u64, ctx: &DispatchCtx) {
        let Some(mut ann) = CapabilityAnnouncement::from_bytes(payload) else {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                len = payload.len(),
                "capability: decode failed"
            );
            return;
        };

        // Direct peers may only announce their own caps. Forwarded
        // announcements (hop_count > 0) are relayed through a peer
        // that isn't the origin, so we skip the check in that path
        // and rely on signature verification plus the TOFU binding
        // to keep forgers out.
        if ann.hop_count == 0 && ann.node_id != from_node {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                ann_node = format!("{:#x}", ann.node_id),
                "capability: node_id mismatch (peer can only announce for itself)"
            );
            return;
        }

        // Origin self-check — if we're the origin, drop. A mesh
        // loop could bounce our own announcement back to us; no
        // reason to re-index or re-broadcast.
        if ann.node_id == ctx.local_node_id {
            return;
        }

        // Dedup on (origin, version, is_direct). The third axis is
        // `hop_count == 0` — without it, a forwarder that ships an
        // announcement claiming a victim's `(node_id, version)`
        // primes the cache and the victim's own direct ann arriving
        // later is silently dropped, leaving `peer_entity_ids` un-
        // populated for that peer and breaking subsequent
        // channel-auth (TOFU pin runs only on the direct path).
        // Diamond topologies are still protected: a forwarded ann
        // dedups against any later forwarded ann for the same key;
        // the direct path is a distinct key processed exactly once.
        // Insert happens AFTER validation so a malformed
        // announcement doesn't poison the cache.
        let is_direct = ann.hop_count == 0;
        let dedup_key = (ann.node_id, ann.version, is_direct);
        if ctx.seen_announcements.contains_key(&dedup_key) {
            return;
        }

        if ctx.require_signed_capabilities && ann.signature.is_none() {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                "capability: unsigned announcement rejected"
            );
            return;
        }

        // Verify the signature (when present) against the
        // announcement's self-claimed entity_id. Unsigned
        // announcements skip this branch; receivers that care about
        // authenticity set `require_signed_capabilities = true`.
        let signature_verified = if ann.signature.is_some() {
            if ann.verify().is_err() {
                tracing::trace!(
                    from_node = format!("{:#x}", from_node),
                    "capability: signature verification failed"
                );
                return;
            }
            true
        } else {
            false
        };

        // Bind `node_id` to `entity_id` cryptographically. The
        // signature covers `entity_id` but NOT `node_id` — without
        // this check a signed announcement could claim any
        // `node_id`, poisoning the capability index and route
        // learning for an unrelated peer. `EntityId::node_id()` is
        // a blake2s derivation over the public key, so a forger who
        // doesn't control the key can't produce matching bytes.
        if ann.entity_id.node_id() != ann.node_id {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                claimed_node = format!("{:#x}", ann.node_id),
                derived_node = format!("{:#x}", ann.entity_id.node_id()),
                "capability: node_id does not match entity_id derivation"
            );
            return;
        }

        // First-seen identity pin — TOFU. A peer that tries to
        // rebind its `entity_id` in a later announcement is
        // silently rejected. Two preconditions must hold before we
        // pin anything:
        //
        // 1. The announcement is **signature-verified**. An
        //    unsigned announcement's `entity_id` is attacker-
        //    controlled and would poison the binding; unauthenticated
        //    deployments skip the pin entirely, and channel-auth
        //    paths fall through to "missing entity" instead of
        //    trusting forged input.
        // 2. The announcement arrived **directly** from the origin
        //    (`hop_count == 0`). On that path `ann.node_id` was
        //    already checked to equal `from_node` above, so pinning
        //    `from_node → ann.entity_id` binds the session to the
        //    key that actually signed for it. A forwarded
        //    announcement (`hop_count > 0`) travels through an
        //    arbitrary middle peer; pinning `from_node → victim_id`
        //    in that path would let the forwarder pose as the
        //    origin for subsequent channel auth (`authorize_subscribe`
        //    keys on `peer_entity_ids.get(from_node)`). Forwarded
        //    caps still update the capability index + routing, but
        //    the entity binding is deferred to the eventual direct
        //    announcement.
        if signature_verified && ann.hop_count == 0 {
            if let Some(existing) = ctx.peer_entity_ids.get(&from_node) {
                if *existing.value() != ann.entity_id {
                    tracing::trace!(
                        from_node = format!("{:#x}", from_node),
                        "capability: entity_id rebind rejected (TOFU)"
                    );
                    return;
                }
            } else {
                ctx.peer_entity_ids.insert(from_node, ann.entity_id.clone());
                // Mirror the entity-id pin into the origin_hash
                // reverse index. First-write-wins: an existing
                // claimant keeps the slot; a different node_id
                // grinding the same u64 (2^32 adversarial work,
                // accidental 2^-32) is rejected. Post-
                // `WIRE_ORIGIN_HASH_64BIT` the wire header carries
                // the full `EntityId::origin_hash()` u64 so the
                // reverse-index key matches the application-layer
                // value verbatim — accidental collisions are
                // effectively impossible.
                let origin_hash = ann.entity_id.origin_hash();
                let _ = ctx
                    .origin_hash_to_node
                    .entry(origin_hash)
                    .or_insert(from_node);
            }
        }

        // Derive the peer's subnet *before* moving `ann` into the
        // index — the policy needs `ann.capabilities` and `index()`
        // consumes the announcement by value.
        //
        // Gated on `signature_verified && ann.hop_count == 0` for
        // the same reasons the TOFU pin above has that exact pair
        // of conditions:
        //
        // 1. Unsigned `ann.capabilities` is attacker-controlled, so
        //    a deployment running with
        //    `require_signed_capabilities = false` for discovery
        //    must not let unsigned input feed `peer_subnets` —
        //    that map is read by `subnet_visible` on the
        //    publish / subscribe paths, and a spoofed subnet would
        //    admit a peer to `SubnetLocal` channels it shouldn't
        //    see.
        // 2. On a forwarded announcement (`hop_count > 0`) the
        //    `from_node` in our hands is the relay peer, not the
        //    origin. Writing the origin's derived subnet under the
        //    relay's `node_id` would overwrite the relay's legitimate
        //    subnet binding — a crafted forwarded announcement could
        //    shift any legitimate peer into a different subnet just
        //    by being the last hop on its path. The real binding
        //    comes from the origin's own direct announcement.
        if signature_verified && ann.hop_count == 0 {
            if let Some(policy) = ctx.local_subnet_policy.as_ref() {
                let subnet = policy.assign(&ann.capabilities);
                ctx.peer_subnets.insert(from_node, subnet);
            }
        }

        // Cache BEFORE indexing (the index consumes `ann` by value,
        // but the dedup key is already captured above). Insert at
        // this point so a subsequent duplicate short-circuits at the
        // `contains_key` check without re-parsing + re-verifying.
        ctx.seen_announcements
            .insert(dedup_key, std::time::Instant::now());

        // Topology learning from multi-hop receipt. An announcement
        // arriving with `hop_count > 0` traveled through `from_node`
        // to reach us, so install a route to the origin with metric
        // `hop_count + 2`. The `+2` offset matches the pingwave
        // convention so direct routes (metric 1) always strictly
        // beat any announcement-installed route. Routes from
        // capability announcements compete with pingwave-installed
        // routes via the routing table's "better metric wins" rule.
        // Direct announcements (hop_count == 0) skip this — the
        // session itself is already the authority for that peer.
        if ann.hop_count > 0 {
            if let Some(entry) = ctx.peer_addrs.get(&from_node) {
                let sender_addr = *entry.value();
                let metric = u16::from(ann.hop_count) + 2;
                ctx.router
                    .routing_table()
                    .add_route_with_metric(ann.node_id, sender_addr, metric);
            }
        }

        // Multi-hop forwarding: if we haven't exhausted the hop
        // budget, increment `hop_count` and re-broadcast to every
        // directly-connected peer except the sender and the peer we
        // use to reach the origin (split horizon). Do this BEFORE
        // handing `ann` to the index (which consumes by value) so
        // the forwarder has the current view of `hop_count`.
        if ann.hop_count < MAX_CAPABILITY_HOPS - 1 {
            let mut forwarded = ann.clone();
            // Saturating bump matches every other hop-count
            // increment in the crate (`swarm.rs:122`, `route.rs:254`).
            // The `< MAX_CAPABILITY_HOPS - 1` guard above already
            // bounds this in practice, but a future refactor that
            // raises the cap or relaxes the check would otherwise
            // turn an attacker-controlled byte into a debug-panic /
            // release-wraparound.
            forwarded.hop_count = forwarded.hop_count.saturating_add(1);
            // `to_bytes` on a clone with the bumped counter —
            // signature remains valid because `signed_payload()`
            // zeros `hop_count` on verify.
            let fwd_bytes = forwarded.to_bytes();
            Self::forward_capability_announcement(fwd_bytes, ann.node_id, from_node, ctx);
        }

        // Strip substrate-reserved metadata keys from the local copy
        // now that the forward (if any) has already shipped the
        // signature-covered bytes verbatim. A peer must not be able
        // to steer the receiver's greedy admission / placement
        // decisions by stamping `intent`, `colocate-with`,
        // `priority`, `owner`, or any `tool::*` key on its own
        // announcement. Strip must run AFTER the forward block — the
        // signature transcript covers `metadata`, so stripping before
        // re-broadcast would invalidate the signature for any
        // downstream peer that re-verifies. Strip is also applied to
        // unsigned anns because their metadata is even more
        // attacker-controlled. The only consumer between the forward
        // block and here is `policy.assign(&ann.capabilities)` above,
        // which reads `caps.tags` only, not `caps.metadata`.
        ann.strip_reserved_metadata();

        // Strip unauthorized `heat:<hex>=...` tags before indexing.
        // A peer can only annotate heat for chains it *also* claims
        // to hold (i.e. advertises `causal:<hex>` for the same
        // origin). Otherwise an arbitrary peer could publish
        // `heat:<any_origin>=0.99` and poison gravity decisions on
        // every other node. Self-announcements (from this node)
        // skip the filter — we trust our own emit path. `ann` is
        // already `mut` at the outer binding (the inbound-metadata
        // reserved-key strip needed it), so no re-binding required.
        if from_node != ctx.local_node_id {
            Self::filter_unauthorized_heat_tags(&mut ann.capabilities);
        }
        let fold_ann = super::behavior::fold::capability_bridge::translate_announcement(&ann);
        let _ = ctx.capability_fold.apply(fold_ann);

        // SI-6 review P1 (unified scheduler-input generation): fold
        // membership is a scheduler-relevant plane — a changed
        // capability set can alter the resolved population and the
        // selected provider, so re-matchers wake here.
        if ctx.enable_sensing_coalescing {
            ctx.sensing_overlay_changed.send_modify(|generation| {
                *generation = generation.wrapping_add(1);
            });
            // SI-6.1: reconcile live leader demand with the changed
            // fold (damped inside).
            #[cfg(feature = "redex")]
            Self::reconcile_sensing_leader_fold(ctx, Instant::now());
        }

        // R-5: the peer's capability set just changed in the fold, so
        // any cached ack-ranges gate verdict for it is now stale.
        // Drop it so the next gate check re-resolves through the fold
        // instead of serving a `false` cached before this announcement
        // landed (the connect-time race) or a `true` from a capability
        // the peer just dropped (downgrade/re-handshake). Keyed on the
        // announcement origin — for a direct ann that is `from_node`,
        // for a forwarded one the origin whose caps we just folded.
        ctx.ack_ranges_peer_cache.remove(&ann.node_id);
    }

    /// Drop every `heat:<hex>=...` reserved tag from `caps` whose
    /// `<hex>` is not matched by an accompanying `causal:<hex>*`
    /// tag in the same set. This enforces "you can only annotate
    /// heat for chains you advertise as holding," closing the
    /// inbound-heat-tag forge surface.
    fn filter_unauthorized_heat_tags(
        caps: &mut crate::adapter::net::behavior::capability::CapabilitySet,
    ) {
        // Collect every hex this peer claims via causal: tags.
        let mut claimed: std::collections::HashSet<String> = std::collections::HashSet::new();
        for tag in &caps.tags {
            if let Tag::Reserved { prefix, body } = tag {
                if prefix == "causal:" {
                    // Hex is the prefix of body up to the first ':' / '['.
                    let hex_end = body
                        .bytes()
                        .position(|b| b == b':' || b == b'[')
                        .unwrap_or(body.len());
                    claimed.insert(body[..hex_end].to_string());
                }
            }
        }
        // Per-announce cap on `heat:blob:*` tags. Blob-heat is
        // intentionally not gated by a `causal:` claim (the blob
        // is content-addressed, so a forged hash just produces a
        // useless prefetch attempt). But the gravity migration
        // controller consumes the *rate* via
        // `should_migrate_blob_to`, so a peer spraying thousands
        // of `heat:blob:<random>=1.0` tags would force every
        // healthy node to attempt that many prefetches. The cap
        // bounds the amplification: at most
        // `MAX_BLOB_HEAT_TAGS_PER_ANNOUNCE` blob-heat tags
        // survive the filter per inbound announcement.
        let mut blob_heat_budget: usize = MAX_BLOB_HEAT_TAGS_PER_ANNOUNCE;
        caps.tags.retain(|tag| match tag {
            Tag::Reserved { prefix, body } if prefix == "heat:" => {
                // Blob-heat tags (body shape `blob:<hex64>=<rate>`)
                // ride a separate trust model: the blob is
                // content-addressed, so a forged claim just causes
                // a useless prefetch attempt at worst (no data
                // corruption, no traffic redirection). Allow up
                // to the per-announce cap; drop the overflow.
                if body.starts_with("blob:") {
                    if blob_heat_budget == 0 {
                        return false;
                    }
                    blob_heat_budget -= 1;
                    return true;
                }
                // Chain-heat shape: `<hex>=<rate>`. Hex is everything
                // before the first `=`; strip when the peer didn't
                // also claim the chain via `causal:<hex>`.
                let hex_end = body.bytes().position(|b| b == b'=').unwrap_or(body.len());
                claimed.contains(&body[..hex_end])
            }
            _ => true,
        });
    }

    /// Fan an already-serialized capability announcement out to every
    /// directly-connected peer, minus the sender and any split-
    /// horizon-excluded peer. Spawned onto the runtime so the
    /// synchronous dispatch handler isn't blocked on per-peer
    /// encryption and network send. Mirrors the pingwave forwarding
    /// loop at the top of `dispatch_packet` — same split-horizon
    /// rule, same best-effort send semantics.
    fn forward_capability_announcement(
        payload: Vec<u8>,
        origin_node_id: u64,
        sender_node_id: u64,
        ctx: &DispatchCtx,
    ) {
        let peers = ctx.peers.clone();
        let socket = ctx.socket.clone();
        let partition_filter = ctx.partition_filter.clone();
        let router = ctx.router.clone();

        tokio::spawn(async move {
            // Split-horizon: consult the routing table for the
            // origin's best next hop and skip that peer. Matches the
            // pingwave rule so capability forwarding + pingwave
            // forwarding contribute to the same DV loop-avoidance
            // invariant.
            let next_hop_addr = router.routing_table().lookup(origin_node_id);

            for entry in peers.iter() {
                let peer = entry.value();
                if peer.node_id == sender_node_id {
                    continue; // never send back to whoever gave it to us
                }
                if Some(peer.addr) == next_hop_addr {
                    continue; // split horizon: that's our path to the origin
                }
                if partition_filter.contains(&peer.addr) {
                    continue;
                }

                // Build + send a subprotocol packet through this
                // peer's session. Same path as `send_subprotocol`;
                // inlined because the dispatch handler has no `self`.
                let session = &peer.session;
                let stream_id = SUBPROTOCOL_CAPABILITY_ANN as u64;
                let pool = session.thread_local_pool();
                let mut builder = pool.get();
                let seq = {
                    let stream = session.get_or_create_stream(stream_id);
                    stream.next_tx_seq()
                };
                let events = vec![Bytes::copy_from_slice(&payload)];
                let packet = builder.build_subprotocol(
                    stream_id,
                    seq,
                    &events,
                    PacketFlags::NONE,
                    SUBPROTOCOL_CAPABILITY_ANN,
                );
                let _ = socket.send_to(&packet, peer.addr).await;
                drop(builder);
                session.touch();
            }
        });
    }

    /// Coordinator-side handler for a `PunchRequest` from peer A
    /// (who wants to punch to target B).
    ///
    /// Behavior (plan §3 coordinator steps 1–3):
    ///
    /// 1. Resolve B's reflex address. Preferred source is the
    ///    `reflex_addr` field on B's latest signed
    ///    `CapabilityAnnouncement` in the local index. Without a
    ///    cached reflex, coordination can't proceed — we drop the
    ///    request silently. A's side times out on
    ///    `connect_direct` and falls back to routed-handshake.
    /// 2. Pick `fire_at = now() + TraversalConfig::punch_fire_lead`
    ///    (default 500 ms) — short enough to be under any plausible
    ///    NAT keep-alive row timeout, long enough for both
    ///    endpoints to receive `PunchIntroduce` and arm their
    ///    timers.
    /// 3. Fan out `PunchIntroduce` to both A and B with the
    ///    respective counterpart's reflex and the shared
    ///    `fire_at`.
    ///
    /// Best-effort: A unreachable-from-us or B not-in-our-peer-
    /// table short-circuits. Neither is surfaced — the caller's
    /// `connect_direct` timeout is the recovery path.
    #[cfg(feature = "nat-traversal")]
    fn handle_punch_request(
        from_node: u64,
        req: super::traversal::rendezvous::PunchRequest,
        ctx: &DispatchCtx,
    ) {
        use super::traversal::rendezvous::{
            PunchIntroduce, PunchReject, RejectReason, RendezvousMsg,
        };

        // Resolve A's session up-front. We need A's observed wire
        // source address to validate the self-reported reflex, to send
        // A its `PunchIntroduce`, and to send A a typed `PunchReject`
        // on any refusal. If A isn't in our peer table we can't
        // coordinate — and can't reject either — so just drop.
        let Some((a_addr, a_session)) = ctx
            .peers
            .get(&from_node)
            .map(|e| (e.value().addr, e.value().session.clone()))
        else {
            return;
        };

        // Helper: send A a typed `PunchReject` so its `request_punch`
        // fails fast (Finding 5) instead of blocking until
        // `punch_deadline`. `target` echoes the request so A resolves
        // the matching waiter. Best-effort — a failed send just
        // degrades to the old timeout behavior. Borrows `a_session` /
        // `ctx.socket` and clones only when actually invoked, so the
        // common successful-mediation path (no reject fires) pays no
        // Arc refcount bumps. Its last call precedes A_session's move
        // into the introduce spawn below, so the borrow is released in
        // time (NLL).
        let reject_target = req.target;
        // Echo the request's correlation token so A's waiter can
        // tell this reject answers THIS request, not a superseded
        // concurrent one to the same target (cubic P2).
        let reject_punch_id = req.punch_id;
        let send_reject = |reason: RejectReason| {
            let session = a_session.clone();
            let socket = ctx.socket.clone();
            let body = RendezvousMsg::PunchReject(PunchReject {
                target: reject_target,
                punch_id: reject_punch_id,
                reason,
            })
            .encode();
            tokio::spawn(async move {
                let pool = session.thread_local_pool();
                let mut builder = pool.get();
                let seq = {
                    let stream = session
                        .get_or_create_stream(super::traversal::SUBPROTOCOL_RENDEZVOUS as u64);
                    stream.next_tx_seq()
                };
                let events = vec![body];
                let packet = builder.build_subprotocol(
                    super::traversal::SUBPROTOCOL_RENDEZVOUS as u64,
                    seq,
                    &events,
                    PacketFlags::NONE,
                    super::traversal::SUBPROTOCOL_RENDEZVOUS,
                );
                let _ = socket.send_to(&packet, a_addr).await;
            });
        };

        // Coordinator per-requester budget (Finding 5). Over budget →
        // fast typed rejection, no fan-out.
        if !ctx.rendezvous_budgets.charge_request(
            from_node,
            ctx.traversal_config.punch_budget_window,
            ctx.traversal_config.punch_requests_per_window,
        ) {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                "rendezvous: PunchRequest over per-requester budget; rejecting",
            );
            send_reject(RejectReason::RateLimited);
            return;
        }

        // 1. Resolve B's reflex address. A's self-reported reflex
        //    (carried on the request) is the fallback when the
        //    capability cache doesn't have one yet — matches plan
        //    decision 7's "prefer-cached, fall-back-to-announced."
        //    But we do NOT override A's reflex with the cached one
        //    if A also announces it: the cache may be stale after
        //    a NAT rebind, and A's self-report is the freshest
        //    observation from A's own perspective.
        let Some(b_reflex) =
            super::behavior::fold::reflex_addr_for(&ctx.capability_fold, req.target)
        else {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                target = format!("{:#x}", req.target),
                "rendezvous: no cached reflex for target; rejecting PunchRequest",
            );
            send_reject(RejectReason::UnknownTargetReflex);
            return;
        };

        // Anti-reflection guard. `self_reflex` is an unsigned,
        // attacker-controllable field on the request. Forwarding it
        // verbatim into B's `PunchIntroduce` would let a malicious A
        // name an arbitrary victim address — B (which accepts an
        // unsolicited introduce as the punch responder) would then
        // fire its keep-alive train at that victim, turning the
        // coordinator + B into a UDP reflector with A's identity
        // hidden. Bind the self-report to A's actual session source
        // IP: a genuine A is reachable at `a_addr`, so its real
        // reflex shares that IP — only the port can differ, under
        // symmetric NAT. A mismatched IP is a spoofed target; reject
        // (fast typed failure) and A's `connect_direct` falls back to
        // the relay.
        //
        // Assumption: A is a *direct* session peer of R, so `a_addr`
        // is A's own wire source. In the normal rendezvous topology A
        // reaches its chosen coordinator directly, so this holds. If R
        // ever reached A via a relay, `PeerInfo::addr` would be the
        // relay's address and this guard would compare A's self-report
        // against the relay IP and drop a legitimate request — but
        // that only costs the optimization (A falls back to the
        // relay), never correctness.
        if req.self_reflex.ip() != a_addr.ip() {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                claimed = %req.self_reflex,
                session_src = %a_addr,
                "rendezvous: PunchRequest self_reflex IP != session source; \
                 rejecting (anti-reflection)",
            );
            send_reject(RejectReason::ReflexMismatch);
            return;
        }

        // A's reflex comes from the request body. R trusts A's
        // self-report over the cached value for A-side, per the
        // note above; a mid-session rebind on A's gateway is
        // visible to A before it propagates into R's capability
        // cache via a re-announce. The IP is now pinned to A's
        // session source by the guard above, so only the port is
        // free to vary.
        let a_reflex = req.self_reflex;

        // 2. Compute the shared fire time.
        let fire_lead = ctx.traversal_config.punch_fire_lead;
        let fire_at_ms = match std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH) {
            Ok(d) => d
                .saturating_add(fire_lead)
                .as_millis()
                .min(u64::MAX as u128) as u64,
            Err(_) => {
                // System clock pre-1970 — can't compute a
                // meaningful fire_at. Drop rather than introduce
                // with a garbage time that endpoints would
                // interpret as "already past."
                return;
            }
        };

        // 3. Build introduce payloads. Each side learns the
        //    counterpart's reflex + the shared fire_at.
        let intro_to_a = RendezvousMsg::PunchIntroduce(PunchIntroduce {
            peer: req.target,
            peer_reflex: b_reflex,
            fire_at_ms,
        })
        .encode();
        let intro_to_b = RendezvousMsg::PunchIntroduce(PunchIntroduce {
            peer: from_node,
            peer_reflex: a_reflex,
            fire_at_ms,
        })
        .encode();

        // Look up B's session. If B isn't in our peer table we can't
        // introduce — reject with `NoSessionWithTarget` so A fails
        // fast. (A's session was resolved up-front, above.)
        let Some((b_addr, b_session)) = ctx
            .peers
            .get(&req.target)
            .map(|e| (e.value().addr, e.value().session.clone()))
        else {
            tracing::trace!(
                from_node = format!("{:#x}", from_node),
                target = format!("{:#x}", req.target),
                "rendezvous: target peer not directly connected; rejecting",
            );
            send_reject(RejectReason::NoSessionWithTarget);
            return;
        };

        if ctx.partition_filter.contains(&a_addr) || ctx.partition_filter.contains(&b_addr) {
            return;
        }

        let socket_a = ctx.socket.clone();
        let socket_b = ctx.socket.clone();
        tokio::spawn(async move {
            let pool = a_session.thread_local_pool();
            let mut builder = pool.get();
            let seq = {
                let stream =
                    a_session.get_or_create_stream(super::traversal::SUBPROTOCOL_RENDEZVOUS as u64);
                stream.next_tx_seq()
            };
            let events = vec![intro_to_a];
            let packet = builder.build_subprotocol(
                super::traversal::SUBPROTOCOL_RENDEZVOUS as u64,
                seq,
                &events,
                PacketFlags::NONE,
                super::traversal::SUBPROTOCOL_RENDEZVOUS,
            );
            let _ = socket_a.send_to(&packet, a_addr).await;
        });
        tokio::spawn(async move {
            let pool = b_session.thread_local_pool();
            let mut builder = pool.get();
            let seq = {
                let stream =
                    b_session.get_or_create_stream(super::traversal::SUBPROTOCOL_RENDEZVOUS as u64);
                stream.next_tx_seq()
            };
            let events = vec![intro_to_b];
            let packet = builder.build_subprotocol(
                super::traversal::SUBPROTOCOL_RENDEZVOUS as u64,
                seq,
                &events,
                PacketFlags::NONE,
                super::traversal::SUBPROTOCOL_RENDEZVOUS,
            );
            let _ = socket_b.send_to(&packet, b_addr).await;
        });
    }

    /// Gate an *unsolicited* `PunchIntroduce` (one with no local
    /// waiter — the responder role, or a forged direct introduce)
    /// before it drives a keep-alive train. Closes review Finding 4:
    /// without this, any authenticated session peer could ship us a
    /// forged introduce naming a victim's `ip:port` as `peer_reflex`,
    /// and we would fire our keep-alive train there — turning this
    /// node into a UDP reflector with the forger's identity hidden.
    ///
    /// Validation mirrors the coordinator-side anti-reflection guard
    /// in [`Self::handle_punch_request`]:
    ///
    /// - If we hold a *cached, signed* reflex for the claimed
    ///   counterpart (`intro.peer`, from its capability announcement),
    ///   the introduce's `peer_reflex` must share that IP. Only the
    ///   port may legitimately differ — a symmetric NAT rebinds the
    ///   port per-destination but never the public IP. A mismatched IP
    ///   is a spoofed target; drop.
    /// - If no reflex is cached yet (fresh counterpart, announcement
    ///   not yet folded — a legitimate race on a young mesh), we have
    ///   nothing to validate against. Admit only through a
    ///   conservative fixed-window per-source cap so a peer that names
    ///   a nonexistent counterpart (to force this branch) gets at most
    ///   a trickle. Stage 2 replaces this cap with the full rendezvous
    ///   responder budget + typed `RendezvousRejected`.
    ///
    /// Returns `Some(slot)` — a reserved global concurrent-train slot,
    /// held for the punch's lifetime — to proceed to
    /// [`Self::schedule_punch`]; `None` to drop silently (answering an
    /// attacker is pure information leak, and no requester is waiting
    /// on the responder path; the legitimate responder re-arrives on
    /// the next introduce once the counterpart's announcement folds
    /// in).
    ///
    /// Beyond the Stage 1 IP validation, this charges the Stage 2
    /// responder budgets (Finding 5): a per-source fixed-window cap on
    /// how many unsolicited trains one introducing peer can trigger,
    /// plus a global concurrent-train ceiling so a Sybil source set
    /// can't multiply the aggregate.
    #[cfg(feature = "nat-traversal")]
    fn unsolicited_introduce_permitted(
        intro: &super::traversal::rendezvous::PunchIntroduce,
        from_node: u64,
        ctx: &DispatchCtx,
    ) -> Option<TrainSlot> {
        // 1. Anti-reflection (Finding 4): if we hold a signed reflex
        //    for the claimed counterpart, the introduce's peer_reflex
        //    must share its IP (symmetric NAT may shift the port, never
        //    the public IP).
        if let Some(cached) =
            super::behavior::fold::reflex_addr_for(&ctx.capability_fold, intro.peer)
        {
            if intro.peer_reflex.ip() != cached.ip() {
                tracing::trace!(
                    from = from_node,
                    counterpart = intro.peer,
                    claimed = %intro.peer_reflex,
                    announced = %cached,
                    "rendezvous: unsolicited PunchIntroduce peer_reflex IP != \
                     announced reflex; dropping (anti-reflection, Finding 4)"
                );
                return None;
            }
        }

        // 2. Per-source responder budget (Finding 5). Applies to every
        //    unsolicited train — cached-match and uncached alike — so a
        //    peer can't flood introduces even at a legitimate target.
        let window = ctx.traversal_config.punch_budget_window;
        if !ctx.rendezvous_budgets.charge_train(
            from_node,
            window,
            ctx.traversal_config.punch_trains_per_window,
        ) {
            tracing::trace!(
                from = from_node,
                counterpart = intro.peer,
                "rendezvous: unsolicited PunchIntroduce over per-source train \
                 budget; dropping"
            );
            return None;
        }

        // 3. Global concurrent-train ceiling (Finding 5). The slot is
        //    released when the punch scheduler's observer task ends.
        match ctx
            .rendezvous_budgets
            .try_train_slot(ctx.traversal_config.punch_trains_concurrent_max)
        {
            Some(slot) => Some(slot),
            None => {
                tracing::trace!(
                    from = from_node,
                    counterpart = intro.peer,
                    "rendezvous: unsolicited PunchIntroduce over global concurrent-train \
                     ceiling; dropping"
                );
                None
            }
        }
    }

    /// Endpoint-side: schedule the keep-alive train + observer
    /// after receiving a `PunchIntroduce`. Plan §3 endpoint
    /// behavior, end-to-end:
    ///
    /// 1. At `fire_at`, `fire_at + 100ms`, `fire_at + 250ms`
    ///    send a keep-alive packet to `intro.peer_reflex`. Raw
    ///    UDP, no encryption — the peer has no session with us
    ///    yet. The purpose is to open our side's NAT
    ///    connection-tracking row, so the peer's keep-alive
    ///    (fired in the same window on their side) can arrive.
    /// 2. Install an observer on `punch_observers[peer_reflex]`.
    ///    The receive loop's pre-session keep-alive recognition
    ///    fires it on first matching inbound.
    /// 3. Wait up to `punch_deadline` for the observer. On
    ///    success, emit a `PunchAck` via the coordinator; on
    ///    timeout, drop silently — the counterpart's
    ///    `await_punch_ack` times out too, and `connect_direct`
    ///    records the fallback.
    ///
    /// Best-effort throughout: a failed send at any step is
    /// logged-and-skipped. Rendezvous is an optimization (plan
    /// framing); routed-handshake is always the safety net.
    ///
    /// `train_slot` is the responder budget's global concurrent-train
    /// reservation (`Some` for an unsolicited train, `None` for an
    /// initiator's own train, which isn't budget-gated). It is moved
    /// into the observer task so the slot stays counted until the
    /// punch resolves or times out, then released on drop.
    #[cfg(feature = "nat-traversal")]
    fn schedule_punch(
        coordinator_node_id: u64,
        intro: super::traversal::rendezvous::PunchIntroduce,
        ctx: &DispatchCtx,
        train_slot: Option<TrainSlot>,
    ) {
        use super::traversal::rendezvous::{encode_keepalive, Keepalive, PunchAck, RendezvousMsg};

        let Some((coord_addr, coord_session)) = ctx
            .peers
            .get(&coordinator_node_id)
            .map(|e| (e.value().addr, e.value().session.clone()))
        else {
            return;
        };
        if ctx.partition_filter.contains(&coord_addr) {
            return;
        }
        if ctx.partition_filter.contains(&intro.peer_reflex) {
            return;
        }

        // Install the observer, tagged with the counterpart's
        // `node_id` so the receive loop can validate a keep-alive's
        // `sender_node_id` before firing this oneshot. A prior
        // pending entry at the same addr (unusual — would mean two
        // simultaneous punches to the same peer_reflex) is replaced;
        // the earlier scheduler task sees a `SendError` on its
        // oneshot.
        let (obs_tx, obs_rx) = oneshot::channel();
        ctx.punch_observers
            .insert(intro.peer_reflex, (intro.peer, obs_tx));

        // Compute keep-alive send delays. `fire_at_ms` is a Unix
        // epoch millisecond value synthesized by R; the lead is
        // `fire_at - now`, clamped to `punch_deadline`. See
        // [`keepalive_send_offsets`] for the negative-lead and
        // unbounded-future handling.
        let now_ms = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_millis() as u64)
            .unwrap_or(0);
        let offsets = keepalive_send_offsets(
            intro.fire_at_ms,
            now_ms,
            ctx.traversal_config.punch_deadline,
        );

        let local_node_id = ctx.local_node_id;
        let peer_reflex = intro.peer_reflex;
        let peer = intro.peer;
        let socket_send = ctx.socket.clone();
        let socket_ack = ctx.socket.clone();
        let deadline = ctx.traversal_config.punch_deadline;
        let punch_observers = ctx.punch_observers.clone();

        // Keep-alive sender task: fires three packets at
        // absolute offsets from the spawn instant. Each
        // `offsets[i]` is the intended delay from `start`, not
        // from the previous iteration — `sleep_until(start + offset)`
        // keeps the schedule anchored so a slow `send_to` on
        // packet N doesn't push packet N+1 past its deadline.
        //
        // History: an earlier revision did `sleep(offset)` in
        // the loop, which cumulatively summed to 500 / 1100 /
        // 1850 ms instead of 500 / 600 / 750 ms at the default
        // fire_lead — the later packets missed the peer's punch
        // window entirely. cubic flagged this as P1.
        let keepalive_payload = encode_keepalive(&Keepalive {
            sender_node_id: local_node_id,
            punch_id: 0, // reserved; no generator wiring yet
        });
        tokio::spawn(async move {
            let start = tokio::time::Instant::now();
            for offset in offsets {
                tokio::time::sleep_until(start + offset).await;
                let _ = socket_send
                    .send_to(&keepalive_payload[..], peer_reflex)
                    .await;
            }
            // Sustain the train for the rest of the punch window. The
            // §3 burst above is only a 250 ms opener; a real cone NAT
            // often needs repeated keep-alives to latch, because the
            // two sides' conntrack mappings are rarely both established
            // at the same instant — scheduling skew, or an early packet
            // dropped at the peer's gateway before its own outbound
            // created the reverse mapping. Keep firing at the same
            // 250 ms cadence until `deadline`, when the observer gives
            // up anyway. Extra keep-alives once the punch latches are
            // harmless: the peer's observer is already consumed and
            // ignores them. (Loopback punches land on the opener, so
            // this only ever matters against genuine NAT.)
            let mut resend = tokio::time::interval(Duration::from_millis(250));
            resend.tick().await; // consume the immediate tick
            while start.elapsed() < deadline {
                resend.tick().await;
                let _ = socket_send
                    .send_to(&keepalive_payload[..], peer_reflex)
                    .await;
            }
        });

        // Observer task: waits for the receive loop to fire the
        // oneshot. On success emits the PunchAck; on timeout /
        // cancellation defers to `await_punch_observer_outcome`
        // for cleanup so the map-eviction race against a
        // replacement observer is handled in one place.
        tokio::spawn(async move {
            // Hold the concurrent-train slot (if any) for the whole
            // observer lifetime — it releases on drop when this task
            // ends, so `concurrent_trains` reflects trains that are
            // still plausibly live (≤ punch_deadline).
            let _train_slot = train_slot;
            // The receive loop only fires this observer for a
            // keep-alive whose `sender_node_id` matches `peer` (the
            // expected id was stored alongside the oneshot at insert
            // time), so a `true` here already means the counterpart's
            // keep-alive reached us. A wrong-sender packet is dropped
            // upstream *without* consuming the observer, so it can't
            // burn the attempt — a later valid keep-alive still fires.
            if !await_punch_observer_outcome(obs_rx, deadline, &punch_observers, peer_reflex).await
            {
                return;
            }
            // Observer fired — build + send the ack via the
            // coordinator session, same shape as the former
            // `send_punch_ack_via` helper.
            let ack_body = RendezvousMsg::PunchAck(PunchAck {
                from_peer: local_node_id,
                to_peer: peer,
                punch_id: 0,
            })
            .encode();
            let pool = coord_session.thread_local_pool();
            let mut builder = pool.get();
            let seq = {
                let stream = coord_session
                    .get_or_create_stream(super::traversal::SUBPROTOCOL_RENDEZVOUS as u64);
                stream.next_tx_seq()
            };
            let events = vec![ack_body];
            let packet = builder.build_subprotocol(
                super::traversal::SUBPROTOCOL_RENDEZVOUS as u64,
                seq,
                &events,
                PacketFlags::NONE,
                super::traversal::SUBPROTOCOL_RENDEZVOUS,
            );
            let _ = socket_ack.send_to(&packet, coord_addr).await;
        });
    }

    /// Coordinator-side: forward a `PunchAck` whose `to_peer`
    /// isn't us to the session with `to_peer`. Best-effort —
    /// if we don't have a session with `to_peer`, drop.
    ///
    /// Wire bytes are preserved intact: `from_peer` still names
    /// the original sender so the recipient can correlate
    /// against its `pending_punch_acks` map.
    #[cfg(feature = "nat-traversal")]
    fn forward_punch_ack(ack: super::traversal::rendezvous::PunchAck, ctx: &DispatchCtx) {
        use super::traversal::rendezvous::RendezvousMsg;

        let Some((dest_addr, dest_session)) = ctx
            .peers
            .get(&ack.to_peer)
            .map(|e| (e.value().addr, e.value().session.clone()))
        else {
            tracing::trace!(
                to_peer = format!("{:#x}", ack.to_peer),
                "rendezvous: no session with PunchAck.to_peer; dropping",
            );
            return;
        };
        if ctx.partition_filter.contains(&dest_addr) {
            return;
        }

        let body = RendezvousMsg::PunchAck(ack).encode();
        let socket = ctx.socket.clone();
        tokio::spawn(async move {
            let pool = dest_session.thread_local_pool();
            let mut builder = pool.get();
            let seq = {
                let stream = dest_session
                    .get_or_create_stream(super::traversal::SUBPROTOCOL_RENDEZVOUS as u64);
                stream.next_tx_seq()
            };
            let events = vec![body];
            let packet = builder.build_subprotocol(
                super::traversal::SUBPROTOCOL_RENDEZVOUS as u64,
                seq,
                &events,
                PacketFlags::NONE,
                super::traversal::SUBPROTOCOL_RENDEZVOUS,
            );
            let _ = socket.send_to(&packet, dest_addr).await;
        });
    }

    /// Decide whether a Subscribe from `from_node` on `channel` is allowed.
    ///
    /// Rules, in order:
    /// 1. Per-peer channel cap — rejects with `TooManyChannels`.
    /// 2. If a `channel_configs` registry is set and the channel isn't in
    ///    it, reject with `UnknownChannel`.
    /// 3. Channel [`Visibility`] must permit the subscriber's subnet
    ///    — reject cross-subnet subscribes with `Unauthorized`.
    /// 4. Channel auth — `publish_caps` / `subscribe_caps` /
    ///    `require_token` on `ChannelConfig` are honored via
    ///    `ChannelConfig::can_subscribe`. A presented token is
    ///    installed into the local `TokenCache` (after signature
    ///    verification) before the check runs.
    fn authorize_subscribe(
        channel: &ChannelName,
        from_node: u64,
        token_bytes: Option<&[u8]>,
        ctx: &DispatchCtx,
    ) -> (bool, Option<AckReason>) {
        // Rate-limit check runs first — a throttled peer short-
        // circuits without consuming any ed25519 work. The
        // failure counter increments only on actual auth-rule
        // rejections below (not on `TooManyChannels`, which is a
        // resource-limit failure, not an auth failure).
        if Self::is_auth_throttled(from_node, ctx) {
            return (false, Some(AckReason::RateLimited));
        }
        // Idempotent re-subscribe handling. Pre-fix a peer sitting
        // at the per-peer channel cap that retransmitted a Subscribe
        // for a channel it already held was rejected with
        // `TooManyChannels`, even though `SubscriberRoster` is
        // set-typed and `add` would be a no-op for the existing
        // pair. The rejection AckReason is filtered out of the
        // auth-failure budget so it didn't trip the throttle, but
        // the legitimate re-subscribe still failed at the wire
        // level.
        //
        // The fix SUPPRESSES THE CAP REJECTION ONLY when the pair
        // is already in the roster — it does NOT short-circuit the
        // visibility / registry / token / capability gates further
        // down. A re-emitted Subscribe with a now-revoked token,
        // tightened visibility, or removed channel must reject the
        // same way a fresh Subscribe would; otherwise the wire-
        // level acceptance silently outlives the auth state. The
        // periodic token-expiry sweep (`evict_unauthorized_subscribers`)
        // does remove expired-token entries, but it doesn't catch
        // visibility tightening or the brief window before the
        // sweep fires, so we re-validate on every Subscribe.
        // The clone of `channel` is unavoidable for the O(1)
        // `DashSet<ChannelId>::contains` lookup; it's a small
        // String clone and runs ahead of the AEAD/ed25519 work
        // already on this path.
        let channel_id = ChannelId::new(channel.clone());
        let already_subscribed = ctx.roster.is_subscribed(from_node, &channel_id);
        if !already_subscribed
            && ctx.roster.channels_for_peer_count(from_node) >= ctx.max_channels_per_peer
        {
            return (false, Some(AckReason::TooManyChannels));
        }
        let Some(ref configs) = ctx.channel_configs else {
            // No registry → no ACL (test / permissive deployments).
            return (true, None);
        };
        let Some(cfg_ref) = configs.get_by_name(channel.as_str()) else {
            return (false, Some(AckReason::UnknownChannel));
        };
        // Clone the cfg so we can drop the DashMap guard before
        // any further work — the cfg fields are all cheap to clone
        // and doing so releases the registry's read lock early.
        let cfg = cfg_ref.clone();
        drop(cfg_ref);

        let peer_subnet = ctx
            .peer_subnets
            .get(&from_node)
            .map(|e| *e.value())
            .unwrap_or(SubnetId::GLOBAL);
        let visible = Self::subnet_visible(ctx.local_subnet, peer_subnet, cfg.visibility);
        if let Some(gw) = ctx.subnet_gateway.as_ref() {
            if visible {
                gw.record_forward();
            } else {
                gw.record_drop(Self::visibility_drop_reason(cfg.visibility));
            }
        }
        if !visible {
            return (false, Some(AckReason::Unauthorized));
        }

        // Parse the presented credential as a delegation chain. A
        // single directly-issued token is a one-link chain. Full
        // verification — root anchor, per-link signature/time/
        // revocation, link continuity, monotonic authority — runs
        // inside `cfg.can_subscribe` via `TokenChain::verify_authorizes`;
        // here we only parse. A malformed blob parses to `None` and is
        // treated as "no credential presented" (rejected by the gate).
        let presented_chain = token_bytes.and_then(|bytes| TokenChain::from_bytes(bytes).ok());

        // Whether any cap / token gate is in play. A fully open
        // channel (no filters, no require_token) short-circuits
        // without needing a peer entity_id at all.
        let has_auth_gates =
            cfg.publish_caps.is_some() || cfg.subscribe_caps.is_some() || cfg.token_required();
        if !has_auth_gates {
            return (true, None);
        }

        // Peer caps synthesized from the fold's tag set for
        // `from_node`. Subscribe-before-announce races resolve
        // to an empty CapabilitySet (the publisher has no fold
        // entries yet), which makes `subscribe_caps` filters
        // fail closed — matches the legacy
        // `capability_index.get(from_node).unwrap_or_default()`
        // shape.
        let peer_caps = super::behavior::fold::capability_bridge::synthesize_capability_set(
            &ctx.capability_fold,
            from_node,
        );

        // Revocation registry + clock skew for chain verification.
        // Pulled from the shared token cache when present; otherwise a
        // transient empty registry (nothing revoked) with strict skew.
        // The `transient_revocation` binding is declared here so it
        // outlives the borrow taken in the `None` arm.
        let transient_revocation;
        let (revocation, skew_secs): (&RevocationRegistry, u64) = match ctx.token_cache.as_ref() {
            Some(cache) => (cache.revocation().as_ref(), cache.clock_skew_secs()),
            None => {
                transient_revocation = RevocationRegistry::new();
                (&transient_revocation, 0)
            }
        };

        // Peer entity — load-bearing for `require_token`: the chain's
        // leaf subject must bind to this AEAD-verified handshake
        // identity. Missing entity + require_token = reject.
        let Some(peer_entity) = ctx
            .peer_entity_ids
            .get(&from_node)
            .map(|e| e.value().clone())
        else {
            if cfg.token_required() {
                return (false, Some(AckReason::Unauthorized));
            }
            // Cap-filter-only mode without a known entity — run the
            // cap match with a dummy id. The token gate is skipped
            // because the channel requires no token.
            let dummy = EntityId::from_bytes([0u8; 32]);
            return if cfg.can_subscribe(&peer_caps, &dummy, None, revocation, skew_secs) {
                (true, None)
            } else {
                (false, Some(AckReason::Unauthorized))
            };
        };

        if !cfg.can_subscribe(
            &peer_caps,
            &peer_entity,
            presented_chain.as_ref(),
            revocation,
            skew_secs,
        ) {
            return (false, Some(AckReason::Unauthorized));
        }

        // Authorized. Retain the verified chain keyed by
        // (node_id, channel_hash) so the periodic re-validation sweep
        // (`sweep_expired_subscribers`) can re-check expiry +
        // revocation later without the peer re-presenting. Only stored
        // for token-gated subscribes; cap-only channels have no chain.
        if let Some(chain) = presented_chain {
            // `verify_authorizes` above just verified the signatures, but
            // store the flag as unverified: cheap, and the first publish
            // re-check re-establishes it without trusting cross-path
            // state. (Marking it verified here would only save the one
            // first-publish verification.)
            ctx.subscriber_chains.insert(
                (from_node, cfg.channel_id.hash()),
                RetainedChain::new(chain),
            );
        }
        (true, None)
    }

    /// Check whether `from_node` is currently auth-throttled.
    /// Reads + clears the `throttled_until` instant atomically so
    /// an expired throttle state doesn't leak into future windows.
    fn is_auth_throttled(from_node: u64, ctx: &DispatchCtx) -> bool {
        if ctx.max_auth_failures_per_window == u16::MAX {
            return false; // threshold disabled
        }
        let Some(mut entry) = ctx.auth_failures.get_mut(&from_node) else {
            return false;
        };
        match entry.throttled_until {
            Some(until) if std::time::Instant::now() < until => true,
            Some(_) => {
                // Throttle elapsed — reset so the peer gets a
                // clean slate next time around.
                entry.throttled_until = None;
                entry.failures = 0;
                entry.window_start = None;
                false
            }
            None => false,
        }
    }

    /// Record an authorization-rule rejection against `from_node`.
    /// Increments the rolling-window counter; once it crosses
    /// `max_auth_failures_per_window`, marks the peer as throttled
    /// for `auth_throttle_duration`.
    fn record_auth_failure(from_node: u64, ctx: &DispatchCtx) {
        if ctx.max_auth_failures_per_window == u16::MAX {
            return;
        }
        let now = std::time::Instant::now();
        let mut entry = ctx.auth_failures.entry(from_node).or_default();
        // Window reset: if the current window has elapsed, start
        // fresh. Keeps failure counts from leaking across honest
        // retry storms separated by long idle periods.
        let reset_window = match entry.window_start {
            Some(start) => now.duration_since(start) >= ctx.auth_failure_window,
            None => true,
        };
        if reset_window {
            entry.window_start = Some(now);
            entry.failures = 0;
        }
        entry.failures = entry.failures.saturating_add(1);
        if entry.failures >= ctx.max_auth_failures_per_window {
            entry.throttled_until = Some(now + ctx.auth_throttle_duration);
        }
    }

    /// Wipe `from_node`'s failure counter. Called after a successful
    /// subscribe so honest peers that occasionally fail (stale
    /// token, renewal race) don't accumulate toward the throttle.
    fn clear_auth_failures(from_node: u64, ctx: &DispatchCtx) {
        ctx.auth_failures.remove(&from_node);
    }

    /// `true` if a packet with `visibility` originating in `source`
    /// should be delivered to a peer in `dest`.
    ///
    /// Mirrors the `SubnetGateway::should_forward` visibility matrix
    /// but doesn't need the gateway's state (`peer_subnets`,
    /// `export_table`). Regular participants use this for
    /// publish-fan-out filtering + subscribe-gate checks;
    /// border-gateway nodes with richer routing state should use the
    /// full `SubnetGateway` instead.
    ///
    /// `Exported` is conservative — returns `false` unless a
    /// per-channel export table is consulted elsewhere. Wiring that
    /// is a documented follow-up.
    /// Translate a [`Visibility`] verdict into the matching
    /// [`DropReason`] for gateway counter telemetry. Mirrors the
    /// matrix in [`Self::subnet_visible`] — `Global` never
    /// triggers a drop (caller short-circuits with
    /// `record_forward` instead), so this returns the dominant
    /// reason for the non-Global variants.
    fn visibility_drop_reason(visibility: Visibility) -> DropReason {
        match visibility {
            Visibility::Global => DropReason::SubnetLocal, // unreachable in practice
            Visibility::SubnetLocal => DropReason::SubnetLocal,
            Visibility::ParentVisible => DropReason::NotAncestor,
            Visibility::Exported => DropReason::NotExported,
        }
    }

    fn subnet_visible(source: SubnetId, dest: SubnetId, visibility: Visibility) -> bool {
        match visibility {
            Visibility::Global => true,
            Visibility::SubnetLocal => source.is_same_subnet(dest),
            Visibility::ParentVisible => {
                // "Visible to the parent subnet but not siblings" —
                // strictly upward. A child's broadcast reaches its
                // own subnet (covered by `is_ancestor_of` since a
                // subnet is its own ancestor) and any ancestor; a
                // parent broadcasting down to descendants would leak
                // region-scoped traffic and is rejected.
                dest.is_ancestor_of(source)
            }
            Visibility::Exported => false,
        }
    }

    /// Send an `Ack` on the membership subprotocol back to `to_node`.
    /// Non-fatal if `to_node` is not in the peer map or the send fails;
    /// the requester will simply hit its ack timeout.
    fn send_membership_ack(
        to_node: u64,
        nonce: u64,
        accepted: bool,
        reason: Option<AckReason>,
        ctx: &DispatchCtx,
    ) {
        let Some(peer_entry) = ctx.peers.get(&to_node) else {
            return;
        };
        let dest_addr = peer_entry.value().addr;
        if ctx.partition_filter.contains(&dest_addr) {
            return;
        }
        let dest_sess = peer_entry.value().session.clone();
        let socket = ctx.socket.clone();
        let ack = MembershipMsg::Ack {
            nonce,
            accepted,
            reason,
        };
        let bytes = Bytes::from(membership::encode(&ack));
        drop(peer_entry);

        tokio::spawn(async move {
            let pool = dest_sess.thread_local_pool();
            let mut builder = pool.get();
            let stream_id = SUBPROTOCOL_CHANNEL_MEMBERSHIP as u64;
            let seq = {
                let stream = dest_sess.get_or_create_stream(stream_id);
                stream.next_tx_seq()
            };
            let events = vec![bytes];
            let packet = builder.build_subprotocol(
                stream_id,
                seq,
                &events,
                PacketFlags::NONE,
                SUBPROTOCOL_CHANNEL_MEMBERSHIP,
            );
            let _ = socket.send_to(&packet, dest_addr).await;
        });
    }

    // ── Channel fan-out (ChannelPublisher) ─────────────────────────────

    /// Build a [`ChannelPublisher`] recipe. Does NOT talk to the wire —
    /// combine with [`publish`](Self::publish) or
    /// [`publish_many`](Self::publish_many) to actually fan out.
    pub fn channel_publisher(
        &self,
        channel: ChannelName,
        config: PublishConfig,
    ) -> ChannelPublisher {
        ChannelPublisher::new(channel, config)
    }

    /// Fan `payload` out to every subscriber of the publisher's channel.
    ///
    /// One per-peer unicast per subscriber — no multicast primitive, no
    /// group crypto. Per-peer concurrency is bounded by
    /// `PublishConfig::max_inflight`. The failure policy controls whether
    /// per-peer errors short-circuit the fan-out (see [`OnFailure`]).
    pub async fn publish(
        &self,
        publisher: &ChannelPublisher,
        payload: Bytes,
    ) -> Result<PublishReport, AdapterError> {
        self.publish_many(publisher, &[payload]).await
    }

    /// Fan multiple payloads out to every subscriber of the publisher's
    /// channel. Semantics are the same as [`publish`](Self::publish); the
    /// whole `events` slice is delivered as one batch per subscriber.
    pub async fn publish_many(
        &self,
        publisher: &ChannelPublisher,
        events: &[Bytes],
    ) -> Result<PublishReport, AdapterError> {
        // Publisher-side auth: if the channel is registered with
        // `publish_caps` / `require_token`, the local node must
        // satisfy them *before* fan-out begins. Keeps a node from
        // silently publishing to a channel whose own ACL it doesn't
        // match. Channels absent from the registry are treated as
        // open (permissive default).
        let cfg_snapshot = self.channel_configs.as_ref().and_then(|cr| {
            cr.get_by_name(publisher.channel().name().as_str())
                .map(|c| c.clone())
        });
        if let Some(cfg) = cfg_snapshot.as_ref() {
            if cfg.publish_caps.is_some() || cfg.token_required() {
                let self_caps = self
                    .local_announcement
                    .load()
                    .as_deref()
                    .map(|ann| ann.capabilities.clone())
                    .unwrap_or_default();
                let self_entity = self.identity.entity_id().clone();
                // Build the publish chain. Prefer an explicitly-held
                // (possibly delegated, multi-link) chain installed via
                // `set_publish_chain` — its issuer can be a delegator
                // rather than a channel root. Otherwise fall back to a
                // single directly-granted PUBLISH token from the
                // `TokenCache`.
                //
                // `get_for_action` (not `get`) selects a token that
                // actually carries PUBLISH on this channel: a slot can
                // hold a SUBSCRIBE token side-by-side with the PUBLISH
                // one, and a scope-agnostic `get` would intermittently
                // return the SUBSCRIBE token, failing the gate even
                // though a valid PUBLISH grant is cached.
                //
                // The transient empty registry keeps the borrow alive
                // when the node has no token cache configured — a held
                // chain still publishes in that mode (nothing revoked,
                // strict skew).
                let held = self
                    .published_chains
                    .get(&cfg.channel_id.hash())
                    .map(|c| c.value().clone());
                let transient_revocation;
                let (revocation, skew, chain) = match self.token_cache.as_ref() {
                    Some(cache) => {
                        let chain = held.or_else(|| {
                            cache
                                .get_for_action(
                                    &self_entity,
                                    TokenScope::PUBLISH,
                                    cfg.channel_id.hash(),
                                )
                                .map(TokenChain::single)
                        });
                        (cache.revocation().as_ref(), cache.clock_skew_secs(), chain)
                    }
                    None => {
                        transient_revocation = RevocationRegistry::new();
                        (&transient_revocation, 0u64, held)
                    }
                };
                if !cfg.can_publish(&self_caps, &self_entity, chain.as_ref(), revocation, skew) {
                    return Err(AdapterError::Connection(
                        "channel: publish denied by channel ACL".into(),
                    ));
                }
            }
        }

        // Snapshot subscribers at call time; late subscribers won't see
        // this publish, early-unsubscribes may still receive it — both
        // are documented non-goals.
        //
        // `dispatch_recipients` is the per-publish view: every
        // `Broadcast` subscriber plus one selected member of each
        // queue group on this channel. The `members()` API still
        // exists for set-membership queries; this path wants the
        // dispatch view because that's what enforces the
        // one-of-N delivery semantic for queue-group subscribers.
        //
        // Sharp edge: if a queue-group member is selected here and
        // then denied by the auth-guard / visibility filters
        // below, the publish is dropped for that group on this
        // call (no per-publish retry against a different group
        // member). In practice queue-group members share a
        // capability posture (same operator, same tokens), so the
        // failure case is rare; documented in
        // `docs/misc/NRPC_DESIGN.md` open-questions.
        let mut subscribers = self.roster.dispatch_recipients(publisher.channel());

        // Subnet visibility + AuthGuard filters folded into a single
        // `retain` pass per discovery-routing perf #105. Pre-fix the
        // publish hot path ran two sequential `retain` passes over
        // the same `Vec<u64>` — each walked the whole Vec and shifted
        // elements on a drop. Folded into one pass, each peer hits
        // its subnet + auth DashMap lookups with cache locality (no
        // round-trip through every peer twice), the Vec is walked
        // once not twice, and the closure short-circuits on the
        // first rejecting predicate.
        //
        // Visibility filter: look up the channel's configured
        // visibility; if the channel has no registry entry, fall
        // back to `config.default_visibility` (which itself defaults
        // to `Visibility::Global` for back-compat with simple
        // registry-less deployments). Fleet operators who want
        // fail-closed behavior set
        // `with_default_visibility(Visibility::SubnetLocal)` so
        // a forgotten registry entry confines messages to the
        // local subnet rather than leaking them mesh-wide.
        // Filtered subscribers don't show up in `attempted` or
        // `errors` — they're policy decisions, not failures.
        //
        // AuthGuard fast path. Populated by `authorize_subscribe`;
        // revoked on unsubscribe and by the expiry sweep. Consulted
        // on every publish so revocations take effect on the next
        // fan-out without waiting for a roster refresh.
        //
        // Three-way verdict:
        //
        // - `Allowed`: bloom hit + verified-cache entry says yes.
        //   The verified cache is keyed on the canonical
        //   [`ChannelHash`] (u64) — collision-resistant at realistic
        //   deployment scale (~65 K channels before birthday-collision
        //   threshold), but a sufficiently adversarial name selection
        //   could still alias two channels. The exact-name ACL is
        //   the unconditional backstop: cross-check the canonical
        //   name against `exact` before trusting the verdict, so a
        //   collision can only ever produce a brief miss, never a
        //   policy swap.
        // - `Denied`: bloom miss — no auth entry exists for this
        //   (origin, channel). Skip the subscriber.
        // - `Unknown`: bloom hit but verified cache missed. Fall
        //   back to the exact-channel ACL. On hit, promote back
        //   into the verified cache so subsequent publishes take
        //   the fast path.
        //
        // Open channels (no auth configured) are admitted on every
        // subscribe via `allow_channel`, so the fast path trivially
        // passes for them — no conditional branch needed.
        //
        // Additionally, when the channel is `require_token`, we do a
        // **lazy expiry check** on each admitted subscriber. The
        // periodic token sweep (`spawn_token_sweep_loop`) is the
        // primary eviction path, but a caller may deliberately
        // configure `token_sweep_interval = Duration::MAX` to opt out
        // — and without a second line of defence an expired token
        // would keep authorizing packets forever. Probing the token
        // cache per admitted subscriber costs one DashMap lookup +
        // a timestamp compare per publish, which is only paid on
        // token-gated channels (`require_token = false` skips the
        // branch entirely). An expired subscriber is revoked inline
        // so the next publish takes the `Denied` path.
        let visibility = cfg_snapshot
            .as_ref()
            .map(|c| c.visibility)
            .unwrap_or(self.config.default_visibility);
        let channel_name = publisher.channel().name().clone();
        let channel_hash = channel_name.hash();
        let auth_guard = self.auth_guard.clone();
        let require_token = cfg_snapshot
            .as_ref()
            .map(|c| c.token_required())
            .unwrap_or(false);
        subscribers.retain(|peer_id| {
            // (1) Subnet visibility. Cheap check first — a peer in
            // the wrong subnet should short-circuit before any
            // auth-cache probing.
            let peer_subnet = self
                .peer_subnets
                .get(peer_id)
                .map(|e| *e.value())
                .unwrap_or(SubnetId::GLOBAL);
            let visible = Self::subnet_visible(self.local_subnet, peer_subnet, visibility);
            if let Some(gw) = self.subnet_gateway.as_ref() {
                if visible {
                    gw.record_forward();
                } else {
                    gw.record_drop(Self::visibility_drop_reason(visibility));
                }
            }
            if !visible {
                return false;
            }
            // (2) Auth guard (bloom + verified cache).
            let origin = subscriber_origin_hash(*peer_id);
            let admitted = match auth_guard.check_fast(origin, channel_hash) {
                AuthVerdict::Allowed => auth_guard.is_authorized_full(origin, &channel_name),
                AuthVerdict::Denied => false,
                AuthVerdict::NeedsFullCheck => {
                    if auth_guard.is_authorized_full(origin, &channel_name) {
                        auth_guard.allow_channel(origin, &channel_name);
                        true
                    } else {
                        false
                    }
                }
            };
            if !admitted {
                return false;
            }
            if !require_token {
                return true;
            }
            // (3) Token-gated branch: re-verify the subscriber's
            // retained token chain against the current clock +
            // revocation floors. The chain was stored by
            // `authorize_subscribe` when the subscribe passed; a
            // missing chain, an expired link, a revoked root/link, or
            // a root no longer in `token_roots` all revoke inline so
            // the next publish takes the `Denied` path. Re-verifying
            // the chain (not a bare `cache.check`) keeps the publish
            // path anchored to the channel's root of trust, same as
            // the subscribe path and the periodic sweep.
            let entity = self.peer_entity_ids.get(peer_id).map(|e| e.value().clone());
            let chain_ok = match (entity, self.token_cache.as_ref(), cfg_snapshot.as_ref()) {
                (Some(entity), Some(cache), Some(cfg)) => self
                    .subscriber_chains
                    .get(&(*peer_id, channel_hash))
                    .is_some_and(|r| {
                        let revocation = cache.revocation().as_ref();
                        let skew = cache.clock_skew_secs();
                        // Skip the per-link ed25519 verifies once they've
                        // verified for this immutable chain — time bounds,
                        // revocation, anchoring, and scope are still
                        // re-checked every packet. Avoids N × up-to-8
                        // signature verifies per publish on a high-fanout
                        // channel.
                        if r.signatures_verified.load(Ordering::Relaxed) {
                            cfg.reverify_subscribe_presigned(&r.chain, &entity, revocation, skew)
                        } else if cfg.reverify_subscribe(&r.chain, &entity, revocation, skew) {
                            r.signatures_verified.store(true, Ordering::Relaxed);
                            true
                        } else {
                            false
                        }
                    }),
                // Missing entity binding, no cache, or no channel
                // config — treat as unauthorized. The subscribe path
                // would have rejected this peer in the first place;
                // reaching here means config drift we must not paper
                // over by admitting the publish. (A missing config also
                // means no roots, which the re-verify would reject
                // anyway.)
                _ => false,
            };
            if !chain_ok {
                auth_guard.revoke_channel(origin, &channel_name);
                return false;
            }
            true
        });

        let mut report = PublishReport {
            attempted: subscribers.len(),
            delivered: 0,
            errors: Vec::new(),
        };
        if subscribers.is_empty() {
            return Ok(report);
        }

        let reliable = publisher.config().reliability.is_reliable();
        let stream_id = Self::publish_stream_id(publisher.channel());
        let max_inflight = publisher.config().max_inflight;
        let on_failure = publisher.config().on_failure;

        use tokio::sync::Semaphore;
        let sem = Arc::new(Semaphore::new(max_inflight.max(1)));

        match on_failure {
            OnFailure::FailFast => {
                // Sequential; stop on first error. Concurrency isn't
                // meaningful here because we'd be discarding in-flight
                // results anyway.
                for peer_id in &subscribers {
                    match self
                        .publish_to_peer(*peer_id, channel_hash, stream_id, reliable, events)
                        .await
                    {
                        Ok(()) => report.delivered += 1,
                        Err(e) => {
                            report.errors.push((*peer_id, e));
                            return Ok(report);
                        }
                    }
                }
                Ok(report)
            }
            OnFailure::BestEffort | OnFailure::Collect => {
                let mut handles = Vec::with_capacity(subscribers.len());
                // Hoist the events into an `Arc<[Bytes]>` once and
                // clone the `Arc` per spawned task instead of
                // calling `events.to_vec()` per peer. Pre-fix
                // [discovery-routing perf #109 in
                // `docs/performance/net-discovery-routing-analysis.md`]
                // a 100-subscriber × 1000-event broadcast did 100
                // Vec allocations + 100K `Bytes` refcount bumps;
                // post-fix it's 1 Vec alloc + 1K `Bytes` bumps +
                // 100 `Arc` bumps. The spawned task derefs the
                // `Arc<[Bytes]>` to `&[Bytes]` at the
                // `publish_to_peer` call site.
                let events_shared: Arc<[Bytes]> = events.to_vec().into();
                for peer_id in subscribers {
                    let permit = Arc::clone(&sem);
                    let events_for_task: Arc<[Bytes]> = Arc::clone(&events_shared);
                    let fut = async move {
                        let _permit = permit.acquire_owned().await.ok();
                        (
                            peer_id,
                            self.publish_to_peer(
                                peer_id,
                                channel_hash,
                                stream_id,
                                reliable,
                                &events_for_task,
                            )
                            .await,
                        )
                    };
                    handles.push(fut);
                }
                let results = futures::future::join_all(handles).await;
                for (peer_id, res) in results {
                    match res {
                        Ok(()) => report.delivered += 1,
                        Err(e) => report.errors.push((peer_id, e)),
                    }
                }
                // BestEffort returns Ok as long as at least one subscriber
                // got the payload — empty roster was handled above, so
                // here there was at least one attempt.
                if matches!(on_failure, OnFailure::BestEffort)
                    && report.delivered == 0
                    && !report.errors.is_empty()
                {
                    let first = report
                        .errors
                        .first()
                        .map(|(id, e)| {
                            format!(
                                "all {} peers failed (first: {:#x}: {})",
                                report.attempted, id, e
                            )
                        })
                        .unwrap_or_else(|| "all peers failed".into());
                    return Err(AdapterError::Connection(first));
                }
                Ok(report)
            }
        }
    }

    /// Encode the channel hash into a `u64` stream id so that per-channel
    /// ordering holds within a session. Hash collisions between channels
    /// are possible but harmless here — streams are opaque u64 to the
    /// transport and have no ACL meaning.
    pub(super) fn publish_stream_id(channel: &ChannelId) -> u64 {
        // Pack channel hash with the bit-48 discriminator so that
        // channel-keyed publisher streams don't alias the common
        // subprotocol range (0x0400..0x0A00). `channel.hash()` is
        // u64 (per ChannelHash = u64), so no widening cast needed.
        0x0001_0000_0000_0000 | channel.hash()
    }

    /// Send one per-peer leg of a publish. Reuses the same packet-build
    /// path as `send_on_stream`, with an explicit stream opened per
    /// `(peer, channel)` pair.
    /// Direct unicast publish of `events` to `peer_node_id` on the
    /// channel identified by `channel_hash`. Used by `Mesh::publish`
    /// (which routes via the subscriber roster) and by the
    /// `mesh_rpc` glue (which knows the target directly and bypasses
    /// the roster).
    pub(super) async fn publish_to_peer(
        &self,
        peer_node_id: u64,
        channel_hash: ChannelHash,
        stream_id: u64,
        reliable: bool,
        events: &[Bytes],
    ) -> Result<(), AdapterError> {
        let (dest_addr, session) = match self.peers.get(&peer_node_id) {
            Some(p) => (p.value().addr, p.value().session.clone()),
            None => {
                return Err(AdapterError::Connection(format!(
                    "publish: no session for subscriber {:#x}",
                    peer_node_id
                )));
            }
        };

        if self.partition_filter.contains(&dest_addr) {
            return Err(AdapterError::Connection(format!(
                "publish: peer {:#x} is partitioned",
                peer_node_id
            )));
        }

        // Ensure a stream is open with the right reliability mode.
        // `open_stream_with` seeds the stream with
        // `DEFAULT_STREAM_WINDOW_BYTES` so publish traffic rides
        // the same v2 byte-credit window as `send_on_stream`.
        session.open_stream_with(stream_id, reliable, 1);

        // Charge credit on the wire-byte size of the packet we're
        // about to build. The `TxSlotGuard` refunds on Drop unless
        // we `commit()` after a successful socket send, so a failed
        // send doesn't strand credit.
        let payload_bytes: usize = events.iter().map(|e| EventFrame::LEN_SIZE + e.len()).sum();
        let needed = wire_bytes_for_payload(payload_bytes);
        let (guard, seq) = match session.try_acquire_tx_credit_guard(stream_id, needed) {
            TxAdmit::Acquired { guard, seq } => (guard, seq),
            TxAdmit::WindowFull => {
                return Err(AdapterError::Connection(format!(
                    "publish: stream {:#x} backpressured",
                    stream_id
                )));
            }
            TxAdmit::StreamClosed => {
                return Err(AdapterError::Connection(format!(
                    "publish: stream {:#x} closed",
                    stream_id
                )));
            }
        };

        let pool = session.thread_local_pool();
        let mut builder = pool.get();
        // Stamp `channel_hash` on the outbound packet header so the
        // receiver can route per-channel. The mesh's pub/sub
        // historically routed entirely via the subscriber roster
        // and the wire-level `channel_hash` rode at 0, so per-
        // channel inbound dispatchers (e.g. nRPC's
        // `register_rpc_inbound`) couldn't differentiate. Stamping
        // it makes the wire carry the channel identity the receiver
        // needs; the roster path is unaffected (the receiver's
        // shard-inbound queue still gets the event when no per-
        // channel dispatcher is registered).
        //
        // The wire `NetHeader::channel_hash` is a `u16` fast-path hint
        // — narrow the canonical [`ChannelHash`] (u64) to 16 bits for
        // the wire. Wire-side collisions are benign (the receiver
        // disambiguates via `ChannelConfigRegistry::get_by_wire_hash`
        // (Option, None on collision — collision-safe policy) /
        // `ChannelRegistry::get_all_by_wire_hash` (Vec, full collision
        // set — used by receive-side dispatch fan-out) and re-keys on
        // the canonical 64-bit hash for ACL / storage decisions).
        builder.set_channel_hash(channel_hash as u16);
        // Stamp our identity's origin_hash so the receiver can
        // route per-chain logic (greedy cache, gravity heat
        // counters, RYW tokens) against a real chain identifier
        // rather than the protocol-level default of zero. The
        // packet header carries a `u32` view of the `u64` keypair
        // origin_hash; routing-hash collisions in the lower 32
        // bits are benign for the chain-routing use case (the
        // receiver compares full hashes when it matters).
        builder.set_origin_hash(self.identity.entity_id().origin_hash());
        // Match the rest of the sender call sites
        // (`send_to_peer:3661`, `send_to_peer:3685`, `send_routed:3755`,
        // `send_routed:3785`, `send_on_stream:6110`, `mod.rs:1016, 1063`):
        // thread `reliable` into the packet header. Pre-fix this site
        // hard-coded `PacketFlags::NONE` and only fed `reliable` into
        // `open_stream_with`. Today the dispatch path doesn't inspect
        // `flags.is_reliable()` (reliability is per-stream, set on
        // open), so the bug is latent — but the per-call-site
        // inconsistency would silently bite if a future receiver path
        // started consulting the packet flag the way `proxy.rs` /
        // `route.rs` / `router.rs` already consult `is_priority` /
        // `is_control`.
        let flags = if reliable {
            PacketFlags::RELIABLE
        } else {
            PacketFlags::NONE
        };
        let packet = builder.build_subprotocol(
            stream_id, seq, events, flags, 0, /* subprotocol_id 0 = event-plane */
        );

        let next_hop = self
            .router
            .routing_table()
            .lookup(peer_node_id)
            .unwrap_or(dest_addr);

        self.socket
            .send_to(&packet, next_hop)
            .await
            .map_err(|e| AdapterError::Connection(format!("publish send failed: {}", e)))?;
        guard.commit(); // wire-accepted — bytes now belong to the receiver

        drop(builder);
        session.touch();
        Ok(())
    }

    /// Encode a [`super::behavior::fold::SignedAnnouncement`] and
    /// send it to one peer as a
    /// [`super::behavior::fold::SUBPROTOCOL_FOLD`] frame.
    /// The receiver's `dispatch_packet` arm decodes + verifies +
    /// routes to the right typed [`super::behavior::fold::Fold<K>`]
    /// via the installed
    /// [`super::behavior::fold::FoldChannelRouter`].
    ///
    /// Returns the encoded byte count for metrics / diagnostics.
    pub async fn publish_fold_to_peer<P>(
        &self,
        peer_addr: SocketAddr,
        ann: &super::behavior::fold::SignedAnnouncement<P>,
    ) -> Result<usize, AdapterError>
    where
        P: serde::Serialize + serde::de::DeserializeOwned,
    {
        let bytes = ann
            .encode()
            .map_err(|e| AdapterError::Connection(format!("fold: encode failed: {e}")))?;
        let n = bytes.len();
        self.send_subprotocol(peer_addr, super::behavior::fold::SUBPROTOCOL_FOLD, &bytes)
            .await?;
        Ok(n)
    }

    /// Best-effort fan-out of a fold announcement to every
    /// currently-connected peer. Per-peer send failures are
    /// logged and skipped rather than short-circuiting the rest
    /// of the fan-out. The N peer sends run concurrently via
    /// `futures::future::join_all` so a chatty publisher (e.g.
    /// ReservationFold against a busy resource) doesn't block
    /// its own task on serial encryption + UDP-send latency.
    ///
    /// Returns the number of peers the announcement was
    /// successfully shipped to.
    pub async fn publish_fold_broadcast<P>(
        &self,
        ann: &super::behavior::fold::SignedAnnouncement<P>,
    ) -> Result<usize, AdapterError>
    where
        P: serde::Serialize + serde::de::DeserializeOwned,
    {
        let bytes = ann
            .encode()
            .map_err(|e| AdapterError::Connection(format!("fold: encode failed: {e}")))?;
        let peer_addrs: Vec<SocketAddr> = self.peers.iter().map(|e| e.value().addr).collect();
        // Share the encoded bytes by reference; each send
        // borrows the same slice. send_subprotocol clones into
        // its own internal allocation, so concurrent sends don't
        // contend on the buffer.
        let bytes_ref = &bytes;
        let sends = peer_addrs.into_iter().map(|addr| async move {
            let result = self
                .send_subprotocol(addr, super::behavior::fold::SUBPROTOCOL_FOLD, bytes_ref)
                .await;
            (addr, result)
        });
        let results = futures::future::join_all(sends).await;
        let mut sent = 0usize;
        for (addr, result) in results {
            match result {
                Ok(()) => sent += 1,
                Err(e) => {
                    tracing::trace!(peer = %addr, error = %e, "fold: broadcast send failed");
                }
            }
        }
        Ok(sent)
    }

    /// Allocate the next monotonic generation for one
    /// `(kind, class)` slot. Pre-increment semantic — first call
    /// returns `1`, since the wire format reserves `0` as the
    /// "uninitialized" sentinel
    /// [`super::behavior::fold::FoldError::InvalidGeneration`]
    /// rejects. Also stamps `last_touched_us` so the
    /// fold-generation GC keeps the slot live as long as the
    /// publisher is actively using it.
    pub(crate) fn next_fold_generation(&self, kind: u16, class: u64) -> u64 {
        let entry = self
            .fold_generations
            .entry((kind, class))
            .or_insert_with(FoldGenerationEntry::new);
        entry
            .last_touched_us
            .store(super::current_timestamp_micros(), Ordering::Relaxed);
        entry.counter.fetch_add(1, Ordering::Relaxed) + 1
    }

    /// Sign + broadcast one fold announcement.
    ///
    /// `counter_class` shards the per-`(kind, class)` generation
    /// counter; `envelope_class` is the wire envelope's `class`
    /// field. The two are identical for most folds; reservation
    /// passes `counter_class=resource_id` (per-resource counter)
    /// but `envelope_class=0` (pool identifier unused).
    async fn publish_fold<K>(
        &self,
        counter_class: u64,
        envelope_class: u64,
        payload: K::Payload,
    ) -> Result<usize, AdapterError>
    where
        K: super::behavior::fold::FoldKind,
    {
        let gen = self.next_fold_generation(K::KIND_ID, counter_class);
        let meta = super::behavior::fold::EnvelopeMeta {
            announced_at: super::current_timestamp_micros(),
            ..Default::default()
        };
        let ann = super::behavior::fold::SignedAnnouncement::sign(
            &self.identity,
            K::KIND_ID,
            envelope_class,
            self.node_id,
            gen,
            meta,
            payload,
        )
        .map_err(|e| AdapterError::Connection(format!("fold: sign failed: {e}")))?;
        self.publish_fold_broadcast(&ann).await
    }

    /// Publish a [`super::behavior::fold::CapabilityFold`]
    /// membership announcement against this node's identity.
    /// The counter is sharded per-`class_hash` so concurrent
    /// publishes to different classes don't contend.
    pub async fn publish_capability_membership(
        &self,
        membership: super::behavior::fold::CapabilityMembership,
    ) -> Result<usize, AdapterError> {
        let class = membership.class_hash;
        self.publish_fold::<super::behavior::fold::CapabilityFold>(class, class, membership)
            .await
    }

    /// Publish a [`super::behavior::fold::RoutingFold`] route
    /// announcement. The fold doesn't shard by class, so both
    /// the counter and the envelope use class `0`. `via` is
    /// auto-stamped to this node's `node_id`.
    pub async fn publish_route(
        &self,
        destination: super::behavior::fold::NodeId,
        next_hop: SocketAddr,
        metric: u32,
    ) -> Result<usize, AdapterError> {
        self.publish_fold::<super::behavior::fold::RoutingFold>(
            0,
            0,
            super::behavior::fold::RouteAnnouncement {
                destination,
                next_hop,
                metric,
                via: self.node_id,
            },
        )
        .await
    }

    /// Publish a [`super::behavior::fold::ReservationFold`]
    /// state transition for `resource_id`. Generation is
    /// per-resource (counter sharded by `resource_id`) so
    /// concurrent transitions against different resources don't
    /// contend; the envelope's `class` field is unused for this
    /// fold and stays `0`.
    pub async fn publish_reservation(
        &self,
        resource_id: super::behavior::fold::ResourceId,
        state: super::behavior::fold::ReservationState,
    ) -> Result<usize, AdapterError> {
        self.publish_fold::<super::behavior::fold::ReservationFold>(
            resource_id,
            0,
            super::behavior::fold::ReservationAnnouncement { resource_id, state },
        )
        .await
    }

    /// Publish this node's [`super::behavior::fold::IslandTopologyFold`]
    /// record for one of its GPU islands — the host self-announcing
    /// its gpu set, warm models, and the live load / p50-latency
    /// axes. Re-publish each heartbeat to refresh the live axes;
    /// generation is per-island (sharded by island id). Peers fold
    /// these into the Thunderdome gang scheduler's numeric-filter
    /// view.
    ///
    /// `record.host` is forced to this node's id so the announcement
    /// passes the fold's ownership gate (a node may only announce
    /// islands it hosts).
    pub async fn publish_island_topology(
        &self,
        mut record: super::behavior::fold::IslandRecord,
    ) -> Result<usize, AdapterError> {
        use super::behavior::fold::{FoldKind, IslandTopologyFold};
        record.host = self.node_id;
        let island_id = record.id;
        let gen = self.next_fold_generation(IslandTopologyFold::KIND_ID, island_id);
        let meta = super::behavior::fold::EnvelopeMeta {
            announced_at: super::current_timestamp_micros(),
            ..Default::default()
        };
        let ann = super::behavior::fold::SignedAnnouncement::sign(
            &self.identity,
            IslandTopologyFold::KIND_ID,
            0,
            self.node_id,
            gen,
            meta,
            record,
        )
        .map_err(|e| AdapterError::Connection(format!("island: sign failed: {e}")))?;
        // Self-index so the node's OWN scheduler sees islands it hosts:
        // match_islands / claim_island read self.island_fold,
        // and the broadcast only reaches peers. Mirrors the capability
        // (announce_capabilities) and reservation
        // (apply_and_broadcast_reservation) self-apply paths (review #1).
        let _ = self.island_fold.apply(ann.clone());
        self.publish_fold_broadcast(&ann).await
    }

    /// Send a raw subprotocol message to a peer.
    ///
    /// The payload is sent as a single event frame with the specified
    /// `subprotocol_id` set in the Net header (included in AEAD AAD).
    pub async fn send_subprotocol(
        &self,
        peer_addr: SocketAddr,
        subprotocol_id: u16,
        payload: &[u8],
    ) -> Result<(), AdapterError> {
        if self.partition_filter.contains(&peer_addr) {
            return Ok(());
        }

        let node_id = self
            .addr_to_node
            .get(&peer_addr)
            .map(|e| *e.value())
            .ok_or_else(|| AdapterError::Connection("unknown peer".into()))?;
        let peer = self
            .peers
            .get(&node_id)
            .ok_or_else(|| AdapterError::Connection("unknown peer".into()))?;

        let session = &peer.session;
        let stream_id = subprotocol_id as u64;

        let pool = session.thread_local_pool();
        let mut builder = pool.get();

        let seq = {
            let stream = session.get_or_create_stream(stream_id);
            stream.next_tx_seq()
        };

        let events = vec![Bytes::copy_from_slice(payload)];
        let packet =
            builder.build_subprotocol(stream_id, seq, &events, PacketFlags::NONE, subprotocol_id);

        self.socket
            .send_to(&packet, peer_addr)
            .await
            .map_err(|e| AdapterError::Connection(format!("send failed: {}", e)))?;

        drop(builder);
        session.touch();
        Ok(())
    }

    // ── Capability announcements ──────────────────────────────────────
    //
    // `SUBPROTOCOL_CAPABILITY_ANN` payloads; the on-wire form is
    // `CapabilityAnnouncement::to_bytes`. Direct-peer push only in
    // v1; multi-hop gossip is a follow-up.

    /// Self-index a fresh `CapabilityAnnouncement` that merges every
    /// currently-registered nRPC service from `rpc_local_services`
    /// into the existing `user_caps` baseline. Used by `serve_rpc`
    /// so the v0.4 capability-auth callee-side gate (in
    /// `serve_rpc`'s bridge) observes a self-announcement carrying
    /// the new `nrpc:<service>` tag the moment the bridge starts
    /// consuming inbound events. Closes the cold-start hole (H1)
    /// and the `announce_capabilities` / `serve_rpc` ordering trap
    /// (H2): the merged self-announcement is in the local index
    /// regardless of whether the operator called
    /// `announce_capabilities` first, last, or not at all.
    ///
    /// Sync (no broadcast). Peer-side visibility happens via the
    /// subsequent spawned `announce_capabilities` call in
    /// `serve_rpc` (or the next operator-issued announce). The
    /// version bump is cheap and monotonic with the broadcast
    /// path — receivers always honor the highest version per
    /// `node_id`.
    ///
    /// **Divergence from `announce_capabilities_with`**: this sync
    /// path intentionally skips the `nat:*` piggyback tag and the
    /// `reflex_addr` field that the broadcast path adds. The
    /// capability-auth gate is `nrpc:`-only, so the omission is
    /// invisible to the gate; the spawned re-announce that
    /// follows in `serve_rpc` lays down the full
    /// `nat:` + `reflex_addr` form for peer-visible filtering. If
    /// a future gate axis keys on `nat:*` (e.g. requiring callers
    /// to be open-cone), this sync self-index becomes the
    /// cold-start hole that re-opens it — extend the merged
    /// `CapabilitySet` here in lockstep.
    #[cfg(feature = "cortex")]
    pub(crate) fn index_self_with_local_services(&self) {
        let baseline = self.user_caps_snapshot();
        let merged = {
            let mut m = baseline;
            for svc in self.rpc_local_services.snapshot() {
                m = m.add_tag(format!("nrpc:{}", svc.as_str()));
            }
            m
        };
        let version = self.capability_version.fetch_add(1, Ordering::Relaxed) + 1;
        let mut ann = CapabilityAnnouncement::new(
            self.node_id,
            self.identity.entity_id().clone(),
            version,
            merged,
        )
        .with_ttl(300);
        ann.sign(&self.identity);
        let fold_ann = super::behavior::fold::capability_bridge::translate_announcement(&ann);
        let _ = self.capability_fold.apply(fold_ann);
    }

    /// Announce this node's capabilities to every directly-connected
    /// peer. Also self-indexes so single-node `find_nodes_by_filter`
    /// queries return us too.
    ///
    /// TTL defaults to 5 minutes. Unsigned (signatures tie in with
    /// Stage E channel auth). For explicit control over TTL or
    /// signing, see [`Self::announce_capabilities_with`].
    pub async fn announce_capabilities(&self, caps: CapabilitySet) -> Result<(), AdapterError> {
        // Default to signed — the node always has a keypair (either
        // caller-supplied or ephemeral at construction time), so
        // signing is free and closes the trust-on-first-use gap.
        self.announce_capabilities_with(caps, Duration::from_secs(300), true)
            .await
    }

    /// Extended announce with explicit TTL and signing opt-in.
    ///
    /// `sign = true` signs the announcement with the node's
    /// [`EntityKeypair`] so receivers can validate end-to-end.
    /// `sign = false` broadcasts unsigned — useful in trusted
    /// environments where the wire signature adds no value.
    /// Receivers with `require_signed_capabilities = true` drop
    /// unsigned announcements regardless.
    pub async fn announce_capabilities_with(
        &self,
        caps: CapabilitySet,
        ttl: Duration,
        sign: bool,
    ) -> Result<(), AdapterError> {
        // Explicit announce: `caps` becomes the new user-caps baseline.
        self.announce_from_baseline(Some(caps), ttl, sign).await
    }

    /// Core announce path shared by explicit announces and the
    /// re-announce loops (RT-3 change-driven + keep-alive).
    ///
    /// `new_baseline = Some(caps)` sets a NEW user-caps baseline;
    /// `None` RE-announces the CURRENT baseline without overwriting
    /// it — what the keep-alive and RT-3 loops want. Passing `None`
    /// (instead of snapshotting `user_caps` outside and handing it
    /// back in) closes the RT-3 clobber TOCTOU: a concurrent explicit
    /// `announce(Y)` can no longer be overwritten by a re-announce
    /// that captured the old baseline (RT-3 review Finding 8).
    ///
    /// The whole synchronous critical section — baseline read/write,
    /// the `capability_version` bump, and the `local_announcement`
    /// store — runs under `announce_mu`, so two concurrent announces
    /// can't interleave their version and store order and leave the
    /// lower-version announcement published (RT-1 review Finding 11).
    /// The guard is released before the async peer broadcast.
    async fn announce_from_baseline(
        &self,
        new_baseline: Option<CapabilitySet>,
        ttl: Duration,
        sign: bool,
    ) -> Result<(), AdapterError> {
        // `Some(bytes)` to broadcast after releasing the lock; `None`
        // when the announce was rate-limit-deferred or coalesced.
        let to_broadcast = {
            let _announce_guard = self.announce_mu.lock();
            // Set a new baseline or re-read the current one — both
            // under `announce_mu` so a re-announce never clobbers a
            // concurrent explicit announce's newer baseline. The
            // baseline lets subsequent `announce_chain` /
            // `withdraw_chain` calls layer mutations on top without
            // re-augmenting the nrpc / nat tags that follow.
            let caps = match new_baseline {
                Some(caps) => {
                    *self.user_caps.write() = Some(caps.clone());
                    caps
                }
                None => self.user_caps.read().clone().unwrap_or_default(),
            };
            // Merge nRPC service registrations as `nrpc:<service>` tags.
            // Other nodes' capability indexes pick these up, letting
            // `Mesh::find_service_nodes(name)` resolve us as a server
            // for the registered services. Local-only state from
            // `Mesh::serve_rpc`; deduped against existing tags so a
            // user that pre-tagged manually doesn't get double entries.
            // Gated on `cortex` because `rpc_local_services` only
            // exists when the cortex layer (which provides serve_rpc)
            // is compiled in.
            #[cfg(feature = "cortex")]
            let caps = if self.rpc_local_services.is_empty() {
                caps
            } else {
                let mut merged = caps;
                for svc in self.rpc_local_services.snapshot() {
                    let tag = format!("nrpc:{}", svc.as_str());
                    // Phase A.5.N.2: tags is HashSet<Tag>; insert via
                    // builder so the parsed-tag form lands and dedupes
                    // against existing entries.
                    merged = merged.add_tag(tag);
                }
                merged
            };

            // Merge AI-tool registrations on top of the `nrpc:` tags.
            // For every tool the SDK's `serve_tool` registered, this
            // appends:
            //   - an `ai-tool:<name>` capability tag, so
            //     `find_nodes_for_tag_prefix("ai-tool:")` discovers
            //     this host;
            //   - the typed `ToolCapability` itself (added via
            //     `CapabilitySet::add_tool`), so the typed views aggregate
            //     a `Vec<ToolCapability>` across peers in the fold;
            //   - the description / streaming / tags metadata keys via
            //     `CapabilitySet::metadata`, mirroring the existing
            //     `input_schema` / `output_schema` convention so peers
            //     without the `tool` feature still receive the data and
            //     just ignore the unknown keys.
            //
            // Tool registrations are local to this node, just like
            // `rpc_local_services`. Drop on the SDK's `ServeHandle`
            // removes from the registry; the next `announce_capabilities`
            // reflects the smaller set.
            #[cfg(feature = "tool")]
            let caps = if self.tool_registry.is_empty() {
                caps
            } else {
                use crate::adapter::net::behavior::ToolCapability;
                use crate::adapter::net::cortex::tool::{
                    description_metadata_key, pricing_terms_metadata_key, streaming_metadata_key,
                    tags_metadata_key,
                };
                let snapshot = self.tool_registry.snapshot();
                // Reconstruct ToolCapability values from each descriptor's
                // wire-cheap fields; schemas stay in metadata (the fold
                // has its own schema-too-large branch) so the typed-cap
                // payload doesn't bloat.
                let tools_to_add: Vec<ToolCapability> = snapshot
                    .iter()
                    .map(|descriptor| {
                        let mut cap = ToolCapability::new(&descriptor.tool_id, &descriptor.name)
                            .with_version(&descriptor.version)
                            .with_estimated_time(descriptor.estimated_time_ms)
                            .with_stateless(descriptor.stateless);
                        if let Some(ref schema) = descriptor.input_schema {
                            cap = cap.with_input_schema(schema.clone());
                        }
                        if let Some(ref schema) = descriptor.output_schema {
                            cap = cap.with_output_schema(schema.clone());
                        }
                        for req in &descriptor.requires {
                            cap = cap.requires(req.clone());
                        }
                        cap
                    })
                    .collect();
                // Single set_tools call; O(N) total instead of the
                // O(N²) chain of per-tool add_tool invocations.
                let mut merged = caps.add_tools(tools_to_add);
                for descriptor in snapshot.iter() {
                    merged = merged.add_tag(format!("ai-tool:{}", descriptor.tool_id));
                    // Description + streaming + tags ride the metadata
                    // extensibility hook (same convention input/output
                    // schemas already use). Pre-tool peers receive these
                    // keys and ignore them — no wire-breaking change.
                    if let Some(ref desc) = descriptor.description {
                        merged = merged.with_metadata(
                            description_metadata_key(&descriptor.tool_id),
                            desc.clone(),
                        );
                    }
                    if descriptor.streaming {
                        merged = merged.with_metadata(
                            streaming_metadata_key(&descriptor.tool_id),
                            "1".to_string(),
                        );
                    }
                    if !descriptor.tags.is_empty() {
                        merged = merged.with_metadata(
                            tags_metadata_key(&descriptor.tool_id),
                            descriptor.tags.join(","),
                        );
                    }
                    // Pricing terms (net.pricing.terms@1 canonical JSON) ride
                    // the same hook — paid capability = metadata + invocation
                    // policy, not a different kind of tool. The substrate
                    // never parses the value.
                    if let Some(ref terms) = descriptor.pricing_terms {
                        merged = merged.with_metadata(
                            pricing_terms_metadata_key(&descriptor.tool_id),
                            terms.clone(),
                        );
                    }
                }
                merged
            };

            // STREAM_ACK_BATCHING R-5: advertise transport support for
            // positive SACK-range ACKs — same auto-augment pattern as the
            // `nrpc:` / `ai-tool:` tags above. Config-gated so operators
            // can turn the feature off wire-wide (compliant peers then
            // never emit ranges to us, and we never emit to anyone).
            let caps = if self.config.enable_stream_ack_ranges {
                caps.add_tag(ACK_RANGES_CAPABILITY_TAG.to_string())
            } else {
                caps
            };

            let version = self.capability_version.fetch_add(1, Ordering::Relaxed) + 1;

            // Piggyback the current NAT classification as a `nat:*`
            // capability tag so peers can filter-match on NAT type,
            // and the reflex address on the dedicated announcement
            // field so peers have a direct-connect candidate without a
            // separate discovery round-trip. Both are feature-gated on
            // `nat-traversal` — callers compiled without the feature
            // emit announcements identical to the pre-traversal format.
            //
            // The two reads happen under `traversal_publish_mu` so
            // the announcement always carries a consistent (class,
            // reflex) pair. Without the mutex, a concurrent
            // set/clear/commit could interleave between our reads
            // and let us publish a torn state — e.g., the new
            // override's reflex paired with the pre-override NAT
            // class. The lock is held only for the two atomic reads,
            // not across the signing or network send.
            #[cfg(feature = "nat-traversal")]
            let (caps, reflex_snapshot) = {
                use super::traversal::classify::NatClass;
                let _g = self.traversal_publish_mu.lock();
                let class =
                    NatClass::from_u8(self.nat_class.load(std::sync::atomic::Ordering::Acquire));
                let reflex = self.reflex_addr.load_full().map(|arc| *arc);
                // Strip any prior `nat:*` tags before adding the fresh
                // one so a reclassification doesn't leave a stale tag
                // behind when the class transitions. Phase A.5.N.2:
                // `caps.tags` is `HashSet<Tag>` — `nat:*` tags parse
                // as `Tag::Legacy`, so we render to wire form for
                // prefix matching.
                let mut next = caps;
                next.tags.retain(|t| !t.to_string().starts_with("nat:"));
                let next = next.add_tag(class.tag().to_string());
                (next, reflex)
            };

            // Push the fully-merged capability set into the proximity
            // graph so origin pingwaves — the heartbeat tick AND the
            // change-driven `emit_event_pingwave` the RT-3/RT-4 loop
            // fires right after this announce — piggyback the CURRENT
            // capability hash / version / primary summary instead of the
            // graph's default (0, 0, empty). `set_local_capabilities`
            // was previously dead code, so every event pingwave carried
            // a stale summary (RT-5 review P2). Runs before the
            // rate-limit branch, same as the self-index below, so a
            // coalesced announce still refreshes the local pingwave
            // state.
            self.proximity_graph.set_local_capabilities(caps.clone());

            let mut ann = CapabilityAnnouncement::new(
                self.node_id,
                self.identity.entity_id().clone(),
                version,
                caps,
            )
            .with_ttl(ttl.as_secs().min(u32::MAX as u64) as u32);
            #[cfg(feature = "nat-traversal")]
            {
                ann = ann.with_reflex_addr(reflex_snapshot);
            }
            if sign {
                ann.sign(&self.identity);
            }

            // Self-index so local queries see our own caps. Always runs
            // regardless of rate limit — the self-index reflects the
            // latest intended announcement.
            let fold_ann = super::behavior::fold::capability_bridge::translate_announcement(&ann);
            let _ = self.capability_fold.apply(fold_ann);

            // Publish as the latest local announcement so future
            // session-opens push this version to new peers. Also always
            // runs so late joiners get the latest caps even when we've
            // rate-limited away the broadcast.
            self.local_announcement.store(Some(Arc::new(ann.clone())));

            // Origin-side rate limit: within-window calls update the
            // self-index + `local_announcement` and coalesce into one
            // trailing-edge flush at window end (RT-1). Pre-fix the
            // suppressed broadcast was silently dropped, so a change
            // landing inside the window stayed invisible to peers
            // until the next explicit call or the 150 s re-announce
            // keep-alive. At most one flush task is pending at a
            // time; it broadcasts whatever `local_announcement` holds
            // when it fires, so N suppressed calls collapse to one
            // send of the newest version.
            let now = std::time::Instant::now();
            let min_interval = self.config.min_announce_interval;
            let defer_for = {
                let mut gate = self.announce_gate.lock();
                let elapsed = gate
                    .last_broadcast_at
                    .map(|t| now.saturating_duration_since(t));
                match elapsed {
                    Some(e) if e < min_interval => {
                        // In-window with a flush already pending: that
                        // flush will pick up the `local_announcement`
                        // we just stored. Nothing to schedule.
                        if gate.deferred_scheduled {
                            return Ok(());
                        }
                        // Bare-start node (no `start_arc`): there is no
                        // owned `Arc` for a flush task to hold — same
                        // constraint as the re-announce loop. Preserve
                        // the pre-RT-1 drop semantics (peers see the
                        // change on the next out-of-window announce or
                        // the keep-alive).
                        if self.self_weak.get().is_none() {
                            tracing::debug!(
                                "capability: in-window announce not deferred \
                             (node not started via start_arc)"
                            );
                            return Ok(());
                        }
                        gate.deferred_scheduled = true;
                        // New deferral claim → new generation. The
                        // flush task captures this and re-checks it, so
                        // a task orphaned by a rate-limit-floor reset
                        // can't fire against this claim (Finding 12).
                        gate.deferral_generation = gate.deferral_generation.wrapping_add(1);
                        Some((min_interval - e, gate.deferral_generation))
                    }
                    _ => {
                        gate.last_broadcast_at = Some(now);
                        None
                    }
                }
            };
            if let Some((delay, generation)) = defer_for {
                self.spawn_deferred_announce(delay, generation);
                None
            } else {
                Some(ann.to_bytes())
            }
        };
        // `announce_mu` is released here — the peer broadcast is
        // network I/O and must never hold the announce lock.

        // Fan out to currently-connected peers.
        let Some(bytes) = to_broadcast else {
            return Ok(());
        };
        self.broadcast_announcement_bytes(&bytes).await;
        Ok(())
    }

    /// Broadcast a serialized `CapabilityAnnouncement` to every
    /// currently-connected peer. Best-effort — a per-peer send failure
    /// is logged and skipped rather than short-circuiting the fan-out.
    /// Shared by the immediate announce path and the RT-1 trailing-edge
    /// flush so the two can't drift (RT-1 review Finding 14).
    async fn broadcast_announcement_bytes(&self, bytes: &[u8]) {
        let peer_addrs: Vec<SocketAddr> = self.peers.iter().map(|e| e.value().addr).collect();
        for addr in peer_addrs {
            if let Err(e) = self
                .send_subprotocol(addr, SUBPROTOCOL_CAPABILITY_ANN, bytes)
                .await
            {
                tracing::trace!(peer = %addr, error = %e, "capability: announce send failed");
            }
        }
    }

    /// Schedule the trailing-edge announce flush for the current
    /// rate-limit window (RT-1). The caller has already claimed the
    /// deferred slot (`deferred_scheduled = true`) under the gate
    /// lock and verified `self_weak` is populated; this task holds
    /// only a `Weak<MeshNode>` so a pending flush can't keep a
    /// dropped node alive.
    ///
    /// `generation` is the deferral id captured at claim time; the
    /// flush re-checks it so a task orphaned by a rate-limit-floor
    /// reset can't fire against a newer claim (Finding 12).
    fn spawn_deferred_announce(&self, delay: Duration, generation: u64) {
        // Guaranteed `Some` by the gate branch that claimed the
        // deferred slot; release the slot rather than panic if a
        // future caller breaks that invariant.
        let Some(weak) = self.self_weak.get().cloned() else {
            self.announce_gate.lock().deferred_scheduled = false;
            return;
        };
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();
        tokio::spawn(async move {
            tokio::select! {
                _ = tokio::time::sleep(delay) => {}
                _ = shutdown_notify.notified() => return,
            }
            if shutdown.load(Ordering::Acquire) {
                return;
            }
            let Some(node) = weak.upgrade() else { return };
            node.flush_deferred_announce(generation).await;
        });
    }

    /// Trailing-edge flush: broadcast the latest `local_announcement`
    /// to all connected peers and open the next rate-limit window.
    /// Runs at most once per scheduled deferral, and only if the
    /// deferred slot is still claimed BY THIS DEFERRAL — a
    /// rate-limit-floor reset (`set_reflex_override` /
    /// `clear_reflex_override`) cancels the slot, and a fresh in-window
    /// announce re-claims it with a new `deferral_generation`. Either
    /// way, an orphaned task whose captured `generation` no longer
    /// matches no-ops instead of broadcasting inside a fresh window
    /// (Finding 12); the reset's documented follow-up announce
    /// supersedes the flush.
    async fn flush_deferred_announce(&self, generation: u64) {
        {
            let mut gate = self.announce_gate.lock();
            if !gate.deferred_scheduled || gate.deferral_generation != generation {
                return;
            }
            gate.deferred_scheduled = false;
            gate.last_broadcast_at = Some(std::time::Instant::now());
        }
        // `local_announcement` is stored before the gate on every
        // announce path, so a scheduled flush always finds it.
        let Some(ann) = self.local_announcement.load_full() else {
            return;
        };
        self.broadcast_announcement_bytes(&ann.to_bytes()).await;
    }

    // ── Chain-tag discovery helpers ───────────────────────────────────
    //
    // Capability Phase B: `Mesh::announce_chain` / `announce_chain_range`
    // / `withdraw_chain` / `find_chain_holders` per
    // `docs/plans/CAPABILITY_SYSTEM_PLAN.md` §B. Mutates the user-
    // supplied capability baseline atomically + re-broadcasts via
    // `announce_capabilities`; the nrpc / nat tags layered on at
    // broadcast time aren't re-augmented twice. Each helper is
    // idempotent — repeated calls converge to the same wire shape.
    //
    // Consumed by `redex::replication::ReplicationCoordinator`
    // (Phase C of `REDEX_DISTRIBUTED_PLAN.md`) for replica-holding
    // advertisement; the deterministic election function takes its
    // membership set from this discovery surface.

    /// Hex-render an `origin_hash` into the lowercase 16-char shape
    /// the `causal:<hex>` tag carries. Pinned here so wire-format
    /// drift (e.g. uppercase / shortened-form) breaks at the
    /// helper, not in the field.
    fn chain_hex(origin_hash: u64) -> String {
        format!("{origin_hash:016x}")
    }

    /// True iff `tag` is a `causal:<hex>*` reserved tag for the
    /// given hex.
    fn is_causal_for(tag: &Tag, hex: &str) -> bool {
        match tag {
            Tag::Reserved { prefix, body } if prefix.as_str() == "causal:" => {
                Self::is_causal_body_for(body, hex)
            }
            _ => false,
        }
    }

    /// String-form of [`Self::is_causal_for`] for the fold's
    /// canonical tag rendering. Same body-shape logic; takes
    /// a `&str` shaped as `"causal:<hex>"` / `"causal:<hex>:..."` /
    /// `"causal:<hex>[...]"`.
    fn is_causal_for_str(tag: &str, hex: &str) -> bool {
        let Some(body) = tag.strip_prefix("causal:") else {
            return false;
        };
        Self::is_causal_body_for(body, hex)
    }

    /// Match a `causal:`-body against the hex digest.
    ///
    /// Body shapes per CAPABILITY_SYSTEM_PLAN.md §2:
    /// - `<hex>` — presence-form
    /// - `<hex>:<tip_seq>` — tip-form
    /// - `<hex>[<start>..<end>]` — range-form
    ///
    /// All three share the `<hex>` prefix followed by `:` / `[`
    /// / end-of-body. Match exactly so a longer hex that
    /// happens to start with our hex doesn't false-match.
    fn is_causal_body_for(body: &str, hex: &str) -> bool {
        if !body.starts_with(hex) {
            return false;
        }
        matches!(
            body.as_bytes().get(hex.len()),
            None | Some(b':') | Some(b'[')
        )
    }

    /// Strip every `causal:<hex>*` tag for `origin_hash` from
    /// `caps` and insert `replacement` in its place.
    fn replace_causal_tags(caps: &mut CapabilitySet, origin_hash: u64, replacement: Option<Tag>) {
        let hex = Self::chain_hex(origin_hash);
        caps.tags.retain(|t| !Self::is_causal_for(t, &hex));
        if let Some(t) = replacement {
            caps.tags.insert(t);
        }
    }

    /// True iff `tag` is a `heat:<hex>=...` reserved tag for the
    /// supplied chain-hash. Used by [`Self::replace_heat_tags`]
    /// to strip stale heat annotations before re-emission.
    #[cfg(feature = "dataforts")]
    fn is_heat_for(tag: &Tag, hex: &str) -> bool {
        match tag {
            Tag::Reserved { prefix, body } if prefix == "heat:" => {
                // Body shape: `<hex>=<rate>`. Match the chain by
                // prefix-then-`=` so we don't accidentally strip
                // tags for a hex that begins with the target.
                if !body.starts_with(hex) {
                    return false;
                }
                matches!(body.as_bytes().get(hex.len()), Some(b'='))
            }
            _ => false,
        }
    }

    /// Strip every `heat:<hex>=*` tag for `origin_hash` from
    /// `caps` and insert `replacement` in its place. `None` is
    /// withdrawal — every heat annotation for the chain drops.
    #[cfg(feature = "dataforts")]
    fn replace_heat_tags(caps: &mut CapabilitySet, origin_hash: u64, replacement: Option<Tag>) {
        let hex = Self::chain_hex(origin_hash);
        caps.tags.retain(|t| !Self::is_heat_for(t, &hex));
        if let Some(t) = replacement {
            caps.tags.insert(t);
        }
    }

    /// Format a 32-byte BLAKE3 hash as a 64-character lowercase
    /// hex string. Used as the chunk identifier inside `heat:blob:
    /// <hex64>=<rate>` reserved tags.
    #[cfg(feature = "dataforts")]
    fn blob_hex(hash: &[u8; 32]) -> String {
        let mut s = String::with_capacity(64);
        for b in hash {
            use std::fmt::Write;
            let _ = write!(s, "{:02x}", b);
        }
        s
    }

    /// True iff `tag` is a `heat:blob:<hex64>=...` reserved tag for
    /// `hex64`. Mirrors [`Self::is_heat_for`] but matches the
    /// blob-heat body sub-prefix so chain-heat tags and blob-heat
    /// tags never collide.
    #[cfg(feature = "dataforts")]
    fn is_blob_heat_for(tag: &Tag, hex64: &str) -> bool {
        match tag {
            Tag::Reserved { prefix, body } if prefix == "heat:" => {
                if !body.starts_with("blob:") {
                    return false;
                }
                let rest = &body[5..];
                if !rest.starts_with(hex64) {
                    return false;
                }
                matches!(rest.as_bytes().get(hex64.len()), Some(b'='))
            }
            _ => false,
        }
    }

    /// Strip every `heat:blob:<hex64>=*` tag for `hash` from `caps`
    /// and insert `replacement` in its place. `None` is withdrawal.
    /// Parallel to [`Self::replace_heat_tags`] for the per-blob
    /// heat-tag family.
    #[cfg(feature = "dataforts")]
    fn replace_blob_heat_tags(caps: &mut CapabilitySet, hash: &[u8; 32], replacement: Option<Tag>) {
        let hex = Self::blob_hex(hash);
        caps.tags.retain(|t| !Self::is_blob_heat_for(t, &hex));
        if let Some(t) = replacement {
            caps.tags.insert(t);
        }
    }

    /// Read the current user-supplied baseline, defaulting to an
    /// empty `CapabilitySet` when no `announce_capabilities` has
    /// landed yet. Returns an owned snapshot — callers mutate the
    /// snapshot and re-announce.
    ///
    /// `pub(crate)` so the dataforts-blob overflow handler can
    /// read live local caps inside the inbound nRPC path — the
    /// admission gate observes the *current* `overflow_enabled`
    /// state on every push, not a build-time snapshot.
    pub(crate) fn user_caps_snapshot(&self) -> CapabilitySet {
        self.user_caps.read().clone().unwrap_or_default()
    }

    /// Advertise that this node holds the causal chain identified
    /// by `origin_hash` up to and including `tip_seq`. Emits the
    /// `causal:<hex>:<tip_seq>` reserved tag and re-broadcasts the
    /// node's capability announcement.
    ///
    /// Idempotent on the chain identity — every prior tip / range
    /// advertisement for the same `origin_hash` is replaced. The
    /// most recent call wins.
    ///
    /// Capability Phase B per `CAPABILITY_SYSTEM_PLAN.md` §B and a
    /// hard prerequisite for `REDEX_DISTRIBUTED_PLAN.md` Phase C/D/E.
    pub async fn announce_chain(&self, origin_hash: u64, tip_seq: u64) -> Result<(), AdapterError> {
        let hex = Self::chain_hex(origin_hash);
        let replacement = Tag::parse(&format!("causal:{hex}:{tip_seq}")).ok();
        let mut snapshot = self.user_caps_snapshot();
        Self::replace_causal_tags(&mut snapshot, origin_hash, replacement);
        self.announce_capabilities(snapshot).await
    }

    /// Advertise that this node holds the half-open range
    /// `[start_seq, end_seq)` of the chain identified by
    /// `origin_hash`. Emits the
    /// `causal:<hex>[<start>..<end>]` reserved tag and re-broadcasts.
    ///
    /// `start_seq >= end_seq` is a no-op — a degenerate range
    /// would advertise nothing meaningful. Idempotent on the chain
    /// identity; the most recent call replaces every prior tip /
    /// range / presence form for the same `origin_hash`.
    pub async fn announce_chain_range(
        &self,
        origin_hash: u64,
        start_seq: u64,
        end_seq: u64,
    ) -> Result<(), AdapterError> {
        if start_seq >= end_seq {
            return Ok(());
        }
        let hex = Self::chain_hex(origin_hash);
        let replacement = Tag::parse(&format!("causal:{hex}[{start_seq}..{end_seq}]")).ok();
        let mut snapshot = self.user_caps_snapshot();
        Self::replace_causal_tags(&mut snapshot, origin_hash, replacement);
        self.announce_capabilities(snapshot).await
    }

    /// Withdraw every `causal:<hex>*` advertisement for
    /// `origin_hash` and re-broadcast. Idempotent — repeated calls
    /// converge to the same view (the chain tag absent from the
    /// announced set).
    pub async fn withdraw_chain(&self, origin_hash: u64) -> Result<(), AdapterError> {
        let mut snapshot = self.user_caps_snapshot();
        Self::replace_causal_tags(&mut snapshot, origin_hash, None);
        self.announce_capabilities(snapshot).await
    }

    /// Annotate the local capability set with a `heat:<hex>=<rate>`
    /// reserved tag for `origin_hash` and re-broadcast. Replaces
    /// any prior heat tag for the same chain — the most recent
    /// call wins.
    ///
    /// `rate` is clamped to `[0.0, 1.0]` by the substrate's
    /// `CapabilitySet::heat_level` builder; the wire emits the
    /// clamped value with two decimal places. Data-gravity
    /// callers normalize their unbounded read-rate to that range
    /// before calling.
    ///
    /// Rebel Yell Phase 4. See
    /// `docs/misc/DATAFORTS_PLAN.md` § Phase 4.
    #[cfg(feature = "dataforts")]
    pub async fn announce_heat(&self, origin_hash: u64, rate: f64) -> Result<(), AdapterError> {
        let hex = Self::chain_hex(origin_hash);
        let clamped = if rate.is_finite() {
            rate.clamp(0.0, 1.0)
        } else {
            return Err(AdapterError::Fatal("heat rate must be finite".to_string()));
        };
        let replacement = Tag::parse(&format!("heat:{hex}={clamped:.2}")).ok();
        let mut snapshot = self.user_caps_snapshot();
        Self::replace_heat_tags(&mut snapshot, origin_hash, replacement);
        self.announce_capabilities(snapshot).await
    }

    /// Withdraw every `heat:<hex>=*` tag for `origin_hash` and
    /// re-broadcast. Peers drop the heat annotation; the
    /// chain's `causal:` advertisements are untouched.
    #[cfg(feature = "dataforts")]
    pub async fn withdraw_heat(&self, origin_hash: u64) -> Result<(), AdapterError> {
        let mut snapshot = self.user_caps_snapshot();
        Self::replace_heat_tags(&mut snapshot, origin_hash, None);
        self.announce_capabilities(snapshot).await
    }

    /// Apply a batch of heat emissions in a single
    /// `announce_capabilities` round-trip. Each update is one of:
    /// - `Some(rate)`: replace this chain's `heat:` tag with
    ///   `heat:<hex>=<clamped rate>`.
    /// - `None`: withdraw every `heat:` annotation for this chain.
    ///
    /// Used by `gravity_tick` to coalesce per-chain emissions. The
    /// previous single-shot per-chain `announce_heat` loop rebroadcast
    /// the full capability set N times per tick — O(n_chains² × n_tags)
    /// wire work on a busy node. This batch path mutates the snapshot
    /// once and rebroadcasts once.
    ///
    /// Non-finite rates skip silently (with a trace log).
    #[cfg(feature = "dataforts")]
    pub async fn announce_heat_batch(
        &self,
        updates: &[(u64, Option<f64>)],
    ) -> Result<(), AdapterError> {
        if updates.is_empty() {
            return Ok(());
        }
        let mut snapshot = self.user_caps_snapshot();
        for &(origin_hash, rate_opt) in updates {
            let replacement = match rate_opt {
                Some(rate) if rate.is_finite() => {
                    let hex = Self::chain_hex(origin_hash);
                    let clamped = rate.clamp(0.0, 1.0);
                    Tag::parse(&format!("heat:{hex}={clamped:.2}")).ok()
                }
                Some(_) => {
                    tracing::trace!(
                        origin_hash = origin_hash,
                        "heat: non-finite rate skipped in batch"
                    );
                    continue;
                }
                None => None,
            };
            Self::replace_heat_tags(&mut snapshot, origin_hash, replacement);
        }
        self.announce_capabilities(snapshot).await
    }
}

#[cfg(feature = "dataforts")]
#[async_trait::async_trait]
impl super::dataforts::HeatSink for MeshNode {
    async fn announce_heat(&self, origin_hash: u64, rate: f64) -> Result<(), AdapterError> {
        MeshNode::announce_heat(self, origin_hash, rate).await
    }

    async fn withdraw_heat(&self, origin_hash: u64) -> Result<(), AdapterError> {
        MeshNode::withdraw_heat(self, origin_hash).await
    }

    async fn announce_heat_batch(
        &self,
        updates: &[(u64, Option<f64>)],
    ) -> Result<(), AdapterError> {
        MeshNode::announce_heat_batch(self, updates).await
    }
}

#[cfg(feature = "dataforts")]
impl MeshNode {
    /// Advertise the `heat:blob:<hex64>=<rate>` reserved tag for
    /// chunk `hash`. `rate` is clamped to `[0.0, 1.0]` to match
    /// the chain-heat wire shape. PR-5j-c — operators wire this
    /// via the [`BlobHeatSink`](super::dataforts::BlobHeatSink)
    /// impl below; the [`MeshBlobAdapter::tick_blob_heat`](super::dataforts::MeshBlobAdapter::tick_blob_heat)
    /// loop is the driver.
    pub async fn announce_blob_heat(&self, hash: [u8; 32], rate: f64) -> Result<(), AdapterError> {
        let clamped = if rate.is_finite() {
            rate.clamp(0.0, 1.0)
        } else {
            return Err(AdapterError::Fatal(
                "blob heat rate must be finite".to_string(),
            ));
        };
        let hex = Self::blob_hex(&hash);
        let replacement = Tag::parse(&format!("heat:blob:{hex}={clamped:.2}")).ok();
        let mut snapshot = self.user_caps_snapshot();
        Self::replace_blob_heat_tags(&mut snapshot, &hash, replacement);
        self.announce_capabilities(snapshot).await
    }

    /// Withdraw every `heat:blob:<hex>=*` tag for `hash` and
    /// re-broadcast. Peers drop the blob-heat annotation.
    pub async fn withdraw_blob_heat(&self, hash: [u8; 32]) -> Result<(), AdapterError> {
        let mut snapshot = self.user_caps_snapshot();
        Self::replace_blob_heat_tags(&mut snapshot, &hash, None);
        self.announce_capabilities(snapshot).await
    }

    /// Apply a batch of blob-heat emissions in a single
    /// `announce_capabilities` round-trip. Each update is either
    /// `Some(rate)` (replace this hash's `heat:blob:` tag) or
    /// `None` (withdraw every blob-heat annotation for the hash).
    /// Coalescing matches the chain-heat batch path so a busy
    /// tick doesn't spawn N rebroadcasts.
    pub async fn announce_blob_heat_batch(
        &self,
        updates: &[([u8; 32], Option<f64>)],
    ) -> Result<(), AdapterError> {
        if updates.is_empty() {
            return Ok(());
        }
        let mut snapshot = self.user_caps_snapshot();
        for (hash, rate_opt) in updates {
            let replacement = match rate_opt {
                Some(rate) if rate.is_finite() => {
                    let clamped = rate.clamp(0.0, 1.0);
                    let hex = Self::blob_hex(hash);
                    Tag::parse(&format!("heat:blob:{hex}={clamped:.2}")).ok()
                }
                Some(_) => {
                    tracing::trace!(
                        hash = ?hash,
                        "blob heat: non-finite rate skipped in batch"
                    );
                    continue;
                }
                None => None,
            };
            Self::replace_blob_heat_tags(&mut snapshot, hash, replacement);
        }
        self.announce_capabilities(snapshot).await
    }
}

#[cfg(feature = "dataforts")]
#[async_trait::async_trait]
impl super::dataforts::BlobHeatSink for MeshNode {
    async fn announce_blob_heat(&self, hash: [u8; 32], rate: f64) -> Result<(), AdapterError> {
        MeshNode::announce_blob_heat(self, hash, rate).await
    }

    async fn withdraw_blob_heat(&self, hash: [u8; 32]) -> Result<(), AdapterError> {
        MeshNode::withdraw_blob_heat(self, hash).await
    }

    async fn announce_blob_heat_batch(
        &self,
        updates: &[([u8; 32], Option<f64>)],
    ) -> Result<(), AdapterError> {
        MeshNode::announce_blob_heat_batch(self, updates).await
    }
}

#[cfg(all(feature = "dataforts", feature = "cortex"))]
impl MeshNode {
    /// Send an overflow push nudge to `target_node_id`. The
    /// chunk bytes themselves don't ride this RPC — the
    /// nudge tells the receiver to open the chunk channel
    /// against its local Redex with replication armed; the
    /// existing per-chunk replication runtime pulls the
    /// bytes from any holder advertising `causal:<hash>`
    /// (typically this node, since we're shedding it).
    ///
    /// `Ok(OverflowPushAck::Accepted)` means the receiver
    /// accepted + opened the chunk channel. The sender still
    /// has to observe the durability watermark (the target's
    /// `causal:<hash>` advertisement) before deleting the
    /// local copy — that's the safe-delete gate. Per the
    /// overflow plan, this two-phase pattern lets a failed
    /// open on the receive side (network blip during chunk
    /// pull) keep the bytes alive on the sender.
    ///
    /// Maps non-`Ok` results to typed [`BlobError`] so the
    /// controller's `push_errors` counter bumps uniformly.
    /// See [`super::dataforts::blob::overflow::OverflowPushAck`]
    /// for the variant breakdown.
    ///
    /// [`BlobError`]: super::dataforts::blob::BlobError
    pub async fn send_overflow_push(
        self: &Arc<Self>,
        target_node_id: u64,
        blob_hash: [u8; 32],
        size_bytes: u64,
    ) -> Result<super::dataforts::blob::overflow::OverflowPushAck, super::dataforts::blob::BlobError>
    {
        use super::dataforts::blob::overflow::{
            OverflowPush, OverflowPushAck, OVERFLOW_PUSH_SERVICE,
        };
        use super::dataforts::blob::BlobError;

        let request = OverflowPush {
            blob_hash,
            size_bytes,
            sender_node_id: self.node_id(),
        };
        let body = postcard::to_allocvec(&request)
            .map_err(|e| BlobError::Backend(format!("overflow push: encode failed: {e}")))?;
        let reply = self
            .call(
                target_node_id,
                OVERFLOW_PUSH_SERVICE,
                bytes::Bytes::from(body),
                super::mesh_rpc::CallOptions::default(),
            )
            .await
            .map_err(|e| BlobError::Backend(format!("overflow push: RPC failed: {e}")))?;
        let ack: OverflowPushAck = postcard::from_bytes(&reply.body)
            .map_err(|e| BlobError::Backend(format!("overflow push: decode ack failed: {e}")))?;
        Ok(ack)
    }

    /// Register the receive-side overflow-push handler on
    /// this node. The handler reads live local caps + the
    /// capability index on each request, runs admission,
    /// and on Admit opens the chunk channel against
    /// `adapter` via [`super::dataforts::blob::adapter::BlobAdapter::prefetch`].
    ///
    /// Returns the [`super::mesh_rpc::ServeHandle`] the
    /// operator drops to deregister the handler. Multiple
    /// calls on the same node would conflict on the service
    /// name; the second call returns
    /// [`super::mesh_rpc::ServeError::AlreadyServing`].
    pub fn serve_overflow_push(
        self: &Arc<Self>,
        adapter: Arc<super::dataforts::blob::MeshBlobAdapter>,
    ) -> Result<super::mesh_rpc::ServeHandle, super::mesh_rpc::ServeError> {
        use super::dataforts::blob::overflow::{OverflowPushHandler, OVERFLOW_PUSH_SERVICE};
        let handler = Arc::new(OverflowPushHandler::new(Arc::clone(self), adapter));
        self.serve_rpc(OVERFLOW_PUSH_SERVICE, handler)
    }

    /// Rebroadcast the local capability set with the
    /// `dataforts.blob.overflow` tag set to match `adapter`'s
    /// current `overflow_enabled()` state. Convenience for
    /// operators who flip [`super::dataforts::blob::MeshBlobAdapter::set_overflow_enabled`]
    /// at runtime: the boolean lives on the adapter, but the
    /// capability index reads from this node's announced caps,
    /// so peers only observe the change after the next
    /// announce. Without this helper, every toggle path needs a
    /// matching `announce_capabilities` call — easy to forget,
    /// and the symptom (sender keeps round-tripping pushes that
    /// reject `SenderNotOverflowing`) is non-obvious.
    ///
    /// Snapshots the current user caps, sets / clears the
    /// presence tag based on `adapter.overflow_enabled()`, and
    /// announces the updated set. Returns the
    /// [`AdapterError`] from the inner `announce_capabilities`
    /// if the announce fails (rate-limited, transport down,
    /// etc.).
    pub async fn announce_blob_overflow_state(
        &self,
        adapter: &super::dataforts::blob::MeshBlobAdapter,
    ) -> Result<(), super::AdapterError> {
        use super::behavior::{BlobCapability, Tag, TaxonomyAxis};
        let mut caps = self.user_caps_snapshot();
        let enabled = adapter.overflow_enabled();
        let present = BlobCapability::from_capability_set(&caps).overflow_enabled;
        if enabled == present {
            // Snapshot already matches the adapter's runtime
            // state — nothing to broadcast. Still re-announce
            // to push any caller-supplied caps that may have
            // landed via a different path; cheap (rate-limited
            // upstream).
            return self.announce_capabilities(caps).await;
        }
        let target = Tag::AxisPresent {
            axis: TaxonomyAxis::Dataforts,
            key: "blob.overflow".to_string(),
        };
        if enabled {
            caps.tags.insert(target);
        } else {
            caps.tags.remove(&target);
        }
        self.announce_capabilities(caps).await
    }
}

#[cfg(feature = "dataforts")]
impl MeshNode {
    /// Install the blob-transfer engine over `adapter` (FairScheduler
    /// transport plan). After this, the node serves on-demand chunk
    /// fetches (the `SUBPROTOCOL_BLOB_TRANSFER` control branch + the
    /// transfer-stream data divert route to the engine) and can issue
    /// them via [`Self::transfer_fetch_chunk`]. Idempotent — re-install
    /// replaces the engine.
    ///
    /// Returns the installed engine handle — the same one stored on the
    /// node — so callers (e.g. the `blob.transfers` RPC install) can serve
    /// introspection over the exact registry that's doing the fetches.
    pub fn serve_blob_transfer(
        self: &Arc<Self>,
        adapter: Arc<super::dataforts::blob::MeshBlobAdapter>,
    ) -> Arc<super::dataforts::blob::transfer::BlobTransferEngine> {
        let engine = Arc::new(super::dataforts::blob::transfer::BlobTransferEngine::new(
            self, adapter,
        ));
        *self.blob_transfer_engine.write() = Some(engine.clone());
        engine
    }

    /// Fetch the chunk addressed by `hash` from `holder` over a
    /// reliable, scheduled transfer stream — bytes move over the
    /// FairScheduler-managed stream transport, not RedEX replication or
    /// nRPC. Returns the BLAKE3-verified bytes, or
    /// [`BlobError::NotFound`] on a holder miss / timeout (so the caller
    /// can fail over to another advertised holder).
    ///
    /// [`BlobError`]: super::dataforts::blob::BlobError
    /// [`BlobError::NotFound`]: super::dataforts::blob::BlobError::NotFound
    pub async fn transfer_fetch_chunk(
        self: &Arc<Self>,
        holder: u64,
        hash: [u8; 32],
    ) -> Result<bytes::Bytes, super::dataforts::blob::BlobError> {
        use super::dataforts::blob::transfer::{next_transfer_stream_id, TransferControl};
        use super::dataforts::blob::BlobError;

        let engine = self.blob_transfer_engine.read().clone().ok_or_else(|| {
            BlobError::Backend("blob transfer: engine not installed (serve_blob_transfer?)".into())
        })?;
        let stream_id = next_transfer_stream_id();
        let (tx, rx) = tokio::sync::oneshot::channel();
        engine.register_pending(stream_id, holder, hash, tx);

        // Open the receive stream RELIABLE up front so it tracks SACK and
        // NACKs lost sequences. The holder sends RELIABLE data; the
        // requester must mirror that reliability to recover drops —
        // otherwise the receive stream (auto-created on first packet, or
        // by the control send below) defaults to fire-and-forget and
        // never asks for a retransmit. Receiver-only, so no scheduled
        // flag / fairness weight is needed.
        let _ = self.open_stream(
            holder,
            stream_id,
            StreamConfig::new().with_reliability(super::Reliability::Reliable),
        );

        if let Err(e) = self
            .send_transfer_control(holder, stream_id, &TransferControl::Request { hash })
            .await
        {
            engine.cancel_pending(stream_id);
            return Err(BlobError::Backend(format!(
                "blob transfer: send request failed: {e}"
            )));
        }

        match tokio::time::timeout(std::time::Duration::from_secs(30), rx).await {
            Ok(Ok(result)) => result,
            Ok(Err(_canceled)) => {
                engine.cancel_pending(stream_id);
                Err(BlobError::Backend(
                    "blob transfer: engine dropped the reply".into(),
                ))
            }
            Err(_elapsed) => {
                engine.cancel_pending(stream_id);
                Err(BlobError::NotFound(format!(
                    "blob transfer: timed out fetching mesh://{}",
                    Self::blob_hex(&hash)
                )))
            }
        }
    }

    /// Fetch the chunk addressed by `hash` from whichever connected
    /// peer holds it, without the caller naming a holder. Probes peers
    /// in turn over the transfer transport: a peer that lacks the chunk
    /// replies `NotFound` promptly (so misses are cheap), and the first
    /// peer that serves the BLAKE3-verified bytes wins. Returns
    /// [`BlobError::NotFound`] if no connected peer has it (the caller
    /// may then fall back to its own backend or fail the read).
    ///
    /// This is the usable "fetch by content hash" entry point that
    /// [`Self::transfer_fetch_chunk`] (which requires a known holder)
    /// can't be on its own.
    ///
    /// **Discovery model (deliberate).** v1 probes connected peers
    /// directly rather than consulting the capability fold for
    /// `causal:<hash>` advertisers. The per-chunk `causal:<hex64>` tag
    /// is a single-datagram advertisement that caps at ~15-20
    /// chunks/node, so it does not scale as a per-chunk holder index —
    /// which is exactly why the directory transfer
    /// ([`super::dataforts::dir`]) pulls from a *known* source instead.
    /// Probing sidesteps the ceiling entirely: the holder's prompt
    /// `NotFound` is the membership test. A future optimization can use
    /// a node-level "serves blobs" capability (one tag, no ceiling) or a
    /// dedicated zero-byte probe frame to ORDER / prune candidates and
    /// to stay robust against a silent peer; today each probe is bounded
    /// by [`DISCOVERY_PROBE_TIMEOUT`] so one unresponsive peer can't
    /// stall the whole search.
    ///
    /// [`BlobError::NotFound`]: super::dataforts::blob::BlobError::NotFound
    /// [`DISCOVERY_PROBE_TIMEOUT`]: Self::transfer_fetch_chunk_discovered
    pub async fn transfer_fetch_chunk_discovered(
        self: &Arc<Self>,
        hash: [u8; 32],
    ) -> Result<bytes::Bytes, super::dataforts::blob::BlobError> {
        use super::dataforts::blob::BlobError;

        // Generous enough for a max-chunk (≤4 MiB) transfer from a
        // healthy holder, tight enough that a silent peer only costs
        // this once before the search moves on. A miss returns its
        // `NotFound` long before this fires.
        const DISCOVERY_PROBE_TIMEOUT: Duration = Duration::from_secs(10);

        let candidates: Vec<u64> = self.peers.iter().map(|e| *e.key()).collect();
        if candidates.is_empty() {
            return Err(BlobError::NotFound(format!(
                "blob transfer: no connected peers to discover mesh://{}",
                Self::blob_hex(&hash)
            )));
        }
        for peer in candidates {
            match tokio::time::timeout(
                DISCOVERY_PROBE_TIMEOUT,
                self.transfer_fetch_chunk(peer, hash),
            )
            .await
            {
                // First holder to serve the verified bytes wins.
                Ok(Ok(bytes)) => return Ok(bytes),
                // Peer doesn't have it / transient error / went silent —
                // try the next candidate.
                Ok(Err(_)) | Err(_) => continue,
            }
        }
        Err(BlobError::NotFound(format!(
            "blob transfer: no connected peer served mesh://{}",
            Self::blob_hex(&hash)
        )))
    }

    /// Send a blob-transfer control packet (subprotocol-tagged, tiny)
    /// to `peer` on `stream_id`. Goes straight to the socket — control
    /// is a single small packet; reliability is the requester's
    /// timeout-and-retry, not per-packet retransmit.
    async fn send_transfer_control(
        &self,
        peer: u64,
        stream_id: u64,
        control: &super::dataforts::blob::transfer::TransferControl,
    ) -> Result<(), super::AdapterError> {
        let (dest_addr, session) = match self.peers.get(&peer) {
            Some(p) => (p.value().addr, p.value().session.clone()),
            None => {
                return Err(super::AdapterError::Connection(format!(
                    "transfer control: no session for {peer:#x}"
                )))
            }
        };
        let bytes = bytes::Bytes::from(postcard::to_allocvec(control).map_err(|e| {
            super::AdapterError::Connection(format!("transfer control: encode failed: {e}"))
        })?);
        let pool = session.thread_local_pool();
        let mut builder = pool.get();
        let seq = session.get_or_create_stream(stream_id).next_tx_seq();
        let events = [bytes];
        let packet = builder.build_subprotocol(
            stream_id,
            seq,
            &events,
            PacketFlags::RELIABLE,
            super::dataforts::blob::SUBPROTOCOL_BLOB_TRANSFER,
        );
        self.socket.send_to(&packet, dest_addr).await.map_err(|e| {
            super::AdapterError::Connection(format!("transfer control: send failed: {e}"))
        })?;
        Ok(())
    }
}

#[cfg(feature = "net")]
impl MeshNode {
    /// Install (or replace) the `SUBPROTOCOL_REDEX` inbound
    /// router. Used by `Redex` to register a per-node router
    /// that owns the per-channel runtime registry; the mesh
    /// dispatch hot-path consults this router on every inbound
    /// `SUBPROTOCOL_REDEX` frame.
    ///
    /// Passing `None` un-installs the router — every subsequent
    /// inbound replication frame is dropped silently until a new
    /// router is installed.
    #[cfg(feature = "redex")]
    pub fn set_replication_inbound_router(
        &self,
        router: Option<Arc<dyn super::redex::ReplicationInboundRouter>>,
    ) {
        *self.replication_inbound_router.write() = router;
    }

    /// Install (or replace) the `SUBPROTOCOL_MESHDB` inbound
    /// router. The MeshDB transport installs one of these to
    /// receive federated-query traffic — both inbound requests
    /// (routed to the server-side query handler) and inbound
    /// responses (routed to the matching in-flight caller).
    ///
    /// Passing `None` un-installs the router — subsequent
    /// inbound MeshDB frames are dropped silently until a new
    /// router is installed.
    ///
    /// Idempotent — re-installing replaces the previous handle.
    /// Hot-path cost is one `parking_lot::RwLock` read per
    /// inbound `SUBPROTOCOL_MESHDB` frame.
    #[cfg(feature = "meshdb")]
    pub fn set_meshdb_inbound_router(
        &self,
        router: Option<Arc<dyn super::behavior::meshdb::MeshDbInboundRouter>>,
    ) {
        *self.meshdb_inbound_router.write() = router;
    }

    /// True iff a MeshDB inbound router is currently installed.
    /// Useful for tests and the operator surface to confirm the
    /// install landed.
    #[cfg(feature = "meshdb")]
    pub fn has_meshdb_inbound_router(&self) -> bool {
        self.meshdb_inbound_router.read().is_some()
    }

    /// Install (or uninstall) the fold-framework channel router.
    /// Absent router = fold packets dropped silently.
    /// Idempotent; re-installing replaces the previous handle.
    pub fn set_fold_router(
        &self,
        router: Option<Arc<dyn super::behavior::fold::FoldChannelRouter>>,
    ) {
        *self.fold_router.write() = router;
    }

    /// True iff a fold-framework channel router is currently
    /// installed. Useful for tests and the operator surface to
    /// confirm the install landed.
    pub fn has_fold_router(&self) -> bool {
        self.fold_router.read().is_some()
    }

    /// Aggregated [`super::behavior::fold::FoldStats`] for every
    /// fold the installed router addresses. The
    /// `net-mesh fold list` CLI command and the Deck FOLDS panel
    /// call this once per scrape tick. Returns an empty `Vec`
    /// when no router is installed.
    pub fn fold_stats(&self) -> Vec<super::behavior::fold::FoldStats> {
        let guard = self.fold_router.read();
        let Some(router) = guard.as_ref() else {
            return Vec::new();
        };
        router.stats()
    }

    /// Install (or uninstall) the greedy-LRU observer. `Redex`
    /// calls this from
    /// [`Redex::enable_greedy_dataforts`](super::redex::Redex)
    /// to wire the inbound dispatch fanout. `None` uninstalls;
    /// subsequent standard-event packets fall through the
    /// observer hook untouched.
    ///
    /// Idempotent — re-installing replaces the previous handle.
    /// Hot-path cost is unchanged when called with the same Arc.
    #[cfg(feature = "dataforts")]
    pub fn set_greedy_observer(&self, observer: Option<Arc<dyn super::dataforts::GreedyObserver>>) {
        *self.greedy_observer.write() = observer;
    }

    /// True iff a greedy observer is currently installed. Useful
    /// for tests and for the operator surface to confirm the
    /// install landed.
    #[cfg(feature = "dataforts")]
    pub fn has_greedy_observer(&self) -> bool {
        self.greedy_observer.read().is_some()
    }

    /// Return every node currently advertising any `causal:<hex>*`
    /// variant for `origin_hash`. Includes this node when self-
    /// indexed. Sorted by ascending RTT from this node where the
    /// proximity graph has measurements, with self at the front
    /// and unmeasured peers (no recent ping) at the back; among
    /// equally-measured peers, ties broken by ascending NodeId.
    ///
    /// Reads the capability fold directly; no broadcast.
    pub fn find_chain_holders(&self, origin_hash: u64) -> Vec<u64> {
        let hex = Self::chain_hex(origin_hash);
        let mut holders: Vec<u64> = self.capability_fold.with_state(|state| {
            let mut seen: std::collections::HashSet<u64> = std::collections::HashSet::new();
            for entry in state.entries.values() {
                if seen.contains(&entry.node_id) {
                    continue;
                }
                if entry
                    .payload
                    .tags
                    .iter()
                    .any(|t| Self::is_causal_for_str(t, &hex))
                {
                    seen.insert(entry.node_id);
                }
            }
            seen.into_iter().collect::<Vec<u64>>()
        });

        // Proximity sort: self first (RTT == 0), then peers with
        // measured RTT in ascending order, then unmeasured peers,
        // ties broken by lex NodeId. Mirrors the
        // `REDEX_DISTRIBUTED_PLAN.md` §4 `elect()` ordering.
        let self_id = self.node_id;
        let proximity = self.proximity_graph.clone();
        let rtt_of = |node: u64| -> Option<std::time::Duration> {
            if node == self_id {
                Some(std::time::Duration::ZERO)
            } else {
                let graph_id = node_id_to_graph_id(node);
                proximity.nearest_rtt(|n| n.node_id == graph_id)
            }
        };
        holders.sort_by(|&a, &b| {
            let rtt_a = rtt_of(a);
            let rtt_b = rtt_of(b);
            match (rtt_a, rtt_b) {
                (Some(da), Some(db)) => match da.cmp(&db) {
                    std::cmp::Ordering::Equal => a.cmp(&b),
                    other => other,
                },
                (Some(_), None) => std::cmp::Ordering::Less,
                (None, Some(_)) => std::cmp::Ordering::Greater,
                (None, None) => a.cmp(&b),
            }
        });
        holders
    }

    /// Query the capability fold. Returns node ids (including our
    /// own `node_id`) whose latest announcement matches `filter`.
    /// Routes through `capability_bridge::find_nodes_matching` so
    /// post-query predicates (memory, vram, GPU) execute in-memory
    /// alongside the fold's tag-based intersection.
    pub fn find_nodes_by_filter(&self, filter: &CapabilityFilter) -> Vec<u64> {
        super::behavior::fold::capability_bridge::find_nodes_matching(&self.capability_fold, filter)
    }

    /// Scoped variant of [`Self::find_nodes_by_filter`]. Filters
    /// candidates through `scope` (derived from each peer's
    /// `scope:*` reserved tags) on top of the capability filter.
    /// `SubnetLocal` peers and the [`ScopeFilter::SameSubnet`]
    /// filter resolve same-subnet membership against
    /// `peer_subnets`.
    ///
    /// **Warm-up rule.** When a peer's subnet is unknown:
    /// - **With** a `local_subnet_policy`, the candidate is
    ///   admitted (a fresh peer's announcement may not have
    ///   landed yet — the policy will resolve it on receipt).
    /// - **Without** a `local_subnet_policy`, `peer_subnets`
    ///   stays permanently empty (the dispatch handler only
    ///   writes it when a policy is installed), so "unknown"
    ///   means "will never resolve" — admitting unknowns there
    ///   leaks every peer through `SameSubnet`. The candidate
    ///   is excluded.
    pub fn find_nodes_by_filter_scoped(
        &self,
        filter: &CapabilityFilter,
        scope: &ScopeFilter<'_>,
    ) -> Vec<u64> {
        let my_subnet = self.local_subnet;
        let peer_subnets = self.peer_subnets.clone();
        let local_node_id = self.node_id;
        // See doc-comment: without a policy, an unresolvable
        // "unknown" cannot be admitted as same-subnet.
        let policy_installed = self.local_subnet_policy.is_some();
        super::behavior::fold::capability_bridge::find_nodes_matching_scoped(
            &self.capability_fold,
            filter,
            scope,
            |nid| {
                if nid == local_node_id {
                    return true;
                }
                match peer_subnets.get(&nid).map(|e| *e.value()) {
                    Some(s) => s == my_subnet,
                    None => policy_installed,
                }
            },
        )
    }

    /// Read a peer's most recently advertised public reflex
    /// `SocketAddr` from the capability index. `None` before the
    /// peer has sent a stage-2 announcement, or when the peer was
    /// compiled without `nat-traversal`.
    ///
    /// Stage 3 (rendezvous) reads this field to resolve the punch
    /// target's public address. Exposed for observability and for
    /// tests that want to verify capability-announcement propagation
    /// of the reflex field.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub fn peer_reflex_addr(&self, peer_node_id: u64) -> Option<std::net::SocketAddr> {
        super::behavior::fold::reflex_addr_for(&self.capability_fold, peer_node_id)
    }

    /// Read a peer's most recently advertised NAT classification
    /// from the capability index. Parses the `nat:*` tag on the
    /// peer's announcement. Returns `NatClass::Unknown` when the
    /// peer has not indexed (we've never received an announcement),
    /// or the announcement carried no `nat:*` tag (peer was
    /// compiled without `nat-traversal`, or hasn't classified yet).
    ///
    /// Consumed by the pair-type matrix (plan §3) — `connect_direct`
    /// reads this to decide whether to attempt a punch or
    /// short-circuit to the routed path.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub fn peer_nat_class(&self, peer_node_id: u64) -> super::traversal::classify::NatClass {
        use super::traversal::classify::NatClass;
        self.capability_fold.with_state(|state| {
            let Some(keys) = state.by_node.get(&peer_node_id) else {
                return NatClass::Unknown;
            };
            for key in keys {
                let Some(entry) = state.entries.get(key) else {
                    continue;
                };
                for tag in entry.payload.tags.iter() {
                    if let Some(class) = NatClass::from_tag(tag) {
                        return class;
                    }
                }
            }
            NatClass::Unknown
        })
    }

    /// Cumulative traversal counters — punch attempts, successes,
    /// and relay fallbacks. Returns a consistent point-in-time
    /// snapshot.
    ///
    /// See [`super::traversal::TraversalStatsSnapshot`] for the
    /// field semantics. The base counters are monotonic and never
    /// reset, so deltas between snapshots are safe — with two
    /// exceptions: `punches_failed` is DERIVED at snapshot time
    /// (`attempted - succeeded`) and can decrease when an in-flight
    /// punch lands, and `port_mapping_renewals` resets to zero on
    /// each fresh mapping install. Compute rates from the base
    /// counters, not the derived/resettable fields.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub fn traversal_stats(&self) -> super::traversal::TraversalStatsSnapshot {
        self.traversal_stats.snapshot()
    }

    /// Whether the session to `peer_id` reachable at `addr` is
    /// **relay-routed** rather than direct. Signal: `addr_to_node[addr]`
    /// — the node owning that transport address — is someone *other
    /// than* `peer_id` (a relay), or the address isn't registered at
    /// all. A direct session's address is owned by the peer itself. An
    /// unknown address counts as relayed — the conservative default
    /// that makes the upgrade loop re-examine it and coordinator
    /// selection exclude it. Single source of truth for the
    /// relayed-vs-direct test shared by [`Self::select_punch_coordinator`],
    /// [`Self::attempt_direct_upgrade`], and
    /// [`Self::upgrade_is_loop_candidate`], so the three can't drift
    /// apart on the default or the ownership rule.
    #[cfg(feature = "nat-traversal")]
    fn is_relayed_peer(&self, peer_id: u64, addr: &SocketAddr) -> bool {
        self.addr_to_node
            .get(addr)
            .map(|owner| *owner != peer_id)
            .unwrap_or(true)
    }

    /// Pick a rendezvous coordinator for a punch to `target`, without
    /// the caller having to name one (`NAT_TRAVERSAL_V2_PLAN.md`
    /// decision 5). Four tiers, graceful degradation:
    ///
    /// 1. **Routing next-hop.** For a relay-reached target, the peer
    ///    currently forwarding to it demonstrably has live sessions
    ///    with both ends — the highest-probability coordinator, and no
    ///    discovery needed.
    /// 2. **`relay-capable` direct peer.** A mutual direct peer that
    ///    advertised `RELAY_CAPABLE_TAG`. Picked at random from the
    ///    tier's candidates (not lowest-`node_id`): a deterministic
    ///    pick would funnel every requester's punches through one peer,
    ///    making it a mesh-wide coordinator hotspot and single point of
    ///    failure.
    /// 3. **Any direct peer.** Best-effort; the chosen peer may lack a
    ///    session with the target, in which case its coordinator
    ///    rejects with `NoSessionWithTarget` and the caller falls back.
    /// 4. **None.** No candidate — the caller surfaces
    ///    `RendezvousNoRelay` and stays on the routed path.
    ///
    /// Never fails a connection: a `None` here only means the punch
    /// optimization isn't attempted, never that the peer is
    /// unreachable.
    #[cfg(feature = "nat-traversal")]
    pub fn select_punch_coordinator(&self, target: u64) -> Option<u64> {
        // Tier 1: the relay currently forwarding to the target. Only
        // yields a distinct node for a relay-reached target — for a
        // direct peer the next hop is the target itself (excluded).
        if let Some(next_hop) = self.router.routing_table().lookup(target) {
            if let Some(nid) = self.addr_to_node.get(&next_hop).map(|e| *e.value()) {
                if nid != target && nid != self.node_id && self.peers.contains_key(&nid) {
                    return Some(nid);
                }
            }
        }

        // Tiers 2 & 3: collect the direct mutual peers (excluding self
        // and the target), then split into relay-capable and any.
        // Collected (not min-reduced) so the pick can be spread across
        // the tier's candidates — see `spread_pick`.
        let mut any: Vec<u64> = Vec::new();
        for entry in self.peers.iter() {
            let nid = *entry.key();
            if nid == target || nid == self.node_id {
                continue;
            }
            // Only genuinely DIRECT peers qualify (cubic P2): the peer
            // table also holds relay-routed sessions whose `addr` is the
            // relay's. A routed "coordinator" is doubly wrong — our
            // PunchRequest would land at the relay's address (whose
            // session can't decrypt it), and even if it arrived, the
            // coordinator's anti-reflection guard would reject the
            // routed pair anyway.
            if self.is_relayed_peer(nid, &entry.value().addr) {
                continue;
            }
            any.push(nid);
        }
        // Relay-capable subset, resolved in ONE fold lock for the whole
        // candidate batch — the prior code took the fold lock and
        // allocated a tag `Vec` for every candidate just to test one tag.
        let relay_capable_set = super::behavior::fold::nodes_with_capability_tag(
            &self.capability_fold,
            &any,
            super::behavior::capability::RELAY_CAPABLE_TAG,
        );

        // Tier 2 preferred, tier 3 fallback, else tier 4 (None). Spread
        // the pick within the chosen tier so load doesn't concentrate.
        if !relay_capable_set.is_empty() {
            let relay_capable: Vec<u64> = any
                .iter()
                .copied()
                .filter(|nid| relay_capable_set.contains(nid))
                .collect();
            Self::spread_pick(&relay_capable)
        } else {
            Self::spread_pick(&any)
        }
    }

    /// Pick one node id from `pool` at random, spread across calls so
    /// rendezvous-coordination load doesn't concentrate on one peer.
    /// Uses a freshly-seeded [`RandomState`] hash for per-call entropy
    /// (the same OS-entropy trick as `adapter::dedup_state`) — cheap,
    /// dependency-free, and varies both across requesters and across a
    /// single requester's retries, so no node becomes a coordinator
    /// hotspot / SPOF. Returns `None` only for an empty pool.
    ///
    /// [`RandomState`]: std::collections::hash_map::RandomState
    #[cfg(feature = "nat-traversal")]
    fn spread_pick(pool: &[u64]) -> Option<u64> {
        use std::hash::BuildHasher;
        if pool.is_empty() {
            return None;
        }
        let salt = std::collections::hash_map::RandomState::new().hash_one(pool.len() as u64);
        pool.get((salt % pool.len() as u64) as usize).copied()
    }

    /// Like [`Self::connect_direct`], but auto-selects the rendezvous
    /// coordinator via [`Self::select_punch_coordinator`] instead of
    /// taking one from the caller — the ergonomic entry point for
    /// "just give me the best path to this peer."
    ///
    /// - `Direct` pairs don't need a coordinator (the peer is publicly
    ///   reachable), so this delegates straight through.
    /// - `SinglePunch` / `SkipPunch` pairs need one; if no candidate
    ///   exists, returns [`super::traversal::TraversalError::RendezvousNoRelay`]
    ///   — the tier-4 skip. The caller stays on the routed-handshake
    ///   path (connectivity is never at risk; the punch is the
    ///   optimization).
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub async fn connect_direct_auto(
        &self,
        peer_node_id: u64,
        peer_pubkey: &[u8; 32],
    ) -> Result<u64, super::traversal::TraversalError> {
        use super::traversal::classify::{pair_action, PairAction};
        use super::traversal::TraversalError;

        let action = pair_action(self.nat_class(), self.peer_nat_class(peer_node_id));
        match action {
            // Direct pairs ignore the coordinator entirely; pass a
            // sentinel `0` — the Direct arm never reads it.
            PairAction::Direct => self.connect_direct(peer_node_id, peer_pubkey, 0).await,
            PairAction::SinglePunch | PairAction::SkipPunch => {
                match self.select_punch_coordinator(peer_node_id) {
                    Some(coord) => self.connect_direct(peer_node_id, peer_pubkey, coord).await,
                    None => {
                        self.traversal_stats.record_rendezvous_no_relay();
                        Err(TraversalError::RendezvousNoRelay)
                    }
                }
            }
        }
    }

    /// Establish a direct session to `peer_node_id`, using the
    /// pair-type matrix (plan §3) to decide between a direct
    /// handshake, a rendezvous-coordinated single-shot punch, or
    /// a routed-only fallback.
    ///
    /// # Flow
    ///
    /// 1. Read local + remote NAT classifications (self
    ///    `nat_class()` + `peer_nat_class`). Unknown sides are
    ///    handled per the matrix — never treated as "don't attempt"
    ///    (plan decision 8).
    /// 2. Resolve the peer's reflex address from the local
    ///    capability index. Fails with
    ///    [`super::traversal::TraversalError::PeerNotReachable`] if no reflex is
    ///    cached (peer hasn't announced yet).
    /// 3. Apply the matrix:
    ///    - `Direct` → connect via the routing table's
    ///      first-hop; `coordinator` is not consulted and its
    ///      reachability is irrelevant. `relay_fallbacks`
    ///      increments (we didn't attempt a punch).
    ///    - `SkipPunch` → connect via `coordinator` as the
    ///      relay; symmetric pairs have no better option.
    ///      Fails with `PeerNotReachable` if `coordinator`
    ///      isn't a live peer.
    ///    - `SinglePunch` → ask `coordinator` to mediate via
    ///      [`Self::request_punch`]. On successful introduction,
    ///      increment `punches_attempted` + `punches_succeeded`
    ///      and connect to `peer_reflex`. On failure, increment
    ///      `punches_attempted` + `relay_fallbacks` and fall
    ///      back to connecting via the coordinator — the plan's
    ///      framing treats punch-failed as "optimization missed,"
    ///      not a connectivity failure.
    ///
    /// # Scope note
    ///
    /// Stage 3c wires the orchestration + stats end-to-end but
    /// always establishes the session via the routed handshake
    /// through `coordinator` — the framing "traffic rides the
    /// relay until a direct punch upgrades it" matches the plan's
    /// "optimization, not correctness" contract. Stage 3d lands
    /// the keep-alive train + `PunchAck` round-trip, at which
    /// point a successful `SinglePunch` outcome upgrades to a
    /// direct session; failed punches (or matrix-skipped pairs)
    /// continue to resolve on the routed path as they do today.
    ///
    /// Stats are set on the stage-3c semantics already:
    /// `punches_attempted` increments when the matrix picks
    /// `SinglePunch` and the coordinator mediates; stage 3d
    /// refines `punches_succeeded` / `relay_fallbacks` against
    /// the real keep-alive outcome.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub async fn connect_direct(
        &self,
        peer_node_id: u64,
        peer_pubkey: &[u8; 32],
        coordinator: u64,
    ) -> Result<u64, super::traversal::TraversalError> {
        use super::traversal::classify::{pair_action, PairAction};
        use super::traversal::TraversalError;

        // NOTE: `peer_reflex` and `coordinator` are deliberately
        // NOT resolved here. Two separate cubic P1 reviews
        // flagged that eager lookups + `PeerNotReachable` fast-
        // fails at the top broke branches that didn't actually
        // need those inputs — `Direct` doesn't need the
        // coordinator, and `SkipPunch` / `SinglePunch` don't need
        // the peer's reflex (SinglePunch gets it from the
        // coordinator's `PunchIntroduce`; SkipPunch rides the
        // coordinator relay and doesn't probe the peer directly).
        // Both lookups now happen lazily inside the arms that
        // actually consume them.

        let local_class = self.nat_class();
        let remote_class = self.peer_nat_class(peer_node_id);
        let action = pair_action(local_class, remote_class);

        // Resolve `coordinator` into a wire address. Only call
        // from the SkipPunch / SinglePunch arms — `Direct`
        // routes via the routing table (below).
        let coordinator_addr = || {
            self.peer_addrs
                .get(&coordinator)
                .map(|e| *e.value())
                .ok_or(TraversalError::PeerNotReachable)
        };

        // Helper: `true` iff we already have a session with
        // `peer_node_id` whose transport points at `want_addr`.
        // Used by the branches below to decide whether to
        // short-circuit (session is already on the path we want)
        // vs. re-handshake to upgrade (session exists but on the
        // wrong path — typically a relayed session that a fresh
        // direct/punched attempt should replace).
        // Unconditionally short-circuiting on any existing session
        // would leave callers stuck on the relay forever,
        // defeating the optimization.
        let session_matches = |want_addr: std::net::SocketAddr| {
            self.peers
                .get(&peer_node_id)
                .map(|e| e.value().addr == want_addr)
                .unwrap_or(false)
        };

        // Helper: open a session directly to `target_addr` by
        // wrapping msg1 in a routing header and sending straight
        // to the peer. Works for `Direct` (target_addr = peer_reflex)
        // and for post-punch upgrade (same). Uses the dispatch-
        // loop pending_handshakes path via `connect_via`, which
        // avoids recv-loop contention on a post-`start()` node.
        let connect_on_direct_path = |target_addr: std::net::SocketAddr| async move {
            let id = if session_matches(target_addr) {
                peer_node_id
            } else {
                self.connect_via(target_addr, peer_pubkey, peer_node_id)
                    .await
                    .map_err(|e| TraversalError::Transport(e.to_string()))?
            };
            // After a successful direct upgrade (either an
            // already-matching session or a fresh `connect_via`
            // landing), point `addr_to_node` at the upgraded
            // session's wire addr. `connect_via` deliberately does
            // NOT touch `addr_to_node` so that *relayed* sessions
            // keep mapping to the relay's own node_id — but a
            // direct upgrade has a known peer reflex on the wire
            // and should benefit from the dispatch fast path
            // (`addr_to_node.get(&source) → peers.get(nid)`).
            // Without this insert the dispatcher misses on
            // `target_addr` and falls back to a linear
            // `peers.iter().find` per packet for the upgraded
            // session. (#9)
            self.addr_to_node.insert(target_addr, peer_node_id);
            Ok::<u64, TraversalError>(id)
        };

        // Helper: open a relayed session via `coord_addr`. Short-
        // circuits only when an existing session is already on
        // exactly that coordinator's path. An unrelated session
        // (stale, dead, on a different hop) is NOT treated as
        // success — a `contains_key`-based short-circuit here
        // would mask a failed direct attempt behind whatever
        // stale session happened to still be in the peers map,
        // so `connect_direct` would report "success" without
        // actually establishing the intended path. The handshake
        // runs unless we can confirm the existing session is
        // already the one this call was asked to resolve.
        let connect_via_coordinator = |coord_addr: std::net::SocketAddr| async move {
            if session_matches(coord_addr) {
                return Ok(peer_node_id);
            }
            self.connect_via(coord_addr, peer_pubkey, peer_node_id)
                .await
                .map_err(|e| TraversalError::Transport(e.to_string()))
        };

        match action {
            PairAction::Direct => {
                // `Direct` pairs (Open/Open, Open/Cone,
                // Open/Unknown, Unknown/Unknown, etc.) don't
                // need the coordinator — the peer is publicly
                // reachable at its advertised reflex. Send the
                // routed-handshake packet straight to
                // `peer_reflex`; the peer's dispatch loop sees
                // `dest == self` and completes locally. Only
                // when that direct attempt fails do we try the
                // routing table's first-hop as a fallback
                // (pingwave-installed routes, etc.). Always
                // going via the routing table would add an
                // unnecessary relay hop when a direct path is
                // available.
                //
                // Stats note: `record_relay_fallback` fires only
                // when we actually fall back to the routed path
                // — not on entry. A successful direct connect is
                // not a fallback; attributing it as one breaks
                // `TraversalStats.relay_fallbacks`'s documented
                // meaning ("ended up on the routed-
                // handshake path") and makes the counter useless
                // for assessing NAT-traversal effectiveness.
                // `Direct` is the one branch that genuinely
                // needs the peer's reflex — it's the wire target
                // for the direct-handshake attempt. Resolve it
                // lazily here (cubic P1): putting this lookup
                // at the top of the function used to reject
                // `SkipPunch` pairs (which don't need a reflex
                // at all) with `PeerNotReachable`.
                let peer_reflex = self
                    .peer_reflex_addr(peer_node_id)
                    .ok_or(TraversalError::PeerNotReachable)?;

                match connect_on_direct_path(peer_reflex).await {
                    Ok(id) => Ok(id),
                    Err(_) => {
                        // Direct handshake on `peer_reflex` failed.
                        // Run the routing-table fallback
                        // *unconditionally* — cubic P2 flagged
                        // that short-circuiting on "any session
                        // exists" would mask the failed direct
                        // attempt behind a stale / unrelated
                        // session, preventing the upgrade this
                        // API is meant to attempt. If
                        // `connect_routed` itself finds the
                        // existing session is already on a valid
                        // first-hop it'll succeed quickly; if no
                        // route is cached it returns an honest
                        // error the caller can observe.
                        //
                        // Stats ordering (cubic P2):
                        // `record_relay_fallback` only fires
                        // *after* `connect_routed` actually
                        // succeeds. Bumping it before the
                        // fallback runs would overcount — if
                        // the routing-table path also fails,
                        // the call returns Err and the counter
                        // would still have moved, breaking
                        // `relay_fallbacks`'s documented meaning
                        // ("resolutions that stayed on the
                        // routed path").
                        let id = self
                            .connect_routed(peer_pubkey, peer_node_id)
                            .await
                            .map_err(|e| TraversalError::Transport(e.to_string()))?;
                        self.traversal_stats.record_relay_fallback();
                        Ok(id)
                    }
                }
            }
            PairAction::SkipPunch => {
                // Symmetric × Symmetric (and Symmetric ×
                // Unknown). Punch can't land; the coordinator
                // is the only way to relay. Fail fast if the
                // caller's coordinator isn't reachable — there
                // is no viable fallback in this branch.
                //
                // Stats note (cubic P2): `record_relay_fallback`
                // runs only *after* `connect_via_coordinator`
                // actually succeeds. A failed coordinator
                // handshake returns Err without bumping, so
                // `relay_fallbacks` continues to mean "ended
                // up on the routed-handshake path" — not "the
                // matrix picked the routed path but the
                // handshake also failed."
                let coord = coordinator_addr()?;
                let id = connect_via_coordinator(coord).await?;
                self.traversal_stats.record_relay_fallback();
                Ok(id)
            }
            PairAction::SinglePunch => {
                // Punch requires the coordinator for rendezvous
                // mediation. Resolve it here (not eagerly at the
                // top) so Direct-path callers with no active
                // coordinator peer can still succeed.
                let coord = coordinator_addr()?;
                let self_reflex = self.reflex_addr().unwrap_or_else(|| self.local_addr());

                // Install the PunchAck waiter BEFORE firing the
                // request so a fast round-trip can't beat us to
                // the correlation map. Generation-stamped so
                // cleanup paths below only evict our own entry,
                // not a racing concurrent call.
                let (ack_tx, ack_rx) = oneshot::channel();
                let ack_gen = self
                    .next_waiter_gen
                    .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
                // Bind to `coordinator` — the node that will
                // forward the counterpart's ack to us. The
                // dispatch arm requires the session peer to match
                // this id before completing the oneshot.
                self.pending_punch_acks
                    .insert(peer_node_id, (ack_gen, coordinator, ack_tx));

                let punch_outcome = self
                    .request_punch(coordinator, peer_node_id, self_reflex)
                    .await;

                // Stats ordering (cubic P2): `record_punch_attempt`
                // fires only when `request_punch` returns Ok —
                // i.e., the coordinator mediated the introduction,
                // which proves the send succeeded and the intro
                // arrived. Bumping before knowing the outcome
                // would overcount cases where no wire activity
                // actually happened (coordinator unreachable,
                // socket send failed). Similarly, the relay-
                // fallback counters below only fire after the
                // fallback handshake itself lands.
                let intro = match punch_outcome {
                    Ok(intro) => {
                        self.traversal_stats.record_punch_attempt();
                        intro
                    }
                    Err(_) => {
                        // Coordinator mediation failed — no
                        // point waiting for an ack that will
                        // never come. Evict the waiter only if
                        // it's still ours (a concurrent call may
                        // have replaced it; cubic P1). No
                        // `record_punch_attempt` — the wire
                        // punch didn't happen. The relay-
                        // fallback counter is bumped only after
                        // `connect_via_coordinator` actually
                        // succeeds.
                        self.pending_punch_acks
                            .remove_if(&peer_node_id, |_, (g, _, _)| *g == ack_gen);
                        let id = connect_via_coordinator(coord).await?;
                        self.traversal_stats.record_relay_fallback();
                        return Ok(id);
                    }
                };

                // Await the counterpart's PunchAck, forwarded by
                // the coordinator. On success we try a direct
                // handshake to the peer's advertised reflex —
                // that's the whole point of the punch, and
                // without it this code path is a fancy way of
                // doing a relayed connect while lying in stats
                // that a punch happened. On ack-timeout or
                // direct-handshake failure we fall back to relay
                // so the caller still gets a usable session.
                let deadline = self.traversal_config.punch_deadline;
                match tokio::time::timeout(deadline, ack_rx).await {
                    Ok(Ok(_ack)) => {
                        match connect_on_direct_path(intro.peer_reflex).await {
                            Ok(id) => {
                                self.traversal_stats.record_punch_success();
                                Ok(id)
                            }
                            Err(_) => {
                                // Punch opened but direct
                                // handshake failed (NAT rebound
                                // between ack and handshake, or
                                // the peer's socket buffer
                                // filled). Relay fallback — bump
                                // `relay_fallbacks` only after
                                // the coordinator handshake
                                // actually lands.
                                let id = connect_via_coordinator(coord).await?;
                                self.traversal_stats.record_relay_fallback();
                                Ok(id)
                            }
                        }
                    }
                    Ok(Err(_)) => {
                        // Our sender was replaced by a concurrent
                        // call — the map entry is now theirs, do
                        // NOT remove. Fall through to relay on
                        // our side.
                        let id = connect_via_coordinator(coord).await?;
                        self.traversal_stats.record_relay_fallback();
                        Ok(id)
                    }
                    Err(_) => {
                        self.pending_punch_acks
                            .remove_if(&peer_node_id, |_, (g, _, _)| *g == ack_gen);
                        // Ack-wait deadline elapsed: the introduce
                        // arrived but the counterpart's PunchAck never
                        // did — the punch's one timeout for this flow
                        // (the introduce wait resolved Ok, so
                        // `request_punch` didn't count one).
                        self.traversal_stats.record_punch_timeout();
                        let id = connect_via_coordinator(coord).await?;
                        self.traversal_stats.record_relay_fallback();
                        Ok(id)
                    }
                }
            }
        }
    }

    /// Rank peers for a scored requirement. Returns the best-
    /// scoring node's id, or `None` if no peer matches.
    ///
    /// Phase 3b note: scoring runs against a tag-only
    /// [`CapabilitySet`](super::behavior::capability::CapabilitySet)
    /// synthesized from the fold (the fold's
    /// [`CapabilityMembership`](super::behavior::fold::CapabilityMembership)
    /// doesn't carry the full legacy hardware/models projection).
    /// Hardware- and model-based preference weights (memory,
    /// vram, tokens/sec, loaded) read zero, so this method
    /// degrades to "any matching candidate, lex-sorted by
    /// node_id." That's the same shape as the cap-propagation-
    /// race fallback; production has no rich-scoring caller per
    /// the Phase 3b survey.
    pub fn find_best_node(
        &self,
        req: &super::behavior::capability::CapabilityRequirement,
    ) -> Option<u64> {
        let candidates = super::behavior::fold::capability_bridge::find_nodes_matching(
            &self.capability_fold,
            &req.filter,
        );
        Self::best_by_score(&self.capability_fold, candidates, req)
    }

    /// Scoped variant of [`Self::find_best_node`]. See
    /// [`Self::find_nodes_by_filter_scoped`] for the scope
    /// resolution semantics; selection picks the highest-scoring
    /// candidate within the scoped set.
    ///
    /// Phase 3b note: same scoring caveat as
    /// [`Self::find_best_node`] — the fold's
    /// [`CapabilityMembership`](super::behavior::fold::CapabilityMembership)
    /// doesn't carry the legacy hardware/models projection, so
    /// scoring degrades to "any matching candidate, lex-sorted."
    pub fn find_best_node_scoped(
        &self,
        req: &super::behavior::capability::CapabilityRequirement,
        scope: &ScopeFilter<'_>,
    ) -> Option<u64> {
        let candidates = self.find_nodes_by_filter_scoped(&req.filter, scope);
        Self::best_by_score(&self.capability_fold, candidates, req)
    }

    /// Pick the highest-scoring candidate against `req`. Synthesizes
    /// each candidate's [`CapabilitySet`] from the fold exactly once
    /// (sort by score key, lex-tiebreak on `node_id` for stable
    /// output), instead of re-synthesizing twice per
    /// `max_by` comparison.
    fn best_by_score(
        fold: &Arc<super::behavior::fold::Fold<super::behavior::fold::CapabilityFold>>,
        candidates: Vec<u64>,
        req: &super::behavior::capability::CapabilityRequirement,
    ) -> Option<u64> {
        let mut scored: Vec<(u64, f32)> = candidates
            .into_iter()
            .map(|node_id| {
                let caps = super::behavior::fold::capability_bridge::synthesize_capability_set(
                    fold, node_id,
                );
                (node_id, req.score(&caps))
            })
            .collect();
        // Sort by descending score, lex-asc node_id tiebreak —
        // matches `find_nodes_matching`'s sort ordering when scores
        // tie (which they always do today, per the docstring's
        // "scoring degrades to lex-sorted" caveat) so the result
        // is byte-stable across runs.
        scored.sort_by(|(na, sa), (nb, sb)| {
            sb.partial_cmp(sa)
                .unwrap_or(std::cmp::Ordering::Equal)
                .then_with(|| na.cmp(nb))
        });
        scored.into_iter().next().map(|(node_id, _)| node_id)
    }

    /// Shared reference to the capability fold — the canonical
    /// capability-state surface. Used by operator dashboards,
    /// the rendezvous coordinator (reflex lookup), and the
    /// dataforts-blob overflow handler.
    pub fn capability_fold(
        &self,
    ) -> &Arc<super::behavior::fold::Fold<super::behavior::fold::CapabilityFold>> {
        &self.capability_fold
    }

    /// Shared reference to the reservation fold. Always present
    /// (allocated at construction even when the node never
    /// publishes a reservation) so the aggregator surface +
    /// future scheduler callers don't have to discriminate on
    /// presence.
    pub fn reservation_fold(
        &self,
    ) -> &Arc<super::behavior::fold::Fold<super::behavior::fold::ReservationFold>> {
        &self.reservation_fold
    }

    /// Shared reference to the island-topology fold (Thunderdome
    /// gang-claim scheduler). Always present; the scheduler's
    /// match→claim pipeline reads it alongside
    /// [`Self::capability_fold`] for the live numeric-filter step.
    pub fn island_fold(
        &self,
    ) -> &Arc<super::behavior::fold::Fold<super::behavior::fold::IslandTopologyFold>> {
        &self.island_fold
    }

    /// Match islands for a gang job by reading this node's capability +
    /// island folds (Thunderdome §2 steps 1–3). Pure read; returns the
    /// candidate islands in claim order. The node-level entry to the
    /// match→claim pipeline.
    pub fn match_islands(
        &self,
        criteria: &super::behavior::gang::MatchCriteria,
    ) -> Vec<super::behavior::fold::IslandId> {
        let down = self.liveness_down.load();
        super::behavior::gang::match_islands(
            &self.capability_fold,
            &self.island_fold,
            criteria,
            &down,
        )
    }

    /// Replace the set of hosts the gang matcher treats as down. The
    /// runtime feeds this each liveness tick from
    /// `scheduler_bridge::project_liveness(meshos).down` (MeshOS ↔
    /// Scheduler Projection 4); [`Self::match_islands`] then prunes those
    /// hosts so a dead node's islands / capabilities are never offered.
    /// Lock-free swap — safe to call from the liveness / reconcile loop
    /// concurrently with matching.
    pub fn set_liveness_down(
        &self,
        down: std::collections::HashSet<super::behavior::fold::NodeId>,
    ) {
        self.liveness_down.store(Arc::new(down));
    }

    /// SI-6: [`Self::match_islands`] with this node's sensed
    /// readiness for `spec` joined at the same seam as the liveness
    /// gate (sensing plan §6 SI-6): providers sensed explicitly
    /// NotReady for THIS interest are pruned from THIS match only —
    /// never suspended (§4.9) — and sensed-viable providers' islands
    /// lead the claim order in the aggregate's own consumer-local
    /// economics. Unsensed and Unknown hosts are unaffected (absence
    /// of evidence never prunes). Compound AND/gang policy stays
    /// with the caller; re-matching on overlay movement rides
    /// [`Self::subscribe_sensing_overlay_changes`].
    pub fn match_islands_sensed(
        &self,
        criteria: &super::behavior::gang::MatchCriteria,
        spec: &sensing::InterestSpec,
        budget: &sensing::ConsumerLatencyBudget,
        resolved_population: Option<&[u64]>,
    ) -> Vec<super::behavior::fold::IslandId> {
        let sensed = self.sensed_candidates(spec, budget, resolved_population);
        let down = self.liveness_down.load();
        let non_viable: std::collections::HashSet<super::behavior::fold::NodeId> =
            sensed.non_viable.iter().copied().collect();
        super::behavior::gang::match_islands_sensed(
            &self.capability_fold,
            &self.island_fold,
            criteria,
            &down,
            &non_viable,
            &sensed.viable,
        )
    }

    /// SI-6: match with sensed readiness and reserve the first
    /// available island — the sensed order makes the first success
    /// target the SELECTED provider (the aggregate's best-ranked
    /// viable candidate), falling through to the next candidate on
    /// contention exactly like [`Self::claim_island`].
    pub async fn claim_island_sensed(
        &self,
        criteria: &super::behavior::gang::MatchCriteria,
        spec: &sensing::InterestSpec,
        budget: &sensing::ConsumerLatencyBudget,
        resolved_population: Option<&[u64]>,
        until_unix_us: u64,
    ) -> Result<Option<super::behavior::fold::IslandId>, AdapterError> {
        for island in self.match_islands_sensed(criteria, spec, budget, resolved_population) {
            if matches!(
                self.reserve_island(island, until_unix_us).await?,
                super::behavior::gang::ClaimOutcome::Won
            ) {
                return Ok(Some(island));
            }
        }
        Ok(None)
    }

    /// Reserve `island` under this node's identity: apply the
    /// `Reserved` transition to the local reservation fold — this
    /// node's optimistic AP view (locked decision 2) — and broadcast
    /// it to peers. Returns the local CAS outcome (`Won` if the
    /// island was free/unheld in this node's view, `Lost` if already
    /// held). `until_unix_us` is the takeover deadline.
    pub async fn reserve_island(
        &self,
        island: super::behavior::fold::IslandId,
        until_unix_us: u64,
    ) -> Result<super::behavior::gang::ClaimOutcome, AdapterError> {
        self.apply_and_broadcast_reservation(
            island,
            super::behavior::fold::ReservationState::Reserved {
                holder: self.node_id,
                until_unix_us,
            },
        )
        .await
    }

    /// Release `island` this node holds: apply `Free` locally and
    /// broadcast. Returns `Lost` if this node wasn't the holder.
    ///
    /// We gate on holder identity first: a `Free` write to an island
    /// with no local entry would `Insert` and falsely report `Won`
    /// (leaving a spurious `Free` entry), so a non-holder release is
    /// reported `Lost` without touching the fold or the wire (review #5).
    pub async fn release_island(
        &self,
        island: super::behavior::fold::IslandId,
    ) -> Result<super::behavior::gang::ClaimOutcome, AdapterError> {
        use super::behavior::fold::ReservationQuery;
        let held_by_us = self
            .reservation_fold
            .query(ReservationQuery::State(island))
            .first()
            .and_then(|(_, state)| state.holder())
            == Some(self.node_id);
        if !held_by_us {
            return Ok(super::behavior::gang::ClaimOutcome::Lost);
        }
        self.apply_and_broadcast_reservation(island, super::behavior::fold::ReservationState::Free)
            .await
    }

    /// Match islands by `criteria` and reserve the first available, all
    /// under this node's identity — the node-level "schedule a single-
    /// island gang against my own folds" loop (the `Reserved` reject
    /// walks to the next candidate). Returns the claimed island, or
    /// `None` when nothing matched or every match was contended in this
    /// node's view.
    pub async fn claim_island(
        &self,
        criteria: &super::behavior::gang::MatchCriteria,
        until_unix_us: u64,
    ) -> Result<Option<super::behavior::fold::IslandId>, AdapterError> {
        for island in self.match_islands(criteria) {
            if matches!(
                self.reserve_island(island, until_unix_us).await?,
                super::behavior::gang::ClaimOutcome::Won
            ) {
                return Ok(Some(island));
            }
        }
        Ok(None)
    }

    /// Build a signed reservation transition, apply it to the local
    /// reservation fold for the optimistic CAS outcome, and broadcast
    /// it. Shared by [`Self::reserve_island`] / [`Self::release_island`].
    async fn apply_and_broadcast_reservation(
        &self,
        island: super::behavior::fold::IslandId,
        state: super::behavior::fold::ReservationState,
    ) -> Result<super::behavior::gang::ClaimOutcome, AdapterError> {
        use super::behavior::fold::{ApplyOutcome, FoldKind, ReservationFold};
        let gen = self.next_fold_generation(ReservationFold::KIND_ID, island);
        let meta = super::behavior::fold::EnvelopeMeta {
            announced_at: super::current_timestamp_micros(),
            ..Default::default()
        };
        let ann = super::behavior::fold::SignedAnnouncement::sign(
            &self.identity,
            ReservationFold::KIND_ID,
            0,
            self.node_id,
            gen,
            meta,
            super::behavior::fold::ReservationAnnouncement {
                resource_id: island,
                state,
            },
        )
        .map_err(|e| AdapterError::Connection(format!("reservation: sign failed: {e}")))?;
        // Local optimistic CAS (this node's AP view), then propagate.
        let outcome = self
            .reservation_fold
            .apply(ann.clone())
            .map_err(|e| AdapterError::Connection(format!("reservation: apply failed: {e}")))?;
        // The broadcast is best-effort gossip (the local CAS already
        // decided the AP outcome), but don't silently drop a failed
        // propagation: the returned ClaimOutcome reflects only the local
        // view, so a dropped error hides "won locally, peers not told"
        // (review #10).
        if let Err(e) = self.publish_fold_broadcast(&ann).await {
            tracing::warn!(
                island,
                error = %e,
                "reservation broadcast failed; local CAS applied but peers not notified",
            );
        }
        Ok(match outcome {
            ApplyOutcome::Inserted | ApplyOutcome::Replaced => {
                super::behavior::gang::ClaimOutcome::Won
            }
            ApplyOutcome::Rejected => super::behavior::gang::ClaimOutcome::Lost,
        })
    }

    /// Test-only helper — translate a legacy
    /// [`CapabilityAnnouncement`] into the fold-shaped envelope
    /// and apply it. Mirrors the inbound dispatch path's
    /// behavior without going through the wire, so test fixtures
    /// can prime a node's capability view in one line.
    #[doc(hidden)]
    pub fn test_inject_capability_announcement(
        &self,
        ann: super::behavior::capability::CapabilityAnnouncement,
    ) {
        let fold_ann = super::behavior::fold::capability_bridge::translate_announcement(&ann);
        let _ = self.capability_fold.apply(fold_ann);
    }

    /// Test-only helper — does the fold know about an entry
    /// keyed on `node_id`? Mirrors the legacy
    /// `CapabilityIndex::get(node_id).is_some()` check.
    #[doc(hidden)]
    pub fn test_capability_fold_has(&self, node_id: u64) -> bool {
        self.capability_fold
            .with_state(|state| state.by_node.contains_key(&node_id))
    }

    /// Test-only helper — synthesize a legacy `CapabilitySet`
    /// for `node_id` from the fold's tag state. Mirrors the
    /// legacy `CapabilityIndex::get(node_id).unwrap_or_default()`.
    #[doc(hidden)]
    pub fn test_capability_fold_get(
        &self,
        node_id: u64,
    ) -> super::behavior::capability::CapabilitySet {
        super::behavior::fold::capability_bridge::synthesize_capability_set(
            &self.capability_fold,
            node_id,
        )
    }

    /// Resolve a wire `origin_hash` to its publisher's `node_id`,
    /// or `None` when no publisher has claimed it yet. Post-
    /// `WIRE_ORIGIN_HASH_64BIT` the wire hash is the full
    /// `EntityId::origin_hash()` u64; accidental collisions are
    /// 2^-32 (effectively impossible). The map is populated
    /// first-write-wins, so an adversary grinding a colliding
    /// keypair (~2^32 work) cannot displace an established
    /// claimant.
    pub fn get_node_by_origin_hash(&self, origin_hash: u64) -> Option<u64> {
        self.origin_hash_to_node.get(&origin_hash).map(|v| *v)
    }

    /// Push the currently-stored local announcement (if any) to
    /// `peer_addr`. Called from the end of `connect` / `accept` so
    /// late joiners don't have to wait for a re-announce. No-op
    /// when we haven't yet announced anything.
    async fn push_local_announcement(&self, peer_addr: SocketAddr) {
        let Some(ann) = self.local_announcement.load_full() else {
            return;
        };
        let bytes = ann.to_bytes();
        if let Err(e) = self
            .send_subprotocol(peer_addr, SUBPROTOCOL_CAPABILITY_ANN, &bytes)
            .await
        {
            tracing::trace!(
                peer = %peer_addr,
                error = %e,
                "capability: session-open push failed"
            );
        }
    }

    // ── Stream API ─────────────────────────────────────────────────────

    /// Open (or look up) a logical stream to a connected peer.
    ///
    /// A stream is one ordered, independently reliability-configured
    /// channel inside the encrypted session to `peer_node_id`. Multiple
    /// streams share one session, one cipher, and one UDP socket, but
    /// have independent sequence numbers and reliability state. See
    /// [`Stream`] for the full contract.
    ///
    /// **Idempotent:** repeated calls for the same `(peer_node_id,
    /// stream_id)` return handles backed by the same underlying state;
    /// a config argument that differs from the first call's is ignored
    /// with a warning log. Close + re-open to change a stream's config.
    pub fn open_stream(
        &self,
        peer_node_id: u64,
        stream_id: u64,
        config: StreamConfig,
    ) -> Result<Stream, AdapterError> {
        let peer = self.peers.get(&peer_node_id).ok_or_else(|| {
            AdapterError::Connection(format!(
                "open_stream: no session for peer {:#x}",
                peer_node_id
            ))
        })?;
        let reliable = config.reliability.is_reliable();
        // Capture the freshly-allocated (or existing, on idempotent
        // re-open) epoch so the returned `Stream` handle can later
        // reject stale sends after a close+reopen.
        let epoch = peer.session.open_stream_full(
            stream_id,
            reliable,
            config.fairness_weight,
            config.window_bytes,
        );
        // Propagate the weight to the router's fair scheduler so
        // forwarded traffic on this stream (e.g., multi-hop relays
        // where we're an intermediate) respects the weight too. v1
        // caveat: local outbound sends via `send_on_stream` bypass the
        // scheduler; the weight only becomes observable on the wire
        // when a packet with this stream_id transits *this* node as
        // a forwarder. Documented in STREAM_MULTIPLEXING_PLAN.md.
        self.router
            .scheduler()
            .set_stream_weight(stream_id, config.fairness_weight);
        // Opportunistic eviction: if this open just pushed us over the
        // cap, trim via the same path as close_stream (idle==0 means
        // only the cap-exceeded pass runs).
        if peer.session.stream_count() > self.config.max_streams {
            peer.session.evict_idle_streams(
                Duration::from_nanos(u64::MAX),
                self.config.max_streams,
                "cap_exceeded",
            );
        }
        Ok(Stream {
            peer_node_id,
            stream_id,
            epoch,
            config,
        })
    }

    /// Close a stream: drop its `StreamState` from the session, ending
    /// delivery of any buffered inbound events for the stream and
    /// dropping outbound packets that haven't hit the wire yet.
    /// Idempotent. `CloseBehavior::DrainThenClose` is honored only to
    /// the extent the router's scheduler has already flushed; there is
    /// no wire "drain-then-close" signal in v1.
    pub fn close_stream(&self, peer_node_id: u64, stream_id: u64) {
        if let Some(peer) = self.peers.get(&peer_node_id) {
            peer.session.close_stream(stream_id);
        }
    }

    /// Close a reliable stream **gracefully** (H-7, `DrainThenClose`):
    /// wait until the reliability layer has no unacked packets — i.e. the
    /// receiver has acked everything (with H-9 ack-pruning, `pending`
    /// empties as grants arrive) — or `timeout` elapses, then close. Use
    /// after the last bytes of a reliable send so retransmit can still
    /// fill gaps before teardown; closing eagerly (`close_stream`) drops
    /// the retransmit window and can strand a lost tail packet on a lossy
    /// link. A fire-and-forget stream (nothing tracked) drains instantly.
    pub async fn close_stream_graceful(
        &self,
        peer_node_id: u64,
        stream_id: u64,
        timeout: Duration,
    ) {
        let deadline = std::time::Instant::now() + timeout;
        loop {
            let drained = match self.peers.get(&peer_node_id) {
                Some(p) => p
                    .session
                    .try_stream(stream_id)
                    .map(|s| !s.with_reliability(|r| r.has_pending()))
                    .unwrap_or(true), // stream already gone → nothing to drain
                None => true, // peer gone → nothing to drain
            };
            if drained || std::time::Instant::now() >= deadline {
                break;
            }
            tokio::time::sleep(Duration::from_millis(2)).await;
        }
        self.close_stream(peer_node_id, stream_id);
    }

    /// Send a batch of events on an explicit stream.
    ///
    /// Uses the stream's reliability mode from its original `open_stream`
    /// config. Returns `Backpressure` when the stream's in-flight count
    /// (`tx_inflight`) would exceed its configured `tx_window`; the event
    /// was not enqueued — the caller decides what to do (drop, retry,
    /// or buffer at the app layer). `tx_window == 0` disables the check
    /// and preserves pre-backpressure behavior. `Transport` is returned
    /// for underlying socket send failures.
    ///
    /// Returns `NotConnected` when the stream was never opened or has
    /// been closed since (`close_stream`, idle eviction, cap-exceeded
    /// LRU). A previously-closed `Stream` handle is inert by design —
    /// reusing it does NOT silently re-create the stream with default
    /// config; the caller must explicitly re-open.
    pub async fn send_on_stream(
        &self,
        stream: &Stream,
        events: &[Bytes],
    ) -> Result<(), StreamError> {
        let peer = self
            .peers
            .get(&stream.peer_node_id)
            .ok_or(StreamError::NotConnected)?;
        let peer_addr = peer.addr;
        let session = peer.session.clone();
        drop(peer);

        if self.partition_filter.contains(&peer_addr) {
            return Ok(()); // matches send_to_peer's silent drop
        }

        let stream_id = stream.stream_id;
        let reliable = stream.config.reliability.is_reliable();
        // Opt-in: bulk-transfer streams route their originating sends
        // through the FairScheduler (T-0.5) instead of straight to the
        // socket, so they participate in per-stream weighted fairness.
        // Default streams keep the direct path (zero blast radius).
        let scheduled = stream.config.scheduled;

        // Refuse to send on a stream that isn't currently open, OR
        // whose live state has a different epoch than the handle. The
        // second case covers the subtle "close + reopen with the same
        // id" bug: the handle's epoch was captured at its original
        // open, but a reopen allocates a fresh `StreamState` with a
        // new epoch. A naive existence-only check would silently
        // reroute the send onto the new stream — wrong config, wrong
        // stats, wrong tx_window accounting.
        match session.try_stream(stream_id) {
            None => return Err(StreamError::NotConnected),
            Some(state) if state.epoch() != stream.epoch => {
                return Err(StreamError::NotConnected);
            }
            // Congestion gate (H-6): if in-flight is already at the
            // congestion window, back-pressure — the caller's
            // `send_with_retry` retries as acks open the window, pacing
            // the stream to its cwnd under loss. Loss-free streams never
            // hit this (cwnd grows past the in-flight count), so normal
            // and low-volume (nRPC) traffic is unaffected.
            Some(state) if reliable && !state.with_reliability(|r| r.can_send()) => {
                return Err(StreamError::Backpressure);
            }
            Some(_) => {}
        }

        let pool = session.thread_local_pool();
        let mut builder = pool.get();

        let mut current_batch: Vec<Bytes> = Vec::with_capacity(64);
        let mut current_size = 0usize;

        // Each socket send acquires byte credit from the stream's
        // `tx_credit_remaining`. On success we `commit()` the guard —
        // the bytes now belong to the receiver, which will refund via
        // `StreamWindow` grants once it drains them. On any failure
        // (socket error, cancellation, `close_stream` race) the guard
        // drops without commit and refunds the bytes — the bytes
        // never hit the wire, so pretending they did would strand
        // credit. `NotConnected` is surfaced when the stream
        // disappears mid-call.
        let flags = if reliable {
            PacketFlags::RELIABLE
        } else {
            PacketFlags::NONE
        };

        // #19 atomicity: once ANY packet of this call has been committed
        // (put on the wire / handed to the scheduler), the call is past
        // the point of no return. Surfacing `Backpressure` to the caller
        // after a partial commit is unsafe: `send_with_retry` replays the
        // WHOLE `events` slice under fresh sequence numbers, so the
        // already-committed packets would be delivered twice. So we only
        // return `Backpressure` while `committed_any == false` (the caller
        // may safely retry the whole slice — nothing has been sent and any
        // consumed seq was rolled back). After the first commit, a flush
        // that meets backpressure retries *internally* with backoff until
        // it clears, so the batch is sent exactly once, in order.
        let mut committed_any = false;

        for event in events {
            let frame_size = EventFrame::LEN_SIZE + event.len();
            if current_size + frame_size > protocol::MAX_PAYLOAD_SIZE && !current_batch.is_empty() {
                self.flush_stream_batch(
                    &session,
                    &mut builder,
                    stream,
                    stream_id,
                    peer_addr,
                    scheduled,
                    flags,
                    &current_batch,
                    current_size,
                    &mut committed_any,
                )
                .await?;
                current_batch.clear();
                current_size = 0;
            }
            current_batch.push(event.clone());
            current_size += frame_size;
        }

        if !current_batch.is_empty() {
            self.flush_stream_batch(
                &session,
                &mut builder,
                stream,
                stream_id,
                peer_addr,
                scheduled,
                flags,
                &current_batch,
                current_size,
                &mut committed_any,
            )
            .await?;
        }

        drop(builder);
        session.touch();
        Ok(())
    }

    /// Flush one built batch of a [`Self::send_on_stream`] call: acquire
    /// byte credit + a sequence, build the packet, deliver it, commit the
    /// credit, and register the reliable retransmit descriptor.
    ///
    /// Backpressure handling is the delicate part (bug-audit #19). The
    /// sequence is allocated atomically with the byte credit (so a
    /// close+reopen race can't cross-contaminate accounting across stream
    /// lifetimes), but `deliver_stream_packet` can *still* fail with
    /// `Backpressure` AFTER the seq was consumed — a full FairScheduler
    /// queue on a `scheduled` stream. The fix has two halves:
    ///
    /// * **No permanent gap.** On the scheduler-backpressure failure path
    ///   the guard's `Drop` refunds the byte credit, and we additionally
    ///   roll back the just-consumed sequence via
    ///   [`NetSession::try_rollback_tx_seq`] (a CAS that only reclaims the
    ///   most-recently-issued seq). The packet was never on the wire, so
    ///   reclaiming the seq leaves no hole for the receiver to NACK
    ///   forever.
    /// * **No duplicate replay.** `*committed_any` tracks whether an
    ///   earlier flush in the same call already put a packet on the wire.
    ///   Before the first commit, backpressure propagates as
    ///   `StreamError::Backpressure` (the caller's `send_with_retry` may
    ///   safely replay the whole slice). After the first commit, this
    ///   flush instead retries internally with exponential backoff until
    ///   it clears, so the committed prefix is never re-sent under new
    ///   seqs — bounded by [`COMMITTED_FLUSH_STALL_BUDGET`]: a receiver
    ///   that grants no credit by then is treated as dead and a terminal
    ///   `StreamError::Transport` is surfaced (which the caller does NOT
    ///   replay), so a permanently-stalled peer can't hang the sender.
    #[allow(clippy::too_many_arguments)]
    async fn flush_stream_batch(
        &self,
        session: &Arc<NetSession>,
        builder: &mut super::pool::ThreadLocalPooledBuilder<'_>,
        stream: &Stream,
        stream_id: u64,
        peer_addr: SocketAddr,
        scheduled: bool,
        flags: PacketFlags,
        batch: &[Bytes],
        batch_size: usize,
        committed_any: &mut bool,
    ) -> Result<(), StreamError> {
        // Charge the **wire size** (Net header + AEAD tag + payload)
        // rather than just the event-frame payload so the byte window
        // matches the bandwidth the sender actually pumps onto the link.
        // Both ends add the same fixed per-packet overhead, so sender and
        // receiver accounting stay symmetric.
        let needed = wire_bytes_for_payload(batch_size);
        let mut delay = Duration::from_millis(5);
        let cap = Duration::from_millis(200);
        // Bound the post-commit internal retry so a stalled (but not
        // closed) receiver that never grants credit can't hang the
        // sender forever (#4 follow-up). Only consulted on the committed
        // path; pre-commit backpressure still returns immediately.
        let stall_deadline = tokio::time::Instant::now() + COMMITTED_FLUSH_STALL_BUDGET;
        loop {
            // `TxAdmit::Acquired` returns credit + sequence under the
            // same DashMap lookup — a close+reopen race can't slip a
            // stale sequence from the old lifetime onto the new state.
            let (guard, seq) =
                match session.try_acquire_tx_credit_matching_epoch(stream_id, stream.epoch, needed)
                {
                    TxAdmit::Acquired { guard, seq } => (guard, seq),
                    TxAdmit::WindowFull => {
                        if *committed_any {
                            // Already committed earlier packets this call —
                            // a return would trigger a whole-slice replay.
                            // Wait for a receiver grant to free credit, but
                            // give up (terminal error, no replay) once the
                            // stall budget is exhausted.
                            await_credit_or_stall(&mut delay, cap, stall_deadline).await?;
                            continue;
                        }
                        return Err(StreamError::Backpressure);
                    }
                    TxAdmit::StreamClosed => return Err(StreamError::NotConnected),
                };
            let packet = builder.build(stream_id, seq, batch, flags);
            match self
                .deliver_stream_packet(scheduled, &packet, peer_addr, stream_id)
                .await
            {
                Ok(()) => {
                    guard.commit(); // accepted (socket or scheduler) — bytes are the receiver's now
                    Self::register_retransmit(session, stream_id, stream.epoch, seq, batch, flags);
                    *committed_any = true;
                    return Ok(());
                }
                Err(StreamError::Backpressure) => {
                    // Scheduler queue full: the packet did NOT reach the
                    // wire. Drop the guard (refunds the byte credit) and
                    // roll back the consumed sequence so no receiver gap
                    // is left behind, then either retry internally (if a
                    // prefix is already committed) or surface backpressure
                    // for a safe whole-slice replay.
                    drop(guard);
                    session.try_rollback_tx_seq(stream_id, stream.epoch, seq);
                    if *committed_any {
                        await_credit_or_stall(&mut delay, cap, stall_deadline).await?;
                        continue;
                    }
                    return Err(StreamError::Backpressure);
                }
                Err(e) => {
                    // Transport/other error: the guard's Drop refunds the
                    // credit. Roll back the seq too — the packet never
                    // reached the wire, so the sequence is unused.
                    drop(guard);
                    session.try_rollback_tx_seq(stream_id, stream.epoch, seq);
                    return Err(e);
                }
            }
        }
    }

    /// Register a just-sent reliable packet for retransmit (STREAM_RETRANSMIT
    /// plan D-1). Stashing the pre-encryption descriptor (not the wire
    /// bytes) lets the NACK / timeout retransmit paths rebuild the packet
    /// with a fresh AEAD counter — a stale-counter replay would be
    /// rejected by the receiver's replay window. No-op for unreliable
    /// streams. The epoch guard skips registration if a close+reopen
    /// raced and replaced the stream state since the credit was acquired.
    ///
    /// Clock note (T-4): `on_send` stamps `sent_at = Instant::now()` here,
    /// at enqueue time. For a `scheduled` stream the packet may then sit
    /// in the FairScheduler queue before the router's send loop ships it,
    /// so a deep scheduler backlog starts the RTT/RTO clock slightly
    /// before the packet is on the wire — biasing the adaptive-RTO sample
    /// low and risking a marginally early timeout-driven resend. This
    /// self-corrects (the next clean RTT sample re-converges) and the
    /// scheduler queue is shallow in practice; stamping at dequeue would
    /// need the descriptor visible in the router send loop, which it
    /// isn't, so the enqueue-time stamp is accepted.
    fn register_retransmit(
        session: &Arc<NetSession>,
        stream_id: u64,
        epoch: u64,
        seq: u64,
        events: &[Bytes],
        flags: PacketFlags,
    ) {
        if !flags.contains(PacketFlags::RELIABLE) {
            return;
        }
        let descriptor = Arc::new(super::RetransmitDescriptor {
            seq,
            stream_id,
            events: events.to_vec(),
            flags,
        });
        if let Some(state) = session.try_stream(stream_id) {
            if state.epoch() == epoch {
                state.with_reliability(|r| r.on_send(descriptor));
            }
        }
    }

    /// Deliver one built stream packet, either straight to the socket
    /// (the default direct path) or — when the stream is `scheduled`
    /// (T-0.5) — by enqueueing it on the router's
    /// [`FairScheduler`](super::router::FairScheduler) so the router's
    /// send loop ships it under per-stream weighted fairness.
    ///
    /// A full scheduler queue surfaces as [`StreamError::Backpressure`]
    /// (same shape as a tx-credit `WindowFull`), so `send_with_retry`
    /// rides it. Scheduled sends pay one `Bytes` copy (the build pool
    /// buffer is reused after the call); bulk transfer absorbs it.
    async fn deliver_stream_packet(
        &self,
        scheduled: bool,
        packet: &[u8],
        peer_addr: SocketAddr,
        stream_id: u64,
    ) -> Result<(), StreamError> {
        if scheduled {
            let queued = super::router::QueuedPacket {
                data: Bytes::copy_from_slice(packet),
                dest: peer_addr,
                stream_id,
                // Bulk data rides non-priority; the scheduler's
                // priority lane is reserved for control/interactive.
                priority: false,
                queued_at: std::time::Instant::now(),
            };
            if self.router.scheduler().enqueue(queued) {
                Ok(())
            } else {
                Err(StreamError::Backpressure)
            }
        } else {
            self.socket
                .send_to(packet, peer_addr)
                .await
                .map(|_| ())
                .map_err(|e| StreamError::Transport(format!("send failed: {}", e)))
        }
    }

    /// Send `events` on `stream`, retrying on `Backpressure` with
    /// exponential backoff (5 ms → 200 ms, doubling) up to `max_retries`
    /// times. Transport failures are returned immediately — they're a
    /// real error, not a pressure signal, and retrying would just mask
    /// them. Returns the final `Backpressure` error if the stream stays
    /// saturated across every attempt.
    pub async fn send_with_retry(
        &self,
        stream: &Stream,
        events: &[Bytes],
        max_retries: usize,
    ) -> Result<(), StreamError> {
        let mut delay = Duration::from_millis(5);
        let cap = Duration::from_millis(200);
        let mut last_backpressure: Option<StreamError> = None;
        for _ in 0..max_retries.saturating_add(1) {
            match self.send_on_stream(stream, events).await {
                Ok(()) => return Ok(()),
                Err(StreamError::Backpressure) => {
                    last_backpressure = Some(StreamError::Backpressure);
                    tokio::time::sleep(delay).await;
                    delay = (delay * 2).min(cap);
                }
                Err(e) => return Err(e),
            }
        }
        Err(last_backpressure.unwrap_or(StreamError::Backpressure))
    }

    /// Convenience wrapper around [`send_with_retry`](Self::send_with_retry)
    /// with a generous retry count. Blocks the calling task until the
    /// send succeeds or a transport error occurs. Use when you'd rather
    /// wait than drop; prefer `send_with_retry` if you need a concrete
    /// upper bound on retry attempts.
    pub async fn send_blocking(
        &self,
        stream: &Stream,
        events: &[Bytes],
    ) -> Result<(), StreamError> {
        // 4096 retries × 200 ms cap = ~13 minutes in the worst case,
        // effectively "block until the network lets up or something is
        // actually wrong." Callers that need a tighter bound should use
        // `send_with_retry` directly.
        self.send_with_retry(stream, events, 4096).await
    }

    /// Snapshot of per-stream stats for a single stream.
    ///
    /// Returns `None` if either the peer or the stream doesn't exist.
    pub fn stream_stats(&self, peer_node_id: u64, stream_id: u64) -> Option<StreamStats> {
        let peer = self.peers.get(&peer_node_id)?;
        let state = peer.session.get_stream(stream_id)?;
        Some(StreamStats {
            tx_seq: state.current_tx_seq(),
            rx_seq: state.current_rx_seq(),
            inbound_pending: state.inbound_len() as u64,
            last_activity_ns: state.last_activity_ns(),
            active: state.is_active(),
            backpressure_events: state.backpressure_events(),
            tx_credit_remaining: state.tx_credit_remaining(),
            tx_window: state.tx_window(),
            credit_grants_received: state.credit_grants_received(),
            credit_grants_sent: state.credit_grants_sent(),
        })
    }

    /// Snapshot of per-stream stats for every stream in the session to
    /// `peer_node_id`. Empty vec if the peer doesn't exist.
    pub fn all_stream_stats(&self, peer_node_id: u64) -> Vec<(u64, StreamStats)> {
        let peer = match self.peers.get(&peer_node_id) {
            Some(p) => p,
            None => return Vec::new(),
        };
        let session = peer.session.clone();
        drop(peer);
        session
            .stream_ids()
            .into_iter()
            .filter_map(|sid| {
                let state = session.get_stream(sid)?;
                Some((
                    sid,
                    StreamStats {
                        tx_seq: state.current_tx_seq(),
                        rx_seq: state.current_rx_seq(),
                        inbound_pending: state.inbound_len() as u64,
                        last_activity_ns: state.last_activity_ns(),
                        active: state.is_active(),
                        backpressure_events: state.backpressure_events(),
                        tx_credit_remaining: state.tx_credit_remaining(),
                        tx_window: state.tx_window(),
                        credit_grants_received: state.credit_grants_received(),
                        credit_grants_sent: state.credit_grants_sent(),
                    },
                ))
            })
            .collect()
    }

    /// Connect to a peer whose first hop on the wire is `relay_addr`.
    ///
    /// The handshake is an ordinary Net packet with the `HANDSHAKE` flag
    /// plus a routing header addressed to `dest_node_id`. The routing
    /// layer forwards it hop-by-hop (like any other packet); the
    /// responder's msg2 comes back the same way. There's no separate
    /// subprotocol, no per-hop re-encryption — Noise NKpsk0 provides
    /// end-to-end confidentiality and authenticity, and the prologue
    /// binds `(src_node_id, dest_node_id)` so a relay that rewrites
    /// either identity in the routing header fails the responder's MAC
    /// check on msg1.
    ///
    /// `start()` must have been called before `connect_via` — the
    /// receive loop has to be running to deliver msg2 back to us.
    /// One attempt of the routed-handshake protocol: register a
    /// pending-initiator slot, send msg1, await msg2. On any
    /// error path the pending slot is cleared so a retry from
    /// the caller (or a fresh `connect_via` invocation) sees a
    /// clean entry. Returns the negotiated [`SessionKeys`] on
    /// success — the caller installs the peer (NetSession +
    /// router + peers + addr_to_node).
    async fn try_connect_via_once(
        &self,
        relay_addr: SocketAddr,
        dest_pubkey: &[u8; 32],
        dest_node_id: u64,
    ) -> Result<SessionKeys, AdapterError> {
        // Build msg1. Prologue uses *routing-identity* (32-bit) versions
        // of (self, dest) — that's what a malicious relay could see and
        // rewrite in the routing header, so binding those bits into the
        // Noise transcript catches tampering. The FULL u64 self.node_id
        // is carried inside the msg1 payload (Noise-AEAD-authenticated),
        // so the responder learns it after decryption and can address
        // msg2 back to the correct u64 identity.
        let pending_key = routing_id(dest_node_id);
        let prologue = handshake_prologue(routing_id(self.node_id), pending_key);
        let mut noise =
            NoiseHandshake::initiator_with_prologue(&self.config.psk, dest_pubkey, &prologue)
                .map_err(|e| AdapterError::Fatal(format!("handshake init failed: {}", e)))?;
        let msg1 = noise
            .write_message(&self.node_id.to_le_bytes())
            .map_err(|e| AdapterError::Connection(format!("write_message failed: {}", e)))?;

        // Register pending-initiator state so the dispatch loop can
        // complete the handshake when msg2 arrives. Keyed by the
        // 32-bit routing identity because msg2's routing header carries
        // the truncated src_id — that's the only key the dispatch loop
        // has when it tries to find the matching initiator.
        let (tx, rx) = oneshot::channel();
        match self.pending_handshakes.entry(pending_key) {
            dashmap::mapref::entry::Entry::Occupied(_) => {
                return Err(AdapterError::Connection(format!(
                    "connect_via: handshake already in flight for peer {:#x}",
                    dest_node_id
                )));
            }
            dashmap::mapref::entry::Entry::Vacant(v) => {
                v.insert(PendingHandshake { noise, tx });
            }
        }

        // Wrap msg1 in a Net handshake packet + routing header and
        // send to the first hop. No session encryption — the handshake
        // payload is the raw Noise bytes, authenticated/confidential
        // by Noise itself.
        let inner = {
            let mut builder = PacketBuilder::new(&[0u8; 32], 0);
            builder.build_handshake(&msg1)
        };
        let routing = RoutingHeader::new(dest_node_id, self.node_id as u32, DEFAULT_HANDSHAKE_TTL);
        let mut routed = bytes::BytesMut::with_capacity(ROUTING_HEADER_SIZE + inner.len());
        routed.extend_from_slice(&routing.to_bytes());
        routed.extend_from_slice(&inner);
        if let Err(e) = self.socket.send_to(&routed, relay_addr).await {
            self.pending_handshakes.remove(&pending_key);
            return Err(AdapterError::Connection(format!("send failed: {}", e)));
        }

        // Wait for the dispatch loop to complete msg2.
        let keys = match tokio::time::timeout(self.config.handshake_timeout, rx).await {
            Ok(Ok(Ok(k))) => k,
            Ok(Ok(Err(e))) => {
                self.pending_handshakes.remove(&pending_key);
                return Err(AdapterError::Fatal(format!("handshake failed: {}", e)));
            }
            Ok(Err(_)) => {
                self.pending_handshakes.remove(&pending_key);
                return Err(AdapterError::Connection("handshake channel dropped".into()));
            }
            Err(_) => {
                self.pending_handshakes.remove(&pending_key);
                return Err(AdapterError::Connection("handshake timeout".into()));
            }
        };
        Ok(keys)
    }

    /// Connect to `dest_node_id` via a routed handshake through
    /// `relay_addr`. Unlike [`Self::connect`] (which requires the
    /// responder to pre-`accept()` this initiator's node_id before
    /// `start()`), this path embeds the initiator's full node_id
    /// inside the Noise msg1 payload and routes the packet through
    /// the dispatch loop's `handle_routed_handshake` Case 2 — so a
    /// daemon that's already `start()`ed accepts msg1 from a brand-
    /// new initiator without prior coordination.
    ///
    /// When `relay_addr == final destination` (the CLI remote-attach
    /// case), the routed path is degenerate one-hop. The post-
    /// handshake peer install populates `addr_to_node[relay_addr]`
    /// via `entry().or_insert(...)` so address-keyed sends resolve
    /// the peer; in a true multi-hop scenario the relay's prior
    /// mapping stays intact.
    ///
    /// Retries up to [`MeshNodeConfig::handshake_retries`] (default
    /// 3) — a single UDP drop on msg1 or msg2 should not surface
    /// as a typed error.
    pub async fn connect_via(
        &self,
        relay_addr: SocketAddr,
        dest_pubkey: &[u8; 32],
        dest_node_id: u64,
    ) -> Result<u64, AdapterError> {
        // Retry the msg1-send + msg2-await `handshake_retries` times
        // (mirrors `handshake_initiator` for the direct path). Routed
        // handshakes ride a UDP relay path that can drop msg1 or msg2
        // independently; a single packet loss should not surface as a
        // typed error to the operator. Per-attempt cleanup happens
        // inside `try_connect_via_once`, so each retry starts fresh.
        let mut attempt = 0;
        let keys = loop {
            attempt += 1;
            match self
                .try_connect_via_once(relay_addr, dest_pubkey, dest_node_id)
                .await
            {
                Ok(keys) => break keys,
                Err(e) if attempt < self.config.handshake_retries => {
                    tracing::warn!(
                        attempt,
                        error = %e,
                        "mesh routed handshake failed, retrying"
                    );
                    tokio::time::sleep(Duration::from_millis(100 * attempt as u64)).await;
                }
                Err(e) => return Err(e),
            }
        };

        // Shared peer install. Routed-mode preserves any prior
        // `addr_to_node[relay_addr]` entry (a true multi-hop
        // relay keeps its own peer_id; degenerate single-hop
        // installs the destination). Routed handshakes
        // intentionally skip the post-install pingwave /
        // failure_detector / announcement push — see
        // `connect`'s wiring for the direct-handshake-only
        // bookkeeping.
        self.install_peer(
            dest_node_id,
            relay_addr,
            keys,
            AddrInstallMode::RoutedPreserve,
        );

        Ok(dest_node_id)
    }

    /// Handshake to `target_addr` and install the resulting session
    /// with a compare-and-swap against `expected_prior_session_id`
    /// (`NAT_TRAVERSAL_V2_PLAN.md` C2). Same retrying handshake as
    /// [`Self::connect_via`], but the install proceeds only if the
    /// peer's current session_id still matches — so a background
    /// direct-path upgrade never clobbers a racing rotation.
    ///
    /// Returns `Ok(true)` if the session was installed, `Ok(false)` if
    /// the CAS lost (a racing handshake won — the caller leaves the
    /// current session, typically the working relay path, intact), or
    /// `Err` on handshake failure (nothing was mutated, so the relay
    /// session is likewise untouched).
    #[cfg(feature = "nat-traversal")]
    async fn connect_via_cas(
        &self,
        target_addr: SocketAddr,
        dest_pubkey: &[u8; 32],
        dest_node_id: u64,
        expected_prior_session_id: u64,
        addr_mode: AddrInstallMode,
    ) -> Result<bool, AdapterError> {
        let mut attempt = 0;
        let keys = loop {
            attempt += 1;
            match self
                .try_connect_via_once(target_addr, dest_pubkey, dest_node_id)
                .await
            {
                Ok(keys) => break keys,
                Err(e) if attempt < self.config.handshake_retries => {
                    tracing::debug!(attempt, error = %e, "upgrade handshake retry");
                    tokio::time::sleep(Duration::from_millis(100 * attempt as u64)).await;
                }
                Err(e) => return Err(e),
            }
        };
        Ok(self.install_peer_cas(
            dest_node_id,
            target_addr,
            keys,
            addr_mode,
            Some(expected_prior_session_id),
        ))
    }

    // ── Background direct-path upgrade (Stage 3) ─────────────────────────

    /// `true` if a fresh upgrade attempt for `peer_id` is allowed right
    /// now — no cache entry, or an entry that isn't `done` and whose
    /// backoff/defer window has elapsed.
    #[cfg(feature = "nat-traversal")]
    fn upgrade_should_attempt(&self, peer_id: u64) -> bool {
        match self.upgrade_cache.get(&peer_id) {
            None => true,
            Some(e) => !e.done && Instant::now() >= e.next_eligible,
        }
    }

    /// Lease an attempt: push `next_eligible` out so the scan loop won't
    /// re-spawn a second attempt for this peer while one is in flight.
    /// The attempt's outcome recorder overwrites this.
    #[cfg(feature = "nat-traversal")]
    fn upgrade_lease(&self, peer_id: u64, lease: Duration) {
        let mut e = self
            .upgrade_cache
            .entry(peer_id)
            .or_insert(UpgradeCacheEntry {
                next_eligible: Instant::now(),
                failures: 0,
                done: false,
            });
        e.next_eligible = Instant::now() + lease;
    }

    /// Record a terminal outcome: the session is direct (or can't be
    /// upgraded) — stop attempting.
    #[cfg(feature = "nat-traversal")]
    fn upgrade_record_done(&self, peer_id: u64) {
        let mut e = self
            .upgrade_cache
            .entry(peer_id)
            .or_insert(UpgradeCacheEntry {
                next_eligible: Instant::now(),
                failures: 0,
                done: false,
            });
        e.done = true;
    }

    /// Record a busy-defer: retry after a short delay, without counting
    /// it as a failure (the session is healthy, just carrying traffic).
    #[cfg(feature = "nat-traversal")]
    fn upgrade_record_defer(&self, peer_id: u64, delay: Duration) {
        let mut e = self
            .upgrade_cache
            .entry(peer_id)
            .or_insert(UpgradeCacheEntry {
                next_eligible: Instant::now(),
                failures: 0,
                done: false,
            });
        e.next_eligible = Instant::now() + delay;
    }

    /// Record a failed attempt: exponential backoff on the retry.
    #[cfg(feature = "nat-traversal")]
    fn upgrade_record_failure(&self, peer_id: u64) {
        const BASE: Duration = Duration::from_secs(2);
        const MAX_SHIFT: u32 = 5; // cap backoff at BASE << 5 = 64 s
        let mut e = self
            .upgrade_cache
            .entry(peer_id)
            .or_insert(UpgradeCacheEntry {
                next_eligible: Instant::now(),
                failures: 0,
                done: false,
            });
        e.failures = e.failures.saturating_add(1);
        let backoff = BASE.saturating_mul(1u32 << e.failures.min(MAX_SHIFT));
        e.next_eligible = Instant::now() + backoff;
    }

    /// Attempt a single background direct-path upgrade of a
    /// relay-routed session to `peer_id` (`NAT_TRAVERSAL_V2_PLAN.md`
    /// Stage 3). Best-effort throughout: on any failure the working
    /// relay session is left intact (the whole feature is an
    /// optimization). Enforces the migration contract:
    ///
    /// - **C3 initiator busy gate:** if the local session has open
    ///   streams or unacked in-flight data, defer — a swap would drop
    ///   it. Retried once quiescent.
    /// - **C2 CAS install:** the punched session installs only if the
    ///   peer's session_id hasn't changed since we snapshotted it, so a
    ///   racing inbound rotation wins instead of being clobbered.
    ///
    /// (C1 — only the lower-node-id end initiates — is enforced by the
    /// scan loop before this is called.)
    ///
    /// This landing upgrades **`Direct` pairs** (the peer is directly
    /// reachable at its reflex). Coordinated-punch (`SinglePunch`)
    /// upgrades reuse the same install machinery and are a follow-up;
    /// `SkipPunch` pairs can never punch. `SkipPunch` is marked
    /// terminal (`done`) so the scan stops revisiting it, but
    /// `SinglePunch` is only *deferred*: a later reflex-drift
    /// reclassification can flip the pair to `Direct`, and a permanent
    /// `done` would pin the session to the relay for the rest of the
    /// process's life. The per-peer cache entry is also dropped when
    /// the peer is evicted (heartbeat sweep), so a session that
    /// regresses direct→relay and reconnects starts from a clean slate.
    #[cfg(feature = "nat-traversal")]
    async fn attempt_direct_upgrade(&self, peer_id: u64) {
        use super::traversal::classify::{pair_action, PairAction};

        // Re-evaluate a not-yet-upgradable `SinglePunch` pair after
        // this long, so a NAT reclassification that makes it `Direct`
        // gets picked up instead of being cached off permanently.
        const SINGLEPUNCH_RECHECK: Duration = Duration::from_secs(30);

        // Snapshot the current session.
        let Some((relay_addr, prior_sid, pubkey, busy)) = self.peers.get(&peer_id).map(|e| {
            let v = e.value();
            (
                v.addr,
                v.session.session_id(),
                v.remote_static_pub,
                v.session.has_open_streams() || v.session.has_unacked(),
            )
        }) else {
            return;
        };

        // Still relay-routed? A direct session is already on the best
        // path — nothing to upgrade.
        if !self.is_relayed_peer(peer_id, &relay_addr) {
            self.upgrade_record_done(peer_id);
            return;
        }

        // C3 initiator busy gate.
        if busy {
            self.traversal_stats.record_upgrade_deferred_busy();
            self.upgrade_record_defer(peer_id, Duration::from_secs(1));
            return;
        }

        let action = pair_action(self.nat_class(), self.peer_nat_class(peer_id));
        let target_addr = match action {
            PairAction::Direct => match self.peer_reflex_addr(peer_id) {
                Some(addr) => addr,
                // No cached reflex yet — retry with backoff once the
                // peer's announcement lands.
                None => {
                    self.upgrade_record_failure(peer_id);
                    return;
                }
            },
            // `SkipPunch` can never punch — terminal, stop scanning.
            PairAction::SkipPunch => {
                self.upgrade_record_done(peer_id);
                return;
            }
            // `SinglePunch` upgrades aren't wired yet, but the pair may
            // become `Direct` after a reclassification. Defer instead
            // of marking terminal so the scan revisits it.
            PairAction::SinglePunch => {
                self.upgrade_record_defer(peer_id, SINGLEPUNCH_RECHECK);
                return;
            }
        };

        // Guard against "upgrading" to the very path we're already on.
        if target_addr == relay_addr {
            self.upgrade_record_done(peer_id);
            return;
        }

        self.traversal_stats.record_upgrade_attempt();
        match self
            .connect_via_cas(
                target_addr,
                &pubkey,
                peer_id,
                prior_sid,
                AddrInstallMode::DirectOverwrite,
            )
            .await
        {
            Ok(true) => {
                self.traversal_stats.record_upgrade_success();
                self.upgrade_record_done(peer_id);
            }
            // CAS lost to a racing rotation, or handshake failed — the
            // existing session is untouched. Back off and re-evaluate;
            // if the race made the session direct, the next attempt's
            // relayed-check marks it done.
            Ok(false) | Err(_) => {
                self.upgrade_record_failure(peer_id);
            }
        }
    }

    /// Test hook: drive a single [`Self::attempt_direct_upgrade`]
    /// synchronously, bypassing the background scan loop's timing so
    /// integration tests are deterministic under parallel load. The
    /// caller is responsible for the C1 lower-node-id check the loop
    /// normally enforces.
    #[doc(hidden)]
    #[cfg(feature = "nat-traversal")]
    pub async fn attempt_direct_upgrade_for_test(&self, peer_id: u64) {
        self.attempt_direct_upgrade(peer_id).await;
    }

    /// Whether the scan loop should consider `peer_id` for a background
    /// upgrade this tick: the local node is the lower-id initiator (C1),
    /// the session is relay-routed (not already direct), and the
    /// per-peer throttle window has elapsed.
    #[cfg(feature = "nat-traversal")]
    fn upgrade_is_loop_candidate(&self, peer_id: u64) -> bool {
        let Some(addr) = self.peers.get(&peer_id).map(|e| e.value().addr) else {
            return false;
        };
        self.upgrade_is_loop_candidate_at(peer_id, addr)
    }

    /// As [`Self::upgrade_is_loop_candidate`] but with the peer's
    /// session `addr` already in hand — lets the scan loop test each
    /// peer straight from the `peers` iterator entry instead of doing a
    /// redundant `peers.get` shard-lookup on the map it is iterating.
    #[cfg(feature = "nat-traversal")]
    fn upgrade_is_loop_candidate_at(&self, peer_id: u64, addr: SocketAddr) -> bool {
        // C1: only the lower-node-id end initiates.
        if self.node_id >= peer_id {
            return false;
        }
        // Relay-routed only — a direct session has nothing to upgrade.
        if !self.is_relayed_peer(peer_id, &addr) {
            return false;
        }
        self.upgrade_should_attempt(peer_id)
    }

    /// Test hook for [`Self::upgrade_is_loop_candidate`] — lets
    /// integration tests assert the C1 / relay-routed filter
    /// deterministically without racing the loop's cadence.
    #[doc(hidden)]
    #[cfg(feature = "nat-traversal")]
    pub fn upgrade_is_loop_candidate_for_test(&self, peer_id: u64) -> bool {
        self.upgrade_is_loop_candidate(peer_id)
    }

    /// Test hook: whether the direct-path upgrade throttle cache holds
    /// an entry for `peer_id`. Pins that a failed peer's entry is
    /// dropped so the cache can't grow without bound under churn.
    #[doc(hidden)]
    #[cfg(feature = "nat-traversal")]
    pub fn upgrade_cache_contains_for_test(&self, peer_id: u64) -> bool {
        self.upgrade_cache.contains_key(&peer_id)
    }

    /// Test hook: the `done` (terminal) flag of `peer_id`'s throttle
    /// entry, or `None` if there is no entry. `SkipPunch` is terminal
    /// (`Some(true)`); a deferred `SinglePunch` is not (`Some(false)`).
    #[doc(hidden)]
    #[cfg(feature = "nat-traversal")]
    pub fn upgrade_entry_is_done_for_test(&self, peer_id: u64) -> Option<bool> {
        self.upgrade_cache.get(&peer_id).map(|e| e.done)
    }

    /// Spawn the background direct-path upgrade scan loop (Stage 3).
    /// Every tick, find relay-routed peers for which this node is the
    /// lower-id initiator (C1) and whose throttle window has elapsed,
    /// and fire a per-peer `attempt_direct_upgrade`. No-op
    /// unless `MeshNodeConfig::auto_direct_upgrade` is set; exits on
    /// `shutdown_notify`.
    ///
    /// The task holds only a [`Weak`](std::sync::Weak) self-ref
    /// (upgraded transiently per tick), never `Arc::clone(self)`. A
    /// strong self-ref held for the task's lifetime would stop
    /// [`MeshNode::drop`] — the path that sets `shutdown` — from ever
    /// running for an `Arc<MeshNode>` dropped without an explicit
    /// `shutdown()`: the loop would then spin forever and leak the
    /// node, its socket, and every other background task. Same
    /// `Weak`-then-`upgrade()` contract as
    /// `spawn_capability_reannounce_loop`.
    #[cfg(feature = "nat-traversal")]
    pub fn spawn_direct_upgrade_loop(self: &Arc<Self>) -> JoinHandle<()> {
        const SCAN_INTERVAL: Duration = Duration::from_secs(1);
        const ATTEMPT_LEASE: Duration = Duration::from_secs(10);

        let weak = Arc::downgrade(self);
        let shutdown = self.shutdown.clone();
        let shutdown_notify = self.shutdown_notify.clone();

        tokio::spawn(async move {
            // Feature off → nothing to do. Transient upgrade only to
            // read the flag; the strong ref is dropped with the match.
            match weak.upgrade() {
                Some(node) if node.config.auto_direct_upgrade => {}
                _ => return,
            }
            let mut tick = tokio::time::interval(SCAN_INTERVAL);
            tick.tick().await; // skip the immediate tick
            while !shutdown.load(Ordering::Acquire) {
                tokio::select! {
                    _ = shutdown_notify.notified() => {
                        if shutdown.load(Ordering::Acquire) {
                            return;
                        }
                    }
                    _ = tick.tick() => {}
                }

                // Upgrade transiently for this tick; if the node is
                // gone, exit. The strong ref lives only across the
                // synchronous scan below — never across an await — so
                // it can't keep the node alive past a `drop`.
                let Some(node) = weak.upgrade() else { break };

                // Snapshot eligible peers without holding a shard guard
                // across the spawned attempts. Test each peer straight
                // from the iterator entry (id + addr in hand) so the
                // filter doesn't re-`get` the map it's iterating.
                let candidates: Vec<u64> = node
                    .peers
                    .iter()
                    .filter(|entry| {
                        node.upgrade_is_loop_candidate_at(*entry.key(), entry.value().addr)
                    })
                    .map(|entry| *entry.key())
                    .collect();

                for peer_id in candidates {
                    // Lease before spawning so the next scan doesn't
                    // double-fire while this attempt is in flight.
                    node.upgrade_lease(peer_id, ATTEMPT_LEASE);
                    let n = node.clone();
                    tokio::spawn(async move {
                        n.attempt_direct_upgrade(peer_id).await;
                    });
                }
            }
        })
    }

    /// Connect to a peer by node id, using the routing table to pick the
    /// first hop. Fails with `Connection("no route to ...")` if the
    /// routing table doesn't have a route to the destination yet — in
    /// which case the caller can retry once pingwaves have propagated.
    pub async fn connect_routed(
        &self,
        dest_pubkey: &[u8; 32],
        dest_node_id: u64,
    ) -> Result<u64, AdapterError> {
        let first_hop = self
            .router
            .routing_table()
            .lookup(dest_node_id)
            .ok_or_else(|| {
                AdapterError::Connection(format!(
                    "connect_routed: no route to peer {:#x}",
                    dest_node_id
                ))
            })?;
        self.connect_via(first_hop, dest_pubkey, dest_node_id).await
    }

    // ── Handshake helpers ───────────────────────────────────────────────

    async fn handshake_initiator(
        &self,
        peer_addr: SocketAddr,
        peer_pubkey: &[u8; 32],
        peer_node_id: u64,
    ) -> Result<SessionKeys, AdapterError> {
        let mut attempt = 0;
        loop {
            attempt += 1;
            match self
                .try_handshake_initiator(peer_addr, peer_pubkey, peer_node_id)
                .await
            {
                Ok(keys) => return Ok(keys),
                Err(e) if attempt < self.config.handshake_retries => {
                    tracing::warn!(attempt, error = %e, "mesh handshake failed, retrying");
                    tokio::time::sleep(Duration::from_millis(100 * attempt as u64)).await;
                }
                Err(e) => return Err(e),
            }
        }
    }

    async fn try_handshake_initiator(
        &self,
        peer_addr: SocketAddr,
        peer_pubkey: &[u8; 32],
        peer_node_id: u64,
    ) -> Result<SessionKeys, AdapterError> {
        let timeout = self.config.handshake_timeout;

        // Prologue uses the 32-bit `routing_id` projection of the node
        // ids — the same projection routed handshakes use, so the two
        // paths share one prologue convention. Direct handshakes don't
        // traverse the routing plane, but the unified convention
        // simplifies reasoning and future code reuse.
        let prologue = handshake_prologue(routing_id(self.node_id), routing_id(peer_node_id));
        let mut handshake =
            NoiseHandshake::initiator_with_prologue(&self.config.psk, peer_pubkey, &prologue)
                .map_err(|e| AdapterError::Fatal(format!("handshake init failed: {}", e)))?;

        let msg1 = handshake
            .write_message(&[])
            .map_err(|e| AdapterError::Connection(format!("write_message failed: {}", e)))?;

        let mut builder = PacketBuilder::new(&[0u8; 32], 0);
        let packet = builder.build_handshake(&msg1);

        // Polling `socket_arc.recv_from` directly would race
        // `spawn_receive_loop`'s consumer post-`start()` (tokio
        // dispatches a UDP datagram to exactly one waiter), so:
        //   - Pre-`start()`: use `recv_from`; the dispatcher isn't
        //     running, so there's no race. This preserves the
        //     existing init-time ordering where `connect()` is
        //     called before `start()`.
        //   - Post-`start()`: register an oneshot in
        //     `pending_direct_initiators`, then send msg1, then
        //     await the oneshot. The dispatcher's direct-handshake
        //     branch forwards the parsed payload bytes through.
        // Concurrent direct connects on the same node also work
        // — each registers under its own peer_addr.
        let payload_bytes = if self.started.load(Ordering::Acquire) {
            let (tx, rx) = oneshot::channel::<Bytes>();
            // Register BEFORE sending msg1 so we can't miss a
            // fast responder that replies before we'd otherwise
            // be ready to receive. `insert` replaces any prior
            // entry for the same `peer_addr` — last writer wins.
            self.pending_direct_initiators.insert(peer_addr, tx);

            if let Err(e) = self.socket.send_to(&packet, peer_addr).await {
                self.pending_direct_initiators.remove(&peer_addr);
                return Err(AdapterError::Connection(format!("send failed: {}", e)));
            }

            match tokio::time::timeout(timeout, rx).await {
                Ok(Ok(payload)) => payload,
                Ok(Err(_)) => {
                    // Sender dropped — the dispatcher removed our
                    // entry without forwarding. Should not happen
                    // unless start() shut down; treat as timeout.
                    self.pending_direct_initiators.remove(&peer_addr);
                    return Err(AdapterError::Connection("handshake channel dropped".into()));
                }
                Err(_) => {
                    // Timeout — the responder never replied or its
                    // reply arrived for a different source. Clean up.
                    self.pending_direct_initiators.remove(&peer_addr);
                    return Err(AdapterError::Connection("handshake timeout".into()));
                }
            }
        } else {
            // Pre-start fallback: dispatcher is not running, so
            // there's nothing to forward through the registry.
            // Poll the socket directly — no race exists yet.
            let socket_arc = self.socket.socket_arc();
            self.socket
                .send_to(&packet, peer_addr)
                .await
                .map_err(|e| AdapterError::Connection(format!("send failed: {}", e)))?;

            let parsed = tokio::time::timeout(timeout, async {
                loop {
                    let mut recv_buf = bytes::BytesMut::with_capacity(protocol::MAX_PACKET_SIZE);
                    recv_buf.resize(protocol::MAX_PACKET_SIZE, 0);

                    let (n, source) = socket_arc
                        .recv_from(&mut recv_buf)
                        .await
                        .map_err(|e| AdapterError::Connection(format!("recv failed: {}", e)))?;

                    if source != peer_addr {
                        continue;
                    }

                    recv_buf.truncate(n);
                    let data = recv_buf.freeze();

                    if let Some(p) = ParsedPacket::parse(data, source) {
                        if p.header.flags.is_handshake() {
                            return Ok::<_, AdapterError>(p);
                        }
                    }
                }
            })
            .await
            .map_err(|_| AdapterError::Connection("handshake timeout".into()))??;
            parsed.payload
        };

        handshake
            .read_message(&payload_bytes)
            .map_err(|e| AdapterError::Connection(format!("read_message failed: {}", e)))?;

        handshake
            .into_session_keys()
            .map_err(|e| AdapterError::Fatal(format!("key extraction failed: {}", e)))
    }

    async fn handshake_responder(
        &self,
        peer_node_id: u64,
    ) -> Result<(SessionKeys, SocketAddr), AdapterError> {
        let mut attempt = 0;
        loop {
            attempt += 1;
            match self.try_handshake_responder(peer_node_id).await {
                Ok(result) => return Ok(result),
                Err(e) if attempt < self.config.handshake_retries => {
                    tracing::warn!(attempt, error = %e, "mesh accept failed, retrying");
                    tokio::time::sleep(Duration::from_millis(100 * attempt as u64)).await;
                }
                Err(e) => return Err(e),
            }
        }
    }

    async fn try_handshake_responder(
        &self,
        peer_node_id: u64,
    ) -> Result<(SessionKeys, SocketAddr), AdapterError> {
        let timeout = self.config.handshake_timeout;
        let socket_arc = self.socket.socket_arc();

        // Wait for initiator's handshake
        let (parsed, source) = tokio::time::timeout(timeout, async {
            loop {
                let mut recv_buf = bytes::BytesMut::with_capacity(protocol::MAX_PACKET_SIZE);
                recv_buf.resize(protocol::MAX_PACKET_SIZE, 0);

                let (n, source) = socket_arc
                    .recv_from(&mut recv_buf)
                    .await
                    .map_err(|e| AdapterError::Connection(format!("recv failed: {}", e)))?;

                recv_buf.truncate(n);
                let data = recv_buf.freeze();

                if let Some(p) = ParsedPacket::parse(data, source) {
                    if p.header.flags.is_handshake() {
                        return Ok::<_, AdapterError>((p, source));
                    }
                }
            }
        })
        .await
        .map_err(|_| AdapterError::Connection("handshake timeout".into()))??;

        // Direct responder: mirror the initiator's `routing_id`-based
        // prologue so direct and routed share one convention.
        let prologue = handshake_prologue(routing_id(peer_node_id), routing_id(self.node_id));
        let mut handshake = NoiseHandshake::responder_with_prologue(
            &self.config.psk,
            &self.static_keypair,
            &prologue,
        )
        .map_err(|e| AdapterError::Fatal(format!("handshake init failed: {}", e)))?;

        handshake
            .read_message(&parsed.payload)
            .map_err(|e| AdapterError::Connection(format!("read_message failed: {}", e)))?;

        let msg2 = handshake
            .write_message(&[])
            .map_err(|e| AdapterError::Connection(format!("write_message failed: {}", e)))?;

        let mut builder = PacketBuilder::new(&[0u8; 32], 0);
        let packet = builder.build_handshake(&msg2);

        self.socket
            .send_to(&packet, source)
            .await
            .map_err(|e| AdapterError::Connection(format!("send failed: {}", e)))?;

        let keys = handshake
            .into_session_keys()
            .map_err(|e| AdapterError::Fatal(format!("key extraction failed: {}", e)))?;

        Ok((keys, source))
    }

    // ── NAT traversal ──────────────────────────────────────────────────
    //
    // `SUBPROTOCOL_REFLEX` client. The handler half lives in the
    // packet-dispatch loop (`process_local_packet`, in the
    // `SUBPROTOCOL_REFLEX` branch) and echoes the observed UDP
    // source back as a `ReflexResponse`. This method is the
    // requester side: send an empty-body request, await the
    // pending-oneshot, return the observed `SocketAddr`.
    //
    // Remember: reflex discovery is an optimization, not a
    // connectivity guarantee. A `ReflexTimeout` or `PeerNotReachable`
    // doesn't mean the peers can't talk; it means this specific
    // address-discovery path didn't resolve.

    /// Send one reflex probe to `peer_node_id` and return the
    /// public `SocketAddr` the peer observed on the probe's UDP
    /// envelope.
    ///
    /// Waits up to [`super::traversal::TraversalConfig::reflex_timeout`] (default
    /// 3 s) for the response. Fails with [`super::traversal::TraversalError::ReflexTimeout`]
    /// on timeout, [`super::traversal::TraversalError::PeerNotReachable`] if the peer
    /// has no active session, or [`super::traversal::TraversalError::Transport`] on
    /// a socket-level send failure.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub async fn probe_reflex(
        &self,
        peer_node_id: u64,
    ) -> Result<std::net::SocketAddr, super::traversal::TraversalError> {
        use super::traversal::{reflex, TraversalError};

        let peer_addr = self
            .peer_addrs
            .get(&peer_node_id)
            .map(|e| *e.value())
            .ok_or(TraversalError::PeerNotReachable)?;

        // Install the pending-oneshot BEFORE sending so an
        // improbably-fast response can still complete it. A
        // previously-in-flight probe to the same peer is
        // overwritten — its waiter will hit ReflexTimeout, which
        // matches the "one probe per peer in flight" contract.
        //
        // Stamp each waiter with a unique generation so our
        // timeout cleanup only evicts *our* entry, not a racing
        // replacement. See `next_waiter_gen` doc for the race.
        let (tx, rx) = oneshot::channel();
        let gen = self
            .next_waiter_gen
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        self.pending_reflex_probes.insert(peer_node_id, (gen, tx));

        // Empty-body event frame on the reflex subprotocol.
        let body = reflex::encode_request();
        if let Err(e) = self
            .send_subprotocol(peer_addr, super::traversal::SUBPROTOCOL_REFLEX, &body)
            .await
        {
            self.pending_reflex_probes
                .remove_if(&peer_node_id, |_, (g, _)| *g == gen);
            return Err(TraversalError::Transport(e.to_string()));
        }

        let timeout = self.traversal_config.reflex_timeout;
        match tokio::time::timeout(timeout, rx).await {
            Ok(Ok(addr)) => Ok(addr),
            Ok(Err(_recv_err)) => {
                // oneshot cancelled — treat as timeout. Only
                // happens if a concurrent probe to the same peer
                // replaced our sender; the replacement owns the
                // map entry now and we must NOT touch it.
                Err(TraversalError::ReflexTimeout)
            }
            Err(_elapsed) => {
                self.pending_reflex_probes
                    .remove_if(&peer_node_id, |_, (g, _)| *g == gen);
                Err(TraversalError::ReflexTimeout)
            }
        }
    }

    /// The current NAT classification for this node. `Unknown`
    /// until the classification sweep has run; updated atomically
    /// by the sweep and by [`Self::reclassify_nat`]. Read-only for
    /// external callers — the sweep is the only writer.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub fn nat_class(&self) -> super::traversal::classify::NatClass {
        super::traversal::classify::NatClass::from_u8(
            self.nat_class.load(std::sync::atomic::Ordering::Acquire),
        )
    }

    /// This node's public-facing `SocketAddr` as observed by a
    /// remote peer during the classification sweep. `None` before
    /// the first sweep has produced an observation. Exposed
    /// primarily for tests + observability; the announce-
    /// capabilities path piggybacks this value onto every signed
    /// `CapabilityAnnouncement`.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub fn reflex_addr(&self) -> Option<std::net::SocketAddr> {
        self.reflex_addr.load_full().map(|arc| *arc)
    }

    /// Install a runtime reflex override. Forces `nat_class =
    /// Open` and `reflex_addr = Some(external)` immediately, and
    /// short-circuits any further classifier sweeps until
    /// [`Self::clear_reflex_override`] is called.
    ///
    /// # Publishing to peers
    ///
    /// This method updates only *local* state. To propagate the
    /// change to peers, call [`Self::announce_capabilities`]
    /// afterward. The setter resets the announce rate-limit
    /// floor so the next announce is guaranteed to broadcast
    /// rather than coalesce against the previous send — cubic
    /// P2 pinned this, after flagging that callers who set an
    /// override within `min_announce_interval` of a prior
    /// announce would find peers still seeing the old reflex.
    ///
    /// **Optimization, not correctness.** A node with no override
    /// still reaches every peer through the routed-handshake
    /// path; the override just pins the publicly-advertised
    /// address when it's already known (port-forwarded server, a
    /// successful stage-4 port-mapping install, etc).
    ///
    /// Safe to call concurrently with `announce_capabilities` —
    /// the triple-write runs under `traversal_publish_mu`
    /// (alongside the announce's multi-field read), so a
    /// concurrent announce either sees the pre-override state
    /// or the fully-installed override, never a torn mix.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub fn set_reflex_override(&self, external: SocketAddr) {
        use std::sync::atomic::Ordering;
        // Hold the publication mutex across the triple-write.
        // Without it, a concurrent `announce_capabilities_with`
        // could interleave its two reads between our three
        // writes and publish a torn state (e.g. the new reflex
        // paired with the pre-override NAT class). The mutex is
        // briefly contended only with other override writers or
        // the announce multi-field read; single-field readers
        // stay lock-free.
        let _g = self.traversal_publish_mu.lock();
        self.reflex_addr.store(Some(Arc::new(external)));
        self.nat_class.store(
            super::traversal::classify::NatClass::Open.as_u8(),
            Ordering::Release,
        );
        self.reflex_override_active.store(true, Ordering::Release);

        // Reset the rate-limit floor so the next
        // `announce_capabilities` call is guaranteed to
        // broadcast — cubic P2 flagged that the override
        // setter's doc implies immediate peer visibility, but
        // the rate limit could coalesce an announce that lands
        // inside `min_announce_interval`. Callers that want
        // peers to see the new reflex "right away" still need
        // to call announce themselves; this just makes that
        // call's broadcast step unconditional instead of
        // coalesced. Cancel any pending trailing-edge flush in
        // the same lock (RT-1 review follow-up): the caller's
        // documented next announce supersedes it, and letting it
        // fire too would put a second broadcast inside the fresh
        // window. The parked flush task no-ops when it finds the
        // slot cleared.
        {
            let mut gate = self.announce_gate.lock();
            gate.last_broadcast_at = None;
            gate.deferred_scheduled = false;
        }
    }

    /// Drop a previously-installed runtime reflex override. The
    /// classifier sweep resumes on its normal cadence; the next
    /// sweep repopulates `reflex_addr` and `nat_class` from real
    /// probe observations. `reflex_addr` is cleared to `None`
    /// immediately so a between-sweep read doesn't return a stale
    /// override value as "still current."
    ///
    /// # Publishing to peers
    ///
    /// Mirrors [`Self::set_reflex_override`]: only local state
    /// changes here. Call [`Self::announce_capabilities`] after
    /// this to tell peers. The rate-limit floor is reset so that
    /// call broadcasts unconditionally.
    ///
    /// No-op when no override is active — safe to call
    /// unconditionally during shutdown / port-mapping revoke
    /// paths.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub fn clear_reflex_override(&self) {
        use std::sync::atomic::Ordering;
        // Hold the publication mutex across the flag flip + the
        // field resets so a concurrent announce can't observe
        // the cleared flag alongside the not-yet-reset reflex /
        // NAT class (or vice versa). Same invariant as in
        // `set_reflex_override`.
        let _g = self.traversal_publish_mu.lock();
        if !self.reflex_override_active.swap(false, Ordering::AcqRel) {
            return;
        }
        // Reset reflex_addr + nat_class to their pre-classification
        // defaults so a caller reading immediately gets an honest
        // "no current observation" answer rather than the stale
        // override.
        self.reflex_addr.store(None);
        self.nat_class.store(
            super::traversal::classify::NatClass::Unknown.as_u8(),
            Ordering::Release,
        );
        // Same rate-limit reset as `set_reflex_override` — the
        // next `announce_capabilities` call broadcasts
        // unconditionally instead of coalescing against the
        // previous send, and a pending trailing-edge flush is
        // canceled for the same reason. See that method's
        // comment for details (cubic P2 + RT-1 follow-up).
        {
            let mut gate = self.announce_gate.lock();
            gate.last_broadcast_at = None;
            gate.deferred_scheduled = false;
        }
    }

    /// Reflex-diff re-classification trigger
    /// (`NAT_TRAVERSAL_V2_PLAN.md` decision 8, trigger 2). Called by
    /// the capability re-announce loop before each periodic announce:
    /// if the currently-observed reflex differs from the one in the
    /// last *published* announcement, run exactly one classification
    /// sweep first so the `nat:*` tag and the reflex field ship
    /// together — a reflex that drifted since the last sweep (probe /
    /// punch activity, gateway reboot) usually means the class is
    /// stale too.
    ///
    /// Returns `true` iff a sweep ran. Deliberately conservative —
    /// all of these skip (no sweep, `false`):
    /// - an active reflex override (it pins `(class, reflex)`; the
    ///   sweep would be short-circuited anyway),
    /// - no prior published announcement (the initial announce path
    ///   owns the first pair),
    /// - no current observation (`reflex_addr = None` — the classify
    ///   loop owns first population; announcing `None` is honest),
    /// - observed == published (the no-flap cadence guard: steady
    ///   state must not add sweeps to the re-announce tick).
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub async fn reclassify_if_reflex_drifted(&self) -> bool {
        use std::sync::atomic::Ordering as AtOrd;
        if self.reflex_override_active.load(AtOrd::Acquire) {
            return false;
        }
        let Some(published) = self.local_announcement.load_full() else {
            return false;
        };
        let Some(observed) = self.reflex_addr() else {
            return false;
        };
        if published.reflex_addr == Some(observed) {
            return false;
        }
        self.reclassify_nat().await;
        true
    }

    /// Testing hook: overwrite the observed reflex WITHOUT the
    /// override pin (unlike [`Self::set_reflex_override`], which pins
    /// `(class, reflex)` and short-circuits the classifier). Lets
    /// tests simulate a between-announce reflex drift — something a
    /// real deployment gets from probe/punch observations after a
    /// gateway reboot, and loopback can never produce naturally —
    /// so the reflex-diff trigger has something to reconcile. Runs
    /// under `traversal_publish_mu` like every multi-field traversal
    /// write.
    #[cfg(feature = "nat-traversal")]
    #[doc(hidden)]
    pub fn set_reflex_for_test(&self, addr: SocketAddr) {
        let _g = self.traversal_publish_mu.lock();
        self.reflex_addr.store(Some(Arc::new(addr)));
    }

    /// Testing / debugging hook: force this node's advertised
    /// `NatClass` without running the probe sweep. On loopback
    /// every node classifies as `Open`, which means the pair-type
    /// matrix always picks `Direct` — useful for Open×Open cases
    /// but leaves the `SinglePunch` path unexercised. Regression
    /// tests that need to drive `connect_direct` through the
    /// punch branch set this to `Cone` (or `Symmetric`) before
    /// calling `announce_capabilities`, then the peer reads it
    /// back via `peer_nat_class` and the matrix resolves to
    /// `SinglePunch`.
    ///
    /// Not for production use: the classifier is the intended
    /// writer, and forcing a class short-circuits real NAT
    /// observation. Exposed as `pub` (not `pub(crate)`) only so
    /// `tests/connect_direct.rs` can reach it from a separate
    /// crate.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    #[doc(hidden)]
    pub fn force_nat_class_for_test(&self, class: super::traversal::classify::NatClass) {
        self.nat_class.store(class.as_u8(), Ordering::Release);
    }

    /// Test / debug accessor for the most-recent local
    /// capability announcement. Returns `None` until the first
    /// `announce_capabilities*` call. The stored value is the
    /// coherent snapshot published by
    /// [`Self::announce_capabilities_with`] under
    /// `traversal_publish_mu` — regression tests for the
    /// (class, reflex_addr) race read this instead of the
    /// separate atomic accessors, which are lock-free and can
    /// return torn pairs under concurrent mutation.
    #[doc(hidden)]
    pub fn local_announcement_for_test(&self) -> Option<Arc<CapabilityAnnouncement>> {
        self.local_announcement.load_full()
    }

    /// Send a `PunchRequest` to a coordinator peer `relay`, asking
    /// it to mediate a hole-punch to `target`. Returns the
    /// `PunchIntroduce` produced by the coordinator (the one
    /// arriving on this node's side of the introduction — carrying
    /// `target`'s reflex and the shared `fire_at`).
    ///
    /// This is a stage-3b primitive: it exercises the coordinator
    /// fan-out end-to-end but does not itself schedule the
    /// keep-alive train or finalize the punched session. The
    /// full `connect_direct` flow lands in stage 3c.
    ///
    /// Fails with:
    /// - [`super::traversal::TraversalError::PeerNotReachable`] if `relay` has no
    ///   active session.
    /// - [`super::traversal::TraversalError::Transport`] on a socket-level send
    ///   failure.
    /// - [`super::traversal::TraversalError::RendezvousRejected`] if the
    ///   coordinator refused with a typed `PunchReject` (rate-limited, no
    ///   cached target reflex, no session with the target, or the
    ///   anti-reflection check failed). This resolves *immediately* — no
    ///   `punch_deadline` wait — and carries the reason sub-kind.
    /// - [`super::traversal::TraversalError::PunchFailed`] if the coordinator
    ///   neither introduced nor rejected within
    ///   [`super::traversal::TraversalConfig::punch_deadline`].
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub async fn request_punch(
        &self,
        relay: u64,
        target: u64,
        self_reflex: std::net::SocketAddr,
    ) -> Result<super::traversal::rendezvous::PunchIntroduce, super::traversal::TraversalError>
    {
        use super::traversal::rendezvous::{PunchRequest, RendezvousMsg};
        use super::traversal::TraversalError;

        let relay_addr = self
            .peer_addrs
            .get(&relay)
            .map(|e| *e.value())
            .ok_or(TraversalError::PeerNotReachable)?;

        // Install the waiter BEFORE sending. An improbably fast
        // coordinator response (R is local, A is local) could
        // otherwise arrive before the oneshot is registered.
        // Keyed by `target` because the introduce we'll receive
        // has `peer = target` in its body.
        //
        // Generation-stamped so our cleanup only evicts our own
        // entry — a concurrent `request_punch` to the same
        // target installs a new entry (and drops our sender),
        // and that replacement must survive our timeout/send-
        // failure remove.
        let (tx, rx) = oneshot::channel();
        let gen = self
            .next_waiter_gen
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        // Wire correlation token, echoed by any PunchReject this
        // request draws. Skip the reserved 0 sentinel on wrap.
        let punch_id = {
            let mut id = self
                .next_punch_id
                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
            if id == 0 {
                id = self
                    .next_punch_id
                    .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
            }
            id
        };
        // Bind to the relay we're sending PunchRequest to — only
        // that node is authorized to send the matching introduce
        // back. Without this, any session peer could forge a
        // PunchIntroduce for `target` and complete this oneshot
        // with attacker-chosen reflex data.
        self.pending_punch_introduces
            .insert(target, (gen, relay, punch_id, tx));

        let body = RendezvousMsg::PunchRequest(PunchRequest {
            target,
            punch_id,
            self_reflex,
        })
        .encode();
        if let Err(e) = self
            .send_subprotocol(relay_addr, super::traversal::SUBPROTOCOL_RENDEZVOUS, &body)
            .await
        {
            self.pending_punch_introduces
                .remove_if(&target, |_, (g, _, _, _)| *g == gen);
            return Err(TraversalError::Transport(e.to_string()));
        }

        let deadline = self.traversal_config.punch_deadline;
        match tokio::time::timeout(deadline, rx).await {
            Ok(Ok(PunchIntroduceOutcome::Introduce(intro))) => Ok(intro),
            Ok(Ok(PunchIntroduceOutcome::Rejected(reason))) => {
                // Coordinator refused with a typed reason — fast,
                // non-timeout failure (Finding 5). The waiter was
                // removed by the dispatch arm that delivered the
                // reject; nothing to clean up here.
                self.traversal_stats.record_punch_rejection();
                Err(TraversalError::RendezvousRejected(
                    reason.kind().to_string(),
                ))
            }
            Ok(Err(_recv_err)) => {
                // oneshot cancelled — another request_punch to the
                // same target replaced our sender. Don't touch the
                // map: the replacement owns the entry now. Not a
                // timeout — no reason counter (stage 5): the
                // superseding call does its own accounting.
                Err(TraversalError::PunchFailed)
            }
            Err(_elapsed) => {
                self.pending_punch_introduces
                    .remove_if(&target, |_, (g, _, _, _)| *g == gen);
                self.traversal_stats.record_punch_timeout();
                Err(TraversalError::PunchFailed)
            }
        }
    }

    /// Install a waiter for an incoming `PunchIntroduce` from
    /// `counterpart`, brokered by `coordinator`. The dispatch arm
    /// admits the introduce only when the session peer matches
    /// `coordinator`. The returned future resolves when the
    /// dispatcher decodes a matching introduce, or with
    /// [`super::traversal::TraversalError::PunchFailed`] after
    /// [`super::traversal::TraversalConfig::punch_deadline`].
    ///
    /// Stage-3b responder-side primitive: the peer being punched
    /// *into* uses this to observe the introduce without
    /// initiating the flow itself. The responder must know which
    /// coordinator will forward the introduce — supply that node's
    /// id as `coordinator`. Stage 3c wires the keep-alive train
    /// onto the returned introduce.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub async fn await_punch_introduce(
        &self,
        counterpart: u64,
        coordinator: u64,
    ) -> Result<super::traversal::rendezvous::PunchIntroduce, super::traversal::TraversalError>
    {
        use super::traversal::TraversalError;
        let (tx, rx) = oneshot::channel();
        let gen = self
            .next_waiter_gen
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        self.pending_punch_introduces
            .insert(counterpart, (gen, coordinator, 0, tx));
        let deadline = self.traversal_config.punch_deadline;
        match tokio::time::timeout(deadline, rx).await {
            Ok(Ok(PunchIntroduceOutcome::Introduce(intro))) => Ok(intro),
            Ok(Ok(PunchIntroduceOutcome::Rejected(reason))) => {
                self.traversal_stats.record_punch_rejection();
                Err(TraversalError::RendezvousRejected(
                    reason.kind().to_string(),
                ))
            }
            Ok(Err(_)) => Err(TraversalError::PunchFailed),
            Err(_) => {
                self.pending_punch_introduces
                    .remove_if(&counterpart, |_, (g, _, _, _)| *g == gen);
                self.traversal_stats.record_punch_timeout();
                Err(TraversalError::PunchFailed)
            }
        }
    }

    /// Install a waiter for an incoming `PunchAck` whose
    /// `from_peer` matches `counterpart`. Stage-3d correlation
    /// surface — the `SinglePunch` path in `connect_direct`
    /// registers the waiter before firing `request_punch` and
    /// awaits it afterward. Times out with
    /// [`super::traversal::TraversalError::PunchFailed`] after
    /// [`super::traversal::TraversalConfig::punch_deadline`].
    ///
    /// Note: the caller inserts the oneshot sender into
    /// `pending_punch_acks` before issuing the request so the ack
    /// can't arrive and be dropped before the await call is
    /// entered.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub async fn await_punch_ack(
        &self,
        counterpart: u64,
        coordinator: u64,
    ) -> Result<super::traversal::rendezvous::PunchAck, super::traversal::TraversalError> {
        use super::traversal::TraversalError;
        let (tx, rx) = oneshot::channel();
        let gen = self
            .next_waiter_gen
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        self.pending_punch_acks
            .insert(counterpart, (gen, coordinator, tx));
        let deadline = self.traversal_config.punch_deadline;
        match tokio::time::timeout(deadline, rx).await {
            Ok(Ok(ack)) => Ok(ack),
            Ok(Err(_)) => Err(TraversalError::PunchFailed),
            Err(_) => {
                self.pending_punch_acks
                    .remove_if(&counterpart, |_, (g, _, _)| *g == gen);
                Err(TraversalError::PunchFailed)
            }
        }
    }

    /// Fire the classification sweep. Picks up to two currently-
    /// connected peers, runs [`Self::probe_reflex`] against each in
    /// parallel, feeds the observations to
    /// [`super::traversal::classify::ClassifyFsm`], and updates
    /// `nat_class` + `reflex_addr` with the result.
    ///
    /// Runs at most one *sweep* at a time — a second `reclassify_nat`
    /// call while a sweep is in flight is a no-op (the `SweepGuard`
    /// at the top of the body). The gate is sweep-level only: a
    /// standalone [`Self::probe_reflex`] — e.g. the
    /// `net_mesh_probe_reflex` FFI — is *not* gated and can still race
    /// a sweep's probe to the same peer (a benign collision; see the
    /// gate comment in the body). Exits early if fewer than 2
    /// peers are currently connected; callers should check
    /// [`Self::nat_class`] after the returned future completes to
    /// see whether classification produced a definite verdict or
    /// stayed at `Unknown`.
    ///
    /// Bounded by [`super::traversal::TraversalConfig::classify_deadline`] — even if
    /// probes hang, the sweep returns within that window with
    /// whatever observations arrived.
    ///
    /// Requires the `nat-traversal` cargo feature.
    #[cfg(feature = "nat-traversal")]
    pub async fn reclassify_nat(&self) {
        use super::traversal::classify::ClassifyFsm;

        // Single-flight gate (doc contract: "at most one sweep at a
        // time"). `reclassify_nat` is `pub` + FFI-exported, so an
        // operator call can race the background classify loop's tick
        // (or another operator call). Concurrent sweeps collide on
        // `pending_reflex_probes` — keyed by peer id, the later
        // probe insert drops the earlier sweep's oneshot and starves
        // it. A second concurrent entry is a no-op; the RAII guard
        // clears the flag on every exit path below.
        //
        // Scope: this gate serializes *sweeps* against each other, not
        // the `pending_reflex_probes` map itself. A standalone
        // `probe_reflex` (the `net_mesh_probe_reflex` FFI) doesn't take
        // the gate, so it can still race a sweep's probe to the same
        // peer and cancel one of them. That residual is benign: probe
        // waiters are generation-stamped (cleanup can't evict a
        // replacement), the loser just gets `ReflexTimeout`, and the
        // <2-observation guard (Finding B2) keeps a sweep that drops a
        // probe this way on its prior class instead of flapping to
        // Unknown.
        let Some(_sweep) = SweepGuard::try_enter(&self.nat_classifying) else {
            return;
        };

        // Reflex-override short-circuit: an operator-set (or
        // port-mapping installed) external address already tells
        // us everything the classifier would: NAT type is Open,
        // reflex is the override. Running the multi-peer probe
        // sweep would only replace the overridden values with
        // (possibly worse) observations — skip it.
        if self
            .reflex_override_active
            .load(std::sync::atomic::Ordering::Acquire)
        {
            return;
        }

        // Snapshot up to two peers. Two is enough to distinguish
        // Cone vs. Symmetric (plan §2); sampling more adds probe
        // traffic for no classification gain.
        //
        // Caveat (code review 2026-06-21, Finding B4): symmetric-NAT
        // detection assumes the two peers are distinct *destinations*
        // (different public IPs). Two node ids resolving to the same
        // host/IP look like one destination to the NAT, so a
        // symmetric NAT keyed on dest IP could hand out the same port
        // for both and be misread as Cone. Low-probability on a real
        // mesh, and it only affects the Cone-vs-Symmetric distinction
        // — a misread still falls back to the routed path on punch
        // failure.
        let peers: Vec<u64> = self.peers.iter().map(|e| *e.key()).take(2).collect();
        if peers.len() < 2 {
            return;
        }

        // Fire probes in parallel so the sweep finishes in one
        // reflex_timeout window rather than N*timeout. Each probe
        // already respects its own timeout via `probe_reflex`.
        let bind = self.local_addr();
        let futures = peers.iter().copied().map(|peer| async move {
            let res = self.probe_reflex(peer).await;
            (peer, res)
        });
        let deadline = self.traversal_config.classify_deadline;
        let results = match tokio::time::timeout(deadline, futures::future::join_all(futures)).await
        {
            Ok(results) => results,
            Err(_elapsed) => {
                // Classification-deadline blown. Leave current
                // classification untouched — a later sweep can
                // retry; treating deadline-expired as "Unknown"
                // would flap state on a temporarily slow link.
                tracing::debug!("nat-traversal: classify_deadline elapsed, keeping prior state");
                return;
            }
        };

        let mut fsm = ClassifyFsm::new();
        let mut latest_reflex: Option<std::net::SocketAddr> = None;
        for (peer, res) in results {
            if let Ok(addr) = res {
                fsm.observe(peer, addr);
                latest_reflex = Some(addr);
            }
        }

        let class = fsm.classify(bind);
        self.commit_reclassify_observations(class, latest_reflex, fsm.observation_count());
    }

    /// Commit the result of a classification sweep.
    ///
    /// Split out from [`Self::reclassify_nat`] so the
    /// override-race guard is unit-testable without standing up
    /// a full probe mesh. The guard fixes a cubic-flagged P1
    /// bug: the entry-time check in `reclassify_nat` races with
    /// any `set_reflex_override` call that lands *during* the
    /// probe sweep — the flag flips false→true while we're
    /// awaiting probe futures, and a blind commit would silently
    /// stomp the fresh override with whatever the classifier
    /// observed. A port-mapping install is a strong signal (we
    /// have a known-public `external` address) that outranks
    /// peer-probed reflex; clobbering it would demote the node
    /// from Open back to whatever NAT class the probes inferred
    /// and could re-advertise the wrong reflex to peers.
    #[cfg(feature = "nat-traversal")]
    fn commit_reclassify_observations(
        &self,
        class: super::traversal::classify::NatClass,
        latest_reflex: Option<std::net::SocketAddr>,
        observation_count: usize,
    ) {
        use std::sync::atomic::Ordering;
        // Hold the publication mutex across the re-check + the
        // (potentially) paired writes. This both makes the
        // override mid-sweep guard atomic with the commit
        // (no TOCTOU on the flag vs stores), and serializes
        // against concurrent `announce_capabilities_with` reads
        // so the classifier can't publish nat_class without
        // reflex_addr (or vice versa) being visible together.
        let _g = self.traversal_publish_mu.lock();
        if self.reflex_override_active.load(Ordering::Acquire) {
            tracing::debug!("nat-traversal: reflex override installed mid-sweep, skipping commit");
            return;
        }
        // Insufficient-observations guard (code review 2026-06-21,
        // Finding B2). `classify` returns `Unknown` below two
        // observations; publishing that would flap a previously-good
        // Cone/Open down to Unknown on nothing more than transient
        // packet loss (one of the two probes dropped). That's the same
        // flap the deadline-expired branch in `reclassify_nat`
        // deliberately avoids — so apply the same policy here: keep
        // the prior (class, reflex) pair and let a later two-response
        // sweep install a fresh one.
        if observation_count < 2 {
            tracing::debug!(
                observation_count,
                "nat-traversal: fewer than 2 probe observations this sweep, keeping prior pair"
            );
            return;
        }
        // No-reflex guard (defense-in-depth). For coherent inputs from
        // `reclassify_nat` the <2-observation guard above already
        // subsumes this case: an all-probes-failed sweep has
        // `observation_count == 0`, and any sweep with
        // `observation_count >= 2` necessarily threaded a
        // `latest_reflex` (it is set on every `fsm.observe`). This
        // guard remains for a *torn* input — a caller passing
        // `observation_count >= 2` with `latest_reflex == None` — so
        // the commit never publishes a `nat_class` without a paired
        // reflex (the `traversal_publish_mu` coherence invariant a
        // downstream `announce_capabilities_with` reader relies on).
        // Same policy as the deadline-expired branch in
        // `reclassify_nat`: leave the previously-published pair
        // untouched. Pinned by
        // `commit_keeps_prior_on_torn_class_without_reflex`.
        let Some(addr) = latest_reflex else {
            tracing::debug!(
                "nat-traversal: no probe observations this sweep, keeping prior (class, reflex) pair"
            );
            return;
        };
        self.nat_class.store(class.as_u8(), Ordering::Release);
        self.reflex_addr.store(Some(Arc::new(addr)));
        tracing::debug!(
            nat_class = ?class,
            reflex = ?addr,
            "nat-traversal: reclassified",
        );
    }
}

// ── Adapter trait impl ──────────────────────────────────────────────────

#[async_trait]
impl Adapter for MeshNode {
    async fn init(&mut self) -> Result<(), AdapterError> {
        // MeshNode is initialized via new() + connect(). This is a no-op.
        Ok(())
    }

    async fn on_batch(&self, batch: std::sync::Arc<Batch>) -> Result<(), AdapterError> {
        // Send to the first connected peer. For a real mesh, this should
        // use the routing table to pick the right peer based on the
        // event's destination. For now, round-robin or first-match.
        let peer_addr = self
            .peers
            .iter()
            .next()
            .map(|e| e.value().addr)
            .ok_or_else(|| AdapterError::Connection("no peers connected".into()))?;

        self.send_to_peer(peer_addr, &batch).await
    }

    async fn flush(&self) -> Result<(), AdapterError> {
        Ok(())
    }

    async fn shutdown(&self) -> Result<(), AdapterError> {
        self.shutdown.store(true, Ordering::Release);
        self.shutdown_notify.notify_waiters();
        self.router.stop();

        // Deactivate all sessions
        for entry in self.peers.iter() {
            entry.value().session.deactivate();
        }

        // Wait for background tasks
        let tasks = std::mem::take(&mut *self.tasks.lock().await);
        for handle in tasks {
            let _ = handle.await;
        }

        Ok(())
    }

    async fn poll_shard(
        &self,
        shard_id: u16,
        from_id: Option<&str>,
        limit: usize,
    ) -> Result<ShardPollResult, AdapterError> {
        let queue = match self.inbound.get(&shard_id) {
            Some(q) => q,
            None => return Ok(ShardPollResult::empty()),
        };

        let mut events = Vec::with_capacity(limit.min(1000));
        let mut last_id = None;
        // from_id is ignored — the SegQueue is consume-once, so every pop
        // removes the event permanently. Cursor-based skipping would destroy
        // events that have already been consumed. Callers should consume
        // from the head without a cursor.
        let _ = from_id;

        for _ in 0..limit {
            match queue.pop() {
                Some(event) => {
                    last_id = Some(event.id.clone());
                    events.push(event);
                }
                None => break,
            }
        }

        let has_more = !queue.is_empty();

        Ok(ShardPollResult {
            events,
            next_id: last_id,
            has_more,
        })
    }

    fn name(&self) -> &'static str {
        "mesh"
    }

    async fn is_healthy(&self) -> bool {
        self.started.load(Ordering::Acquire) && !self.peers.is_empty()
    }
}

impl Drop for MeshNode {
    fn drop(&mut self) {
        self.shutdown.store(true, Ordering::Release);
        self.shutdown_notify.notify_waiters();
        self.router.stop();
    }
}

#[cfg(all(test, feature = "nat-traversal"))]
mod punch_observer_tests {
    //! Tests for [`await_punch_observer_outcome`].
    //!
    //! Regression coverage for a cubic-flagged bug (P2): earlier
    //! revisions collapsed the `Ok(Err(_))` (sender dropped) and
    //! `Err(_)` (deadline) arms into a single `remove`-in-both
    //! branch, which evicted replacement observers. Each test
    //! below pins one of the three outcomes independently.
    use super::*;
    use crate::adapter::net::traversal::rendezvous::Keepalive;
    use tokio::sync::oneshot;

    fn sample_ka() -> Keepalive {
        Keepalive {
            sender_node_id: 0x1234,
            punch_id: 0,
        }
    }

    fn sample_peer() -> SocketAddr {
        "198.51.100.5:9001".parse().unwrap()
    }

    /// Expected counterpart node id stored alongside each observer.
    /// `await_punch_observer_outcome` itself doesn't validate it —
    /// the receive loop's `remove_if` does that before firing — so
    /// these cleanup-semantics tests just need a stable value.
    const EXPECTED_PEER: u64 = 0x1234;

    /// Keep-alive fires before the deadline — outcome is `true`
    /// (caller emits the ack). The map entry was consumed by the
    /// receive loop's sender-validated `remove_if` when it fired the
    /// oneshot, so the helper doesn't need to remove anything.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn fires_true_when_keepalive_arrives() {
        let observers: DashMap<SocketAddr, (u64, oneshot::Sender<Keepalive>)> = DashMap::new();
        let peer = sample_peer();
        let (tx, rx) = oneshot::channel();
        observers.insert(peer, (EXPECTED_PEER, tx));

        // Simulate the receive loop firing the oneshot after its
        // sender-id check passes: remove from the map + send the ka.
        let (_, (_id, fired_tx)) = observers.remove(&peer).unwrap();
        fired_tx.send(sample_ka()).expect("send");

        let result =
            await_punch_observer_outcome(rx, Duration::from_secs(1), &observers, peer).await;
        assert!(result, "keepalive arrival should return true");
    }

    /// Deadline expires while our sender is still the live value
    /// in the map — helper must evict the stale entry so a late
    /// keep-alive doesn't find it.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn timeout_evicts_own_stale_entry() {
        let observers: DashMap<SocketAddr, (u64, oneshot::Sender<Keepalive>)> = DashMap::new();
        let peer = sample_peer();
        let (tx, rx) = oneshot::channel();
        observers.insert(peer, (EXPECTED_PEER, tx));

        // Very short deadline; nobody fires.
        let result =
            await_punch_observer_outcome(rx, Duration::from_millis(50), &observers, peer).await;
        assert!(!result, "timeout should return false");
        assert!(
            !observers.contains_key(&peer),
            "timeout should evict our own stale entry",
        );
    }

    /// The cubic-flagged regression: a newer observer replaces
    /// ours (our sender is dropped). Our task's `Ok(Err(_))` arm
    /// must **not** remove the peer_reflex key — it would evict
    /// the replacement observer that's the current live value
    /// in the map.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn sender_dropped_leaves_replacement_observer_intact() {
        let observers: DashMap<SocketAddr, (u64, oneshot::Sender<Keepalive>)> = DashMap::new();
        let peer = sample_peer();

        // Install observer A.
        let (tx_a, rx_a) = oneshot::channel::<Keepalive>();
        observers.insert(peer, (EXPECTED_PEER, tx_a));

        // Install observer B via insert — this drops A's sender
        // (the old value returned from the insert is dropped
        // immediately). Now the map contains B's sender.
        let (tx_b, _rx_b) = oneshot::channel::<Keepalive>();
        observers.insert(peer, (EXPECTED_PEER, tx_b));
        assert!(observers.contains_key(&peer), "B's sender in map");

        // A's task runs the cleanup helper. A's rx_a sees
        // RecvError (tx_a dropped), outcome is `Ok(Err(_))`.
        let result =
            await_punch_observer_outcome(rx_a, Duration::from_secs(5), &observers, peer).await;
        assert!(!result, "sender-dropped path returns false");
        assert!(
            observers.contains_key(&peer),
            "B's sender must still be in the map — A's cleanup must not evict",
        );
    }

    /// Idempotent-by-peer check: after a timeout-eviction,
    /// removing again is a no-op. Prevents a hypothetical
    /// double-eviction regression where the helper called
    /// `remove` on every cleanup path.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn timeout_then_sender_drop_does_not_double_evict() {
        let observers: DashMap<SocketAddr, (u64, oneshot::Sender<Keepalive>)> = DashMap::new();
        let peer = sample_peer();

        // First task: install A, let it time out, evict.
        let (tx_a, rx_a) = oneshot::channel::<Keepalive>();
        observers.insert(peer, (EXPECTED_PEER, tx_a));
        let r1 =
            await_punch_observer_outcome(rx_a, Duration::from_millis(20), &observers, peer).await;
        assert!(!r1);
        assert!(!observers.contains_key(&peer));

        // Second task: install B, drop B's sender via a fresh
        // insert from C — simulates the "replacement" scenario
        // but now for a different observer lineage.
        let (tx_b, rx_b) = oneshot::channel::<Keepalive>();
        observers.insert(peer, (EXPECTED_PEER, tx_b));
        let (tx_c, _rx_c) = oneshot::channel::<Keepalive>();
        observers.insert(peer, (EXPECTED_PEER, tx_c));

        // B's task cleanup. Must NOT remove peer (C is live).
        let r2 = await_punch_observer_outcome(rx_b, Duration::from_secs(5), &observers, peer).await;
        assert!(!r2);
        assert!(
            observers.contains_key(&peer),
            "C's sender must remain after B's sender-dropped cleanup",
        );
    }
}

#[cfg(all(test, feature = "nat-traversal"))]
mod keepalive_offset_tests {
    //! Unit coverage for [`keepalive_send_offsets`] (code review
    //! 2026-06-21, Finding 3): the per-packet send schedule must
    //! clamp a coordinator-supplied `fire_at_ms` so a far-future
    //! value can't park the keep-alive sender task indefinitely or
    //! overflow `Instant`.
    use super::keepalive_send_offsets;
    use std::time::Duration;

    const DEADLINE: Duration = Duration::from_secs(5);

    #[test]
    fn normal_lead_is_preserved_with_documented_spacing() {
        // fire_at 500 ms in the future → 500 / 600 / 750 ms.
        let offsets = keepalive_send_offsets(1_000_500, 1_000_000, DEADLINE);
        assert_eq!(offsets[0], Duration::from_millis(500));
        assert_eq!(offsets[1], Duration::from_millis(600));
        assert_eq!(offsets[2], Duration::from_millis(750));
    }

    #[test]
    fn past_fire_at_collapses_to_immediate() {
        // fire_at already elapsed → base lead 0; spacing still applies.
        let offsets = keepalive_send_offsets(900_000, 1_000_000, DEADLINE);
        assert_eq!(offsets[0], Duration::ZERO);
        assert_eq!(offsets[1], Duration::from_millis(100));
        assert_eq!(offsets[2], Duration::from_millis(250));
    }

    #[test]
    fn far_future_fire_at_is_clamped_to_deadline() {
        // A malicious/buggy coordinator names a fire time ~1e9 s out.
        // The base lead must clamp to `deadline`, bounding the sender
        // task's lifetime rather than parking it for ~31 years.
        let offsets = keepalive_send_offsets(1_000_000 + 1_000_000_000_000, 1_000_000, DEADLINE);
        assert_eq!(offsets[0], DEADLINE, "base lead must clamp to deadline");
        // Spacing applies after the clamp; bounded just past it.
        assert_eq!(offsets[1], DEADLINE + Duration::from_millis(100));
        assert_eq!(offsets[2], DEADLINE + Duration::from_millis(250));
    }

    #[test]
    fn u64_max_fire_at_does_not_panic_and_clamps() {
        // Extreme input: must neither panic on the millis→Duration
        // conversion nor exceed the clamp.
        let offsets = keepalive_send_offsets(u64::MAX, 0, DEADLINE);
        assert_eq!(offsets[0], DEADLINE);
        assert!(offsets[2] <= DEADLINE + Duration::from_millis(250));
    }
}

#[cfg(all(test, feature = "nat-traversal"))]
mod sweep_guard_tests {
    //! Unit coverage for [`SweepGuard`] (code review 2026-06-21,
    //! port-scanning Finding B1): the single-flight gate that backs
    //! `reclassify_nat`'s "at most one sweep at a time" contract.
    use super::SweepGuard;
    use std::sync::atomic::AtomicBool;

    #[test]
    fn try_enter_is_single_flight_and_releases_on_drop() {
        let flag = AtomicBool::new(false);

        let g1 = SweepGuard::try_enter(&flag);
        assert!(g1.is_some(), "first entry must acquire the gate");
        assert!(
            SweepGuard::try_enter(&flag).is_none(),
            "a second concurrent entry must be refused while the first is held",
        );

        drop(g1);
        assert!(
            SweepGuard::try_enter(&flag).is_some(),
            "after the guard drops, the gate must be re-enterable",
        );
    }
}

#[cfg(all(test, feature = "nat-traversal"))]
mod reclassify_override_race_tests {
    //! Regression coverage for a cubic-flagged P1 bug:
    //! [`MeshNode::reclassify_nat`] checked
    //! `reflex_override_active` only at entry, then ran the
    //! multi-peer probe sweep, then committed the result. A
    //! `set_reflex_override` call landing *after* the entry
    //! check but *before* the commit was silently stomped:
    //! the commit unconditionally overwrote `nat_class` and
    //! `reflex_addr` with the probe-derived values, undoing
    //! the freshly-installed override.
    //!
    //! Fix: [`MeshNode::reclassify_nat`] now calls
    //! [`MeshNode::commit_reclassify_observations`], which
    //! re-loads the flag before any store and bails out if an
    //! override landed mid-sweep. Tests below pin that guard
    //! without needing to stand up a real probe mesh.
    use super::*;
    use crate::adapter::net::traversal::classify::NatClass;
    use std::net::SocketAddr;

    async fn build_node_for_test() -> Arc<MeshNode> {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x17u8; 32]);
        Arc::new(
            MeshNode::new(EntityKeypair::generate(), cfg)
                .await
                .expect("MeshNode::new"),
        )
    }

    /// RT-5 review P2: `ProximityGraph::set_local_capabilities` had no
    /// caller, so origin pingwaves (the heartbeat tick AND the
    /// change-driven event pingwave) carried the graph's default
    /// capability summary (hash 0 / version 0). An announce must now push
    /// the merged caps into the graph so the pingwave piggybacks them.
    #[tokio::test]
    async fn announced_capabilities_reach_the_origin_pingwave() {
        let node = build_node_for_test().await;

        // Before any announce the pingwave carries the default summary.
        let before = node
            .proximity_graph()
            .create_pingwave(HealthStatus::Healthy);
        assert_eq!(before.capability_hash, 0, "no caps announced yet");
        assert_eq!(before.capability_version, 0);

        node.announce_capabilities(CapabilitySet::new().add_tag("svc:demo".to_string()))
            .await
            .expect("announce");

        // The pingwave now carries the announced caps' hash and a bumped
        // version — the summary event pingwaves piggyback.
        let after = node
            .proximity_graph()
            .create_pingwave(HealthStatus::Healthy);
        assert_ne!(
            after.capability_hash, 0,
            "pingwave must carry the announced capability hash, not the default"
        );
        assert!(
            after.capability_version > before.capability_version,
            "announcing capabilities must bump the pingwave capability version",
        );
    }

    /// RT-3 review P2: a capability mutation that lands between a bare
    /// `start()` and a later `start_arc()` must survive. The change loop
    /// used to `borrow_and_update` (mark the signal seen) BEFORE checking
    /// whether `self_weak` was installed, so a mutation in that window
    /// was dropped permanently until the next reannounce. The landed
    /// Finding-7 test called `start_arc` before mutating, so it missed
    /// this ordering.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn bare_start_then_mutate_then_start_arc_still_announces() {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x23u8; 32])
            // Enable the change-driven announcer with a snappy debounce…
            .with_announce_debounce(Duration::from_millis(20))
            // …and DISABLE the keep-alive reannounce so the ONLY thing
            // that can bump capability_version after start_arc is the
            // change-driven announce we are testing.
            .with_capability_reannounce_interval(Duration::MAX);
        let node = Arc::new(
            MeshNode::new(EntityKeypair::generate(), cfg)
                .await
                .expect("MeshNode::new"),
        );

        // Bare start: spawns the change loop with `self_weak` still None.
        node.start();
        tokio::time::sleep(Duration::from_millis(50)).await;

        // A local-caps mutation lands BEFORE start_arc.
        node.test_bump_local_caps_changed();
        // Give the loop time to (pre-fix) consume + drop the signal.
        tokio::time::sleep(Duration::from_millis(150)).await;
        let v_before = node.capability_version.load(Ordering::Relaxed);

        // Enable the Arc-started announcer. The parked mutation must now
        // drive an announce, bumping capability_version.
        node.start_arc();

        let deadline = tokio::time::Instant::now() + Duration::from_secs(3);
        let mut announced = false;
        while tokio::time::Instant::now() < deadline {
            if node.capability_version.load(Ordering::Relaxed) > v_before {
                announced = true;
                break;
            }
            tokio::time::sleep(Duration::from_millis(25)).await;
        }
        assert!(
            announced,
            "the mutation made between bare start() and start_arc() was dropped — \
             capability_version never advanced after start_arc"
        );
    }

    /// Regression for the capability re-announce loop. A node's own
    /// capability self-entry TTL-expires and the fold sweeper reaps it,
    /// after which (a) its callee-side nRPC gate denies its own services
    /// and (b) peers can no longer discover it. The loop must re-announce
    /// on its cadence — keeping the self-entry alive past its TTL (checked
    /// here) while advancing `capability_version` (the actual broadcast).
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn capability_reannounce_keeps_self_entry_alive_past_ttl() {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x21u8; 32])
            .with_capability_reannounce_interval(Duration::from_millis(40));
        let node = Arc::new(
            MeshNode::new(EntityKeypair::generate(), cfg)
                .await
                .expect("MeshNode::new"),
        );
        // Self-entry with a deliberately short TTL — without the loop it
        // would expire and the fold sweeper (500 ms) would reap it.
        node.announce_capabilities_with(CapabilitySet::new(), Duration::from_millis(120), true)
            .await
            .expect("announce");
        node.start_arc();

        let v0 = node.capability_version.load(Ordering::Relaxed);
        // Past the 120 ms TTL and a fold sweep tick.
        tokio::time::sleep(Duration::from_millis(750)).await;
        let present = node
            .capability_fold
            .with_state(|s| s.by_node.contains_key(&node.node_id));
        let v1 = node.capability_version.load(Ordering::Relaxed);
        assert!(
            present,
            "self-entry must survive past its TTL while the re-announce loop runs"
        );
        assert!(
            v1 >= v0 + 3,
            "the loop must re-announce (broadcast) periodically: version {v0} -> {v1}"
        );
    }

    /// Control for the above: with the loop disabled (`Duration::MAX`),
    /// the self-entry expires and is swept — the pre-fix behavior, pinned
    /// so the loop's effect is unambiguous.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn capability_self_entry_expires_without_reannounce() {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x22u8; 32])
            .with_capability_reannounce_interval(Duration::MAX);
        let node = Arc::new(
            MeshNode::new(EntityKeypair::generate(), cfg)
                .await
                .expect("MeshNode::new"),
        );
        node.announce_capabilities_with(CapabilitySet::new(), Duration::from_millis(120), true)
            .await
            .expect("announce");
        node.start_arc();

        tokio::time::sleep(Duration::from_millis(750)).await;
        let present = node
            .capability_fold
            .with_state(|s| s.by_node.contains_key(&node.node_id));
        assert!(
            !present,
            "without the re-announce loop the self-entry must expire and be swept"
        );
    }

    /// Regression for the P2 throttle interaction: when the re-announce
    /// interval is configured *below* `min_announce_interval`, the loop ticks
    /// fast but `announce_capabilities_with` rate-limits the network broadcast
    /// to `min_announce_interval`. The stamped TTL must cover that *effective*
    /// (throttled) cadence — `2 × min_announce_interval` here — not the bare
    /// `2 × reannounce_interval`, which would expire on peers before the
    /// throttle releases the next broadcast.
    #[test]
    fn reannounce_ttl_covers_throttled_broadcast_cadence() {
        // reannounce 40 ms ≪ min_announce 10 s: the throttle dominates.
        let ttl = capability_reannounce_ttl(Duration::from_millis(40), Duration::from_secs(10));
        assert_eq!(
            ttl,
            Duration::from_secs(20),
            "TTL must be 2× the effective (throttled) cadence, not 2× the 40 ms tick"
        );
    }

    /// When the re-announce interval dominates `min_announce_interval`, the
    /// throttle is a no-op and the TTL is just `2 × reannounce_interval`.
    #[test]
    fn reannounce_ttl_uses_reannounce_when_it_dominates() {
        // Defaults: reannounce 150 s, min_announce 10 s.
        let ttl = capability_reannounce_ttl(Duration::from_secs(150), Duration::from_secs(10));
        assert_eq!(ttl, Duration::from_secs(300));
    }

    /// Both intervals sub-second → the TTL still floors at 1 s, since the
    /// announce TTL is truncated to whole seconds on the wire.
    #[test]
    fn reannounce_ttl_floors_at_one_second() {
        let ttl = capability_reannounce_ttl(Duration::from_millis(40), Duration::from_millis(50));
        assert_eq!(ttl, Duration::from_secs(1));
    }

    /// Pre-fix behavior: with override inactive, the commit
    /// path overwrites both `nat_class` and `reflex_addr`.
    /// This pins the positive case so the guard doesn't
    /// silently turn into a no-op.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn commit_applies_when_override_inactive() {
        let node = build_node_for_test().await;
        let probed: SocketAddr = "198.51.100.9:4242".parse().unwrap();

        // Override flag is false by default.
        node.commit_reclassify_observations(NatClass::Cone, Some(probed), 2);

        assert_eq!(node.nat_class(), NatClass::Cone);
        assert_eq!(node.reflex_addr(), Some(probed));
    }

    /// The race guard: flag flipped true mid-sweep →
    /// commit must be a no-op. Without the fix the `nat_class`
    /// store and the `reflex_addr` store would land regardless,
    /// demoting the override-provided Open/external-ip back to
    /// the classifier's observation.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn commit_skips_when_override_installed_mid_sweep() {
        let node = build_node_for_test().await;
        let override_addr: SocketAddr = "203.0.113.77:9999".parse().unwrap();
        let probed: SocketAddr = "198.51.100.9:4242".parse().unwrap();

        // Simulate the race: `reclassify_nat` passed its entry
        // check with the flag false, ran probes, and is about
        // to commit. In between, port-mapping install fires
        // `set_reflex_override` — the flag flips true and the
        // reflex/class are written.
        node.set_reflex_override(override_addr);
        assert_eq!(node.nat_class(), NatClass::Open);
        assert_eq!(node.reflex_addr(), Some(override_addr));

        // Now the classifier's (stale) commit tries to land.
        // With the guard in place, it must be skipped.
        node.commit_reclassify_observations(NatClass::Symmetric, Some(probed), 2);

        assert_eq!(
            node.nat_class(),
            NatClass::Open,
            "mid-sweep commit stomped the override's NAT class — \
             the node would be demoted from Open back to Symmetric",
        );
        assert_eq!(
            node.reflex_addr(),
            Some(override_addr),
            "mid-sweep commit stomped the override reflex — the \
             node would advertise the classifier's observation \
             instead of the known-public mapping",
        );
    }

    /// Same guard, but the `latest_reflex = None` path — when
    /// every probe failed, the buggy commit *still* wrote
    /// `nat_class` (only the `reflex_addr` store was gated by
    /// `Some`). The fix's guard covers both stores.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn commit_skips_nat_class_store_even_when_reflex_absent() {
        let node = build_node_for_test().await;
        let override_addr: SocketAddr = "203.0.113.77:9999".parse().unwrap();

        node.set_reflex_override(override_addr);

        // Classifier gave up (all probes failed); it would
        // still store `Unknown` without the guard.
        node.commit_reclassify_observations(NatClass::Unknown, None, 0);

        assert_eq!(
            node.nat_class(),
            NatClass::Open,
            "`nat_class` was overwritten with Unknown even though \
             `latest_reflex` was None — demonstrates the second \
             half of the bug that the bare `if let Some` would've \
             missed",
        );
        assert_eq!(node.reflex_addr(), Some(override_addr));
    }

    /// Regression for `BUG_AUDIT_2026_05_03_MESH.md` #4: when every
    /// probe in a sweep failed (`latest_reflex == None`) and the
    /// override is INACTIVE, the commit must skip both stores
    /// rather than writing `nat_class` (typically `Unknown`) over
    /// the previously-published class while leaving the previous
    /// `reflex_addr` in place — that pair is torn from the
    /// `traversal_publish_mu` reader's perspective. Match the
    /// deadline-expired branch in `reclassify_nat`: treat
    /// "no observations this sweep" as transient and keep the
    /// previously-published pair coherent.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn commit_skips_both_stores_when_no_observation_and_no_override() {
        let node = build_node_for_test().await;
        let probed: SocketAddr = "198.51.100.9:4242".parse().unwrap();

        // Seed a coherent (Cone, Some(probed)) pair via the same
        // commit path; no override is installed so this must apply.
        node.commit_reclassify_observations(NatClass::Cone, Some(probed), 2);
        assert_eq!(node.nat_class(), NatClass::Cone);
        assert_eq!(node.reflex_addr(), Some(probed));

        // Simulate the next sweep where every probe failed.
        // Pre-fix this would have stored `Unknown` over `Cone`
        // while keeping `Some(probed)` as the reflex — torn pair.
        // Post-fix the function returns early and both fields
        // remain untouched.
        node.commit_reclassify_observations(NatClass::Unknown, None, 0);

        assert_eq!(
            node.nat_class(),
            NatClass::Cone,
            "no-observation sweep flapped nat_class from Cone to \
             Unknown; pre-fix the store landed unconditionally even \
             though the paired reflex store was gated by Some",
        );
        assert_eq!(
            node.reflex_addr(),
            Some(probed),
            "reflex_addr was not torn (good) but nat_class was \
             rewritten — the pair an `announce_capabilities_with` \
             reader sees under traversal_publish_mu becomes \
             (fresh class, stale reflex) which violates the mutex's \
             coherent-snapshot invariant",
        );
    }

    /// Finding B2 (code review 2026-06-21, port-scanning): a sweep
    /// that collected fewer than two observations must NOT publish.
    /// `classify` returns `Unknown` below 2 observations, and
    /// committing that would flap a previously-good class down to
    /// Unknown on nothing more than transient packet loss (one of the
    /// two probes dropped). The commit must keep the prior
    /// (class, reflex) pair.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn commit_keeps_prior_class_on_single_observation_sweep() {
        let node = build_node_for_test().await;
        let probed: SocketAddr = "198.51.100.9:4242".parse().unwrap();

        // Seed a coherent two-observation result.
        node.commit_reclassify_observations(NatClass::Cone, Some(probed), 2);
        assert_eq!(node.nat_class(), NatClass::Cone);
        assert_eq!(node.reflex_addr(), Some(probed));

        // Next sweep gets only ONE probe response → classify() yields
        // Unknown for <2 observations. Pre-fix this stored
        // (Unknown, single); post-fix the prior pair is kept.
        let single: SocketAddr = "198.51.100.10:4243".parse().unwrap();
        node.commit_reclassify_observations(NatClass::Unknown, Some(single), 1);

        assert_eq!(
            node.nat_class(),
            NatClass::Cone,
            "a single-observation sweep must not downgrade a good class to Unknown",
        );
        assert_eq!(
            node.reflex_addr(),
            Some(probed),
            "a single-observation sweep must not overwrite the published reflex",
        );
    }

    /// Finding B2 follow-up (code review 2026-06-21, port-scanning):
    /// the no-reflex guard in `commit_reclassify_observations` is
    /// subsumed by the <2-observation guard for every coherent
    /// `reclassify_nat` input (0 observations ⟹ caught by the count
    /// guard; ≥2 observations ⟹ a reflex was threaded). It is retained
    /// purely as defense-in-depth against a *torn* input — a commit
    /// claiming ≥2 observations yet carrying no reflex. Such an input
    /// must still keep the prior (class, reflex) pair rather than
    /// publish a class with no paired reflex.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn commit_keeps_prior_on_torn_class_without_reflex() {
        let node = build_node_for_test().await;
        let probed: SocketAddr = "198.51.100.9:4242".parse().unwrap();

        // Seed a coherent two-observation result.
        node.commit_reclassify_observations(NatClass::Cone, Some(probed), 2);
        assert_eq!(node.nat_class(), NatClass::Cone);
        assert_eq!(node.reflex_addr(), Some(probed));

        // Torn input: claims 2 observations (so the <2 guard does NOT
        // fire) but carries no reflex. The no-reflex guard must catch
        // it and keep the prior pair.
        node.commit_reclassify_observations(NatClass::Open, None, 2);

        assert_eq!(
            node.nat_class(),
            NatClass::Cone,
            "a torn (class, None) commit must not publish a class without a reflex",
        );
        assert_eq!(
            node.reflex_addr(),
            Some(probed),
            "a torn (class, None) commit must leave the published reflex intact",
        );
    }

    /// After `clear_reflex_override` is called, the classifier
    /// regains write access. Without this, the fix would
    /// permanently freeze classification once any override had
    /// ever been installed.
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn commit_resumes_after_override_cleared() {
        let node = build_node_for_test().await;
        let override_addr: SocketAddr = "203.0.113.77:9999".parse().unwrap();
        let probed: SocketAddr = "198.51.100.9:4242".parse().unwrap();

        node.set_reflex_override(override_addr);
        node.clear_reflex_override();

        node.commit_reclassify_observations(NatClass::Cone, Some(probed), 2);

        assert_eq!(node.nat_class(), NatClass::Cone);
        assert_eq!(node.reflex_addr(), Some(probed));
    }
}

#[cfg(all(test, feature = "redex"))]
mod sensing_fold_gate_tests {
    //! SI-6.1 closure witnesses for the gate itself: leading edge
    //! runs, in-window defers exactly once then coalesces, and the
    //! boundary sleeper's claim is exactly-once (including the
    //! subsumed-by-a-fresh-run jitter edge). The e2e in
    //! `tests/sensing_leader_delivery.rs` witnesses the full
    //! suppressed-change repair on real sessions.

    use super::*;

    /// Far out of reach: every second change is in-window.
    const GAP: Duration = Duration::from_secs(3600);

    #[test]
    fn leading_edge_runs_then_defers_then_coalesces() {
        let coalescer = DashMap::new();
        assert!(matches!(
            sensing_fold_gate_admit(&coalescer, [1; 32], GAP),
            SensingFoldGateDecision::RunNow
        ));
        assert!(matches!(
            sensing_fold_gate_admit(&coalescer, [1; 32], GAP),
            SensingFoldGateDecision::Defer { .. }
        ));
        assert!(
            matches!(
                sensing_fold_gate_admit(&coalescer, [1; 32], GAP),
                SensingFoldGateDecision::Coalesced
            ),
            "further in-window changes coalesce into the ONE scheduled boundary run",
        );
        // Distinct capabilities gate independently.
        assert!(matches!(
            sensing_fold_gate_admit(&coalescer, [2; 32], GAP),
            SensingFoldGateDecision::RunNow
        ));
    }

    /// Bind the token a `Defer` minted (panics on any other decision).
    fn defer_token(decision: SensingFoldGateDecision) -> u64 {
        match decision {
            SensingFoldGateDecision::Defer { token, .. } => token,
            _ => panic!("expected Defer"),
        }
    }

    #[test]
    fn boundary_reclaim_is_exactly_once_and_a_fresh_run_subsumes_the_sleeper() {
        let coalescer = DashMap::new();
        assert!(matches!(
            sensing_fold_gate_admit(&coalescer, [1; 32], GAP),
            SensingFoldGateDecision::RunNow
        ));
        let token = defer_token(sensing_fold_gate_admit(&coalescer, [1; 32], GAP));
        assert!(
            sensing_fold_gate_reclaim(&coalescer, &[1; 32], token),
            "the sleeper owns its scheduled boundary run",
        );
        assert!(
            !sensing_fold_gate_reclaim(&coalescer, &[1; 32], token),
            "exactly one trailing run per window",
        );

        // Jitter edge: a fresh OUT-of-window change lands before the
        // sleeper wakes (zero gap makes every change out-of-window)
        // — the fresh run subsumes the sleeper's pending run.
        assert!(matches!(
            sensing_fold_gate_admit(&coalescer, [2; 32], GAP),
            SensingFoldGateDecision::RunNow
        ));
        let subsumed = defer_token(sensing_fold_gate_admit(&coalescer, [2; 32], GAP));
        assert!(matches!(
            sensing_fold_gate_admit(&coalescer, [2; 32], Duration::ZERO),
            SensingFoldGateDecision::RunNow
        ));
        assert!(
            !sensing_fold_gate_reclaim(&coalescer, &[2; 32], subsumed),
            "a fresh out-of-window run subsumes the sleeper's pending reconciliation",
        );
    }

    /// SI-6.1 re-review P1: a stale sleeper scheduled in an OLD window
    /// (whose run was subsumed out-of-window) must not steal a NEWER
    /// window's pending run when scheduler jitter delays its wake past
    /// the new window's `Defer`. Reviewer's exact sequence.
    #[test]
    fn a_stale_sleeper_cannot_steal_a_newer_windows_pending_reconciliation() {
        let coalescer = DashMap::new();
        // (T0) leading edge runs.
        assert!(matches!(
            sensing_fold_gate_admit(&coalescer, [1; 32], GAP),
            SensingFoldGateDecision::RunNow
        ));
        // (T10) in-window event schedules sleeper S1.
        let s1 = defer_token(sensing_fold_gate_admit(&coalescer, [1; 32], GAP));
        // (T110) S1 is delayed; a fresh OUT-of-window event runs
        // immediately and invalidates S1's token.
        assert!(matches!(
            sensing_fold_gate_admit(&coalescer, [1; 32], Duration::ZERO),
            SensingFoldGateDecision::RunNow
        ));
        // (T120) a new-window in-window event schedules S2.
        let s2 = defer_token(sensing_fold_gate_admit(&coalescer, [1; 32], GAP));
        assert_ne!(s1, s2, "each window mints a distinct ownership token");
        // (T130) the stale S1 finally wakes: it must NOT reclaim S2's
        // pending run.
        assert!(
            !sensing_fold_gate_reclaim(&coalescer, &[1; 32], s1),
            "a stale sleeper must not steal a newer window's pending reconciliation",
        );
        // S2, at its own boundary, still owns and runs its window.
        assert!(
            sensing_fold_gate_reclaim(&coalescer, &[1; 32], s2),
            "the current window's sleeper still owns its run",
        );
    }
}

#[cfg(test)]
mod sensing_live_direct_session_tests {
    //! SI-5 review P1 witnesses: `peers.contains_key` is NOT "live
    //! direct session" — a `connect_via` destination stores the
    //! RELAY's address in its `PeerInfo`, so it lingers in the map
    //! while being reachable only through the relay, and both
    //! routeless failure-plane fallbacks skipped disruption on it.
    //! The reverse `addr_to_node` mapping is the directness
    //! discriminator (`promotable_direct_hop`'s rule); the detector
    //! arm mirrors that helper's liveness gate verbatim.

    use super::*;

    #[test]
    fn relayed_session_address_is_not_a_live_direct_session() {
        // Kyra's exact misclassification: provider P was connected
        // via relay X — its PeerInfo carries X's ADDRESS, and the
        // reverse mapping for that address names X, not P. The old
        // `peers.contains_key(P)` predicate read this as a live
        // direct session and skipped disruption.
        let relay_addr: SocketAddr = "127.0.0.1:9001".parse().unwrap();
        let addr_to_node: DashMap<SocketAddr, u64> = DashMap::new();
        addr_to_node.insert(relay_addr, 0xE0); // the RELAY's id
        assert!(
            !sensing_addr_is_live_direct(&addr_to_node, None, 0xF0, relay_addr),
            "a relayed PeerInfo must never read as a live direct session",
        );
    }

    #[test]
    fn direct_session_reverse_maps_to_the_node_itself() {
        let addr: SocketAddr = "127.0.0.1:9002".parse().unwrap();
        let addr_to_node: DashMap<SocketAddr, u64> = DashMap::new();
        addr_to_node.insert(addr, 0xD1);
        assert!(sensing_addr_is_live_direct(&addr_to_node, None, 0xD1, addr));
        // And an address nobody reverse-maps is not direct either
        // (a torn/mid-eviction entry stays conservative).
        let stale: SocketAddr = "127.0.0.1:9003".parse().unwrap();
        assert!(!sensing_addr_is_live_direct(
            &addr_to_node,
            None,
            0xD1,
            stale
        ));
    }
}

#[cfg(test)]
mod fold_publisher_helpers_tests {
    //! Per-fold publisher convenience helpers — confirm the
    //! per-`(kind, class)` generation counter advances
    //! monotonically and shards correctly. The actual sign +
    //! broadcast pipeline is exercised by the existing
    //! `behavior::fold::tests` end-to-end pin
    //! (`publisher_to_receiver_full_pipeline_in_process`); this
    //! module pins the publisher-side counter logic that the
    //! helpers compose with that pipeline.

    use super::*;
    use std::net::SocketAddr;

    async fn build_node_for_test() -> Arc<MeshNode> {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x42u8; 32]);
        Arc::new(
            MeshNode::new(EntityKeypair::generate(), cfg)
                .await
                .expect("MeshNode::new"),
        )
    }

    #[tokio::test]
    async fn next_fold_generation_first_call_returns_one() {
        // Wire format reserves gen=0 as the "uninitialized"
        // sentinel; the helper's pre-increment shape ensures
        // the first emitted announcement is always gen=1.
        let node = build_node_for_test().await;
        assert_eq!(node.next_fold_generation(0x0F00, 0xAA), 1);
    }

    #[tokio::test]
    async fn next_fold_generation_advances_monotonically_per_class() {
        let node = build_node_for_test().await;
        let class = 0xBEEF;
        let kind = 0x0F00;
        let mut last = 0;
        for _ in 0..8 {
            let g = node.next_fold_generation(kind, class);
            assert!(
                g > last,
                "generation must be strictly monotonic per (kind, class)"
            );
            last = g;
        }
        assert_eq!(last, 8, "8 calls → gens 1..=8");
    }

    #[tokio::test]
    async fn next_fold_generation_shards_per_kind_and_class() {
        // Independent (kind, class) slots have independent
        // counters — gen=1 for (kind_A, class_X) doesn't
        // affect (kind_A, class_Y) or (kind_B, class_X).
        let node = build_node_for_test().await;
        let g_a_x = node.next_fold_generation(0x0F00, 0xAA);
        let g_a_y = node.next_fold_generation(0x0F00, 0xBB);
        let g_b_x = node.next_fold_generation(0x0F01, 0xAA);
        assert_eq!(g_a_x, 1);
        assert_eq!(g_a_y, 1);
        assert_eq!(g_b_x, 1);

        // Second call on (kind_A, class_X) advances independently
        // of the other slots, which stay at their last value.
        let g_a_x_2 = node.next_fold_generation(0x0F00, 0xAA);
        assert_eq!(g_a_x_2, 2);
        // Other slots advance to 2 only when we ask them to.
        assert_eq!(node.next_fold_generation(0x0F00, 0xBB), 2);
        assert_eq!(node.next_fold_generation(0x0F01, 0xAA), 2);
    }

    #[tokio::test]
    async fn publish_capability_membership_signs_with_node_identity() {
        // The publisher helper must sign with the local node's
        // identity. Roundtrip-verify by hand: capture the
        // identity, replicate the sign step independently, and
        // confirm the helper's signature would verify against
        // it. We can't fully exercise broadcast here (no peers),
        // but we CAN confirm the helper composes correctly with
        // `next_fold_generation` and produces a well-formed
        // envelope on the broadcast path.
        let node = build_node_for_test().await;
        // No peers connected → broadcast returns 0 sent without
        // failure. The relevant pin: the helper doesn't panic
        // and produces a result.
        let result = node
            .publish_capability_membership(super::super::behavior::fold::CapabilityMembership {
                class_hash: 0x1000,
                tags: vec!["gpu".into()],
                hardware: None,
                state: super::super::behavior::fold::NodeState::Idle,
                region: Some("us-east".into()),
                price_quote: None,
                reflex_addr: None,
                allowed_nodes: Vec::new(),
                allowed_subnets: Vec::new(),
                allowed_groups: Vec::new(),
                metadata: std::collections::BTreeMap::new(),
            })
            .await;
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), 0, "no peers → 0 sent");

        // The generation counter advanced for (CapabilityFold,
        // 0x1000) — pinning that the helper threaded through
        // next_fold_generation correctly.
        let next = node.next_fold_generation(
            <super::super::behavior::fold::CapabilityFold as super::super::behavior::fold::FoldKind>::KIND_ID,
            0x1000,
        );
        assert_eq!(
            next, 2,
            "first publish used gen=1, next_fold_generation returns gen=2"
        );
    }

    #[tokio::test]
    async fn fold_generation_gc_evicts_stale_slots_keeps_recent() {
        // GC behavior: an entry whose last_touched_us is older
        // than FOLD_GENERATION_GC_MAX_AGE is removed; recently-
        // touched slots survive. We drive the sweep inline by
        // calling the same retain closure the background task
        // uses, so the test stays fast and deterministic without
        // spinning the 5-minute interval.
        let node = build_node_for_test().await;
        let kind = 0x0F00u16;
        let stale_class = 0xAAAA_u64;
        let fresh_class = 0xBBBB_u64;

        // Stale entry: stamp last_touched far in the past.
        node.next_fold_generation(kind, stale_class);
        node.fold_generations
            .get(&(kind, stale_class))
            .expect("stale entry exists")
            .last_touched_us
            .store(0, Ordering::Relaxed);

        // Fresh entry: just stamped, last_touched ≈ now.
        node.next_fold_generation(kind, fresh_class);

        // Run the same retain the background loop would on tick.
        let cutoff_us = crate::adapter::net::current_timestamp_micros()
            .saturating_sub(FOLD_GENERATION_GC_MAX_AGE.as_micros() as u64);
        node.fold_generations
            .retain(|_, e| e.last_touched_us.load(Ordering::Relaxed) >= cutoff_us);

        assert!(
            !node.fold_generations.contains_key(&(kind, stale_class)),
            "stale slot evicted"
        );
        assert!(
            node.fold_generations.contains_key(&(kind, fresh_class)),
            "fresh slot survives"
        );
    }

    #[tokio::test]
    async fn origin_hash_index_first_write_wins_on_adversarial_collision() {
        // Post-`WIRE_ORIGIN_HASH_64BIT` policy: `origin_hash_to_node`
        // uses first-write-wins. Two distinct node_ids claiming the
        // same u64 origin_hash (~2^32 adversarial work to engineer)
        // resolve to whichever was inserted first; the second
        // claimant cannot displace the established slot.
        //
        // Pre-cutover the slot promoted to `Multiple` and lookups
        // returned `None` for the ambiguous case — that branch is
        // gone with the truncation it was designed to handle.
        let node = build_node_for_test().await;
        let hash = 0xCAFE_BABE_DEAD_BEEF_u64;
        let first = 0xAAAA_u64;
        let second = 0xBBBB_u64;

        // Empty slot.
        assert_eq!(node.get_node_by_origin_hash(hash), None);

        // First claimant lands.
        node.origin_hash_to_node.entry(hash).or_insert(first);
        assert_eq!(node.get_node_by_origin_hash(hash), Some(first));

        // Second adversarial claimant — `or_insert` is a no-op
        // because the entry already exists.
        node.origin_hash_to_node.entry(hash).or_insert(second);
        assert_eq!(
            node.get_node_by_origin_hash(hash),
            Some(first),
            "first-write-wins must not be displaced by an adversarial grind"
        );

        // Removal via `remove_if` only drops when the predicate
        // matches the current claimant — mirrors what the
        // failure-detector eviction does.
        node.origin_hash_to_node
            .remove_if(&hash, |_, claimant| *claimant == second);
        assert_eq!(
            node.get_node_by_origin_hash(hash),
            Some(first),
            "remove_if on non-claimant is a no-op"
        );
        node.origin_hash_to_node
            .remove_if(&hash, |_, claimant| *claimant == first);
        assert_eq!(
            node.get_node_by_origin_hash(hash),
            None,
            "remove_if on the current claimant clears the slot"
        );
    }

    #[tokio::test]
    async fn origin_hash_index_distinguishes_low32_collisions() {
        // Regression for the original cutover motivation: pre-
        // `WIRE_ORIGIN_HASH_64BIT` the slot keyed on the truncated
        // u32 form, so two `EntityId`s whose low 32 bits collided
        // but whose full u64 hashes differed would conflict on the
        // wire. Post-cutover the index keys on the full u64, so the
        // two publishers occupy distinct slots and both lookups
        // succeed.
        let node = build_node_for_test().await;
        let low_common: u32 = 0xDEAD_BEEF;
        let hash_a: u64 = low_common as u64;
        let hash_b: u64 = (0x4242_4242_u64 << 32) | (low_common as u64);
        assert_eq!(hash_a as u32, hash_b as u32);
        assert_ne!(hash_a, hash_b);

        node.origin_hash_to_node.insert(hash_a, 0xAAAA);
        node.origin_hash_to_node.insert(hash_b, 0xBBBB);

        assert_eq!(node.get_node_by_origin_hash(hash_a), Some(0xAAAA));
        assert_eq!(node.get_node_by_origin_hash(hash_b), Some(0xBBBB));
    }

    #[tokio::test]
    async fn local_subnet_defaults_to_global_without_config_override() {
        // `build_node_for_test` constructs `MeshNodeConfig::new(...)`
        // without `.with_subnet(...)`, so the local subnet must
        // come out as `SubnetId::GLOBAL`. Pins the
        // GLOBAL-as-default contract operator tooling relies on.
        let node = build_node_for_test().await;
        assert_eq!(node.local_subnet(), SubnetId::GLOBAL);
        assert!(node.local_subnet_policy().is_none());
    }

    #[tokio::test]
    async fn gateway_handle_is_none_until_channel_configs_installed() {
        // `set_channel_configs` builds the gateway lazily; nodes
        // without a registry have no gateway and `gateway()`
        // returns `None`. Operator tooling discriminates on this
        // to print "no gateway configured" vs. real stats.
        let node = build_node_for_test().await;
        assert!(node.gateway().is_none());
        // The node we get from `build_node_for_test` is wrapped
        // in an `Arc`, so installing configs requires mutable
        // access via Arc::try_unwrap or unsafe. Cover the
        // None-then-Some transition via a fresh node we own.
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x17u8; 32]);
        let mut owned = MeshNode::new(EntityKeypair::generate(), cfg)
            .await
            .expect("MeshNode::new");
        assert!(owned.gateway().is_none());
        owned.set_channel_configs(std::sync::Arc::new(
            crate::adapter::net::ChannelConfigRegistry::new(),
        ));
        let gw = owned.gateway().expect("gateway installed");
        assert_eq!(gw.local_subnet(), SubnetId::GLOBAL);
        assert_eq!(gw.forwarded_count(), 0);
        assert_eq!(gw.dropped_count(), 0);
    }

    #[tokio::test]
    async fn failed_peer_eviction_drops_retained_subscribe_chains() {
        // A peer that fails (heartbeat timeout) never sends an
        // unsubscribe, and the periodic sweep can't reach its retained
        // chain once `peer_entity_ids` is cleared — so the
        // failure-detector callback must drop it directly, scoped to the
        // failed node and nothing else.
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg =
            MeshNodeConfig::new(addr, [0x17u8; 32]).with_session_timeout(Duration::from_millis(1));
        let node = MeshNode::new(EntityKeypair::generate(), cfg)
            .await
            .expect("MeshNode::new");

        let dead: u64 = 0xDEAD;
        let live: u64 = 0xBEEF;
        let channel_hash: ChannelHash = 0x1234;

        let issuer = EntityKeypair::generate();
        let subject = EntityKeypair::generate();
        let chain = TokenChain::single(PermissionToken::issue(
            &issuer,
            subject.entity_id().clone(),
            TokenScope::SUBSCRIBE,
            channel_hash,
            3600,
            0,
        ));
        node.subscriber_chains
            .insert((dead, channel_hash), RetainedChain::new(chain.clone()));
        node.subscriber_chains
            .insert((live, channel_hash), RetainedChain::new(chain));
        assert_eq!(node.subscriber_chains.len(), 2);

        node.failure_detector.heartbeat(dead, addr);
        node.failure_detector.heartbeat(live, addr);

        // Age `dead`'s heartbeat well past `miss_threshold × timeout`,
        // then refresh `live` so only `dead` trips.
        tokio::time::sleep(Duration::from_millis(20)).await;
        node.failure_detector.heartbeat(live, addr);

        let failed = node.failure_detector.check_all();
        assert!(failed.contains(&dead), "dead peer must be detected failed");

        assert!(
            node.subscriber_chains.get(&(live, channel_hash)).is_some(),
            "live peer's retained chain must survive"
        );
        assert!(
            node.subscriber_chains.get(&(dead, channel_hash)).is_none(),
            "failed peer's retained chain must be evicted"
        );
    }

    #[tokio::test]
    async fn delegated_publish_chain_authorizes_publish() {
        use crate::adapter::net::{ChannelConfig, ChannelConfigRegistry, ChannelId, ChannelName};

        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x17u8; 32]);
        let mut node = MeshNode::new(EntityKeypair::generate(), cfg)
            .await
            .expect("MeshNode::new");

        // Channel rooted at `owner`; the publishing node is NOT a root.
        let owner = EntityKeypair::generate();
        let mid = EntityKeypair::generate();
        let channel = ChannelName::new("fleet/telemetry").unwrap();
        let registry = ChannelConfigRegistry::new();
        registry.insert(
            ChannelConfig::new(ChannelId::new(channel.clone()))
                .with_token_roots(vec![owner.entity_id().clone()]),
        );
        node.set_channel_configs(Arc::new(registry));

        // Delegated PUBLISH chain: owner -> mid -> this node. The node's
        // own leaf token is issued by `mid` (a delegator), not a channel
        // root, so a single-link chain from it can't anchor.
        let root = PermissionToken::issue(
            &owner,
            mid.entity_id().clone(),
            TokenScope::PUBLISH.union(TokenScope::DELEGATE),
            channel.hash(),
            3600,
            2,
        );
        let leaf = root
            .delegate(&mid, node.entity_id().clone(), TokenScope::PUBLISH)
            .expect("delegation should succeed");
        let chain = TokenChain {
            tokens: vec![root, leaf],
        };

        let publisher = node.channel_publisher(channel.clone(), PublishConfig::default());

        // Without the held chain the publish-side ACL can only build a
        // single-link chain from the cache, which can't anchor a
        // delegated grant -> publish denied.
        assert!(
            node.publish_many(&publisher, &[Bytes::from_static(b"x")])
                .await
                .is_err(),
            "delegated publisher must be denied until it presents its chain"
        );

        // Install the delegated chain -> publish admitted (no
        // subscribers, so it reports an empty fan-out).
        node.set_publish_chain(&channel, chain);
        let report = node
            .publish_many(&publisher, &[Bytes::from_static(b"x")])
            .await
            .expect("held delegated chain must authorize publish");
        assert_eq!(report.attempted, 0);
    }

    #[cfg(feature = "cortex")]
    #[tokio::test]
    async fn aggregator_registry_is_none_until_installed() {
        // Nodes that don't run aggregators leave the registry
        // empty — CLI verbs short-circuit on this.
        use crate::adapter::net::behavior::aggregator::AggregatorRegistry;
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x17u8; 32]);
        let mut owned = MeshNode::new(EntityKeypair::generate(), cfg)
            .await
            .expect("MeshNode::new");
        assert!(owned.aggregator_registry().is_none());
        let registry = std::sync::Arc::new(AggregatorRegistry::new());
        owned.set_aggregator_registry(registry.clone());
        let installed = owned.aggregator_registry().expect("registry installed");
        assert!(std::sync::Arc::ptr_eq(installed, &registry));
        assert!(installed.is_empty());
    }

    #[tokio::test]
    async fn known_subnets_sorted_by_node_id() {
        // Pin the deterministic-order contract `subnet ls` /
        // `subnet tree` operator tools depend on. Build a node,
        // populate `peer_subnets` directly with three out-of-order
        // entries, and assert `known_subnets()` returns them
        // sorted ascending by node_id.
        let node = build_node_for_test().await;
        assert!(node.known_subnets().is_empty());

        node.peer_subnets
            .insert(0xC0FFEE, SubnetId::new(&[3, 7, 2]));
        node.peer_subnets.insert(0xAAAA, SubnetId::new(&[3, 7, 1]));
        node.peer_subnets.insert(0xB0B0, SubnetId::new(&[3, 8]));

        let snapshot = node.known_subnets();
        let ids: Vec<u64> = snapshot.iter().map(|(id, _)| *id).collect();
        assert_eq!(ids, vec![0xAAAA, 0xB0B0, 0xC0FFEE]);
        assert_eq!(snapshot[0].1, SubnetId::new(&[3, 7, 1]));
        assert_eq!(snapshot[1].1, SubnetId::new(&[3, 8]));
        assert_eq!(snapshot[2].1, SubnetId::new(&[3, 7, 2]));
    }

    #[tokio::test]
    async fn capability_fold_is_wired_at_construction() {
        // Sub-step 3B-1 contract: every freshly-built MeshNode
        // owns a CapabilityFold registered with the node's
        // internal FoldRegistry, with the registry installed as
        // the fold channel router. Pins the wiring so callers
        // can rely on `mesh.capability_fold()` returning a
        // queryable handle and the inbound dispatch arm
        // routing SUBPROTOCOL_FOLD envelopes correctly.
        let node = build_node_for_test().await;
        // Fold handle is reachable, queries don't panic.
        assert_eq!(node.capability_fold().stats().entries, 0);
        // Channel router is installed by default.
        assert!(node.has_fold_router());
        // Router exposes the fold's stats — proves the
        // capability fold is registered in the registry that
        // backs the router.
        let stats = node.fold_stats();
        assert!(
            stats.iter().any(|s| {
                s.kind == <super::super::behavior::fold::CapabilityFold
                as super::super::behavior::fold::FoldKind>::KIND_ID
            }),
            "capability fold registered in default router"
        );
    }
}

#[cfg(test)]
mod route_withdrawal_promotion_tests {
    //! RT-5 review Findings 1 & 2: the withdrawal receive path must
    //! not promote an alternate that is (a) a peer the failure
    //! detector considers dead — `peers`/`addr_to_node`/`peer_addrs`
    //! retain Failed peers for transient-partition recovery, so a
    //! naive promotion resurrects an un-displaceable metric-1 route
    //! to a dead peer; (b) a relayed hop, whose recorded address is
    //! the relay's and does not map back to the hop; or (c) any hop
    //! whose address is the withdrawing sender's own, which would
    //! reinstall exactly the route the withdrawal just dropped.
    use super::*;
    use crate::adapter::net::failure::{FailureDetector, FailureDetectorConfig, NodeStatus};
    use std::net::SocketAddr;
    use std::time::Duration;

    fn addr(port: u16) -> SocketAddr {
        format!("127.0.0.1:{port}").parse().unwrap()
    }

    /// A detector whose nodes go Failed after a hair of real time so
    /// the test can drive a specific `NodeStatus` deterministically.
    fn detector() -> FailureDetector {
        FailureDetector::with_config(FailureDetectorConfig {
            timeout: Duration::from_millis(1),
            miss_threshold: 1,
            suspicion_threshold: 1,
            cleanup_interval: Duration::from_secs(60),
        })
    }

    #[test]
    fn healthy_direct_hop_is_promotable() {
        let hop = 0xA1;
        let hop_addr = addr(4001);
        let via_addr = addr(4099);
        let a2n = DashMap::new();
        a2n.insert(hop_addr, hop);
        let fd = detector();
        fd.heartbeat(hop, hop_addr); // Healthy
        assert!(MeshNode::promotable_direct_hop(
            &a2n, &fd, hop, hop_addr, via_addr
        ));
    }

    #[test]
    fn failed_hop_is_not_promotable() {
        // Finding 2: dead-but-retained peer must not be resurrected.
        let hop = 0xA2;
        let hop_addr = addr(4002);
        let via_addr = addr(4099);
        let a2n = DashMap::new();
        a2n.insert(hop_addr, hop);
        let fd = detector();
        fd.heartbeat(hop, hop_addr);
        std::thread::sleep(Duration::from_millis(5));
        assert_eq!(fd.check_all(), vec![hop], "precondition: hop is Failed");
        assert_eq!(fd.status(hop), NodeStatus::Failed);
        assert!(
            !MeshNode::promotable_direct_hop(&a2n, &fd, hop, hop_addr, via_addr),
            "a Failed hop must never be promoted (un-displaceable metric-1 black hole)"
        );
    }

    #[test]
    fn relayed_hop_is_not_promotable() {
        // Finding 1: a relayed hop's recorded addr is the relay's and
        // does not map back to the hop in addr_to_node.
        let hop = 0xA3;
        let relay_addr = addr(4003);
        let via_addr = addr(4099);
        let a2n = DashMap::new();
        // relay_addr maps to some OTHER node (the relay), not `hop`.
        a2n.insert(relay_addr, 0xBEEF);
        let fd = detector();
        fd.heartbeat(hop, relay_addr); // hop itself is Healthy
        assert!(
            !MeshNode::promotable_direct_hop(&a2n, &fd, hop, relay_addr, via_addr),
            "a relayed hop (addr maps to the relay, not the hop) must not be promoted"
        );
    }

    #[test]
    fn hop_at_the_withdrawing_addr_is_not_promotable() {
        // Finding 1: never reinstall through the withdrawing sender's
        // own address — that is the route we just dropped.
        let hop = 0xA4;
        let via_addr = addr(4004);
        let a2n = DashMap::new();
        a2n.insert(via_addr, hop);
        let fd = detector();
        fd.heartbeat(hop, via_addr);
        assert!(
            !MeshNode::promotable_direct_hop(&a2n, &fd, hop, via_addr, via_addr),
            "promoting the withdrawing sender's own address reinstalls the dropped route"
        );
    }

    /// RT-5 review P2: the withdrawal damper keys on `(dest, exclude)`,
    /// not `dest` alone. Two cascades for the same dest but different
    /// split-horizon neighbors reach different recipient sets and must
    /// not suppress one another inside the damp window.
    #[test]
    fn withdraw_damper_keys_on_dest_and_exclude() {
        let damper: DashMap<(u64, Option<u64>), std::time::Instant> = DashMap::new();
        let dest = 0xD;
        let t0 = std::time::Instant::now();

        // A cascade learned from B: admitted, stamps (D, Some(B)).
        assert!(route_withdraw_damp_admit(&damper, (dest, Some(0xB)), t0));
        // The identical key again inside the window: damped.
        assert!(!route_withdraw_damp_admit(&damper, (dest, Some(0xB)), t0));
        // A second loss learned from C must still notify B — a different
        // recipient set, admitted despite (D, Some(B)) being stamped.
        assert!(route_withdraw_damp_admit(&damper, (dest, Some(0xC)), t0));
        // The failure-detector flood (exclude = None) is independent too.
        assert!(route_withdraw_damp_admit(&damper, (dest, None), t0));

        // Once the window elapses, the original key re-admits.
        let t1 = t0 + ROUTE_WITHDRAW_DAMP_WINDOW;
        assert!(route_withdraw_damp_admit(&damper, (dest, Some(0xB)), t1));
    }
}

#[cfg(test)]
mod heartbeat_aead_tests {
    //! Regression for BUG_AUDIT_2026_04_30_CORE.md #85: the mesh
    //! dispatch loop's heartbeat fast-path used to skip AEAD
    //! verification, letting an off-path attacker who observed the
    //! cleartext `session_id` and source UDP address spoof
    //! heartbeats indefinitely. The fix routes through
    //! [`NetSession::verify_and_touch_heartbeat`] before calling
    //! `failure_detector.heartbeat`. The verify+touch are now fused
    //! into the session method so a future caller can't reorder
    //! them or forget to touch on success. These tests pin both
    //! the AEAD-verify outcome AND the touch-on-success/no-touch-
    //! on-failure invariant at the same coverage bar the legacy
    //! single-peer adapter has at
    //! `mod.rs::heartbeat_is_aead_authenticated`.
    use super::*;
    use crate::adapter::net::crypto::{NoiseHandshake, StaticKeypair};
    use crate::adapter::net::pool::PacketBuilder;
    use crate::adapter::net::protocol::{NetHeader, PacketFlags};

    /// Extract the TX counter (bytes 16..24, little-endian u64) from
    /// a serialized packet's header. Both data packets and
    /// heartbeats patch the counter into the same wire-format
    /// position; see `pool.rs::PacketBuilder::build` lines
    /// `header_bytes[16..24].copy_from_slice(&counter.to_le_bytes())`
    /// and the matching line in `build_heartbeat`.
    fn counter_of(packet: &[u8]) -> u64 {
        u64::from_le_bytes(
            packet[16..24]
                .try_into()
                .expect("packet header is at least 24 bytes"),
        )
    }

    fn make_session_keys() -> (
        crate::adapter::net::crypto::SessionKeys,
        crate::adapter::net::crypto::SessionKeys,
    ) {
        let psk = [0x42u8; 32];
        let responder_kp = StaticKeypair::generate();
        let mut initiator = NoiseHandshake::initiator(&psk, &responder_kp.public).unwrap();
        let mut responder = NoiseHandshake::responder(&psk, &responder_kp).unwrap();
        let msg1 = initiator.write_message(&[]).unwrap();
        responder.read_message(&msg1).unwrap();
        let msg2 = responder.write_message(&[]).unwrap();
        initiator.read_message(&msg2).unwrap();
        (
            initiator.into_session_keys().unwrap(),
            responder.into_session_keys().unwrap(),
        )
    }

    #[test]
    fn aead_authenticated_heartbeat_passes_verification_and_touches_session() {
        let (init_keys, resp_keys) = make_session_keys();
        let resp_session = NetSession::new(resp_keys, "127.0.0.1:5000".parse().unwrap(), 4, false);
        let mut builder = PacketBuilder::new(&init_keys.tx_key, init_keys.session_id);
        let bytes = builder.build_heartbeat();

        let parsed = ParsedPacket::parse(bytes, "127.0.0.1:5000".parse().unwrap())
            .expect("legitimate heartbeat must parse");
        assert!(parsed.header.flags.is_heartbeat());

        let last_before = resp_session.last_activity_ns();
        // Sleep so `current_timestamp()` ticks observably forward
        // before `verify_and_touch_heartbeat` reads it.
        std::thread::sleep(std::time::Duration::from_millis(2));

        assert!(
            resp_session.verify_and_touch_heartbeat(&parsed),
            "AEAD-authenticated heartbeat must verify against the matched session"
        );
        assert!(
            resp_session.last_activity_ns() > last_before,
            "successful verify must touch the session — verify+touch are fused"
        );
    }

    #[test]
    fn unauthenticated_heartbeat_fails_verification_and_does_not_touch() {
        let (_init_keys, resp_keys) = make_session_keys();
        let resp_session = NetSession::new(resp_keys, "127.0.0.1:5000".parse().unwrap(), 4, false);

        // Attacker forges a heartbeat header with the right
        // session_id but garbage 16-byte tail. Pre-fix this passed
        // through; post-fix it must fail.
        let mut forged = bytes::BytesMut::new();
        let mut header_bytes = NetHeader::heartbeat(resp_session.session_id()).to_bytes();
        // Stamp a plausible nonce so the receiver gets to decrypt
        // (otherwise it bails earlier on the counter check).
        header_bytes[12..16].copy_from_slice(&[0u8; 4]);
        header_bytes[16..24].copy_from_slice(&1u64.to_le_bytes());
        forged.extend_from_slice(&header_bytes);
        forged.extend_from_slice(&[0xAAu8; 16]); // garbage tag
        let parsed = ParsedPacket::parse(forged.freeze(), "127.0.0.1:5000".parse().unwrap())
            .expect("forged heartbeat must still parse — verification is downstream");
        assert!(parsed.header.flags.is_heartbeat());

        let last_before = resp_session.last_activity_ns();
        std::thread::sleep(std::time::Duration::from_millis(2));

        assert!(
            !resp_session.verify_and_touch_heartbeat(&parsed),
            "heartbeat with garbage AEAD tag must NOT verify — pre-fix the \
             mesh dispatcher would have called session.touch() / \
             failure_detector.heartbeat() unconditionally"
        );
        assert_eq!(
            resp_session.last_activity_ns(),
            last_before,
            "failed verify must NOT touch the session — verify+touch are fused"
        );
    }

    /// Regression for BUG_AUDIT_2026_04_30_CORE.md #87: dropping
    /// a `PeerRegistrationGuard` whose `completed` flag is still
    /// `false` (cancellation, panic, or non-success path) must
    /// run the same rollback the legacy inline error arm did —
    /// remove the peer entry, peer-addr mapping, and routing
    /// table entry, but only if those entries still match the
    /// values this handshake wrote (a concurrent retry may have
    /// replaced them).
    #[tokio::test]
    async fn peer_registration_guard_rolls_back_on_drop_when_not_completed() {
        let peer_id = 0xDEAD_BEEFu64;
        let next_hop: SocketAddr = "10.0.0.1:9000".parse().unwrap();

        let peers: Arc<DashMap<u64, PeerInfo>> = Arc::new(DashMap::new());
        let peer_addrs: Arc<DashMap<u64, SocketAddr>> = Arc::new(DashMap::new());
        let router = Arc::new(
            NetRouter::new(crate::adapter::net::router::RouterConfig::new(
                0xCAFE_BABE,
                "127.0.0.1:0".parse().unwrap(),
            ))
            .await
            .unwrap(),
        );

        // Simulate the post-handshake registration: insert peer,
        // peer-addr, and a route. We can't construct a fully-
        // populated `PeerInfo` without the matched session keys,
        // but the rollback only inspects `pi.addr`, so we build
        // a minimal session and check post-Drop that the entry
        // is gone.
        let (init_keys, _resp_keys) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, next_hop, 4, false));
        let registered_session_id = session.session_id();
        let session_id_to_node: Arc<DashMap<u64, u64>> = Arc::new(DashMap::new());
        session_id_to_node.insert(registered_session_id, peer_id);
        peers.insert(
            peer_id,
            PeerInfo {
                node_id: peer_id,
                addr: next_hop,
                session,
                remote_static_pub: [0u8; 32],
                last_initiator_ephemeral: None,
            },
        );
        peer_addrs.insert(peer_id, next_hop);
        router.add_route(peer_id, next_hop);

        // Drop guard without committing.
        {
            let _guard = PeerRegistrationGuard {
                peer_node_id: peer_id,
                registered_session_id,
                registered_next_hop: next_hop,
                peers: peers.clone(),
                peer_addrs: peer_addrs.clone(),
                session_id_to_node: session_id_to_node.clone(),
                router: router.clone(),
            };
        } // Drop runs here.

        assert!(
            !peers.contains_key(&peer_id),
            "peers entry must be removed by Drop rollback"
        );
        assert!(
            !peer_addrs.contains_key(&peer_id),
            "peer_addrs entry must be removed by Drop rollback"
        );
        assert!(
            !session_id_to_node.contains_key(&registered_session_id),
            "session_id_to_node entry must be removed by Drop rollback (PERF_AUDIT §2.4)"
        );
        assert!(
            router.routing_table().lookup(peer_id).is_none(),
            "route must be removed by Drop rollback"
        );
    }

    #[tokio::test]
    async fn peer_registration_guard_is_no_op_on_drop_when_completed() {
        let peer_id = 0xCAFE_F00Du64;
        let next_hop: SocketAddr = "10.0.0.2:9000".parse().unwrap();

        let peers: Arc<DashMap<u64, PeerInfo>> = Arc::new(DashMap::new());
        let peer_addrs: Arc<DashMap<u64, SocketAddr>> = Arc::new(DashMap::new());
        let router = Arc::new(
            NetRouter::new(crate::adapter::net::router::RouterConfig::new(
                0xCAFE_BABE,
                "127.0.0.1:0".parse().unwrap(),
            ))
            .await
            .unwrap(),
        );

        let (init_keys, _resp_keys) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, next_hop, 4, false));
        let registered_session_id = session.session_id();
        let session_id_to_node: Arc<DashMap<u64, u64>> = Arc::new(DashMap::new());
        session_id_to_node.insert(registered_session_id, peer_id);
        peers.insert(
            peer_id,
            PeerInfo {
                node_id: peer_id,
                addr: next_hop,
                session,
                remote_static_pub: [0u8; 32],
                last_initiator_ephemeral: None,
            },
        );
        peer_addrs.insert(peer_id, next_hop);
        router.add_route(peer_id, next_hop);

        {
            let guard = PeerRegistrationGuard {
                peer_node_id: peer_id,
                registered_session_id,
                registered_next_hop: next_hop,
                peers: peers.clone(),
                peer_addrs: peer_addrs.clone(),
                session_id_to_node: session_id_to_node.clone(),
                router: router.clone(),
            };
            // Successful-send path consumes the guard without
            // running Drop's rollback.
            guard.commit();
        }

        assert!(peers.contains_key(&peer_id));
        assert!(peer_addrs.contains_key(&peer_id));
        assert!(
            session_id_to_node.contains_key(&registered_session_id),
            "commit() must preserve session_id_to_node alongside the other maps"
        );
        assert!(router.routing_table().lookup(peer_id).is_some());
    }

    /// Regression: if a concurrent retry has overwritten the
    /// peer-addr / route to a different next-hop, the guard's
    /// rollback must NOT clobber the newer (valid) registration.
    /// Mirrors the `remove_if`/`remove_route_if_next_hop_is`
    /// guarantees from the original inline rollback.
    #[tokio::test]
    async fn peer_registration_guard_preserves_concurrent_overwrite() {
        let peer_id = 0xFACE_F00Du64;
        let stale: SocketAddr = "10.0.0.3:9000".parse().unwrap();
        let fresh: SocketAddr = "10.0.0.4:9000".parse().unwrap();

        let peers: Arc<DashMap<u64, PeerInfo>> = Arc::new(DashMap::new());
        let peer_addrs: Arc<DashMap<u64, SocketAddr>> = Arc::new(DashMap::new());
        let router = Arc::new(
            NetRouter::new(crate::adapter::net::router::RouterConfig::new(
                0xCAFE_BABE,
                "127.0.0.1:0".parse().unwrap(),
            ))
            .await
            .unwrap(),
        );

        let (init_keys, _resp_keys) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, fresh, 4, false));
        let fresh_session_id = session.session_id();
        // The stale guard carries a DIFFERENT session_id — the
        // simulated concurrent retry installed a fresh session under
        // the same peer_node_id with a new session_id. The rollback
        // must not touch the fresh entry under the reverse index.
        let stale_session_id = fresh_session_id.wrapping_add(0xDEAD_BEEF);
        let session_id_to_node: Arc<DashMap<u64, u64>> = Arc::new(DashMap::new());
        session_id_to_node.insert(fresh_session_id, peer_id);
        // Concurrent retry has overwritten with `fresh` — the
        // stale guard about to drop should NOT remove this.
        peers.insert(
            peer_id,
            PeerInfo {
                node_id: peer_id,
                addr: fresh,
                session,
                remote_static_pub: [0u8; 32],
                last_initiator_ephemeral: None,
            },
        );
        peer_addrs.insert(peer_id, fresh);
        router.add_route(peer_id, fresh);

        {
            let _guard = PeerRegistrationGuard {
                peer_node_id: peer_id,
                registered_session_id: stale_session_id, // NOT the live session_id
                registered_next_hop: stale,              // NOT what's currently in the maps
                peers: peers.clone(),
                peer_addrs: peer_addrs.clone(),
                session_id_to_node: session_id_to_node.clone(),
                router: router.clone(),
            };
        }

        assert!(
            peers.contains_key(&peer_id),
            "peers must keep the fresh (concurrent-retry) entry"
        );
        assert_eq!(*peer_addrs.get(&peer_id).unwrap(), fresh);
        assert!(
            session_id_to_node.contains_key(&fresh_session_id),
            "session_id_to_node must keep the fresh entry — the stale guard's session_id \
             differs, so remove_if leaves the live entry alone"
        );
        assert_eq!(router.routing_table().lookup(peer_id), Some(fresh));
    }

    /// PERF_AUDIT §2.4 regression: the routed-local dispatch
    /// lookup must resolve via the `session_id → node_id` reverse
    /// index AND defensively re-check that the resolved peer's
    /// session_id still matches. A stale reverse-index entry (peer
    /// re-handshaken under the same node_id with a new session_id,
    /// reverse-index update racing with the inbound packet) would
    /// otherwise route the old packet to the wrong session.
    ///
    /// This pins the helper closure logic that lives in
    /// `dispatch_packet`'s routed branch:
    ///
    /// ```ignore
    /// session_id_to_node.get(session_id)
    ///     .and_then(|nid| peers.get(nid).map(|e| (nid, e.session.clone())))
    ///     .filter(|(_, sess)| sess.session_id() == session_id)
    /// ```
    ///
    /// Without the `.filter`, the second test case below would
    /// resolve to the FRESH session despite the inbound packet
    /// carrying the OLD session_id, and the receiver would AEAD-
    /// verify against the wrong key.
    #[tokio::test]
    async fn routed_dispatch_lookup_filters_session_id_mismatch() {
        let peer_id = 0xBEEF_CAFEu64;
        let peer_addr: SocketAddr = "10.1.1.1:9000".parse().unwrap();

        let peers: Arc<DashMap<u64, PeerInfo>> = Arc::new(DashMap::new());
        let session_id_to_node: Arc<DashMap<u64, u64>> = Arc::new(DashMap::new());

        let (init_keys, _resp_keys) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, peer_addr, 4, false));
        let live_session_id = session.session_id();
        peers.insert(
            peer_id,
            PeerInfo {
                node_id: peer_id,
                addr: peer_addr,
                session,
                remote_static_pub: [0u8; 32],
                last_initiator_ephemeral: None,
            },
        );
        session_id_to_node.insert(live_session_id, peer_id);

        // Case 1 — the happy path: an inbound packet carrying the
        // live session_id resolves to (peer_id, session) directly.
        let resolved = session_id_to_node
            .get(&live_session_id)
            .map(|e| *e.value())
            .and_then(|nid| peers.get(&nid).map(|e| (nid, e.value().session.clone())))
            .filter(|(_, s)| s.session_id() == live_session_id);
        assert!(
            resolved.is_some(),
            "fresh inbound for the live session_id must resolve via the reverse index"
        );
        let (resolved_node, resolved_session) = resolved.unwrap();
        assert_eq!(resolved_node, peer_id);
        assert_eq!(resolved_session.session_id(), live_session_id);

        // Case 2 — stale reverse-index entry: the peer was
        // re-handshaken under the same node_id and the live
        // session_id changed. An inbound packet carrying the OLD
        // session_id must NOT be routed to the live session (the
        // AEAD key would be wrong). The `.filter` clause is what
        // catches this — without it, the lookup would happily
        // resolve to the new session by node_id.
        let old_session_id = live_session_id.wrapping_add(1);
        session_id_to_node.insert(old_session_id, peer_id);
        let stale = session_id_to_node
            .get(&old_session_id)
            .map(|e| *e.value())
            .and_then(|nid| peers.get(&nid).map(|e| (nid, e.value().session.clone())))
            .filter(|(_, s)| s.session_id() == old_session_id);
        assert!(
            stale.is_none(),
            "stale reverse-index entry must NOT resolve to the live session — \
             the .filter() guard preserves the pre-fix `peers.iter().find(matching session_id)` \
             semantic that returned None in the same scenario"
        );
    }

    /// PERF_AUDIT §2.4 regression: a peer re-handshake replaces
    /// the `PeerInfo` under the same node_id with a fresh session
    /// (new session_id). The reverse index must evict the
    /// displaced session_id's entry alongside installing the new
    /// one — otherwise every re-handshake leaks one stale entry
    /// forever (the `.filter` guard in dispatch makes stale
    /// entries harmless for routing, but the map grows without
    /// bound across rotations).
    #[tokio::test]
    async fn install_peer_replacement_evicts_displaced_reverse_index_entry() {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x2Au8; 32]);
        let node = MeshNode::new(EntityKeypair::generate(), cfg)
            .await
            .expect("MeshNode::new");

        let peer_id = 0xFEED_F00Du64;
        let peer_addr: SocketAddr = "10.2.2.2:9100".parse().unwrap();

        let (first_keys, _) = make_session_keys();
        let first_session_id = first_keys.session_id;
        node.install_peer(
            peer_id,
            peer_addr,
            first_keys,
            AddrInstallMode::DirectOverwrite,
        );
        assert_eq!(
            node.session_id_to_node.get(&first_session_id).map(|e| *e),
            Some(peer_id),
            "first install must populate the reverse index"
        );

        // Re-handshake: fresh keys → fresh session_id under the
        // SAME node_id.
        let (second_keys, _) = make_session_keys();
        let second_session_id = second_keys.session_id;
        assert_ne!(
            first_session_id, second_session_id,
            "fresh handshake must derive a distinct session_id"
        );
        node.install_peer(
            peer_id,
            peer_addr,
            second_keys,
            AddrInstallMode::DirectOverwrite,
        );

        assert_eq!(
            node.session_id_to_node.get(&second_session_id).map(|e| *e),
            Some(peer_id),
            "replacement install must index the fresh session_id"
        );
        assert!(
            !node.session_id_to_node.contains_key(&first_session_id),
            "displaced session_id must be evicted from the reverse index — \
             leaving it would leak one entry per re-handshake"
        );
        assert_eq!(
            node.session_id_to_node.len(),
            1,
            "exactly one reverse-index entry per live peer session"
        );
    }

    /// Direct-path upgrade C2: `install_peer_cas` refuses to overwrite
    /// when the peer's current session_id no longer matches the one
    /// the upgrade observed — a racing handshake won, and clobbering it
    /// is exactly the F5 nondeterminism the CAS removes. The working
    /// session is left intact.
    #[tokio::test]
    async fn install_peer_cas_refuses_on_session_id_mismatch() {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x2Cu8; 32]);
        let node = MeshNode::new(EntityKeypair::generate(), cfg)
            .await
            .expect("MeshNode::new");

        let peer_id = 0xAB_CD_EF_01u64;
        let relay_addr: SocketAddr = "10.9.9.9:9100".parse().unwrap();
        let (relay_keys, _) = make_session_keys();
        let relay_session_id = relay_keys.session_id;
        node.install_peer(
            peer_id,
            relay_addr,
            relay_keys,
            AddrInstallMode::RoutedPreserve,
        );

        // A racing rotation installs a DIFFERENT session for the peer
        // (simulated by a plain install). The upgrade below still holds
        // the OLD session_id as its expectation.
        let (raced_keys, _) = make_session_keys();
        let raced_session_id = raced_keys.session_id;
        node.install_peer(
            peer_id,
            relay_addr,
            raced_keys,
            AddrInstallMode::RoutedPreserve,
        );

        // Upgrade tries to install a punched session but expects the
        // pre-race session_id → CAS must refuse.
        let punched_addr: SocketAddr = "10.1.1.1:7000".parse().unwrap();
        let (punch_keys, _) = make_session_keys();
        let installed = node.install_peer_cas(
            peer_id,
            punched_addr,
            punch_keys,
            AddrInstallMode::DirectOverwrite,
            Some(relay_session_id),
        );
        assert!(!installed, "CAS must refuse when the session_id changed");
        // The raced session survives untouched.
        assert_eq!(
            node.peers
                .get(&peer_id)
                .map(|p| p.value().session.session_id()),
            Some(raced_session_id),
            "the racing session must be left intact after a refused CAS",
        );
        assert!(
            !node.addr_to_node.contains_key(&punched_addr),
            "a refused CAS must not touch addr_to_node",
        );
    }

    /// C2 happy path: when the observed session_id still matches,
    /// `install_peer_cas` installs the new (punched) session and the
    /// C4 hygiene removes the displaced relay addr's stale reverse
    /// mapping.
    #[tokio::test]
    async fn install_peer_cas_installs_and_cleans_stale_addr_on_match() {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x2Du8; 32]);
        let node = MeshNode::new(EntityKeypair::generate(), cfg)
            .await
            .expect("MeshNode::new");

        let peer_id = 0x11_22_33_44u64;
        // Direct install so addr_to_node[old_addr] = peer_id (a
        // stale mapping the swap should clean up).
        let old_addr: SocketAddr = "10.5.5.5:9100".parse().unwrap();
        let (first_keys, _) = make_session_keys();
        let first_session_id = first_keys.session_id;
        node.install_peer(
            peer_id,
            old_addr,
            first_keys,
            AddrInstallMode::DirectOverwrite,
        );
        assert_eq!(
            node.addr_to_node.get(&old_addr).map(|e| *e),
            Some(peer_id),
            "precondition: old addr maps to the peer",
        );

        let new_addr: SocketAddr = "10.1.1.1:7000".parse().unwrap();
        let (punch_keys, _) = make_session_keys();
        let punch_session_id = punch_keys.session_id;
        let installed = node.install_peer_cas(
            peer_id,
            new_addr,
            punch_keys,
            AddrInstallMode::DirectOverwrite,
            Some(first_session_id),
        );
        assert!(installed, "CAS must install when the session_id matches");
        assert_eq!(
            node.peers
                .get(&peer_id)
                .map(|p| p.value().session.session_id()),
            Some(punch_session_id),
            "the punched session must replace the old one",
        );
        assert_eq!(
            node.addr_to_node.get(&new_addr).map(|e| *e),
            Some(peer_id),
            "the new addr must map to the peer",
        );
        assert!(
            !node.addr_to_node.contains_key(&old_addr),
            "C4: the displaced addr's stale reverse mapping must be removed",
        );
    }

    /// PERF_AUDIT §2.8 regression — the grant-path fast path must
    /// be SELF-PRIMING: a fallback resolution publishes the node id
    /// onto the session so the next packet takes the tier-1 atomic
    /// load. b45bc44b8 originally shipped without the publish, so
    /// the cache stayed empty for any session whose traffic never
    /// traversed the cortex RPC dispatch hook (plain reliable
    /// streams) and the fast path was dead. Also pins the stale-
    /// cache safety: a replaced session's resolution must fail the
    /// session-id cross-check rather than misroute to the
    /// replacement peer entry.
    #[tokio::test]
    async fn grant_peer_resolution_self_primes_node_id_cache() {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x2Bu8; 32]);
        let node = MeshNode::new(EntityKeypair::generate(), cfg)
            .await
            .expect("MeshNode::new");

        let peer_id = 0xCAFE_D00Du64;
        let peer_addr: SocketAddr = "10.3.3.3:9100".parse().unwrap();
        let (keys, _) = make_session_keys();
        node.install_peer(peer_id, peer_addr, keys, AddrInstallMode::DirectOverwrite);
        let session = node
            .peers
            .get(&peer_id)
            .map(|p| p.value().session.clone())
            .expect("peer installed");
        assert_eq!(
            session.cached_node_id(),
            None,
            "install_peer must not pre-prime the cache (lazy by design)"
        );

        // First resolution: tier 1 misses, the fallback resolves via
        // addr_to_node AND publishes the node id.
        let (resolved_addr, resolved_session) =
            MeshNode::resolve_grant_peer(&node.peers, &node.addr_to_node, &session)
                .expect("fallback chain resolves the installed peer");
        assert_eq!(resolved_addr, peer_addr);
        assert_eq!(resolved_session.session_id(), session.session_id());
        assert_eq!(
            session.cached_node_id(),
            Some(peer_id),
            "fallback resolution must publish the cache (self-priming)"
        );

        // Second resolution: tier 1 must carry it alone — drop the
        // addr_to_node entry to prove the fallback chain is no
        // longer needed for this session.
        node.addr_to_node.remove(&peer_addr);
        let (addr2, _) = MeshNode::resolve_grant_peer(&node.peers, &node.addr_to_node, &session)
            .expect("tier-1 cached resolution");
        assert_eq!(addr2, peer_addr);

        // Stale-cache safety: a re-handshake replaces the session
        // under the same node id. The OLD session's cached id now
        // points at a peer entry whose session_id no longer matches
        // — tier 1 must reject it, and with no addr or scan match
        // for the dead session the resolution returns None instead
        // of misrouting a grant to the replacement session.
        let (new_keys, _) = make_session_keys();
        node.install_peer(
            peer_id,
            peer_addr,
            new_keys,
            AddrInstallMode::DirectOverwrite,
        );
        assert!(
            MeshNode::resolve_grant_peer(&node.peers, &node.addr_to_node, &session).is_none(),
            "stale session must not resolve to the replacement peer entry"
        );
    }

    /// Regression for BUG_AUDIT_2026_04_30_CORE.md #97: the
    /// production heartbeat path must (a) build with the
    /// session's actual TX key — not `&[0u8; 32]` — and (b) use a
    /// **shared** `tx_counter` across builders so successive
    /// heartbeats don't all encrypt under counter=0 and trigger
    /// the receiver's replay window. Both bugs were latent before
    /// #85 wired up AEAD verification on the mesh receiver; this
    /// test pins the post-fix invariant by acquiring two builders
    /// from the SAME session pool (mirroring what the heartbeat
    /// timer at `mesh.rs:3220` does on each tick) and verifying
    /// that BOTH heartbeats verify against the peer session in
    /// order. Pre-fix behavior with the all-zero key would fail
    /// the first verify; pre-fix behavior with per-builder
    /// counters would fail the second.
    #[test]
    fn pooled_heartbeat_builds_succeed_in_sequence_and_verify() {
        let (init_keys, resp_keys) = make_session_keys();
        let init_session = NetSession::new(
            init_keys.clone(),
            "127.0.0.1:5001".parse().unwrap(),
            4,
            false,
        );
        let resp_session = NetSession::new(resp_keys, "127.0.0.1:5000".parse().unwrap(), 4, false);

        // Mirror the production sender — go through
        // `Session::build_heartbeat`, not a fresh
        // `PacketBuilder::new`.
        let h1_bytes = init_session.build_heartbeat();
        let h2_bytes = init_session.build_heartbeat();

        let p1 = ParsedPacket::parse(h1_bytes, "127.0.0.1:5001".parse().unwrap())
            .expect("first heartbeat must parse");
        let p2 = ParsedPacket::parse(h2_bytes, "127.0.0.1:5001".parse().unwrap())
            .expect("second heartbeat must parse");

        assert!(
            resp_session.verify_and_touch_heartbeat(&p1),
            "first pooled heartbeat must verify — pre-fix the \
             all-zero key would have produced an AEAD tag the \
             receiver couldn't decrypt"
        );
        assert!(
            resp_session.verify_and_touch_heartbeat(&p2),
            "second pooled heartbeat must also verify — pre-fix, \
             a per-builder fresh counter would reuse counter=0 \
             and the receiver's replay window would reject this \
             as a duplicate"
        );
    }

    #[test]
    fn replay_of_authenticated_heartbeat_fails_verification_on_second_try() {
        let (init_keys, resp_keys) = make_session_keys();
        let resp_session = NetSession::new(resp_keys, "127.0.0.1:5000".parse().unwrap(), 4, false);
        let mut builder = PacketBuilder::new(&init_keys.tx_key, init_keys.session_id);
        let bytes = builder.build_heartbeat();
        let parsed = ParsedPacket::parse(bytes, "127.0.0.1:5000".parse().unwrap()).unwrap();

        assert!(resp_session.verify_and_touch_heartbeat(&parsed));
        // Replay: counter is now committed, so the second attempt
        // must fail at the replay-window check.
        assert!(
            !resp_session.verify_and_touch_heartbeat(&parsed),
            "replay of an already-accepted heartbeat must fail"
        );
    }

    /// Invariant: heartbeats and data-path packets share a
    /// single TX counter via `thread_local_pool`. Pre-#106-fix,
    /// `NetSession` exposed two pools (`packet_pool` and
    /// `thread_local_pool`) with the same key but independent
    /// counters; a caller that mixed `session.packet_pool().get()`
    /// for some packets and `session.thread_local_pool().get()` for
    /// others would produce ChaCha20-Poly1305 nonce reuse against
    /// the same key, leaking plaintext via XOR.
    ///
    /// The fix removed `packet_pool` and routes all TX through
    /// `thread_local_pool`. Today `Session::build_heartbeat` calls
    /// `self.thread_local_pool.get().build_heartbeat()` and the
    /// data path builds via `self.thread_local_pool.get().build(...)`.
    /// This test pins the resulting wire-level invariant: the
    /// counters on heartbeat and data packets interleave strictly
    /// monotonically (no two packets ever share a counter, no
    /// matter the order they're built in). A future contributor who
    /// re-introduced a separate pool/counter for heartbeats would
    /// see this test fail because both sequences would restart at
    /// 0.
    #[test]
    fn heartbeat_and_data_share_tx_counter_strictly_monotonic() {
        let (init_keys, _resp_keys) = make_session_keys();
        let init_session = NetSession::new(
            init_keys.clone(),
            "127.0.0.1:5001".parse().unwrap(),
            4,
            false,
        );

        // Build sequence: heartbeat, data, heartbeat, data,
        // heartbeat. All five must have strictly-increasing
        // counters.
        let h1 = init_session.build_heartbeat();
        let d1 = {
            let mut pooled = init_session.thread_local_pool().get();
            pooled.build(
                0xCAFE_F00D,
                0,
                &[bytes::Bytes::from_static(b"event-a")],
                PacketFlags::NONE,
            )
        };
        let h2 = init_session.build_heartbeat();
        let d2 = {
            let mut pooled = init_session.thread_local_pool().get();
            pooled.build(
                0xCAFE_F00D,
                1,
                &[bytes::Bytes::from_static(b"event-b")],
                PacketFlags::NONE,
            )
        };
        let h3 = init_session.build_heartbeat();

        let counters = [
            counter_of(&h1),
            counter_of(&d1),
            counter_of(&h2),
            counter_of(&d2),
            counter_of(&h3),
        ];

        // Strict monotonicity: each counter > the previous one.
        for window in counters.windows(2) {
            assert!(
                window[0] < window[1],
                "tx counters must be strictly increasing across heartbeat/data \
                 interleave; got {:?} (regression: heartbeats and data \
                 are drawing from independent counters)",
                counters
            );
        }
    }

    /// CR-8: source-level tripwire pinning that no dispatch
    /// branch uses `events.into_iter().next()` to drop multi-event
    /// frames. The original fix only patched
    /// `SUBPROTOCOL_STREAM_WINDOW`; CR-8 extended the same fix to
    /// the migration / channel-membership / capability-ann / reflex
    /// / rendezvous branches. This test scans the file source for
    /// any new occurrence outside fix-doc comments and fails loudly
    /// if a future maintainer reintroduces the pattern.
    ///
    /// We assemble the forbidden token at runtime so the test's
    /// own source doesn't trigger itself.
    #[test]
    fn cr8_dispatch_must_not_use_single_event_pattern() {
        // Build the forbidden token from fragments so this test's
        // source doesn't contain the literal substring.
        let needle = format!("events.into_iter().{}()", "next");

        let src = include_str!("mesh.rs");
        for (lineno, line) in src.lines().enumerate() {
            let trimmed = line.trim_start();
            // Skip line comments and doc comments — these are
            // ALLOWED to mention the pre-fix shape (the fix-doc
            // narratives are load-bearing context for future
            // maintainers).
            if trimmed.starts_with("//") {
                continue;
            }
            // Skip lines inside doc-string-style comments inside
            // string literals: we don't try to be too clever here,
            // since a code line containing `events.into_iter().next()`
            // outside a comment is the regression we want to catch.
            assert!(
                !trimmed.contains(&needle),
                "CR-8 regression: single-event dispatch pattern reintroduced \
                 at mesh.rs:{} — multi-event frames will silently drop \
                 every payload past the first.\n  line: {}",
                lineno + 1,
                line
            );
        }
    }

    /// Source-level pin: every `hop_count += 1` / `hop_count = X + 1`
    /// pattern in this file MUST go through `saturating_add`.
    /// `hop_count: u8` saturates at 255; an attacker-controlled
    /// inbound packet whose `hop_count` is already u8::MAX would
    /// debug-panic (`overflow`) or release-wraparound to 0 on a
    /// bare `+= 1`. Today the upstream `< MAX_CAPABILITY_HOPS - 1`
    /// guard bounds the value at 14 before the bump, so the
    /// saturating call is dormant — but a future change that
    /// raises the cap or relaxes the guard would otherwise turn
    /// an attacker byte into UB / wrap. This pin ensures the
    /// hardening stays in place even if the upstream gate moves.
    /// Regression for `BUG_AUDIT_2026_05_03_MESH.md` #3 (replay
    /// guard arm): a routed msg1 whose `remote_static_pub` matches
    /// the live session's static must be dropped so the live
    /// session's keys aren't overwritten by NKpsk0's fresh-ephemeral
    /// reply.
    #[test]
    fn routed_rotation_outcome_drops_replay_for_matching_static_and_ephemeral() {
        let addr: SocketAddr = "10.0.0.1:9000".parse().unwrap();
        let (init_keys, _) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, addr, 4, false));
        let static_a = [0xAAu8; 32];
        let ephemeral_a = [0xCCu8; 32];
        let info = PeerInfo {
            node_id: 0xBEEF_BEEFu64,
            addr,
            session,
            remote_static_pub: static_a,
            last_initiator_ephemeral: Some(ephemeral_a),
        };
        assert_eq!(
            routed_rotation_outcome(&info, &static_a, &ephemeral_a, Duration::from_secs(30)),
            RoutedRotationOutcome::DropReplay,
        );
    }

    /// Regression for the pass-2 follow-up: a routed msg1 with the
    /// SAME static but a DIFFERENT ephemeral is a legitimate
    /// re-handshake from the same peer (only the static + PSK
    /// holder can produce a fresh ephemeral). Pre-fix the gate
    /// flagged this as a replay and refused — breaking the
    /// `connect_direct` retarget path. AcceptRotation now.
    #[test]
    fn routed_rotation_outcome_accepts_reinit_with_fresh_ephemeral() {
        let addr: SocketAddr = "10.0.0.1:9000".parse().unwrap();
        let (init_keys, _) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, addr, 4, false));
        let static_a = [0xAAu8; 32];
        let ephemeral_old = [0xCCu8; 32];
        let ephemeral_new = [0xDDu8; 32];
        let info = PeerInfo {
            node_id: 0xBEEF_BEEFu64,
            addr,
            session,
            remote_static_pub: static_a,
            last_initiator_ephemeral: Some(ephemeral_old),
        };
        assert_eq!(
            routed_rotation_outcome(&info, &static_a, &ephemeral_new, Duration::from_secs(30)),
            RoutedRotationOutcome::AcceptRotation,
        );
    }

    /// Regression for `BUG_AUDIT_2026_05_03_MESH.md` #3 (rotation
    /// gate, fresh-session arm): a routed msg1 with a *different*
    /// `remote_static_pub` for an existing peer must NOT overwrite
    /// the live session while the existing session is still within
    /// `session_timeout`. Pre-fix this branch unconditionally
    /// inserted the new keys, opening a trivial DoS where any party
    /// with the PSK and a valid Noise static could break AEAD
    /// verification on every legitimate packet to the affected peer.
    #[test]
    fn routed_rotation_outcome_refuses_rotation_while_session_is_fresh() {
        let addr: SocketAddr = "10.0.0.1:9000".parse().unwrap();
        let (init_keys, _) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, addr, 4, false));
        let info = PeerInfo {
            node_id: 0xBEEF_BEEFu64,
            addr,
            session,
            remote_static_pub: [0xAAu8; 32],
            last_initiator_ephemeral: Some([0xCCu8; 32]),
        };
        let new_static = [0xBBu8; 32];
        let new_ephemeral = [0xDDu8; 32];
        assert_eq!(
            routed_rotation_outcome(&info, &new_static, &new_ephemeral, Duration::from_secs(30),),
            RoutedRotationOutcome::RefuseFresh,
        );
    }

    /// Companion to the fresh-session refusal: once the live session
    /// has gone silent for at least `session_timeout`, a rotation
    /// from a different `remote_static_pub` IS accepted. This pins
    /// that the gate eventually unblocks — a permanent refusal would
    /// be a different kind of bug (legitimate peers rotating keys
    /// could never reconnect).
    #[test]
    fn routed_rotation_outcome_accepts_rotation_after_session_timeout() {
        let addr: SocketAddr = "10.0.0.1:9000".parse().unwrap();
        let (init_keys, _) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, addr, 4, false));
        let info = PeerInfo {
            node_id: 0xBEEF_BEEFu64,
            addr,
            session,
            remote_static_pub: [0xAAu8; 32],
            last_initiator_ephemeral: Some([0xCCu8; 32]),
        };
        // Wait past a 1 ms session_timeout. `current_timestamp()`
        // uses wall-clock `SystemTime::now()` so a real sleep
        // advances it.
        std::thread::sleep(Duration::from_millis(5));
        let new_static = [0xBBu8; 32];
        let new_ephemeral = [0xDDu8; 32];
        assert_eq!(
            routed_rotation_outcome(&info, &new_static, &new_ephemeral, Duration::from_millis(1),),
            RoutedRotationOutcome::AcceptRotation,
        );
    }

    /// Direct-path upgrade C3 (responder half): a same-static
    /// re-handshake that would normally rotate is DEFERRED when the
    /// existing session is live and busy (an open application stream),
    /// so an in-flight transfer isn't dropped by the swap.
    #[test]
    fn routed_rotation_outcome_defers_while_session_busy() {
        let addr: SocketAddr = "10.0.0.1:9000".parse().unwrap();
        let (init_keys, _) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, addr, 4, false));
        // Open an application stream → the session is now "busy".
        session.get_or_create_stream(1);
        assert!(session.has_open_streams(), "precondition: session is busy");
        let static_a = [0xAAu8; 32];
        let info = PeerInfo {
            node_id: 0xBEEF_BEEFu64,
            addr,
            session,
            remote_static_pub: static_a,
            last_initiator_ephemeral: Some([0xCCu8; 32]),
        };
        // Same static, fresh ephemeral, live (30 s timeout) + busy.
        assert_eq!(
            routed_rotation_outcome(&info, &static_a, &[0xDDu8; 32], Duration::from_secs(30)),
            RoutedRotationOutcome::DeferBusy,
        );
    }

    /// The DeferBusy liveness bound: a busy session that has gone idle
    /// past `session_timeout` rotates anyway (AcceptRotation), so a
    /// genuinely dead path — e.g. the peer recovering after a NAT
    /// rebind — is never blocked by stale "busy" state.
    #[test]
    fn routed_rotation_outcome_accepts_busy_session_past_timeout() {
        let addr: SocketAddr = "10.0.0.1:9000".parse().unwrap();
        let (init_keys, _) = make_session_keys();
        let session = Arc::new(NetSession::new(init_keys, addr, 4, false));
        session.get_or_create_stream(1);
        assert!(session.has_open_streams(), "precondition: session is busy");
        let static_a = [0xAAu8; 32];
        let info = PeerInfo {
            node_id: 0xBEEF_BEEFu64,
            addr,
            session,
            remote_static_pub: static_a,
            last_initiator_ephemeral: Some([0xCCu8; 32]),
        };
        // Let the session go idle past a 1 ms timeout — not live.
        std::thread::sleep(Duration::from_millis(5));
        assert_eq!(
            routed_rotation_outcome(&info, &static_a, &[0xDDu8; 32], Duration::from_millis(1)),
            RoutedRotationOutcome::AcceptRotation,
        );
    }

    /// Regression for `BUG_AUDIT_2026_05_03_MESH.md` #9:
    /// `connect_on_direct_path` must refresh
    /// `addr_to_node[target_addr] = peer_node_id` on success.
    /// Pre-fix the closure called `connect_via` which deliberately
    /// does NOT touch `addr_to_node` (correct for relayed sessions
    /// where the relay's address must keep mapping to the relay's
    /// own node_id), so a successful direct upgrade left the
    /// dispatch fast path
    /// (`addr_to_node.get(&source) → peers.get(nid)`) missing on
    /// the upgraded session's reflex addr — every inbound packet
    /// then fell back to a linear `peers.iter().find(|e|
    /// session_id == ...)` for exactly the sessions that benefit
    /// most from the index. Source-level pin so the closure body
    /// keeps the `addr_to_node.insert` after the upgrade lands.
    #[test]
    fn connect_direct_upgrade_refreshes_addr_to_node() {
        let src = include_str!("mesh.rs");
        let start = src
            .find("let connect_on_direct_path =")
            .expect("connect_on_direct_path closure must exist");
        let scan_end = (start + 4000).min(src.len());
        let body = &src[start..scan_end];

        assert!(
            body.contains("self.addr_to_node.insert(target_addr, peer_node_id)"),
            "regression: connect_on_direct_path must refresh addr_to_node \
             on success — pre-fix the dispatch fast path missed on the \
             upgraded session's reflex addr and fell back to a linear \
             peers.iter().find per packet for exactly the sessions that \
             benefit most from the index."
        );
    }

    /// Regression for `BUG_AUDIT_2026_05_03_MESH.md` #8: the
    /// migration-handler loopback drain in `process_local_packet`
    /// must cap the synchronous self-bounce depth. Pre-fix the
    /// in-place `pending: VecDeque` loop drained as long as the
    /// handler emitted self-bound follow-ups, so a buggy or
    /// attacker-influenced handler that always emitted a self-bound
    /// message would spin the dispatch task forever, starving every
    /// other peer's packets. Source-level pin: the constant
    /// `MAX_MIGRATION_LOOPBACK_DEPTH` and a `> MAX_..._DEPTH` guard
    /// must be present in the file. A future change that drops the
    /// guard fails this pin loudly rather than silently
    /// reintroducing the starvation.
    #[test]
    fn migration_loopback_drain_caps_self_bounce_depth() {
        let src = include_str!("mesh.rs");
        assert!(
            src.contains("const MAX_MIGRATION_LOOPBACK_DEPTH: usize"),
            "regression: process_local_packet's migration loopback drain \
             must declare a `MAX_MIGRATION_LOOPBACK_DEPTH` cap. Pre-fix \
             the loop ran unbounded so a handler stuck in a self-bounce \
             state would starve the dispatch task."
        );
        assert!(
            src.contains("loopback_count > MAX_MIGRATION_LOOPBACK_DEPTH"),
            "regression: the migration loopback drain must short-circuit \
             past the depth cap with a warn — the bare `loopback_count += 1; \
             match handler.handle_message(...)` shape without the threshold \
             check leaves the unbounded-spin hazard in place."
        );
    }

    /// Regression for `BUG_AUDIT_2026_05_03_MESH.md` #7:
    /// `publish_to_peer` was the only sender call site that
    /// hard-coded `PacketFlags::NONE` instead of computing
    /// `if reliable { PacketFlags::RELIABLE } else { PacketFlags::NONE }`.
    /// Today the dispatch path doesn't consult `is_reliable()` (per-
    /// stream reliability is set at open), so the inconsistency is
    /// latent — but receiver-side code already consults the packet
    /// flag for `is_priority` / `is_control`, and `is_reliable` is
    /// the obvious next addition. This source-level pin ensures the
    /// fix doesn't get reverted before the dispatch path catches up.
    #[test]
    fn publish_to_peer_propagates_reliable_to_packet_flags() {
        let src = include_str!("mesh.rs");
        let start = src
            .find("async fn publish_to_peer(")
            .expect("publish_to_peer must exist");
        // Round down to a char boundary — the source has multibyte
        // box-drawing characters in doc comments, and a fixed-byte
        // window can land mid-UTF-8 sequence after edits to the
        // surrounding code shift offsets.
        let mut scan_end = (start + 6000).min(src.len());
        while scan_end < src.len() && !src.is_char_boundary(scan_end) {
            scan_end += 1;
        }
        let body = &src[start..scan_end];

        assert!(
            body.contains("if reliable") && body.contains("PacketFlags::RELIABLE"),
            "regression: publish_to_peer must thread `reliable` into the packet \
             header — pre-fix it hard-coded PacketFlags::NONE while only \
             feeding `reliable` into open_stream_with, leaving every other \
             sender call site (send_to_peer, send_routed, send_on_stream) \
             inconsistent."
        );
    }

    /// Regression for `BUG_AUDIT_2026_05_03_MESH.md` #6: the
    /// routed-handshake replay/rotation decision and the subsequent
    /// `peers.insert` must happen under a single `peers.entry`
    /// write guard so two concurrent routed handshakes for the same
    /// `peer_node_id` cannot both pass the existing-static check
    /// and race the insert. The shape pin guards against a future
    /// refactor that reintroduces the get→insert split.
    #[test]
    fn routed_handshake_uses_entry_api_for_atomic_insert() {
        let src = include_str!("mesh.rs");
        // Find `fn handle_routed_handshake` and scan to the next
        // function definition (or 16 KB, whichever comes first).
        let start = src
            .find("fn handle_routed_handshake")
            .expect("handle_routed_handshake must exist");
        let scan_end = (start + 16_000).min(src.len());
        let body = &src[start..scan_end];
        assert!(
            body.contains("ctx.peers.entry(peer_node_id)"),
            "regression: handle_routed_handshake must use peers.entry() so the \
             replay/rotation decision and the insert are atomic. Pre-fix the \
             function used `peers.get` followed by `peers.insert`, which let \
             two concurrent handshakes race the insert and wedge the loser's \
             pending_handshakes state until handshake_timeout."
        );
        // Negative pin: the bare insert pattern outside the entry
        // block would signal a regression to the get→insert split.
        assert!(
            !body.contains("ctx.peers.insert(\n            peer_node_id,"),
            "regression: bare ctx.peers.insert(peer_node_id, ...) reintroduced \
             outside the peers.entry() block — the insert must be gated by the \
             same entry guard as the existing-static check."
        );
    }

    /// Regression for `BUG_AUDIT_2026_05_03_MESH.md` #5 (narrow form):
    /// the idempotent re-subscribe handling in `authorize_subscribe`
    /// must SUPPRESS THE CAP REJECTION ONLY — not short-circuit the
    /// whole auth chain. The original fix (returning `(true, None)`
    /// directly when `is_subscribed` was true) bypassed visibility,
    /// registry, and token validation for any peer already in the
    /// roster, silently outliving auth-state changes (e.g., a
    /// re-emitted Subscribe with a now-revoked token would have been
    /// admitted at the wire level even though the periodic sweep
    /// would later evict the entry). Pin the narrower combined check
    /// so a future "simplification" back to the broad form fails
    /// loudly here rather than re-introducing the bypass.
    #[test]
    fn authorize_subscribe_only_suppresses_cap_for_already_subscribed() {
        let src = include_str!("mesh.rs");
        let start = src
            .find("fn authorize_subscribe(")
            .expect("authorize_subscribe must exist");
        let scan_end = (start + 4_000).min(src.len());
        let body = &src[start..scan_end];

        // Positive: the combined predicate must be present.
        assert!(
            body.contains("let already_subscribed = ctx.roster.is_subscribed("),
            "regression: authorize_subscribe must capture an \
             `already_subscribed` boolean and use it to gate ONLY the \
             cap rejection."
        );
        assert!(
            body.contains("!already_subscribed") && body.contains(">= ctx.max_channels_per_peer"),
            "regression: the cap rejection must be guarded by \
             `!already_subscribed && ... >= max_channels_per_peer` so \
             an under-cap or already-subscribed peer falls through to \
             the visibility / registry / token gates rather than being \
             admitted with `(true, None)` ahead of them."
        );

        // Negative: the broad short-circuit `if is_subscribed { return (true, None) }`
        // must NOT reappear — that was the original over-broad form
        // that bypassed the rest of the auth chain.
        assert!(
            !body.contains("if ctx.roster.is_subscribed(from_node, &channel_id) {\n            return (true, None);"),
            "regression: the broad `if is_subscribed -> return (true, None)` \
             short-circuit reintroduced — this bypasses visibility, \
             registry, and token validation for any peer already in the \
             roster. Use the narrower `!already_subscribed && >= cap` \
             form so the cap rejection is the ONLY thing suppressed."
        );
    }

    #[test]
    fn hop_count_increments_must_be_saturating() {
        // Build the forbidden token at runtime so this test's source
        // doesn't trigger itself.
        let bare_bump = format!("hop_count {} 1", "+=");

        let src = include_str!("mesh.rs");
        for (lineno, line) in src.lines().enumerate() {
            let trimmed = line.trim_start();
            // Comments are allowed to mention the pre-fix shape.
            if trimmed.starts_with("//") {
                continue;
            }
            assert!(
                !trimmed.contains(&bare_bump),
                "hop_count regression: bare `+= 1` reintroduced at \
                 mesh.rs:{} — use `saturating_add(1)` so an attacker-\
                 controlled `hop_count == u8::MAX` cannot wrap.\n  line: {}",
                lineno + 1,
                line,
            );
        }
    }
}

#[cfg(test)]
#[cfg(feature = "redex")]
mod replication_dispatch_tests {
    //! Pure-logic tests for `dispatch_replication_payload`. Covers
    //! the wire-format dispatch routing (header → variant) without
    //! spinning a real `MeshNode`.
    use super::*;
    use crate::adapter::net::redex::{ChannelId, ReplicaRole};
    use crate::adapter::net::redex::{
        Inbound, ReplicationInboundRouter, SyncHeartbeat, SyncNack, SyncNackError, SyncRequest,
        SyncResponse, DISPATCH_SYNC_NACK,
    };
    use parking_lot::Mutex as ParkingMutex;

    #[derive(Default)]
    struct RecorderRouter {
        events: ParkingMutex<Vec<(ChannelId, Inbound)>>,
        /// When set, `try_route` returns the event back unrouted.
        always_reject: ParkingMutex<bool>,
    }

    impl ReplicationInboundRouter for RecorderRouter {
        fn try_route(&self, channel_id: ChannelId, inbound: Inbound) -> Result<(), Inbound> {
            if *self.always_reject.lock() {
                return Err(inbound);
            }
            self.events.lock().push((channel_id, inbound));
            Ok(())
        }
    }

    fn cid_for(name: &str) -> ChannelId {
        let cn = ChannelName::new(name).unwrap();
        ChannelId::from_name(&cn)
    }

    #[test]
    fn heartbeat_dispatches_to_router() {
        let cid = cid_for("test/heartbeat");
        let hb = SyncHeartbeat {
            channel_id: cid,
            tail_seq: 42,
            role: ReplicaRole::Leader,
            wall_clock_ms: 0,
        };
        let payload = hb.to_bytes();
        let router = RecorderRouter::default();
        MeshNode::dispatch_replication_payload(&payload, 0xDEAD_BEEF, &router);
        let events = router.events.lock();
        assert_eq!(events.len(), 1);
        let (got_cid, ref got_inbound) = events[0];
        assert_eq!(got_cid, cid);
        assert!(matches!(
            got_inbound,
            Inbound::Heartbeat {
                from: 0xDEAD_BEEF,
                ..
            }
        ));
    }

    #[test]
    fn sync_request_dispatches_to_router() {
        let cid = cid_for("test/sync_request");
        let req = SyncRequest {
            channel_id: cid,
            since_seq: 100,
            chunk_max: 4096,
            request_id: 0,
            class: Default::default(),
        };
        let payload = req.to_bytes();
        let router = RecorderRouter::default();
        MeshNode::dispatch_replication_payload(&payload, 0x12, &router);
        let events = router.events.lock();
        assert!(matches!(
            events[0].1,
            Inbound::SyncRequest { from: 0x12, .. }
        ));
    }

    #[test]
    fn sync_response_dispatches_to_router() {
        let cid = cid_for("test/sync_response");
        let resp = SyncResponse {
            channel_id: cid,
            first_seq: 0,
            leader_first_retained_seq: 0,
            events: vec![],
            request_id: 0,
        };
        let payload = resp.to_bytes();
        let router = RecorderRouter::default();
        MeshNode::dispatch_replication_payload(&payload, 0x34, &router);
        let events = router.events.lock();
        assert!(matches!(
            events[0].1,
            Inbound::SyncResponse { from: 0x34, .. }
        ));
    }

    #[test]
    fn sync_nack_dispatches_to_router() {
        let cid = cid_for("test/sync_nack");
        let nack = SyncNack {
            channel_id: cid,
            since_seq: 50,
            error_code: SyncNackError::NotLeader,
            leader_first_retained_seq: 0,
            detail: "re-resolve leader".to_string(),
            request_id: 0,
        };
        let payload = nack.to_bytes();
        let router = RecorderRouter::default();
        MeshNode::dispatch_replication_payload(&payload, 0x56, &router);
        let events = router.events.lock();
        assert!(matches!(events[0].1, Inbound::SyncNack { from: 0x56, .. }));
    }

    #[test]
    fn truncated_payload_dropped_silently() {
        let router = RecorderRouter::default();
        // Just the 3-byte header but body is missing.
        let payload: Vec<u8> = vec![0x00, 0x0E, DISPATCH_SYNC_NACK];
        MeshNode::dispatch_replication_payload(&payload, 0, &router);
        assert!(router.events.lock().is_empty());
    }

    #[test]
    fn payload_shorter_than_header_dropped() {
        let router = RecorderRouter::default();
        let payload: Vec<u8> = vec![0x00, 0x0E]; // missing dispatch byte
        MeshNode::dispatch_replication_payload(&payload, 0, &router);
        assert!(router.events.lock().is_empty());
    }

    #[test]
    fn unknown_dispatch_code_dropped() {
        let router = RecorderRouter::default();
        // Valid subprotocol id, but dispatch code outside
        // 0x20..=0x23 (the implemented range). 0x2F is in the
        // reserved-future range.
        let payload: Vec<u8> = vec![0x00, 0x0E, 0x2F, 0xAA, 0xBB];
        MeshNode::dispatch_replication_payload(&payload, 0, &router);
        assert!(router.events.lock().is_empty());
    }

    #[test]
    fn wrong_subprotocol_id_in_payload_dropped() {
        // Payload's leading 2 bytes claim a different
        // subprotocol id — the per-message decoder rejects it.
        let cid = cid_for("test/wrong_subprotocol");
        let hb = SyncHeartbeat {
            channel_id: cid,
            tail_seq: 0,
            role: ReplicaRole::Leader,
            wall_clock_ms: 0,
        };
        let mut payload = hb.to_bytes();
        payload[0] = 0x00;
        payload[1] = 0x05; // SUBPROTOCOL_MIGRATION
        let router = RecorderRouter::default();
        MeshNode::dispatch_replication_payload(&payload, 0, &router);
        assert!(router.events.lock().is_empty());
    }

    #[test]
    fn router_rejection_swallowed_silently() {
        // Router returns the event back (full buffer / unknown
        // channel). Dispatch hot-path must not panic; the event
        // is simply dropped.
        let cid = cid_for("test/rejection");
        let hb = SyncHeartbeat {
            channel_id: cid,
            tail_seq: 0,
            role: ReplicaRole::Leader,
            wall_clock_ms: 0,
        };
        let payload = hb.to_bytes();
        let router = RecorderRouter::default();
        *router.always_reject.lock() = true;
        // Should not panic.
        MeshNode::dispatch_replication_payload(&payload, 0, &router);
        assert!(router.events.lock().is_empty());
    }
}

#[cfg(test)]
mod chain_helper_tests {
    //! Pure-logic tests for `Mesh::chain_hex` / `is_causal_for` /
    //! `replace_causal_tags`. The integration-flavored variants
    //! that spin a real `MeshNode` live in
    //! `net/crates/net/tests/chain_discovery.rs`.
    use super::*;
    use crate::adapter::net::behavior::capability::CapabilitySet;
    use crate::adapter::net::behavior::tag::Tag;

    #[test]
    fn chain_hex_is_lowercase_16_chars() {
        assert_eq!(MeshNode::chain_hex(0), "0000000000000000");
        assert_eq!(
            MeshNode::chain_hex(0xDEAD_BEEF_CAFE_BABE),
            "deadbeefcafebabe"
        );
        assert_eq!(MeshNode::chain_hex(u64::MAX), "ffffffffffffffff");
        // Pin the 16-char width — wire-format drift would surface
        // here.
        for h in [0u64, 1, 0x42, u64::MAX] {
            assert_eq!(MeshNode::chain_hex(h).len(), 16);
        }
    }

    // The `MeshNode::blob_hex` / `is_blob_heat_for` /
    // `replace_blob_heat_tags` helpers live behind the `dataforts`
    // feature flag (they back the PR-5j-c blob-heat tag emission
    // path on the production wire). Gate the tests so a build
    // without the feature doesn't try to call non-existent
    // methods.
    #[cfg(feature = "dataforts")]
    #[test]
    fn blob_hex_is_lowercase_64_chars() {
        let zero = [0u8; 32];
        assert_eq!(MeshNode::blob_hex(&zero).len(), 64);
        assert!(MeshNode::blob_hex(&zero).chars().all(|c| c == '0'));
        let mut h = [0u8; 32];
        h[0] = 0xDE;
        h[1] = 0xAD;
        h[31] = 0xFF;
        let hex = MeshNode::blob_hex(&h);
        assert!(hex.starts_with("dead"));
        assert!(hex.ends_with("ff"));
        assert_eq!(hex.len(), 64);
    }

    #[cfg(feature = "dataforts")]
    #[test]
    fn is_blob_heat_for_matches_blob_body_only() {
        let mut h = [0u8; 32];
        h[0] = 0x42;
        let hex = MeshNode::blob_hex(&h);
        let blob_tag = Tag::Reserved {
            prefix: "heat:".to_string(),
            body: format!("blob:{}=0.5", hex),
        };
        assert!(MeshNode::is_blob_heat_for(&blob_tag, &hex));
        // Chain-heat shape (no "blob:" sub-prefix) must NOT match.
        let chain_tag = Tag::Reserved {
            prefix: "heat:".to_string(),
            body: format!("{}=0.5", MeshNode::chain_hex(0x42)),
        };
        assert!(!MeshNode::is_blob_heat_for(&chain_tag, &hex));
    }

    #[cfg(feature = "dataforts")]
    #[test]
    fn replace_blob_heat_tags_round_trip() {
        let mut h = [0u8; 32];
        h[0] = 0x77;
        let hex = MeshNode::blob_hex(&h);
        let mut caps = CapabilitySet::default();
        let initial = Tag::Reserved {
            prefix: "heat:".to_string(),
            body: format!("blob:{}=0.10", hex),
        };
        caps.tags.insert(initial.clone());
        // Replace with a fresh rate.
        let replacement = Tag::Reserved {
            prefix: "heat:".to_string(),
            body: format!("blob:{}=0.80", hex),
        };
        MeshNode::replace_blob_heat_tags(&mut caps, &h, Some(replacement.clone()));
        assert!(caps.tags.contains(&replacement));
        assert!(!caps.tags.contains(&initial));
        // Withdraw — every heat:blob:<hex>=* drops.
        MeshNode::replace_blob_heat_tags(&mut caps, &h, None);
        assert!(!caps
            .tags
            .iter()
            .any(|t| MeshNode::is_blob_heat_for(t, &hex)));
    }

    fn causal_tag(body: impl Into<String>) -> Tag {
        Tag::Reserved {
            prefix: "causal:".to_string(),
            body: body.into(),
        }
    }

    #[test]
    fn is_causal_for_presence_form() {
        let hex = MeshNode::chain_hex(0x42);
        assert!(MeshNode::is_causal_for(&causal_tag(&hex), &hex));
    }

    #[test]
    fn is_causal_for_tip_form() {
        let hex = MeshNode::chain_hex(0x42);
        assert!(MeshNode::is_causal_for(
            &causal_tag(format!("{hex}:100")),
            &hex
        ));
    }

    #[test]
    fn is_causal_for_range_form() {
        let hex = MeshNode::chain_hex(0x42);
        assert!(MeshNode::is_causal_for(
            &causal_tag(format!("{hex}[50..100]")),
            &hex
        ));
    }

    #[test]
    fn is_causal_for_rejects_different_hash() {
        let our = MeshNode::chain_hex(0x42);
        let theirs = MeshNode::chain_hex(0x43);
        assert!(!MeshNode::is_causal_for(&causal_tag(&theirs), &our));
        assert!(!MeshNode::is_causal_for(
            &causal_tag(format!("{theirs}:100")),
            &our,
        ));
    }

    #[test]
    fn is_causal_for_rejects_non_causal_reserved() {
        // `fork-of:<hash>` is a Reserved tag too, but with a
        // different prefix. Must not false-match.
        let hex = MeshNode::chain_hex(0x42);
        let t = Tag::Reserved {
            prefix: "fork-of:".to_string(),
            body: hex.clone(),
        };
        assert!(!MeshNode::is_causal_for(&t, &hex));
    }

    #[test]
    fn is_causal_for_rejects_axis_value_tag() {
        let hex = MeshNode::chain_hex(0x42);
        let t = Tag::parse("hardware.gpu=nvidia").unwrap();
        assert!(!MeshNode::is_causal_for(&t, &hex));
    }

    #[test]
    fn is_causal_for_no_false_match_on_hex_prefix() {
        // The shorter hex `00...0100` is a substring prefix of the
        // longer `00...1000` ONLY at the first character (`0`). The
        // matcher must inspect the byte AFTER the hex to ensure we
        // see `:`, `[`, or end-of-body.
        //
        // More direct test: a `causal:<our_hex>x...` body where `x`
        // is some character other than `:` or `[` — must not match.
        let our = MeshNode::chain_hex(0x42);
        let mut bogus = our.clone();
        bogus.push('x'); // not a valid delimiter
        bogus.push_str(":99");
        let t = causal_tag(bogus);
        assert!(!MeshNode::is_causal_for(&t, &our));
    }

    #[test]
    fn replace_causal_tags_strips_every_variant() {
        let mut caps = CapabilitySet::default();
        // Insert four causal: tags — three for our chain, one for
        // a different chain — plus an unrelated axis tag.
        let our = 0x42u64;
        let our_hex = MeshNode::chain_hex(our);
        let other_hex = MeshNode::chain_hex(0x43);
        caps.tags.insert(causal_tag(&our_hex));
        caps.tags.insert(causal_tag(format!("{our_hex}:50")));
        caps.tags.insert(causal_tag(format!("{our_hex}[10..20]")));
        caps.tags.insert(causal_tag(&other_hex));
        caps.tags.insert(Tag::parse("hardware.gpu").unwrap());

        MeshNode::replace_causal_tags(&mut caps, our, None);

        // Every causal: tag for our hash gone; other chain's tag
        // intact; axis tag untouched.
        let our_count = caps
            .tags
            .iter()
            .filter(|t| MeshNode::is_causal_for(t, &our_hex))
            .count();
        let other_count = caps
            .tags
            .iter()
            .filter(|t| MeshNode::is_causal_for(t, &other_hex))
            .count();
        assert_eq!(our_count, 0, "every variant for our hash must be stripped");
        assert_eq!(other_count, 1, "other chain's tag must survive");
        assert!(
            caps.tags.iter().any(|t| matches!(t,
                Tag::AxisPresent { axis, key }
                    if axis == &crate::adapter::net::behavior::tag::TaxonomyAxis::Hardware
                        && key == "gpu"
            )),
            "non-causal tag must survive"
        );
    }

    #[test]
    fn replace_causal_tags_inserts_replacement() {
        let mut caps = CapabilitySet::default();
        let our = 0x42u64;
        let our_hex = MeshNode::chain_hex(our);
        caps.tags.insert(causal_tag(format!("{our_hex}:50")));

        // Replace tip 50 with tip 100.
        let replacement = causal_tag(format!("{our_hex}:100"));
        MeshNode::replace_causal_tags(&mut caps, our, Some(replacement.clone()));

        let variants: Vec<_> = caps
            .tags
            .iter()
            .filter(|t| MeshNode::is_causal_for(t, &our_hex))
            .collect();
        assert_eq!(variants.len(), 1, "exactly one causal: tag for our hash");
        assert_eq!(variants[0], &replacement);
    }

    #[test]
    fn filter_unauthorized_heat_tags_strips_unclaimed_origins() {
        // A peer can only annotate heat for chains it also
        // advertises holding. Heat tags whose hex doesn't appear
        // in any causal: tag in the same set get filtered out.
        let mut caps = CapabilitySet::default();
        let owned_hex = MeshNode::chain_hex(0xCAFE);
        let forged_hex = MeshNode::chain_hex(0xDEAD);
        caps.tags.insert(causal_tag(&owned_hex));
        caps.tags.insert(Tag::Reserved {
            prefix: "heat:".to_string(),
            body: format!("{owned_hex}=0.50"),
        });
        caps.tags.insert(Tag::Reserved {
            prefix: "heat:".to_string(),
            body: format!("{forged_hex}=0.99"),
        });
        // Throw in a non-heat reserved tag — must survive.
        caps.tags.insert(Tag::Reserved {
            prefix: "scope:".to_string(),
            body: "industrial".to_string(),
        });

        MeshNode::filter_unauthorized_heat_tags(&mut caps);

        // Owned heat tag survives; forged one is gone.
        let surviving_heat: Vec<_> = caps
            .tags
            .iter()
            .filter_map(|t| match t {
                Tag::Reserved { prefix, body } if prefix == "heat:" => Some(body.clone()),
                _ => None,
            })
            .collect();
        assert_eq!(surviving_heat.len(), 1);
        assert!(surviving_heat[0].starts_with(&owned_hex));
        // Scope tag survived; causal tag survived.
        assert!(caps.tags.iter().any(|t| matches!(
            t,
            Tag::Reserved { prefix, .. } if prefix == "scope:"
        )));
        assert!(caps
            .tags
            .iter()
            .any(|t| MeshNode::is_causal_for(t, &owned_hex)));
    }

    /// Regression for the heat:blob DoS surface. A peer injects
    /// more than `MAX_BLOB_HEAT_TAGS_PER_ANNOUNCE` blob-heat tags
    /// into a single announcement; the filter drops the overflow.
    /// The cap bounds the migration-controller amplification
    /// (each surviving heat tag drives an `adapter.prefetch`
    /// attempt).
    #[cfg(feature = "dataforts")]
    #[test]
    fn filter_unauthorized_heat_tags_caps_blob_heat_flood_per_announce() {
        let mut caps = CapabilitySet::default();
        // Stuff in 2× the cap of distinct blob-heat tags.
        let flood = MAX_BLOB_HEAT_TAGS_PER_ANNOUNCE * 2;
        for i in 0..flood {
            let mut hash = [0u8; 32];
            // Pack the index into bytes 0..8 so each hash is
            // distinct without needing a hash function.
            hash[..8].copy_from_slice(&(i as u64).to_le_bytes());
            let hex = MeshNode::blob_hex(&hash);
            caps.tags.insert(Tag::Reserved {
                prefix: "heat:".to_string(),
                body: format!("blob:{hex}=1.00"),
            });
        }
        // Sanity: every distinct tag landed in the HashSet.
        let pre_filter = caps
            .tags
            .iter()
            .filter(|t| {
                matches!(t, Tag::Reserved { prefix, body }
                if prefix == "heat:" && body.starts_with("blob:"))
            })
            .count();
        assert_eq!(pre_filter, flood);

        MeshNode::filter_unauthorized_heat_tags(&mut caps);

        let post_filter = caps
            .tags
            .iter()
            .filter(|t| {
                matches!(t, Tag::Reserved { prefix, body }
                if prefix == "heat:" && body.starts_with("blob:"))
            })
            .count();
        assert_eq!(
            post_filter, MAX_BLOB_HEAT_TAGS_PER_ANNOUNCE,
            "filter must drop blob-heat tags past the per-announce cap"
        );
    }
}

#[cfg(test)]
#[cfg(feature = "cortex")]
mod route_cache_tests {
    //! Coverage for `MeshNode::rpc_route_for_service` — the
    //! per-service nRPC route cache landed in T1.3 of the
    //! 2026-05-19 perf audit. Pins:
    //!
    //!   - cache hits return the same `Arc<RpcRoute>` (so the
    //!     refcount-bump fast path is real, not silently
    //!     rebuilding);
    //!   - the cached route is byte-for-byte equivalent to what
    //!     the removed per-call code produced (any future tweak
    //!     to channel-name derivation can't silently diverge from
    //!     server-side service lookup);
    //!   - distinct services don't alias (the obvious safety
    //!     property);
    //!   - the [`RPC_ROUTE_CACHE_SOFT_CAP`] is honored — past
    //!     the cap, the lookup still returns a correct route but
    //!     stops growing the cache.
    use super::*;
    use std::net::SocketAddr;

    async fn build_node_for_test() -> Arc<MeshNode> {
        let addr: SocketAddr = "127.0.0.1:0".parse().unwrap();
        let cfg = MeshNodeConfig::new(addr, [0x17u8; 32]);
        Arc::new(
            MeshNode::new(EntityKeypair::generate(), cfg)
                .await
                .expect("MeshNode::new"),
        )
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn cached_lookup_returns_same_arc() {
        let node = build_node_for_test().await;
        let a = node.rpc_route_for_service("svc.alpha").expect("first");
        let b = node.rpc_route_for_service("svc.alpha").expect("second");
        assert!(
            Arc::ptr_eq(&a, &b),
            "repeat lookup must hit the cache (same Arc), not rebuild"
        );
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn cached_route_matches_freshly_computed() {
        let node = build_node_for_test().await;
        let service = "svc.beta";
        let cached = node.rpc_route_for_service(service).expect("cached");

        // Re-derive everything from scratch the way the pre-cache
        // code path did. Any future refactor of channel-name
        // derivation that diverges from server-side service
        // lookup will surface here.
        let expected_request =
            ChannelName::new(&format!("{service}.requests")).expect("request name");
        let expected_request_id = ChannelId::new(expected_request.clone());
        let expected_request_hash = expected_request_id.hash();
        let expected_stream_id = MeshNode::publish_stream_id(&expected_request_id);
        let self_origin = node.public_key_origin_hash();
        let expected_reply =
            ChannelName::new(&format!("{service}.replies.{self_origin:016x}")).expect("reply name");
        let expected_reply_hash = expected_reply.hash();

        assert_eq!(cached.request_channel.as_str(), expected_request.as_str());
        assert_eq!(cached.request_channel_hash, expected_request_hash);
        assert_eq!(cached.request_stream_id, expected_stream_id);
        assert_eq!(cached.reply_channel.as_str(), expected_reply.as_str());
        assert_eq!(cached.reply_hash, expected_reply_hash);
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn distinct_services_get_distinct_routes() {
        let node = build_node_for_test().await;
        let a = node.rpc_route_for_service("svc.one").expect("one");
        let b = node.rpc_route_for_service("svc.two").expect("two");
        assert_ne!(a.request_channel.as_str(), b.request_channel.as_str());
        assert_ne!(a.request_channel_hash, b.request_channel_hash);
        assert_ne!(a.reply_channel.as_str(), b.reply_channel.as_str());
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn invalid_service_name_returns_err() {
        let node = build_node_for_test().await;
        // Uppercase is rejected by `ChannelName::validate`.
        assert!(node.rpc_route_for_service("SVC.Bad").is_err());
        // And nothing got cached for the rejected name.
        assert!(node.rpc_route_cache.get("SVC.Bad").is_none());
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn cache_respects_soft_cap() {
        let node = build_node_for_test().await;
        // Push well past the cap, single-threaded, so the
        // size-then-insert check is non-racy.
        let overflow = 64usize;
        for i in 0..(RPC_ROUTE_CACHE_SOFT_CAP + overflow) {
            let svc = format!("svc.cap.{i:04}");
            let route = node
                .rpc_route_for_service(&svc)
                .expect("build must succeed regardless of cap");
            // Overflow callers still get a correct route — just
            // not a cached one.
            assert_eq!(
                route.request_channel.as_str(),
                format!("{svc}.requests").as_str()
            );
        }
        assert!(
            node.rpc_route_cache.len() <= RPC_ROUTE_CACHE_SOFT_CAP,
            "cache size {} exceeds soft cap {}",
            node.rpc_route_cache.len(),
            RPC_ROUTE_CACHE_SOFT_CAP,
        );
        // Past the cap, lookups for new services should *not*
        // grow the map (they bypass the insert branch). Lookups
        // for already-cached services still hit.
        let len_before = node.rpc_route_cache.len();
        let _ = node.rpc_route_for_service("svc.overflow.new").unwrap();
        assert_eq!(
            node.rpc_route_cache.len(),
            len_before,
            "post-cap insert must be a no-op for new services"
        );
        // And a previously-cached service still returns the same Arc.
        let first = node.rpc_route_for_service("svc.cap.0000").unwrap();
        let second = node.rpc_route_for_service("svc.cap.0000").unwrap();
        assert!(Arc::ptr_eq(&first, &second));
    }
}

#[cfg(test)]
mod routed_forward_tests {
    //! PERF_AUDIT §2.5 — the routed-forward branch of
    //! `dispatch_packet` patches the routing header in place via
    //! `try_into_mut` + `write_at` when the inbound `Bytes` is
    //! sole-owned, and falls back to the legacy rebuild when a
    //! clone is outstanding. Both branches MUST produce identical
    //! wire bytes: the header re-serialized with the bumped
    //! hop_count / decremented ttl, the body untouched.
    use super::*;
    use bytes::Bytes;

    /// Replicates `dispatch_packet`'s forward-branch logic on a
    /// synthetic routed packet, exercising BOTH match arms, and
    /// asserts byte equality. A drift in `write_at` offsets (fast
    /// path) versus `to_bytes` layout (slow path) — or a branch
    /// forgetting `forward()` — fails here without standing up a
    /// three-node mesh.
    #[test]
    fn forward_fast_and_slow_paths_produce_identical_wire_bytes() {
        let header = RoutingHeader::new(0xDDDD_EEEE_FFFF_0001, 0xABCD_1234, 7);
        let body: &[u8] = b"opaque-encrypted-inner-packet-bytes-not-touched-by-forwarding";
        let mut packet = bytes::BytesMut::with_capacity(ROUTING_HEADER_SIZE + body.len());
        packet.extend_from_slice(&header.to_bytes());
        packet.extend_from_slice(body);
        let original = packet.freeze();

        // Parse the way dispatch_packet does, then forward().
        let routing_header =
            RoutingHeader::from_bytes(&original[..ROUTING_HEADER_SIZE]).expect("header parses");
        let mut fwd_header = routing_header;
        assert!(fwd_header.forward(), "ttl=7 must be forwardable");

        // Slow path (refcount > 1): hold a clone so try_into_mut
        // must fail, then rebuild like the Err arm.
        let data_shared = original.clone();
        let outstanding_clone = original.clone();
        let slow = match data_shared.try_into_mut() {
            Ok(_) => panic!("refcount > 1 must take the slow path"),
            Err(orig_data) => {
                let mut new_data = bytes::BytesMut::with_capacity(orig_data.len());
                new_data.extend_from_slice(&fwd_header.to_bytes());
                new_data.extend_from_slice(&orig_data[ROUTING_HEADER_SIZE..]);
                new_data.freeze()
            }
        };
        drop(outstanding_clone);

        // Fast path (sole owner): in-place write_at.
        let fast = match original.try_into_mut() {
            Ok(mut mut_data) => {
                fwd_header.write_at(&mut mut_data[..ROUTING_HEADER_SIZE]);
                mut_data.freeze()
            }
            Err(_) => panic!("sole-owned Bytes must take the fast path"),
        };

        assert_eq!(
            fast, slow,
            "fast (in-place write_at) and slow (rebuild) forward paths must be wire-identical"
        );
        // Pin the semantic deltas: ttl decremented (byte 2),
        // hop_count incremented (byte 3), body untouched.
        let reparsed = RoutingHeader::from_bytes(&fast[..ROUTING_HEADER_SIZE]).unwrap();
        assert_eq!(reparsed.ttl, 6, "forward() must decrement ttl");
        assert_eq!(reparsed.hop_count, 1, "forward() must increment hop_count");
        assert_eq!(reparsed.dest_id, routing_header.dest_id);
        assert_eq!(reparsed.src_id, routing_header.src_id);
        assert_eq!(
            &fast[ROUTING_HEADER_SIZE..],
            body,
            "forwarding must never touch the encrypted body"
        );
    }

    /// The fast path requires the inbound `Bytes` to be truly
    /// sole-owned. A `Bytes` produced by `BytesMut::split()` whose
    /// parent handle is still alive (the default `PacketReceiver`
    /// shape — `recv_buf.split().freeze()` with `recv_buf`
    /// retaining the allocation tail) is NOT unique, and must fall
    /// back to the copying path rather than corrupt shared memory.
    #[test]
    fn split_with_live_parent_takes_slow_path() {
        let mut parent = bytes::BytesMut::with_capacity(256);
        parent.extend_from_slice(&RoutingHeader::new(1, 2, 3).to_bytes());
        parent.extend_from_slice(b"body");
        let child: Bytes = parent.split().freeze();
        // `parent` still holds the allocation tail — the frozen
        // child must not be considered unique.
        assert!(
            child.try_into_mut().is_err(),
            "split().freeze() with the parent BytesMut alive must take the slow path — \
             if this ever starts succeeding, re-evaluate PERF_AUDIT §2.2/§2.5: the \
             in-place forward fast path would then fire on the default ingress too"
        );
        drop(parent);
    }
}

// NOTE: this test module lives at the END of the file ON PURPOSE. The
// heartbeat drift check in session.rs treats the FIRST column-0
// `#[cfg(test)] mod` as the production/test boundary, so a test module
// placed earlier would hide the real `session.build_heartbeat()` caller
// from `mesh_rs_production_callers_match_allowlist`.
#[cfg(test)]
mod committed_flush_stall_tests {
    use super::*;

    /// #4: the committed-prefix retry must be bounded. Against a receiver
    /// that never grants credit, `await_credit_or_stall` returns a
    /// terminal `Transport` error once `COMMITTED_FLUSH_STALL_BUDGET`
    /// elapses instead of looping forever. Paused time auto-advances as
    /// the backoff sleeps complete, so this runs instantly.
    #[tokio::test(start_paused = true)]
    async fn committed_flush_retry_is_bounded_by_stall_budget() {
        let cap = Duration::from_millis(200);
        let deadline = tokio::time::Instant::now() + COMMITTED_FLUSH_STALL_BUDGET;
        let mut delay = Duration::from_millis(5);
        let mut iters = 0u32;
        loop {
            match await_credit_or_stall(&mut delay, cap, deadline).await {
                Ok(()) => {
                    iters += 1;
                    assert!(iters < 100_000, "retry must be bounded, not spin forever");
                }
                Err(StreamError::Transport(msg)) => {
                    assert!(
                        msg.contains("credit stalled"),
                        "terminal stall error: {msg}"
                    );
                    break;
                }
                Err(other) => panic!("unexpected error variant: {other}"),
            }
        }
        // Backoff caps at 200ms, so reaching the 30s budget takes on the
        // order of ~150 iterations — bounded, never the spin guard.
        assert!(iters > 0, "should back off at least once before giving up");
        assert!(
            iters < 10_000,
            "should reach the budget via capped backoff, got {iters}"
        );
    }

    /// A still-fresh deadline lets the retry continue (`Ok`) and doubles
    /// the backoff toward the cap.
    #[tokio::test(start_paused = true)]
    async fn await_credit_backs_off_while_under_deadline() {
        let cap = Duration::from_millis(200);
        let deadline = tokio::time::Instant::now() + Duration::from_secs(60);
        let mut delay = Duration::from_millis(5);
        match await_credit_or_stall(&mut delay, cap, deadline).await {
            Ok(()) => {}
            Err(e) => panic!("under deadline must continue (Ok), got {e}"),
        }
        assert_eq!(delay, Duration::from_millis(10), "backoff must double");
    }
}

#[cfg(test)]
mod stream_ack_batching_tests {
    //! STREAM_ACK_BATCHING Phase 1 (B-1..B-5): grouping-key contract,
    //! payload-budget chunk math, and multi-event control-frame
    //! round-trips. The wire-cadence bound ("M streams to one session
    //! ⇒ one grant packet per drain cycle, plus spill") follows from
    //! `group_grants_by_session` + `chunks(GRANT_EVENTS_PER_PACKET)`,
    //! both pinned here without spinning real sockets.
    use super::*;
    use crate::adapter::net::crypto::{NoiseHandshake, PacketCipher, StaticKeypair};
    use crate::adapter::net::protocol::NetHeader;
    use crate::adapter::net::subprotocol::stream_window::{STREAM_NACK_SIZE, STREAM_RESET_SIZE};

    /// Fixed-count framing budget for the fixed-size `StreamNack` /
    /// `StreamReset` frames — the reference the codec round-trip tests
    /// fill "a full packet's worth" against. Production packs these by
    /// actual size via [`pack_control_events`] (see `GRANT_EVENTS_PER_
    /// PACKET`), so the constants live here with their tests rather
    /// than in the module body.
    const NACK_EVENTS_PER_PACKET: usize =
        protocol::MAX_PAYLOAD_SIZE / (EventFrame::LEN_SIZE + STREAM_NACK_SIZE);
    const RESET_EVENTS_PER_PACKET: usize =
        protocol::MAX_PAYLOAD_SIZE / (EventFrame::LEN_SIZE + STREAM_RESET_SIZE);

    fn make_session_keys() -> (
        crate::adapter::net::crypto::SessionKeys,
        crate::adapter::net::crypto::SessionKeys,
    ) {
        let psk = [0x42u8; 32];
        let responder_kp = StaticKeypair::generate();
        let mut initiator = NoiseHandshake::initiator(&psk, &responder_kp.public).unwrap();
        let mut responder = NoiseHandshake::responder(&psk, &responder_kp).unwrap();
        let msg1 = initiator.write_message(&[]).unwrap();
        responder.read_message(&msg1).unwrap();
        let msg2 = responder.write_message(&[]).unwrap();
        initiator.read_message(&msg2).unwrap();
        (
            initiator.into_session_keys().unwrap(),
            responder.into_session_keys().unwrap(),
        )
    }

    fn session_at(addr: &str) -> Arc<NetSession> {
        let (_init, resp) = make_session_keys();
        Arc::new(NetSession::new(resp, addr.parse().unwrap(), 4, false))
    }

    fn pending(session: &Arc<NetSession>, addr: &str, consumed: u64) -> PendingStreamGrant {
        PendingStreamGrant {
            session: session.clone(),
            peer_addr: addr.parse().unwrap(),
            total_consumed: consumed,
        }
    }

    /// The chunk constants must (a) actually batch, (b) fill a packet
    /// without overflowing the payload budget, and (c) stay under the
    /// header's event-count cap — the payload budget must be the
    /// binding constraint.
    #[test]
    fn chunk_constants_fit_payload_and_event_caps() {
        for (per_packet, event_size) in [
            (GRANT_EVENTS_PER_PACKET, STREAM_WINDOW_SIZE),
            (NACK_EVENTS_PER_PACKET, STREAM_NACK_SIZE),
            (RESET_EVENTS_PER_PACKET, STREAM_RESET_SIZE),
        ] {
            assert!(per_packet > 1, "batching must batch");
            let frame = EventFrame::LEN_SIZE + event_size;
            assert!(
                per_packet * frame <= protocol::MAX_PAYLOAD_SIZE,
                "a full chunk must fit the payload budget"
            );
            assert!(
                (per_packet + 1) * frame > protocol::MAX_PAYLOAD_SIZE,
                "chunk must fill the packet (one more event would overflow)"
            );
            assert!(
                per_packet <= NetHeader::MAX_EVENTS_PER_PACKET as usize,
                "payload budget, not the event-count cap, must bind"
            );
        }
    }

    /// B-1 grouping-key contract: two DIFFERENT sessions behind the
    /// SAME peer address (e.g. a rotation mid-drain) must not share a
    /// batch — each owns its own AEAD cipher + control-seq counter.
    #[test]
    fn grouping_is_by_session_not_peer_addr() {
        let addr = "127.0.0.1:7001";
        let s1 = session_at(addr);
        let s2 = session_at(addr);
        let mut drained = HashMap::new();
        drained.insert((s1.session_id(), 10u64), pending(&s1, addr, 100));
        drained.insert((s2.session_id(), 10u64), pending(&s2, addr, 200));
        let grouped = group_grants_by_session(drained);
        assert_eq!(grouped.len(), 2, "distinct sessions must stay separate");
    }

    /// All streams of one session collapse into one batch, each
    /// exactly once, with its own `total_consumed`.
    #[test]
    fn grouping_collects_all_streams_of_one_session() {
        let addr = "127.0.0.1:7002";
        let s = session_at(addr);
        let mut drained = HashMap::new();
        for stream_id in 0..100u64 {
            drained.insert(
                (s.session_id(), stream_id),
                pending(&s, addr, stream_id * 10),
            );
        }
        let grouped = group_grants_by_session(drained);
        assert_eq!(grouped.len(), 1, "one session ⇒ one batch");
        let (_, peer_addr, grants) = &grouped[&s.session_id()];
        assert_eq!(*peer_addr, addr.parse().unwrap());
        let mut seen: Vec<(u64, u64)> = grants.clone();
        seen.sort_unstable();
        assert_eq!(
            seen,
            (0..100u64).map(|i| (i, i * 10)).collect::<Vec<_>>(),
            "every stream survives grouping exactly once with its value"
        );
    }

    /// The build step must NOT bump `credit_grants_sent` — that
    /// counter means "grant datagram sent", and the drainer bumps it
    /// per covered stream only after the chunk clears `send_to`.
    /// Pre-fix the bump ran at build time, overcounting whenever the
    /// send failed (review P2).
    #[test]
    fn build_session_control_events_does_not_bump_grants_sent() {
        let addr = "127.0.0.1:7005";
        let s = session_at(addr);
        let sid = 42u64;
        s.get_or_create_stream_for_packet(sid, true);

        let grants = vec![(sid, 1000u64)];
        let (entries, _nacks, _acks) = build_session_control_events(&s, &grants, false);
        assert_eq!(entries.len(), 1);

        let state = s.try_stream(sid).expect("stream exists");
        assert_eq!(
            state.credit_grants_sent(),
            0,
            "building the grant event must not count it as sent"
        );
        // The post-send bump is the drainer's job — one per grant
        // that actually cleared the socket.
        state.note_grant_sent();
        assert_eq!(state.credit_grants_sent(), 1);
    }

    /// Grant entries stay paired (stream id ↔ encoded event) so the
    /// post-send accounting hits the right streams, and NACK / SACK
    /// events are built only for gapped streams (SACK only when the
    /// peer supports ranges).
    #[test]
    fn build_session_control_events_pairs_ids_and_gates_gap_events() {
        use crate::adapter::net::subprotocol::stream_window::StreamAckRanges;

        let addr = "127.0.0.1:7006";
        let s = session_at(addr);
        // Stream 1: clean in-order receive. Stream 2: gapped (0
        // received, 5 out of order → head gap at 1).
        s.get_or_create_stream_for_packet(1, true)
            .with_reliability(|r| {
                assert!(r.on_receive(0));
            });
        s.get_or_create_stream_for_packet(2, true)
            .with_reliability(|r| {
                assert!(r.on_receive(0));
                assert!(r.on_receive(5));
            });

        let grants = vec![(1u64, 10u64), (2u64, 20u64)];
        let (entries, nacks, acks) = build_session_control_events(&s, &grants, true);

        assert_eq!(entries.len(), 2);
        for (sid, event) in &entries {
            let g = StreamWindow::decode(event).expect("grant event decodes");
            assert_eq!(g.stream_id, *sid, "entry id must match its encoded event");
        }

        assert_eq!(nacks.len(), 1, "only the gapped stream NACKs");
        let n = StreamNack::decode(&nacks[0]).expect("nack decodes");
        assert_eq!(n.stream_id, 2);
        assert_eq!(n.next_expected, 1);

        assert_eq!(acks.len(), 1, "only the gapped stream has SACK ranges");
        let a = StreamAckRanges::decode(&acks[0]).expect("ack ranges decode");
        assert_eq!(a.stream_id, 2);
        assert_eq!(a.ack_seq, 1);
        assert_eq!(a.ranges, vec![(5, 6)]);

        // Capability gate off ⇒ no SACK events, everything else same.
        let (_, _, acks_off) = build_session_control_events(&s, &grants, false);
        assert!(acks_off.is_empty(), "no ranges to a non-advertising peer");
    }

    /// The capability-gate cache sweep drops entries past the age
    /// bound and keeps fresh ones — the backstop that keeps the
    /// insert-on-lookup cache bounded under peer churn (review P2).
    #[test]
    fn ack_ranges_cache_sweep_drops_only_stale_entries() {
        let cache: DashMap<u64, (bool, Instant)> = DashMap::new();
        let stale_at = Instant::now() - ACK_RANGES_CAP_CACHE_MAX_AGE - Duration::from_secs(1);
        cache.insert(1, (true, stale_at));
        cache.insert(2, (false, stale_at));
        cache.insert(3, (true, Instant::now()));

        sweep_ack_ranges_cache(&cache, ACK_RANGES_CAP_CACHE_MAX_AGE);

        assert!(!cache.contains_key(&1), "stale positive entry swept");
        assert!(!cache.contains_key(&2), "stale negative entry swept");
        assert!(
            cache.contains_key(&3),
            "fresh entry survives — active peers keep their cached verdict"
        );
    }

    /// R-5 gate-cache invalidation (review CAPCACHE): a verdict cached
    /// before a peer's capability announcement is folded is stale for
    /// the whole TTL, so the drainer keeps the legacy path during the
    /// opening loss episode of a fresh transfer. `handle_capability_
    /// announcement` removes the peer's cache entry the instant the
    /// announcement folds; this pins that removal is what lets the
    /// next gate check re-resolve to `true` (rather than waiting for
    /// the TTL). Drives the real `peer_supports_ack_ranges` + fold.
    #[test]
    fn ack_ranges_gate_reresolves_after_announcement_invalidation() {
        use crate::adapter::net::behavior::capability::{CapabilityAnnouncement, CapabilitySet};
        use crate::adapter::net::behavior::fold::capability::CapabilityFold;
        use crate::adapter::net::behavior::fold::capability_bridge::translate_announcement;
        use crate::adapter::net::behavior::fold::Fold;

        let cache: DashMap<u64, (bool, Instant)> = DashMap::new();
        let session_id_to_node: DashMap<u64, u64> = DashMap::new();
        let fold: Fold<CapabilityFold> = Fold::new();

        let kp = crate::adapter::net::EntityKeypair::generate();
        let node_id = kp.node_id();
        let session_id = 0x5E5510_u64; // arbitrary session id
        session_id_to_node.insert(session_id, node_id);

        // Fold empty ⇒ gate resolves false and CACHES (false, now).
        assert!(!peer_supports_ack_ranges(
            &cache,
            &session_id_to_node,
            &fold,
            session_id
        ));
        assert_eq!(cache.get(&node_id).map(|e| e.value().0), Some(false));

        // Peer now advertises the tag; fold updated (as the dispatch
        // handler does before invalidating the cache).
        let caps = CapabilitySet::new().add_tag(ACK_RANGES_CAPABILITY_TAG.to_string());
        let ann = CapabilityAnnouncement::new(node_id, kp.entity_id().clone(), 1, caps);
        fold.apply(translate_announcement(&ann))
            .expect("fold apply");

        // Without invalidation the stale `false` still wins (the bug).
        assert!(
            !peer_supports_ack_ranges(&cache, &session_id_to_node, &fold, session_id),
            "cached false shadows the freshly-folded capability"
        );

        // The invalidation `handle_capability_announcement` now performs.
        cache.remove(&node_id);

        // Next check re-resolves through the fold ⇒ true.
        assert!(
            peer_supports_ack_ranges(&cache, &session_id_to_node, &fold, session_id),
            "after invalidation the gate must see the announced capability"
        );
    }

    /// R-5 (review DORMANT/CAPCACHE): the peer's advertisement — not
    /// local support — controls the SACK-range path. With an empty fold
    /// (the peer never announced `ACK_RANGES_CAPABILITY_TAG`) the gate
    /// resolves `false`, and the drainer ANDs that into `emit_ack_ranges`;
    /// so a gapped stream produces the legacy grant + NACK and NO
    /// `StreamAckRanges`, even though this node's own support is on.
    #[test]
    fn no_advertised_capability_keeps_sender_on_legacy_path() {
        use crate::adapter::net::behavior::fold::capability::CapabilityFold;
        use crate::adapter::net::behavior::fold::Fold;

        let cache: DashMap<u64, (bool, Instant)> = DashMap::new();
        let session_id_to_node: DashMap<u64, u64> = DashMap::new();
        let fold: Fold<CapabilityFold> = Fold::new();

        let session = session_at("127.0.0.1:7011");
        session_id_to_node.insert(session.session_id(), 0xBEEF_u64);

        // Peer never advertised ⇒ gate false. This is exactly the value
        // the drainer ANDs with `enable_stream_ack_ranges` to decide
        // whether to emit ranges.
        let supported =
            peer_supports_ack_ranges(&cache, &session_id_to_node, &fold, session.session_id());
        assert!(
            !supported,
            "no advertisement ⇒ legacy path even with local support enabled"
        );

        // A gapped receive stream: 0 received, 5 out of order ⇒ head gap
        // at 1 (so there IS a NACK and there WOULD be SACK ranges).
        session
            .get_or_create_stream_for_packet(3, true)
            .with_reliability(|r| {
                assert!(r.on_receive(0));
                assert!(r.on_receive(5));
            });

        let (grants, nacks, acks) =
            build_session_control_events(&session, &[(3u64, 10u64)], supported);
        assert_eq!(grants.len(), 1, "grant still emitted");
        assert_eq!(nacks.len(), 1, "legacy NACK still emitted for the gap");
        assert!(
            acks.is_empty(),
            "no StreamAckRanges to a peer that has not advertised support"
        );
    }

    /// Grants for different peers (different sessions) route to their
    /// own batches with their own addresses.
    #[test]
    fn grouping_keeps_peers_separate() {
        let a1 = "127.0.0.1:7003";
        let a2 = "127.0.0.1:7004";
        let s1 = session_at(a1);
        let s2 = session_at(a2);
        let mut drained = HashMap::new();
        drained.insert((s1.session_id(), 1u64), pending(&s1, a1, 11));
        drained.insert((s2.session_id(), 1u64), pending(&s2, a2, 22));
        let grouped = group_grants_by_session(drained);
        assert_eq!(grouped.len(), 2);
        assert_eq!(grouped[&s1.session_id()].1, a1.parse().unwrap());
        assert_eq!(grouped[&s2.session_id()].1, a2.parse().unwrap());
    }

    /// Decrypt-side pin for `chunk` → `build_subprotocol` framing:
    /// a maximal batched frame fits one wire packet and every event
    /// decodes back to its message. The receive path has always
    /// iterated the full event vector (`mesh.rs` StreamWindow /
    /// StreamNack / StreamReset arms), so this is the whole wire-
    /// compatibility story for B-2/B-3.
    fn roundtrip_full_chunk(payloads: Vec<Vec<u8>>, subprotocol_id: u16) -> Vec<Bytes> {
        let key = [0x5Au8; 32];
        let session_id = 0xACE0_FACEu64;
        let mut builder = PacketBuilder::new(&key, session_id);
        let events: Vec<Bytes> = payloads.iter().map(|p| Bytes::copy_from_slice(p)).collect();
        let pkt = builder.build_subprotocol(
            CONTROL_STREAM_ID,
            1,
            &events,
            PacketFlags::NONE,
            subprotocol_id,
        );
        assert!(
            pkt.len() <= protocol::MAX_PACKET_SIZE,
            "full chunk must fit one wire packet ({} > {})",
            pkt.len(),
            protocol::MAX_PACKET_SIZE
        );
        let header = NetHeader::from_bytes(&pkt[..HEADER_SIZE]).expect("header parses");
        assert_eq!(header.event_count as usize, events.len());
        assert_eq!(header.subprotocol_id, subprotocol_id);
        let rx = PacketCipher::new(&key, session_id);
        let nonce = u64::from_le_bytes(pkt[16..24].try_into().unwrap());
        let aad = header.aad();
        let mut buf = bytes::BytesMut::from(&pkt[HEADER_SIZE..]);
        let n = rx
            .decrypt_in_place(nonce, &aad, &mut buf[..])
            .expect("decrypt succeeds");
        EventFrame::read_events(buf.split_to(n).freeze(), header.event_count)
    }

    #[test]
    fn full_grant_chunk_roundtrips_as_one_packet() {
        let grants: Vec<StreamWindow> = (0..GRANT_EVENTS_PER_PACKET as u64)
            .map(|i| StreamWindow {
                stream_id: i,
                total_consumed: i * 7,
                ack_seq: i * 3,
            })
            .collect();
        let recovered = roundtrip_full_chunk(
            grants.iter().map(|g| g.encode().to_vec()).collect(),
            SUBPROTOCOL_STREAM_WINDOW,
        );
        assert_eq!(
            recovered.len(),
            grants.len(),
            "every grant survives framing"
        );
        for (event, g) in recovered.iter().zip(&grants) {
            assert_eq!(StreamWindow::decode(event).unwrap(), *g);
        }
    }

    #[test]
    fn full_nack_chunk_roundtrips_as_one_packet() {
        let nacks: Vec<StreamNack> = (0..NACK_EVENTS_PER_PACKET as u64)
            .map(|i| StreamNack {
                stream_id: i,
                next_expected: i + 1,
                missing_bitmap: i | 1,
            })
            .collect();
        let recovered = roundtrip_full_chunk(
            nacks.iter().map(|n| n.encode().to_vec()).collect(),
            SUBPROTOCOL_STREAM_NACK,
        );
        assert_eq!(recovered.len(), nacks.len());
        for (event, n) in recovered.iter().zip(&nacks) {
            assert_eq!(StreamNack::decode(event).unwrap(), *n);
        }
    }

    #[test]
    fn full_reset_chunk_roundtrips_as_one_packet() {
        let resets: Vec<StreamReset> = (0..RESET_EVENTS_PER_PACKET as u64)
            .map(|i| StreamReset { stream_id: i })
            .collect();
        let recovered = roundtrip_full_chunk(
            resets.iter().map(|r| r.encode().to_vec()).collect(),
            SUBPROTOCOL_STREAM_RESET,
        );
        assert_eq!(recovered.len(), resets.len());
        for (event, r) in recovered.iter().zip(&resets) {
            assert_eq!(StreamReset::decode(event).unwrap(), *r);
        }
    }

    /// Overflow spill (B-5): a batch larger than one packet's budget
    /// splits into ceil(N / per-packet) chunks, none over budget,
    /// with no event dropped.
    #[test]
    fn oversized_grant_batch_spills_without_loss() {
        let total = GRANT_EVENTS_PER_PACKET * 2 + 122;
        let events: Vec<Bytes> = (0..total as u64)
            .map(|i| {
                Bytes::copy_from_slice(
                    &StreamWindow {
                        stream_id: i,
                        total_consumed: i,
                        ack_seq: 0,
                    }
                    .encode(),
                )
            })
            .collect();
        let chunks: Vec<&[Bytes]> = events.chunks(GRANT_EVENTS_PER_PACKET).collect();
        assert_eq!(chunks.len(), 3, "ceil(2N+122 / N) = 3 packets");
        assert_eq!(
            chunks.iter().map(|c| c.len()).sum::<usize>(),
            total,
            "no grant dropped by the spill"
        );
        for c in &chunks {
            assert!(EventFrame::calculate_size(c) <= protocol::MAX_PAYLOAD_SIZE);
        }
    }

    /// R-4 size-aware packing (review ACKCHUNK/H5): variable-size
    /// `StreamAckRanges` events pack by ACTUAL size, so a batch of
    /// small one-range events fills far fewer packets than the old
    /// worst-case count (payload / 272 B ≈ 29 events/packet) — while
    /// every chunk still fits the payload budget and no event is lost.
    #[test]
    fn pack_control_events_fills_by_size_not_worst_case() {
        // 200 single-range SACK events (one range each → 32 wire B,
        // 36 B framed). Worst-case chunking (StreamAckRanges::MAX_SIZE
        // = 272 B) would have shipped ~29/packet ⇒ ≥7 packets.
        let events: Vec<Bytes> = (0..200u64)
            .map(|i| {
                Bytes::from(
                    StreamAckRanges {
                        stream_id: i,
                        ack_seq: 0,
                        ranges: vec![(10 * i + 1, 10 * i + 2)],
                    }
                    .encode(),
                )
            })
            .collect();

        let ranges = pack_control_events(&events);

        // Every event covered exactly once, in order, no gaps/overlap.
        let covered: usize = ranges.iter().map(|r| r.len()).sum();
        assert_eq!(covered, events.len(), "no event dropped by packing");
        let mut next = 0usize;
        for r in &ranges {
            assert_eq!(r.start, next, "chunks are contiguous and in order");
            next = r.end;
        }
        // Each chunk fits the payload budget.
        for r in &ranges {
            assert!(
                EventFrame::calculate_size(&events[r.clone()]) <= protocol::MAX_PAYLOAD_SIZE,
                "a packed chunk must fit the payload budget"
            );
        }
        // Density: small events pack far below the worst-case bound.
        // 200 × 36 B ≈ 7.2 KiB ⇒ one packet at an ~8 KiB budget.
        let worst_case_packets = events.len().div_ceil(
            protocol::MAX_PAYLOAD_SIZE / (EventFrame::LEN_SIZE + StreamAckRanges::MAX_SIZE),
        );
        assert!(
            ranges.len() < worst_case_packets,
            "size packing ({} packets) must beat worst-case count ({})",
            ranges.len(),
            worst_case_packets
        );
    }

    /// A single event larger than the budget still ships alone rather
    /// than producing an empty chunk (the `i > start` guard).
    #[test]
    fn pack_control_events_lone_oversized_event_ships_alone() {
        let big = Bytes::from(vec![0u8; protocol::MAX_PAYLOAD_SIZE + 10]);
        let small = Bytes::from_static(b"x");
        let events = vec![small.clone(), big, small];
        let ranges = pack_control_events(&events);
        // small | big-alone | small — three chunks, none empty.
        assert_eq!(ranges.len(), 3);
        assert!(ranges.iter().all(|r| !r.is_empty()));
    }
}