decdn-node 0.1.0

//! Two-endpoint loopback tests for `cdn/client/v1` paid delivery (#317).
//!
//! Spins up a server running [`ClientHandler`], connects a client endpoint over
//! iroh on localhost, and drives the [`stream_fetch`] requester against it. The
//! happy path proves bytes are delivered + hash-verified and the persisted
//! lane state advances; the error paths prove a zero-rate response is
//! rejected on receive (#252), an unknown lane is cleanly refused pre-serve
//! with `NotFound` (the #327 boundary), and a transient
//! persist-write failure cleanly ABORTS the stream (ADR 003 §332) — no in-band
//! reject reason, just a clean finish — so the client resends the same voucher
//! on a fresh stream.
//!
//! Delivery/authorization gates also covered: the buyer-side received-byte
//! ceiling (#1895, `BlobTooLarge` on bytes that actually arrive), the
//! `Declined` refusal of a blob evicted between probe and stream, the client-binding
//! mismatch reset and the binding-does-not-own-pool `NotFound` (both driven
//! by a small [`raw_request`] client, since the honest requester never sends a
//! binding), and per-lane voucher serialization under concurrency.
//!
//! The ADR 005 §Connection lifetime idle-close (#1193) has its own group: the
//! never-opened-a-stream reap, the `inflight.is_empty()` gate under a parked
//! request read, and — driven by [`stall_delivery_at_closing_voucher`], a raw
//! delivery client that parks a REAL paid stream at its closing-voucher exchange
//! — the gate under active deliveries, repeated clock re-arms, and the rule that
//! every concurrent stream must finish before the idle countdown begins (#1261,
//! #1287).
//!
//! Hostile-client and hostile-server paths (#1562) reimplement the receive or
//! serve loop by hand — [`stall_delivery_at_closing_voucher`] is the honest half
//! the payment-fault tests extend, and [`serve_lying_stream`] is the hostile
//! server the client-side detection tests drive the real [`stream_fetch`]
//! against. Covered here: an underpaying voucher draws `Underpaid` (carrying the
//! accepted watermark once there is one) and advances no watermark; a `BadSignature` and a watermark-regression
//! (`BytesRegression`) proof arriving *after* an accepted voucher are both
//! rejected in band while the accepted watermark survives; the per-connection
//! stream-cap sheds an over-cap stream with a bare QUIC reset and no signed
//! `StreamResponse`; the buyer rejects a server that over-sends past the promised
//! length or delivers hash-mismatched bytes; and the request-read timeout and
//! the proof wait each tear down a peer that opens a stream (or parks a paid
//! delivery) and then goes silent.

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

use alloy::dyn_abi::Eip712Domain;
use alloy::primitives::{Address, B256, U256};
use alloy::signers::SignerSync;
use alloy::signers::local::PrivateKeySigner;
use async_trait::async_trait;
use decdn_cache::{
    CacheEngine, CacheMetrics, CircuitBreakerPolicy, Hash, PinnedHashes, RetryPolicy,
};
use decdn_client::{
    BlobTooLarge, Cumulative, HashMismatch, PoolContext, PoolLedger, PullDeadlines,
    RateAboveCeiling, UpstreamVoucherRejected, VoucherProgress, WarmConnection,
    sign_client_binding, stream_fetch, stream_fetch_on, stream_fetch_shared, stream_fetch_tracked,
    stream_fetch_tracked_with_progress,
};
use decdn_incentive::{
    EPHEMERAL_BINDING_NONCE, LaneKey, LaneState, MemoryPoolStateStore, PoolStateStore, Voucher,
    bind_node_id_domain, binding_signing_hash, min_payment, signed_to_wire_voucher,
    slash_judge_domain, stream_sig::StreamSlashData, voucher_domain,
};
use decdn_node::dispatch::ConnectionLimiter;
use decdn_node::handlers::client::{ClientHandler, ClientHandlerDeps, ClientProtocol};
use decdn_node::metrics::Metrics;
use decdn_protocol::client::{
    CHUNK_BYTES, ChunkData, ClientBinding, ClientMessage, StreamError, StreamRequest,
    StreamRequestExt, StreamResponse, StreamResponseBody, StreamResponseExt, VoucherRejectReason,
    encode_stream_response,
};
use decdn_protocol::{ALPN_CLIENT, decode_message, encode_stream_request, read_frame, write_frame};
use iroh::endpoint::{
    ApplicationClose, Connection, ConnectionError, ReadError, ReadToEndError, RecvStream,
    SendStream, VarInt,
};
use iroh::protocol::ProtocolHandler as _;
use iroh::{Endpoint, EndpointAddr};

mod support;
use decdn_node::receipt_log::{DownloadReceipt, spawn_receipt_writer};
use support::{
    BlockingReceiptLog, BufferedClientReader, FailingReceiptLog, FailingRecordStore,
    HandlerDomains, VecReceiptLog, build_handler_full, build_handler_full_configured,
    build_handler_full_with_receipts, build_handler_full_with_sink, cache_with_blob, empty_cache,
    fresh_key, local_endpoint, permissive_limiter, read_client_msg, read_stream_response, shutdown,
    spawn_server, spawn_server_counting, write_client_msg,
};

const CHAIN_ID: u64 = 421_614;
const RATE_PER_MB: u64 = 10;

/// Lower-hex encode bytes (no `0x`), matching `DownloadReceipt`'s rendering so a
/// test can reconstruct the expected `hash` / `client_node_id` strings.
fn hex_lower(bytes: &[u8]) -> String {
    use std::fmt::Write as _;
    bytes.iter().fold(String::new(), |mut s, b| {
        let _ = write!(s, "{b:02x}");
        s
    })
}

fn slash_domain() -> Eip712Domain {
    slash_judge_domain(CHAIN_ID, Address::repeat_byte(0x11))
}

fn payment_domain() -> Eip712Domain {
    voucher_domain(CHAIN_ID, Address::repeat_byte(0x34))
}

fn binding_domain() -> Eip712Domain {
    bind_node_id_domain(CHAIN_ID, Address::repeat_byte(0x99))
}

/// The loopback suite's fixed EIP-712 domains.
fn loopback_domains() -> HandlerDomains {
    HandlerDomains {
        slash: slash_domain(),
        voucher: payment_domain(),
        binding: binding_domain(),
    }
}

const fn pool_id() -> B256 {
    B256::repeat_byte(0xC1)
}

/// Fixed server-operator identity. The seller keys a lane on the serving node's
/// own operator address (`self.eth_signer.address()`), so a lane seeded before
/// the server is built must name the same key the server later runs with. The
/// loopback servers therefore run this fixed key rather than a random one, and
/// every lane / voucher `provider` in the suite is [`operator_addr`].
#[allow(clippy::expect_used)] // fixed-constant key; a bad scalar is a test bug
fn operator_signer() -> Arc<PrivateKeySigner> {
    Arc::new(
        PrivateKeySigner::from_bytes(&B256::repeat_byte(0x42))
            .expect("0x42-repeated is a valid secp256k1 scalar"),
    )
}

/// Address of the fixed [`operator_signer`] — the `provider` every loopback lane
/// pays and every voucher names.
fn operator_addr() -> Address {
    operator_signer().address()
}

/// The lane key a loopback voucher signed by `signer` targets: the fixed
/// [`pool_id`], the paying `signer`, and the [`operator_addr`] provider.
fn lane_key(signer: Address) -> LaneKey {
    LaneKey {
        pool_id: pool_id(),
        signer,
        provider: operator_addr(),
    }
}

/// A fresh lane on [`pool_id`]: `signer` pays [`operator_addr`] with capability
/// cap `cap`, no prior watermark and no expiry.
fn fresh_lane(signer: Address, cap: U256) -> LaneState {
    LaneState::hydrate(
        pool_id(),
        signer,
        operator_addr(),
        cap,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    )
}

/// Build a `ClientHandler` with the given rate and pool-state store and a 16-stream
/// per-connection cap (the common-case setup).
fn build_handler(
    server_id: iroh::PublicKey,
    server_eth: &Arc<PrivateKeySigner>,
    metrics: &Arc<Metrics>,
    limiter: Arc<ConnectionLimiter>,
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    rate: u64,
) -> anyhow::Result<Arc<ClientHandler>> {
    build_handler_limited(
        server_id, server_eth, metrics, limiter, cache, store, rate, 16,
    )
}

/// Build a `ClientHandler` exposing the `max_concurrent_streams` knob.
#[allow(clippy::too_many_arguments)]
fn build_handler_limited(
    server_id: iroh::PublicKey,
    server_eth: &Arc<PrivateKeySigner>,
    metrics: &Arc<Metrics>,
    limiter: Arc<ConnectionLimiter>,
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    rate: u64,
    max_concurrent_streams: usize,
) -> anyhow::Result<Arc<ClientHandler>> {
    build_handler_full(
        server_id,
        server_eth,
        metrics,
        limiter,
        cache,
        store,
        rate,
        &loopback_domains(),
        max_concurrent_streams,
    )
}

/// [`build_handler`] with a construction-time `configure` hook for the optional
/// deps the handler takes at construction (#1254).
#[allow(clippy::too_many_arguments)]
fn build_handler_configured(
    server_id: iroh::PublicKey,
    server_eth: &Arc<PrivateKeySigner>,
    metrics: &Arc<Metrics>,
    limiter: Arc<ConnectionLimiter>,
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    rate: u64,
    configure: impl FnOnce(&mut ClientHandlerDeps),
) -> anyhow::Result<Arc<ClientHandler>> {
    build_handler_limited_configured(
        server_id, server_eth, metrics, limiter, cache, store, rate, 16, configure,
    )
}

/// [`build_handler_limited`] with a construction-time `configure` hook (#1254).
#[allow(clippy::too_many_arguments)]
fn build_handler_limited_configured(
    server_id: iroh::PublicKey,
    server_eth: &Arc<PrivateKeySigner>,
    metrics: &Arc<Metrics>,
    limiter: Arc<ConnectionLimiter>,
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    rate: u64,
    max_concurrent_streams: usize,
    configure: impl FnOnce(&mut ClientHandlerDeps),
) -> anyhow::Result<Arc<ClientHandler>> {
    build_handler_full_configured(
        server_id,
        server_eth,
        metrics,
        limiter,
        cache,
        store,
        rate,
        &loopback_domains(),
        max_concurrent_streams,
        configure,
    )
}

/// The honest-requester [`PoolContext`]: a fresh lane for `client_signer` paying
/// [`operator_addr`], carrying an ADR 005 client identity binding over the
/// paying `client_ep`'s node id. The pool-model serve gate refuses any request
/// that cannot prove ownership of a lane, so every honest paid fetch attaches a
/// binding signed by the paying key over the connection's node id.
#[allow(clippy::expect_used)] // signing a fixed binding cannot fail in-test
fn pool_context(
    client_ep: &Endpoint,
    client_signer: Arc<PrivateKeySigner>,
    deposit: U256,
) -> PoolContext {
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&client_signer, own_node_id, &binding_domain())
        .expect("sign client binding over the loopback client node id");
    PoolContext {
        pool_id: pool_id(),
        provider: operator_addr(),
        deposit,
        client_signer,
        voucher_domain: payment_domain(),
        prior_bytes_delivered: U256::ZERO,
        prior_amount: U256::ZERO,
        client_binding: Some(binding),
        capability: None,
    }
}

/// The UNBOUND requester context (`client_binding: None`): the honest requester
/// sends no ADR 005 identity binding, so the seller cannot resolve a lane signer
/// and refuses the serve. Used by the control tests that prove the binding is
/// what unlocks the paid path.
fn unbound_context(client_signer: Arc<PrivateKeySigner>, deposit: U256) -> PoolContext {
    PoolContext {
        pool_id: pool_id(),
        provider: operator_addr(),
        deposit,
        client_signer,
        voucher_domain: payment_domain(),
        prior_bytes_delivered: U256::ZERO,
        prior_amount: U256::ZERO,
        client_binding: None,
        capability: None,
    }
}

/// Full happy path: a 1.5 MiB blob crosses one voucher-interval boundary plus a
/// closing voucher (two vouchers), the requester hash-verifies the bytes, and
/// the persisted lane state advances to nonce 2 / full byte count.
#[tokio::test(flavor = "multi_thread")]
async fn client_delivery_roundtrip_advances_lane_state() -> anyhow::Result<()> {
    let spans = support::capture_spans();
    let payload = vec![0xABu8; 1_572_864]; // 1.5 MiB
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;

    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch"
    );

    // The persisted lane advanced: two vouchers (interval + closing), full
    // byte count, non-zero cumulative amount.
    let persisted = store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    // ADR 038: metered quantity is bao wire bytes
    let wire = support::bao_wire_len_whole(payload.len() as u64);
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(wire),
        "bytes_delivered: {} (expected {wire})",
        only.last_bytes_delivered()
    );
    anyhow::ensure!(only.last_amount() > U256::ZERO, "amount must be non-zero");

    // The real serve path records its end once on its span: completed, with the
    // bytes it wrote and the join keys the requester's spans carry. The server
    // task drains the client's FIN after `StreamEnd`, so its span can close a
    // moment after the fetch returns; wait for it before shutdown would abort it.
    let key = hash.to_string();
    let deadline = std::time::Instant::now() + Duration::from_secs(10);
    while spans.matching("serve_stream", "hash", &key).is_empty()
        && std::time::Instant::now() < deadline
    {
        tokio::time::sleep(Duration::from_millis(20)).await;
    }
    shutdown([server_task], [&client_ep, &server_ep]).await?;

    assert_one_completed_inbound_stream(&metrics, 2)?;

    let served = spans.matching("serve_stream", "hash", &key);
    let [span] = served.as_slice() else {
        anyhow::bail!("expected one serve_stream span for the hash, got {served:?}");
    };
    anyhow::ensure!(
        span.fields.get("outcome").map(String::as_str) == Some("completed"),
        "outcome: {span:?}"
    );
    anyhow::ensure!(
        span.fields.get("bytes").is_some_and(|b| b != "0"),
        "bytes: {span:?}"
    );
    anyhow::ensure!(
        span.fields.get("peer").map(String::as_str) == Some(client_ep.id().to_string().as_str()),
        "peer: {span:?}"
    );
    support::assert_serve_waits_recorded(span, payload.len() as u64)?;
    Ok(())
}

/// Two different hashes fetched back-to-back over ONE [`WarmConnection`] reuse the
/// single dialed connection: the server accepts exactly one connection and serves
/// both hashes as separate bi-streams. A pull that closed the connection on
/// `finish` would force the second fetch to fail (or silently re-dial), so this
/// pins connection reuse across hashes.
#[tokio::test(flavor = "multi_thread")]
async fn two_hashes_reuse_one_warm_connection() -> anyhow::Result<()> {
    let payload_a = vec![0x11u8; 400_000];
    let payload_b = vec![0x22u8; 500_000];
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(50_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let (server_task, accepted) = spawn_server_counting(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);

    let warm = WarmConnection::connect(&client_ep, target, Duration::from_secs(20), None).await?;

    let got_a = stream_fetch_on(
        &warm,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash_a.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got_a.as_ref() == payload_a.as_slice(),
        "hash A bytes mismatch"
    );

    // Hash B pays on the same lane, so its vouchers continue the lane's
    // cumulative totals where hash A left them.
    let after_a = store.load_all()?;
    let lane_a = after_a
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane after hash A"))?;
    let ctx_b = PoolContext {
        prior_bytes_delivered: lane_a.last_bytes_delivered(),
        prior_amount: lane_a.last_amount(),
        ..ctx
    };
    let got_b = stream_fetch_on(
        &warm,
        &ctx_b,
        &slash_domain(),
        server_eth.address(),
        *hash_b.as_bytes(),
        0,
        0x00c0_ffef,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got_b.as_ref() == payload_b.as_slice(),
        "hash B bytes mismatch"
    );

    let dialed = accepted.load(std::sync::atomic::Ordering::SeqCst);
    anyhow::ensure!(
        dialed == 1,
        "expected exactly one accepted connection across two hash fetches, got {dialed}"
    );

    drop(warm);
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A [`PeerSource`](decdn_client::PeerSource) with a
/// [`Connections`](decdn_client::Connections) map runs every leg to one node on
/// one connection: two whole-blob drives dial once, and a `NotFound` refusal
/// between them leaves the connection for the next leg.
#[allow(
    clippy::too_many_lines,
    reason = "one fixture: a paid handler, a lane, two drives and a refusal"
)]
#[tokio::test(flavor = "multi_thread")]
async fn peer_source_legs_share_one_connection_across_a_refusal() -> anyhow::Result<()> {
    use decdn_client::driver::drive;
    use decdn_client::source::BlobSource as _;
    use decdn_client::{BudgetPacer, ClientRangedStore, Connections, PeerSource};

    let payload_a = vec![0x31u8; 400_000];
    let payload_b = vec![0x42u8; 500_000];
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(50_000_000u64);
    let pool_store = Arc::new(MemoryPoolStateStore::new());
    pool_store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = pool_store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let (server_task, accepted) = spawn_server_counting(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    let ledger = Arc::new(ctx.new_ledger());
    let ctx = Arc::new(std::sync::Mutex::new(ctx));
    let slash = slash_domain();
    let connections = Connections::new(client_ep.clone());
    let source = PeerSource::new(
        &client_ep,
        target,
        Arc::clone(&ctx),
        Arc::clone(&ledger),
        &slash,
        server_eth.address(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        u64::MAX,
        PullDeadlines::new(Duration::from_secs(10), Duration::from_secs(10), 0)?,
        Some(connections.clone()),
    );
    let pacer = BudgetPacer::new();
    let store_dir = tempfile::tempdir()?;
    let fetch = |name: &'static str, hash: Hash, len: usize| {
        let (source, pacer, ctx, ledger) = (&source, &pacer, &ctx, &ledger);
        let dir = store_dir.path().to_path_buf();
        async move {
            let total = u64::try_from(len)?;
            let store = ClientRangedStore::create(&dir, name, *hash.as_bytes(), total)?;
            drive(
                &store,
                source,
                pacer,
                ctx,
                ledger,
                *hash.as_bytes(),
                0,
                0,
                None,
                None,
                None,
                None,
            )
            .await?;
            Ok::<_, anyhow::Error>(std::fs::read(dir.join(name))?)
        }
    };

    anyhow::ensure!(fetch("a", hash_a, payload_a.len()).await? == payload_a);
    // A leg naming a pool the node has never seen is refused with `NotFound`.
    let known_pool = {
        let mut ctx = ctx
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        std::mem::replace(&mut ctx.pool_id, B256::repeat_byte(0xEE))
    };
    let range = decdn_bao_range::align_range(0, 0, u64::try_from(payload_a.len())?)?;
    let refused = source
        .open(*hash_a.as_bytes(), range)
        .await
        .err()
        .ok_or_else(|| anyhow::anyhow!("a leg on an unknown pool must be refused"))?;
    ctx.lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
        .pool_id = known_pool;
    anyhow::ensure!(
        refused
            .downcast_ref::<decdn_client::UpstreamRefused>()
            .is_some_and(|r| *r.error() == StreamError::NotFound),
        "expected a NotFound refusal, got: {refused:#}"
    );
    anyhow::ensure!(fetch("b", hash_b, payload_b.len()).await? == payload_b);

    anyhow::ensure!(
        connections.dials() == 1,
        "every leg must share one dial, got {}",
        connections.dials()
    );
    let served = accepted.load(std::sync::atomic::Ordering::SeqCst);
    anyhow::ensure!(
        served == 1,
        "the node must accept one connection, got {served}"
    );

    drop(source);
    drop(connections);
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Drive a scattered range set across four concurrent sibling stores, then the
/// rest of the blob into one of them, through one `PeerSource` on one ledger
/// against a live handler. The lane is seeded with a live chain from an
/// earlier payer process ([`lane_with_proved_reveals`]), so the fresh ledger
/// trails the node's watermark and every leg's first proof is stale.
#[allow(
    clippy::too_many_lines,
    reason = "one fixture: a paid handler, a lane, and the two drives it serves"
)]
async fn drive_scattered_as_a_restarted_payer() -> anyhow::Result<()> {
    use decdn_client::driver::drive;
    use decdn_client::{BudgetPacer, ClientRangedStore, PeerSource, SharedPool};

    const GROUP: u64 = 16 * 1024;
    let payload: Vec<u8> = (0..32 * GROUP).map(|i| (i % 251) as u8).collect();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let total = u64::try_from(payload.len())?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(1_000_000_000u64);
    let pool_store = Arc::new(MemoryPoolStateStore::new());
    pool_store.record(&lane_with_proved_reveals(&client_signer, deposit)?)?;
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = pool_store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let (server_task, _accepted) = spawn_server_counting(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    let ledger = Arc::new(ctx.new_ledger());
    let ctx = Arc::new(std::sync::Mutex::new(ctx));
    let slash = slash_domain();
    let source = PeerSource::new(
        &client_ep,
        target,
        Arc::clone(&ctx),
        Arc::clone(&ledger),
        &slash,
        server_eth.address(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        u64::MAX,
        PullDeadlines::new(Duration::from_secs(10), Duration::from_secs(10), 0)?,
        None,
    );
    // Four sibling fetches of the blob, one store each, on the one lane: the
    // shape of concurrent bundle entries that share a provider.
    let store_dir = tempfile::tempdir()?;
    let stores = (0..4)
        .map(|i| {
            ClientRangedStore::create(
                store_dir.path(),
                &format!("blob{i}"),
                *hash.as_bytes(),
                total,
            )
        })
        .collect::<Result<Vec<_>, _>>()?;

    let spent_ledger = Arc::clone(&ledger);
    let spent = move || spent_ledger.committed().amount;
    let pool = SharedPool {
        spent: &spent,
        quotes: None,
    };
    let scattered: Vec<(u64, u64)> = (0..32).step_by(2).map(|g| (g * GROUP, GROUP)).collect();
    let pacer = BudgetPacer::new();
    let range = |store, (offset, len): (u64, u64)| {
        drive(
            store,
            &source,
            &pacer,
            &ctx,
            &ledger,
            *hash.as_bytes(),
            offset,
            len,
            None,
            None,
            None,
            Some(&pool),
        )
    };
    // Each sibling drives every fourth range of the set, all four at once.
    let siblings = stores.iter().enumerate().map(|(i, store)| {
        let mine: Vec<(u64, u64)> = scattered.iter().copied().skip(i).step_by(4).collect();
        async move {
            for r in mine {
                range(store, r).await?;
            }
            anyhow::Ok(())
        }
    });
    for driven in futures_util::future::join_all(siblings).await {
        driven?;
    }
    // Then the first sibling drives the rest of the blob.
    let first = stores.first().ok_or_else(|| anyhow::anyhow!("no store"))?;
    range(first, (0, 0)).await?;
    anyhow::ensure!(
        std::fs::read(store_dir.path().join("blob0"))? == payload,
        "the range set and the rest assemble the blob byte-exact"
    );
    drop(source);
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A restarted payer drives a scattered range set, four legs at a time on one
/// ledger, against a lane whose watermark it lost (#2173). Each 16 KiB leg's
/// only proof is a sealed closing voucher at or below the node's signed anchor, and
/// lane headroom cannot pay it, so the node rejects it with the watermark
/// bundle. The first rejection reseeds the shared ledger; every concurrent leg
/// rejected after it finds the ledger already reseeded and retries. The whole
/// set must still assemble.
#[tokio::test(flavor = "multi_thread")]
async fn a_restarted_payer_heals_a_concurrent_range_set() -> anyhow::Result<()> {
    Box::pin(drive_scattered_as_a_restarted_payer()).await
}

/// A restarted payer's sub-chunk transfer (#1946): the node's lane sits two
/// transfers ahead of the payer's lost watermark. The transfer's only proof is
/// a sealed closing voucher below the signed anchor, which is the proof that
/// pays its chunk, and lane headroom cannot pay it. The node rejects it with
/// the bundle, and the payer reseeds and completes.
#[tokio::test(flavor = "multi_thread")]
async fn a_restarted_payer_heals_a_sub_chunk_transfer() -> anyhow::Result<()> {
    restarted_sub_chunk_transfer(2).await
}

/// The same heal when the node's lane sits exactly ONE transfer ahead: the
/// restarted payer re-signs the node's own watermark for a transfer the same
/// size. The voucher is at the signed anchor, not below it, but it is still
/// stale: the lane already holds that payment, and headroom cannot pay the
/// chunk again. Crediting it nothing and waiting would leave the node waiting
/// on a proof the payer never sends.
#[tokio::test(flavor = "multi_thread")]
async fn a_restarted_payer_heals_a_transfer_that_repeats_the_anchor() -> anyhow::Result<()> {
    restarted_sub_chunk_transfer(1).await
}

/// Run `earlier` healthy 256 KiB transfers, each resuming from the watermark
/// the last one left, then the same transfer from a payer whose watermark is
/// gone. The 8s budget sits below the node's proof-wait backstop (10s with no
/// transport progress, `VOUCHER_READ_TIMEOUT`), so the heal must fire on the
/// rejection itself.
async fn restarted_sub_chunk_transfer(earlier: u64) -> anyhow::Result<()> {
    let payload = vec![0x3Cu8; 256 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, Arc::clone(&store), RATE_PER_MB, 16).await?;
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;

    let fetch = |ctx: PoolContext, timestamp_us: u64, budget: Duration| {
        let target = target.clone();
        let client_ep = &client_ep;
        let server = server_eth.address();
        async move {
            stream_fetch(
                client_ep,
                target,
                &ctx,
                &slash_domain(),
                server,
                *hash.as_bytes(),
                0,
                timestamp_us,
                budget,
            )
            .await
        }
    };
    for timestamp_us in 0x7771..0x7771 + earlier {
        let mut ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);
        if let Some(lane) = store.load_all()?.first() {
            ctx.prior_amount = lane.last_amount();
            ctx.prior_bytes_delivered = lane.last_bytes_delivered();
        }
        let got = fetch(ctx, timestamp_us, Duration::from_secs(20)).await?;
        anyhow::ensure!(got.as_ref() == payload.as_slice());
    }

    // The restarted payer: its watermark is gone.
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);
    let got = fetch(ctx, 0x7770, Duration::from_secs(8)).await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "the restarted payer must reseed and recover the blob"
    );
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_voucher_rejected_total")? == 1,
        "the heal costs exactly one rejected voucher"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// One served stream timed its first frame, in the `class` sibling (`hit` or
/// `miss`) and not the other. A buffered fill serves a miss through the
/// cache-hit delivery loop, and must still record as a miss.
fn assert_first_byte_class(metrics: &Metrics, class: &str) -> anyhow::Result<()> {
    let encoded = metrics.encode()?;
    for sibling in ["hit", "miss"] {
        let line = format!(
            "decdn_serve_first_byte_{sibling}_seconds_count {}",
            u64::from(sibling == class)
        );
        anyhow::ensure!(
            metric_line_present(&encoded, &line),
            "missing `{line}`:\n{encoded}"
        );
    }
    Ok(())
}

/// The stream-outcome family counts one completed inbound stream and no failed
/// one, with the `vouchers` it accepted and a non-zero byte count.
fn assert_one_completed_inbound_stream(metrics: &Metrics, vouchers: u64) -> anyhow::Result<()> {
    let encoded = metrics.encode()?;
    for line in [
        "decdn_streams_completed_total{direction=\"inbound\"} 1".to_string(),
        "decdn_streams_failed_total{direction=\"inbound\"} 0".to_string(),
        format!("decdn_vouchers_received_total {vouchers}"),
        // The harness seeds the blob locally, so the availability gate must
        // classify this serve as a complete-blob hit and leave both siblings
        // at zero. Pinned here because the serve path reads the store through
        // `export_bao_range_stream`, never `CacheEngine::get` — the `get`-scoped
        // `decdn_cache_hits_total` stays at zero throughout a real serve, so it
        // cannot stand in for this assertion.
        "decdn_serve_cache_hit_total 1".to_string(),
        "decdn_serve_cache_partial_hit_total 0".to_string(),
        "decdn_serve_cache_miss_total 0".to_string(),
        // The first frame of the hit records into the hit sibling only.
        "decdn_serve_first_byte_hit_seconds_count 1".to_string(),
        "decdn_serve_first_byte_miss_seconds_count 0".to_string(),
    ] {
        anyhow::ensure!(
            metric_line_present(&encoded, &line),
            "missing `{line}`:\n{encoded}"
        );
    }
    anyhow::ensure!(
        !metric_line_present(&encoded, "decdn_bytes_served_total 0"),
        "bytes served must count the delivered frames:\n{encoded}"
    );
    Ok(())
}

/// One voucher accounting interval — [`decdn_protocol::client::CHUNK_BYTES`].
const HARNESS_INTERVAL_BYTES: u64 = decdn_protocol::client::CHUNK_BYTES;

/// The payer's verify lag ([`decdn_client::VERIFY_LAG_BYTES`]): the wire bytes
/// past an interval boundary it must receive before it can verify, and so pay
/// for, the interval.
const HARNESS_LAG_BYTES: u64 = decdn_client::VERIFY_LAG_BYTES;

/// The node's credit-window floor: one interval plus the payer's verify lag. An
/// unpaid stream receives exactly this much and parks; each whole interval paid
/// at the floor reopens exactly one more interval.
const HARNESS_FLOOR_BYTES: u64 = HARNESS_INTERVAL_BYTES + HARNESS_LAG_BYTES;

/// Spin up a serving `ClientHandler` with an explicit downstream credit-window
/// ceiling and ramp divisor (ADR 003 §Credit window, #1669). The effective
/// window at any point is `ramped_credit_window(credit_ramp_divisor,
/// floor, credit_max, paid)`: at `paid = 0` a non-zero divisor floors the
/// window to [`HARNESS_FLOOR_BYTES`] (stop-and-wait), while `credit_ramp_divisor = 0`
/// opens the full `credit_max` immediately regardless of payment.
async fn spawn_pipelined_server(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    credit_max: u64,
    credit_ramp_divisor: u64,
) -> anyhow::Result<(
    EndpointAddr,
    Arc<PrivateKeySigner>,
    Endpoint,
    tokio::task::JoinHandle<()>,
)> {
    let (target, server_eth, server_ep, server_task, _metrics) =
        spawn_pipelined_server_with_metrics(cache, store, credit_max, credit_ramp_divisor).await?;
    Ok((target, server_eth, server_ep, server_task))
}

/// As [`spawn_pipelined_server`], but also returns the server's `Arc<Metrics>`.
async fn spawn_pipelined_server_with_metrics(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    credit_max: u64,
    credit_ramp_divisor: u64,
) -> anyhow::Result<(
    EndpointAddr,
    Arc<PrivateKeySigner>,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_full_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        &loopback_domains(),
        16,
        |deps| {
            deps.credit_max = credit_max;
            deps.credit_ramp_divisor = credit_ramp_divisor;
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((target, server_eth, server_ep, server_task, metrics))
}

/// Open a paid `cdn/client/v1` stream and read past its signed `StreamResponse`,
/// leaving the caller positioned to read `ChunkData`. The raw counterpart to the
/// pipelined requester (#1484): it drives the byte stream by hand so a test can
/// choose exactly when (and whether) to pay.
async fn open_paid_stream(
    conn: &Connection,
    hash: [u8; 32],
    ext: Option<&StreamRequestExt>,
) -> anyhow::Result<(SendStream, RecvStream)> {
    open_paid_range_stream(conn, hash, ext, 0, 0).await
}

/// As [`open_paid_stream`], for the range `[byte_offset, +byte_len)` (`byte_len
/// == 0` is to the blob's end).
async fn open_paid_range_stream(
    conn: &Connection,
    hash: [u8; 32],
    ext: Option<&StreamRequestExt>,
    byte_offset: u64,
    byte_len: u64,
) -> anyhow::Result<(SendStream, RecvStream)> {
    let (mut send, mut recv) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi: {e}"))?;
    let req = StreamRequest {
        hash,
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset,
        byte_len,
        timestamp_us: 0x0012_61a0,
    };
    let payload =
        encode_stream_request(&req, ext).map_err(|e| anyhow::anyhow!("encode request: {e}"))?;
    write_frame(&mut send, &payload)
        .await
        .map_err(|e| anyhow::anyhow!("write request: {e}"))?;
    let (resp, resp_ext) = read_stream_response(&mut recv).await?;
    anyhow::ensure!(resp.body.ok, "delivery refused: {:?}", resp_ext.error);
    Ok((send, recv))
}

/// Read EXACTLY `expect` wire bytes of `ChunkData`, giving each read a generous
/// ceiling so a loaded CI box cannot spuriously truncate a delivery that is in
/// fact coming. Bails if the server sends a non-chunk, stalls before `expect`, or
/// overshoots the expected count. Deterministic under load: it waits for bytes
/// that a correct server WILL send, rather than inferring "done" from a quiet gap.
async fn read_exact_chunks(recv: &mut RecvStream, expect: u64) -> anyhow::Result<()> {
    let mut got: u64 = 0;
    while got < expect {
        let msg = tokio::time::timeout(Duration::from_secs(10), read_client_msg(recv))
            .await
            .map_err(|_| {
                anyhow::anyhow!("server stalled after {got} of {expect} expected wire bytes")
            })??;
        match msg {
            ClientMessage::ChunkData(chunk) => {
                got = got.saturating_add(chunk.bytes().len() as u64);
            }
            other => anyhow::bail!("expected ChunkData, got {other:?}"),
        }
    }
    anyhow::ensure!(
        got == expect,
        "read {got} wire bytes, expected exactly {expect} (server overshot the credit window)"
    );
    Ok(())
}

/// Assert the server has PARKED — that it has sent nothing beyond what was already
/// read and is blocked in `collect_voucher` awaiting a voucher we are withholding.
///
/// This is the credit-exposure bound, checked as an ABSENCE and therefore robust
/// under parallel test load: a correct pipelining node cannot send past the credit
/// window without a voucher, so no further byte is ever coming and the read times
/// out deterministically. Only a buggy OVER-delivering server makes this read
/// return — and it returns fast, so the timeout only bounds how long we wait to
/// catch that bug, never whether a correct server passes.
async fn assert_parked_awaiting_voucher(recv: &mut RecvStream) -> anyhow::Result<()> {
    match tokio::time::timeout(Duration::from_secs(2), read_client_msg(recv)).await {
        Err(_elapsed) => Ok(()),
        Ok(Ok(ClientMessage::ChunkData(chunk))) => anyhow::bail!(
            "server sent {} more wire bytes past the credit window instead of parking for a voucher",
            chunk.bytes().len()
        ),
        Ok(other) => anyhow::bail!("expected the server to park awaiting a voucher; got {other:?}"),
    }
}

/// Sign a single cumulative voucher paying for `bytes_delivered` bytes and
/// write it to `send`. Acceptance is implicit — the node sends no ack, it
/// just advances `paid` and (if the wider window has room) keeps delivering.
async fn pay_cumulative(
    send: &mut SendStream,
    signer: &PrivateKeySigner,
    bytes_delivered: u64,
) -> anyhow::Result<()> {
    let amount = min_payment(bytes_delivered, RATE_PER_MB);
    let voucher = Voucher {
        pool_id: pool_id(),
        signer: signer.address(),
        provider: operator_addr(),
        amount,
        bytes_delivered: U256::from(bytes_delivered),
        chain_root: B256::ZERO,
        chunk_price: U256::ZERO,
    }
    .sign(signer, &payment_domain())
    .map_err(|e| anyhow::anyhow!("sign voucher: {e}"))?;
    write_client_msg(
        send,
        &ClientMessage::Voucher(signed_to_wire_voucher(&voucher)?),
    )
    .await
}

/// The payer's per-lane seed for the `PayWord` tests. A real seed is derived per
/// `(pool_id, signer, provider)` lane and epoch from the payer's key; every test
/// here drives a single lane, so one seed covers each epoch it opens.
const CHAIN_SEED: B256 = B256::repeat_byte(0x5E);

/// The seed of the epoch a rollover opens, for the tests that roll the lane
/// off [`CHAIN_SEED`]'s chain.
const ROLLED_SEED: B256 = B256::repeat_byte(0x6E);

fn chain_root() -> B256 {
    decdn_incentive::root_from_seed(CHAIN_SEED)
}

fn rolled_root() -> B256 {
    decdn_incentive::root_from_seed(ROLLED_SEED)
}

/// Sign a **metering** voucher: it opens (or re-asserts) a chain at `root`, and
/// commits to the node's quoted per-MB rate as the chunk price. Every reveal
/// that follows inherits that price, which is why the node checks it here.
async fn open_chain(
    send: &mut SendStream,
    signer: &PrivateKeySigner,
    root: B256,
    chunk_price: u64,
    amount: U256,
    bytes_delivered: u64,
) -> anyhow::Result<()> {
    let voucher = Voucher {
        pool_id: pool_id(),
        signer: signer.address(),
        provider: operator_addr(),
        amount,
        bytes_delivered: U256::from(bytes_delivered),
        chain_root: root,
        chunk_price: U256::from(chunk_price),
    }
    .sign(signer, &payment_domain())
    .map_err(|e| anyhow::anyhow!("sign voucher: {e}"))?;
    write_client_msg(
        send,
        &ClientMessage::Voucher(signed_to_wire_voucher(&voucher)?),
    )
    .await
}

/// Release the preimage at `index` on [`CHAIN_SEED`]'s chain — the one-message,
/// no-signature tick that pays for one whole chunk.
async fn release(send: &mut SendStream, index: u8) -> anyhow::Result<()> {
    release_from(send, CHAIN_SEED, index).await
}

/// Release the preimage at `index` on the chain `chain_seed` derives.
async fn release_from(send: &mut SendStream, chain_seed: B256, index: u8) -> anyhow::Result<()> {
    write_client_msg(
        send,
        &ClientMessage::ChunkPreimage(decdn_protocol::client::ChunkPreimage {
            preimage: decdn_incentive::preimage_at(chain_seed, index).into(),
            index,
        }),
    )
    .await
}

/// Read the mid-stream rejection the node answers a bad proof with, and assert
/// its reason. A rejection rides in band as a `StreamError` and closes the
/// stream cleanly — no QUIC reset — precisely so the payer can tell a payment
/// refusal from a network failure.
async fn expect_reject(recv: &mut RecvStream, expected: VoucherRejectReason) -> anyhow::Result<()> {
    loop {
        let msg = tokio::time::timeout(Duration::from_secs(10), read_client_msg(recv))
            .await
            .map_err(|_| anyhow::anyhow!("node never answered with a rejection"))??;
        match msg {
            // Chunks already in flight when we sent the bad proof.
            ClientMessage::ChunkData(_) => {}
            ClientMessage::StreamError(StreamError::VoucherRejected { reason, bundle }) => {
                anyhow::ensure!(reason == expected, "expected {expected:?}, got {reason:?}");
                anyhow::ensure!(
                    bundle.is_none(),
                    "a chain rejection carries no watermark bundle: a preimage has no \
                     signature of its own, so a payment watermark cannot repair it"
                );
                return Ok(());
            }
            other => anyhow::bail!("expected a VoucherRejected, got {other:?}"),
        }
    }
}

/// A serve's first frame is small, so the first byte leaves after a few chunk
/// groups rather than a whole interval. The frames after it still fill the
/// window floor exactly, and the node parks for its voucher at the same
/// boundary.
#[tokio::test(flavor = "multi_thread")]
async fn the_first_frame_is_small_and_the_interval_still_ends_on_its_boundary() -> anyhow::Result<()>
{
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    const FIRST_FRAME_MAX: u64 = 64 * 1024;
    let payload = vec![0x45u8; 8 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;
    let (target, _server_eth, server_ep, server_task, _metrics) =
        spawn_pipelined_server_with_metrics(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (_send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    let first = tokio::time::timeout(Duration::from_secs(10), read_client_msg(&mut recv))
        .await
        .map_err(|_| anyhow::anyhow!("no first frame"))??;
    let ClientMessage::ChunkData(first) = first else {
        anyhow::bail!("expected ChunkData, got {first:?}");
    };
    let first_len = first.bytes().len() as u64;
    anyhow::ensure!(
        first_len <= FIRST_FRAME_MAX,
        "the first frame carries {first_len} bytes, over {FIRST_FRAME_MAX}"
    );
    read_exact_chunks(&mut recv, HARNESS_FLOOR_BYTES - first_len).await?;
    assert_parked_awaiting_voucher(&mut recv).await?;

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The whole `PayWord` tick, end to end: one signed voucher opens a chain, and
/// from then on each delivered chunk is paid for by a single 33-byte reveal with
/// no signature at all. The node credits the reveal exactly as it would a
/// voucher, so the credit window reopens and delivery continues.
#[tokio::test(flavor = "multi_thread")]
async fn a_released_preimage_pays_for_a_chunk_and_resumes_delivery() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x44u8; 8 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task, metrics) =
        spawn_pipelined_server_with_metrics(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (mut send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    // One chunk and the verify lag delivered against the ramp floor, then the
    // node parks.
    read_exact_chunks(&mut recv, HARNESS_FLOOR_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv).await?;

    // Anchor this stream to the chain, then pay the delivered chunk with a
    // reveal. The anchor voucher itself credits nothing — it re-asserts a
    // cumulative of zero — so the node keeps waiting until the reveal lands.
    open_chain(&mut send, &signer, chain_root(), RATE_PER_MB, U256::ZERO, 0).await?;
    release(&mut send, 1).await?;

    // The reveal paid for a whole chunk, so the window reopened.
    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv).await?;

    // And it is recorded, on the same lane row a signature would advance.
    let lane = store
        .get(lane_key(signer.address()))?
        .ok_or_else(|| anyhow::anyhow!("lane row missing"))?;
    anyhow::ensure!(
        lane.chain().verified_index == 1,
        "the lane's chain frontier must record the reveal"
    );
    anyhow::ensure!(
        lane.owed() == U256::from(RATE_PER_MB),
        "one chunk at the quoted rate, owed on top of a zero anchor: {}",
        lane.owed()
    );
    // The anchor counts as a voucher and the reveal counts apart from it.
    anyhow::ensure!(counter(&metrics, "decdn_vouchers_received_total")? == 1);
    anyhow::ensure!(counter(&metrics, "decdn_preimage_reveals_received_total")? == 1);

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A reveal is a bearer proof: 33 bytes naming no chain. On a stream that has
/// not carried the epoch's root voucher the node cannot say which chain it
/// extends, so it refuses rather than guess. Not fatal — the payer sends the
/// root voucher on this stream and resends.
#[tokio::test(flavor = "multi_thread")]
async fn a_preimage_before_its_epoch_voucher_is_unanchored() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x45u8; 4 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (mut send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;
    // A reveal with no anchor on this stream.
    release(&mut send, 1).await?;
    expect_reject(&mut recv, VoucherRejectReason::UnanchoredPreimage).await?;

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Index 0 names the chain root and resolves to the voucher's own `amount`, so
/// it proves nothing the voucher does not already say. It is the settlement case
/// at redemption and never travels the wire.
#[tokio::test(flavor = "multi_thread")]
async fn a_preimage_at_index_zero_is_refused() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x46u8; 4 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (mut send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;
    open_chain(&mut send, &signer, chain_root(), RATE_PER_MB, U256::ZERO, 0).await?;
    release(&mut send, 0).await?;
    expect_reject(&mut recv, VoucherRejectReason::ChainIndexZero).await?;

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A reveal inside the capability's expiry margin is refused with
/// `CapabilityExpired`, exactly as a voucher is, even on a stream the node
/// anchored before the margin started. Otherwise the claim could keep growing
/// after the redeemer's cutoff sweep has read the lane (#2233).
#[tokio::test(flavor = "multi_thread")]
async fn a_preimage_inside_the_expiry_margin_is_refused() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x49u8; 4 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;
    // The margin starts two seconds from now.
    let cutoff = unix_now()?.saturating_add(2);
    let mut lane = store
        .get(lane_key(signer.address()))?
        .ok_or_else(|| anyhow::anyhow!("lane row missing"))?;
    lane.expiry = cutoff.saturating_add(DEFAULT_EXPIRY_MARGIN);
    store.record(&lane)?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (mut send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    // The anchor voucher lands before the margin.
    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;
    open_chain(&mut send, &signer, chain_root(), RATE_PER_MB, U256::ZERO, 0).await?;
    anyhow::ensure!(
        unix_now()? < cutoff,
        "the anchor must land before the margin"
    );

    // The reveal lands inside it.
    while unix_now()? < cutoff {
        tokio::time::sleep(Duration::from_millis(100)).await;
    }
    release(&mut send, 1).await?;
    expect_reject(&mut recv, VoucherRejectReason::CapabilityExpired).await?;

    let lane = store
        .get(lane_key(signer.address()))?
        .ok_or_else(|| anyhow::anyhow!("lane row missing"))?;
    anyhow::ensure!(
        lane.chain().verified_index == 0,
        "the refused reveal must not extend the claim"
    );

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A value from another chain never reaches the node's tip, and it cannot: only
/// the payer can produce a value at a given depth. The rejection is terminal —
/// a wrong seed or a wrong chain is a payer bug, not transient state.
#[tokio::test(flavor = "multi_thread")]
async fn a_foreign_preimage_is_refused() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x47u8; 4 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (mut send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;
    open_chain(&mut send, &signer, chain_root(), RATE_PER_MB, U256::ZERO, 0).await?;
    write_client_msg(
        &mut send,
        &ClientMessage::ChunkPreimage(decdn_protocol::client::ChunkPreimage {
            preimage: decdn_incentive::preimage_at(B256::repeat_byte(0x5F), 1).into(),
            index: 1,
        }),
    )
    .await?;
    expect_reject(&mut recv, VoucherRejectReason::BadPreimage).await?;

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Assert that the node wrote exactly one `rejecting a payment proof` line for
/// `signer`, with `reason` and `with_watermark`. The capture is shared across
/// the binary, so the per-test random signer keeps the filter unique (#2342).
fn assert_one_reject_line(
    spans: &support::SpanCapture,
    signer: &PrivateKeySigner,
    reason: &str,
    with_watermark: bool,
) -> anyhow::Result<()> {
    let lines = spans.events(
        "rejecting a payment proof",
        "signer",
        &signer.address().to_string(),
    );
    let [line] = lines.as_slice() else {
        anyhow::bail!("expected one proof-reject line for the signer, got {lines:?}");
    };
    let with_watermark = with_watermark.to_string();
    anyhow::ensure!(
        line.get("reason").map(String::as_str) == Some(reason)
            && line.get("with_watermark") == Some(&with_watermark),
        "expected reason={reason} with_watermark={with_watermark}: {line:?}"
    );
    Ok(())
}

/// The node MUST check the price it is being paid. A reveal carries no price of
/// its own, so a chain opened at the wrong `chunk_price` would meter every later
/// chunk below the node's quote with no per-tick moment revealing it.
#[tokio::test(flavor = "multi_thread")]
async fn a_chain_opened_below_the_quoted_rate_is_refused() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let spans = support::capture_spans();
    let payload = vec![0x48u8; 4 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (mut send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;
    // A tenth of the quote — the governance-floor price against a node quoting
    // ten times it.
    open_chain(&mut send, &signer, chain_root(), 1, U256::ZERO, 0).await?;
    expect_reject(&mut recv, VoucherRejectReason::ChunkPriceMismatch).await?;
    // The node logs before it writes the frame, so the line is already there.
    assert_one_reject_line(&spans, &signer, "ChunkPriceMismatch", false)?;

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A sealed voucher meters no chunk, so it MUST carry a zero price — that is
/// what keeps `chain_root == 0 ⟺ chunk_price == 0` true on both sides of the
/// wire, and it is why nothing downstream needs a branch on the zero root.
#[tokio::test(flavor = "multi_thread")]
async fn a_sealed_voucher_carrying_a_price_is_refused() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x49u8; 4 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (mut send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;
    open_chain(
        &mut send,
        &signer,
        B256::ZERO,
        RATE_PER_MB,
        min_payment(HARNESS_INTERVAL_BYTES, RATE_PER_MB),
        HARNESS_INTERVAL_BYTES,
    )
    .await?;
    expect_reject(&mut recv, VoucherRejectReason::ChunkPriceMismatch).await?;

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Deepest-preimage-wins, across two concurrent streams on ONE lane.
///
/// The chain's scope is the lane, so both streams share one root and one index
/// space. Stream A skips ahead to index 3 and stream B then offers 1 and 2 —
/// both already covered, so both advance nothing and hash nothing. Stream B's
/// index 5 does advance. The lane converges on the deepest index either stream
/// proved, never on their sum: a claim is a maximum, because a rollover voucher
/// already folds the retired chain into its own amount.
#[tokio::test(flavor = "multi_thread")]
async fn two_streams_on_one_lane_converge_on_the_deepest_index() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x4Au8; 8 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;

    let (mut send_a, mut recv_a) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
    let (mut send_b, mut recv_b) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
    read_exact_chunks(&mut recv_a, HARNESS_FLOOR_BYTES).await?;
    read_exact_chunks(&mut recv_b, HARNESS_FLOOR_BYTES).await?;

    // Each stream anchors ITSELF to the epoch — a sibling having done so is not
    // enough, because a bare reveal is placed against the stream it arrives on.
    open_chain(
        &mut send_a,
        &signer,
        chain_root(),
        RATE_PER_MB,
        U256::ZERO,
        0,
    )
    .await?;
    open_chain(
        &mut send_b,
        &signer,
        chain_root(),
        RATE_PER_MB,
        U256::ZERO,
        0,
    )
    .await?;

    // A skips ahead; B then offers indices already covered, and finally a deeper
    // one. The already-covered reveals are benign, not rejections.
    release(&mut send_a, 3).await?;
    read_exact_chunks(&mut recv_a, HARNESS_INTERVAL_BYTES).await?;
    release(&mut send_b, 1).await?;
    release(&mut send_b, 2).await?;
    release(&mut send_b, 5).await?;
    read_exact_chunks(&mut recv_b, HARNESS_INTERVAL_BYTES).await?;

    // The node reads B's queued reveals one owed chunk at a time, so index 5
    // lands a recoup phase after the chunk just read. Wait for it.
    let deadline = Instant::now() + Duration::from_secs(10);
    let lane = loop {
        let lane = store
            .get(lane_key(signer.address()))?
            .ok_or_else(|| anyhow::anyhow!("lane row missing"))?;
        if lane.chain().verified_index >= 5 || Instant::now() >= deadline {
            break lane;
        }
        tokio::time::sleep(Duration::from_millis(20)).await;
    };
    anyhow::ensure!(
        lane.chain().verified_index == 5,
        "the lane converges on the deepest index proved, got {}",
        lane.chain().verified_index
    );
    anyhow::ensure!(
        lane.owed() == U256::from(5 * RATE_PER_MB),
        "the lane's claim is a MAXIMUM over the streams, never a sum: {}",
        lane.owed()
    );

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A slow co-stream must not STARVE when its reveal for its OWN delivered chunk
/// lands below a fast sibling's frontier.
///
/// The chain index is lane-global, so cross-stream reordering routinely puts one
/// stream's reveal at or below the frontier a faster sibling already advanced.
/// That reveal folds nothing — but the lane has ALREADY been paid for those
/// bytes by the sibling's deeper reveal, so the node must credit this stream from
/// that lane headroom and reopen its window, exactly as it does for a benign
/// already-satisfied VOUCHER. Crediting nothing throttles the slow stream to a
/// `MAX_PROOFS_PER_CHUNK` stall — the concurrent same-lane voucher-starvation bug
/// (the concrete #1689 "needs a rendezvous" case).
///
/// The construction isolates the reveal-credit path. Stream A skips ahead to
/// index 5 and reads its chunk, so the lane is paid several chunks ahead. Stream
/// B then anchors. Its anchor is a metering voucher, and a metering voucher pays
/// no whole chunk, so B stays parked even with headroom on the lane. B then pays
/// each delivered chunk with a below-frontier reveal: the node must credit each
/// one from the remaining headroom, or B never reads its next chunk.
#[tokio::test(flavor = "multi_thread")]
async fn a_below_frontier_reveal_is_credited_from_lane_headroom() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x4Bu8; 8 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;

    let (mut send_a, mut recv_a) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
    let (mut send_b, mut recv_b) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
    read_exact_chunks(&mut recv_a, HARNESS_FLOOR_BYTES).await?;
    read_exact_chunks(&mut recv_b, HARNESS_FLOOR_BYTES).await?;

    // The fast sibling anchors and pays its delivered chunk with a DEEP index,
    // advancing the lane frontier to 5. Reading its next chunk confirms the
    // advance landed before B pays below it — so B's reveal is unambiguously
    // below the frontier, with several chunks of paid headroom behind it.
    open_chain(
        &mut send_a,
        &signer,
        chain_root(),
        RATE_PER_MB,
        U256::ZERO,
        0,
    )
    .await?;
    release(&mut send_a, 5).await?;
    read_exact_chunks(&mut recv_a, HARNESS_INTERVAL_BYTES).await?;

    // B anchors. The anchor is a metering voucher, so it takes none of the
    // headroom the sibling's reveal opened, and B stays parked on its first
    // chunk.
    open_chain(
        &mut send_b,
        &signer,
        chain_root(),
        RATE_PER_MB,
        U256::ZERO,
        0,
    )
    .await?;
    assert_parked_awaiting_voucher(&mut recv_b).await?;

    // B pays each chunk with a BELOW-frontier reveal. Each folds nothing, but
    // the lane has been paid for these bytes, so the node must credit it and
    // reopen the window: B reads its second chunk, then its third.
    release(&mut send_b, 3).await?;
    read_exact_chunks(&mut recv_b, HARNESS_INTERVAL_BYTES).await?;
    release(&mut send_b, 4).await?;
    read_exact_chunks(&mut recv_b, HARNESS_INTERVAL_BYTES).await?;

    // Billing is a MAXIMUM over the streams, never a sum: the deepest index wins,
    // and the benign below-frontier reveal took no new money.
    let lane = store
        .get(lane_key(signer.address()))?
        .ok_or_else(|| anyhow::anyhow!("lane row missing"))?;
    anyhow::ensure!(
        lane.chain().verified_index == 5,
        "the lane stays at the deepest index proved, got {}",
        lane.chain().verified_index
    );
    anyhow::ensure!(
        lane.owed() == U256::from(5 * RATE_PER_MB),
        "the below-frontier reveals must take no new money: {}",
        lane.owed()
    );

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A sibling's rollover must not take the credit that a reveal on a retired
/// root is owed.
///
/// A payer rolls the lane when the chain is spent, and the rollover voucher
/// folds every reveal the payer released — including one that a sibling stream
/// carries and the node has not read yet. That reveal then lands under a
/// retired root: it folds nothing, and the node can only pay its stream from
/// lane headroom. If the rollover voucher took that headroom for its own
/// stream's outstanding chunk, the sibling would wait for a proof the payer
/// never sends, and its stream would die when its proof wait faults.
///
/// Stream X anchors the first chain and pays one chunk with index 1. Stream Y
/// anchors the same chain. X then rolls to a second chain with a voucher that
/// folds index 2, which only Y carries. X must stay parked: the rollover is a
/// metering voucher and pays no whole chunk. Y's index 2 then lands on the
/// retired root and must credit Y at once, and X pays its own chunk with index 1
/// on the new chain.
#[tokio::test(flavor = "multi_thread")]
async fn a_sibling_roll_does_not_take_a_retired_reveals_credit() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x4Cu8; 8 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;

    let (mut send_x, mut recv_x) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
    let (mut send_y, mut recv_y) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
    read_exact_chunks(&mut recv_x, HARNESS_FLOOR_BYTES).await?;
    read_exact_chunks(&mut recv_y, HARNESS_FLOOR_BYTES).await?;

    // X anchors the first chain and pays its chunk with index 1.
    open_chain(
        &mut send_x,
        &signer,
        chain_root(),
        RATE_PER_MB,
        U256::ZERO,
        0,
    )
    .await?;
    release(&mut send_x, 1).await?;
    read_exact_chunks(&mut recv_x, HARNESS_INTERVAL_BYTES).await?;

    // Y anchors the same chain. The lane holds no headroom, so Y stays parked.
    open_chain(
        &mut send_y,
        &signer,
        chain_root(),
        RATE_PER_MB,
        U256::ZERO,
        0,
    )
    .await?;
    assert_parked_awaiting_voucher(&mut recv_y).await?;

    // X rolls to the second chain. The rollover folds index 2 of the first
    // chain — the reveal Y is about to send — so the lane watermark reaches two
    // chunks. The rollover pays no whole chunk, so X stays parked.
    open_chain(
        &mut send_x,
        &signer,
        rolled_root(),
        RATE_PER_MB,
        min_payment(2 * HARNESS_INTERVAL_BYTES, RATE_PER_MB),
        2 * HARNESS_INTERVAL_BYTES,
    )
    .await?;
    assert_parked_awaiting_voucher(&mut recv_x).await?;
    let deadline = Instant::now() + Duration::from_secs(10);
    loop {
        let lane = store
            .get(lane_key(signer.address()))?
            .ok_or_else(|| anyhow::anyhow!("lane row missing"))?;
        if lane.chain().chain_root == rolled_root() {
            break;
        }
        anyhow::ensure!(
            Instant::now() < deadline,
            "the lane never adopted the rolled root"
        );
        tokio::time::sleep(Duration::from_millis(20)).await;
    }

    // Y sends index 2 on the retired root. It folds nothing, but the rollover
    // already put its money on the lane, so the node must credit Y from that
    // headroom at once — well inside the node's proof wait.
    release(&mut send_y, 2).await?;
    tokio::time::timeout(
        Duration::from_secs(3),
        read_exact_chunks(&mut recv_y, HARNESS_INTERVAL_BYTES),
    )
    .await
    .map_err(|_| anyhow::anyhow!("Y's retired reveal was not credited"))??;

    // X pays its own chunk with index 1 on the new chain.
    release_from(&mut send_x, ROLLED_SEED, 1).await?;
    read_exact_chunks(&mut recv_x, HARNESS_INTERVAL_BYTES).await?;

    // The lane is owed the two folded chunks plus one reveal on the new chain.
    let lane = store
        .get(lane_key(signer.address()))?
        .ok_or_else(|| anyhow::anyhow!("lane row missing"))?;
    anyhow::ensure!(
        lane.chain().chain_root == rolled_root() && lane.chain().verified_index == 1,
        "the lane meters the rolled chain at index 1"
    );
    anyhow::ensure!(
        lane.owed() == U256::from(3 * RATE_PER_MB),
        "three chunks at the quoted rate: {}",
        lane.owed()
    );

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1669: with the ramp enabled (a non-zero `credit_ramp_divisor`), a stream that
/// has paid nothing is served only the floor (one chunk plus the payer's verify
/// lag) and then parks: the stop-and-wait cadence. `credit_max` being large
/// makes no difference at `paid = 0`: the window is `ramped_credit_window`
/// clamped to the floor until payment clears it.
#[tokio::test(flavor = "multi_thread")]
async fn unpaid_stream_is_served_only_the_floor_then_pauses() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x22u8; 16 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (_send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
    // Exactly the ramp floor, then a park.
    read_exact_chunks(&mut recv, HARNESS_FLOOR_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv).await?;

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1669: as cumulative `paid` advances, the window ramps past the floor once
/// `paid` clears `credit_ramp_divisor * floor`. With `credit_ramp_divisor = 1`
/// the window is `max(paid, floor)`, where the floor is one interval plus the
/// verify lag: after the first interval is paid the window is still pinned at
/// the floor (`paid` is below it), so the server delivers one further interval.
/// After the SECOND interval is paid the window is `paid`, two intervals, and
/// the server delivers nearly two further intervals in one pass before it parks
/// again: the observable widening this test asserts.
#[tokio::test(flavor = "multi_thread")]
async fn paying_grows_the_window_to_paid_over_divisor() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    let payload = vec![0x33u8; 16 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 1).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (mut send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    // Round 1: floor only (paid == 0 during this delivery pass).
    read_exact_chunks(&mut recv, HARNESS_FLOOR_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv).await?;
    pay_cumulative(&mut send, &signer, HARNESS_INTERVAL_BYTES).await?;

    // Round 2: still floor-width. `paid` is one interval, below the floor at
    // divisor 1, so one more interval goes out.
    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv).await?;
    pay_cumulative(&mut send, &signer, 2 * HARNESS_INTERVAL_BYTES).await?;

    // Round 3: `paid` is two intervals, past the floor, so the window is
    // `paid / 1`. The server fills it from the floor's lag up to two intervals
    // past `paid` in this pass before parking again: the widened window.
    read_exact_chunks(&mut recv, 2 * HARNESS_INTERVAL_BYTES - HARNESS_LAG_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv).await?;

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Pay a `[0, +range)` stream on `conn` to its `StreamEnd`: each interval as
/// it lands, and the remainder when the node parks. `paid` is the lane's
/// cumulative wire bytes before the stream; returns it after.
async fn pay_range_to_end(
    conn: &Connection,
    hash: [u8; 32],
    ext: &StreamRequestExt,
    signer: &PrivateKeySigner,
    range: u64,
    mut paid: u64,
) -> anyhow::Result<u64> {
    let (mut send, mut recv) = open_paid_range_stream(conn, hash, Some(ext), 0, range).await?;
    // The loop reads the stream again after a timeout, so the read must be cancel-safe.
    let mut reader = BufferedClientReader::default();
    let mut received = paid;
    loop {
        match tokio::time::timeout(Duration::from_secs(5), reader.read(&mut recv)).await {
            Ok(msg) => match msg? {
                ClientMessage::ChunkData(chunk) => {
                    received = received.saturating_add(chunk.bytes().len() as u64);
                    if received.saturating_sub(paid) >= HARNESS_INTERVAL_BYTES {
                        pay_cumulative(&mut send, signer, received).await?;
                        paid = received;
                    }
                }
                ClientMessage::StreamEnd => break,
                other => anyhow::bail!("expected ChunkData or StreamEnd, got {other:?}"),
            },
            Err(_elapsed) => {
                anyhow::ensure!(received > paid, "the stream stalled with nothing owed");
                pay_cumulative(&mut send, signer, received).await?;
                paid = received;
            }
        }
    }
    let _ = send.finish();
    Ok(paid)
}

/// Read what an unpaid whole-blob stream on `conn` receives before the node
/// parks it for a voucher. Returns the stream so the caller controls its end.
async fn read_unpaid_opening(
    conn: &Connection,
    hash: [u8; 32],
    ext: &StreamRequestExt,
) -> anyhow::Result<(u64, SendStream, RecvStream)> {
    let (send, mut recv) = open_paid_stream(conn, hash, Some(ext)).await?;
    let mut unpaid: u64 = 0;
    while let Ok(msg) =
        tokio::time::timeout(Duration::from_secs(2), read_client_msg(&mut recv)).await
    {
        match msg? {
            ClientMessage::ChunkData(chunk) => {
                unpaid = unpaid.saturating_add(chunk.bytes().len() as u64);
            }
            other => anyhow::bail!("expected ChunkData, got {other:?}"),
        }
    }
    Ok((unpaid, send, recv))
}

/// #2168: a stream that ends fully paid returns its paid content to its lane's
/// ramp-credit pool, so the payer's next request on the lane opens at the
/// window the first one earned instead of at the floor (ADR 003 §Credit
/// window). Stream 1 pays for a 4 MiB range to its `StreamEnd`. Stream 2 then
/// asks for the whole blob and pays nothing: at divisor 1 it still receives
/// about 4 MiB before it parks, where a fresh lane receives the floor
/// (`unpaid_stream_is_served_only_the_floor_then_pauses`).
#[tokio::test(flavor = "multi_thread")]
async fn a_back_to_back_stream_opens_at_the_lanes_banked_ramp() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    const FIRST_RANGE: u64 = 4 * HARNESS_INTERVAL_BYTES;
    let payload = vec![0x5Au8; 16 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 1).await?;
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;

    let paid = pay_range_to_end(&conn, *hash.as_bytes(), &ext, &signer, FIRST_RANGE, 0).await?;
    anyhow::ensure!(paid >= FIRST_RANGE, "stream 1 paid {paid} wire bytes");

    // Stream 2: the same lane, no voucher. It opens at the banked window, so it
    // receives the first range's content before it parks, and never more than
    // that window plus the one frame that crosses it.
    let (unpaid, _send, _recv) = read_unpaid_opening(&conn, *hash.as_bytes(), &ext).await?;
    anyhow::ensure!(
        unpaid >= FIRST_RANGE,
        "stream 2 received {unpaid} unpaid wire bytes; the banked ramp opens {FIRST_RANGE}"
    );
    anyhow::ensure!(
        unpaid <= paid.saturating_add(HARNESS_INTERVAL_BYTES),
        "stream 2 received {unpaid} unpaid wire bytes past its {paid}-byte window"
    );

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #2168: a stream that ends unpaid forfeits the ramp credit it carried, so a
/// payer that paid once cannot open a wide window on stream after stream it
/// abandons. Stream 2 opens at the banked window and walks away unpaid; stream 3
/// then opens at the floor.
#[tokio::test(flavor = "multi_thread")]
async fn an_abandoned_stream_forfeits_its_lanes_ramp() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    const FIRST_RANGE: u64 = 4 * HARNESS_INTERVAL_BYTES;
    let payload = vec![0x5Cu8; 16 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task, metrics) =
        spawn_pipelined_server_with_metrics(cache, Arc::clone(&store), CREDIT_MAX, 1).await?;
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;

    pay_range_to_end(&conn, *hash.as_bytes(), &ext, &signer, FIRST_RANGE, 0).await?;
    let (unpaid, mut send, mut recv) = read_unpaid_opening(&conn, *hash.as_bytes(), &ext).await?;
    anyhow::ensure!(
        unpaid >= FIRST_RANGE,
        "stream 2 opened at {unpaid} wire bytes"
    );

    // Walk away from stream 2, then wait for the node to end it.
    let ended = || -> anyhow::Result<u64> {
        Ok(
            counter(&metrics, "decdn_serve_stream_client_declined_total")?
                + counter(&metrics, "decdn_serve_stream_client_abandoned_total")?,
        )
    };
    let before = ended()?;
    let _ = send.reset(0u32.into());
    let _ = recv.stop(0u32.into());
    let deadline = Instant::now() + Duration::from_secs(15);
    while ended()? == before {
        anyhow::ensure!(Instant::now() < deadline, "the node never ended stream 2");
        tokio::time::sleep(Duration::from_millis(20)).await;
    }

    let (unpaid, _send, _recv) = read_unpaid_opening(&conn, *hash.as_bytes(), &ext).await?;
    anyhow::ensure!(
        unpaid == HARNESS_FLOOR_BYTES,
        "stream 3 received {unpaid} unpaid wire bytes; the forfeited lane opens at the floor"
    );

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1669: `credit_ramp_divisor = 0` opens the full `credit_max` ceiling
/// immediately, regardless of `paid` — the flat-window behavior, now opt-in. A
/// client that pays nothing still reads a full `credit_max` ahead of any
/// voucher, and never more than that (the bounded credit exposure).
#[tokio::test(flavor = "multi_thread")]
async fn divisor_zero_serves_the_full_credit_max_immediately() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 8 * 1024 * 1024;
    let payload = vec![0x11u8; 16 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_pipelined_server(cache, Arc::clone(&store), CREDIT_MAX, 0).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (_send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
    // The full ceiling arrives ahead of ANY voucher...
    read_exact_chunks(&mut recv, CREDIT_MAX).await?;
    // ...and not one byte more (exposure bounded to exactly the ceiling).
    assert_parked_awaiting_voucher(&mut recv).await?;

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// ADR 005 §Connection lifetime (#1193): a connection with no active stream is
/// closed by the application layer after `APP_IDLE_TIMEOUT`. A short timeout is
/// injected via `ClientHandlerDeps.idle_timeout` so the test need not wait the production 30s.
/// The client opens no stream, so the server's serve loop is idle from the start
/// and must close it; the close is asserted to be the graceful no-error "idle"
/// close (`APP_ERR_NO_ERROR` + reason `"idle"`), not a fault or transport reset.
#[tokio::test(flavor = "multi_thread")]
async fn idle_connection_is_closed_by_the_app_layer() -> anyhow::Result<()> {
    let (cache, _cache_tmp) = empty_cache().await?;
    let store: Arc<dyn PoolStateStore> = Arc::new(MemoryPoolStateStore::new());

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        |deps| deps.idle_timeout = Some(Duration::from_millis(300)),
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    // No stream is ever opened: the serve loop is idle from the first poll and
    // must close us after the injected 300ms window. The outer 10s bound is
    // generous against CI jitter yet still fails if the idle arm never fires.
    let err = tokio::time::timeout(Duration::from_secs(10), conn.closed())
        .await
        .map_err(|_| anyhow::anyhow!("connection was not idle-closed within 10s"))?;

    ensure_graceful_idle_close(&err)?;

    // The reap must be metered, not just logged at `debug!` — the counter is the
    // operator's only signal for the streamless-keep-alive abuse pattern (#1193).
    // Asserting the exact `name value` line also guards the recorder wiring: a
    // typo'd metric name or a bump of the wrong counter would fail here.
    let encoded = metrics.encode()?;
    anyhow::ensure!(
        metric_line_present(&encoded, "decdn_client_idle_close_total 1"),
        "idle-close must bump decdn_client_idle_close_total; got:\n{encoded}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// ADR 005 §Connection lifetime (#1193): the app-layer idle reaper must (a) NOT
/// close a connection while a stream is still being served, and (b) re-arm from
/// that stream's completion — the two invariants the never-opened-a-stream test
/// above cannot reach. The client opens one stream and parks it mid-request (it
/// sends only the frame's length prefix, so the server blocks in `read_frame`),
/// holding the serve loop's `inflight` non-empty; the connection must survive
/// several idle windows. Completing the frame lets the serve future finish and
/// empties `inflight`; the reaper then re-arms and reaps the now-idle connection.
#[tokio::test(flavor = "multi_thread")]
async fn in_flight_stream_defers_idle_close_then_reaps_on_completion() -> anyhow::Result<()> {
    // Frame-body length promised in the prefix but withheld to park the server's
    // `read_frame`; a single varint byte since 64 < 128.
    const BODY_LEN: u8 = 64;

    let (cache, _cache_tmp) = empty_cache().await?;
    let store: Arc<dyn PoolStateStore> = Arc::new(MemoryPoolStateStore::new());

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let idle = Duration::from_millis(150);
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        |deps| deps.idle_timeout = Some(idle),
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    // Open a stream and send ONLY the frame's length prefix, then withhold the
    // body. The server accepts the stream and parks in `read_frame`'s
    // `read_exact`, so its serve future stays in `inflight` — held there well
    // within the 5s request-read timeout.
    let (mut send, _recv) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi: {e}"))?;
    send.write_all(&[BODY_LEN])
        .await
        .map_err(|e| anyhow::anyhow!("write frame len: {e}"))?;

    // (a) Gating: with a stream in flight the reaper is disabled, so the
    // connection must NOT be closed even after several idle windows. A resolved
    // `closed()` here means the `inflight.is_empty()` gate is broken and a live
    // stream was truncated. The `idle * 5` bound is well past the idle window yet
    // far short of the 5s read timeout, so a pass is the gate holding open, not
    // the parked read expiring.
    let premature = tokio::time::timeout(idle * 5, conn.closed()).await;
    anyhow::ensure!(
        premature.is_err(),
        "connection was idle-closed while a stream was in flight: {premature:?}"
    );

    // Complete the frame; the 64 bytes decode to no valid request, so the server
    // resets the stream and its serve future returns, emptying `inflight`.
    send.write_all(&[0xFFu8; BODY_LEN as usize])
        .await
        .map_err(|e| anyhow::anyhow!("write frame body: {e}"))?;

    // (b) Re-arm: from that completion the idle clock restarts and must reap the
    // now-streamless connection with the same graceful no-error "idle" close.
    let err = tokio::time::timeout(Duration::from_secs(10), conn.closed())
        .await
        .map_err(|_| {
            anyhow::anyhow!("connection was not idle-closed after the stream completed")
        })?;
    ensure_graceful_idle_close(&err)?;

    // Exactly one connection was reaped, and only after the stream finished.
    let encoded = metrics.encode()?;
    anyhow::ensure!(
        metric_line_present(&encoded, "decdn_client_idle_close_total 1"),
        "post-stream idle-close must bump decdn_client_idle_close_total; got:\n{encoded}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// One cached blob exposed by an [`IdleFixture`].
#[derive(Clone, Copy)]
struct IdleBlob {
    hash: Hash,
    /// Bao wire bytes the whole-blob delivery emits (content plus interleaved
    /// proof, ADR 038) — what a raw client must read before the server parks on
    /// the closing voucher, and what that voucher must cover.
    wire_bytes: u64,
}

/// A server serving one or more blobs under an injected idle window, plus
/// everything a raw client needs to drive paid deliveries against it — the
/// shared fixture for the #1261 and #1287 idle-close guard tests below.
struct IdleFixture {
    target: EndpointAddr,
    /// The lane's authorized client — the key a voucher must recover to.
    client_signer: Arc<PrivateKeySigner>,
    store: Arc<MemoryPoolStateStore>,
    blobs: Vec<IdleBlob>,
    metrics: Arc<Metrics>,
    server_ep: Endpoint,
    server_task: tokio::task::JoinHandle<()>,
    _cache_tmp: tempfile::TempDir,
}

impl IdleFixture {
    fn blob(&self, index: usize) -> anyhow::Result<IdleBlob> {
        self.blobs
            .get(index)
            .copied()
            .ok_or_else(|| anyhow::anyhow!("idle fixture has no blob at index {index}"))
    }
}

/// Build an [`IdleFixture`] serving `payload` with `idle` injected as the
/// app-layer idle-close window (so a test need not wait the production 30s).
async fn idle_fixture(payload: &[u8], idle: Duration) -> anyhow::Result<IdleFixture> {
    let (cache, hash, cache_tmp) = cache_with_blob(payload).await?;

    idle_fixture_with_cache(
        cache,
        vec![IdleBlob {
            hash,
            wire_bytes: support::bao_wire_len_whole(payload.len() as u64),
        }],
        cache_tmp,
        idle,
    )
    .await
}

/// Build an [`IdleFixture`] serving two distinct blobs on the same connection.
async fn idle_fixture_with_two_blobs(
    a: &[u8],
    b: &[u8],
    idle: Duration,
) -> anyhow::Result<IdleFixture> {
    let (cache, hash_a, hash_b, cache_tmp) = cache_with_two_blobs(a, b).await?;
    idle_fixture_with_cache(
        cache,
        vec![
            IdleBlob {
                hash: hash_a,
                wire_bytes: support::bao_wire_len_whole(a.len() as u64),
            },
            IdleBlob {
                hash: hash_b,
                wire_bytes: support::bao_wire_len_whole(b.len() as u64),
            },
        ],
        cache_tmp,
        idle,
    )
    .await
}

/// Wire an idle-close handler around a pre-populated cache without duplicating
/// the loopback endpoint and payment pool setup.
async fn idle_fixture_with_cache(
    cache: CacheEngine,
    blobs: Vec<IdleBlob>,
    cache_tmp: tempfile::TempDir,
    idle: Duration,
) -> anyhow::Result<IdleFixture> {
    let client_signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        U256::from(10_000_000u64),
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
        |deps| deps.idle_timeout = Some(idle),
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    Ok(IdleFixture {
        target: EndpointAddr::new(server_id).with_ip_addr(server_addr),
        client_signer,
        store,
        blobs,
        metrics,
        server_ep,
        server_task,
        _cache_tmp: cache_tmp,
    })
}

/// A raw `cdn/client/v1` delivery parked at its closing-voucher exchange: every
/// chunk has been read, and the server is blocked in `collect_voucher` awaiting
/// payment — so its `serve_stream` future is genuinely held in the serve loop's
/// `inflight` set, for as long as the test declines to pay.
struct StalledDelivery {
    send: SendStream,
    recv: RecvStream,
    /// Wire bytes read, and therefore what the closing voucher must cover.
    wire_bytes: u64,
}

/// Cumulative lane state used to settle a sequence of raw stalled streams.
#[derive(Clone, Copy, Default)]
struct VoucherTotals {
    wire_bytes: u64,
    amount: U256,
}

/// Drive a real paid delivery up to — but not through — its closing voucher.
///
/// The honest requester (`stream_fetch`) owns its connection internally, so a
/// caller cannot watch the server idle-close it, and it pays the moment a
/// voucher is due. This reimplements the receive loop so the test keeps the
/// connection AND chooses when to pay: it sends the `StreamRequest`, reads the
/// signed `StreamResponse` and every `ChunkData` of the whole blob, and stops
/// there. `expected_wire` bytes is the whole delivery, so with a payload well
/// under one chunk the server has exactly one (closing) voucher left
/// to collect and is now parked reading it — the stall is a protocol-level
/// rendezvous, not a race, and it holds until the test pays or the handler's
/// proof wait ends it. The client holds every byte, so the stream adds no
/// transport progress: the wait ends after 10s (`VOUCHER_READ_TIMEOUT`) when the
/// connection carries nothing else, and up to 30s while sibling streams on it
/// keep sending.
async fn stall_delivery_at_closing_voucher(
    conn: &Connection,
    hash: [u8; 32],
    expected_wire: u64,
    ext: Option<&StreamRequestExt>,
) -> anyhow::Result<StalledDelivery> {
    let (mut send, mut recv) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi: {e}"))?;

    let req = StreamRequest {
        hash,
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x0012_61a0,
    };
    let payload =
        encode_stream_request(&req, ext).map_err(|e| anyhow::anyhow!("encode request: {e}"))?;
    write_frame(&mut send, &payload)
        .await
        .map_err(|e| anyhow::anyhow!("write request: {e}"))?;

    let (resp, resp_ext) = read_stream_response(&mut recv).await?;
    anyhow::ensure!(resp.body.ok, "delivery refused: {:?}", resp_ext.error);

    let mut wire_bytes: u64 = 0;
    while wire_bytes < expected_wire {
        match read_client_msg(&mut recv).await? {
            ClientMessage::ChunkData(chunk) => {
                wire_bytes = wire_bytes.saturating_add(chunk.bytes().len() as u64);
            }
            other => anyhow::bail!("expected ChunkData mid-delivery, got {other:?}"),
        }
    }
    anyhow::ensure!(
        wire_bytes == expected_wire,
        "read {wire_bytes} wire bytes, expected exactly {expected_wire}"
    );

    Ok(StalledDelivery {
        send,
        recv,
        wire_bytes,
    })
}

impl StalledDelivery {
    /// Pay the closing voucher and read the delivery out to its `StreamEnd`,
    /// releasing the server's `serve_stream` future. Returns the instant the
    /// CLIENT saw `StreamEnd` — a lower bound on the server-side stream close the
    /// idle clock is required to count from — plus the new cumulative totals.
    async fn pay_and_finish(
        mut self,
        signer: &PrivateKeySigner,
        prior: VoucherTotals,
    ) -> anyhow::Result<(Instant, VoucherTotals)> {
        let amount_delta = min_payment(self.wire_bytes, RATE_PER_MB);
        let settled = VoucherTotals {
            wire_bytes: prior
                .wire_bytes
                .checked_add(self.wire_bytes)
                .ok_or_else(|| anyhow::anyhow!("voucher wire-byte total overflow"))?,
            amount: prior
                .amount
                .checked_add(amount_delta)
                .ok_or_else(|| anyhow::anyhow!("voucher amount overflow"))?,
        };
        let voucher = Voucher {
            pool_id: pool_id(),
            signer: signer.address(),
            provider: operator_addr(),
            // Exactly the advertised-rate minimum for the bytes served, which
            // clears the handler's per-delta `verify_rate` (1% tolerance). The
            // node applies no cumulative rate-floor check — the delivery floor
            // is a redemption-time credit clamp only.
            amount: settled.amount,
            bytes_delivered: U256::from(settled.wire_bytes),
            chain_root: B256::ZERO,
            chunk_price: U256::ZERO,
        }
        .sign(signer, &payment_domain())
        .map_err(|e| anyhow::anyhow!("sign voucher: {e}"))?;
        write_client_msg(
            &mut self.send,
            &ClientMessage::Voucher(signed_to_wire_voucher(&voucher)?),
        )
        .await?;

        // Acceptance is implicit — the server sends no ack and proceeds straight
        // to `StreamEnd` once the closing voucher clears.
        match read_client_msg(&mut self.recv).await? {
            ClientMessage::StreamEnd => {}
            other => anyhow::bail!("expected StreamEnd, got {other:?}"),
        }
        Ok((Instant::now(), settled))
    }

    /// Sign and send a voucher carrying an explicit cumulative
    /// `(bytes_delivered, amount)`, then read and return the node's next message.
    /// Unlike [`Self::pay_and_finish`] this hands the caller an arbitrary
    /// watermark, so a test can inject a malformed or out-of-order voucher and
    /// assert how the node rejects it.
    async fn send_cumulative_voucher(
        &mut self,
        signer: &PrivateKeySigner,
        bytes_delivered: u64,
        amount: U256,
    ) -> anyhow::Result<ClientMessage> {
        let voucher = Voucher {
            pool_id: pool_id(),
            signer: signer.address(),
            provider: operator_addr(),
            amount,
            bytes_delivered: U256::from(bytes_delivered),
            chain_root: B256::ZERO,
            chunk_price: U256::ZERO,
        }
        .sign(signer, &payment_domain())
        .map_err(|e| anyhow::anyhow!("sign voucher: {e}"))?;
        write_client_msg(
            &mut self.send,
            &ClientMessage::Voucher(signed_to_wire_voucher(&voucher)?),
        )
        .await?;
        read_client_msg(&mut self.recv).await
    }
}

/// Drive a raw `cdn/client/v1` request expecting a pre-serve refusal: send the
/// `StreamRequest` and read only the `StreamResponse` — a refused request never
/// emits `ChunkData`, so there is nothing to stall on. Sibling of
/// [`stall_delivery_at_closing_voucher`] for gates (like the per-lane admission
/// cap) that refuse before delivery begins.
async fn open_expecting_refusal(
    conn: &Connection,
    hash: [u8; 32],
    ext: Option<&StreamRequestExt>,
) -> anyhow::Result<(
    decdn_protocol::client::StreamResponse,
    decdn_protocol::client::StreamResponseExt,
)> {
    let (mut send, mut recv) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi: {e}"))?;

    let req = StreamRequest {
        hash,
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x0012_61a0,
    };
    let payload =
        encode_stream_request(&req, ext).map_err(|e| anyhow::anyhow!("encode request: {e}"))?;
    write_frame(&mut send, &payload)
        .await
        .map_err(|e| anyhow::anyhow!("write request: {e}"))?;

    read_stream_response(&mut recv).await
}

/// Open two same-lane streams as concurrently as the harness allows: both
/// `StreamRequest`s are sent before either `StreamResponse` is read, so the
/// server genuinely sees the two opens overlapping rather than sequenced by
/// this test's own await order. Sibling of [`stall_delivery_at_closing_voucher`]
/// and [`open_expecting_refusal`], for the pool ceiling's concurrent-admit TOCTOU
/// test.
async fn race_two_same_lane_opens(
    conn: &Connection,
    hash_a: [u8; 32],
    hash_b: [u8; 32],
    ext: &StreamRequestExt,
) -> anyhow::Result<(bool, bool)> {
    let (mut send_a, mut recv_a) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi a: {e}"))?;
    let (mut send_b, mut recv_b) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi b: {e}"))?;

    let req_a = StreamRequest {
        hash: hash_a,
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x0012_61a0,
    };
    let req_b = StreamRequest {
        hash: hash_b,
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x0012_61a0,
    };
    let payload_a = encode_stream_request(&req_a, Some(ext))
        .map_err(|e| anyhow::anyhow!("encode request a: {e}"))?;
    let payload_b = encode_stream_request(&req_b, Some(ext))
        .map_err(|e| anyhow::anyhow!("encode request b: {e}"))?;

    // Both requests are in flight before either response is read.
    write_frame(&mut send_a, &payload_a)
        .await
        .map_err(|e| anyhow::anyhow!("write request a: {e}"))?;
    write_frame(&mut send_b, &payload_b)
        .await
        .map_err(|e| anyhow::anyhow!("write request b: {e}"))?;

    let ok_a = match read_client_msg(&mut recv_a).await? {
        ClientMessage::StreamResponse(resp) => resp.body.ok,
        other => anyhow::bail!("expected a StreamResponse for a, got {other:?}"),
    };
    let ok_b = match read_client_msg(&mut recv_b).await? {
        ClientMessage::StreamResponse(resp) => resp.body.ok,
        other => anyhow::bail!("expected a StreamResponse for b, got {other:?}"),
    };

    Ok((ok_a, ok_b))
}

/// Assert `err` is the handler's graceful app-layer idle close: `APP_ERR_NO_ERROR`
/// (0x00) with reason `"idle"`, not a fault code or a transport reset.
fn ensure_graceful_idle_close(err: &ConnectionError) -> anyhow::Result<()> {
    match err {
        ConnectionError::ApplicationClosed(ac) => {
            anyhow::ensure!(
                ac.error_code.into_inner() == 0,
                "idle close must use the no-error code, got {}",
                ac.error_code.into_inner()
            );
            anyhow::ensure!(
                ac.reason.as_ref() == b"idle",
                "idle close reason: {:?}",
                ac.reason
            );
            Ok(())
        }
        other => anyhow::bail!("expected a graceful application idle-close, got {other:?}"),
    }
}

/// ADR 005 §Connection lifetime (#1261): a stalled paid delivery survives the
/// idle window and then settles at the exact byte count. The sibling test above
/// already pins the `inflight.is_empty()` gate itself (it kills the same
/// delete/invert mutations); what is new here is the PARK POINT and the
/// settlement assertions — the server sits past the whole blob in
/// `collect_voucher`, with every byte on the wire and payment pending, so this
/// is the test that fails if the deferral is ever narrowed to the request-read
/// phase alone (e.g. by moving the reaper inside `serve_stream`).
#[tokio::test(flavor = "multi_thread")]
async fn active_delivery_stream_defers_idle_close() -> anyhow::Result<()> {
    // 64 KiB: far under the fixed voucher accounting interval, so the delivery
    // has exactly one (closing) voucher and the park point is unambiguous.
    let payload = vec![0x3Du8; 64 * 1024];
    let idle = Duration::from_millis(150);
    let fx = idle_fixture(&payload, idle).await?;
    let blob = fx.blob(0)?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;
    let stalled = stall_delivery_at_closing_voucher(
        &conn,
        *blob.hash.as_bytes(),
        blob.wire_bytes,
        Some(&ext),
    )
    .await?;

    // The reaper is disabled while the stream is in flight: no close, however many
    // idle windows pass. `idle * 5` is well past the window yet far short of the
    // 10s no-progress proof wait, so a pass is the gate holding, not the park
    // expiring.
    let premature = tokio::time::timeout(idle * 5, conn.closed()).await;
    anyhow::ensure!(
        premature.is_err(),
        "connection was idle-closed while a paid delivery was in flight: {premature:?}"
    );

    // Delivery completes on resume, and the lane advanced by exactly the bytes
    // that were already on the wire during the stall — proof the stall did not
    // corrupt or truncate the delivery it was holding open.
    let (_completed_at, _totals) = stalled
        .pay_and_finish(&fx.client_signer, VoucherTotals::default())
        .await?;
    let persisted = fx.store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(blob.wire_bytes),
        "bytes_delivered: {} (expected {})",
        only.last_bytes_delivered(),
        blob.wire_bytes
    );

    drop(conn);
    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// ADR 005 §Connection lifetime (#1261): the idle clock counts from the LAST
/// STREAM'S CLOSE, not from connection accept. The serve loop builds a fresh
/// `tokio::time::sleep(idle_timeout)` on every iteration; hoisting it into a
/// single `tokio::pin!`'d binding before the loop — a plausible "avoid
/// re-allocating a timer" refactor — would silently make the countdown run from
/// accept, and every other idle test would stay green.
///
/// This one holds a real delivery in flight for `idle * 3`, so a timer armed at
/// connection start has long since expired by the time the stream closes. The
/// close must then arrive a further ~`idle` AFTER completion. Under the hoisted
/// variant the already-expired timer is merely gated off by `is_empty()`, so it
/// fires on the first iteration after `inflight` drains — landing within a
/// round-trip of completion, an order of magnitude under the floor asserted
/// below.
#[tokio::test(flavor = "multi_thread")]
async fn idle_clock_re_arms_from_last_stream_close() -> anyhow::Result<()> {
    let payload = vec![0x4Eu8; 64 * 1024];
    let idle = Duration::from_millis(400);
    let fx = idle_fixture(&payload, idle).await?;
    let blob = fx.blob(0)?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;
    let stalled = stall_delivery_at_closing_voucher(
        &conn,
        *blob.hash.as_bytes(),
        blob.wire_bytes,
        Some(&ext),
    )
    .await?;

    // Park past `connect + idle` so the two candidate origins are unambiguously
    // separated: a clock counting from accept is already due when we pay.
    tokio::time::sleep(idle * 3).await;
    let (completed_at, _totals) = stalled
        .pay_and_finish(&fx.client_signer, VoucherTotals::default())
        .await?;

    let err = tokio::time::timeout(Duration::from_secs(10), conn.closed())
        .await
        .map_err(|_| {
            anyhow::anyhow!("connection was not idle-closed after the stream completed")
        })?;
    // Both endpoints of this measurement are stamped client-side, so the two
    // loopback flight times largely cancel. What does NOT cancel is that the
    // server writes `StreamEnd` BEFORE `serve_stream` returns, so it re-arms
    // strictly after the instant `completed_at` records: the interval is
    // `idle + (re-arm - StreamEnd write)`, i.e. it can only over-report the
    // server's own delay. That direction is what makes the floor below safe.
    let since_completion = completed_at.elapsed();
    ensure_graceful_idle_close(&err)?;

    // The ORDERING property, with slack for scheduling jitter on a loaded runner:
    // the close is a fresh window measured from the stream's close, not the
    // already-elapsed remainder of a window armed at connection start (which would
    // land within a round-trip of completion, an order of magnitude under this floor).
    let floor = idle.mul_f64(0.8);
    anyhow::ensure!(
        since_completion >= floor,
        "idle clock did not re-arm from the stream's close: closed {since_completion:?} after \
         completion, expected at least {floor:?} (a hoisted timer counts from connection accept)"
    );

    anyhow::ensure!(
        metric_line_present(&fx.metrics.encode()?, "decdn_client_idle_close_total 1"),
        "the re-armed reap must bump decdn_client_idle_close_total"
    );

    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// ADR 005 §Connection lifetime (#1287): every completed stream must re-arm
/// the idle clock, not only the first one. Three paid deliveries finish on the
/// same connection, with each successor starting before the previous fresh
/// idle window expires. The connection survives every cadence, then one final
/// uninterrupted idle window reaps it exactly once.
#[tokio::test(flavor = "multi_thread")]
async fn idle_clock_re_arms_after_each_completed_stream() -> anyhow::Result<()> {
    let payload = vec![0x6Au8; 64 * 1024];
    let idle = Duration::from_secs(1);
    let activity_cadence = idle.mul_f64(0.6);
    let fx = idle_fixture(&payload, idle).await?;
    let blob = fx.blob(0)?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;
    let mut totals = VoucherTotals::default();
    let mut final_completion = Instant::now();

    for round in 1..=3 {
        let stalled = stall_delivery_at_closing_voucher(
            &conn,
            *blob.hash.as_bytes(),
            blob.wire_bytes,
            Some(&ext),
        )
        .await?;
        let (completed_at, settled) = stalled.pay_and_finish(&fx.client_signer, totals).await?;
        totals = settled;
        final_completion = completed_at;

        if round < 3 {
            let premature = tokio::time::timeout(activity_cadence, conn.closed()).await;
            anyhow::ensure!(
                premature.is_err(),
                "connection closed after re-arm round {round}, before the next activity: \
                 {premature:?}"
            );
        }
    }

    let err = tokio::time::timeout(Duration::from_secs(10), conn.closed())
        .await
        .map_err(|_| anyhow::anyhow!("connection was not reaped after the final idle window"))?;
    // The server re-arms only after writing StreamEnd, so measuring from the
    // client's read can only over-report the server-side idle delay.
    let since_completion = final_completion.elapsed();
    ensure_graceful_idle_close(&err)?;
    let floor = idle.mul_f64(0.8);
    anyhow::ensure!(
        since_completion >= floor,
        "final idle window was not freshly armed: closed {since_completion:?} after completion, \
         expected at least {floor:?}"
    );

    let persisted = fx.store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(totals.wire_bytes),
        "bytes_delivered: {} (expected {})",
        only.last_bytes_delivered(),
        totals.wire_bytes
    );
    anyhow::ensure!(
        metric_line_present(&fx.metrics.encode()?, "decdn_client_idle_close_total 1"),
        "repeated re-arms must end in exactly one metered idle-close"
    );

    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// ADR 005 §Connection lifetime (#1287): draining one completed future from
/// a connection with two concurrent paid streams must not arm the idle reaper.
/// Only after BOTH streams finish may the fresh idle window begin.
#[tokio::test(flavor = "multi_thread")]
async fn concurrent_streams_all_finish_before_idle_clock_arms() -> anyhow::Result<()> {
    let payload_a = vec![0x71u8; 48 * 1024];
    let payload_b = vec![0x82u8; 64 * 1024];
    let idle = Duration::from_millis(300);
    let fx = idle_fixture_with_two_blobs(&payload_a, &payload_b, idle).await?;
    let blob_a = fx.blob(0)?;
    let blob_b = fx.blob(1)?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;
    let stalled_a = stall_delivery_at_closing_voucher(
        &conn,
        *blob_a.hash.as_bytes(),
        blob_a.wire_bytes,
        Some(&ext),
    )
    .await?;
    let stalled_b = stall_delivery_at_closing_voucher(
        &conn,
        *blob_b.hash.as_bytes(),
        blob_b.wire_bytes,
        Some(&ext),
    )
    .await?;

    let (_first_completed_at, totals) = stalled_a
        .pay_and_finish(&fx.client_signer, VoucherTotals::default())
        .await?;

    // One completed future may be drained, but the second delivery remains in
    // `inflight`; surviving three whole windows distinguishes `is_empty()` from
    // a broken one-entry/last-completed interpretation.
    let premature = tokio::time::timeout(idle * 3, conn.closed()).await;
    anyhow::ensure!(
        premature.is_err(),
        "connection was idle-closed while the second stream was still in flight: {premature:?}"
    );

    let (second_completed_at, _totals) =
        stalled_b.pay_and_finish(&fx.client_signer, totals).await?;
    let err = tokio::time::timeout(Duration::from_secs(10), conn.closed())
        .await
        .map_err(|_| {
            anyhow::anyhow!("connection was not reaped after both concurrent streams completed")
        })?;
    // The server re-arms only after writing StreamEnd, so measuring from the
    // client's read can only over-report the server-side idle delay.
    let since_completion = second_completed_at.elapsed();
    ensure_graceful_idle_close(&err)?;
    let floor = idle.mul_f64(0.8);
    anyhow::ensure!(
        since_completion >= floor,
        "idle window started before the second stream closed: reaped {since_completion:?} after \
         completion, expected at least {floor:?}"
    );

    let expected_wire_bytes = blob_a
        .wire_bytes
        .checked_add(blob_b.wire_bytes)
        .ok_or_else(|| anyhow::anyhow!("expected wire-byte total overflow"))?;
    let persisted = fx.store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(expected_wire_bytes),
        "persisted bytes: {}, expected {expected_wire_bytes}",
        only.last_bytes_delivered(),
    );
    anyhow::ensure!(
        metric_line_present(&fx.metrics.encode()?, "decdn_client_idle_close_total 1"),
        "the post-concurrency idle reap must be metered exactly once"
    );

    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// ADR 005 §Payment lanes and concurrent streams: two same-lane streams share
/// ONE aggregate byte counter and ONE cumulative-voucher watermark. Two
/// deliveries run on one `(pool_id, signer, provider)` lane — each blob is under
/// a single chunk, so neither stream crosses the 1 MiB
/// `CHUNK_BYTES` boundary alone, but their combined wire bytes do — so
/// the SHARED lane counter is what carries the crossing. Both serve legs sit
/// parked at their closing voucher on the one lane, then settle in the REVERSE of
/// their open order. The node reconstructs each voucher's cumulative
/// `bytes_delivered` from the shared counter plus that stream's own delivered
/// delta, so the final persisted watermark is the exact aggregate no matter which
/// stream is paid first (#1689).
#[tokio::test(flavor = "multi_thread")]
async fn concurrent_same_lane_streams_aggregate_across_the_chunk_boundary() -> anyhow::Result<()> {
    // Each blob is under one chunk, so a single stream yields just one
    // (closing) voucher; their sum clears the interval, so only the shared lane
    // counter crosses the boundary — the aggregate-accounting path under test.
    // Each blob is under ONE chunk on its own, so neither crosses the boundary
    // by itself — but together they do, which is exactly the lane-aggregate
    // accounting under test.
    let payload_a = vec![0x71u8; 768 * 1024];
    let payload_b = vec![0x82u8; 512 * 1024];
    // A generous idle window: the test settles promptly and asserts nothing about
    // the idle reaper, so the clock must never fire while streams are parked.
    let idle = Duration::from_secs(30);
    let fx = idle_fixture_with_two_blobs(&payload_a, &payload_b, idle).await?;
    let blob_a = fx.blob(0)?;
    let blob_b = fx.blob(1)?;

    // The preconditions the test's meaning rests on: each stream stays under one
    // interval (so neither crosses the boundary on its own), yet their aggregate
    // clears it (so the shared counter must).
    anyhow::ensure!(
        blob_a.wire_bytes < CHUNK_BYTES && blob_b.wire_bytes < CHUNK_BYTES,
        "each blob must stay under one chunk: a={}, b={}, chunk={}",
        blob_a.wire_bytes,
        blob_b.wire_bytes,
        CHUNK_BYTES,
    );
    let aggregate_wire = blob_a
        .wire_bytes
        .checked_add(blob_b.wire_bytes)
        .ok_or_else(|| anyhow::anyhow!("aggregate wire-byte overflow"))?;
    anyhow::ensure!(
        aggregate_wire > CHUNK_BYTES,
        "the two streams must aggregate past one interval: {aggregate_wire} <= {CHUNK_BYTES}",
    );

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;

    // Both streams open on the one connection and fully deliver: every chunk of
    // both blobs is on the wire (each blob sits inside the one-interval credit
    // window) before either voucher is paid, so the two serve legs are
    // simultaneously parked at their closing-voucher exchange on the shared lane.
    let stalled_a = stall_delivery_at_closing_voucher(
        &conn,
        *blob_a.hash.as_bytes(),
        blob_a.wire_bytes,
        Some(&ext),
    )
    .await?;
    let stalled_b = stall_delivery_at_closing_voucher(
        &conn,
        *blob_b.hash.as_bytes(),
        blob_b.wire_bytes,
        Some(&ext),
    )
    .await?;

    // Out-of-order settlement: pay stream B (opened SECOND) first, then A. The
    // cumulative watermark is threaded in PAYMENT order, not open order — the node
    // steps the shared counter by each stream's own delivered delta, so B's
    // voucher reconstructs to `wire_b` and A's to `wire_b + wire_a`.
    let (_b_completed_at, after_b) = stalled_b
        .pay_and_finish(&fx.client_signer, VoucherTotals::default())
        .await?;
    anyhow::ensure!(
        after_b.wire_bytes == blob_b.wire_bytes,
        "after paying B first the cumulative wire bytes must be exactly B's: {} vs {}",
        after_b.wire_bytes,
        blob_b.wire_bytes,
    );

    // A's cumulative voucher is where the shared counter crosses the 1 MiB
    // boundary (from `wire_b` to `wire_b + wire_a`).
    let (_a_completed_at, after_a) = stalled_a.pay_and_finish(&fx.client_signer, after_b).await?;
    anyhow::ensure!(
        after_a.wire_bytes == aggregate_wire,
        "the final cumulative wire bytes must be the exact aggregate: {} vs {aggregate_wire}",
        after_a.wire_bytes,
    );

    // The lane persisted ONE shared watermark — the exact aggregate of both
    // streams (monotone, never double-counted) — and its cumulative amount is what
    // the two vouchers paid.
    let persisted = fx.store.load_all()?;
    anyhow::ensure!(
        persisted.len() == 1,
        "the two streams share one lane, but {} were persisted",
        persisted.len(),
    );
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(aggregate_wire),
        "shared lane watermark: {} (expected the {aggregate_wire}-byte aggregate)",
        only.last_bytes_delivered(),
    );
    anyhow::ensure!(
        only.last_amount() == after_a.amount,
        "cumulative amount: {} (expected {})",
        only.last_amount(),
        after_a.amount,
    );

    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// A lane funded for two same-lane streams minus one base unit admits the first
/// and refuses a concurrent second with `NotFound` (the pool ceiling's wire
/// collapse), while the admitted stream still delivers and settles.
///
/// Each blob is under one chunk, so it delivers fully within one credit window
/// (parking at the closing voucher) and its span-capped floor reservation is its
/// own `min_payment`. `remaining` is exactly both reservations less one base unit:
/// enough for the first stream, one unit short of both live at once, so the
/// per-pool ceiling (`remaining − M`) refuses the second.
#[tokio::test(flavor = "multi_thread")]
async fn second_same_lane_stream_refused_when_budget_covers_one() -> anyhow::Result<()> {
    // Each blob stays inside ONE chunk of wire, so the whole delivery rides the
    // ramp floor and the test settles it with a single closing voucher. Sizes are
    // multiples of the bao chunk group, so the span-capped reservation is exactly
    // `min_payment(len)`.
    let payload_a = vec![0x71u8; 512 * 1024];
    let payload_b = vec![0x82u8; 256 * 1024];
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        U256::from(10_000_000u64),
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    // Exactly both streams' span-capped floor reservations, minus one base unit:
    // covers the first stream alone but not both live at once. Derived from the
    // same `min_payment` the accumulator charges, so it tracks the payment quantum
    // and rounding rather than a hard-coded number.
    let reserved_a = min_payment(payload_a.len() as u64, RATE_PER_MB);
    let reserved_b = min_payment(payload_b.len() as u64, RATE_PER_MB);
    let remaining = reserved_a + reserved_b - U256::from(1u64);
    let (target, _server_eth, server_ep, server_task, _metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        remaining,
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let ext = binding_ext(&signer, client_node_id)?;

    // First same-lane stream: admitted, parked mid-delivery (holds its slot).
    let wire_a = support::bao_wire_len_whole(payload_a.len() as u64);
    let first =
        stall_delivery_at_closing_voucher(&conn, *hash_a.as_bytes(), wire_a, Some(&ext)).await?;

    // Second concurrent same-lane stream: refused by the pool ceiling. This lane
    // is a proven requester, so the refusal is `Unfunded`, not the prober-facing
    // `NotFound`.
    let (refusal, refusal_ext) =
        open_expecting_refusal(&conn, *hash_b.as_bytes(), Some(&ext)).await?;
    anyhow::ensure!(
        !refusal.body.ok,
        "second same-lane stream must be refused while budget covers only one floor"
    );
    anyhow::ensure!(
        matches!(
            refusal_ext.error,
            Some(decdn_protocol::client::StreamError::Unfunded)
        ),
        "expected the Unfunded wire code, got {:?}",
        refusal_ext.error
    );

    // The admitted stream still settles cleanly once its slot is the only one
    // left, proving the cap released and did not wedge the lane.
    let _ = first
        .pay_and_finish(&signer, VoucherTotals::default())
        .await?;

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A finished stream releases its floor reservation: after the first same-lane
/// stream settles, a later same-lane open on the same one-floor budget is admitted
/// again. It proves the reservation frees the pool's floor headroom on settle, not
/// merely that a fresh lane admits; a leaked reservation would refuse the second
/// open here.
#[tokio::test(flavor = "multi_thread")]
async fn finished_stream_releases_its_floor_reservation() -> anyhow::Result<()> {
    // Each blob stays inside ONE chunk of wire, so the whole delivery rides the
    // ramp floor and the test settles it with a single closing voucher.
    let payload_a = vec![0x71u8; 512 * 1024];
    let payload_b = vec![0x82u8; 256 * 1024];
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        U256::from(10_000_000u64),
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    // One floor of pool headroom and no more: the credit window's ramp floor is
    // one chunk, so a floor costs `min_payment(CHUNK_BYTES, rate)`. Derived
    // rather than hard-coded so it tracks the payment quantum.
    let remaining = min_payment(CHUNK_BYTES, RATE_PER_MB) + U256::from(2u64);
    let (target, _server_eth, server_ep, server_task, _metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        remaining,
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let ext = binding_ext(&signer, client_node_id)?;

    // Admit, deliver, and fully settle the first stream — its `FloorReservation`
    // releases once `pay_and_finish` returns.
    let wire_a = support::bao_wire_len_whole(payload_a.len() as u64);
    let first =
        stall_delivery_at_closing_voucher(&conn, *hash_a.as_bytes(), wire_a, Some(&ext)).await?;
    let (_first_completed_at, totals) = first
        .pay_and_finish(&signer, VoucherTotals::default())
        .await?;

    // A later same-lane open now succeeds on the same budget — the reservation
    // was released, not leaked. `stall_delivery_at_closing_voucher` itself
    // asserts `resp.body.ok`, so a leaked reservation fails this call with a
    // refusal error.
    // The shared lane's cumulative watermark carries forward (as in
    // `concurrent_same_lane_streams_aggregate_across_the_chunk_boundary`
    // above): the second voucher's `bytes_delivered` must cover both streams.
    let wire_b = support::bao_wire_len_whole(payload_b.len() as u64);
    let second =
        stall_delivery_at_closing_voucher(&conn, *hash_b.as_bytes(), wire_b, Some(&ext)).await?;
    let _ = second.pay_and_finish(&signer, totals).await?;

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A single same-lane stream on a one-floor budget is admitted and settles: one
/// stream reserves one floor, which the pool ceiling covers.
#[tokio::test(flavor = "multi_thread")]
async fn single_same_lane_stream_admitted_unchanged() -> anyhow::Result<()> {
    // Inside one chunk of wire, so the whole delivery rides the ramp floor.
    let payload = vec![0x93u8; 512 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        U256::from(10_000_000u64),
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    // One floor of pool headroom and no more: the credit window's ramp floor is
    // one chunk, so a floor costs `min_payment(CHUNK_BYTES, rate)`. Derived
    // rather than hard-coded so it tracks the payment quantum.
    let remaining = min_payment(CHUNK_BYTES, RATE_PER_MB) + U256::from(2u64);
    let (target, _server_eth, server_ep, server_task, _metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        remaining,
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let ext = binding_ext(&signer, client_node_id)?;

    let wire = support::bao_wire_len_whole(payload.len() as u64);
    let only = stall_delivery_at_closing_voucher(&conn, *hash.as_bytes(), wire, Some(&ext)).await?;
    let (_completed_at, totals) = only
        .pay_and_finish(&signer, VoucherTotals::default())
        .await?;
    anyhow::ensure!(
        totals.wire_bytes == wire,
        "settled wire bytes: {} (expected the whole blob's {wire})",
        totals.wire_bytes
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Two simultaneous same-lane opens on a one-floor budget: `try_reserve_floor`
/// reserves under one lock hold, so the pool ceiling (`remaining − M`) admits
/// exactly one and refuses the other with `NotFound` — no TOCTOU double-admit.
/// Each blob is at least one chunk, so each reserves a FULL ramp-start floor;
/// with only one floor of headroom the two reservations cannot both fit, and
/// which open wins is scheduling-dependent and deliberately not asserted.
#[tokio::test(flavor = "multi_thread")]
async fn concurrent_opens_admit_exactly_one() -> anyhow::Result<()> {
    // Each blob spans at least one chunk of wire, so its span-capped floor
    // reservation is a full ramp-start window — two of them overflow the
    // one-floor budget, so the pool ceiling admits exactly one.
    let payload_a = vec![0x71u8; 2 * 1024 * 1024];
    let payload_b = vec![0x82u8; 2 * 1024 * 1024];
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        U256::from(10_000_000u64),
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    // One floor of pool headroom and no more: the credit window's ramp floor is
    // one chunk, so a floor costs `min_payment(CHUNK_BYTES, rate)`. Derived
    // rather than hard-coded so it tracks the payment quantum.
    let remaining = min_payment(CHUNK_BYTES, RATE_PER_MB) + U256::from(2u64);
    let (target, _server_eth, server_ep, server_task, _metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        remaining,
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let ext = binding_ext(&signer, client_node_id)?;

    let (a_ok, b_ok) =
        race_two_same_lane_opens(&conn, *hash_a.as_bytes(), *hash_b.as_bytes(), &ext).await?;
    assert_ne!(
        a_ok, b_ok,
        "exactly one of the two concurrent opens is admitted"
    );

    // The admitted stream's chunks are left unread here — this test only
    // exercises the gate, not delivery — so the server side may still be writing
    // when the endpoints close. `spawn_server` swallows handler errors, so that
    // reaches nothing below; only a panic would.
    drop(conn);
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A SKIP-AHEAD voucher — one whose cumulative `bytes_delivered` assumes
/// another same-lane stream's bytes are already settled, sent before that
/// stream is paid — is accepted. The voucher's cumulative bytes come from the
/// WIRE (ADR 005 §Voucher wire format), self-described and signed by the
/// client, so the node verifies it directly against the lane's pinned signer
/// instead of reconstructing a per-stream cumulative from the shared lane
/// counter plus this stream's delivered delta. Such a reconstruction would make
/// a skip-ahead voucher recover a different address than it was signed under;
/// with the wire value verified directly, settlement does not depend on the
/// order concurrent same-lane streams pay in.
#[tokio::test(flavor = "multi_thread")]
async fn skip_ahead_voucher_on_a_concurrent_lane_is_accepted() -> anyhow::Result<()> {
    // Both blobs sit under one chunk, so each stream has a single
    // closing voucher; their sizes differ so a skip-ahead cumulative cannot
    // coincidentally match the reconstructed per-stream value.
    let payload_a = vec![0x71u8; 512 * 1024];
    let payload_b = vec![0x82u8; 384 * 1024];
    let idle = Duration::from_secs(30);
    let fx = idle_fixture_with_two_blobs(&payload_a, &payload_b, idle).await?;
    let blob_a = fx.blob(0)?;
    let blob_b = fx.blob(1)?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;

    // Both streams deliver fully and park at their closing voucher; nothing is
    // paid yet, so the shared lane counter is still 0. Stream A is left parked
    // (never paid) for the whole test — its bytes are exactly what B's skip-ahead
    // voucher wrongly assumes are already on the lane.
    let _stalled_a = stall_delivery_at_closing_voucher(
        &conn,
        *blob_a.hash.as_bytes(),
        blob_a.wire_bytes,
        Some(&ext),
    )
    .await?;
    let mut stalled_b = stall_delivery_at_closing_voucher(
        &conn,
        *blob_b.hash.as_bytes(),
        blob_b.wire_bytes,
        Some(&ext),
    )
    .await?;

    // On stream B, pay a voucher that SKIPS AHEAD: its cumulative bytes/amount
    // assume A's bytes are already on the lane, even though A has not been paid.
    let skip_ahead_bytes = blob_a
        .wire_bytes
        .checked_add(blob_b.wire_bytes)
        .ok_or_else(|| anyhow::anyhow!("skip-ahead wire-byte overflow"))?;
    let skip_ahead_amount = min_payment(blob_a.wire_bytes, RATE_PER_MB)
        .checked_add(min_payment(blob_b.wire_bytes, RATE_PER_MB))
        .ok_or_else(|| anyhow::anyhow!("skip-ahead amount overflow"))?;

    let reply = stalled_b
        .send_cumulative_voucher(&fx.client_signer, skip_ahead_bytes, skip_ahead_amount)
        .await?;

    // Self-describing bytes: B's voucher carries the aggregate cumulative it
    // was signed over, so the node verifies it directly and advances the lane
    // watermark to A+B — the skip-ahead voucher is accepted, not WrongSigner.
    match reply {
        ClientMessage::StreamError(err) => {
            anyhow::bail!("skip-ahead voucher must be accepted, got StreamError {err:?}")
        }
        // A clean acceptance surfaces as continued delivery ending in StreamEnd
        // (B's whole range is already on the wire), or no immediate reply frame.
        ClientMessage::StreamEnd | ClientMessage::ChunkData(_) => {}
        other => anyhow::bail!("unexpected reply to an accepted voucher: {other:?}"),
    }

    // The accepted aggregate is the persisted watermark.
    let persisted = fx.store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("lane state must persist after an accepted voucher"))?;
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(skip_ahead_bytes),
        "an accepted skip-ahead voucher lands the aggregate watermark, got {}",
        only.last_bytes_delivered(),
    );

    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// #1699 out-of-order settlement: after a higher (aggregate) voucher settles
/// the lane, a lower voucher arriving on a slower stream is ALREADY-SATISFIED —
/// the node does not kill that stream and the watermark never regresses. This
/// is the case a naive wire+verify change would fail (fatal regression).
#[tokio::test(flavor = "multi_thread")]
async fn lower_voucher_after_higher_sibling_is_already_satisfied() -> anyhow::Result<()> {
    let payload_a = vec![0x71u8; 512 * 1024];
    let payload_b = vec![0x82u8; 384 * 1024];
    let idle = Duration::from_secs(30);
    let fx = idle_fixture_with_two_blobs(&payload_a, &payload_b, idle).await?;
    let blob_a = fx.blob(0)?;
    let blob_b = fx.blob(1)?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;

    let mut stalled_a = stall_delivery_at_closing_voucher(
        &conn,
        *blob_a.hash.as_bytes(),
        blob_a.wire_bytes,
        Some(&ext),
    )
    .await?;
    let mut stalled_b = stall_delivery_at_closing_voucher(
        &conn,
        *blob_b.hash.as_bytes(),
        blob_b.wire_bytes,
        Some(&ext),
    )
    .await?;

    // Settle the aggregate (A+B) on stream B first — the "higher" voucher.
    let agg_bytes = blob_a.wire_bytes + blob_b.wire_bytes;
    let agg_amount =
        min_payment(blob_a.wire_bytes, RATE_PER_MB) + min_payment(blob_b.wire_bytes, RATE_PER_MB);
    let reply_b = stalled_b
        .send_cumulative_voucher(&fx.client_signer, agg_bytes, agg_amount)
        .await?;
    anyhow::ensure!(
        !matches!(reply_b, ClientMessage::StreamError(_)),
        "aggregate voucher on B must be accepted, got {reply_b:?}"
    );

    // Now the LOWER standalone voucher for just A arrives on stream A. It is
    // below the A+B watermark — already satisfied, NOT a WrongSigner/regression
    // kill.
    let reply_a = stalled_a
        .send_cumulative_voucher(
            &fx.client_signer,
            blob_a.wire_bytes,
            min_payment(blob_a.wire_bytes, RATE_PER_MB),
        )
        .await?;
    anyhow::ensure!(
        !matches!(reply_a, ClientMessage::StreamError(_)),
        "a superseded lower voucher must be already-satisfied, got StreamError: {reply_a:?}"
    );

    // The watermark holds at the aggregate; it did not regress to A.
    let persisted = fx.store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("lane state must persist"))?;
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(agg_bytes),
        "watermark must stay at the aggregate, got {}",
        only.last_bytes_delivered(),
    );

    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// Regression for #1054: a 0-byte blob delivers end-to-end over `cdn/client/v1`.
/// The serve emits no `ChunkData` and no voucher (0 wire bytes), the requester
/// proves the empty stream against the empty root `Hash::new(&[])` and returns
/// empty bytes, and the lane does NOT advance (nonce 0, 0 bytes delivered).
/// Before the fix, `align_range(0, 0, 0)` rejected the whole-empty serve/receive
/// with `RangeOutOfBounds`.
#[tokio::test(flavor = "multi_thread")]
async fn client_delivers_empty_blob() -> anyhow::Result<()> {
    // Empty payload → `hash` is the empty root, computed via `bao_tree::blake3`, by construction.
    let payload: Vec<u8> = Vec::new();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;

    anyhow::ensure!(got.as_ref().is_empty(), "empty blob delivers empty bytes");

    // No wire bytes → no voucher → the lane stays at its registered state.
    let persisted = store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::ZERO,
        "0 bytes delivered, got {}",
        only.last_bytes_delivered()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Watermark-on-error contract (#852) on the `stream_fetch_tracked` path: when a
/// pull errors mid-stream *after* at least one voucher was acked, `progress` must
/// still hold the last acked watermark so the caller can persist what it paid —
/// it must NOT reset to `None`.
///
/// Induced deterministically by capability-cap exhaustion (no mock server): a
/// blob one chunk plus a remainder needs two vouchers — a cumulative amount
/// for the interval, then a larger cumulative amount for the close — but the
/// signer's cap only clears the first. The node acks voucher 1 and rejects
/// voucher 2 as over-cap (`SpendingCapExhausted`), so the fetch errors after one
/// acked voucher.
/// `progress.advanced()` must then report voucher 1 (nonce 1), proving the
/// copy-back in `stream_fetch_tracked` runs on the error path.
///
/// The deposit is load-bearing in both directions: it must clear the #1516
/// pre-serve gate's ceiling (one credit window at `RATE_PER_MB`) so the first
/// attempt is actually served, and fall short of voucher 2 so the mid-stream
/// ceiling is what stops it. An acked nonce of 1 is only reachable through
/// that exact sequence, so it pins the mid-stream backstop as surely as
/// asserting on the reject reason did.
///
/// The *terminal* error is the voucher rejection itself, and no resume retry is
/// attempted at all. The rejection does carry an authenticated `WatermarkBundle`,
/// but that bundle merely echoes the watermark this client already holds (nonce 1
/// — the node attaches one to every watermark-gated rejection once any voucher has
/// been accepted, including a genuinely exhausted one). `PoolLedger::reseed`
/// refuses a non-advancing cumulative, so `fetch_inner` surfaces the real cause
/// instead of spending a resume attempt re-sending a voucher the node has already
/// refused for lack of deposit. The counter assertion below pins that: there is
/// no futile resume attempt, so the node serves no fresh free window for one.
#[tokio::test(flavor = "multi_thread")]
async fn tracked_watermark_survives_post_ack_error() -> anyhow::Result<()> {
    // 6 MiB — several whole chunks plus a closing remainder, so the transfer
    // meters a run of reveals and then settles the tail with a signature.
    let payload = vec![0xABu8; 6 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    // Exactly voucher 1's cumulative amount: it clears the #1516 pre-serve
    // ceiling (also one interval, with no configured credit window) and covers
    // voucher 1, but falls short of voucher 2's larger cumulative amount.
    let deposit = min_payment(HARNESS_INTERVAL_BYTES, RATE_PER_MB);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    let mut progress = VoucherProgress::default();

    let result = stream_fetch_tracked(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c0_ffee,
        PullDeadlines::whole_transfer(Duration::from_secs(20)),
        0,
        0,
        &mut progress,
    )
    .await;

    // Assert the *intended* failure mode, not just any error: the over-deposit
    // voucher rejection is what surfaces, unmasked by a futile resume. A
    // regression that errors for some other reason (e.g. a transport fault)
    // should fail this test loudly.
    let err = result
        .err()
        .ok_or_else(|| anyhow::anyhow!("fetch must error when voucher 2 is over-deposit"))?;
    let rejected = err
        .downcast_ref::<UpstreamVoucherRejected>()
        .ok_or_else(|| anyhow::anyhow!("expected UpstreamVoucherRejected, got: {err:?}"))?;
    anyhow::ensure!(
        matches!(
            rejected.reason,
            decdn_protocol::client::VoucherRejectReason::SpendingCapExhausted
        ),
        "the exhausted cap must surface its own rejection reason; got {:?}",
        rejected.reason
    );
    // The bundle IS attached — this is the case that made bundle presence alone
    // an unsafe reseed trigger. Pinning it here keeps the test honest: it is
    // asserting that a *present* bundle was correctly declined, not that none
    // arrived.
    anyhow::ensure!(
        rejected.bundle.is_some(),
        "the rejection should still carry a watermark bundle; \
         without one this test would pass vacuously"
    );
    // The contract this test exists for: the watermark survives the error and
    // reflects the one cleared voucher. A non-zero cumulative amount — and no
    // further advance — is only possible if voucher 1 cleared and voucher 2 hit
    // the mid-stream cap ceiling, so this also pins that backstop.
    let advanced = progress.advanced().ok_or_else(|| {
        anyhow::anyhow!("advanced watermark must survive a post-ack error, got None")
    })?;
    anyhow::ensure!(
        advanced.1 > U256::ZERO,
        "at least one voucher should have cleared before the rejection; amount = {}",
        advanced.1
    );
    // #1516 pinned that a futile resume retry is refused pre-serve rather than
    // handed a free credit window. With the non-advancing bundle now declined,
    // there is no second attempt to refuse at all — strictly stronger, so the
    // pre-serve rejection counter must stay at zero.
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_insufficient_deposit_total 0"
        ),
        "an exhausted cap must not retry at all, so nothing should reach the \
         pre-serve deposit gate"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Wiring guard for `decdn node lanes` (issue #1733): a real signed-voucher
/// accept through the live `ClientHandler` must advance the last-voucher clock
/// the admin surface reads off the lane registry.
///
/// The stamp call site (`handlers/client/voucher.rs`) has no other test caller —
/// a dropped or mis-placed stamp would silently leave `seconds_since_last_voucher`
/// at `None` ("never") forever. Here we take a `LaneActivityClock` over the
/// handler's registry, drive one successful delivery (which accepts vouchers),
/// and assert the lane now reports `Some(age)`. Before the accept the lane's
/// stamp is `0`, so it is absent from `ages`; a present age proves the accept
/// path stamped the lane state.
#[tokio::test(flavor = "multi_thread")]
async fn accepted_voucher_advances_lane_activity_clock() -> anyhow::Result<()> {
    let payload = vec![0xABu8; 1_572_864]; // 1.5 MiB → crosses a chunk
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
        |_deps| {},
    )?;
    // A read handle over the handler's live registry — the same wiring
    // `runtime::run` performs for the admin surface. Before any accept the
    // lane's stamp is 0, so it is absent from `ages`.
    let activity = handler.lane_activity_clock();
    assert!(
        !activity
            .ages()
            .await
            .contains_key(&lane_key(client_signer.address())),
        "no voucher accepted yet → clock must report the lane as absent (never)"
    );

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch"
    );

    // The accept path stamped the lane state: the admin surface reading the
    // same registry would now report an age rather than "never".
    assert!(
        activity
            .ages()
            .await
            .contains_key(&lane_key(client_signer.address())),
        "an accepted voucher must advance the lane's last-voucher clock"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Issue #248: every proof that actually credits bytes appends one download
/// receipt naming the served blob's hash, the bytes it paid for, the paying
/// client's iroh node id, and the lane's cumulative amount.
///
/// Under `PayWord` the meter ticks per chunk, so a multi-chunk delivery records
/// one receipt per whole chunk plus one for the closing residual — and their
/// `size`s still sum to exactly the delivered wire bytes, which is the property
/// the audit log actually rests on. The count is asserted against that sum
/// rather than hard-coded, so it tracks the blob rather than the cadence.
///
/// Crucially the anchor voucher each stream sends before its first reveal
/// records NOTHING: it re-asserts a cumulative the lane already holds, so it
/// credits nothing, and a receipt for it would log a payment that never
/// happened.
#[tokio::test(flavor = "multi_thread")]
async fn voucher_acceptance_appends_download_receipt() -> anyhow::Result<()> {
    // 6 MiB — several whole chunks, plus a closing residual smaller than one.
    let payload = vec![0x5Au8; 6 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let receipts = Arc::new(VecReceiptLog::default());
    let handler = build_handler_full_with_receipts(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        Arc::clone(&receipts) as Arc<dyn decdn_node::receipt_log::ReceiptLog>,
        RATE_PER_MB,
        &loopback_domains(),
        16,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let client_sk = fresh_key();
    let client_node_id = client_sk.public();
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch"
    );

    assert_receipts_cover_the_delivery(&receipts.snapshot(), hash, client_node_id, &payload)?;

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Every assertion the receipt log has to satisfy after a completed delivery,
/// split out to keep the test itself readable.
fn assert_receipts_cover_the_delivery(
    recorded: &[DownloadReceipt],
    hash: Hash,
    client_node_id: iroh::PublicKey,
    payload: &[u8],
) -> anyhow::Result<()> {
    let want_hash = hex_lower(hash.as_bytes());
    let want_node = hex_lower(client_node_id.as_bytes());
    let total: u64 = recorded.iter().map(DownloadReceipt::size).sum();
    // ADR 038: metered quantity is bao wire bytes
    let wire = support::bao_wire_len_whole(payload.len() as u64);
    // One receipt per whole chunk, plus one for the residual when the wire
    // length is not an exact multiple.
    let chunk = decdn_protocol::client::CHUNK_BYTES;
    let expected = (wire / chunk) + u64::from(!wire.is_multiple_of(chunk));
    anyhow::ensure!(
        recorded.len() as u64 == expected,
        "expected {expected} receipts (one per chunk plus the closing residual), got {}: \
         {recorded:?}",
        recorded.len()
    );
    anyhow::ensure!(
        recorded.iter().all(|r| r.size() > 0),
        "a proof that credited nothing must record no receipt: {recorded:?}"
    );
    anyhow::ensure!(
        total == wire,
        "receipt sizes sum to {total}, expected {wire}"
    );
    for (i, r) in recorded.iter().enumerate() {
        anyhow::ensure!(
            r.hash() == want_hash,
            "receipt[{i}] hash {} != {want_hash}",
            r.hash()
        );
        anyhow::ensure!(
            r.client_node_id() == want_node,
            "receipt[{i}] client_node_id {} != {want_node}",
            r.client_node_id()
        );
        anyhow::ensure!(r.size() > 0, "receipt[{i}] size must be > 0");
        anyhow::ensure!(r.timestamp_secs() > 0, "receipt[{i}] timestamp must be set");
    }
    // Proofs carry no nonce; each accepted proof records the lane's cumulative
    // claim at that moment, so the amounts rise strictly across the run — the
    // reveals by one `chunk_price` each, the closing residual by less.
    let amounts: Vec<u128> = recorded
        .iter()
        .map(|r| r.voucher_amount().parse::<u128>().unwrap_or(0))
        .collect();
    anyhow::ensure!(
        amounts.windows(2).all(|w| w.first() < w.last()),
        "receipt amounts must rise strictly, got {amounts:?}"
    );
    anyhow::ensure!(
        amounts.first() == Some(&u128::from(RATE_PER_MB)),
        "the first reveal claims exactly one chunk at the quoted rate, got {amounts:?}"
    );
    Ok(())
}

/// Issue #803: receipt-log I/O must never back-pressure paid delivery. Wired
/// through the REAL `ChannelReceiptSink` + background writer (not the inline
/// `DirectReceiptSink`), with the underlying log stalled on every `append`, the
/// full blob must still deliver and hash-verify — an implementation that awaits
/// the append inline before continuing delivery would hang here. After
/// releasing the stall and draining the writer, every receipt is recovered,
/// proving the decoupling loses nothing on a clean shutdown.
#[tokio::test(flavor = "multi_thread")]
async fn delivery_completes_while_receipt_writer_is_stalled() -> anyhow::Result<()> {
    let payload = vec![0x3Cu8; 1_572_864]; // 1.5 MiB — two voucher appends.
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    // The production sink: a bounded channel feeding a background writer whose
    // log blocks on every append until we release it.
    let blocking_log = Arc::new(BlockingReceiptLog::default());
    let (receipt_sink, writer_handle) = spawn_receipt_writer(
        Arc::clone(&blocking_log) as Arc<dyn decdn_node::receipt_log::ReceiptLog>,
        Arc::clone(&metrics),
    );
    let handler = build_handler_full_with_sink(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        receipt_sink,
        RATE_PER_MB,
        &loopback_domains(),
        16,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);

    // Delivery must complete while every receipt `append` is stalled. The outer
    // timeout is the real assertion: an inline-await implementation would hang.
    let got = tokio::time::timeout(
        Duration::from_secs(20),
        stream_fetch(
            &client_ep,
            target,
            &ctx,
            &slash_domain(),
            server_eth.address(),
            *hash.as_bytes(),
            0,
            0x00c0_ffee,
            Duration::from_secs(20),
        ),
    )
    .await
    .map_err(|_| anyhow::anyhow!("delivery hung while the receipt writer was stalled (#803)"))??;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch"
    );

    // Release the stall and drain the writer; the audit receipts are not lost.
    blocking_log.release();
    tokio::time::timeout(Duration::from_secs(10), writer_handle.shutdown())
        .await
        .map_err(|_| anyhow::anyhow!("receipt writer did not drain after release"))??;
    let recorded = blocking_log.snapshot();
    let total: u64 = recorded.iter().map(DownloadReceipt::size).sum();
    // ADR 038: metered quantity is bao wire bytes
    let wire = support::bao_wire_len_whole(payload.len() as u64);
    anyhow::ensure!(
        total == wire,
        "drained receipt sizes sum to {total}, expected {wire} ({} receipts)",
        recorded.len()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Issue #248: a download-receipt write failure is non-fatal. The payment
/// already committed to the pool-state store, so even with a receipt log that
/// errors on every append, the full blob is delivered and hash-verifies and the
/// lane state still advances. A receipt-log failure must never fail delivery
/// or block payment.
#[tokio::test(flavor = "multi_thread")]
async fn receipt_log_write_failure_does_not_fail_delivery() -> anyhow::Result<()> {
    let payload = vec![0x7Eu8; 1_572_864]; // 1.5 MiB — exercises two voucher appends.
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler_full_with_receipts(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        Arc::new(FailingReceiptLog) as Arc<dyn decdn_node::receipt_log::ReceiptLog>,
        RATE_PER_MB,
        &loopback_domains(),
        16,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivery must succeed despite receipt-log failure"
    );

    // Payment still committed: the lane advanced to the full byte count.
    let persisted = store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    // ADR 038: metered quantity is bao wire bytes
    let wire = support::bao_wire_len_whole(payload.len() as u64);
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(wire),
        "lane state must still advance: bytes_delivered={} (expected {wire})",
        only.last_bytes_delivered()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Reused lane: two sequential streams on one lane. The second stream
/// must resume from the first's cumulative voucher state (bytes/amount), not
/// restart at zero — otherwise the node rejects the second voucher as
/// `AmountRegression`. Validates the `PoolContext.prior_*` resume fields.
#[tokio::test(flavor = "multi_thread")]
async fn client_reused_lane_resumes() -> anyhow::Result<()> {
    let payload = vec![0x33u8; 4096];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    // Stream 1: fresh lane (prior_* = 0).
    let ctx1 = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    let got1 = stream_fetch(
        &client_ep,
        target.clone(),
        &ctx1,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x1111,
        Duration::from_secs(15),
    )
    .await?;
    anyhow::ensure!(got1.as_ref() == payload.as_slice());

    let after1 = store.load_all()?;
    let s1 = after1
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    // ADR 038: the metered/persisted quantity is the bao verified-stream wire
    // size, not the payload content length.
    let wire = support::bao_wire_len_whole(payload.len() as u64);
    anyhow::ensure!(
        s1.last_bytes_delivered() == U256::from(wire),
        "stream-1 bytes: {} (expected {wire})",
        s1.last_bytes_delivered()
    );

    // Stream 2: resume from the lane's advanced state. Each `stream_fetch`
    // opens a fresh connection, so the resume request re-sends the binding.
    let ctx2 = PoolContext {
        prior_bytes_delivered: s1.last_bytes_delivered(),
        prior_amount: s1.last_amount(),
        ..pool_context(&client_ep, Arc::clone(&client_signer), deposit)
    };
    let got2 = stream_fetch(
        &client_ep,
        target,
        &ctx2,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x2222,
        Duration::from_secs(15),
    )
    .await?;
    anyhow::ensure!(got2.as_ref() == payload.as_slice());

    // The lane advanced again: nonce 2, cumulative bytes = both streams.
    let after2 = store.load_all()?;
    let s2 = after2
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        s2.last_bytes_delivered() == U256::from(2 * wire),
        "cumulative bytes: {}",
        s2.last_bytes_delivered()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Crash-restart desync (#1946): the client's persisted voucher watermark falls
/// BEHIND the node's after a mid-stream crash — the ledger commits in memory as
/// each voucher is sent and persists to disk only once, at end of fetch, so a
/// kill before that write loses every voucher the node already accepted. On
/// restart the client re-seeds its ledger from the stale persisted watermark
/// (`prior_* = 0` here) and re-signs from there, so its first voucher lands
/// STRICTLY BELOW the node's `last_amount`.
///
/// The node must hand back its authoritative watermark (a `WatermarkBundle` on a
/// gated rejection) so the client can reseed and resume; otherwise every proof
/// is stale and credits nothing, the credit window stays pinned at its
/// floor, and the stream wedges after ~1 chunk.
///
/// The blob is 3 MiB — above the 1 MiB (`CHUNK_BYTES`) credit floor — so delivery
/// must cross the window and demand a payment-advancing voucher the stale client
/// cannot produce until it reseeds. A sub-1 MiB blob fits inside the opening
/// floor window and never exercises the wedge.
#[tokio::test(flavor = "multi_thread")]
async fn client_restart_with_stale_watermark_heals_and_resumes() -> anyhow::Result<()> {
    let payload: Vec<u8> = (0..3 * 1024 * 1024u32).map(|i| (i % 251) as u8).collect();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(1_000_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    // Stream 1: a healthy fetch that advances the node's lane watermark to the
    // full blob. This is the state the node holds when the client crashes.
    let ctx1 = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    let got1 = stream_fetch(
        &client_ep,
        target.clone(),
        &ctx1,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x1111,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(got1.as_ref() == payload.as_slice());

    let after1 = store.load_all()?;
    let s1 = after1
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    let wire = support::bao_wire_len_whole(payload.len() as u64);
    anyhow::ensure!(
        s1.last_bytes_delivered() == U256::from(wire),
        "stream-1 advanced the node lane to {wire}, got {}",
        s1.last_bytes_delivered()
    );

    // Stream 2: the RESTARTED client. `prior_* = 0` models a crash before the
    // end-of-fetch watermark persist — the node's lane is at `wire`, the client
    // believes it is at zero. It must still complete: the node hands back its
    // watermark and the client reseeds forward.
    //
    // The 8s budget is deliberately BELOW the node's proof-wait backstop (10s
    // with no transport progress, `VOUCHER_READ_TIMEOUT`): recovery must fire on
    // the first stale proof the lane headroom cannot pay, not wait for the proof
    // wait to fault. An unhealed stream wedges at the ~1 MiB floor
    // and blows this budget.
    let ctx2 = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    let got2 = stream_fetch(
        &client_ep,
        target,
        &ctx2,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x2222,
        Duration::from_secs(8),
    )
    .await?;
    anyhow::ensure!(
        got2.as_ref() == payload.as_slice(),
        "restarted client must recover the full blob, got {} of {} bytes",
        got2.len(),
        payload.len()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The mirror of [`client_restart_with_stale_watermark_heals_and_resumes`]: the
/// client's persisted watermark is AHEAD of the node's lane, carrying bytes the
/// node never accepted a voucher for (a voucher committed optimistically on send
/// and then refused). Every span the client signs then pays below the quoted
/// rate over the node's watermark, so the node answers `Underpaid` with that
/// watermark. The client verifies it against its own signature, rebases down to
/// it, and completes — against a real handler, whose bundle carries the lane's
/// real chain state.
///
/// The 8s budget is below the node's proof-wait backstop (10s with no transport
/// progress, `VOUCHER_READ_TIMEOUT`), so the heal must fire on the rejection
/// itself, not on a proof-wait fault.
#[tokio::test(flavor = "multi_thread")]
async fn client_ahead_of_the_node_rebases_and_resumes() -> anyhow::Result<()> {
    let payload: Vec<u8> = (0..3 * 1024 * 1024u32).map(|i| (i % 251) as u8).collect();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(1_000_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    // Stream 1: a healthy fetch that gives the node's lane an accepted watermark.
    let ctx1 = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    let got1 = stream_fetch(
        &client_ep,
        target.clone(),
        &ctx1,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x3333,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(got1.as_ref() == payload.as_slice());
    let node_lane = store
        .load_all()?
        .first()
        .map(|l| (l.last_amount(), l.last_bytes_delivered()))
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;

    // Stream 2: the client believes it paid one base unit more for many more
    // bytes than the node accepted — every span it signs from there underpays.
    let mut ctx2 = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    ctx2.prior_amount = node_lane.0 + U256::from(1u64);
    ctx2.prior_bytes_delivered = node_lane.1 + U256::from(64u64 * 1024 * 1024);
    let got2 = stream_fetch(
        &client_ep,
        target,
        &ctx2,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x4444,
        Duration::from_secs(8),
    )
    .await?;
    anyhow::ensure!(
        got2.as_ref() == payload.as_slice(),
        "the client ahead of the node must rebase and recover the full blob, got {} of {} \
         bytes",
        got2.len(),
        payload.len()
    );
    let healed = store
        .load_all()?
        .first()
        .map(|l| (l.last_amount(), l.last_bytes_delivered()))
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        healed.0 > node_lane.0 && healed.1 > node_lane.1,
        "the node must credit the healed stream from its own watermark: {node_lane:?} -> \
         {healed:?}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Under-fold heal (#2167): the node's lane holds a LIVE chain from an earlier
/// payer process — a signed anchor plus reveals proved on top of it — and a new
/// process resumes from a persisted watermark ABOVE the signed anchor but SHORT
/// of the live claim. Its first voucher opens a fresh root, so it retires the
/// live chain without folding all of it.
#[tokio::test(flavor = "multi_thread")]
async fn client_under_folding_a_live_chain_reseeds_and_resumes() -> anyhow::Result<()> {
    resume_under_a_live_chain(1).await
}

/// The same heal when the new process resumes from EXACTLY the signed anchor: the
/// earlier process sent reveals and exited before it persisted them, so the
/// persisted watermark is the anchor and the node's frontier is past it. The opening
/// voucher repeats the anchor amount under a fresh root. No sibling settled it
/// under that root, so it is an under-fold, not an already-satisfied voucher.
#[tokio::test(flavor = "multi_thread")]
async fn client_resuming_at_the_anchor_under_a_live_chain_heals() -> anyhow::Result<()> {
    resume_under_a_live_chain(0).await
}

/// Restart heal on a multi-stream lane (#2173): a restarted payer that lost
/// accepted vouchers pulls while a sibling stream on the same lane is still
/// open. Its opening voucher names a fresh root BELOW the node's signed anchor.
/// The node cannot tell that voucher from an honest sibling's late one, so it
/// lets it anchor the stream. The reveal after it folds nothing, and lane
/// headroom cannot pay its chunk: that is the stale payer, and the node rejects
/// it with the bundle however many streams the lane holds.
///
/// The sibling is a sub-chunk delivery held at its closing voucher, so the lane
/// has two live streams for the whole pull. The 8s budget sits below the node's
/// proof-wait backstop (10s with no transport progress, `VOUCHER_READ_TIMEOUT`),
/// so a stream left waiting on a proof the payer never sends blows it.
#[tokio::test(flavor = "multi_thread")]
async fn a_restarted_payer_beside_a_live_sibling_heals_below_the_anchor() -> anyhow::Result<()> {
    // Larger than the seeded lane's five proved chunks, so a stream cannot
    // finish on that frontier even if the node counted it as headroom (#2171).
    let payload: Vec<u8> = (0..8 * 1024 * 1024u32).map(|i| (i % 251) as u8).collect();
    let sibling_payload = vec![0x82u8; 256 * 1024];
    let (cache, hash, sibling_hash, _cache_tmp) =
        cache_with_two_blobs(&payload, &sibling_payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(1_000_000_000u64);
    let lane = lane_with_proved_reveals(&client_signer, deposit)?;
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&lane)?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    // Serve each connection on its own task: the sibling's connection stays open
    // for the whole pull, and `spawn_server` serves one connection at a time.
    let accept_ep = server_ep.clone();
    let server_task = tokio::spawn(async move {
        while let Some(incoming) = accept_ep.accept().await {
            let Ok(connecting) = incoming.accept() else {
                continue;
            };
            let Ok(conn) = connecting.await else { continue };
            let handler = Arc::clone(&handler);
            tokio::spawn(async move {
                let _ = ClientProtocol::new(handler).accept(conn).await;
            });
        }
    });
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    // The sibling: a live same-lane stream that waits on its closing voucher.
    let (sibling_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let sibling_conn = sibling_ep
        .connect(target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let sibling_ext = binding_ext(&client_signer, B256::from(*sibling_ep.id().as_bytes()))?;
    let _sibling = stall_delivery_at_closing_voucher(
        &sibling_conn,
        *sibling_hash.as_bytes(),
        support::bao_wire_len_whole(sibling_payload.len() as u64),
        Some(&sibling_ext),
    )
    .await?;

    // The restarted process: a watermark at zero, far below the signed anchor.
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x5555,
        Duration::from_secs(8),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "the restarted client must reseed and recover the full blob, got {} of {} bytes",
        got.len(),
        payload.len()
    );
    let healed = store
        .load_all()?
        .first()
        .map(LaneState::owed)
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        healed > lane.owed(),
        "the healed stream must pay past the live claim: {} -> {healed}",
        lane.owed()
    );
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_voucher_rejected_total")? == 1,
        "the heal costs exactly one rejected proof"
    );

    drop(sibling_conn);
    shutdown([server_task], [&client_ep, &sibling_ep, &server_ep]).await?;
    Ok(())
}

/// The earlier process's lane: an anchor `signer` signed under root `R` at
/// three chunks, plus five reveals the node proved on top of it. A reloaded
/// lane counts that whole claim as credited (#2171), so none of it is headroom
/// a stream whose reveals fold nothing could draw on.
fn lane_with_proved_reveals(signer: &PrivateKeySigner, deposit: U256) -> anyhow::Result<LaneState> {
    lane_with_proved_frontier(signer, deposit, 5)
}

/// [`lane_with_proved_reveals`] with `verified_index` reveals proved on top of
/// the anchor.
fn lane_with_proved_frontier(
    signer: &PrivateKeySigner,
    deposit: U256,
    verified_index: u8,
) -> anyhow::Result<LaneState> {
    use decdn_incentive::chain::{CHUNK_BYTES, preimage_at, root_from_seed};

    let price = decdn_incentive::min_payment(CHUNK_BYTES, RATE_PER_MB);
    let anchor_amount = price * U256::from(3u64);
    let anchor_bytes = U256::from(3 * CHUNK_BYTES);
    let chain_seed = B256::repeat_byte(0x5E);
    let chain = decdn_incentive::LaneChain {
        chain_root: root_from_seed(chain_seed),
        chunk_price: price,
        verified_index,
        tip: preimage_at(chain_seed, verified_index),
    };
    let anchor = decdn_incentive::Voucher {
        pool_id: pool_id(),
        signer: signer.address(),
        provider: operator_addr(),
        amount: anchor_amount,
        bytes_delivered: anchor_bytes,
        chain_root: chain.chain_root,
        chunk_price: price,
    }
    .sign(signer, &payment_domain())?;
    Ok(LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        deposit,
        0,
        anchor_amount,
        anchor_bytes,
        Some(anchor.signature.as_bytes()),
        chain,
    ))
}

/// Seed a lane holding a live chain ([`lane_with_proved_reveals`]), then
/// fetch from a new process whose persisted amount sits `above_anchor` base
/// units over the anchor, short of the live claim.
///
/// The node must reject the first voucher `UnderFold` with the bundle stating
/// the fold owed; the client folds, reseeds, and completes. Crediting it zero
/// instead leaves the node waiting on a proof the client never sends, and the
/// stream only dies at the proof-wait backstop (10s with no transport progress,
/// `VOUCHER_READ_TIMEOUT`). The 8s budget sits below that backstop, so the heal
/// must fire on the rejection itself.
async fn resume_under_a_live_chain(above_anchor: u64) -> anyhow::Result<()> {
    let payload: Vec<u8> = (0..3 * 1024 * 1024u32).map(|i| (i % 251) as u8).collect();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(1_000_000_000u64);
    let lane = lane_with_proved_reveals(&client_signer, deposit)?;
    let anchor_amount = lane.last_amount();
    let anchor_bytes = lane.last_bytes_delivered();
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&lane)?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    // The new process: at or just above the signed anchor, short of the chain
    // the node proved.
    let mut ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    ctx.prior_amount = anchor_amount + U256::from(above_anchor);
    ctx.prior_bytes_delivered = anchor_bytes;
    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x5555,
        Duration::from_secs(8),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "the under-folding client must reseed and recover the full blob, got {} of {} bytes",
        got.len(),
        payload.len()
    );
    let healed = store
        .load_all()?
        .first()
        .map(LaneState::owed)
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        healed > lane.owed(),
        "the healed stream must pay past the live claim: {} -> {healed}",
        lane.owed()
    );
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_client_declined_total")? == 0,
        "no stream may stall on a proof the client never sends"
    );
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_voucher_rejected_total")? == 1,
        "the heal costs exactly one rejected voucher"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #2257: a new process resumes at the signed anchor under a lane whose live
/// claim is one chunk past it, and the node opens the whole credit window at
/// once. The stream's opening voucher names a fresh root and under-folds, but
/// the node delivers ahead of reading it, so the stream releases several reveals
/// under that root before the rejection lands. Only the last reveal rewinds, so
/// the ledger already covers the bundle and has nothing to reseed. The heal
/// must retire the root the node never adopted: a retry that re-anchors under
/// it repeats the same under-fold until the resume budget runs out.
#[tokio::test(flavor = "multi_thread")]
async fn an_unadopted_chain_past_the_bundle_is_retired_and_the_pull_completes() -> anyhow::Result<()>
{
    let payload: Vec<u8> = (0..8 * 1024 * 1024u32).map(|i| (i % 239) as u8).collect();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(1_000_000_000u64);
    let lane = lane_with_proved_frontier(&client_signer, deposit, 1)?;
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&lane)?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    // A zero ramp divisor opens the full ceiling at once, so the node streams
    // the whole blob before it has read the opening voucher.
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
        |deps| deps.credit_ramp_divisor = 0,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let mut ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    ctx.prior_amount = lane.last_amount();
    ctx.prior_bytes_delivered = lane.last_bytes_delivered();
    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x2257,
        Duration::from_secs(8),
    )
    .await
    .map_err(|e| anyhow::anyhow!("resumed fetch: {e:#}"))?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "the resumed fetch must recover the full blob, got {} of {} bytes",
        got.len(),
        payload.len()
    );
    let healed = store
        .load_all()?
        .first()
        .map(LaneState::owed)
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        healed > lane.owed(),
        "the healed stream must pay past the live claim: {} -> {healed}",
        lane.owed()
    );
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_voucher_rejected_total")? == 1,
        "the heal costs exactly one rejected voucher"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #2169: the path that leaves a persisted watermark behind the node's chain.
/// One process pulls two blobs over one lane ledger, the way a bundle pull
/// drives its entries, and persists after the first only: it exits before the
/// second entry's persist. The node proved the second entry's reveals, so the
/// next process resumes from a watermark that trails the node's frontier. Its
/// first voucher under-folds, the node rejects it once with the bundle, and the
/// client folds the bundle and completes.
#[tokio::test(flavor = "multi_thread")]
async fn a_process_that_exits_before_its_last_persist_heals_in_one_rejection() -> anyhow::Result<()>
{
    let payload_a: Vec<u8> = (0..3 * 1024 * 1024u32).map(|i| (i % 251) as u8).collect();
    let payload_b: Vec<u8> = (0..3 * 1024 * 1024u32).map(|i| (i % 241) as u8).collect();
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, Arc::clone(&store), RATE_PER_MB, 16).await?;
    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let sd = slash_domain();
    let deadlines = PullDeadlines::whole_transfer(Duration::from_secs(15));

    // The first process: one ledger across both entries. It persists after
    // the first entry, then exits before the second entry's persist.
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);
    let ledger = Arc::new(PoolLedger::new(Cumulative::default()));
    let fetch_shared = |hash: decdn_cache::Hash, ts: u64| {
        stream_fetch_shared(
            &client_ep,
            target.clone(),
            &ctx,
            &ledger,
            &sd,
            server_eth.address(),
            *hash.as_bytes(),
            0,
            ts,
            deadlines,
            0,
            0,
        )
    };
    fetch_shared(hash_a, 0x2169_0001)
        .await
        .map_err(|e| anyhow::anyhow!("entry A: {e:#}"))?;
    let persisted = ledger.committed();
    fetch_shared(hash_b, 0x2169_0002)
        .await
        .map_err(|e| anyhow::anyhow!("entry B: {e:#}"))?;
    let node_claim = store
        .load_all()?
        .first()
        .map(LaneState::owed)
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        node_claim > persisted.amount,
        "the node proved past the persisted watermark: {node_claim} vs {}",
        persisted.amount
    );
    let rejected_before = counter(&metrics, "decdn_serve_stream_voucher_rejected_total")?;

    // The next process resumes from the persisted watermark.
    let mut next = pool_context(&client_ep, Arc::clone(&signer), deposit);
    next.prior_amount = persisted.amount;
    next.prior_bytes_delivered = persisted.bytes;
    let got = stream_fetch(
        &client_ep,
        target,
        &next,
        &sd,
        server_eth.address(),
        *hash_a.as_bytes(),
        0,
        0x2169_0003,
        Duration::from_secs(8),
    )
    .await
    .map_err(|e| anyhow::anyhow!("resumed fetch: {e:#}"))?;
    anyhow::ensure!(
        got.as_ref() == payload_a.as_slice(),
        "the resumed fetch recovers blob A"
    );
    let healed = store
        .load_all()?
        .first()
        .map(LaneState::owed)
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        healed > node_claim,
        "the healed stream pays past the node's claim: {node_claim} -> {healed}"
    );
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_voucher_rejected_total")? == rejected_before + 1,
        "the heal costs exactly one rejected voucher"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Resume with a NON-EMPTY proof spine (#1060): a ~200 KiB blob spans many 16 KiB
/// chunk groups, so the offset resume exercises the production
/// `export_bao_range` ↔ verifying-decoder pair over real proof PARENT
/// nodes — not the degenerate single-leaf tree `client_byte_offset_returns_suffix`
/// covers. The non-group-aligned offset (70 KiB) also verifies the decoder trims
/// the leading bytes of the widened [64 KiB, 200 KiB) fetch back to the request.
#[tokio::test(flavor = "multi_thread")]
async fn client_byte_offset_returns_suffix_multi_group() -> anyhow::Result<()> {
    let payload: Vec<u8> = (0..204_800u32).map(|i| (i % 251) as u8).collect();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);

    // 70 KiB: past the first four 16 KiB groups and NOT group-aligned, so the
    // serve widens down to the 64 KiB boundary and the decoder trims 6 KiB.
    let offset = 70 * 1024u64;
    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        offset,
        0xfeed,
        Duration::from_secs(15),
    )
    .await?;

    let off = usize::try_from(offset)?;
    let suffix = payload
        .get(off..)
        .ok_or_else(|| anyhow::anyhow!("offset past payload"))?;
    anyhow::ensure!(
        got.as_ref() == suffix,
        "multi-group offset fetch must return the trimmed suffix"
    );
    let persisted = store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    // ADR 038: metered quantity is the bao WIRE size of the widened, aligned range
    // — here strictly larger than the content suffix, because the proof spine
    // carries interior parent nodes (the single-leaf sibling has none).
    let wire = support::bao_wire_len(payload.len() as u64, offset, 0);
    let content_suffix = payload.len() as u64 - offset;
    anyhow::ensure!(
        wire > content_suffix,
        "a multi-group range must carry proof parents (wire {wire} > content {content_suffix})"
    );
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(wire),
        "bytes_delivered should be the aligned bao wire size {wire}, got {}",
        only.last_bytes_delivered()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// `byte_offset` resumes from a partial position: the requester receives only
/// the suffix and the node prices only the delivered bytes.
#[tokio::test(flavor = "multi_thread")]
async fn client_byte_offset_returns_suffix() -> anyhow::Result<()> {
    let payload: Vec<u8> = (0..4096u32).map(|i| (i % 251) as u8).collect();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);

    let offset = 1000u64;
    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        offset,
        0xfeed,
        Duration::from_secs(15),
    )
    .await?;

    let off = usize::try_from(offset)?;
    let suffix = payload
        .get(off..)
        .ok_or_else(|| anyhow::anyhow!("offset past payload"))?;
    anyhow::ensure!(
        got.as_ref() == suffix,
        "offset fetch must return the suffix"
    );
    let persisted = store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    // ADR 038: metered quantity is bao wire bytes (serve aligns up to the 16 KiB group)
    let wire = support::bao_wire_len(payload.len() as u64, offset, 0);
    anyhow::ensure!(
        only.last_bytes_delivered() == U256::from(wire),
        "bytes_delivered should be the aligned bao wire size {wire}, got {}",
        only.last_bytes_delivered()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #252: the requester rejects a `rate_per_mb == 0` response on receive. A
/// handler configured with rate 0 (and floor 0) signs a zero-rate response;
/// `stream_fetch` must refuse it before paying anything.
#[tokio::test(flavor = "multi_thread")]
async fn client_rejects_zero_rate_response() -> anyhow::Result<()> {
    let payload = b"zero-rate must be refused on receive".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    // rate 0 → the response advertises rate_per_mb = 0.
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        0,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, client_signer, deposit);

    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x1234,
        Duration::from_secs(10),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("zero-rate response must be rejected"))?;
    anyhow::ensure!(
        err.to_string().contains("rate") || err.to_string().contains("zero"),
        "error should mention the zero rate: {err}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #327 boundary + #848 free-egress: a stream request for a lane the node has
/// never persisted is refused *pre-serve* — the node signs `ok: false` with the
/// delivery-side `NotFound` code and ships zero bytes. It never serves a free
/// first chunk (or the whole blob, if smaller) and then rejects the voucher
/// mid-stream with `VoucherRejected { WrongPool }`. The 1.5 MiB blob (larger
/// than the chunk) proves the gate fires independent of blob size — not just
/// for sub-interval blobs. Asserting on the
/// server's `StreamResponse` (rather than the buyer's error string) proves the
/// success path was never entered: an `ok: true` would have streamed bytes.
#[tokio::test(flavor = "multi_thread")]
async fn client_unknown_lane_is_rejected() -> anyhow::Result<()> {
    let payload = vec![0xABu8; 1_572_864]; // 1.5 MiB — would cross a chunk if served
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    // Empty store: the lane is unknown to the node.
    let store: Arc<dyn PoolStateStore> = Arc::new(MemoryPoolStateStore::new());
    let (target, _server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, store, RATE_PER_MB, 16).await?;

    // A bound client whose lane is not in the (empty) store: the binding
    // resolves a lane key, but no lane exists for it, so the serve is refused as
    // an unknown lane (#848). Drive the raw path so we read the server's first
    // reply directly.
    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let signer = PrivateKeySigner::random();
    let ext = binding_ext(&signer, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x5678,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), resp_ext) => {
            anyhow::ensure!(
                !resp.body.ok,
                "unknown lane must be refused pre-serve, not served"
            );
            anyhow::ensure!(
                matches!(
                    resp_ext.error,
                    Some(decdn_protocol::client::StreamError::NotFound)
                ),
                "expected NotFound, got {:?}",
                resp_ext.error
            );
        }
        other => anyhow::bail!("expected a pre-serve StreamResponse refusal, got {other:?}"),
    }

    // The wire `NotFound` is deliberately ambiguous, so the server-side
    // reason counter is the only place this is distinguishable from a cache
    // miss or owner mismatch (#876).
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_unknown_lane_total 1"
        ),
        "unknown-lane refusal must bump its reason counter"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1516 pre-serve deposit gate: a known, owned lane whose pool deposit cannot
/// cover the first credit window is refused *before* the node signs `ok: true`.
/// Without the gate the node signs and streams a whole window (one voucher
/// accounting interval) before the first voucher's pool-solvency check can fire
/// (`PoolExhausted`) — a free interval per request, on every request. The blob
/// exceeds the window, so the gate is what stops the stream, not the blob
/// running out. The deposit sits one base unit under the window's cost at
/// `RATE_PER_MB`.
#[tokio::test(flavor = "multi_thread")]
async fn client_underfunded_pool_is_refused_pre_serve() -> anyhow::Result<()> {
    // 6 MiB: larger than one credit window (the ramp floor).
    let payload = vec![0xABu8; 6 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let window_cost = min_payment(HARNESS_FLOOR_BYTES, RATE_PER_MB);
    let deposit = window_cost.saturating_sub(U256::from(1u64));

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    // Pool remaining sits one base unit under the floor's cost. A large
    // `credit_max` makes no difference here — the default (non-zero) ramp
    // divisor prices the gate at the floor, not the ceiling.
    let (target, _server_eth, server_ep, server_task, metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        deposit,
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let ext = binding_ext(&signer, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x1516,
    };
    // Raw, so the server's FIRST reply is read directly: an `ok: true` here would
    // mean bytes were already committed to the wire.
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), resp_ext) => {
            anyhow::ensure!(
                !resp.body.ok,
                "an underfunded pool must be refused pre-serve, not served"
            );
            // This requester seeded a KNOWN, OWNED lane and proved it with a client
            // binding, so it reaches the floor gate as a proven requester — and the
            // node speaks `Unfunded` (not the prober-facing `NotFound`) so its
            // funding recovery can run.
            anyhow::ensure!(
                matches!(
                    resp_ext.error,
                    Some(decdn_protocol::client::StreamError::Unfunded)
                ),
                "expected the Unfunded wire code, got {:?}",
                resp_ext.error
            );
        }
        other => anyhow::bail!("expected a pre-serve StreamResponse refusal, got {other:?}"),
    }

    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_insufficient_deposit_total 1"
        ),
        "the refusal must be distinguishable server-side"
    );
    // The acceptance criterion of #1516: zero bytes served. The lane never
    // advanced, so nothing was delivered and nothing was owed.
    let persisted = store.load_all()?;
    let state = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("the seeded lane must still be persisted"))?;
    anyhow::ensure!(
        state.last_bytes_delivered() == U256::ZERO && state.last_amount() == U256::ZERO,
        "a refused request must deliver zero bytes; got {} bytes / {} owed",
        state.last_bytes_delivered(),
        state.last_amount()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The `min(credit window, request span)` term of the #1516 gate. The gate
/// reserves what the node can actually front before the first voucher, which for
/// a sub-interval blob is the blob — not a whole chunk it will never
/// stream. Reserving a whole interval here would price this request far above
/// the ~3 the transfer really costs, and refuse a deposit that comfortably
/// covers it, turning a correctness fix into a regression for small blobs.
#[tokio::test(flavor = "multi_thread")]
async fn client_sub_interval_blob_serves_below_one_interval_cost() -> anyhow::Result<()> {
    let payload = vec![0x2Cu8; 262_144]; // 256 KiB — a fraction of one chunk
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(5u64); // < one interval's cost, > this blob's (~3)
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, store_dyn, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x2C01,
        Duration::from_secs(10),
    )
    .await?;
    anyhow::ensure!(got == payload, "the sub-interval blob must transfer intact");
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_insufficient_deposit_total 0"
        ),
        "a funded sub-interval request must not trip the deposit gate"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1669: with the ramp enabled (a non-zero `credit_ramp_divisor`), the gate
/// prices at `paid = 0` (the floor, [`HARNESS_FLOOR_BYTES`]), not the fully-ramped
/// `credit_max` ceiling. A deposit that covers exactly the floor's cost clears
/// the gate even though `credit_max` is configured far larger: unlike the
/// flat window (a zero divisor), a big ceiling does not mean the node fronts that much
/// before the first voucher.
#[tokio::test(flavor = "multi_thread")]
async fn client_deposit_gate_reserves_only_the_floor_by_default() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024; // far wider than the floor
    let payload = vec![0x77u8; 8 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        U256::from(HARNESS_FLOOR_COST),
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    // Pool remaining exactly covers the floor, not the 64 MiB ceiling.
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let (target, _server_eth, server_ep, server_task, _metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        U256::from(HARNESS_FLOOR_COST),
        CREDIT_MAX,
        2,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let ext = binding_ext(&signer, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x1477,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), _resp_ext) => anyhow::ensure!(
            resp.body.ok,
            "a deposit covering the floor must clear the gate regardless of credit_max"
        ),
        other => anyhow::bail!("expected a pre-serve StreamResponse acceptance, got {other:?}"),
    }

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1669: `credit_ramp_divisor = 0` opens the full `credit_max` ceiling
/// immediately — the pre-ramp flat-window behavior, now opt-in — so the
/// pre-serve gate must reserve the WHOLE ceiling, not the floor. A deposit that
/// only covers one interval is refused against a wider ceiling, exactly how
/// enabling the flat window would silently re-open the hole #1516 closes if the
/// gate only ever priced at the floor.
#[tokio::test(flavor = "multi_thread")]
async fn client_deposit_gate_scales_with_credit_max_when_ramp_disabled() -> anyhow::Result<()> {
    const CREDIT_MAX: u64 = 8 * 1024 * 1024; // two chunks — wider than the floor
    let payload = vec![0x77u8; 12 * 1024 * 1024]; // larger than the ceiling, so the ceiling binds
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        U256::from(HARNESS_FLOOR_COST),
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    // Pool remaining covers only the first chunk of the 8 MiB ceiling.
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let (target, _server_eth, server_ep, server_task, metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        U256::from(HARNESS_FLOOR_COST),
        CREDIT_MAX,
        0,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let ext = binding_ext(&signer, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x1477,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), _resp_ext) => anyhow::ensure!(
            !resp.body.ok,
            "a deposit covering one interval must not unlock the whole ceiling"
        ),
        other => anyhow::bail!("expected a pre-serve StreamResponse refusal, got {other:?}"),
    }
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_insufficient_deposit_total 1"
        ),
        "the credit-window refusal must bump the deposit counter"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The #1516 gate reserves remaining HEADROOM, not the gross deposit. Both
/// deposit authorities — `LaneState::stage_voucher` off-chain and
/// `PaymentPool._redeemVoucher` on-chain — compare the *cumulative*
/// voucher amount, so a long-lived lane that has already claimed most of its
/// cap has almost nothing left to spend. Here the gross deposit (100) is ten
/// times the window's cost and would sail through a gross-deposit check, while
/// the real headroom (5) cannot cover it. The `last_*` fields are private
/// (#751), so the spent-down watermark is built via `hydrate`.
#[tokio::test(flavor = "multi_thread")]
async fn client_spent_down_pool_is_refused_pre_serve() -> anyhow::Result<()> {
    let payload = vec![0x5Du8; 1_572_864]; // 1.5 MiB — well under one credit window
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        U256::from(100u64),
        0,
        U256::from(95u64),
        U256::from(9_961_472u64),
        Some([0x22; 65]),
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    // Gross deposit 100, but the pool has only 5 remaining after prior redeems —
    // the headroom the gate reserves against, ten times under the window cost.
    let (target, _server_eth, server_ep, server_task, metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        U256::from(5u64),
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let ext = binding_ext(&signer, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x5D01,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), _resp_ext) => anyhow::ensure!(
            !resp.body.ok,
            "a spent-down pool must be refused on headroom, not waved through on gross deposit"
        ),
        other => anyhow::bail!("expected a pre-serve StreamResponse refusal, got {other:?}"),
    }
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_insufficient_deposit_total 1"
        ),
        "the spent-down refusal must bump the deposit counter"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The resume arm of the #1516 gate's span (`byte_offset > 0`, `byte_len == 0`),
/// which is the shape `decdn get -o` sends when continuing a partial
/// download. The gate must price only the remaining tail, not the whole blob.
///
/// This is the arm with teeth. `decdn get` treats a `NotFound` on a resume as
/// evidence the partial file may belong to another blob, so it rewinds to
/// `byte_offset = 0` and re-downloads — and re-pays for — everything it already
/// had (`crates/cli/src/commands/fetch.rs`, `resume_may_be_stale`). A gate that
/// mispriced a resume as the whole blob would therefore not merely refuse: it
/// would silently double the user's bill on every interrupted large fetch.
///
/// Sized so the two readings diverge: a 1.4 MiB blob resumed at 1 MiB leaves a
/// ~0.4 MiB tail costing 4, while the whole blob would cost 14 and one window
/// 10. A deposit of 5 covers only the tail, so pricing anything but the tail
/// refuses.
#[tokio::test(flavor = "multi_thread")]
async fn client_resumed_range_is_priced_on_the_tail_not_the_whole_blob() -> anyhow::Result<()> {
    const TAIL_OFFSET: u64 = 1_048_576;
    let payload = vec![0x9Eu8; 1_468_006]; // 1.4 MiB
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        U256::from(5u64),
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    // Pool remaining 5 covers the ~0.4 MiB tail (cost 4) but not the whole blob.
    let (target, _server_eth, server_ep, server_task, metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        U256::from(5u64),
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let ext = binding_ext(&signer, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: TAIL_OFFSET,
        byte_len: 0,
        timestamp_us: 0x9E01,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), resp_ext) => anyhow::ensure!(
            resp.body.ok,
            "a resume funded for its tail must be served, not refused: {:?}",
            resp_ext.error
        ),
        other => anyhow::bail!("expected a signed StreamResponse, got {other:?}"),
    }
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_insufficient_deposit_total 0"
        ),
        "the resume must not trip the deposit gate"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The gate's boundary: `headroom == ceiling` must PASS, because the check is
/// `<` and a pool funded to exactly the window's cost can pay for it.
///
/// Left uncovered by the four refusal/serve tests — each sits strictly on one
/// side of the boundary, so flipping `<` to `<=` passes all of them while
/// refusing every exactly-funded pool with a lossy `NotFound` the CLI renders
/// as a missing blob. A `decdn get --working-deposit-micro-usdc` funded to the
/// computed cost is exactly this case.
#[tokio::test(flavor = "multi_thread")]
async fn client_headroom_equal_to_the_ceiling_is_served() -> anyhow::Result<()> {
    // Larger than the floor window, so the floor binds.
    let payload = vec![0xB0u8; 1_572_864];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let window_cost = min_payment(HARNESS_FLOOR_BYTES, RATE_PER_MB);

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        window_cost,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    // Pool remaining exactly equals the floor's cost — the `>=` boundary.
    let (target, _server_eth, server_ep, server_task, metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        window_cost,
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let ext = binding_ext(&signer, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0xB001,
    };
    // Only the pre-serve verdict is asserted. The transfer may still stop at a
    // later voucher — the ceiling is priced in content bytes while vouchers bill
    // wire bytes — and that is the mid-stream ceiling's job, not the gate's.
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), resp_ext) => anyhow::ensure!(
            resp.body.ok,
            "headroom exactly equal to the ceiling must be served: {:?}",
            resp_ext.error
        ),
        other => anyhow::bail!("expected a signed StreamResponse, got {other:?}"),
    }
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_insufficient_deposit_total 0"
        ),
        "an exactly-funded pool must not trip the deposit gate"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A `record` failure is a hard serve fault, not a clean in-band rejection:
/// the buffered lane store's `record` is expected to fail only on a poisoned
/// mutex (ADR 003 §Off-chain voucher state persistence), so `commit_one_proof`
/// treats it as a fault and aborts the stream rather than writing a `StreamError`
/// frame — the client sees a transport-level failure, and the store never
/// observes the advanced watermark.
#[tokio::test(flavor = "multi_thread")]
async fn client_store_record_failure_aborts_the_stream() -> anyhow::Result<()> {
    let payload = vec![0x5Au8; 4096];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let inner = MemoryPoolStateStore::new();
    inner.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store: Arc<dyn PoolStateStore> = Arc::new(FailingRecordStore { inner });

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        Arc::clone(&store),
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, client_signer.clone(), deposit);

    anyhow::ensure!(
        stream_fetch(
            &client_ep,
            target,
            &ctx,
            &slash_domain(),
            server_eth.address(),
            *hash.as_bytes(),
            0,
            0x9abc,
            Duration::from_secs(10),
        )
        .await
        .is_err(),
        "a store record failure must not complete the fetch"
    );
    // The stored row never advanced past the seed — the record failure never
    // reached the store, so nothing was ever accepted. (The handler's in-memory
    // lane does advance before the record; the aborted stream is what stops it
    // mattering.)
    let persisted = store
        .get(lane_key(client_signer.address()))?
        .ok_or_else(|| anyhow::anyhow!("lane row missing"))?;
    anyhow::ensure!(
        persisted.last_bytes_delivered() == U256::ZERO,
        "a failed record must not advance the watermark, got {}",
        persisted.last_bytes_delivered()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Fetch a small blob over a lane whose capability expires at `expiry`, from a
/// handler built with the default redeem interval. Returns the fetch error, or
/// `None` when the fetch completed.
async fn fetch_on_a_lane_expiring_at(expiry: u64) -> anyhow::Result<Option<String>> {
    let payload = vec![0x5Au8; 4096];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    let mut lane = LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    );
    lane.expiry = expiry;
    store.record(&lane)?;
    let store_dyn: Arc<dyn PoolStateStore> = store;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, client_signer, deposit);

    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x9abd,
        Duration::from_secs(10),
    )
    .await
    .err()
    .map(|e| e.to_string());

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(err)
}

/// The node's capability-expiry margin at the default redeem interval.
const DEFAULT_EXPIRY_MARGIN: u64 = decdn_common::config::capability_expiry_margin_secs(
    decdn_common::config::DEFAULT_REDEEM_INTERVAL_SECS,
);

/// The current Unix second.
fn unix_now() -> anyhow::Result<u64> {
    Ok(std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)?
        .as_secs())
}

/// A lane whose capability `expiry` is already in the past is refused at
/// admission with a signed `Unfunded` (#751): the requester holds the lane, so
/// it is proven, and the fix is a fresh capability (ADR 005 §Open-time refusal
/// classes).
#[tokio::test(flavor = "multi_thread")]
async fn client_expired_capability_is_refused_unfunded() -> anyhow::Result<()> {
    // Unix second `1`: long past, so admission refuses the lane.
    let err = fetch_on_a_lane_expiring_at(1)
        .await?
        .ok_or_else(|| anyhow::anyhow!("an expired lane must be refused"))?;
    anyhow::ensure!(
        err.contains("Unfunded"),
        "an expired grant should be refused Unfunded: {err}"
    );
    Ok(())
}

/// A capability that has not yet expired, but expires within the node's margin
/// (one redeem interval plus the redeemer's landing slack), is refused at
/// admission with `Unfunded` (#2242). A voucher accepted that close to expiry
/// could miss the next sweep and redeem for 0.
#[tokio::test(flavor = "multi_thread")]
async fn client_capability_inside_the_expiry_margin_is_refused_unfunded() -> anyhow::Result<()> {
    let expiry = unix_now()?
        .saturating_add(DEFAULT_EXPIRY_MARGIN)
        .saturating_sub(1);
    let err = fetch_on_a_lane_expiring_at(expiry)
        .await?
        .ok_or_else(|| anyhow::anyhow!("a capability inside the margin must be refused"))?;
    anyhow::ensure!(
        err.contains("Unfunded"),
        "a capability inside the margin should be refused Unfunded: {err}"
    );
    Ok(())
}

/// A capability whose expiry lies beyond the node's margin is served (#2242).
#[tokio::test(flavor = "multi_thread")]
async fn client_capability_beyond_the_expiry_margin_is_served() -> anyhow::Result<()> {
    let expiry = unix_now()?
        .saturating_add(DEFAULT_EXPIRY_MARGIN)
        .saturating_add(60);
    let err = fetch_on_a_lane_expiring_at(expiry).await?;
    anyhow::ensure!(
        err.is_none(),
        "a capability beyond the margin must be served: {err:?}"
    );
    Ok(())
}

/// A pool-state store seeded with one lane on a pool owned by a fresh client signer.
/// Returns the store, that client signer, and the deposit.
fn seeded_store() -> anyhow::Result<(Arc<dyn PoolStateStore>, Arc<PrivateKeySigner>, U256)> {
    let signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    Ok((store, signer, deposit))
}

/// Spin up a server endpoint running a `ClientHandler` over `cache`/`store`,
/// returning the dialable target, the node's Ethereum signer (for `slash_sig`
/// verification), the server endpoint, and its accept-loop handle.
async fn spawn_handler_server(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    rate: u64,
    max_streams: usize,
) -> anyhow::Result<(
    EndpointAddr,
    Arc<PrivateKeySigner>,
    Endpoint,
    tokio::task::JoinHandle<()>,
)> {
    let (target, server_eth, server_ep, server_task, _metrics) =
        spawn_handler_server_with_metrics(cache, store, rate, max_streams).await?;
    Ok((target, server_eth, server_ep, server_task))
}

/// As `spawn_handler_server`, but also returns the server's `Arc<Metrics>` so a
/// test can assert a reject counter advanced (#876). The reject path signs a
/// deliberately lossy wire error, so the counter is the only server-side place
/// the precise reason is observable.
async fn spawn_handler_server_with_metrics(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    rate: u64,
    max_streams: usize,
) -> anyhow::Result<(
    EndpointAddr,
    Arc<PrivateKeySigner>,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_limited(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        rate,
        max_streams,
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((target, server_eth, server_ep, server_task, metrics))
}

/// A [`decdn_node::pool_view::PoolView`] returning a fixed `remaining` (and a
/// benign, non-denied `owner`) for every pool. The floor-`M` pre-serve deposit
/// gate reads the pool's on-chain `remaining` through this view; the loopback
/// suite has no chain, so the deposit-gate tests wire this stub to drive the gate
/// with a known headroom.
#[derive(Debug)]
struct FixedRemainingPoolView {
    owner: Address,
    remaining: U256,
}

#[async_trait]
impl decdn_node::pool_view::PoolView for FixedRemainingPoolView {
    async fn status(&self, _pool_id: B256) -> Option<decdn_node::pool_view::PoolStatus> {
        Some(decdn_node::pool_view::PoolStatus {
            owner: self.owner,
            remaining: self.remaining,
            lifecycle: decdn_node::pool_view::Lifecycle::Open,
        })
    }
}

/// A [`PoolView`](decdn_node::pool_view::PoolView) for an open, well-funded
/// pool whose every signer reads as registered with `spent == cap`: the node
/// refuses the signer at admission (`SignerCapExhausted`), which reaches the
/// wire as `Unfunded`.
#[derive(Debug)]
struct DrainedSignerPoolView {
    owner: Address,
    cap: u64,
}

#[async_trait]
impl decdn_node::pool_view::PoolView for DrainedSignerPoolView {
    async fn status(&self, _pool_id: B256) -> Option<decdn_node::pool_view::PoolStatus> {
        Some(decdn_node::pool_view::PoolStatus {
            owner: self.owner,
            remaining: U256::from(50_000_000u64),
            lifecycle: decdn_node::pool_view::Lifecycle::Open,
        })
    }

    async fn signer_authorization(
        &self,
        _pool_id: B256,
        _signer: Address,
    ) -> Option<decdn_incentive::payment_pool::SignerAuthorization> {
        Some(self.registered())
    }
}

impl DrainedSignerPoolView {
    /// The drained registration the node reads.
    const fn registered(&self) -> decdn_incentive::payment_pool::SignerAuthorization {
        decdn_incentive::payment_pool::SignerAuthorization::Registered {
            cap: self.cap,
            expiry: u64::MAX,
            spent: self.cap,
        }
    }
}

/// A node that refuses a drained capability signer at admission answers
/// `Unfunded`: the requester holds a verified binding for a registered signer,
/// so it is proven, and the class alone tells it to recover its funding (ADR 005
/// §Open-time refusal classes, #2338).
#[tokio::test(flavor = "multi_thread")]
async fn a_drained_signer_refused_at_admission_is_unfunded() -> anyhow::Result<()> {
    use decdn_client::PeerSource;
    use decdn_client::source::BlobSource as _;

    let payload = vec![0x5Du8; 300_000];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(50_000_000u64);
    let pool_store = Arc::new(MemoryPoolStateStore::new());
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = pool_store;
    let view = Arc::new(DrainedSignerPoolView {
        owner: operator_addr(),
        cap: 40,
    });
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
        |deps| deps.pool_view = Some(Arc::clone(&view) as _),
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, Arc::clone(&client_signer), deposit);
    let ledger = Arc::new(ctx.new_ledger());
    let ctx = Arc::new(std::sync::Mutex::new(ctx));
    let slash = slash_domain();
    let deadlines = PullDeadlines::new(Duration::from_secs(10), Duration::from_secs(10), 0)?;
    let source = || {
        PeerSource::new(
            &client_ep,
            target.clone(),
            Arc::clone(&ctx),
            Arc::clone(&ledger),
            &slash,
            server_eth.address(),
            decdn_protocol::client::NO_NAMESPACE,
            0,
            u64::MAX,
            deadlines,
            None,
        )
    };
    let range = decdn_bao_range::align_range(0, 0, u64::try_from(payload.len())?)?;

    let refused = source()
        .open(*hash.as_bytes(), range)
        .await
        .err()
        .ok_or_else(|| anyhow::anyhow!("the node must refuse the drained signer"))?;
    anyhow::ensure!(
        refused
            .downcast_ref::<decdn_client::UpstreamRefused>()
            .is_some_and(|r| *r.error() == StreamError::Unfunded),
        "a drained signer's admission refusal is Unfunded, got: {refused:#}"
    );
    let encoded = metrics.encode()?;
    anyhow::ensure!(
        metric_line_present(
            &encoded,
            "decdn_serve_stream_rejected_signer_cap_exhausted_total 1"
        ),
        "the refusal must count as signer_cap_exhausted:\n{encoded}"
    );

    shutdown([server_task], [&server_ep, &client_ep]).await?;
    Ok(())
}

/// A [`PoolView`](decdn_node::pool_view::PoolView) for a funded pool that is
/// `Closing` on-chain.
#[derive(Debug)]
struct ClosingPoolView {
    owner: Address,
}

#[async_trait]
impl decdn_node::pool_view::PoolView for ClosingPoolView {
    async fn status(&self, _pool_id: B256) -> Option<decdn_node::pool_view::PoolStatus> {
        Some(decdn_node::pool_view::PoolStatus {
            owner: self.owner,
            remaining: U256::from(50_000_000u64),
            lifecycle: decdn_node::pool_view::Lifecycle::Closing { deadline: u64::MAX },
        })
    }
}

/// A node does not serve on a `Closing` pool (ADR 003 §Pool solvency). It
/// answers a requester that holds a lane on the pool `Unfunded`, so the owner
/// opens a new pool, and an unbound requester `NotFound`, so the pool's state
/// stays unmappable (ADR 005 §Open-time refusal classes).
#[tokio::test(flavor = "multi_thread")]
async fn a_closing_pool_is_unfunded_to_its_lane_and_not_found_to_anyone_else() -> anyhow::Result<()>
{
    let payload = vec![0x6Cu8; 300_000];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        U256::from(10_000_000u64),
        u64::MAX,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store;
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let owner = operator_addr();
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
        |deps| deps.pool_view = Some(Arc::new(ClosingPoolView { owner })),
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let conn = client_ep
        .connect(target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    let ext = binding_ext(&signer, client_node_id)?;
    let (proven, proven_ext) = open_expecting_refusal(&conn, *hash.as_bytes(), Some(&ext)).await?;
    anyhow::ensure!(!proven.body.ok, "a closing pool must not be served");
    anyhow::ensure!(
        matches!(proven_ext.error, Some(StreamError::Unfunded)),
        "the lane's requester must hear Unfunded, got {:?}",
        proven_ext.error
    );

    // A binding verifies once per connection, so the unbound request goes on a
    // fresh one.
    conn.close(0u32.into(), b"done");
    let stranger = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let (unbound, unbound_ext) = open_expecting_refusal(&stranger, *hash.as_bytes(), None).await?;
    anyhow::ensure!(!unbound.body.ok, "a closing pool must not be served");
    anyhow::ensure!(
        matches!(unbound_ext.error, Some(StreamError::NotFound)),
        "an unbound requester must hear NotFound, got {:?}",
        unbound_ext.error
    );
    let encoded = metrics.encode()?;
    anyhow::ensure!(
        metric_line_present(&encoded, "decdn_serve_stream_rejected_pool_closing_total 2"),
        "both refusals must count as pool_closing:\n{encoded}"
    );

    stranger.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The harness's fixed floor cost: `credit_window(chunk, paid = 0)` collapses
/// to [`HARNESS_FLOOR_BYTES`] (one chunk plus the verify lag) regardless of
/// `credit_max` whenever `credit_ramp_divisor` is non-zero (ADR 003 §Credit
/// window, #1669). Priced as `min_payment` prices it, rounding up, so it
/// tracks the floor rather than a number kept in step by hand.
const HARNESS_FLOOR_COST: u64 =
    (HARNESS_FLOOR_BYTES * RATE_PER_MB).div_ceil(decdn_incentive::BYTES_PER_MB);

/// `spawn_handler_server_with_metrics` with a fixed-`remaining` pool-view wired
/// and an explicit credit-window ceiling/ramp divisor — the setup the floor-`M`
/// pre-serve deposit-gate tests need so the gate reads a known pool headroom.
async fn spawn_handler_server_with_pool(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    remaining: U256,
    credit_max: u64,
    credit_ramp_divisor: u64,
) -> anyhow::Result<(
    EndpointAddr,
    Arc<PrivateKeySigner>,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let owner = operator_addr();
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        |deps| {
            deps.pool_view = Some(Arc::new(FixedRemainingPoolView { owner, remaining }));
            deps.credit_max = credit_max;
            deps.credit_ramp_divisor = credit_ramp_divisor;
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((target, server_eth, server_ep, server_task, metrics))
}

/// A [`PoolView`] whose `remaining` collapses from `high` to `low` the instant a
/// shared `drained` flag is set — the fixture for a pool that drains mid-flight
/// (other lanes redeeming its `remaining` down) so the mid-stream pool-solvency
/// re-check can be driven end-to-end. `owner` is fixed.
#[derive(Debug)]
struct DrainingPoolView {
    owner: Address,
    high: U256,
    low: U256,
    drained: Arc<std::sync::atomic::AtomicBool>,
}

#[async_trait]
impl decdn_node::pool_view::PoolView for DrainingPoolView {
    async fn status(&self, _pool_id: B256) -> Option<decdn_node::pool_view::PoolStatus> {
        let remaining = if self.drained.load(std::sync::atomic::Ordering::Relaxed) {
            self.low
        } else {
            self.high
        };
        Some(decdn_node::pool_view::PoolStatus {
            owner: self.owner,
            remaining,
            lifecycle: decdn_node::pool_view::Lifecycle::Open,
        })
    }
}

/// `spawn_handler_server_with_pool` wired with a [`DrainingPoolView`] instead of a
/// fixed one, so a test can drop the pool's `remaining` mid-stream by flipping the
/// shared `drained` flag.
async fn spawn_handler_server_with_draining_pool(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    high: U256,
    low: U256,
    drained: Arc<std::sync::atomic::AtomicBool>,
    recheck_interval: Duration,
) -> anyhow::Result<(
    EndpointAddr,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let owner = operator_addr();
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        |deps| {
            deps.pool_view = Some(Arc::new(DrainingPoolView {
                owner,
                high,
                low,
                drained,
            }));
            deps.pool_recheck_interval = Some(recheck_interval);
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((target, server_ep, server_task, metrics))
}

/// Mid-stream `PoolExhausted`: a live stream stops IN-BAND at a voucher boundary
/// once its pool can no longer fund the pool's already-committed floor credit.
///
/// Two DISTINCT lanes on ONE pool — different signers, so their voucher
/// watermarks are independent (no shared-lane aggregate voucher): a "holder" (A)
/// that parks mid-delivery holding its live floor reservation, and a "driven"
/// stream (B) whose first voucher boundary the test crosses AFTER draining the
/// pool. When B pays interval 1 it releases its own floor, leaving A's floor as
/// the pool's committed credit; the drained `remaining` (`low = 10`) no longer
/// covers it (one `HARNESS_FLOOR_COST`, `M = 0`), so B's boundary re-check emits
/// a clean `PoolExhausted` and finishes the stream — not a QUIC reset. Per the
/// loopback close-code caveat we assert the received reason, never an app code.
///
/// The handler runs with a ZERO recheck interval so the mid-stream re-check
/// fires at every voucher boundary — this test isolates the drain→`PoolExhausted`
/// path itself; the wall-clock cadence gating is covered separately by
/// [`pool_recheck_gated_by_interval_lets_drained_stream_continue`] and
/// [`pool_recheck_fires_after_interval_on_drained_pool`].
#[tokio::test(flavor = "multi_thread")]
async fn mid_stream_pool_drain_stops_with_pool_exhausted() -> anyhow::Result<()> {
    // A is > one interval so it parks (never finishes) holding its reservation; B
    // is multi-interval so its first boundary is `!done` and the re-check runs.
    let payload_a = vec![0xA1u8; 6 * 1024 * 1024];
    let payload_b = vec![0xB2u8; 16 * 1024 * 1024];
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;

    let signer_a = Arc::new(PrivateKeySigner::random());
    let signer_b = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    for signer in [&signer_a, &signer_b] {
        store.record(&LaneState::hydrate(
            pool_id(),
            signer.address(),
            operator_addr(),
            U256::from(10_000_000u64),
            0,
            U256::ZERO,
            U256::ZERO,
            None,
            decdn_incentive::LaneChain::NONE,
        ))?;
    }
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    // `high` (10_000) covers both lanes' admission floors; `low` covers neither,
    // so once A's floor is the pool's only committed credit
    // `remaining − M < HARNESS_FLOOR_COST` and B's re-check trips. M = 0 here.
    let drained = Arc::new(std::sync::atomic::AtomicBool::new(false));
    let (target, server_ep, server_task, metrics) = spawn_handler_server_with_draining_pool(
        cache,
        store_dyn,
        U256::from(10_000u64),
        // Drained: strictly under ONE floor, so the mid-stream re-check cannot
        // cover even the single reservation still held. Derived from the floor
        // rather than hard-coded, so it tracks the payment quantum.
        U256::from(HARNESS_FLOOR_COST - 1),
        Arc::clone(&drained),
        Duration::ZERO,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    let ext_a = binding_ext(&signer_a, client_node_id)?;
    let ext_b = binding_ext(&signer_b, client_node_id)?;

    // A: admit (reserves one floor), deliver its first interval, then leave it
    // PARKED reading a voucher we never send — it holds its live floor reservation
    // for the pool's whole `committed` while the test runs, well inside the 10s
    // no-progress proof wait. `_send_a` is kept so the stream stays open.
    let (_send_a, mut recv_a) = open_paid_stream(&conn, *hash_a.as_bytes(), Some(&ext_a)).await?;
    read_exact_chunks(&mut recv_a, HARNESS_FLOOR_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv_a).await?;

    // B: admit (reserves a second floor — `high` covers both), deliver its first
    // interval and the verify lag, park.
    let (mut send_b, mut recv_b) =
        open_paid_stream(&conn, *hash_b.as_bytes(), Some(&ext_b)).await?;
    read_exact_chunks(&mut recv_b, HARNESS_FLOOR_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv_b).await?;

    // Drain the pool: `remaining` now reads `low` on every subsequent `status()`.
    drained.store(true, std::sync::atomic::Ordering::Relaxed);

    // Pay B's first interval. The server commits it, releases B's own floor, then
    // runs the mid-stream re-check: A's still-held floor is the pool's committed
    // credit and the drained `remaining` cannot cover it, so B stops in-band.
    pay_cumulative(&mut send_b, &signer_b, HARNESS_INTERVAL_BYTES).await?;

    match tokio::time::timeout(Duration::from_secs(10), read_client_msg(&mut recv_b)).await?? {
        ClientMessage::StreamError(decdn_protocol::client::StreamError::VoucherRejected {
            reason,
            bundle,
        }) => {
            anyhow::ensure!(
                reason == VoucherRejectReason::PoolExhausted,
                "expected PoolExhausted, got {reason:?}"
            );
            anyhow::ensure!(
                bundle.is_none(),
                "PoolExhausted is not watermark-gated, so no bundle attaches"
            );
        }
        other => anyhow::bail!("expected VoucherRejected {{ PoolExhausted }}, got {other:?}"),
    }

    // The stream ended CLEANLY (in-band error then `finish`), not a QUIC reset:
    // the next read hits the FIN as a clean end-of-stream, never another frame.
    anyhow::ensure!(
        tokio::time::timeout(Duration::from_secs(5), read_client_msg(&mut recv_b))
            .await?
            .is_err(),
        "after PoolExhausted the server finishes the stream; no further frame is sent"
    );
    support::assert_inbound_failures_attributed(&metrics, 1).await?;
    anyhow::ensure!(
        counter(
            &metrics,
            "decdn_serve_stream_midstream_pool_exhausted_total"
        )? == 1,
        "the mid-stream stop must be counted"
    );

    // Closing the connection ends the parked holder A unpaid: a decline.
    conn.close(0u32.into(), b"done");
    support::assert_inbound_failures_attributed(&metrics, 2).await?;
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_client_declined_total")? == 1,
        "the parked holder ends unpaid"
    );
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Live handles for the wall-clock recheck-cadence tests, produced by
/// [`setup_recheck_holder_and_driven`]. `_send_a`/`_recv_a` keep the holder lane
/// (A) open so it stays PARKED holding its floor reservation while a test drives B.
struct RecheckFixture {
    conn: Connection,
    client_ep: Endpoint,
    server_ep: Endpoint,
    server_task: tokio::task::JoinHandle<()>,
    _send_a: SendStream,
    _recv_a: RecvStream,
    send_b: SendStream,
    recv_b: RecvStream,
    signer_b: Arc<PrivateKeySigner>,
    drained: Arc<std::sync::atomic::AtomicBool>,
}

/// Shared fixture for the wall-clock recheck-cadence tests. Two DISTINCT lanes (A
/// the holder, B the driven) on one pool served by a [`DrainingPoolView`] with the
/// given `recheck_interval`. Admits both, delivers each its first interval, and
/// leaves A PARKED holding its floor reservation — so once the pool is drained and
/// B releases its own floor, A's floor is the pool's committed credit that the
/// drained `remaining` cannot cover (one `HARNESS_FLOOR_COST`,
/// `M = 0`). B is 16 MiB (4 intervals), so its first boundary is `!done`.
async fn setup_recheck_holder_and_driven(
    recheck_interval: Duration,
) -> anyhow::Result<RecheckFixture> {
    let payload_a = vec![0xA1u8; 6 * 1024 * 1024];
    let payload_b = vec![0xB2u8; 16 * 1024 * 1024];
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;

    let signer_a = Arc::new(PrivateKeySigner::random());
    let signer_b = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    for signer in [&signer_a, &signer_b] {
        store.record(&LaneState::hydrate(
            pool_id(),
            signer.address(),
            operator_addr(),
            U256::from(10_000_000u64),
            0,
            U256::ZERO,
            U256::ZERO,
            None,
            decdn_incentive::LaneChain::NONE,
        ))?;
    }
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    let drained = Arc::new(std::sync::atomic::AtomicBool::new(false));
    let (target, server_ep, server_task, _metrics) = spawn_handler_server_with_draining_pool(
        cache,
        store_dyn,
        U256::from(10_000u64),
        // Drained: strictly under ONE floor, so the mid-stream re-check cannot
        // cover even the single reservation still held. Derived from the floor
        // rather than hard-coded, so it tracks the payment quantum.
        U256::from(HARNESS_FLOOR_COST - 1),
        Arc::clone(&drained),
        recheck_interval,
    )
    .await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    let ext_a = binding_ext(&signer_a, client_node_id)?;
    let ext_b = binding_ext(&signer_b, client_node_id)?;

    // A: admit (reserves one floor), deliver its first interval, then park reading a
    // voucher we never send — it holds its live floor reservation for the whole test.
    let (send_a, mut recv_a) = open_paid_stream(&conn, *hash_a.as_bytes(), Some(&ext_a)).await?;
    read_exact_chunks(&mut recv_a, HARNESS_FLOOR_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv_a).await?;

    // B: admit (a second floor, which `high` covers), deliver its floor, park.
    let (send_b, mut recv_b) = open_paid_stream(&conn, *hash_b.as_bytes(), Some(&ext_b)).await?;
    read_exact_chunks(&mut recv_b, HARNESS_FLOOR_BYTES).await?;
    assert_parked_awaiting_voucher(&mut recv_b).await?;

    Ok(RecheckFixture {
        conn,
        client_ep,
        server_ep,
        server_task,
        _send_a: send_a,
        _recv_a: recv_a,
        send_b,
        recv_b,
        signer_b,
        drained,
    })
}

/// Drive a paid stream to completion from the fixture's parked state and return the
/// total WIRE bytes received (bao content + proof, so `> ` the blob's content size).
///
/// A payment chunk spans one or a few delivery frames, so a per-frame voucher would sign
/// thousands of times; instead this pays one cumulative voucher per accumulated
/// voucher-interval (the efficient cadence the other loopback tests use). The
/// window ramp can leave a final sub-interval remainder the server parks on
/// awaiting payment — a read timeout is the park signal, so on a stall this settles
/// the outstanding remainder to unblock the server, then reads its `StreamEnd`.
async fn pay_and_read_to_end(
    send: &mut SendStream,
    recv: &mut RecvStream,
    signer: &PrivateKeySigner,
) -> anyhow::Result<u64> {
    // The fixture already delivered the floor and parked; pay its whole interval
    // upfront so the first loop read is not spent waiting out a park.
    let mut received = HARNESS_FLOOR_BYTES;
    let mut paid = HARNESS_INTERVAL_BYTES;
    pay_cumulative(send, signer, paid).await?;
    // The loop reads the stream again after a timeout, so the read must be cancel-safe.
    let mut reader = BufferedClientReader::default();
    loop {
        match tokio::time::timeout(Duration::from_secs(5), reader.read(recv)).await {
            Ok(msg) => match msg? {
                ClientMessage::ChunkData(chunk) => {
                    received = received.saturating_add(chunk.bytes().len() as u64);
                    // Pay up to the last whole interval received. Every span
                    // between two whole intervals prices exactly, so the
                    // rounded-up cumulative amount never underpays a span.
                    if received.saturating_sub(paid) >= HARNESS_INTERVAL_BYTES {
                        paid = received - received % HARNESS_INTERVAL_BYTES;
                        pay_cumulative(send, signer, paid).await?;
                    }
                }
                ClientMessage::StreamEnd => return Ok(received),
                other => {
                    anyhow::bail!("expected ChunkData or StreamEnd while draining, got {other:?}")
                }
            },
            // Read timed out: the server has parked. If a sub-interval remainder is
            // outstanding, settle it so `done` can fire; otherwise nothing we can pay
            // would advance the stream, so it is genuinely stuck.
            Err(_elapsed) => {
                anyhow::ensure!(
                    received > paid,
                    "stream stalled with nothing left to pay ({received} wire bytes received)"
                );
                pay_cumulative(send, signer, received).await?;
                paid = received;
            }
        }
    }
}

/// Wall-clock cadence, suppression half (ADR 003 §Pool solvency): with a re-check
/// interval far longer than the whole stream, the mid-stream re-check never comes
/// due, so a pool that drains mid-flight is NOT caught and B streams to completion.
/// A per-voucher-boundary check would trip `PoolExhausted` at B's first boundary
/// after the drain (that is exactly what
/// [`mid_stream_pool_drain_stops_with_pool_exhausted`] pins with a ZERO interval),
/// so B reaching `StreamEnd` across four boundaries proves the check fires at most
/// once per interval — here zero times.
#[tokio::test(flavor = "multi_thread")]
async fn pool_recheck_gated_by_interval_lets_drained_stream_continue() -> anyhow::Result<()> {
    // Longer than the whole (millisecond-scale) stream, so the re-check is never due.
    let mut fx = setup_recheck_holder_and_driven(Duration::from_secs(30)).await?;

    // Drain: every subsequent `status()` reports `low`, below A's committed floor.
    fx.drained.store(true, std::sync::atomic::Ordering::Relaxed);

    // Drive B to completion. With a per-boundary check the first payment after the
    // drain would trip `PoolExhausted`; the 30 s cadence gate suppresses every
    // check, so B receives the whole blob and ends with a clean `StreamEnd`.
    let received = pay_and_read_to_end(&mut fx.send_b, &mut fx.recv_b, &fx.signer_b).await?;
    anyhow::ensure!(
        received >= 16 * 1024 * 1024,
        "expected at least the full 16 MiB blob (wire = content + bao proof), received {received} bytes"
    );

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// Wall-clock cadence, firing half (ADR 003 §Pool solvency): once the re-check
/// interval has elapsed, the NEXT voucher boundary on a drained pool trips
/// `PoolExhausted`. We drain, wait past a short interval while B is parked (the
/// serve loop is blocked in the voucher read, so no check runs during the wait),
/// then pay B's first interval — by which point `last_pool_check.elapsed()` far
/// exceeds the interval, so the re-check runs and stops the stream in-band.
#[tokio::test(flavor = "multi_thread")]
async fn pool_recheck_fires_after_interval_on_drained_pool() -> anyhow::Result<()> {
    let interval = Duration::from_millis(300);
    let mut fx = setup_recheck_holder_and_driven(interval).await?;

    fx.drained.store(true, std::sync::atomic::Ordering::Relaxed);

    // Sleep past the interval so the next boundary is due. The wait only ever
    // lengthens `elapsed`, so the re-check is guaranteed due regardless of load.
    tokio::time::sleep(interval + Duration::from_millis(200)).await;

    // Pay B's first interval: the server commits it, releases B's own floor, then
    // runs the now-due re-check — A's still-held floor is the pool's committed
    // credit and the drained `remaining` cannot cover it, so B stops in-band.
    pay_cumulative(&mut fx.send_b, &fx.signer_b, HARNESS_INTERVAL_BYTES).await?;

    match tokio::time::timeout(Duration::from_secs(10), read_client_msg(&mut fx.recv_b)).await?? {
        ClientMessage::StreamError(decdn_protocol::client::StreamError::VoucherRejected {
            reason,
            bundle,
        }) => {
            anyhow::ensure!(
                reason == VoucherRejectReason::PoolExhausted,
                "expected PoolExhausted, got {reason:?}"
            );
            anyhow::ensure!(bundle.is_none(), "PoolExhausted attaches no bundle");
        }
        other => anyhow::bail!("expected VoucherRejected {{ PoolExhausted }}, got {other:?}"),
    }

    // Clean in-band stop, not a QUIC reset: the next read hits the FIN.
    anyhow::ensure!(
        tokio::time::timeout(Duration::from_secs(5), read_client_msg(&mut fx.recv_b))
            .await?
            .is_err(),
        "after PoolExhausted the server finishes the stream; no further frame is sent"
    );

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// Wall-clock cadence, solvent half (ADR 003 §Pool solvency): a re-check that
/// comes due on a still-SOLVENT pool does not stop the stream. With a short
/// interval and no drain, the re-check fires mid-stream, reads `remaining = high`
/// (which covers the committed floor), and B streams to a clean `StreamEnd`.
#[tokio::test(flavor = "multi_thread")]
async fn solvent_pool_stream_completes_across_recheck_interval() -> anyhow::Result<()> {
    let interval = Duration::from_millis(300);
    // No drain: `remaining` stays `high` for the whole stream.
    let mut fx = setup_recheck_holder_and_driven(interval).await?;

    // Cross an interval boundary in wall-clock time before the next payment, so at
    // least one re-check is guaranteed due while the pool is solvent.
    tokio::time::sleep(interval + Duration::from_millis(200)).await;

    // The re-check fires mid-stream, reads `remaining = high` (which covers the
    // committed floor), and lets B stream to a clean `StreamEnd`.
    let received = pay_and_read_to_end(&mut fx.send_b, &mut fx.recv_b, &fx.signer_b).await?;
    anyhow::ensure!(
        received >= 16 * 1024 * 1024,
        "expected at least the full 16 MiB blob (wire = content + bao proof), received {received} bytes"
    );

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// Seed a fresh in-memory pool store with `n` DISTINCT-signer lanes on the one
/// [`pool_id`], each generously funded on its own capability so the only budget
/// that ever bites is the pool-level floor-credit bound. Returns the store and the
/// signers, one per lane. The aggregate-bound tests drive each signer as its own
/// lane so the property under test is "total free floor data across ALL lanes is
/// bounded to `remaining − M`", never a per-lane limit.
fn store_with_distinct_lanes(
    n: usize,
) -> anyhow::Result<(Arc<MemoryPoolStateStore>, Vec<Arc<PrivateKeySigner>>)> {
    let store = Arc::new(MemoryPoolStateStore::new());
    let mut signers = Vec::with_capacity(n);
    for _ in 0..n {
        let signer = Arc::new(PrivateKeySigner::random());
        store.record(&fresh_lane(signer.address(), U256::from(10_000_000u64)))?;
        signers.push(signer);
    }
    Ok((store, signers))
}

/// CORE security property (concurrent): with many DISTINCT-signer streams held open
/// at once, admissions stop as soon as `Σ live floors` would exceed `remaining −
/// M`. The bound is the per-pool live floor reservation — the hard money envelope
/// no fan-out of fresh signer keys can escape.
///
/// `remaining` is three [`HARNESS_FLOOR_COST`]s plus a slack under one floor,
/// `M = 0`: three lanes fit, a fourth does not. Each lane is opened on its own bi-stream,
/// reads one floor, and PARKS holding its live reservation; the streams stay open
/// (their send/recv halves are kept alive) so all three reservations are held
/// concurrently. With three live floors held, a fourth distinct lane is refused
/// `NotFound`. Non-vacuous: a fourth lane on its own would fit (`40 ≤ 140`); it is
/// refused only because the three concurrent reservations already committed the
/// budget.
#[tokio::test(flavor = "multi_thread")]
async fn concurrent_distinct_lanes_bounded_to_pool_deposit() -> anyhow::Result<()> {
    let payload = vec![0x6Bu8; 6 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let affordable_floors = 3usize;
    // Slack strictly under one floor — see the sequential twin.
    let remaining = U256::from(u128::from(HARNESS_FLOOR_COST) * affordable_floors as u128 + 2);
    let (store, signers) = store_with_distinct_lanes(affordable_floors + 1)?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    let (target, _server_eth, server_ep, server_task, _metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        remaining,
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    // Admit and PARK three concurrent distinct lanes; keep every stream alive so its
    // live floor reservation is held for the duration.
    let mut held = Vec::new();
    for (i, signer) in signers.iter().take(affordable_floors).enumerate() {
        let ext = binding_ext(signer, client_node_id)?;
        let (send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
        read_exact_chunks(&mut recv, HARNESS_FLOOR_BYTES).await?;
        assert_parked_awaiting_voucher(&mut recv).await?;
        held.push((i, send, recv));
    }

    // Fourth concurrent distinct lane: refused, as `Σ live floors + floor >
    // remaining − M`.
    let fourth = signers
        .get(affordable_floors)
        .ok_or_else(|| anyhow::anyhow!("missing the fourth lane signer"))?;
    let ext = binding_ext(fourth, client_node_id)?;
    let (refusal, refusal_ext) =
        open_expecting_refusal(&conn, *hash.as_bytes(), Some(&ext)).await?;
    anyhow::ensure!(
        !refusal.body.ok,
        "the fourth concurrent lane must be refused while three live floors are held"
    );
    // A proven-owner lane refused by the pool ceiling gets `Unfunded`, not the
    // prober-facing `NotFound`.
    anyhow::ensure!(
        matches!(
            refusal_ext.error,
            Some(decdn_protocol::client::StreamError::Unfunded)
        ),
        "expected the Unfunded wire code, got {:?}",
        refusal_ext.error
    );

    drop(held);
    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A topped-up (high-`remaining`) pool serves many concurrent distinct lanes with
/// NO refusal — the Netflix case is unaffected by the floor-credit bound. The
/// control for the two bound tests above: the same concurrent distinct-lane setup,
/// but a `remaining` so large the bound never bites, so every lane is admitted and
/// served. `open_paid_stream` bails on any non-`ok` `StreamResponse`, so all six
/// opens succeeding IS the "no refusal" assertion; reading a floor from each proves
/// each was really served, not merely admitted.
#[tokio::test(flavor = "multi_thread")]
async fn topped_up_pool_serves_many_lanes() -> anyhow::Result<()> {
    let payload = vec![0x7Cu8; 6 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    // Six lanes × one floor = 240 µUSDC of live credit, dwarfed by `remaining`.
    let lanes = 6usize;
    let remaining = U256::from(10_000_000u64);
    let (store, signers) = store_with_distinct_lanes(lanes)?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    let (target, _server_eth, server_ep, server_task, _metrics) = spawn_handler_server_with_pool(
        cache,
        store_dyn,
        remaining,
        decdn_common::config::DEFAULT_CREDIT_MAX,
        decdn_common::config::DEFAULT_CREDIT_RAMP_DIVISOR,
    )
    .await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    let mut held = Vec::new();
    for (i, signer) in signers.iter().enumerate() {
        let ext = binding_ext(signer, client_node_id)?;
        // `open_paid_stream` bails if the server refuses (`!ok`), so reaching the
        // read proves lane `i` was admitted against the topped-up budget.
        let (send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext))
            .await
            .map_err(|e| anyhow::anyhow!("lane {i} must be admitted on a topped-up pool: {e}"))?;
        read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;
        held.push((send, recv));
    }
    anyhow::ensure!(
        held.len() == lanes,
        "every one of the {lanes} distinct lanes must be served on a topped-up pool, served {}",
        held.len()
    );

    drop(held);
    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// True if `encoded` (`OpenMetrics` text from `Metrics::encode`) contains `line`
/// as a full line — mirrors the `has_metric_line` helper in `metrics.rs` so the
/// reject counters are asserted on an exact `name value` match, not a substring.
fn metric_line_present(encoded: &str, line: &str) -> bool {
    encoded.lines().any(|l| l == line)
}

/// Minimal raw client for the binding paths the honest `stream_fetch` requester
/// never drives (it always sends `ext = None`): open one bidi stream, send a
/// `StreamRequest` plus the given `ext`, and return the first decoded reply.
/// Errors if the server reset/closed the stream before a frame arrived — which
/// is exactly how a binding-verification failure surfaces to the peer.
async fn raw_request(
    client_ep: &Endpoint,
    target: EndpointAddr,
    req: &StreamRequest,
    ext: Option<&StreamRequestExt>,
) -> anyhow::Result<(ClientMessage, decdn_protocol::StreamResponseExt)> {
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let (mut send, mut recv) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi: {e}"))?;
    let payload = encode_stream_request(req, ext)?;
    write_frame(&mut send, &payload)
        .await
        .map_err(|e| anyhow::anyhow!("write: {e}"))?;
    let frame = read_frame(&mut recv)
        .await
        .map_err(|e| anyhow::anyhow!("read frame (stream reset?): {e}"))?;
    let (msg, rest) =
        decode_message::<ClientMessage>(&frame).map_err(|e| anyhow::anyhow!("decode: {e}"))?;
    // Only a StreamResponse carries a trailing extension; anything else leaves an
    // empty remainder, which reads back as the default.
    let ext = decdn_protocol::parse_stream_response_ext(rest)
        .map_err(|e| anyhow::anyhow!("decode response ext: {e}"))?;
    Ok((msg, ext))
}

/// Sign a `BindNodeId(client_node_id, nonce = EPHEMERAL_BINDING_NONCE)` under
/// the server's binding domain, returning the wire signature bytes.
fn sign_binding_for(signer: &PrivateKeySigner, client_node_id: B256) -> anyhow::Result<Vec<u8>> {
    let hash = binding_signing_hash(client_node_id, EPHEMERAL_BINDING_NONCE, &binding_domain());
    Ok(signer.sign_hash_sync(&hash)?.as_bytes().to_vec())
}

/// Buyer-side received-byte cap (#1895): the buyer never refuses on the server's
/// *claimed* `total_bytes` — the claim is peer-controlled and unverified
/// (`StreamResponse::validate()` does not bound it). Instead it enters the receive
/// loop and aborts with `BlobTooLarge` once the cumulative RECEIVED bytes cross
/// `max_blob_size_bytes`. Here the whole 8 KiB blob crosses a 4 KiB ceiling inside
/// a single sub-interval frame, so the cap trips before the first 1 MiB payment
/// boundary: the buyer aborts having paid nothing, but only because no voucher
/// interval elapsed — not because it pre-judged the claim.
#[tokio::test(flavor = "multi_thread")]
async fn buyer_aborts_oversized_small_blob_without_paying() -> anyhow::Result<()> {
    let payload = vec![0x5Au8; 8192];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    // The server has no size ceiling — it honestly serves all 8192 bytes; the
    // ceiling under test is the buyer's received-byte cap.
    let (target, server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let mut progress = VoucherProgress::default();
    // Buyer ceiling 4096 < the 8192 bytes that actually arrive → the received
    // bytes trip the cap.
    let err = stream_fetch_tracked(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c1,
        PullDeadlines::whole_transfer(Duration::from_secs(10)),
        4096,
        0,
        &mut progress,
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("received bytes over the ceiling must abort the fetch"))?;
    anyhow::ensure!(
        err.to_string().contains("BlobTooLarge"),
        "error should surface the buyer-side BlobTooLarge ceiling: {err}"
    );
    // The blob is smaller than one 1 MiB payment interval, so the cap trips before
    // any voucher boundary: nothing is paid.
    anyhow::ensure!(
        progress.advanced().is_none(),
        "a sub-interval oversized blob aborts before the first voucher: {:?}",
        progress.advanced()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Buyer-side received-byte cap, payment leg (#1895): a blob genuinely larger than
/// the ceiling is streamed and PAID for up to roughly one ceiling's worth before
/// the cumulative RECEIVED bytes trip the cap — the "honest giant" residual cost.
/// An up-front claim gate would pay nothing here; this test pins that the
/// buyer (a) enters the receive loop despite an over-ceiling `total_bytes`,
/// (b) pays for the bytes it actually took, and (c) never pays past the ceiling.
#[tokio::test(flavor = "multi_thread")]
async fn buyer_pays_for_received_bytes_then_aborts_over_ceiling() -> anyhow::Result<()> {
    let payload = vec![0x5Bu8; 4 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    // The server has no size ceiling — it honestly serves the whole 4 MiB blob;
    // the ceiling under test is the buyer's received-byte cap.
    let (target, server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let mut progress = VoucherProgress::default();
    // Ceiling ~2.4 MiB: two 1 MiB payment intervals clear before the cumulative
    // received bytes cross the ceiling and trip the cap.
    let ceiling: u64 = 2_500_000;
    let err = stream_fetch_tracked(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c2,
        PullDeadlines::whole_transfer(Duration::from_secs(10)),
        ceiling,
        0,
        &mut progress,
    )
    .await
    .err()
    .ok_or_else(|| {
        anyhow::anyhow!("an oversized blob must abort once received bytes cross the ceiling")
    })?;
    anyhow::ensure!(
        err.to_string().contains("BlobTooLarge"),
        "the received-byte cap must surface BlobTooLarge: {err}"
    );
    // The cap fires on RECEIVED bytes, so the buyer paid for the prefix it took —
    // never the inflated claim, and (unlike an up-front claim gate) never
    // nothing: the watermark advanced.
    let (bytes, _amount) = progress.advanced().ok_or_else(|| {
        anyhow::anyhow!("the buyer must pay for the bytes it actually received before aborting")
    })?;
    // ...and the spend is bounded: it never pays a voucher past the ceiling.
    anyhow::ensure!(
        bytes <= U256::from(ceiling),
        "the buyer must not pay past the ceiling, paid {bytes}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Buyer-side RATE gate (#1375): the rate analogue of `buyer_rejects_oversized_total_bytes`.
/// The server quotes `RATE_PER_MB` in a valid, signed `ok == true` `StreamResponse`, but the
/// buyer's ceiling is below it. The buyer must refuse BEFORE paying a single voucher, and the
/// abort must carry the server's OWN signed quote out as `RateAboveCeiling` evidence — that is
/// the rate-manipulation attestation a challenger replays to `SlashJudge` with no re-signing.
#[tokio::test(flavor = "multi_thread")]
async fn buyer_rejects_over_ceiling_rate() -> anyhow::Result<()> {
    let payload = vec![0x5Au8; 4096];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    // Server quotes RATE_PER_MB (10); no size ceiling.
    let (target, server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let mut progress = VoucherProgress::default();
    // Buyer ceiling below the quoted rate → refuse before the first paid interval.
    let buyer_ceiling = RATE_PER_MB - 1;
    let err = stream_fetch_tracked(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c4,
        PullDeadlines::whole_transfer(Duration::from_secs(10)),
        0,
        buyer_ceiling,
        &mut progress,
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("an over-ceiling rate must be refused by the buyer"))?;

    let refused = err
        .downcast_ref::<RateAboveCeiling>()
        .ok_or_else(|| anyhow::anyhow!("must surface a typed RateAboveCeiling, got: {err:#}"))?;
    anyhow::ensure!(
        refused.quoted_rate_per_mb() == RATE_PER_MB
            && refused.ceiling_rate_per_mb() == buyer_ceiling,
        "the error must record the quoted rate {} and the ceiling {}, got {} / {}",
        RATE_PER_MB,
        buyer_ceiling,
        refused.quoted_rate_per_mb(),
        refused.ceiling_rate_per_mb(),
    );
    // The retained evidence is the server's own signed quote and still recovers to it, so a
    // challenger can replay it to `SlashJudge` unchanged.
    let evidence = refused.evidence();
    anyhow::ensure!(
        evidence.body.rate_per_mb == RATE_PER_MB && evidence.body.ok,
        "the retained evidence must be the signed ok:true over-quote"
    );
    // The whole value proposition of retaining the response: its `slash_sig` still
    // ecrecovers to the delivering operator, so it is replayable with no re-signing.
    // (Mirrors `an_open_stage_refusal_preserves_the_signed_stream_response`.)
    let recovered = alloy::primitives::Signature::try_from(evidence.slash_sig.as_slice())?;
    StreamSlashData::from_response_body(&evidence.body).verify_signer(
        &recovered,
        server_eth.address(),
        &slash_domain(),
    )?;
    anyhow::ensure!(
        progress.advanced().is_none(),
        "no voucher may be paid when the buyer refuses the rate up front: {:?}",
        progress.advanced()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Boundary of the buyer-side gate (#840): the ceiling is inclusive. A blob
/// whose `total_bytes` exactly equals `max_blob_size_bytes` must be accepted
/// (the gate is `received > ceiling`, strict) — guards against a `>` → `>=`
/// regression that would silently reject every exactly-ceiling-sized blob. The
/// blob spans several chunk groups with a ragged tail, so its wire carries proof
/// parents: a ceiling computed in content bytes instead of wire bytes would trip
/// on the proof and reject it.
#[tokio::test(flavor = "multi_thread")]
async fn buyer_accepts_blob_at_exact_ceiling() -> anyhow::Result<()> {
    let payload = vec![0x5Au8; 3 * 16 * 1024 + 123];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let mut progress = VoucherProgress::default();
    // Buyer ceiling == promised size → accepted, full blob delivered.
    let got = stream_fetch_tracked(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c2,
        PullDeadlines::whole_transfer(Duration::from_secs(10)),
        u64::try_from(payload.len())?,
        0,
        &mut progress,
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "exact-ceiling blob must deliver intact"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Read a paid leg of `wire_len` wire bytes as a verifying decoder does, one
/// bao chunk group at a time and never past the leg's end, until at least
/// `until` wire bytes are read, the leg's wire is all read, or the stream
/// faults. Returns the wire bytes read. The content is honest, so every byte
/// read stands for a verified one: each read reports the bytes before it
/// verified, and the pull pays for them as it would for a decoder's. A
/// decoder asks for no byte past the leg's end, because the node sends its
/// `StreamEnd` only once the closing voucher for the last bytes arrives.
async fn read_groups(
    reader: &mut decdn_client::sink::PullReader,
    wire_len: u64,
    until: u64,
) -> anyhow::Result<u64> {
    use iroh_io::AsyncStreamReader as _;
    let mut read = 0u64;
    while read < until.min(wire_len) {
        let want = (wire_len - read).min(decdn_bao_range::CHUNK_GROUP_BYTES);
        let bytes = reader.read_bytes(usize::try_from(want)?).await?;
        if bytes.is_empty() {
            break;
        }
        read = read.saturating_add(u64::try_from(bytes.len())?);
    }
    Ok(read)
}

/// A pull stopped before its promised end (a steal's split) pays for exactly
/// the wire bytes its decoder verified, and closes. The frames the node queued
/// past the split arrive but never verify, so they are not paid for. The lane
/// stays healthy: the next leg on the same ledger opens, pays on from there,
/// and completes with no voucher rejection, whether or not the node read the
/// closing voucher.
#[tokio::test(flavor = "multi_thread")]
async fn a_pull_stopped_at_a_split_pays_what_it_verified_and_the_lane_pulls_on()
-> anyhow::Result<()> {
    use decdn_client::PeerSource;
    use decdn_client::source::BlobSource as _;

    let payload = vec![0x3Au8; 8 * 1024 * 1024];
    let total = u64::try_from(payload.len())?;
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let ledger = Arc::new(ctx.new_ledger());
    let slash = slash_domain();
    let source = PeerSource::new(
        &client_ep,
        target,
        Arc::new(std::sync::Mutex::new(ctx)),
        Arc::clone(&ledger),
        &slash,
        server_eth.address(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        u64::MAX,
        PullDeadlines::new(Duration::from_secs(10), Duration::from_secs(10), 0)?,
        None,
    );

    // `[0, 4 MiB)`, stopped once about a third of its wire has verified.
    let range = decdn_bao_range::align_range(0, 4 * 1024 * 1024, total)?;
    let (_header, mut reader) = source.open(*hash.as_bytes(), range).await?;
    let wire_len = support::bao_wire_len(total, 0, 4 * 1024 * 1024);
    let verified = read_groups(&mut reader, wire_len, 3 * 512 * 1024).await?;
    anyhow::ensure!(verified >= 3 * 512 * 1024, "the leg ended before the split");
    // Let the node's credit window queue frames the leg has not read yet:
    // the stop reads them, without waiting, for a rejection behind them.
    tokio::time::sleep(Duration::from_millis(200)).await;
    let stopped = source.stop(reader).await?;
    let (stopped_bytes, _) = stopped
        .advanced()
        .ok_or_else(|| anyhow::anyhow!("the stopped leg must have paid"))?;
    anyhow::ensure!(
        stopped_bytes == U256::from(verified),
        "the stopped leg pays for exactly the {verified} wire bytes it verified, none of the \
         frames queued past the split: paid {stopped_bytes}"
    );

    // The next leg on the same ledger pays on from the stopped one's
    // watermark and completes.
    let range = decdn_bao_range::align_range(4 * 1024 * 1024, 4 * 1024 * 1024, total)?;
    let (_header, mut reader) = source.open(*hash.as_bytes(), range).await?;
    let wire_len = support::bao_wire_len(total, 4 * 1024 * 1024, 4 * 1024 * 1024);
    let next = read_groups(&mut reader, wire_len, u64::MAX).await?;
    anyhow::ensure!(
        next == wire_len,
        "the next leg delivers its whole wire ({next} of {wire_len})"
    );
    let finished = source.finish(reader).await?;
    let (finished_bytes, _) = finished
        .advanced()
        .ok_or_else(|| anyhow::anyhow!("the next leg must have paid"))?;
    anyhow::ensure!(
        finished_bytes == stopped_bytes + U256::from(next),
        "the next leg pays on from the stopped one: {finished_bytes} of {stopped_bytes} + {next}"
    );

    drop(source);
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The received-byte ceiling on a GAP-scoped leg (`byte_len > 0`), the shape the
/// gap-driven driver opens through `PeerSource`. The bound is anchored at the
/// leg's own offset and measured against a ceiling-sized tree, so (a) a leg
/// entirely under the ceiling completes even though the blob's signed
/// `total_bytes` exceeds it — the claim never drives a refusal (#1895) — and (b)
/// the leg that crosses the ceiling aborts with [`BlobTooLarge`] having paid
/// nothing: it verifies less than one metering interval before the abort.
#[tokio::test(flavor = "multi_thread")]
async fn gap_scoped_leg_enforces_the_received_byte_ceiling_from_its_own_offset()
-> anyhow::Result<()> {
    use decdn_client::PeerSource;
    use decdn_client::sink::StashedFault as _;
    use decdn_client::source::BlobSource as _;

    let payload = vec![0x5Cu8; 4 * 1024 * 1024];
    let total = u64::try_from(payload.len())?;
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let ledger = Arc::new(ctx.new_ledger());
    let ceiling: u64 = 2_500_000;
    let slash = slash_domain();
    let source = PeerSource::new(
        &client_ep,
        target,
        Arc::new(std::sync::Mutex::new(ctx)),
        Arc::clone(&ledger),
        &slash,
        server_eth.address(),
        decdn_protocol::client::NO_NAMESPACE,
        ceiling,
        u64::MAX,
        PullDeadlines::new(Duration::from_secs(10), Duration::from_secs(10), 0)?,
        None,
    );

    // (a) `[0, 2 MiB)` of a 4 MiB blob under a ~2.4 MiB ceiling: completes.
    let range = decdn_bao_range::align_range(0, 2 * 1024 * 1024, total)?;
    let (header, mut reader) = source.open(*hash.as_bytes(), range).await?;
    anyhow::ensure!(
        header.total_bytes == total,
        "the signed claim exceeds the ceiling by design"
    );
    let expected = support::bao_wire_len(total, 0, 2 * 1024 * 1024);
    let received = read_groups(&mut reader, expected, u64::MAX).await?;
    anyhow::ensure!(
        received == expected,
        "the under-ceiling leg must deliver its whole wire ({received} of {expected})"
    );
    let paid_first = source.finish(reader).await?;
    let (paid_first, _) = paid_first
        .advanced()
        .ok_or_else(|| anyhow::anyhow!("the completed leg must have paid"))?;

    // (b) `[2 MiB, 4 MiB)`: the ceiling's wire from this offset is ~0.4 MiB, under
    // one metering interval, so the leg aborts before any payment comes due.
    let ceiling_wire_from_offset = support::bao_wire_len(ceiling, 2 * 1024 * 1024, 0);
    anyhow::ensure!(
        ceiling_wire_from_offset < HARNESS_INTERVAL_BYTES,
        "the ceiling's wire from the offset must sit under one interval"
    );
    let range = decdn_bao_range::align_range(2 * 1024 * 1024, 2 * 1024 * 1024, total)?;
    let (_header, mut reader) = source.open(*hash.as_bytes(), range).await?;
    let wire_len = support::bao_wire_len(total, 2 * 1024 * 1024, 2 * 1024 * 1024);
    read_groups(&mut reader, wire_len, u64::MAX).await?;
    let err = reader
        .take_fault()
        .ok_or_else(|| anyhow::anyhow!("the crossing leg must not complete"))?;
    anyhow::ensure!(
        err.downcast_ref::<BlobTooLarge>().is_some(),
        "the crossing leg must abort with BlobTooLarge, got: {err:#}"
    );
    drop(reader);
    let paid_total = ledger.settlement().bytes;
    anyhow::ensure!(
        paid_total == paid_first,
        "the crossing leg paid {} past the first leg's {paid_first}; it verified less than \
         one interval ({ceiling_wire_from_offset} wire bytes at most) and owes nothing",
        paid_total - paid_first
    );

    drop(source);
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Boundary of the buyer-side RATE gate (#1375): inclusive, like the blob-size
/// gate above. A quote EXACTLY equal to the buyer ceiling must be accepted and
/// deliver in full (the gate is `rate_per_mb > ceiling`, strict) — guards against
/// a `>` → `>=` regression that would reject an honest node quoting right at the
/// buyer's ceiling. The sibling of `buyer_accepts_blob_at_exact_ceiling`.
#[tokio::test(flavor = "multi_thread")]
async fn buyer_accepts_rate_at_exact_ceiling() -> anyhow::Result<()> {
    let payload = vec![0x5Au8; 4096];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    // Server quotes RATE_PER_MB; buyer ceiling set to EXACTLY RATE_PER_MB.
    let (target, server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let mut progress = VoucherProgress::default();
    let got = stream_fetch_tracked(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c5,
        PullDeadlines::whole_transfer(Duration::from_secs(10)),
        0,
        RATE_PER_MB, // ceiling == quote → accepted
        &mut progress,
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "a quote exactly at the buyer ceiling must deliver intact"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Delivery-progress hook (#1118): `stream_fetch_tracked_with_progress` invokes
/// the callback as verified leaves land with `(content_position, total_bytes)`.
/// The expected total is the blob's content size, fixed once the signed
/// `StreamResponse` arrives; received bytes advance monotonically, and the final
/// observation reaches the full content size — the contract `decdn get`'s
/// progress bar relies on.
#[tokio::test(flavor = "multi_thread")]
async fn progress_callback_reports_monotonic_delivery() -> anyhow::Result<()> {
    // Multi-frame payload (256 KiB) so the callback fires repeatedly
    // and the monotonic-advance assertion has intermediate points to check.
    let payload = vec![0xABu8; 256 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let mut progress = VoucherProgress::default();
    // `ProgressCallback` is `'static`, so the closure owns an `Arc` handle to the
    // shared sink rather than borrowing a stack local.
    let observations = Arc::new(std::sync::Mutex::new(Vec::<(u64, u64)>::new()));
    let sink = Arc::clone(&observations);
    let record = move |received: u64, expected: u64| {
        if let Ok(mut v) = sink.lock() {
            v.push((received, expected));
        }
    };
    let got = stream_fetch_tracked_with_progress(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c3,
        PullDeadlines::whole_transfer(Duration::from_secs(10)),
        0, // unlimited buyer blob-size ceiling
        0, // unlimited buyer rate ceiling
        &mut progress,
        Some(&record),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "progress-tracked fetch must still deliver the blob intact"
    );

    // Clone the observations out and drop the guard before the cleanup awaits
    // below (clippy `await_holding_lock`).
    let obs: Vec<(u64, u64)> = observations
        .lock()
        .map_err(|_| anyhow::anyhow!("progress mutex poisoned"))?
        .clone();
    anyhow::ensure!(!obs.is_empty(), "progress callback must fire at least once");
    let expected = obs.last().map_or(0, |&(_, e)| e);
    anyhow::ensure!(
        expected == u64::try_from(payload.len())?,
        "expected must be the blob's content size, got {expected}"
    );
    anyhow::ensure!(
        obs.iter().all(|&(_, e)| e == expected),
        "expected total must stay constant across the pull"
    );
    let mut prev = 0u64;
    for &(received, _) in &obs {
        anyhow::ensure!(
            received >= prev,
            "progress must be monotonically non-decreasing ({received} < {prev})"
        );
        anyhow::ensure!(
            received <= expected,
            "progress ({received}) must never exceed the expected total ({expected})"
        );
        prev = received;
    }
    anyhow::ensure!(
        prev == expected,
        "final progress ({prev}) must reach the content size ({expected})"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Build a [`DeniedHashes`] from store hashes, the way config resolution would.
fn denied_hashes(hashes: &[Hash]) -> decdn_cache::DeniedHashes {
    decdn_cache::DeniedHashes::new(
        hashes
            .iter()
            .map(|h| decdn_cache::LeafHash::from_bytes(*h.as_bytes()))
            .collect(),
    )
}

fn content_with_origins(
    origins: &[alloy::primitives::Address],
) -> decdn_common::config::ResolvedContent {
    decdn_common::config::ResolvedContent {
        denied_origins: origins.iter().copied().collect(),
        ..Default::default()
    }
}

/// [`spawn_handler_server_with_metrics`] with an ADR 011 origin deny-set wired in.
/// `owner` is the pool's funder as the serve gate reads it from `getPool.owner`
/// (via a stub pool-view); the origin-blacklist gate refuses a pool whose owner
/// is on the deny-set. Pool `remaining` is unbounded so only the deny-set — not
/// the floor-`M` gate — can refuse.
async fn spawn_handler_server_with_deny(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    deny: Arc<decdn_node::content_deny::ContentDenylist>,
    owner: Address,
) -> anyhow::Result<(
    EndpointAddr,
    Arc<PrivateKeySigner>,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        16,
        |deps| {
            deps.content_deny = deny;
            deps.pool_view = Some(Arc::new(FixedRemainingPoolView {
                owner,
                remaining: U256::MAX,
            }));
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((target, server_eth, server_ep, server_task, metrics))
}

/// ADR 011 §Local Denylist / §On Blacklist Event step 2: a denied hash is
/// refused even though the node still physically holds the bytes.
///
/// Two properties in one test. `CacheEngine::refuses` makes the blob report
/// absent everywhere (defence in depth — this is what also suppresses the probe
/// `has_blob` signature and DHT republish), while the serve gate above the
/// availability check is what turns that into a `Declined` with its own
/// metric rather than a `NotFound`.
///
/// Without a test at this level the whole gate could be deleted and every other
/// test in the suite would stay green — which is exactly what happened.
#[tokio::test(flavor = "multi_thread")]
async fn denylisted_hash_is_refused_even_when_held() -> anyhow::Result<()> {
    let payload = b"content under a local takedown order".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    anyhow::ensure!(cache.has(hash).await?, "held before the takedown");

    // Deliberately NOT evicted — the bytes stay on disk. Denial alone must be
    // enough to stop serving.
    cache.set_denied(&denied_hashes(&[hash]));
    anyhow::ensure!(
        !cache.has(hash).await?,
        "a denied blob must report absent, exactly as an evicted one does — \
         defence in depth behind the serve gate"
    );

    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00e2,
        Duration::from_secs(10),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("a denylisted blob must be refused even when held"))?;
    anyhow::ensure!(
        err.to_string().contains("Declined"),
        "error should surface Declined: {err}"
    );
    support::assert_inbound_failures_attributed(&metrics, 1).await?;
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_hash_denied_total 1"
        ),
        "the takedown refusal must bump its own reason counter, not the eviction one"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// ADR 011 §`StreamRequest` Response: a GOVERNANCE takedown must answer the
/// same wire code as the operator's own denylist entry above.
///
/// A distinct code for either list would tell a client which list a hash is
/// on, and since the governance list is public on-chain, the local code would
/// be a unique fingerprint for "this operator denied it privately". Precisely
/// the map of an operator's legal exposure the ADR forecloses.
///
/// The metric split is the part that MAY differ, and does: it is the operator's
/// own gauge and no client can read it.
#[tokio::test(flavor = "multi_thread")]
async fn governance_denied_hash_is_refused_as_hash_blacklisted() -> anyhow::Result<()> {
    let payload = b"content under a governance takedown".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    // The watcher denies *and* evicts; deny only, so the test proves the deny
    // gate is what produced the code rather than the eviction arm below it.
    cache.set_chain_denied_one(hash, true);
    anyhow::ensure!(!cache.is_denied(hash), "not on the LOCAL list");

    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00e4,
        Duration::from_secs(10),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("a governance-blacklisted blob must be refused"))?;
    anyhow::ensure!(
        err.to_string().contains("Declined"),
        "a governance takedown must sign Declined: {err}"
    );
    let encoded = metrics.encode()?;
    anyhow::ensure!(
        metric_line_present(
            &encoded,
            "decdn_serve_stream_rejected_chain_hash_denied_total 1"
        ),
        "the governance refusal has its own operator-side counter"
    );
    anyhow::ensure!(
        metric_line_present(&encoded, "decdn_serve_stream_rejected_hash_denied_total 0"),
        "...and must not be miscounted as a local denylist hit"
    );
    anyhow::ensure!(
        metric_line_present(
            &encoded,
            "decdn_serve_stream_rejected_evicted_since_probe_total 0"
        ),
        "...nor land on the eviction counter, which is now non-takedown evictions only"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// ADR 011 §On Blacklist Event: "In-flight streams for a blacklisted hash are
/// terminated at the next MB boundary."
///
/// The open-time gates cannot cover this: a takedown that lands *after* a stream
/// opens would otherwise let a multi-GB blob run to completion minutes into a
/// one-hour removal order, and serving past the compliance window is slashable
/// (ADR 026 §Slashing and burn).
///
/// The takedown is landed only once a voucher has been accepted, which is what
/// makes this test exercise the mid-stream path rather than racing the open-time
/// gate: a voucher proves the request was already admitted and bytes are
/// flowing. The blob is sized to many chunks so boundaries remain
/// after the flip.
#[tokio::test(flavor = "multi_thread")]
async fn takedown_mid_stream_terminates_the_delivery() -> anyhow::Result<()> {
    // 4 voucher accounting intervals at the fixed `CHUNK_BYTES`.
    let payload = vec![0x5Au8; 16 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let deny_cache = cache.clone();
    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, Arc::clone(&store), RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let fetch_ep = client_ep.clone();
    let server_addr = server_eth.address();
    let hash_bytes = *hash.as_bytes();
    let fetch = tokio::spawn(async move {
        stream_fetch(
            &fetch_ep,
            target,
            &ctx,
            &slash_domain(),
            server_addr,
            hash_bytes,
            0,
            0x00e5,
            Duration::from_secs(30),
        )
        .await
    });

    // Wait for the first accepted PROOF — the store is written on every acceptance,
    // so a non-zero `owed` means delivery is under way.
    //
    // `owed`, not `last_amount`: under `PayWord` the signed cumulative does not
    // move per chunk. A reveal advances the lane's claim without a signature, so
    // `last_amount` would sit at the opening voucher's value until the close —
    // by which point the whole blob is delivered and there is no mid-stream left
    // to interrupt.
    let deadline = Instant::now() + Duration::from_secs(20);
    while !store
        .load_all()?
        .iter()
        .any(|state| state.owed() > U256::ZERO)
    {
        anyhow::ensure!(
            Instant::now() < deadline,
            "no voucher was ever accepted; the test never reached the mid-stream path"
        );
        tokio::time::sleep(Duration::from_millis(1)).await;
    }
    deny_cache.set_chain_denied_one(hash, true);

    let err = fetch
        .await?
        .err()
        .ok_or_else(|| anyhow::anyhow!("delivery must not complete through a takedown"))?;
    // The dispatch sink counts the stop once the serve task returns, which can
    // trail the client seeing the reset.
    support::assert_inbound_failures_attributed(&metrics, 1).await?;
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_terminated_takedown_total 1"
        ),
        "the cut-off must be metered as an in-flight termination, not a completed \
         delivery ({err})"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// ADR 011 §On Blacklist Event. A pool funded by a blacklisted origin is
/// refused `Declined` for `origin_denied`, including on a CACHE MISS, which is
/// the path a late gate misses: every miss arm returns a plain `NotFound`
/// before a gate placed after it runs.
///
/// `NotFound` is the one answer that must never be given here: it tells the
/// client to retry elsewhere and pay again, when every node will refuse it.
#[tokio::test(flavor = "multi_thread")]
async fn blacklisted_funder_is_refused_on_a_cache_miss() -> anyhow::Result<()> {
    let cache_dir = tempfile::tempdir()?;
    let cache = CacheEngine::open(cache_dir.path(), vec![], 16).await?;
    let (store, signer, deposit) = seeded_store()?;
    let funder = signer.address();
    let deny = Arc::new(decdn_node::content_deny::ContentDenylist::new(
        &content_with_origins(&[funder]),
    ));

    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_deny(cache, store, deny, funder).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        [0x5a; 32], // never cached — the miss path
        0,
        0x00e3,
        Duration::from_secs(10),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("a blacklisted funder must be refused"))?;
    anyhow::ensure!(
        err.to_string().contains("Declined"),
        "error should surface Declined, not NotFound: {err}"
    );
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_origin_denied_total 1"
        ),
        "the compliance gauge must count a miss-path refusal too"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A blob evicted between probe and stream request is refused `Declined`
/// (reason `EvictedSinceProbe`), distinct from a never-had-it `NotFound`.
#[tokio::test(flavor = "multi_thread")]
async fn client_evicted_since_probe_is_refused() -> anyhow::Result<()> {
    let payload = b"evicted between probe and stream".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    cache.evict(hash).await?; // logically gone: has() now false, is_evicted() true.
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, signer, deposit);
    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00e1,
        Duration::from_secs(10),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("evicted blob must be refused"))?;
    anyhow::ensure!(
        err.to_string().contains("Declined"),
        "error should surface Declined: {err}"
    );
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_evicted_since_probe_total 1"
        ),
        "evicted-since-probe refusal must bump its reason counter (#876)"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Client-identity binding gate (ADR 005 §Client identity binding): a binding
/// whose signature recovers a DIFFERENT address than it claims is a client
/// fault — the node resets the stream (no signed response), so the raw read
/// fails. Covers `serve_stream`'s `recovered != claimed` arm.
#[tokio::test(flavor = "multi_thread")]
async fn client_binding_address_mismatch_resets() -> anyhow::Result<()> {
    let payload = b"binding mismatch never delivers".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, _owner, _deposit) = seeded_store()?;
    let (target, _server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;

    // A valid signature by `attacker`, but the binding CLAIMS `claimed`'s address.
    let attacker = PrivateKeySigner::random();
    let claimed = PrivateKeySigner::random();
    let claimed_addr: [u8; 20] = claimed.address().into();
    let ext = StreamRequestExt {
        binding: Some(ClientBinding {
            ethereum_address: claimed_addr,
            binding_signature: sign_binding_for(&attacker, client_node_id)?,
        }),
        ..Default::default()
    };
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x00ba_d001,
    };
    let res = raw_request(&client_ep, target, &req, Some(&ext)).await;
    anyhow::ensure!(
        res.is_err(),
        "a binding recovering a different address must reset the stream, got {res:?}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Binding authorization gate: a correctly-signed binding for an address that
/// signs for no lane on the requested pool is refused as an unknown lane (wire
/// `NotFound`). This is the leech closure for bound clients.
#[tokio::test(flavor = "multi_thread")]
async fn client_binding_for_other_owner_is_not_found() -> anyhow::Result<()> {
    let payload = b"valid binding, wrong pool owner".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    // The pool is owned by `seeded_store`'s signer; the binding attests a
    // different address (`intruder`), so it must not authorize this pool.
    let (store, _owner, _deposit) = seeded_store()?;
    let (target, _server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, store, RATE_PER_MB, 16).await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;

    let intruder = PrivateKeySigner::random();
    let intruder_addr: [u8; 20] = intruder.address().into();
    let ext = StreamRequestExt {
        binding: Some(ClientBinding {
            ethereum_address: intruder_addr,
            binding_signature: sign_binding_for(&intruder, client_node_id)?,
        }),
        ..Default::default()
    };
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x00ba_d002,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), resp_ext) => {
            anyhow::ensure!(
                !resp.body.ok,
                "expected ok:false for an unauthorized binding"
            );
            anyhow::ensure!(
                matches!(
                    resp_ext.error,
                    Some(decdn_protocol::client::StreamError::NotFound)
                ),
                "expected NotFound, got {:?}",
                resp_ext.error
            );
        }
        other => anyhow::bail!("expected a StreamResponse, got {other:?}"),
    }

    // Pool model: a valid binding for an address with no lane on this pool
    // resolves to no lane, so the refusal is the unknown-lane arm — the
    // owner-mismatch gate is subsumed into lane resolution (a wrong signer simply
    // owns no lane). Wire-indistinguishable from a cache miss (all `NotFound`), so
    // only the reason counter proves which arm ran (#876).
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_unknown_lane_total 1"
        ),
        "a bound-but-laneless request must bump the unknown-lane counter"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// What [`delegate_signer_store`] hands back: the seeded store, the funder
/// signer, and the delegate voucher signer.
type DelegateSignerFixture = (
    Arc<dyn PoolStateStore>,
    Arc<PrivateKeySigner>,
    Arc<PrivateKeySigner>,
);

/// A pool-state store seeded with one lane whose pool FUNDER and pinned
/// `voucher_signer` are distinct addresses — the publisher-pays delegate shape,
/// where the funder put up the deposit and a throwaway hot key signs vouchers.
/// Returns the store, the funder signer, and the delegate signer.
fn delegate_signer_store() -> anyhow::Result<DelegateSignerFixture> {
    let funder = Arc::new(PrivateKeySigner::random());
    let delegate = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        delegate.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    Ok((store, funder, delegate))
}

/// Build the `StreamRequestExt` carrying a valid client binding for `signer`
/// over `client_node_id` — the honest requester never sends one, so the binding
/// tests construct it by hand.
fn binding_ext(
    signer: &PrivateKeySigner,
    client_node_id: B256,
) -> anyhow::Result<StreamRequestExt> {
    Ok(StreamRequestExt {
        binding: Some(ClientBinding {
            ethereum_address: signer.address().into(),
            binding_signature: sign_binding_for(signer, client_node_id)?,
        }),
        ..Default::default()
    })
}

/// The binding gate is a *signer* question: a connection bound as the lane's
/// pinned `voucher_signer` is authorized, even though that address never funded
/// the pool. Its vouchers are the ones the lane will accept, so it is the
/// only identity that can pay for this delivery.
#[tokio::test(flavor = "multi_thread")]
async fn binding_matching_the_delegate_signer_is_authorized() -> anyhow::Result<()> {
    let payload = b"delegate-signed lane is served".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, _funder, delegate) = delegate_signer_store()?;
    let (target, _server_eth, server_ep, server_task, _metrics) =
        spawn_handler_server_with_metrics(cache, store, RATE_PER_MB, 16).await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;

    let ext = binding_ext(&delegate, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x00de_1e01,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), resp_ext) => {
            anyhow::ensure!(
                resp.body.ok,
                "the pinned voucher signer must be authorized, got {:?}",
                resp_ext.error
            );
        }
        other => anyhow::bail!("expected a StreamResponse, got {other:?}"),
    }

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The mirror of the above: a connection bound as the *funder* behind a delegated
/// lane is refused as an unknown lane (wire `NotFound`). The funder holds
/// no voucher authority on this lane, so its vouchers would fail
/// `WrongSigner` mid-stream after free bytes had already shipped.
#[tokio::test(flavor = "multi_thread")]
async fn binding_matching_only_the_funder_is_refused() -> anyhow::Result<()> {
    let payload = b"the funder cannot spend a delegated lane".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, funder, _delegate) = delegate_signer_store()?;
    let (target, _server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, store, RATE_PER_MB, 16).await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;

    let ext = binding_ext(&funder, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x00de_1e02,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), resp_ext) => {
            anyhow::ensure!(!resp.body.ok, "expected ok:false for the funder binding");
            anyhow::ensure!(
                matches!(
                    resp_ext.error,
                    Some(decdn_protocol::client::StreamError::NotFound)
                ),
                "expected NotFound, got {:?}",
                resp_ext.error
            );
        }
        other => anyhow::bail!("expected a StreamResponse, got {other:?}"),
    }
    // Pool model: the funder holds no lane on this delegated pool (the lane is
    // keyed by the delegate signer), so its binding resolves to no lane and the
    // refusal is the unknown-lane arm.
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_unknown_lane_total 1"
        ),
        "the funder binding must bump the unknown-lane counter"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// COMPLIANCE REGRESSION GUARD (ADR 011 §On Blacklist Event). The takedown gate
/// keys on the pool's FUNDER, never on the lane's voucher signer. A blacklisted
/// funder that delegates signing to a clean throwaway key must still be refused
/// for `origin_denied`.
///
/// This test fails the moment any blacklist / `content_deny` check is re-keyed
/// onto `voucher_signer` — which is exactly the silent compliance break a
/// blanket `state.client` → `voucher_signer` rename would cause.
#[tokio::test(flavor = "multi_thread")]
async fn blacklisted_funder_is_refused_even_behind_a_clean_delegate() -> anyhow::Result<()> {
    let payload = b"a clean delegate does not launder a blacklisted funder".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, funder, delegate) = delegate_signer_store()?;
    // Only the funder is on the deny-set; the delegate signer is clean.
    let deny = Arc::new(decdn_node::content_deny::ContentDenylist::new(
        &content_with_origins(&[funder.address()]),
    ));
    let (target, _server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_deny(cache, store, deny, funder.address()).await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;

    let ext = binding_ext(&delegate, client_node_id)?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x00de_1e03,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), resp_ext) => {
            anyhow::ensure!(
                !resp.body.ok,
                "a blacklisted funder must be refused behind a clean delegate"
            );
            anyhow::ensure!(
                matches!(
                    resp_ext.error,
                    Some(decdn_protocol::client::StreamError::Declined)
                ),
                "expected Declined, got {:?}",
                resp_ext.error
            );
        }
        other => anyhow::bail!("expected a StreamResponse, got {other:?}"),
    }
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_origin_denied_total 1"
        ),
        "the compliance gauge must count the delegated-lane refusal"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The full delegated round trip: a lane whose `voucher_signer` is NOT the
/// funder is served end to end on delegate-signed vouchers, and the persisted
/// state keeps the two addresses apart.
///
/// Every other delegated-lane test stops at the open-time gate's verdict.
/// This one crosses the whole seam — request admitted, delegate-signed vouchers
/// accepted at each interval, bytes assembled and hash-verified — so a
/// regression that accepted the open but rejected the delegate's vouchers
/// mid-stream cannot hide.
#[tokio::test(flavor = "multi_thread")]
async fn delegate_signed_vouchers_carry_a_delivery_to_completion() -> anyhow::Result<()> {
    // 1.5 MiB crosses one voucher-interval boundary plus a closing voucher, so
    // at least two delegate-signed vouchers are verified.
    let payload = vec![0xC3u8; 1_572_864];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, _funder, delegate) = delegate_signer_store()?;
    let (target, server_eth, server_ep, server_task, _metrics) =
        spawn_handler_server_with_metrics(cache, Arc::clone(&store), RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    // The requester signs with the DELEGATE — the funder's key never appears.
    let ctx = pool_context(&client_ep, Arc::clone(&delegate), U256::from(10_000_000u64));
    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00de_1e05,
        Duration::from_secs(30),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delegate-signed delivery returned {} bytes, expected {}",
        got.len(),
        payload.len()
    );

    let states = store.load_all()?;
    let state = states
        .first()
        .ok_or_else(|| anyhow::anyhow!("the lane must still be persisted"))?;
    // ADR 038: the metered quantity is bao wire bytes, not payload bytes.
    let wire = support::bao_wire_len_whole(payload.len() as u64);
    anyhow::ensure!(
        state.last_bytes_delivered() == U256::from(wire),
        "the persisted byte count must cover the whole blob: {} (expected {wire})",
        state.last_bytes_delivered()
    );
    anyhow::ensure!(
        state.signer == delegate.address() && state.provider == operator_addr(),
        "the delegate is the lane signer across a completed delivery"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// COMPLIANCE REGRESSION GUARD (ADR 011 §On Blacklist Event), mid-stream half.
///
/// The per-MB in-flight takedown re-checks in `window.rs` / `delivery.rs` are
/// keyed on the FUNDER. Only a comment stops them being re-keyed onto
/// `voucher_signer`, and the open-time delegated-funder test passes either way
/// because it never reaches a voucher boundary. This one blacklists the funder
/// AFTER delivery is under way on a lane whose signer is a clean, never-
/// blacklisted delegate: if the re-check moved to the signer, the stream would
/// run to completion and this test fails.
#[tokio::test(flavor = "multi_thread")]
async fn blacklisting_the_funder_mid_stream_cuts_off_a_delegated_delivery() -> anyhow::Result<()> {
    // 4 voucher accounting intervals at the fixed `CHUNK_BYTES`, so
    // plenty of boundaries remain after the deny-set flip.
    let payload = vec![0x6Bu8; 16 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, funder, delegate) = delegate_signer_store()?;
    // Starts empty — nothing is denied at open time, so the request is admitted
    // and the cut-off can only come from the mid-stream re-check.
    let deny = Arc::new(decdn_node::content_deny::ContentDenylist::empty());
    let (target, server_eth, server_ep, server_task, metrics) = spawn_handler_server_with_deny(
        cache,
        Arc::clone(&store),
        Arc::clone(&deny),
        funder.address(),
    )
    .await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, Arc::clone(&delegate), U256::from(10_000_000u64));
    let fetch_ep = client_ep.clone();
    let server_addr = server_eth.address();
    let hash_bytes = *hash.as_bytes();
    let fetch = tokio::spawn(async move {
        stream_fetch(
            &fetch_ep,
            target,
            &ctx,
            &slash_domain(),
            server_addr,
            hash_bytes,
            0,
            0x00de_1e06,
            Duration::from_secs(30),
        )
        .await
    });

    // Wait for the first accepted (delegate-signed) voucher: proof the request
    // was admitted and bytes are flowing, so the flip lands mid-stream rather
    // than racing the open-time gate.
    let deadline = Instant::now() + Duration::from_secs(20);
    while !store
        .load_all()?
        .iter()
        .any(|state| state.owed() > U256::ZERO)
    {
        anyhow::ensure!(
            Instant::now() < deadline,
            "no delegate-signed voucher was ever accepted; the test never reached the \
             mid-stream path"
        );
        tokio::time::sleep(Duration::from_millis(1)).await;
    }
    // Only the FUNDER goes on the deny-set; the delegate signer stays clean.
    deny.apply_chain_origin(funder.address(), true);

    let err = fetch.await?.err().ok_or_else(|| {
        anyhow::anyhow!(
            "delivery must not complete once the funder is blacklisted — the mid-stream \
             re-check has been re-keyed onto the voucher signer"
        )
    })?;
    // The dispatch sink counts the stop once the serve task returns, which can
    // trail the client seeing the reset.
    support::assert_inbound_failures_attributed(&metrics, 1).await?;
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_terminated_takedown_total 1"
        ),
        "the cut-off must be metered as an in-flight termination, not a completed \
         delivery ({err})"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Open a cache pre-seeded with TWO distinct blobs (via a shared filesystem
/// origin, dropped after population), mirroring [`cache_with_blob`] for the
/// concurrent-pull test that requests two different hashes at once.
async fn cache_with_two_blobs(
    a: &[u8],
    b: &[u8],
) -> anyhow::Result<(
    CacheEngine,
    decdn_cache::Hash,
    decdn_cache::Hash,
    tempfile::TempDir,
)> {
    let hash_a = decdn_cache::Hash::new(a);
    let hash_b = decdn_cache::Hash::new(b);
    let origin_dir = tempfile::tempdir()?;
    for (payload, hash) in [(a, hash_a), (b, hash_b)] {
        let hex = hash.to_hex();
        let shard = hex
            .get(..2)
            .ok_or_else(|| anyhow::anyhow!("hex too short"))?;
        let dir = origin_dir.path().join(shard);
        std::fs::create_dir_all(&dir)?;
        std::fs::write(dir.join(hex.as_str()), payload)?;
    }

    let cache_dir = tempfile::tempdir()?;
    let origin = Arc::new(decdn_cache::FilesystemOrigin::new(origin_dir.path()).await?);
    let cache = CacheEngine::open(
        cache_dir.path(),
        vec![origin as Arc<dyn decdn_cache::Origin>],
        16,
    )
    .await?;
    let _ = cache.get(hash_a).await?; // populate local store
    let _ = cache.get(hash_b).await?;
    drop(origin_dir);
    Ok((cache, hash_a, hash_b, cache_dir))
}

/// Concurrent pulls on ONE lane coordinate through a shared [`PoolLedger`]:
/// two simultaneous fetches of two distinct blobs issue vouchers in strict nonce
/// order (the ledger serializes the sign→send→ack→commit cycle), so BOTH succeed
/// and the lane advances monotonically. Without that coordination, two streams
/// would both sign voucher nonce 1 and the node would accept only one.
#[tokio::test(flavor = "multi_thread")]
async fn client_concurrent_same_lane_both_succeed() -> anyhow::Result<()> {
    let payload_a = vec![0x5Au8; 4096];
    let payload_b = vec![0xA5u8; 8192];
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task) =
        spawn_handler_server(cache, Arc::clone(&store), RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    // ONE pool context, ONE shared ledger seeded fresh (all `prior_* == ZERO`),
    // shared across both concurrent pulls via `Arc`.
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);
    let ledger = Arc::new(PoolLedger::new(Cumulative::default()));
    let server_addr = server_eth.address();
    let sd = slash_domain();
    let (ra, rb) = tokio::join!(
        stream_fetch_shared(
            &client_ep,
            target.clone(),
            &ctx,
            &ledger,
            &sd,
            server_addr,
            *hash_a.as_bytes(),
            0,
            0x00aa,
            PullDeadlines::whole_transfer(Duration::from_secs(15)),
            0,
            0,
        ),
        stream_fetch_shared(
            &client_ep,
            target.clone(),
            &ctx,
            &ledger,
            &sd,
            server_addr,
            *hash_b.as_bytes(),
            0,
            0x00bb,
            PullDeadlines::whole_transfer(Duration::from_secs(15)),
            0,
            0,
        ),
    );
    // BOTH succeed: the shared ledger serialized voucher issuance, so neither
    // collided on a nonce. Each pull returns its own verified blob.
    let bytes_a = ra.map_err(|e| anyhow::anyhow!("pull A failed: {e:?}"))?;
    let bytes_b = rb.map_err(|e| anyhow::anyhow!("pull B failed: {e:?}"))?;
    anyhow::ensure!(bytes_a.as_ref() == payload_a.as_slice(), "blob A mismatch");
    anyhow::ensure!(bytes_b.as_ref() == payload_b.as_slice(), "blob B mismatch");

    // The lane advanced monotonically: the cumulative bytes cover BOTH payloads
    // and a non-zero amount was paid. Both pulls completed, so every voucher they
    // sent optimistically has cleared — `committed` carries the full total.
    let final_cum = ledger.committed();
    anyhow::ensure!(
        final_cum.amount > U256::ZERO,
        "ledger amount: {} (expected a paid delivery)",
        final_cum.amount
    );
    let total_bytes = U256::from(payload_a.len() + payload_b.len());
    anyhow::ensure!(
        final_cum.bytes == total_bytes,
        "ledger bytes: {} (expected {})",
        final_cum.bytes,
        total_bytes
    );

    // The node's persisted watermark matches the ledger: the lane applied every
    // voucher in order, ending at the same cumulative bytes.
    let persisted = store.load_all()?;
    let only = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane"))?;
    anyhow::ensure!(
        only.last_bytes_delivered() == total_bytes,
        "persisted bytes_delivered: {} (expected {})",
        only.last_bytes_delivered(),
        total_bytes
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Honest concurrent pulls that roll hash chains draw no voucher rejection. Two
/// multi-chunk fetches share one ledger, so their reveals, re-anchors, rolls and
/// closing vouchers all land on one lane and fold one another's frontiers. A
/// second round runs over the lane the first left behind. Every voucher folds
/// what the lane proved on both axes, so the node rejects none. A false
/// `UnderFold` can heal through the bundle and still pass the fetch, so the
/// test checks the reject counter as well as the bytes.
#[tokio::test(flavor = "multi_thread")]
async fn honest_concurrent_rollovers_draw_no_voucher_rejection() -> anyhow::Result<()> {
    let payload_a: Vec<u8> = (0..3 * 1024 * 1024u32).map(|i| (i % 251) as u8).collect();
    let payload_b: Vec<u8> = (0..5 * 1024 * 1024 / 2u32)
        .map(|i| (i % 241) as u8)
        .collect();
    let (cache, hash_a, hash_b, _cache_tmp) = cache_with_two_blobs(&payload_a, &payload_b).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, Arc::clone(&store), RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);
    let ledger = Arc::new(PoolLedger::new(Cumulative::default()));
    let server_addr = server_eth.address();
    let sd = slash_domain();
    for round in 0..2u64 {
        let (ra, rb) = tokio::join!(
            stream_fetch_shared(
                &client_ep,
                target.clone(),
                &ctx,
                &ledger,
                &sd,
                server_addr,
                *hash_a.as_bytes(),
                0,
                0x0a00 + round,
                PullDeadlines::whole_transfer(Duration::from_secs(20)),
                0,
                0,
            ),
            stream_fetch_shared(
                &client_ep,
                target.clone(),
                &ctx,
                &ledger,
                &sd,
                server_addr,
                *hash_b.as_bytes(),
                0,
                0x0b00 + round,
                PullDeadlines::whole_transfer(Duration::from_secs(20)),
                0,
                0,
            ),
        );
        let bytes_a = ra.map_err(|e| anyhow::anyhow!("round {round} pull A failed: {e:?}"))?;
        let bytes_b = rb.map_err(|e| anyhow::anyhow!("round {round} pull B failed: {e:?}"))?;
        anyhow::ensure!(bytes_a.as_ref() == payload_a.as_slice(), "blob A mismatch");
        anyhow::ensure!(bytes_b.as_ref() == payload_b.as_slice(), "blob B mismatch");
    }

    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_voucher_rejected_total")? == 0,
        "an honest payer's vouchers must all fold the lane"
    );
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_client_declined_total")? == 0,
        "no stream may stall on a proof the client never sends"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A stream shorter than one chunk pays with exactly one voucher, its closing
/// voucher, even on a lane that already meters a live chain (#2132).
///
/// The node keeps a chunk owed until proofs pay all of it, and it lets a metering
/// voucher pay a closing partial. So after a stream's last reveal, or on a stream
/// that makes none, the payer must send only the closing voucher: no open,
/// re-anchor, or roll voucher. An anchor or re-anchor sent before a sub-chunk
/// stream's closing voucher would be read while only the partial is owed. It
/// would take lane headroom that belongs to a sibling's unread proof, and that
/// sibling would then fail when its proof wait faults. The payer anchors a
/// stream only before its first reveal, and a sub-chunk stream makes none.
#[tokio::test(flavor = "multi_thread")]
async fn a_sub_chunk_stream_on_a_live_chain_sends_only_its_closing_voucher() -> anyhow::Result<()> {
    // Several whole chunks, so the first stream opens a chain and reveals on it,
    // and a closing remainder, so it ends by rolling to a fresh live root.
    let big = vec![0x3Cu8; 3 * 1024 * 1024 + 512 * 1024];
    let small = vec![0x4Du8; 400_000];
    let (cache, big_hash, small_hash, _cache_tmp) = cache_with_two_blobs(&big, &small).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth, server_ep, server_task, metrics) =
        spawn_handler_server_with_metrics(cache, Arc::clone(&store), RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);
    let ledger = Arc::new(PoolLedger::new(Cumulative::default()));
    let sd = slash_domain();
    let fetch = |hash: decdn_cache::Hash, request_id: u64| {
        stream_fetch_shared(
            &client_ep,
            target.clone(),
            &ctx,
            &ledger,
            &sd,
            server_eth.address(),
            *hash.as_bytes(),
            0,
            request_id,
            PullDeadlines::whole_transfer(Duration::from_secs(30)),
            0,
            0,
        )
    };

    let got = fetch(big_hash, 0x2132_0001)
        .await
        .map_err(|e| anyhow::anyhow!("multi-chunk pull failed: {e:?}"))?;
    anyhow::ensure!(got.as_ref() == big.as_slice(), "multi-chunk blob mismatch");
    anyhow::ensure!(
        ledger.chain_root().is_some(),
        "the multi-chunk stream must leave the lane on a live chain"
    );

    let before = counter(&metrics, "decdn_vouchers_received_total")?;
    let got = fetch(small_hash, 0x2132_0002)
        .await
        .map_err(|e| anyhow::anyhow!("sub-chunk pull failed: {e:?}"))?;
    anyhow::ensure!(got.as_ref() == small.as_slice(), "sub-chunk blob mismatch");
    let sent = counter(&metrics, "decdn_vouchers_received_total")? - before;
    anyhow::ensure!(
        sent == 1,
        "a sub-chunk stream must pay with its closing voucher alone, sent {sent} vouchers"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The value of the unlabelled counter `name` in the node's metrics.
fn counter(metrics: &Metrics, name: &str) -> anyhow::Result<u64> {
    let encoded = metrics.encode()?;
    let prefix = format!("{name} ");
    encoded
        .lines()
        .find_map(|line| line.strip_prefix(prefix.as_str()))
        .ok_or_else(|| anyhow::anyhow!("no {name} sample"))?
        .trim()
        .parse()
        .map_err(|e| anyhow::anyhow!("parse {name}: {e}"))
}

/// A node without the blob answers `ok: false` with `NotFound`; the requester
/// surfaces the refusal without paying.
#[tokio::test(flavor = "multi_thread")]
async fn client_not_found_is_refused() -> anyhow::Result<()> {
    let (cache, _cache_tmp) = empty_cache().await?;

    let client_signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        client_signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    let ctx = pool_context(&client_ep, client_signer, deposit);

    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        [0x42u8; 32], // a hash the node does not hold
        0,
        0x9abc,
        Duration::from_secs(10),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("absent blob must be refused"))?;
    anyhow::ensure!(
        err.to_string().contains("refused") || err.to_string().contains("NotFound"),
        "error should surface the delivery refusal: {err}"
    );
    // Wire-indistinguishable from an unknown lane or owner mismatch (all
    // `NotFound`); the reason counter is the only proof the cache-miss arm ran
    // (#876). No pull-through is configured, so `!filled` is deterministic.
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_cache_miss_total 1"
        ),
        "cache-miss refusal must bump its reason counter"
    );
    // A refusal writes no frame, so neither time-to-first-byte sibling records.
    let text = metrics.encode()?;
    for line in [
        "decdn_serve_first_byte_hit_seconds_count 0",
        "decdn_serve_first_byte_miss_seconds_count 0",
    ] {
        anyhow::ensure!(
            metric_line_present(&text, line),
            "missing `{line}`:\n{text}"
        );
    }

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// **#327 / #527 idempotency guard.** A re-observed lane registration (every
/// request's capability intake calls `register_lane`, so a client that re-sends
/// its capability registers an already-tracked lane again) must NOT reset an
/// already-advanced voucher watermark — doing so would reopen the replay
/// window. Here the lane is already known with an
/// advanced watermark (hydrated from the store at construction); a fresh
/// `register_lane` for the same [`LaneKey`] must be a no-op.
#[tokio::test]
async fn register_lane_is_idempotent_and_preserves_watermark() -> anyhow::Result<()> {
    let (cache, _tmp) = empty_cache().await?;
    let store = Arc::new(MemoryPoolStateStore::new());
    let client = PrivateKeySigner::random().address();

    // Pre-seed an advanced watermark, as if vouchers had been accepted. The
    // `last_*` fields are private (#751), so build the watermark via `hydrate`.
    let advanced = LaneState::hydrate(
        pool_id(),
        client,
        operator_addr(),
        U256::from(10_000_000u64),
        0,
        U256::from(4_321u64),
        U256::from(2_048u64),
        Some([0x11; 65]),
        decdn_incentive::LaneChain::NONE,
    );
    store.record(&advanced)?;

    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let server_eth = operator_signer();
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    let handler = build_handler(
        fresh_key().public(),
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
    )?;

    // A re-observed registration arrives as a fresh (zero-watermark) lane.
    handler.register_lane(fresh_lane(client, U256::from(10_000_000u64)))?;

    let after = store
        .get(lane_key(client))?
        .ok_or_else(|| anyhow::anyhow!("lane vanished"))?;
    anyhow::ensure!(
        after.last_bytes_delivered() == U256::from(2_048u64),
        "re-observed registration reset the watermark bytes to {} (reopened #527 replay window)",
        after.last_bytes_delivered()
    );
    anyhow::ensure!(after.last_amount() == U256::from(4_321u64));
    Ok(())
}

// ===========================================================================
// Node-to-node cache-miss pull-through authorization gate (#831)
//
// The miss-hook that triggers a *paid* upstream pull must fire only for a
// request that PROVES it signs for a known lane on the named pool — pool ids are public
// on-chain, so existence cannot authorize spend. A `CountingOrigin` (returns
// NotFound but counts every fetch) stands in for the paid `NodeOrigin`, so a
// test can distinguish "the gate blocked the pull" (0 fetches) from "the pull
// was attempted" (>=1 fetch) even though both cases return NotFound to the
// client.
// ===========================================================================

/// An origin that counts how many times it was asked and always reports the blob
/// absent. As the last origin in the chain it models the paid network pull
/// without spending: a nonzero count means the miss-hook reached the (paid)
/// pull, which the authorization gate must prevent for unauthorized requests.
#[derive(Debug)]
struct CountingOrigin {
    hits: Arc<std::sync::atomic::AtomicUsize>,
}

impl decdn_cache::Origin for CountingOrigin {
    fn fetch(
        &self,
        _hash: decdn_cache::Hash,
        _max_bytes: u64,
    ) -> std::pin::Pin<
        Box<
            dyn std::future::Future<
                    Output = Result<decdn_cache::origin::OriginFetch, decdn_cache::OriginPullError>,
                > + Send
                + '_,
        >,
    > {
        self.hits.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
        Box::pin(async { Ok(decdn_cache::origin::OriginFetch::NotFound) })
    }

    fn kind(&self) -> decdn_cache::OriginKind {
        decdn_cache::OriginKind::Peer
    }
}

/// The pull-through gate authorizes ONLY a request whose bound signer holds a
/// known lane on the named pool: an unbound request and a validly-bound request
/// from another signer must NOT reach the paid pull (the counting origin stays
/// at 0), while the lane signer's bound request does. All three return `NotFound` to the
/// client (the stand-in origin has nothing); the security property is whether
/// the paid pull was attempted at all.
#[tokio::test(flavor = "multi_thread")]
async fn pull_through_gate_authorizes_only_lane_signer() -> anyhow::Result<()> {
    let hits = Arc::new(std::sync::atomic::AtomicUsize::new(0));
    let cache_tmp = tempfile::tempdir()?;
    let cache = CacheEngine::open(
        cache_tmp.path(),
        vec![Arc::new(CountingOrigin {
            hits: Arc::clone(&hits),
        }) as Arc<dyn decdn_cache::Origin>],
        16,
    )
    .await?;

    // Pool owned by `owner`; this is the only identity authorized to pull.
    let (store, owner, _deposit) = seeded_store()?;
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    // Arm pull-through, as the runtime does when the feature is enabled.
    let handler = build_handler_full_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        &loopback_domains(),
        16,
        |deps| deps.pull_through = Some(std::time::Duration::from_secs(10)),
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    // A hash the node does not have → a miss that would trigger the pull.
    let miss_hash = [0xEEu8; 32];
    let req = StreamRequest {
        hash: miss_hash,
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x0091_1001,
    };

    // 1) Unbound request: no binding → not authorized → pull NOT attempted.
    let (c1, _) = local_endpoint(fresh_key(), vec![]).await?;
    let _ = raw_request(&c1, target.clone(), &req, None).await?;
    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 0,
        "an unbound request must NOT trigger a paid pull"
    );
    shutdown([], [&c1]).await?;

    // 2) Bound to the WRONG owner: valid signature, but not the pool's owner
    //    → not authorized → pull NOT attempted.
    let intruder_sk = fresh_key();
    let intruder_node_id = B256::from(*intruder_sk.public().as_bytes());
    let (c2, _) = local_endpoint(intruder_sk, vec![]).await?;
    let intruder = PrivateKeySigner::random();
    let ext_intruder = StreamRequestExt {
        binding: Some(ClientBinding {
            ethereum_address: intruder.address().into(),
            binding_signature: sign_binding_for(&intruder, intruder_node_id)?,
        }),
        ..Default::default()
    };
    let _ = raw_request(&c2, target.clone(), &req, Some(&ext_intruder)).await?;
    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 0,
        "a binding for a non-owner address must NOT trigger a paid pull"
    );
    shutdown([], [&c2]).await?;

    // 3) Bound to the pool OWNER: authorized → the pull IS attempted (the
    //    counting origin is reached exactly once).
    let owner_sk = fresh_key();
    let owner_node_id = B256::from(*owner_sk.public().as_bytes());
    let (c3, _) = local_endpoint(owner_sk, vec![]).await?;
    let ext_owner = StreamRequestExt {
        binding: Some(ClientBinding {
            ethereum_address: owner.address().into(),
            binding_signature: sign_binding_for(&owner, owner_node_id)?,
        }),
        ..Default::default()
    };
    let _ = raw_request(&c3, target.clone(), &req, Some(&ext_owner)).await?;
    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 1,
        "the pool owner's bound request MUST trigger the pull exactly once, got {}",
        hits.load(std::sync::atomic::Ordering::SeqCst)
    );
    shutdown([], [&c3]).await?;

    shutdown([server_task], [&server_ep]).await?;
    Ok(())
}

/// The pull-through gate is the same *signer* question as the binding gate: on
/// a lane with a delegated voucher signer, only the delegate can make this
/// node front upstream USDC. The funder — which cannot produce an acceptable
/// voucher — must not.
#[tokio::test(flavor = "multi_thread")]
async fn pull_through_authorizes_the_delegate_not_the_funder() -> anyhow::Result<()> {
    let hits = Arc::new(std::sync::atomic::AtomicUsize::new(0));
    let cache_tmp = tempfile::tempdir()?;
    let cache = CacheEngine::open(
        cache_tmp.path(),
        vec![Arc::new(CountingOrigin {
            hits: Arc::clone(&hits),
        }) as Arc<dyn decdn_cache::Origin>],
        16,
    )
    .await?;

    let (store, funder, delegate) = delegate_signer_store()?;
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_full_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        &loopback_domains(),
        16,
        |deps| deps.pull_through = Some(std::time::Duration::from_secs(10)),
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let req = StreamRequest {
        hash: [0xEDu8; 32], // never cached — a miss that would trigger the pull
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x00de_1e04,
    };

    // 1) Bound as the FUNDER: it holds no voucher authority here, so it must not
    //    make this node spend upstream.
    let funder_sk = fresh_key();
    let funder_node_id = B256::from(*funder_sk.public().as_bytes());
    let (c1, _) = local_endpoint(funder_sk, vec![]).await?;
    let ext_funder = binding_ext(&funder, funder_node_id)?;
    let _ = raw_request(&c1, target.clone(), &req, Some(&ext_funder)).await?;
    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 0,
        "the funder behind a delegated lane must NOT trigger a paid pull"
    );
    shutdown([], [&c1]).await?;

    // 2) Bound as the pinned DELEGATE signer: authorized → the pull is attempted.
    let delegate_sk = fresh_key();
    let delegate_node_id = B256::from(*delegate_sk.public().as_bytes());
    let (c2, _) = local_endpoint(delegate_sk, vec![]).await?;
    let ext_delegate = binding_ext(&delegate, delegate_node_id)?;
    let _ = raw_request(&c2, target.clone(), &req, Some(&ext_delegate)).await?;
    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 1,
        "the pinned voucher signer MUST trigger the pull exactly once, got {}",
        hits.load(std::sync::atomic::Ordering::SeqCst)
    );
    shutdown([], [&c2]).await?;

    shutdown([server_task], [&server_ep]).await?;
    Ok(())
}

/// Build a pull-through-armed handler over a `CountingOrigin` with an ADR 011
/// origin deny-set wired in, and return the dialable target plus the hit
/// counter. Shared by the two blacklist-subject tests below, which differ only
/// in which address is on the deny-set.
async fn spawn_counting_pull_server_with_deny(
    store: Arc<dyn PoolStateStore>,
    denied: &[alloy::primitives::Address],
    remaining: U256,
    owner: Address,
) -> anyhow::Result<(
    EndpointAddr,
    Arc<std::sync::atomic::AtomicUsize>,
    Endpoint,
    tokio::task::JoinHandle<()>,
    tempfile::TempDir,
    Arc<Metrics>,
)> {
    let hits = Arc::new(std::sync::atomic::AtomicUsize::new(0));
    let cache_tmp = tempfile::tempdir()?;
    let cache = CacheEngine::open(
        cache_tmp.path(),
        vec![Arc::new(CountingOrigin {
            hits: Arc::clone(&hits),
        }) as Arc<dyn decdn_cache::Origin>],
        16,
    )
    .await?;
    let deny = Arc::new(decdn_node::content_deny::ContentDenylist::new(
        &content_with_origins(denied),
    ));
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_full_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        &loopback_domains(),
        16,
        |deps| {
            deps.pull_through = Some(std::time::Duration::from_secs(10));
            deps.content_deny = deny;
            deps.pool_view = Some(Arc::new(FixedRemainingPoolView { owner, remaining }));
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((target, hits, server_ep, server_task, cache_tmp, metrics))
}

/// [`spawn_counting_pull_server_with_deny`] with an empty deny-set. `remaining`
/// is the pool headroom the floor-`M` pull-path gate reads through the stub
/// pool-view; `owner` is a benign, non-denied funder.
async fn spawn_counting_pull_server(
    store: Arc<dyn PoolStateStore>,
    remaining: U256,
    owner: Address,
) -> anyhow::Result<(
    EndpointAddr,
    Arc<std::sync::atomic::AtomicUsize>,
    Endpoint,
    tokio::task::JoinHandle<()>,
    tempfile::TempDir,
    Arc<Metrics>,
)> {
    spawn_counting_pull_server_with_deny(store, &[], remaining, owner).await
}

/// #1519, the headline case: an underfunded pool must not make the node spend.
///
/// Every cache-miss fill tier is gated on LANE AUTHORITY (`pull_authorized`)
/// and none was gated on solvency, so before the pre-spend floor a dust-deposit
/// pool could name absent hashes, make the node pay its paid upstream for each,
/// and be refused afterwards by the serve-path gate. The attacker gained nothing —
/// #1516 closed the free-egress half — but the operator still paid.
///
/// `hits == 0` IS the acceptance criterion: the origin was never contacted. The
/// second counter assertion is what makes the test specific rather than merely
/// green — a refusal that came from the fill missing (rather than from the floor)
/// would bump `cache_miss` instead, and `hits == 0` alone cannot tell them apart.
#[tokio::test(flavor = "multi_thread")]
async fn underfunded_pool_never_reaches_the_paid_pull() -> anyhow::Result<()> {
    let window_cost = min_payment(HARNESS_FLOOR_BYTES, RATE_PER_MB);
    let deposit = window_cost.saturating_sub(U256::from(1u64));
    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        deposit,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    // Pool remaining sits one base unit under the window's cost.
    let (target, hits, server_ep, server_task, _cache_tmp, metrics) =
        spawn_counting_pull_server(store_dyn, deposit, signer.address()).await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    // Bound, so `pull_authorized` would have said yes and the pull WOULD have run.
    let ext = binding_ext(&signer, client_node_id)?;
    let req = StreamRequest {
        hash: [0x19u8; 32], // never cached — a miss that would trigger the pull
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x1519,
    };
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), resp_ext) => {
            anyhow::ensure!(!resp.body.ok, "an underfunded miss must be refused");
            // Bound + known lane → the pre-spend floor gate refuses a proven owner,
            // so the wire code is `Unfunded`, not the prober-facing `NotFound`.
            anyhow::ensure!(
                matches!(
                    resp_ext.error,
                    Some(decdn_protocol::client::StreamError::Unfunded)
                ),
                "expected the Unfunded wire code, got {:?}",
                resp_ext.error
            );
        }
        other => anyhow::bail!("expected a signed refusal, got {other:?}"),
    }

    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 0,
        "the origin must never be contacted for a pool that cannot pay: {} hits",
        hits.load(std::sync::atomic::Ordering::SeqCst)
    );
    let text = metrics.encode()?;
    anyhow::ensure!(
        metric_line_present(
            &text,
            "decdn_serve_stream_rejected_insufficient_deposit_total 1"
        ),
        "the refusal must be attributed to the deposit floor"
    );
    anyhow::ensure!(
        metric_line_present(&text, "decdn_serve_stream_rejected_cache_miss_total 0"),
        "the refusal must come from the floor, not from the fill missing"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The boundary control for #1519, and the reason the floor cannot be quietly
/// tightened. A pool funded to EXACTLY one credit window clears the floor
/// (the check is `<`) and must still reach the pull.
///
/// Without this, raising the floor — or flipping `<` to `<=` — would break
/// nothing: `underfunded_pool_never_reaches_the_paid_pull` above only pins
/// that an *under*-funded pool is stopped. A floor that also stopped funded
/// pools would turn a cold fetch into a permanent refusal on every node.
#[tokio::test(flavor = "multi_thread")]
async fn funded_pool_still_reaches_the_paid_pull() -> anyhow::Result<()> {
    let window_cost = min_payment(HARNESS_FLOOR_BYTES, RATE_PER_MB);
    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&LaneState::hydrate(
        pool_id(),
        signer.address(),
        operator_addr(),
        window_cost,
        0,
        U256::ZERO,
        U256::ZERO,
        None,
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    // Pool remaining exactly equals the window's cost — the funded boundary.
    let (target, hits, server_ep, server_task, _cache_tmp, metrics) =
        spawn_counting_pull_server(store_dyn, window_cost, signer.address()).await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let ext = binding_ext(&signer, client_node_id)?;
    let req = StreamRequest {
        hash: [0x1Au8; 32],
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x151A,
    };
    // `CountingOrigin` has nothing to serve, so the request still ends in a
    // refusal — but a `cache_miss` one, AFTER the origin was asked. Asserted rather
    // than discarded: `let _ =` would stay green on a malformed frame or an
    // unexpected `ok: true`.
    match raw_request(&client_ep, target, &req, Some(&ext)).await? {
        (ClientMessage::StreamResponse(resp), _resp_ext) => anyhow::ensure!(
            !resp.body.ok,
            "CountingOrigin holds nothing, so this must still end in a refusal"
        ),
        other => anyhow::bail!("expected a signed StreamResponse, got {other:?}"),
    }

    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 1,
        "a pool funded to exactly the floor must still reach the pull: {} hits",
        hits.load(std::sync::atomic::Ordering::SeqCst)
    );
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_insufficient_deposit_total 0"
        ),
        "an exactly-funded pool must not trip the deposit floor"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The `last_amount` term of the #1519 floor, and the case that actually happens
/// in production. The two tests above use a fresh lane, so
/// `deposit.saturating_sub(last_amount)` is never exercised — a mutant that reads
/// `let headroom = deposit;` passes the entire suite.
///
/// A *dust* pool is the adversarial shape; a *spent-out* pool is the common
/// one. Here the gross deposit is 10 USDC — a million times the floor — while the
/// remaining headroom is 5, one below it. Gating on the gross deposit would let
/// this pool drive an origin pull for every absent hash it names, forever,
/// which is the same drain #1519 closes against a dust pool.
#[tokio::test(flavor = "multi_thread")]
async fn spent_out_pool_never_reaches_the_paid_pull() -> anyhow::Result<()> {
    let client = PrivateKeySigner::random();
    let store = Arc::new(MemoryPoolStateStore::new());
    // `last_*` are private (#751), so the spent-down watermark comes from `hydrate`.
    store.record(&LaneState::hydrate(
        pool_id(),
        client.address(),
        operator_addr(),
        U256::from(10_000_000u64),
        0,
        U256::from(9_999_995u64),
        U256::from(1_048_575_488u64),
        Some([0x33; 65]),
        decdn_incentive::LaneChain::NONE,
    ))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();
    // Gross deposit 10 USDC, but only 5 remaining after prior redeems — well
    // below the window cost.
    let (target, hits, server_ep, server_task, _cache_tmp, metrics) =
        spawn_counting_pull_server(store_dyn, U256::from(5u64), client.address()).await?;

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let ext = binding_ext(&Arc::new(client), client_node_id)?;
    let req = StreamRequest {
        hash: [0x33u8; 32],
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x3301,
    };
    let _ = raw_request(&client_ep, target, &req, Some(&ext)).await?;

    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 0,
        "a spent-out pool must not reach the origin despite a large gross deposit: {} hits",
        hits.load(std::sync::atomic::Ordering::SeqCst)
    );
    anyhow::ensure!(
        metric_line_present(
            &metrics.encode()?,
            "decdn_serve_stream_rejected_insufficient_deposit_total 1"
        ),
        "the refusal must be attributed to the deposit floor, not to the fill missing"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// ADR 011 keys compliance on the FUNDER, so a blacklisted funder must not make
/// this node front upstream USDC even when a perfectly clean delegate key is
/// doing the signing. The delegate's binding satisfies `pull_authorized` (spend
/// authority); the serve gate's funder check is the only thing standing
/// between a sanctioned address and this operator's egress bill.
#[tokio::test(flavor = "multi_thread")]
async fn pull_through_refuses_a_blacklisted_funder_behind_a_clean_delegate() -> anyhow::Result<()> {
    let (store, funder, delegate) = delegate_signer_store()?;
    let (target, hits, server_ep, server_task, _cache_tmp, _metrics) =
        spawn_counting_pull_server_with_deny(
            store,
            &[funder.address()],
            U256::MAX,
            funder.address(),
        )
        .await?;

    let delegate_sk = fresh_key();
    let delegate_node_id = B256::from(*delegate_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(delegate_sk, vec![]).await?;
    let ext = binding_ext(&delegate, delegate_node_id)?;
    let req = StreamRequest {
        hash: [0xB1u8; 32], // never cached — a miss that would trigger the pull
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x00b1_ac11,
    };
    let _ = raw_request(&client_ep, target, &req, Some(&ext)).await?;
    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 0,
        "a blacklisted funder must NOT trigger a paid pull, clean delegate or not"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The mirror image, and the deliberate behaviour change: a CLEAN funder whose
/// pinned `voucher_signer` happens to be on the deny-set IS authorized to pull.
/// A takedown sanctions the money, not whichever throwaway key signs the
/// vouchers, so the signer's deny-set membership is not a compliance event here.
///
/// This test fails the moment anyone re-adds an `is_origin_denied` check on the
/// bound (signer) address — the pre-split check that silently became a signer
/// check when the funder/signer roles were split. It also pins the agreement
/// with `dispatch.rs`, whose serve gate is funder-only: without this, the two
/// paths could drift apart unnoticed, since with `voucher_signer == client` on
/// every lane that exists today no other test can tell them apart.
#[tokio::test(flavor = "multi_thread")]
async fn pull_through_allows_a_clean_funder_with_a_blacklisted_delegate() -> anyhow::Result<()> {
    let (store, funder, delegate) = delegate_signer_store()?;
    // The funder (pool owner) is clean; only the delegate signer is on the
    // deny-set, and the signer's membership is not a compliance event.
    let (target, hits, server_ep, server_task, _cache_tmp, _metrics) =
        spawn_counting_pull_server_with_deny(
            store,
            &[delegate.address()],
            U256::MAX,
            funder.address(),
        )
        .await?;

    let delegate_sk = fresh_key();
    let delegate_node_id = B256::from(*delegate_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(delegate_sk, vec![]).await?;
    let ext = binding_ext(&delegate, delegate_node_id)?;
    let req = StreamRequest {
        hash: [0xB2u8; 32], // never cached — a miss that would trigger the pull
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x00b2_ac11,
    };
    let _ = raw_request(&client_ep, target, &req, Some(&ext)).await?;
    anyhow::ensure!(
        hits.load(std::sync::atomic::Ordering::SeqCst) == 1,
        "a clean funder's delegated request MUST trigger the pull exactly once, got {}",
        hits.load(std::sync::atomic::Ordering::SeqCst)
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

// ===========================================================================
// #859 — handler-level outer-deadline regression. `ClientHandler::try_pull_through`
// wraps the whole pull in ONE `tokio::time::timeout`. Before #859 that outer
// deadline was set EQUAL to the per-candidate budget (`node_pull_timeout_sec`),
// so a pull needing more than one per-candidate budget's wall-clock (e.g.
// candidate #1 stalls a full budget, then #2 delivers) was cancelled before it
// could finish. The derived `outer_pull_deadline` (N × each candidate's three
// sequential stages, + slack) must accommodate it. A single slow origin taking
// longer than one per-candidate
// budget models that scenario through the real handler — the layer the bug
// actually lived in (the NodeOrigin-level fallthrough test cannot, since
// `NodeOrigin::fetch` has no outer wrapper).
// ===========================================================================

/// An origin that returns the blob after a fixed delay — models a pull whose
/// total wall-clock exceeds one per-candidate budget (stall-then-fallback).
#[derive(Debug)]
struct SlowOrigin {
    payload: Vec<u8>,
    delay: Duration,
}

impl decdn_cache::Origin for SlowOrigin {
    fn fetch(
        &self,
        _hash: decdn_cache::Hash,
        _max_bytes: u64,
    ) -> std::pin::Pin<
        Box<
            dyn std::future::Future<
                    Output = Result<decdn_cache::origin::OriginFetch, decdn_cache::OriginPullError>,
                > + Send
                + '_,
        >,
    > {
        let payload = self.payload.clone();
        let delay = self.delay;
        Box::pin(async move {
            tokio::time::sleep(delay).await;
            Ok(decdn_cache::origin::OriginFetch::found_one_shot(
                payload.into(),
            ))
        })
    }

    fn kind(&self) -> decdn_cache::OriginKind {
        decdn_cache::OriginKind::Peer
    }
}

/// Drive one authorized owner request for a hash served only by a `SlowOrigin`
/// taking `origin_delay`, with the handler's outer pull-through deadline set to
/// `outer_deadline`. Returns whether the foreground pull completed and filled the
/// store (probed via a cloned cache handle after the response settles). Only the
/// foreground outer-deadline path can fill the store — there is no background warm
/// (#1610) that could fill it after the fact and mask the broken case.
async fn pull_through_fills_under_deadline(
    outer_deadline: Duration,
    origin_delay: Duration,
) -> anyhow::Result<bool> {
    let payload = vec![0x5Au8; 4096];
    let want = decdn_cache::Hash::new(&payload);
    let cache_tmp = tempfile::tempdir()?;
    let cache = CacheEngine::open(
        cache_tmp.path(),
        vec![Arc::new(SlowOrigin {
            payload: payload.clone(),
            delay: origin_delay,
        }) as Arc<dyn decdn_cache::Origin>],
        16,
    )
    .await?;
    let cache_probe = cache.clone();

    let (store, owner, _deposit) = seeded_store()?;
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_full_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        &loopback_domains(),
        16,
        |deps| deps.pull_through = Some(outer_deadline),
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let req = StreamRequest {
        hash: *want.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x0091_1001,
    };
    let owner_sk = fresh_key();
    let owner_node_id = B256::from(*owner_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(owner_sk, vec![]).await?;
    let ext_owner = StreamRequestExt {
        binding: Some(ClientBinding {
            ethereum_address: owner.address().into(),
            binding_signature: sign_binding_for(&owner, owner_node_id)?,
        }),
        ..Default::default()
    };
    // The handler answers only after `try_pull_through` resolves (populate
    // completes or the outer deadline fires), so the store state is settled by
    // the time this returns.
    let _ = raw_request(&client_ep, target, &req, Some(&ext_owner)).await?;
    shutdown([], [&client_ep]).await?;

    let filled = cache_probe.has(want).await?;
    shutdown([server_task], [&server_ep]).await?;
    Ok(filled)
}

/// #859 regression: a slow pull (1.5s) exceeding one 1s per-candidate budget is
/// abandoned by an outer deadline equal to that budget (the #859 bug), but
/// completes under the derived `outer_pull_deadline`. This is the only test in
/// the suite that fails if the `pull_through` deadline is re-wired to the per-candidate
/// value (re-introducing #859).
#[tokio::test(flavor = "multi_thread")]
async fn pull_through_outer_deadline_accommodates_a_slow_pull() -> anyhow::Result<()> {
    let per = Duration::from_secs(1);
    let stall = Duration::from_secs(1);
    let slow = Duration::from_millis(1500); // > per, well under outer_pull_deadline(per, stall)

    // Buggy wiring (#859): outer == per_candidate cancels the slow pull → store empty.
    anyhow::ensure!(
        !pull_through_fills_under_deadline(per, slow).await?,
        "an outer deadline equal to the per-candidate budget must abandon the slow pull (the #859 bug)"
    );
    // Fixed wiring: the derived outer deadline accommodates it → store filled.
    anyhow::ensure!(
        pull_through_fills_under_deadline(
            decdn_node::selection::outer_pull_deadline(per, stall),
            slow
        )
        .await?,
        "the derived outer deadline must let a pull exceeding one per-candidate budget complete"
    );
    Ok(())
}

/// Build a cache whose local store is EMPTY but whose filesystem origin holds
/// `payload`, so a `cdn/client/v1` cache miss must reactively pull the origin
/// through to serve. Both temp dirs are returned so the caller keeps the origin
/// alive across the fetch (unlike [`cache_with_two_blobs`], which pre-populates
/// the store and drops the origin).
///
/// The engine is opened with an `Arc<CacheMetrics>` (returned) so callers can
/// assert `origin_fetches` — the counter that pins whether the node actually
/// read its origin (`1`) or short-circuited before any egress (`0`). `open`
/// wires no metrics, so `origin_fetches.inc()` would be a no-op there.
async fn empty_cache_with_fs_origin(
    payload: &[u8],
) -> anyhow::Result<(
    CacheEngine,
    decdn_cache::Hash,
    Arc<CacheMetrics>,
    tempfile::TempDir,
    tempfile::TempDir,
)> {
    let hash = decdn_cache::Hash::new(payload);
    let origin_dir = tempfile::tempdir()?;
    let hex = hash.to_hex();
    let shard = hex
        .get(..2)
        .ok_or_else(|| anyhow::anyhow!("hex too short"))?;
    let dir = origin_dir.path().join(shard);
    std::fs::create_dir_all(&dir)?;
    std::fs::write(dir.join(hex.as_str()), payload)?;

    let cache_dir = tempfile::tempdir()?;
    let origin = Arc::new(decdn_cache::FilesystemOrigin::new(origin_dir.path()).await?);
    let cache_metrics = Arc::new(CacheMetrics::default());
    let cache = CacheEngine::open_full(
        cache_dir.path(),
        vec![origin as Arc<dyn decdn_cache::Origin>],
        16,
        PinnedHashes::empty(),
        RetryPolicy::default(),
        CircuitBreakerPolicy::default(),
        Some(Arc::clone(&cache_metrics)),
        Duration::ZERO,
    )
    .await?;
    // Local store intentionally left unpopulated: `has(hash)` is false until a
    // pull-through fills it, which is what the tests below exercise.
    anyhow::ensure!(!cache.has(hash).await?, "cache store must start empty");
    Ok((cache, hash, cache_metrics, origin_dir, cache_dir))
}

/// Spawn a `ClientHandler` server with buffered origin pull-through attached
/// (`ClientHandlerDeps.pull_through`), returning the dial target and the server's voucher
/// signer address. Unlike [`spawn_handler_server`], the handler is built inline
/// so pull-through can be wired before it is spawned.
async fn spawn_pull_through_server(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
) -> anyhow::Result<(
    EndpointAddr,
    Address,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        16,
        |deps| deps.pull_through = Some(Duration::from_secs(20)),
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((
        target,
        server_eth.address(),
        server_ep,
        server_task,
        metrics,
    ))
}

/// Spawn a `ClientHandler` server with `relay_foreign_namespaces = false`
/// (#1759): an origin-only node. Reactive fs-origin pull-through
/// (`ClientHandlerDeps.pull_through`) is wired the same as
/// [`spawn_pull_through_server`] so a hash the backend genuinely holds can
/// still be served; the only difference is the origin-only gate.
async fn spawn_origin_only_server(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
) -> anyhow::Result<(EndpointAddr, Address, Endpoint, tokio::task::JoinHandle<()>)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        16,
        |deps| {
            deps.pull_through = Some(Duration::from_secs(20));
            deps.relay_foreign_namespaces = false;
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((target, server_eth.address(), server_ep, server_task))
}

/// Same as [`spawn_origin_only_server`] but also returns the server's
/// [`Metrics`], so a test can tell a policy decline (`ForeignNamespaceDeclined`)
/// apart from a backend fault (`InternalError`) by the operator's own counters,
/// not just by the wire error (#1766).
async fn spawn_origin_only_server_with_metrics(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
) -> anyhow::Result<(
    EndpointAddr,
    Address,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        16,
        |deps| {
            deps.pull_through = Some(Duration::from_secs(20));
            deps.relay_foreign_namespaces = false;
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((
        target,
        server_eth.address(),
        server_ep,
        server_task,
        metrics,
    ))
}

/// #1766: an origin-only node whose own backend FAULTS on the live probe (a
/// connection-refused `HEAD` against an unreachable http origin) must refuse
/// with `InternalError`, NOT a signed `NotFound` — a fault is not an
/// absence, and signing an authoritative negative during a backend outage
/// would tell a paying client this node's own content is gone.
///
/// `http://127.0.0.1:1/` is used as the "unreachable" origin: port 1 is a
/// privileged, essentially never-listening port, so `reqwest` gets an
/// immediate connection-refused rather than a slow timeout — the origin-chain
/// walk in `origin_probe_presence` sees a live `Err`, not the timeout arm
/// (that arm is already covered by the cache-engine unit tests).
#[tokio::test(flavor = "multi_thread")]
async fn origin_only_node_fault_is_internal_error_not_signed_not_found() -> anyhow::Result<()> {
    let hash = decdn_cache::Hash::new(b"origin-only fault probe");
    let cache_dir = tempfile::tempdir()?;
    let unreachable = decdn_cache::parse_origin_url("http://127.0.0.1:1/")?;
    let origin = Arc::new(decdn_cache::HttpOrigin::new(unreachable)?);
    let cache = CacheEngine::open_full(
        cache_dir.path(),
        vec![origin as Arc<dyn decdn_cache::Origin>],
        16,
        PinnedHashes::empty(),
        RetryPolicy::default(),
        CircuitBreakerPolicy::default(),
        Some(Arc::new(CacheMetrics::default())),
        Duration::ZERO,
    )
    .await?;
    anyhow::ensure!(!cache.has(hash).await?, "cache store must start empty");

    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, metrics) =
        spawn_origin_only_server_with_metrics(cache, Arc::clone(&store)).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);

    match stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    {
        Ok(_) => anyhow::bail!("a faulting backend probe must not deliver"),
        Err(e) => {
            let msg = e.to_string();
            anyhow::ensure!(
                msg.contains("Declined"),
                "a faulting backend probe must surface as Declined (InternalError), got: {e}"
            );
            anyhow::ensure!(
                !msg.contains("NotFound"),
                "a faulting backend probe must NOT sign an authoritative NotFound, got: {e}"
            );
        }
    }

    let encoded = metrics.encode()?;
    anyhow::ensure!(
        metric_line_present(
            &encoded,
            "decdn_serve_stream_rejected_internal_error_total 1"
        ),
        "expected the fault to land in the internal-error counter, not the \
         foreign-decline one; counters were:\n{}",
        encoded
            .lines()
            .filter(|l| l.starts_with("decdn_serve_stream_rejected"))
            .collect::<Vec<_>>()
            .join("\n")
    );
    anyhow::ensure!(
        metric_line_present(
            &encoded,
            "decdn_serve_stream_rejected_foreign_declined_total 0"
        ),
        "a backend fault must not be counted as a foreign decline"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Build a cache holding a blob that the local STORE has already accepted (a
/// past import) but whose backing filesystem origin no longer exists — the
/// backend genuinely does not hold it anymore, so a fresh
/// `CacheEngine::origin_probe_size` reads `None` (a transport error against
/// the now-deleted origin directory) even though `cache.has` is `true`. Used
/// to prove the origin-only gate (#1759) sits ABOVE the cache-hit branch: a
/// foreign hash already sitting in the store is still declined.
async fn cache_with_foreign_blob_imported(
    payload: &[u8],
) -> anyhow::Result<(
    CacheEngine,
    decdn_cache::Hash,
    Arc<CacheMetrics>,
    tempfile::TempDir,
)> {
    let hash = decdn_cache::Hash::new(payload);
    let origin_dir = tempfile::tempdir()?;
    let hex = hash.to_hex();
    let shard = hex
        .get(..2)
        .ok_or_else(|| anyhow::anyhow!("hex too short"))?;
    let dir = origin_dir.path().join(shard);
    std::fs::create_dir_all(&dir)?;
    std::fs::write(dir.join(hex.as_str()), payload)?;

    let cache_dir = tempfile::tempdir()?;
    let origin = Arc::new(decdn_cache::FilesystemOrigin::new(origin_dir.path()).await?);
    let cache_metrics = Arc::new(CacheMetrics::default());
    let cache = CacheEngine::open_full(
        cache_dir.path(),
        vec![origin as Arc<dyn decdn_cache::Origin>],
        16,
        PinnedHashes::empty(),
        RetryPolicy::default(),
        CircuitBreakerPolicy::default(),
        Some(Arc::clone(&cache_metrics)),
        Duration::ZERO,
    )
    .await?;
    let _ = cache.get(hash).await?; // pulls into the local store now
    anyhow::ensure!(
        cache.has(hash).await?,
        "precondition: the blob must be in the local store"
    );
    // Drop the fs origin directory: the backend no longer holds the object,
    // even though the store already imported it.
    drop(origin_dir);
    Ok((cache, hash, cache_metrics, cache_dir))
}

/// #1759: an origin-only node declines a hash its own backend does not hold,
/// even for a request carrying a valid client binding — the gate is
/// backend-authoritative, not a binding/authorization check.
#[tokio::test(flavor = "multi_thread")]
async fn origin_only_node_declines_a_foreign_hash() -> anyhow::Result<()> {
    // Backend holds `payload`/`hash`; we request a DIFFERENT (foreign) hash.
    let payload = vec![0x11u8; 64 * 1024];
    let (cache, _own_hash, cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    let foreign_hash = decdn_cache::Hash::from([0x9Au8; 32]);

    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task) =
        spawn_origin_only_server(cache, Arc::clone(&store)).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);

    let res = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *foreign_hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await;
    anyhow::ensure!(res.is_err(), "origin-only node must decline a foreign hash");

    // Declined BEFORE any origin egress / discovery.
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 0,
        "foreign decline must not touch the origin, got {}",
        cache_metrics.origin_fetches.get()
    );
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1759 control: an origin-only node still serves a hash its own backend
/// holds — the gate refuses only foreign content, not everything.
#[tokio::test(flavor = "multi_thread")]
async fn origin_only_node_serves_its_own_backend_hash() -> anyhow::Result<()> {
    let payload = vec![0x22u8; 64 * 1024];
    let (cache, hash, cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task) =
        spawn_origin_only_server(cache, Arc::clone(&store)).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch for own-backend hash"
    );
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 1,
        "expected exactly 1 origin fetch to fill the own-backend hash, got {}",
        cache_metrics.origin_fetches.get()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1759: the gate is categorical — it sits ABOVE the cache-hit branch, so a
/// foreign hash already sitting in the store (imported by an earlier relay,
/// say) is still declined once the backend no longer holds it.
#[tokio::test(flavor = "multi_thread")]
async fn origin_only_node_declines_a_foreign_blob_already_in_cache() -> anyhow::Result<()> {
    let payload = vec![0x33u8; 32 * 1024];
    let (cache, foreign_hash, cache_metrics, _cache_tmp) =
        cache_with_foreign_blob_imported(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task) =
        spawn_origin_only_server(cache, Arc::clone(&store)).await?;

    // Baseline AFTER setup's own origin fetch (from importing the blob into the
    // store), so the assertion below isolates fetches caused by THIS request.
    let baseline_fetches = cache_metrics.origin_fetches.get();

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit);

    let res = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *foreign_hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await;
    anyhow::ensure!(
        res.is_err(),
        "origin-only node must decline a foreign hash even when it is already cached"
    );
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == baseline_fetches,
        "the cache-hit gate must not touch the origin, got {} beyond baseline {}",
        cache_metrics.origin_fetches.get(),
        baseline_fetches
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1115: a direct client fetch that sends the ADR 005 client identity binding
/// authorizes reactive origin pull-through — with the blob present only in the
/// node's filesystem origin (an empty local store), the miss populates from the
/// origin and the bytes are delivered + hash-verified.
#[tokio::test(flavor = "multi_thread")]
async fn bound_client_fetch_triggers_reactive_origin_pull_through() -> anyhow::Result<()> {
    let payload = vec![0x7Bu8; 64 * 1024];
    let (cache, hash, cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, metrics) =
        spawn_pull_through_server(cache, Arc::clone(&store)).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    // Sign the binding over the CLIENT's own node id with the pool-owning key,
    // under the handler's binding domain — exactly what `pull_authorized` checks.
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch"
    );
    // The blob existed only in the fs origin, so serving it proves the node
    // reactively pulled the origin exactly once (not a double-pull, not some
    // other path).
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 1,
        "expected exactly 1 origin fetch, got {}",
        cache_metrics.origin_fetches.get()
    );
    assert_first_byte_class(&metrics, "miss")?;

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// ADR 041: the buy-side serve-economics gate (the `margin` policy's buy
/// ceiling + the per-source [`decdn_node::warming_allowance::WarmingAllowance`])
/// lives ONLY on `NodeOrigin`'s peer-candidate relay path — the buy loop that
/// decides what to pay ANOTHER node. It is never consulted on the own-namespace
/// path: filling from this node's OWN configured origin is not a purchase, so
/// there is nothing to gate.
///
/// The source's warming allowance is drained to fully spent and the operator
/// fee share pinned at 0 bps before the fetch — settings that, under the
/// `margin` policy, refuse EVERY peer-relay candidate at any positive quote —
/// yet the own-origin fetch still serves the blob intact, proving the own-
/// namespace path never reads either.
#[tokio::test(flavor = "multi_thread")]
async fn own_namespace_miss_ignores_serve_economics_gate() -> anyhow::Result<()> {
    let payload = vec![0x9Eu8; 64 * 1024];
    let (cache, hash, cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);

    // The most restrictive possible ADR 041 settings: an arbitrary source's
    // warming allowance fully drained, and a 0 bps operator fee share (so even
    // the amortized "safe" floor collapses to 0). If the own-origin path
    // consulted either, this fetch would refuse.
    let warming = Arc::new(decdn_node::warming_allowance::WarmingAllowance::new(
        1000, 0,
    ));
    warming.debit_speculative(
        decdn_node::warming_allowance::SourceId::from_bytes([0xAAu8; 32]),
        decdn_cache::Hash::from_bytes([0xBBu8; 32]),
        u64::MAX,
    );
    anyhow::ensure!(
        !warming.available(decdn_node::warming_allowance::SourceId::from_bytes(
            [0xAAu8; 32]
        )),
        "precondition: the source must read as fully spent"
    );

    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store.clone(),
        RATE_PER_MB,
        16,
        |deps| {
            deps.pull_through = Some(Duration::from_secs(20));
            deps.warming_credit = Arc::new(
                decdn_node::warming_allowance::DirectWarmingCreditSink::new(Arc::clone(&warming)),
            );
            deps.operator_shares = decdn_node::fee_shares::OperatorShares::new(0);
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch"
    );
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 1,
        "expected exactly 1 origin fetch (own-namespace path taken), got {}",
        cache_metrics.origin_fetches.get()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// ADR 041: a completed serve credits the warming source through the SHIPPED
/// path — the bounded channel and background aggregator the runtime wires — not
/// just through the inline test sink.
///
/// Every other ADR 041 test here reads the ledger synchronously and so uses
/// `DirectWarmingCreditSink`. That leaves the shipped chain
/// (`credit_warming_serve` -> resolve the source -> `try_send` -> aggregator ->
/// `credit_source`) proven by unit tests alone: an aggregator that never drained
/// would keep every one of them green. This drives that chain end-to-end over a
/// real paid fetch, and polls because the apply is asynchronous by design.
///
/// Scope: the test builds its own deps and spawns its own aggregator, so it
/// covers the chain, not the runtime's wiring of it. Two things outside this
/// test cover that instead. `build_chain_and_handlers` names every
/// `ClientHandlerDeps` field in one exhaustive literal, so dropping the
/// `warming_credit` line is a missing-field compile error rather than a silent
/// fall back to `NoopWarmingCreditSink`. And a node that did fall back would
/// enqueue nothing and so drop nothing, which is why
/// `decdn_warming_credits_applied_total` exists beside the drop counter: on a
/// live node the two read together tell "no credits lost" apart from "no
/// credits at all".
#[tokio::test(flavor = "multi_thread")]
async fn a_completed_serve_credits_the_source_through_the_background_aggregator()
-> anyhow::Result<()> {
    const SOURCE: decdn_node::warming_allowance::SourceId =
        decdn_node::warming_allowance::SourceId::from_bytes([0xA1u8; 32]);
    const OP_BPS: u16 = 6000;
    const BUDGET: u64 = 1_000_000;

    let payload = vec![0x5Cu8; 64 * 1024];
    let (cache, hash, _cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);

    // Tag the blob to SOURCE with a speculative debit of the whole budget: the
    // source reads as spent until a serve credits it, and any positive margin
    // makes it available again. So `available` flips exactly when the aggregator
    // applies the credit, which is the signal this test waits on.
    let warming = Arc::new(decdn_node::warming_allowance::WarmingAllowance::new(
        BUDGET, 0,
    ));
    warming.debit_speculative(SOURCE, hash, BUDGET);
    anyhow::ensure!(
        !warming.available(SOURCE),
        "precondition: the speculative buy must leave the source spent"
    );

    let (warming_credit, creditor) = decdn_node::warming_allowance::spawn_warming_creditor(
        Arc::clone(&warming),
        Arc::clone(&metrics),
    );

    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store.clone(),
        RATE_PER_MB,
        16,
        |deps| {
            deps.pull_through = Some(Duration::from_secs(20));
            deps.warming_credit = warming_credit;
            deps.operator_shares = decdn_node::fee_shares::OperatorShares::new(OP_BPS);
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_dec0,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch"
    );

    let mut credited = false;
    for _ in 0..500 {
        if warming.available(SOURCE) {
            credited = true;
            break;
        }
        tokio::time::sleep(Duration::from_millis(10)).await;
    }
    anyhow::ensure!(
        credited,
        "the serve credit never reached the ledger through the channel sink"
    );

    anyhow::ensure!(
        creditor.shutdown().await.is_ok(),
        "the aggregator must exit cleanly"
    );
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1115 control: the SAME setup WITHOUT a client binding is refused. An
/// unauthenticated request fails `pull_authorized`, so the buffered pull-through
/// never runs and the origin-only blob is a clean `CacheMiss` delivery refusal —
/// pinning that the binding is what unlocks the reactive path.
#[tokio::test(flavor = "multi_thread")]
async fn unbound_client_fetch_is_refused_on_origin_only_blob() -> anyhow::Result<()> {
    let payload = vec![0x7Bu8; 64 * 1024];
    let (cache, hash, cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, _metrics) =
        spawn_pull_through_server(cache, Arc::clone(&store)).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    // No `with_client_binding`: `verified_client` stays `None`.
    let ctx = unbound_context(Arc::clone(&signer), deposit);

    match stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    {
        Ok(_) => anyhow::bail!("unbound fetch of an origin-only blob must be refused"),
        Err(e) => anyhow::ensure!(
            e.to_string().contains("delivery refused"),
            "expected a delivery-refused error, got: {e}"
        ),
    }
    // The anti-griefing guarantee: an unauthorized request must not make the node
    // front upstream/origin work. Prove the gate short-circuited BEFORE any origin
    // egress — not that it read the origin and then refused.
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 0,
        "unbound request must not trigger an origin fetch, got {}",
        cache_metrics.origin_fetches.get()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A serve miss on a hash the node **advertises as origin-held** answers with a
/// signed `StreamResponse{ok: false}` rather than dropping the stream.
///
/// A fail-silent gate (#1130) would suppress this path. A signed
/// `has_blob: true` probe plus a signed `ok: false` stream is not
/// phantom-announcement evidence: the refusal is inert (rate manipulation
/// requires `ok == true`, blacklist violation requires a served claim — ADR
/// 014), so the accountable answer is to sign it. Dropping instead costs the
/// requester a full open-stage timeout.
///
/// The setup is the [`unbound_client_fetch_is_refused_on_origin_only_blob`]
/// control plus the one thing it lacks: `rescan_origins()`, which populates the
/// `origin_held` index so `origin_held_size(hash)` is `Some`. Without that call
/// the branch is unreachable.
#[tokio::test(flavor = "multi_thread")]
async fn origin_held_serve_miss_signs_a_refusal_rather_than_dropping() -> anyhow::Result<()> {
    let payload = vec![0x3Cu8; 32 * 1024];
    let (cache, hash, _cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    // Populate the origin-held index: the node now advertises this hash on
    // probe (`has_blob: true`) even though the store has never held it.
    cache.rescan_origins().await;
    anyhow::ensure!(
        cache.origin_held_size(hash) == Some(payload.len() as u64),
        "precondition: the hash must be indexed as origin-held"
    );
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, _metrics) =
        spawn_pull_through_server(cache, Arc::clone(&store)).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    // No client binding => `pull_authorized` fails, so the reactive pull never
    // runs and the serve path reaches a plain `CacheMiss` on origin-held content.
    let ctx = unbound_context(Arc::clone(&signer), deposit);

    let Err(err) = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    else {
        anyhow::bail!("an unbound fetch of origin-held content must be refused")
    };

    // The assertion that distinguishes this from the deleted behaviour: a typed
    // refusal carrying the operator's signed response, not a timeout on a
    // silently-dropped stream.
    let refused = err
        .downcast_ref::<decdn_client::UpstreamRefused>()
        .ok_or_else(|| anyhow::anyhow!("expected a typed UpstreamRefused, got: {err:#}"))?;
    let evidence = refused.evidence().ok_or_else(|| {
        anyhow::anyhow!("the refusal must carry the operator's signed StreamResponse")
    })?;
    anyhow::ensure!(
        !evidence.body.ok,
        "an origin-held serve miss must sign ok:false, got ok:{}",
        evidence.body.ok
    );
    anyhow::ensure!(
        evidence.body.hash == *hash.as_bytes(),
        "the signed refusal must name the requested hash"
    );
    anyhow::ensure!(
        !evidence.slash_sig.is_empty(),
        "the refusal must be signed — an unsigned one is unattributable"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Like [`spawn_pull_through_server`] but arms ONLY the reactive LOCAL-origin
/// populate (`ClientHandlerDeps.local_populate`) — NOT the node→node buffered/window paths.
/// This is the cache-only-operator wiring (#1116): `[cache.origin]` set,
/// `node_to_node_pull_through_enabled` off.
async fn spawn_local_populate_server(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
) -> anyhow::Result<(
    EndpointAddr,
    Address,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        16,
        |deps| deps.local_populate = Some(Duration::from_secs(20)),
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((
        target,
        server_eth.address(),
        server_ep,
        server_task,
        metrics,
    ))
}

/// A server with BOTH the reactive local populate AND a node→node window origin
/// armed — but the window origin is left UNPROVISIONED (a dead peer path). If the
/// serve path (wrongly) preferred the peer window path over the local origin for
/// a whole-blob request, the pull would hit this dead origin and the fetch would
/// be refused; a successful local serve proves local-first (#1116 shadowing fix).
async fn spawn_local_and_window_server(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
) -> anyhow::Result<(EndpointAddr, Address, Endpoint, tokio::task::JoinHandle<()>)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        16,
        |deps| {
            deps.local_populate = Some(Duration::from_secs(20));
            deps.pull_through_origin = Some(Arc::new(decdn_node::node_origin::NodeOrigin::new()));
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((target, server_eth.address(), server_ep, server_task))
}

/// #1116: a node with node→node pull-through DISABLED — only the reactive
/// LOCAL-origin populate armed — still reactively serves a blob present solely in
/// its own filesystem origin to a bound, pool-owning client. This is the
/// cache-only-operator flow that was a silent `NotFound` before decoupling local
/// populate from `node_to_node_pull_through_enabled`.
#[tokio::test(flavor = "multi_thread")]
async fn local_populate_serves_own_origin_with_node_to_node_off() -> anyhow::Result<()> {
    let payload = vec![0x5Au8; 64 * 1024];
    let (cache, hash, cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, metrics) =
        spawn_local_populate_server(cache, Arc::clone(&store)).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch"
    );
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 1,
        "expected exactly 1 local origin fetch, got {}",
        cache_metrics.origin_fetches.get()
    );
    assert_first_byte_class(&metrics, "miss")?;

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1116 control: the SAME local-populate-only setup WITHOUT a client binding is
/// refused — reactive local populate is gated on the SAME proven pool
/// ownership as the node→node paths (`pull_authorized`), so an S3 origin's egress
/// isn't fronted for an unauthenticated request. No origin fetch is triggered.
#[tokio::test(flavor = "multi_thread")]
async fn unbound_local_populate_is_refused() -> anyhow::Result<()> {
    let payload = vec![0x5Au8; 64 * 1024];
    let (cache, hash, cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, _metrics) =
        spawn_local_populate_server(cache, Arc::clone(&store)).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    // No client binding: reactive local populate must stay gated on proven
    // pool ownership, so the unbound request is refused.
    let ctx = unbound_context(Arc::clone(&signer), deposit);

    match stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    {
        Ok(_) => anyhow::bail!("unbound local-populate fetch must be refused"),
        Err(e) => anyhow::ensure!(
            e.to_string().contains("delivery refused"),
            "expected a delivery-refused error, got: {e}"
        ),
    }
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 0,
        "unbound request must not trigger a local origin fetch, got {}",
        cache_metrics.origin_fetches.get()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1116 (window-shadowing fix): with BOTH the reactive local populate AND a
/// node→node window origin armed, a whole-blob request for a blob the operator
/// holds in its OWN filesystem origin is served from that local origin — the
/// window (peer) path, here deliberately dead/unprovisioned, is never taken.
/// Before the fix a whole-blob miss went straight to the peer window path and
/// never read the local origin.
#[tokio::test(flavor = "multi_thread")]
async fn local_origin_preferred_over_peer_window_path() -> anyhow::Result<()> {
    let payload = vec![0x3Cu8; 64 * 1024];
    let (cache, hash, cache_metrics, _origin_tmp, _cache_tmp) =
        empty_cache_with_fs_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task) =
        spawn_local_and_window_server(cache, Arc::clone(&store)).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);

    let got = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        got.as_ref() == payload.as_slice(),
        "delivered bytes mismatch"
    );
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 1,
        "the local origin must be preferred (served) over the peer window path, got {} fetches",
        cache_metrics.origin_fetches.get()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1116: with node→node OFF and only the local populate armed, a bound fetch for
/// a blob ABSENT from the node's own origin cleanly terminates as a delivery
/// refusal (not a hang or a masked error) after the local origin is consulted
/// exactly once — the miss path (`try_local_populate` returns
/// `FillOutcome::CleanMiss` → falls
/// through to a `CacheMiss`, since node→node is the only further tier and it's
/// off). Guards that the local-first insertion neither shadows a would-be
/// node→node fallthrough nor short-circuits the miss handling.
#[tokio::test(flavor = "multi_thread")]
async fn local_populate_miss_is_clean_cache_miss() -> anyhow::Result<()> {
    let spans = support::capture_spans();
    let payload = vec![0x2Bu8; 64 * 1024];
    let hash = decdn_cache::Hash::new(&payload);
    // A filesystem origin that does NOT contain the blob (empty dir), plus an
    // empty local store — so the reactive local populate is a genuine miss.
    let origin_dir = tempfile::tempdir()?;
    let cache_dir = tempfile::tempdir()?;
    let origin = Arc::new(decdn_cache::FilesystemOrigin::new(origin_dir.path()).await?);
    let cache_metrics = Arc::new(CacheMetrics::default());
    let cache = CacheEngine::open_full(
        cache_dir.path(),
        vec![origin as Arc<dyn decdn_cache::Origin>],
        16,
        PinnedHashes::empty(),
        RetryPolicy::default(),
        CircuitBreakerPolicy::default(),
        Some(Arc::clone(&cache_metrics)),
        Duration::ZERO,
    )
    .await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, metrics) =
        spawn_fault_server(cache, Arc::clone(&store), FaultTiers::LocalOnly).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);

    match stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    {
        Ok(_) => anyhow::bail!("a blob absent from the local origin must be refused"),
        // A GENUINE absence must still sign `NotFound` — the #1129 counterpart of
        // the hard-fault tests below. Pinned to the wire error (not just "refused")
        // so a future change that over-eagerly promotes clean misses to
        // `InternalError` fails here.
        Err(e) => anyhow::ensure!(
            e.to_string().contains("delivery refused") && e.to_string().contains("NotFound"),
            "expected a signed NotFound for a genuine absence, got: {e}"
        ),
    }
    // The local origin WAS consulted on the miss (proving the local-first path
    // ran, not that it was skipped), then the request fell through to a clean
    // refusal because node→node is off — the only further tier.
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 1,
        "local origin should be consulted once on the miss, got {}",
        cache_metrics.origin_fetches.get()
    );
    // The inverse of the hard-fault tests, and the guard that makes the pair
    // airtight: a genuine absence must be metered as a cache miss and must NOT
    // trip the internal-error counter. Over-promoting clean misses would report a
    // healthy-but-empty node as broken and steer clients away from it.
    assert_reject_reason(&metrics, 0, 1)?;
    // Authorized, but node-to-node is off: the local tier ran and missed.
    assert_one_miss_line(&spans, hash, "no_pull_through", "cache_miss")?;

    shutdown([server_task], [&client_ep, &server_ep]).await?;

    // The refusal and the miss chain under it land on the spans: the local
    // tier finds nothing, its origin walk is a clean `not_found` (no error
    // status), and the stream records a signed `cache_miss` refusal.
    let key = hash.to_string();
    let field = |span: &support::CapturedSpan, name: &str| span.fields.get(name).cloned();
    let served = spans.matching("serve_stream", "hash", &key);
    let [serve] = served.as_slice() else {
        anyhow::bail!("expected one serve_stream span for the hash, got {served:?}");
    };
    anyhow::ensure!(
        field(serve, "outcome").as_deref() == Some("refused")
            && field(serve, "reason").as_deref() == Some("cache_miss"),
        "serve_stream: {serve:?}"
    );
    let fills = spans.matching("pull_through", "hash", &key);
    anyhow::ensure!(
        fills
            .iter()
            .any(|s| field(s, "tier").as_deref() == Some("local")
                && field(s, "outcome").as_deref() == Some("clean_miss")
                && s.parent == Some("serve_stream")),
        "pull_through: {fills:?}"
    );
    let walks = spans.matching("origin_pull", "hash", &key);
    anyhow::ensure!(
        walks
            .iter()
            .any(|s| field(s, "outcome").as_deref() == Some("not_found")
                && field(s, "otel.status_code").is_none()
                && s.parent == Some("pull_through")),
        "origin_pull: {walks:?}"
    );
    Ok(())
}

/// #2282: a request that may not make this node spend (here: no client
/// binding) runs no fill tier and refuses on the `no_lane` path. A remote peer
/// reaches that path at will, so its refusal line is throttled: two misses
/// from one unbound peer write one line.
#[tokio::test(flavor = "multi_thread")]
async fn unbound_miss_refuses_on_a_throttled_no_lane_line() -> anyhow::Result<()> {
    let spans = support::capture_spans();
    let payload = vec![0x5Au8; 64 * 1024];
    let hash = decdn_cache::Hash::new(&payload);
    let origin_dir = tempfile::tempdir()?;
    let cache_dir = tempfile::tempdir()?;
    let origin = Arc::new(decdn_cache::FilesystemOrigin::new(origin_dir.path()).await?);
    let cache_metrics = Arc::new(CacheMetrics::default());
    let cache = CacheEngine::open_full(
        cache_dir.path(),
        vec![origin as Arc<dyn decdn_cache::Origin>],
        16,
        PinnedHashes::empty(),
        RetryPolicy::default(),
        CircuitBreakerPolicy::default(),
        Some(Arc::clone(&cache_metrics)),
        Duration::ZERO,
    )
    .await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, metrics) =
        spawn_fault_server(cache, Arc::clone(&store), FaultTiers::LocalOnly).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    // No client binding: the request names no signer this node can hold a
    // lane for.
    let ctx = unbound_context(Arc::clone(&signer), deposit);
    for _ in 0..2 {
        match stream_fetch(
            &client_ep,
            target.clone(),
            &ctx,
            &slash_domain(),
            server_eth_addr,
            *hash.as_bytes(),
            0,
            0x00c0_ffee,
            Duration::from_secs(20),
        )
        .await
        {
            Ok(_) => anyhow::bail!("an unbound miss must be refused"),
            Err(e) => anyhow::ensure!(
                e.to_string().contains("NotFound"),
                "expected a signed NotFound, got: {e}"
            ),
        }
    }
    // No fill tier ran: the local origin was never consulted.
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 0,
        "an unbound request must not reach the local origin, got {}",
        cache_metrics.origin_fetches.get()
    );
    assert_reject_reason(&metrics, 0, 2)?;
    let line = assert_one_miss_line(&spans, hash, "no_lane", "cache_miss")?;
    anyhow::ensure!(
        line.get("suppressed").map(String::as_str) == Some("0"),
        "the first line of a window suppresses nothing: {line:?}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// What the local fs origin holds for a #2315 mid-request-lane test.
#[derive(Clone, Copy, PartialEq, Eq)]
enum OriginHolds {
    /// Nothing: every local tier misses.
    Nothing,
    /// The blob only: the own-origin spine declines (no outboard), the local
    /// populate and the buffered pull-through can fill.
    Blob,
    /// The blob and its `{H}.obao4` outboard: the own-origin spine serves.
    BlobAndOutboard,
}

/// #2315: a sibling stream registers this request's lane after the request
/// resolved it as unknown. The miss tiers keep the request's one answer: no
/// fill tier runs, and the refusal is the `no_lane` `NotFound`. The window leg
/// must not fall through to a false `InternalError` at the size gate, and no
/// leg may spend origin egress on the request. The lane is live for the NEXT
/// request: when the origin holds the blob, a second fetch on the same binding
/// is served.
async fn lane_registered_mid_request_refuses_on_no_lane(
    tiers: FaultTiers,
    holds: OriginHolds,
) -> anyhow::Result<()> {
    let spans = support::capture_spans();
    let payload = vec![0x6Du8; 64 * 1024];
    let hash = decdn_cache::Hash::new(&payload);
    let origin_dir = tempfile::tempdir()?;
    if holds != OriginHolds::Nothing {
        let encoded = decdn_bao_range::encode_outboard(payload.as_slice(), payload.len() as u64)?;
        anyhow::ensure!(
            encoded.hash_hex == hash.to_hex().as_str(),
            "encoder hash mismatch"
        );
        let shard = origin_dir.path().join(encoded.shard());
        std::fs::create_dir_all(&shard)?;
        std::fs::write(shard.join(&encoded.hash_hex), &payload)?;
        if holds == OriginHolds::BlobAndOutboard {
            std::fs::write(shard.join(encoded.obao4_name()), &encoded.outboard)?;
        }
    }
    let cache_dir = tempfile::tempdir()?;
    let origin = Arc::new(decdn_cache::FilesystemOrigin::new(origin_dir.path()).await?);
    let cache_metrics = Arc::new(CacheMetrics::default());
    let cache = CacheEngine::open_full(
        cache_dir.path(),
        vec![origin as Arc<dyn decdn_cache::Origin>],
        16,
        PinnedHashes::empty(),
        RetryPolicy::default(),
        CircuitBreakerPolicy::default(),
        Some(Arc::clone(&cache_metrics)),
        Duration::ZERO,
    )
    .await?;
    // No lane in the store: the bound request resolves its lane as unknown.
    let store: Arc<dyn PoolStateStore> = Arc::new(MemoryPoolStateStore::new());
    let signer = Arc::new(PrivateKeySigner::random());
    let deposit = U256::from(10_000_000u64);
    let (target, server_eth_addr, server_ep, server_task, metrics, handler) =
        spawn_fault_server_with_handler(cache, store, tiers).await?;
    handler.register_lane_after_next_resolution(fresh_lane(signer.address(), deposit));

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);
    let slash = slash_domain();
    let fetch = || {
        stream_fetch(
            &client_ep,
            target.clone(),
            &ctx,
            &slash,
            server_eth_addr,
            *hash.as_bytes(),
            0,
            0x00c0_ffee,
            Duration::from_secs(20),
        )
    };

    match fetch().await {
        Ok(_) => anyhow::bail!("a request whose lane was unknown at resolution must be refused"),
        Err(e) => anyhow::ensure!(
            e.to_string().contains("delivery refused") && e.to_string().contains("NotFound"),
            "expected a signed NotFound, got: {e}"
        ),
    }
    anyhow::ensure!(
        metric_line_present(&metrics.encode()?, "decdn_lanes_open 1"),
        "precondition: the armed lane must be registered mid-request"
    );
    anyhow::ensure!(
        cache_metrics.origin_fetches.get() == 0,
        "no fill tier may run for the request, got {} origin fetches",
        cache_metrics.origin_fetches.get()
    );
    assert_reject_reason(&metrics, 0, 1)?;
    assert_one_miss_line(&spans, hash, "no_lane", "cache_miss")?;

    // The registered lane is this binding's own: the next request resolves it
    // and is served.
    if holds != OriginHolds::Nothing {
        let served = fetch().await?;
        anyhow::ensure!(
            served == payload,
            "the next request must be served the blob"
        );
    }

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #2315, local populate leg: see [`lane_registered_mid_request_refuses_on_no_lane`].
#[tokio::test(flavor = "multi_thread")]
async fn lane_registered_mid_request_spends_no_origin_egress() -> anyhow::Result<()> {
    lane_registered_mid_request_refuses_on_no_lane(FaultTiers::LocalOnly, OriginHolds::Blob).await
}

/// #2315, own-origin spine leg (the origin publishes the outboard): see
/// [`lane_registered_mid_request_refuses_on_no_lane`].
#[tokio::test(flavor = "multi_thread")]
async fn lane_registered_mid_request_skips_the_own_origin_spine() -> anyhow::Result<()> {
    lane_registered_mid_request_refuses_on_no_lane(
        FaultTiers::LocalOnly,
        OriginHolds::BlobAndOutboard,
    )
    .await
}

/// #2315, buffered pull-through leg: see
/// [`lane_registered_mid_request_refuses_on_no_lane`].
#[tokio::test(flavor = "multi_thread")]
async fn lane_registered_mid_request_skips_the_buffered_pull() -> anyhow::Result<()> {
    lane_registered_mid_request_refuses_on_no_lane(FaultTiers::Buffered, OriginHolds::Blob).await
}

/// #2315, window leg: see [`lane_registered_mid_request_refuses_on_no_lane`].
#[tokio::test(flavor = "multi_thread")]
async fn lane_registered_mid_request_is_not_an_internal_error() -> anyhow::Result<()> {
    lane_registered_mid_request_refuses_on_no_lane(FaultTiers::LocalAndWindow, OriginHolds::Nothing)
        .await
}

/// Which reactive fill tiers a fault-test server arms (#1129).
#[derive(Clone, Copy)]
enum FaultTiers {
    /// Cache-only operator: local populate only, node→node OFF.
    LocalOnly,
    /// Local populate + an UNPROVISIONED node→node window origin (a dead peer
    /// path that cleanly misses) — exercises the fault surviving a fall-through.
    LocalAndWindow,
    /// The buffered node→node tier only (`ClientHandlerDeps.pull_through`), no window origin.
    /// This is the `try_pull_through` path — the one whose `HardFault` no other
    /// test reaches.
    Buffered,
}

/// Spawn a serve handler over `cache` with the given fill tiers armed, returning
/// the server `Metrics` so a test can assert the per-reason reject counter.
///
/// The counter is not a nicety here: the wire error is deliberately lossy (seven
/// distinct reject reasons collapse to the single `NotFound` code), so the
/// per-reason metric is the ONLY server-side place the true cause is observable —
/// which is exactly the signal an operator needs while their origin is down.
async fn spawn_fault_server(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    tiers: FaultTiers,
) -> anyhow::Result<(
    EndpointAddr,
    Address,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
)> {
    let (target, server_eth_addr, server_ep, server_task, metrics, _handler) =
        spawn_fault_server_with_handler(cache, store, tiers).await?;
    Ok((target, server_eth_addr, server_ep, server_task, metrics))
}

/// [`spawn_fault_server`], also returning the serving `ClientHandler` so a test
/// can arm its test-support seams.
async fn spawn_fault_server_with_handler(
    cache: CacheEngine,
    store: Arc<dyn PoolStateStore>,
    tiers: FaultTiers,
) -> anyhow::Result<(
    EndpointAddr,
    Address,
    Endpoint,
    tokio::task::JoinHandle<()>,
    Arc<Metrics>,
    Arc<ClientHandler>,
)> {
    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store,
        RATE_PER_MB,
        16,
        |deps| match tiers {
            FaultTiers::LocalOnly => deps.local_populate = Some(Duration::from_secs(20)),
            FaultTiers::LocalAndWindow => {
                deps.local_populate = Some(Duration::from_secs(20));
                deps.pull_through_origin =
                    Some(Arc::new(decdn_node::node_origin::NodeOrigin::new()));
            }
            FaultTiers::Buffered => deps.pull_through = Some(Duration::from_secs(20)),
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), Arc::clone(&handler));
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);
    Ok((
        target,
        server_eth.address(),
        server_ep,
        server_task,
        metrics,
        handler,
    ))
}

/// Assert the serve-reject counters recorded exactly one refusal, of `reason`.
/// Pins BOTH directions — the reason fired and its sibling did not — so a change
/// that over-promotes clean misses to `InternalError` (which would decline
/// every miss on a healthy node) fails just as loudly as one that under-reports a fault.
fn assert_reject_reason(
    metrics: &Arc<Metrics>,
    internal_error: u64,
    cache_miss: u64,
) -> anyhow::Result<()> {
    let encoded = metrics.encode()?;
    for (name, want) in [
        (
            "decdn_serve_stream_rejected_internal_error_total",
            internal_error,
        ),
        ("decdn_serve_stream_rejected_cache_miss_total", cache_miss),
    ] {
        let line = format!("{name} {want}");
        anyhow::ensure!(
            metric_line_present(&encoded, &line),
            "expected metric line `{line}`; counters were:\n{}",
            encoded
                .lines()
                .filter(|l| l.starts_with("decdn_serve_stream_rejected"))
                .collect::<Vec<_>>()
                .join("\n")
        );
    }
    Ok(())
}

/// Assert the serve handler logged exactly one serve-miss refusal line for
/// `hash`, on `path` with `reason` (#2282), and return its fields. The wire
/// error and the counters do not name the path, so the line is the only place
/// a mis-routed exit shows.
fn assert_one_miss_line(
    spans: &support::SpanCapture,
    hash: decdn_cache::Hash,
    path: &str,
    reason: &str,
) -> anyhow::Result<std::collections::HashMap<String, String>> {
    let lines = spans.events(
        "serve-miss: refusing the request",
        "hash",
        &hash.to_string(),
    );
    let [line] = lines.as_slice() else {
        anyhow::bail!("expected one serve-miss refusal line for the hash, got {lines:?}");
    };
    anyhow::ensure!(
        line.get("path").map(String::as_str) == Some(path)
            && line.get("reason").map(String::as_str) == Some(reason),
        "expected path={path} reason={reason}: {line:?}"
    );
    Ok(line.clone())
}

/// An origin that always fails with a TRANSIENT backend error — the shape of an
/// S3 5xx that survives retry exhaustion, an open circuit breaker, or an fs I/O
/// fault. The engine surfaces this as `CacheError::OriginError`, which is NOT an
/// absence: the blob may well exist and be servable once the origin recovers
/// (#1129).
///
/// Distinct from [`CountingOrigin`] in the way that matters: that one is
/// `OriginKind::Peer`, which `populate_local` deliberately SKIPS, so it can never
/// exercise the local tier. This one is `OriginKind::Http` — a local-tier origin
/// the reactive populate does consult.
#[derive(Debug)]
struct FailingOrigin {
    hits: Arc<std::sync::atomic::AtomicUsize>,
}

impl decdn_cache::Origin for FailingOrigin {
    fn fetch(
        &self,
        _hash: decdn_cache::Hash,
        _max_bytes: u64,
    ) -> std::pin::Pin<
        Box<
            dyn std::future::Future<
                    Output = Result<decdn_cache::origin::OriginFetch, decdn_cache::OriginPullError>,
                > + Send
                + '_,
        >,
    > {
        self.hits.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
        Box::pin(async {
            Err(decdn_cache::OriginPullError::Transient(anyhow::anyhow!(
                "synthetic origin outage (HTTP 503)"
            )))
        })
    }

    fn kind(&self) -> decdn_cache::OriginKind {
        decdn_cache::OriginKind::Http
    }
}

/// A cache whose sole configured origin is a [`FailingOrigin`] — the operator's
/// own backend is down. The local store starts empty, so a serve request is a
/// miss whose reactive local populate hits a hard fault.
async fn empty_cache_with_failing_origin(
    payload: &[u8],
) -> anyhow::Result<(
    CacheEngine,
    decdn_cache::Hash,
    Arc<std::sync::atomic::AtomicUsize>,
    tempfile::TempDir,
)> {
    let hash = decdn_cache::Hash::new(payload);
    let cache_dir = tempfile::tempdir()?;
    let hits = Arc::new(std::sync::atomic::AtomicUsize::new(0));
    let origin = Arc::new(FailingOrigin {
        hits: Arc::clone(&hits),
    });
    let cache = CacheEngine::open_full(
        cache_dir.path(),
        vec![origin as Arc<dyn decdn_cache::Origin>],
        16,
        PinnedHashes::empty(),
        RetryPolicy::default(),
        CircuitBreakerPolicy::default(),
        Some(Arc::new(CacheMetrics::default())),
        Duration::ZERO,
    )
    .await?;
    anyhow::ensure!(!cache.has(hash).await?, "cache store must start empty");
    Ok((cache, hash, hits, cache_dir))
}

/// #1129: a cache-only operator (node→node OFF) whose OWN origin hard-faults must
/// refuse `Declined` (reason `InternalError`), NOT a signed `NotFound`.
///
/// The refusal is EIP-712 signed, so `NotFound` is an authoritative, attributable
/// claim that the blob does not exist. Signing it during a transient S3 outage
/// tells paying clients to stop asking for a blob the node will serve fine once
/// the origin recovers. The blob's absence from the store is indistinguishable
/// from a clean miss without the engine's error classification — which is exactly
/// what a bare-`bool` fill helper would discard.
#[tokio::test(flavor = "multi_thread")]
async fn local_origin_hard_fault_is_internal_error_not_signed_not_found() -> anyhow::Result<()> {
    let payload = vec![0x7Eu8; 64 * 1024];
    let (cache, hash, origin_hits, _cache_tmp) = empty_cache_with_failing_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, metrics) =
        spawn_fault_server(cache, Arc::clone(&store), FaultTiers::LocalOnly).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);

    match stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    {
        Ok(_) => anyhow::bail!("a hard origin fault must not deliver"),
        Err(e) => {
            let msg = e.to_string();
            anyhow::ensure!(
                msg.contains("Declined"),
                "a hard origin fault must surface as Declined (InternalError), got: {e}"
            );
            anyhow::ensure!(
                !msg.contains("NotFound"),
                "a hard origin fault must NOT sign an authoritative NotFound, got: {e}"
            );
        }
    }
    anyhow::ensure!(
        origin_hits.load(std::sync::atomic::Ordering::SeqCst) > 0,
        "the failing origin should have been consulted (proving the fault came from \
         the reactive fill, not a short-circuit before it)"
    );
    // The operator-facing half: the reject is metered as an internal error, NOT as a
    // cache miss. Without this the wire assertion above still passes while the
    // dashboard reports an origin outage as an empty cache.
    assert_reject_reason(&metrics, 1, 0)?;

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1129, the arm most likely to regress: with node→node ON, a hard fault on the
/// LOCAL tier must survive the fall-through to the node→node window tier.
///
/// Falling through after a local fault is correct — a peer may legitimately still
/// serve. But the window origin here is unprovisioned (a dead peer path), so it
/// cleanly misses; the terminal refusal must still be `InternalError`, because a
/// later clean miss must not launder the earlier fault back into a signed
/// `NotFound`. This is what `fault_seen` threading exists to prevent.
#[tokio::test(flavor = "multi_thread")]
async fn local_hard_fault_survives_fallthrough_to_the_window_tier() -> anyhow::Result<()> {
    let spans = support::capture_spans();
    let payload = vec![0x3Du8; 64 * 1024];
    let (cache, hash, origin_hits, _cache_tmp) = empty_cache_with_failing_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, metrics) =
        spawn_fault_server(cache, Arc::clone(&store), FaultTiers::LocalAndWindow).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);

    match stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    {
        Ok(_) => anyhow::bail!("a hard origin fault must not deliver"),
        Err(e) => {
            let msg = e.to_string();
            anyhow::ensure!(
                msg.contains("Declined"),
                "a local hard fault must still surface as InternalError after the \
                 node→node tier cleanly misses, got: {e}"
            );
            anyhow::ensure!(
                !msg.contains("NotFound"),
                "the window tier's clean miss must not overwrite the local fault with \
                 a signed NotFound, got: {e}"
            );
        }
    }
    anyhow::ensure!(
        origin_hits.load(std::sync::atomic::Ordering::SeqCst) > 0,
        "the failing local origin should have been consulted before the window tier"
    );
    assert_reject_reason(&metrics, 1, 0)?;
    // The unprovisioned window origin has no provider to open: a clean pull-leg
    // miss, refused as `internal_error` because the local fault is latched.
    let line = assert_one_miss_line(&spans, hash, "pull_leg_miss", "internal_error")?;
    anyhow::ensure!(
        line.get("cause").map(String::as_str) == Some("clean_miss"),
        "pull-leg miss cause: {line:?}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// #1129 on the BUFFERED node→node tier (`try_pull_through`). Without this test,
/// reverting that helper's `HardFault` arm to a clean miss breaks nothing: every
/// other fault test drives `try_local_populate`.
///
/// This is the tier a resumed request or an unset window provider lands on,
/// and its outcome also has to compose with the latch at the call site
/// (`miss_reason(fault_seen || buffered.is_fault())`) — the `buffered.is_fault()`
/// side of that `||` is exercised nowhere else.
#[tokio::test(flavor = "multi_thread")]
async fn buffered_pull_through_hard_fault_is_internal_error() -> anyhow::Result<()> {
    let spans = support::capture_spans();
    let payload = vec![0x9Cu8; 64 * 1024];
    let (cache, hash, origin_hits, _cache_tmp) = empty_cache_with_failing_origin(&payload).await?;
    let (store, signer, deposit) = seeded_store()?;
    let (target, server_eth_addr, server_ep, server_task, metrics) =
        spawn_fault_server(cache, Arc::clone(&store), FaultTiers::Buffered).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let own_node_id = B256::from(*client_ep.id().as_bytes());
    let binding = sign_client_binding(&signer, own_node_id, &binding_domain())?;
    let ctx = pool_context(&client_ep, Arc::clone(&signer), deposit).with_client_binding(binding);

    match stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth_addr,
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    {
        Ok(_) => anyhow::bail!("a hard origin fault must not deliver"),
        Err(e) => {
            let msg = e.to_string();
            anyhow::ensure!(
                msg.contains("Declined"),
                "a buffered-tier hard fault must surface as InternalError, got: {e}"
            );
            anyhow::ensure!(
                !msg.contains("NotFound"),
                "a buffered-tier hard fault must not report the node as merely empty, got: {e}"
            );
        }
    }
    anyhow::ensure!(
        origin_hits.load(std::sync::atomic::Ordering::SeqCst) > 0,
        "the failing origin should have been consulted by the buffered tier"
    );
    assert_reject_reason(&metrics, 1, 0)?;
    assert_one_miss_line(&spans, hash, "buffered_miss", "internal_error")?;

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// End-to-end coverage for the load-shed gate's two `Err` branches in
/// `serve_stream` (dispatch.rs): the cache-miss admission call refuses with
/// `ServeRejectReason::LoadShedMiss`, and the cache-hit admission call refuses
/// with `ServeRejectReason::LoadShedHit`. Both collapse to the same signed wire
/// `NotFound` a paying client sees. The policy's own admit/shed arithmetic
/// already has unit coverage in `load_shed::resource_pressure`; what these two
/// tests add is proof the handler actually wires a shed `Err` into the exact
/// on-wire refusal, through a real loopback connection and a real bound
/// request.
///
/// Both tests pre-set the controller's counters before the client ever
/// connects, so the shed decision is already fixed at admission time — no
/// timing or concurrency race is involved.
///
/// A hash the node genuinely lacks: the request lands on the cache-miss
/// admission call. The node's concurrency ceiling is pre-occupied by a held
/// slot, so it is already at its one-slot high-water mark.
#[tokio::test(flavor = "multi_thread")]
async fn cache_miss_refused_under_concurrency_pressure() -> anyhow::Result<()> {
    let (cache, _cache_tmp) = empty_cache().await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&fresh_lane(signer.address(), U256::from(10_000_000u64)))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    // Concurrency high-water mark of 1: pre-occupying one slot before the
    // client connects puts the node at capacity for every request that follows.
    let shed = decdn_node::load_shed::LoadShedController::from_config(
        &decdn_common::config::ResolvedLoadShed {
            policy: decdn_common::config::LoadShedPolicyKind::ResourcePressure,
            egress_budget_mbps: 0,
            max_concurrent_serves_high: 1,
            max_concurrent_serves_low: 0,
            per_client_serve_cap: 0,
        },
    );
    let held = shed
        .try_admit(
            decdn_node::load_shed::RequestClass::CacheHit,
            B256::repeat_byte(0xAA),
        )
        .map_err(|reason| anyhow::anyhow!("pre-occupy the sole concurrency slot: {reason:?}"))?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
        |deps| {
            deps.shed = Arc::clone(&shed);
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let ext = binding_ext(&signer, client_node_id)?;

    // A hash the empty cache never has: the cache-miss admission branch.
    let miss_hash = Hash::new(b"load-shed test: never cached");
    let (refusal, refusal_ext) =
        open_expecting_refusal(&conn, *miss_hash.as_bytes(), Some(&ext)).await?;
    anyhow::ensure!(
        !refusal.body.ok,
        "a cache-miss request must be shed while the node is at its concurrency ceiling"
    );
    anyhow::ensure!(
        matches!(
            refusal_ext.error,
            Some(decdn_protocol::client::StreamError::NotFound)
        ),
        "expected the collapsed NotFound wire code, got {:?}",
        refusal_ext.error
    );

    // Release the held slot only after the refusal is observed, so the shed
    // decision above is provably driven by the pre-occupied slot.
    drop(held);
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A hash the node already has cached: the request lands on the cache-hit
/// admission call. Concurrency never trips (the high/low water marks are far
/// above anything this test does); only the egress ceiling is saturated, which
/// `ResourcePressure` sheds regardless of the pressure latch (it also sheds
/// hits, unlike the concurrency gate above).
#[tokio::test(flavor = "multi_thread")]
async fn cache_hit_refused_under_egress_saturation() -> anyhow::Result<()> {
    let payload = b"load-shed test: a blob the node already has cached".to_vec();
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&fresh_lane(signer.address(), U256::from(10_000_000u64)))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    let shed = decdn_node::load_shed::LoadShedController::from_config(
        &decdn_common::config::ResolvedLoadShed {
            policy: decdn_common::config::LoadShedPolicyKind::ResourcePressure,
            egress_budget_mbps: 1, // 1 Mbps = 125_000 B/s ceiling
            max_concurrent_serves_high: 10_000,
            max_concurrent_serves_low: 9_000,
            per_client_serve_cap: 0,
        },
    );
    // Pre-feed the egress meter over budget before the client ever connects,
    // so the instant rate the handler samples at admission time is already
    // fixed above the ceiling.
    shed.record_egress(1_000_000);
    let sampled = shed.sample_egress(1);
    anyhow::ensure!(
        sampled >= 125_000,
        "instant egress rate must be at/above the 1 Mbps ceiling, got {sampled}"
    );

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    let handler = build_handler_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
        |deps| {
            deps.shed = Arc::clone(&shed);
        },
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let client_sk = fresh_key();
    let client_node_id = B256::from(*client_sk.public().as_bytes());
    let (client_ep, _) = local_endpoint(client_sk, vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let ext = binding_ext(&signer, client_node_id)?;

    let (refusal, refusal_ext) =
        open_expecting_refusal(&conn, *hash.as_bytes(), Some(&ext)).await?;
    anyhow::ensure!(
        !refusal.body.ok,
        "a cache-hit request must be shed while measured egress is at the configured ceiling"
    );
    anyhow::ensure!(
        matches!(
            refusal_ext.error,
            Some(decdn_protocol::client::StreamError::NotFound)
        ),
        "expected the collapsed NotFound wire code, got {:?}",
        refusal_ext.error
    );

    // The availability gate counts ahead of the shed gate, so a serve the shed
    // refuses still records the hit it refused. This is the only assertion in
    // the suite that pins that ordering: every other test runs a permissive
    // limiter, so moving the bump inside the `Ok(slot)` arm would pass all of
    // them while making the fleet hit-rate panel collapse under exactly the
    // pressure it exists to survive.
    let encoded = metrics.encode()?;
    anyhow::ensure!(
        metric_line_present(&encoded, "decdn_serve_cache_hit_total 1"),
        "a shed-refused cache hit must still count as a hit:\n{encoded}"
    );
    anyhow::ensure!(
        metric_line_present(
            &encoded,
            "decdn_serve_stream_rejected_load_shed_hit_total 1"
        ),
        "the shed refusal keeps its own reason counter:\n{encoded}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

// ---------------------------------------------------------------------------
// Hostile-client and hostile-server paths (#1562)
//
// The payment-fault tests reuse [`StalledDelivery`] / the raw pipelined stream
// helpers to reimplement the payer half by hand, so a test chooses exactly which
// malformed proof it sends and when. The client-side detection tests instead run
// the real [`stream_fetch`] requester against [`serve_lying_stream`], a raw
// server that signs a valid `StreamResponse` and then misbehaves on the byte
// stream. Both extend the honest scaffolding above rather than duplicating it.
// ---------------------------------------------------------------------------

/// Sign a cumulative voucher carrying an explicit `(bytes_delivered, amount)` and
/// write it to `send`. Unlike [`pay_cumulative`] (which prices `amount` at the
/// quoted rate) this hands the caller both fields, so a test can inject a voucher
/// that regresses or diverges from the lane watermark. Signed correctly by the
/// lane's pinned key, so the node's signature recovery passes and the reject is
/// decided by the watermark checks.
async fn send_signed_voucher(
    send: &mut SendStream,
    signer: &PrivateKeySigner,
    bytes_delivered: u64,
    amount: U256,
) -> anyhow::Result<()> {
    let voucher = Voucher {
        pool_id: pool_id(),
        signer: signer.address(),
        provider: operator_addr(),
        amount,
        bytes_delivered: U256::from(bytes_delivered),
        chain_root: B256::ZERO,
        chunk_price: U256::ZERO,
    }
    .sign(signer, &payment_domain())
    .map_err(|e| anyhow::anyhow!("sign voucher: {e}"))?;
    write_client_msg(
        send,
        &ClientMessage::Voucher(signed_to_wire_voucher(&voucher)?),
    )
    .await
}

/// Write a voucher whose signature bytes do not recover to any point (`r == s ==
/// 0`, the canonical unrecoverable case) so the node rejects it `BadSignature`
/// (`VoucherError::InvalidSignature`).
///
/// It is derived from a real, correctly-priced voucher and only its signature is
/// zeroed, so the length still clears the wire `validate()` gate — the reject is
/// the recovery failing, not a malformed frame. A hostile payer is not bound by
/// our constructors, so the forgery is modelled on the wire.
async fn send_unrecoverable_voucher(
    send: &mut SendStream,
    signer: &PrivateKeySigner,
    bytes_delivered: u64,
) -> anyhow::Result<()> {
    let amount = min_payment(bytes_delivered, RATE_PER_MB);
    let voucher = Voucher {
        pool_id: pool_id(),
        signer: signer.address(),
        provider: operator_addr(),
        amount,
        bytes_delivered: U256::from(bytes_delivered),
        chain_root: B256::ZERO,
        chunk_price: U256::ZERO,
    }
    .sign(signer, &payment_domain())
    .map_err(|e| anyhow::anyhow!("sign voucher: {e}"))?;
    let mut wire = signed_to_wire_voucher(&voucher)?;
    // Keep the length (so `Voucher::validate` passes) but blank the bytes: `r ==
    // s == 0` parses structurally yet recovers to nothing → `InvalidSignature`.
    wire.signature = vec![0u8; wire.signature.len()];
    write_client_msg(send, &ClientMessage::Voucher(wire)).await
}

/// Read past any in-flight `ChunkData` to the node's mid-stream `VoucherRejected`,
/// returning its reason and whether a wallet-less-resume [`WatermarkBundle`] rode
/// along. The bundle-carrying twin of [`expect_reject`], which asserts the bundle
/// is absent; a watermark-regression reject on a lane with an accepted voucher
/// carries one (#1481 §5), so this hands the flag back for the caller to assert.
async fn read_voucher_reject(recv: &mut RecvStream) -> anyhow::Result<(VoucherRejectReason, bool)> {
    loop {
        let msg = tokio::time::timeout(Duration::from_secs(10), read_client_msg(recv))
            .await
            .map_err(|_| anyhow::anyhow!("node never answered with a rejection"))??;
        match msg {
            ClientMessage::ChunkData(_) => {}
            ClientMessage::StreamError(StreamError::VoucherRejected { reason, bundle }) => {
                return Ok((reason, bundle.is_some()));
            }
            other => anyhow::bail!("expected a VoucherRejected, got {other:?}"),
        }
    }
}

/// Assert `recv` observes a QUIC reset (or connection close) carrying `code`,
/// with no readable frame first. Mirrors the probe suite's reset assertion: the
/// stream-cap shed resets with [`decdn_protocol::APP_ERR_RATE_LIMITED`] and signs
/// no `StreamResponse`, so a returned frame is itself the failure.
async fn assert_stream_reset(recv: &mut RecvStream, code: u32) -> anyhow::Result<()> {
    let expected = VarInt::from_u32(code);
    match recv.read_to_end(4096).await {
        Err(ReadToEndError::Read(ReadError::Reset(got))) if got == expected => Ok(()),
        Err(ReadToEndError::Read(ReadError::ConnectionLost(
            ConnectionError::ApplicationClosed(ApplicationClose { error_code, .. }),
        ))) if error_code == expected => Ok(()),
        Ok(bytes) => anyhow::bail!(
            "expected a reset carrying {code:#x}, but the server sent {} bytes (it signed a \
             response instead of shedding)",
            bytes.len()
        ),
        other => anyhow::bail!("expected a reset carrying {code:#x}, got {other:?}"),
    }
}

/// An underpaying closing voucher (correct cumulative bytes, an amount far below
/// the quoted-rate minimum) stops delivery with a clean `Underpaid` rejection
/// (ADR 003 §Voucher withholding). The lane has accepted no voucher yet, so there
/// is no watermark to hand back and the rejection carries no bundle. The money
/// half: the lane watermark never advances, so the underpaid bytes are never
/// credited.
#[tokio::test(flavor = "multi_thread")]
async fn underpaying_closing_voucher_fails_the_stream_and_credits_nothing() -> anyhow::Result<()> {
    // Under one credit-window floor (1 chunk) so the delivery has exactly one
    // (closing) voucher, but large enough that the quoted-rate minimum is well
    // above 1 — so `amount = 1` is an unambiguous underpayment, not a rounding tie.
    let payload = vec![0x7Eu8; 768 * 1024];
    let fx = idle_fixture(&payload, Duration::from_secs(30)).await?;
    let blob = fx.blob(0)?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;
    let mut stalled = stall_delivery_at_closing_voucher(
        &conn,
        *blob.hash.as_bytes(),
        blob.wire_bytes,
        Some(&ext),
    )
    .await?;

    // The full byte count, but one base unit of payment: `min_payment` for the
    // whole delivery is far above 1, so this underpays the delivered span.
    let owed = min_payment(blob.wire_bytes, RATE_PER_MB);
    anyhow::ensure!(
        owed > U256::from(1u64),
        "fixture must owe more than one base unit for the underpay to be unambiguous"
    );
    let reply = stalled
        .send_cumulative_voucher(&fx.client_signer, blob.wire_bytes, U256::from(1u64))
        .await?;
    anyhow::ensure!(
        matches!(
            reply,
            ClientMessage::StreamError(StreamError::VoucherRejected {
                reason: VoucherRejectReason::Underpaid,
                bundle: None,
            })
        ),
        "an underpaying voucher on a fresh lane must draw a bundle-less Underpaid, got {reply:?}"
    );

    // The withholding is not merely refused — nothing is credited. The lane
    // watermark stays at zero, so the underpaid bytes cannot be settled later.
    let persisted = fx.store.load_all()?;
    if let Some(lane) = persisted.first() {
        anyhow::ensure!(
            lane.last_bytes_delivered() == U256::ZERO,
            "an underpaid stream must not advance the lane watermark, got {}",
            lane.last_bytes_delivered()
        );
        anyhow::ensure!(
            lane.last_amount() == U256::ZERO,
            "an underpaid stream must credit no amount, got {}",
            lane.last_amount()
        );
    }

    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// Drive a raw pipelined stream to the point where one interval has been paid and
/// accepted and the next is on the wire awaiting its voucher — the shared setup
/// for the two "hostile proof after an accepted voucher" tests. Returns the live
/// stream halves plus the client endpoint / server task to tear down.
struct MidStreamAfterAccept {
    send: SendStream,
    recv: RecvStream,
    signer: Arc<PrivateKeySigner>,
    store: Arc<dyn PoolStateStore>,
    metrics: Arc<Metrics>,
    conn: Connection,
    client_ep: Endpoint,
    server_ep: Endpoint,
    server_task: tokio::task::JoinHandle<()>,
}

async fn drive_to_second_interval_awaiting_voucher() -> anyhow::Result<MidStreamAfterAccept> {
    const CREDIT_MAX: u64 = 64 * 1024 * 1024;
    // 16 MiB: many intervals, so a reject after interval 2 lands with plenty of
    // blob still undelivered — genuinely mid-stream, not the closing voucher.
    let payload = vec![0x9Cu8; 16 * 1024 * 1024];
    let (cache, hash, cache_tmp) = cache_with_blob(&payload).await?;
    std::mem::forget(cache_tmp); // keep the cache dir for the connection's life
    let (store, signer, _deposit) = seeded_store()?;

    // Divisor 2 keeps the window pinned at the floor after the first
    // interval is paid (`paid / 2 < floor`), so the server parks after each
    // interval — a deterministic voucher rendezvous.
    let (target, _server_eth, server_ep, server_task, metrics) =
        spawn_pipelined_server_with_metrics(cache, Arc::clone(&store), CREDIT_MAX, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (mut send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;

    // Interval 1 and the verify lag: delivered on the floor window, then
    // interval 1 is paid + accepted. The server only sends past the floor after
    // crediting this voucher, so reading interval 2 below is itself the proof
    // that interval 1 was accepted.
    read_exact_chunks(&mut recv, HARNESS_FLOOR_BYTES).await?;
    pay_cumulative(&mut send, &signer, HARNESS_INTERVAL_BYTES).await?;

    // The rest of interval 2 and the lag past it arrive; the server then parks
    // awaiting interval 2's voucher, which is where the hostile proof is
    // injected.
    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;

    Ok(MidStreamAfterAccept {
        send,
        recv,
        signer,
        store,
        metrics,
        conn,
        client_ep,
        server_ep,
        server_task,
    })
}

/// A `BadSignature` proof arriving *after* an accepted voucher is rejected in
/// band and the accepted watermark survives: signature recovery is the first
/// watermark-independent gate, so the reject is decided before any lane state is
/// touched, and it carries no wallet-less-resume bundle (the fix is a valid
/// signature, not a watermark resync).
#[tokio::test(flavor = "multi_thread")]
async fn bad_signature_after_an_accepted_voucher_is_rejected() -> anyhow::Result<()> {
    let mut fx = drive_to_second_interval_awaiting_voucher().await?;

    // A voucher for interval 2's cumulative, correctly priced but with an
    // unrecoverable signature.
    send_unrecoverable_voucher(&mut fx.send, &fx.signer, 2 * HARNESS_INTERVAL_BYTES).await?;
    let (reason, has_bundle) = read_voucher_reject(&mut fx.recv).await?;
    anyhow::ensure!(
        reason == VoucherRejectReason::BadSignature,
        "expected BadSignature, got {reason:?}"
    );
    anyhow::ensure!(
        !has_bundle,
        "a BadSignature reject carries no watermark bundle: the fix is a valid signature, not a resync"
    );

    // The accepted interval-1 voucher survives the reject: the watermark holds at
    // one interval, neither regressed nor advanced by the forged proof.
    let persisted = fx.store.load_all()?;
    let lane = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane after an accepted voucher"))?;
    anyhow::ensure!(
        lane.last_bytes_delivered() == U256::from(HARNESS_INTERVAL_BYTES),
        "the accepted watermark must survive the reject, got {}",
        lane.last_bytes_delivered()
    );

    // The stop counts once, as a rejected voucher.
    support::assert_inbound_failures_attributed(&fx.metrics, 1).await?;
    anyhow::ensure!(
        counter(&fx.metrics, "decdn_serve_stream_voucher_rejected_total")? == 1,
        "a rejected voucher must be counted"
    );

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// A voucher that raises the amount but adds no bytes fails the rate check
/// (`ZeroBytes`): a client payment fault, which ends the stream and counts once
/// as a rejected voucher even though a voucher already paid (#2073).
#[tokio::test(flavor = "multi_thread")]
async fn a_zero_byte_voucher_after_paying_counts_as_rejected() -> anyhow::Result<()> {
    let spans = support::capture_spans();
    let mut fx = drive_to_second_interval_awaiting_voucher().await?;

    // Interval 1 is paid. Re-sign its byte count at a higher amount.
    let amount = min_payment(HARNESS_INTERVAL_BYTES, RATE_PER_MB) + U256::from(1u64);
    send_signed_voucher(&mut fx.send, &fx.signer, HARNESS_INTERVAL_BYTES, amount).await?;

    // A rate-check bail drops the stream with no in-band reject frame, which is
    // what tells it apart from a `VoucherRejected` stop.
    match tokio::time::timeout(Duration::from_secs(10), read_client_msg(&mut fx.recv)).await {
        Err(_elapsed) => anyhow::bail!("the node kept the stream open after a zero-byte voucher"),
        Ok(Ok(other)) => anyhow::bail!("expected the stream to drop, got {other:?}"),
        Ok(Err(_)) => {}
    }
    support::assert_inbound_failures_attributed(&fx.metrics, 1).await?;
    anyhow::ensure!(
        counter(&fx.metrics, "decdn_serve_stream_voucher_rejected_total")? == 1,
        "a rate-check bail is a rejected voucher"
    );
    anyhow::ensure!(
        counter(&fx.metrics, "decdn_serve_stream_client_abandoned_total")? == 0,
        "a rate-check bail after payment is not an abandon"
    );
    // No frame names the cause, so the INFO line is the only record of it.
    assert_one_reject_line(&spans, &fx.signer, "RateCheck", false)?;

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// A client that leaves after a voucher credited bytes counts as an abandon,
/// not a decline and not a node fault (#2073).
#[tokio::test(flavor = "multi_thread")]
async fn a_client_that_leaves_after_paying_counts_as_abandoned() -> anyhow::Result<()> {
    let fx = drive_to_second_interval_awaiting_voucher().await?;

    // Interval 1 is paid; interval 2 is on the wire. The client walks away.
    fx.conn.close(0u32.into(), b"client-abandoned");

    support::assert_inbound_failures_attributed(&fx.metrics, 1).await?;
    anyhow::ensure!(
        counter(&fx.metrics, "decdn_serve_stream_client_abandoned_total")? == 1,
        "a client that leaves after paying must count as abandoned"
    );
    anyhow::ensure!(
        counter(&fx.metrics, "decdn_serve_stream_client_declined_total")? == 0,
        "a client that paid did not decline"
    );

    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// A requester that reads the signed `StreamResponse` and the opening credit,
/// then leaves without paying, counts as a decline (#2073). This is the shape of
/// the header handshake a downstream miss pull opens and does not adopt.
#[tokio::test(flavor = "multi_thread")]
async fn a_requester_that_leaves_before_paying_counts_as_declined() -> anyhow::Result<()> {
    let payload = vec![0x3Du8; 4 * 1024 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, signer, _deposit) = seeded_store()?;
    let (target, _server_eth, server_ep, server_task, metrics) =
        spawn_pipelined_server_with_metrics(cache, store, 64 * 1024 * 1024, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;
    let (_send, mut recv) = open_paid_stream(&conn, *hash.as_bytes(), Some(&ext)).await?;
    read_exact_chunks(&mut recv, HARNESS_INTERVAL_BYTES).await?;

    // The quote and the free opening interval are in hand; the requester leaves.
    conn.close(0u32.into(), b"upstream-pull-dropped");

    support::assert_inbound_failures_attributed(&metrics, 1).await?;
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_client_declined_total")? == 1,
        "a requester that leaves before paying must count as declined"
    );
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_node_fault_total")? == 0,
        "a requester that leaves is not a node fault"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A first frame that does not decode as a request resets the stream, and the
/// reset counts once as an unreadable request (#2073).
#[tokio::test(flavor = "multi_thread")]
async fn an_unreadable_request_is_reset_and_counted() -> anyhow::Result<()> {
    let payload = vec![0x3Eu8; 64 * 1024];
    let (cache, _hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, _signer, _deposit) = seeded_store()?;
    let (target, _server_eth, server_ep, server_task, metrics) =
        spawn_pipelined_server_with_metrics(cache, store, 64 * 1024 * 1024, 2).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let (mut send, mut recv) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi: {e}"))?;
    write_frame(&mut send, &[0xFF; 16])
        .await
        .map_err(|e| anyhow::anyhow!("write garbage frame: {e}"))?;
    anyhow::ensure!(
        read_frame(&mut recv).await.is_err(),
        "the node must not answer an undecodable request"
    );

    support::assert_inbound_failures_attributed(&metrics, 1).await?;
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_request_unreadable_total")? == 1,
        "an undecodable request must be counted"
    );
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_node_fault_total")? == 0,
        "an undecodable request is the peer's fault"
    );

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A watermark-regressing proof after an accepted voucher — same signed amount as
/// the accepted watermark but MORE bytes claimed, the single-signer divergence of
/// #1699 rule 4 — is rejected `BytesRegression`. It carries no wallet-less-resume
/// bundle: a divergent voucher from the pinned signer is that signer
/// misbehaving, not a stale local watermark a resync could repair, so the node
/// hands back nothing to re-sign from. The accepted watermark is unmoved.
#[tokio::test(flavor = "multi_thread")]
async fn regressing_voucher_after_an_accepted_voucher_is_rejected() -> anyhow::Result<()> {
    let mut fx = drive_to_second_interval_awaiting_voucher().await?;

    // Same money as the accepted interval-1 voucher, but claiming twice the bytes:
    // same amount + more bytes is a divergent fault, not a benign supersede.
    let accepted_amount = min_payment(HARNESS_INTERVAL_BYTES, RATE_PER_MB);
    send_signed_voucher(
        &mut fx.send,
        &fx.signer,
        2 * HARNESS_INTERVAL_BYTES,
        accepted_amount,
    )
    .await?;
    let (reason, has_bundle) = read_voucher_reject(&mut fx.recv).await?;
    anyhow::ensure!(
        reason == VoucherRejectReason::BytesRegression,
        "expected BytesRegression, got {reason:?}"
    );
    anyhow::ensure!(
        !has_bundle,
        "a divergent equal-amount voucher is a single-signer fault, not a resyncable watermark: no bundle"
    );

    let persisted = fx.store.load_all()?;
    let lane = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane after an accepted voucher"))?;
    anyhow::ensure!(
        lane.last_bytes_delivered() == U256::from(HARNESS_INTERVAL_BYTES),
        "the accepted watermark must not move on a regression reject, got {}",
        lane.last_bytes_delivered()
    );

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// An underpaying voucher after an accepted one draws `Underpaid` carrying the
/// accepted watermark, so a payer whose local watermark ran ahead of the node's
/// can rebase to it instead of wedging the lane. The watermark does not move.
#[tokio::test(flavor = "multi_thread")]
async fn underpaying_voucher_after_an_accepted_voucher_returns_the_watermark() -> anyhow::Result<()>
{
    let mut fx = drive_to_second_interval_awaiting_voucher().await?;

    // Interval 2's bytes for one extra base unit: the span over the accepted
    // watermark pays far below the quoted rate.
    let accepted_amount = min_payment(HARNESS_INTERVAL_BYTES, RATE_PER_MB);
    send_signed_voucher(
        &mut fx.send,
        &fx.signer,
        2 * HARNESS_INTERVAL_BYTES,
        accepted_amount + U256::from(1u64),
    )
    .await?;
    let bundle = loop {
        let msg = tokio::time::timeout(Duration::from_secs(10), read_client_msg(&mut fx.recv))
            .await
            .map_err(|_| anyhow::anyhow!("node never answered with a rejection"))??;
        match msg {
            ClientMessage::ChunkData(_) => {}
            ClientMessage::StreamError(StreamError::VoucherRejected {
                reason: VoucherRejectReason::Underpaid,
                bundle: Some(bundle),
            }) => break bundle,
            other => anyhow::bail!("expected Underpaid carrying the watermark, got {other:?}"),
        }
    };
    anyhow::ensure!(
        U256::from(bundle.amount) == accepted_amount
            && bundle.bytes_delivered == HARNESS_INTERVAL_BYTES,
        "the bundle must report the accepted watermark, got ({}, {})",
        bundle.amount,
        bundle.bytes_delivered
    );

    let persisted = fx.store.load_all()?;
    let lane = persisted
        .first()
        .ok_or_else(|| anyhow::anyhow!("no persisted lane after an accepted voucher"))?;
    anyhow::ensure!(
        lane.last_bytes_delivered() == U256::from(HARNESS_INTERVAL_BYTES),
        "the accepted watermark must not move on an underpay, got {}",
        lane.last_bytes_delivered()
    );

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// A sealed voucher settles part of an outstanding chunk. It moves the watermark
/// less than one interval.
const SLIVER_BYTES: u64 = 64 * 1024;

/// A proof that pays part of an outstanding chunk leaves the rest owed (#2132).
///
/// The node credits a proof only up to the watermark it moves. A sealed voucher
/// that moves the watermark by a sliver pays a sliver of the chunk. The node must
/// keep the remainder outstanding and wait for the proof that pays it. It must not
/// treat the sliver as paying the chunk and reopen the credit window. A node that
/// drops the remainder sends more bytes here, and once `delivered − paid` fills
/// the window with nothing left to collect, its serve loop has no proof to wait
/// for.
#[tokio::test(flavor = "multi_thread")]
async fn a_sliver_voucher_leaves_the_rest_of_the_chunk_owed() -> anyhow::Result<()> {
    let mut fx = drive_to_second_interval_awaiting_voucher().await?;

    // Pay interval 2 by a sliver only. The voucher pays the quoted rate for the
    // span it adds, so the node accepts it and credits exactly the sliver.
    let mut amount = min_payment(HARNESS_INTERVAL_BYTES, RATE_PER_MB);
    amount += min_payment(SLIVER_BYTES, RATE_PER_MB);
    send_signed_voucher(
        &mut fx.send,
        &fx.signer,
        HARNESS_INTERVAL_BYTES + SLIVER_BYTES,
        amount,
    )
    .await?;

    // The rest of interval 2 is still owed, so the window stays shut.
    assert_parked_awaiting_voucher(&mut fx.recv).await?;

    // Paying the remainder settles interval 2 and opens the window for interval 3.
    amount += min_payment(HARNESS_INTERVAL_BYTES - SLIVER_BYTES, RATE_PER_MB);
    send_signed_voucher(&mut fx.send, &fx.signer, 2 * HARNESS_INTERVAL_BYTES, amount).await?;
    read_exact_chunks(&mut fx.recv, HARNESS_INTERVAL_BYTES).await?;

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// A sliver voucher does not starve the runtime (#2132).
///
/// The node, the client and a heartbeat task share one runtime worker. A serve
/// loop that goes around without awaiting holds that worker, so the heartbeat
/// stops ticking. One sliver at the one-interval floor is enough to reach that
/// state in a node that drops the unpaid rest of the chunk: the deliver phase
/// refills `delivered − paid` to the window, and the recoup phase has no chunk
/// left to wait on. The test reads the heartbeat from its own thread, which is
/// not a runtime worker, and leaks a starved runtime rather than drop it: the
/// drop would wait forever for the worker to yield.
#[test]
fn a_sliver_voucher_does_not_starve_the_runtime() -> anyhow::Result<()> {
    use std::sync::atomic::{AtomicU64, Ordering};

    let rt = tokio::runtime::Builder::new_multi_thread()
        .worker_threads(1)
        .enable_all()
        .build()?;
    let ticks = Arc::new(AtomicU64::new(0));
    let (mut fx, heartbeat) = rt.block_on(async {
        let mut fx = drive_to_second_interval_awaiting_voucher().await?;
        let heartbeat = tokio::spawn({
            let ticks = Arc::clone(&ticks);
            async move {
                loop {
                    tokio::time::sleep(Duration::from_millis(10)).await;
                    ticks.fetch_add(1, Ordering::Relaxed);
                }
            }
        });
        let mut amount = min_payment(HARNESS_INTERVAL_BYTES, RATE_PER_MB);
        amount += min_payment(SLIVER_BYTES, RATE_PER_MB);
        send_signed_voucher(
            &mut fx.send,
            &fx.signer,
            HARNESS_INTERVAL_BYTES + SLIVER_BYTES,
            amount,
        )
        .await?;
        anyhow::Ok((fx, heartbeat))
    })?;

    let before = ticks.load(Ordering::Relaxed);
    std::thread::sleep(Duration::from_secs(1));
    let during = ticks.load(Ordering::Relaxed).saturating_sub(before);
    if during < 10 {
        std::mem::forget(fx);
        std::mem::forget(rt);
        anyhow::bail!(
            "the runtime worker ticked {during} times in 1 s: a serve loop holds it without \
             awaiting"
        );
    }

    rt.block_on(async {
        heartbeat.abort();
        // The rest of interval 2 is still owed, so the window stays shut.
        assert_parked_awaiting_voucher(&mut fx.recv).await?;
        fx.conn.close(0u32.into(), b"done");
        shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
        Ok(())
    })
}

/// A payer that answers one chunk with sliver after sliver hits the per-chunk
/// proof budget (#2132). Each sliver credits something, but none settles the
/// chunk. The budget counts every proof that leaves the chunk unsettled, so the
/// node ends the stream instead of holding it open one sliver at a time.
#[tokio::test(flavor = "multi_thread")]
async fn sliver_vouchers_exhaust_the_per_chunk_proof_budget() -> anyhow::Result<()> {
    // The node's private `MAX_PROOFS_PER_CHUNK`; keep the two in step.
    const PROOF_BUDGET: u64 = 8;
    anyhow::ensure!(
        PROOF_BUDGET * SLIVER_BYTES < HARNESS_INTERVAL_BYTES,
        "the slivers must not add up to a whole interval"
    );
    let mut fx = drive_to_second_interval_awaiting_voucher().await?;

    // Each voucher pays the quoted rate for the sliver it adds, so the node
    // accepts every one of them and credits each sliver.
    let mut amount = min_payment(HARNESS_INTERVAL_BYTES, RATE_PER_MB);
    for n in 1..=PROOF_BUDGET {
        amount += min_payment(SLIVER_BYTES, RATE_PER_MB);
        let bytes = HARNESS_INTERVAL_BYTES + n * SLIVER_BYTES;
        send_signed_voucher(&mut fx.send, &fx.signer, bytes, amount).await?;
    }

    // The stream ends with a payment fault: no further byte and no `StreamEnd`.
    match tokio::time::timeout(Duration::from_secs(10), read_client_msg(&mut fx.recv)).await {
        Err(_elapsed) => anyhow::bail!("the node kept the stream open past the proof budget"),
        Ok(Ok(ClientMessage::ChunkData(chunk))) => anyhow::bail!(
            "the node delivered {} more wire bytes on a chunk that is still owed",
            chunk.bytes().len()
        ),
        Ok(Ok(other)) => anyhow::bail!("expected the stream to fail, got {other:?}"),
        Ok(Err(_)) => {}
    }
    // The fault is the payer's, not the node's.
    anyhow::ensure!(
        counter(&fx.metrics, "decdn_serve_stream_node_fault_total")? == 0,
        "a spent proof budget is a client payment fault, not a node fault"
    );
    anyhow::ensure!(
        counter(
            &fx.metrics,
            "decdn_serve_stream_proof_budget_exhausted_total"
        )? == 1,
        "a spent proof budget must be counted"
    );
    support::assert_inbound_failures_attributed(&fx.metrics, 1).await?;

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// A proof that settles a chunk on the last proof of its budget still settles it
/// (#2132). The budget bounds the proofs that leave a chunk unsettled, so a payer
/// may send `MAX_PROOFS_PER_CHUNK − 1` slivers and then pay the rest.
#[tokio::test(flavor = "multi_thread")]
async fn a_chunk_settled_by_the_last_proof_of_its_budget_is_paid() -> anyhow::Result<()> {
    // The node's private `MAX_PROOFS_PER_CHUNK`; keep the two in step.
    const PROOF_BUDGET: u64 = 8;
    let mut fx = drive_to_second_interval_awaiting_voucher().await?;

    let mut amount = min_payment(HARNESS_INTERVAL_BYTES, RATE_PER_MB);
    for n in 1..PROOF_BUDGET {
        amount += min_payment(SLIVER_BYTES, RATE_PER_MB);
        let bytes = HARNESS_INTERVAL_BYTES + n * SLIVER_BYTES;
        send_signed_voucher(&mut fx.send, &fx.signer, bytes, amount).await?;
    }
    let slivers = (PROOF_BUDGET - 1) * SLIVER_BYTES;
    amount += min_payment(HARNESS_INTERVAL_BYTES - slivers, RATE_PER_MB);
    send_signed_voucher(&mut fx.send, &fx.signer, 2 * HARNESS_INTERVAL_BYTES, amount).await?;

    // Interval 2 is paid, so interval 3 arrives.
    read_exact_chunks(&mut fx.recv, HARNESS_INTERVAL_BYTES).await?;
    anyhow::ensure!(
        counter(
            &fx.metrics,
            "decdn_serve_stream_proof_budget_exhausted_total"
        )? == 0,
        "a chunk the last proof of its budget settles must not count as a spent budget"
    );

    fx.conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&fx.client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// The per-connection stream cap sheds an over-cap stream with a bare QUIC reset
/// carrying [`decdn_protocol::APP_ERR_RATE_LIMITED`] and signs no
/// `StreamResponse` (ADR 005 §Concurrent stream limits): signing a response per
/// shed request would let a request flood amplify into one ECDSA signature each,
/// so the cap adds no work to the reject path. One stream holds the sole permit
/// (parked at its closing voucher); a second stream on the same connection is
/// reset without a response.
#[tokio::test(flavor = "multi_thread")]
async fn over_cap_stream_is_reset_without_signing_a_response() -> anyhow::Result<()> {
    // 64 KiB: fits one credit-window floor, so the first stream parks at a single
    // closing voucher while holding the sole stream permit.
    let payload = vec![0x4Bu8; 64 * 1024];
    let (cache, hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let wire_bytes = support::bao_wire_len_whole(payload.len() as u64);

    let signer = Arc::new(PrivateKeySigner::random());
    let store = Arc::new(MemoryPoolStateStore::new());
    store.record(&fresh_lane(signer.address(), U256::from(10_000_000u64)))?;
    let store_dyn: Arc<dyn PoolStateStore> = store.clone();

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = operator_signer();
    let metrics = Arc::new(Metrics::new());
    let limiter = permissive_limiter(&metrics);
    // Per-connection cap of exactly one concurrent stream.
    let handler = build_handler_limited_configured(
        server_id,
        &server_eth,
        &metrics,
        limiter,
        cache,
        store_dyn,
        RATE_PER_MB,
        1,
        |_deps| {},
    )?;
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_server(server_ep.clone(), handler);
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&signer, client_node_id)?;

    // Stream 1 takes the sole permit and parks at its closing voucher, holding it
    // for as long as the test declines to pay.
    let _held =
        stall_delivery_at_closing_voucher(&conn, *hash.as_bytes(), wire_bytes, Some(&ext)).await?;

    // Stream 2 on the SAME connection finds no permit: the handler resets it with
    // RATE_LIMITED and never signs a response.
    let (mut send2, mut recv2) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi (second stream): {e}"))?;
    let req = StreamRequest {
        hash: *hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x0012_61a0,
    };
    write_frame(&mut send2, &encode_stream_request(&req, Some(&ext))?)
        .await
        .map_err(|e| anyhow::anyhow!("write second request: {e}"))?;
    assert_stream_reset(&mut recv2, decdn_protocol::APP_ERR_RATE_LIMITED).await?;
    support::assert_inbound_failures_attributed(&metrics, 1).await?;
    anyhow::ensure!(
        counter(
            &metrics,
            "decdn_serve_stream_rejected_stream_cap_full_total"
        )? == 1,
        "an over-cap stream must be counted"
    );

    // Closing the connection ends the parked stream unpaid: a decline.
    conn.close(0u32.into(), b"done");
    support::assert_inbound_failures_attributed(&metrics, 2).await?;
    anyhow::ensure!(
        counter(&metrics, "decdn_serve_stream_client_declined_total")? == 1,
        "the parked stream ends unpaid"
    );
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The first `chunks_frame` bytes of `wire`, framed as `ChunkData` messages of at
/// most [`LYING_FRAME`] bytes each — a raw upstream's byte stream, hand-rolled so
/// a test can then append more (over-send) or swap in the wrong bytes
/// (hash-mismatch).
const LYING_FRAME: usize = 64 * 1024;

/// Bao interleaved WIRE bytes for the whole of `payload` (content plus proof, ADR
/// 038) — the header-stripped stream a `cdn/client/v1` server emits. Lets a
/// hostile server serve the encoding of a DIFFERENT blob under the requested hash.
fn honest_bao_wire(payload: &[u8]) -> anyhow::Result<Vec<u8>> {
    support::honest_bao_wire_range(payload, 0, 0)
}

/// How a [`serve_lying_stream`] upstream misbehaves after signing a valid
/// `StreamResponse`.
#[derive(Clone, Copy)]
enum Lie {
    /// Stream the honest wire, then one extra full frame past the promised
    /// length — the OOM / overpay shape the client's overrun guard closes.
    OverSend,
    /// Stream the bao encoding of a different blob of the SAME length under the
    /// requested hash — a paid-but-corrupt delivery the client's verifier rejects.
    WrongBytes,
    /// Stream the honest wire with extra bytes appended to its LAST frame, so
    /// the frame straddles the promised length — the shape that trips the
    /// receive loop's mid-stream `cumulative > expected_wire` overrun guard
    /// (a whole extra frame, `OverSend`, surfaces at `finish` instead).
    OverSendStraddling,
    /// Sign an inflated `total_bytes` and stream framed garbage in `frame`-byte
    /// messages for as long as the buyer keeps reading (#1985) — the
    /// bill-for-garbage shape whose exposure the as-it-arrives verifier bounds to
    /// the bytes that landed before the first unverifiable chunk group. With
    /// `served_wire` non-empty, that honest prefix streams first (in
    /// [`LYING_FRAME`] frames) and the garbage follows it.
    InflatedGarbage {
        /// Payload size of each garbage `ChunkData` frame.
        frame: usize,
    },
}

/// A raw `cdn/client/v1` upstream that accepts the request, signs a VALID
/// `StreamResponse` (so the buyer opens the stream and starts paying), then lies
/// on the byte stream per [`Lie`]. Models the hostile server the buyer's own
/// receive-side guards defend against — the counterpart to the payment-fault
/// tests, which model a hostile client.
async fn serve_lying_stream(
    conn: Connection,
    eth: &Arc<PrivateKeySigner>,
    slash: &Eip712Domain,
    served_wire: &[u8],
    advertised_total_bytes: u64,
    lie: Lie,
) -> anyhow::Result<()> {
    let (mut send, mut recv) = conn
        .accept_bi()
        .await
        .map_err(|e| anyhow::anyhow!("accept_bi: {e}"))?;
    let req = match read_client_msg(&mut recv).await? {
        ClientMessage::StreamRequest(req) => req,
        other => anyhow::bail!("lying upstream: expected a StreamRequest, got {other:?}"),
    };

    let body = StreamResponseBody {
        hash: req.hash,
        ok: true,
        rate_per_mb: RATE_PER_MB,
        total_bytes: advertised_total_bytes,
        pool_id: req.pool_id,
        timestamp_us: req.timestamp_us,
    };
    let slash_sig = StreamSlashData::from_response_body(&body)
        .sign(eth.as_ref(), slash)
        .map_err(|e| anyhow::anyhow!("slash sign: {e}"))?
        .as_bytes()
        .to_vec();
    let resp = StreamResponse { body, slash_sig };
    write_frame(
        &mut send,
        &encode_stream_response(&resp, Some(&StreamResponseExt { error: None }))?,
    )
    .await
    .map_err(|e| anyhow::anyhow!("write response: {e}"))?;

    let frames: Vec<&[u8]> = served_wire.chunks(LYING_FRAME).collect();
    for (i, chunk) in frames.iter().enumerate() {
        let mut payload = chunk.to_vec();
        if matches!(lie, Lie::OverSendStraddling) && i + 1 == frames.len() {
            // The final honest frame carries a tail past the promised length.
            payload.extend(std::iter::repeat_n(0u8, 4096));
        }
        write_client_msg(
            &mut send,
            &ClientMessage::ChunkData(ChunkData::new(payload)?),
        )
        .await?;
    }

    match lie {
        Lie::OverSendStraddling => {
            // The buyer bails on the straddling frame before any `StreamEnd`, so
            // nothing more is owed here.
        }
        Lie::InflatedGarbage { frame } => {
            // Keep pushing garbage until the buyer closes the connection: a
            // write error is the expected end of this lie, not a test fault.
            let mut garbage = vec![0u8; frame];
            let mut noise: u64 = 0x9e37_79b9_7f4a_7c15;
            loop {
                for b in &mut garbage {
                    noise ^= noise << 13;
                    noise ^= noise >> 7;
                    noise ^= noise << 17;
                    *b = noise.to_le_bytes().first().copied().unwrap_or(0);
                }
                let msg = ClientMessage::ChunkData(ChunkData::new(garbage.clone())?);
                if write_client_msg(&mut send, &msg).await.is_err() {
                    break;
                }
            }
        }
        Lie::OverSend => {
            // One extra full frame past the promised length: the buyer's decoder
            // consumes exactly the promised wire, so the frame surfaces at
            // `finish` as `ChunkData` after the promised total; it bails before
            // any `StreamEnd`, so nothing more is owed here.
            write_client_msg(
                &mut send,
                &ClientMessage::ChunkData(ChunkData::new(vec![0u8; LYING_FRAME])?),
            )
            .await?;
        }
        Lie::WrongBytes => {
            // The promised byte count is honest. The buyer verifies each chunk
            // group as it lands and drops the connection at the first mismatch;
            // tolerate whatever it sent before that and close cleanly so the
            // failure is unambiguously the integrity check, not a truncated
            // stream.
            let _ = read_client_msg(&mut recv).await;
            let _ = write_client_msg(&mut send, &ClientMessage::StreamEnd).await;
        }
    }
    let _ = send.finish();
    conn.closed().await;
    Ok(())
}

/// Spawn a one-connection [`serve_lying_stream`] server.
fn spawn_lying_server(
    ep: Endpoint,
    eth: Arc<PrivateKeySigner>,
    slash: Eip712Domain,
    served_wire: Vec<u8>,
    advertised_total_bytes: u64,
    lie: Lie,
) -> tokio::task::JoinHandle<()> {
    tokio::spawn(async move {
        if let Ok(conn) = support::accept_one(&ep).await {
            let _ = serve_lying_stream(
                conn,
                &eth,
                &slash,
                &served_wire,
                advertised_total_bytes,
                lie,
            )
            .await;
        }
    })
}

/// The buyer rejects a server that streams more bytes than its signed
/// `StreamResponse` promised (ADR 005 §`cdn/client/v1`). The decoder consumes
/// exactly the promised wire, so the extra frame surfaces at `finish` as
/// `ChunkData` after the promised total; a frame that lands mid-stream trips the
/// `cumulative > expected_wire` overrun guard instead. Either way the fetch
/// bails before the extra bytes can drive an OOM or an overpay, and the node's
/// `is_bao_corruption` classifies both messages as the same over-delivery.
#[tokio::test(flavor = "multi_thread")]
async fn client_rejects_a_server_that_oversends_past_the_promised_length() -> anyhow::Result<()> {
    // Under one interval, so the honest wire is a single closing-voucher span and
    // the extra frame is unambiguously past the promise.
    let payload = vec![0x2Du8; 256 * 1024];
    let hash = Hash::new(&payload);
    let wire = honest_bao_wire(&payload)?;
    let total_bytes = payload.len() as u64;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_lying_server(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        wire,
        total_bytes,
        Lie::OverSend,
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(10_000_000u64),
    );
    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("an over-sending server must fail the fetch"))?;
    let msg = format!("{err:#}");
    anyhow::ensure!(
        msg.contains("more than") || msg.contains("after the promised total"),
        "the fetch must fail on the over-delivery guard, got: {msg}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The mid-stream overrun guard: a frame that STRADDLES the promised length
/// trips `cumulative > expected_wire` inside the receive loop — before the
/// straddling frame is paid for — rather than reaching `finish` (ADR 005
/// §`cdn/client/v1`).
#[tokio::test(flavor = "multi_thread")]
async fn client_rejects_a_frame_that_straddles_the_promised_length() -> anyhow::Result<()> {
    let payload = vec![0x2Eu8; 256 * 1024];
    let hash = Hash::new(&payload);
    let wire = honest_bao_wire(&payload)?;
    let total_bytes = payload.len() as u64;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_lying_server(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        wire,
        total_bytes,
        Lie::OverSendStraddling,
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(10_000_000u64),
    );
    let mut progress = VoucherProgress::default();
    let err = stream_fetch_tracked(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c0_ffee,
        PullDeadlines::whole_transfer(Duration::from_secs(20)),
        0,
        0,
        &mut progress,
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("a straddling frame must fail the fetch"))?;
    let msg = format!("{err:#}");
    anyhow::ensure!(
        msg.contains("more than"),
        "the fetch must fail on the mid-stream overrun guard, got: {msg}"
    );
    anyhow::ensure!(
        progress.advanced().is_none(),
        "the straddling frame is rejected before it is paid for: {:?}",
        progress.advanced()
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The buyer rejects hash-mismatched bytes: a server that serves the bao encoding
/// of a DIFFERENT blob under the requested hash passes the framing but fails
/// verification, so the fetch returns the typed [`HashMismatch`] and surfaces no
/// bytes (ADR 038 §Receive side).
#[tokio::test(flavor = "multi_thread")]
async fn client_rejects_hash_mismatched_bytes() -> anyhow::Result<()> {
    // Two distinct blobs of the SAME length: the wire lengths match, so the
    // buyer reads exactly the promised count and the only thing wrong is content.
    let wanted = vec![0x11u8; 256 * 1024];
    let served = vec![0x22u8; 256 * 1024];
    let wanted_hash = Hash::new(&wanted);
    anyhow::ensure!(Hash::new(&served) != wanted_hash, "fixtures must differ");
    let served_wire = honest_bao_wire(&served)?;
    let total_bytes = wanted.len() as u64;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_lying_server(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        served_wire,
        total_bytes,
        Lie::WrongBytes,
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(10_000_000u64),
    );
    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *wanted_hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("a hash-mismatched delivery must fail the fetch"))?;
    anyhow::ensure!(
        err.downcast_ref::<HashMismatch>().is_some(),
        "the fetch must fail with the typed HashMismatch, got: {err:#}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A server claiming `total_bytes == 0` for a NON-empty requested hash is
/// rejected with the typed [`HashMismatch`] (#1054): an empty range has no chunk
/// group for the decoder to anchor, so the empty stream must be proven against
/// the empty root explicitly rather than accepted for an arbitrary one.
#[tokio::test(flavor = "multi_thread")]
async fn client_rejects_an_empty_claim_for_a_non_empty_hash() -> anyhow::Result<()> {
    let wanted_hash = Hash::new(b"not the empty blob");

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    // No wire at all and an honest-looking `total_bytes = 0`: `WrongBytes` then
    // just tolerates the buyer's abort and sends `StreamEnd`.
    let server_task = spawn_lying_server(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        Vec::new(),
        0,
        Lie::WrongBytes,
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(10_000_000u64),
    );
    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *wanted_hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("an empty claim for a non-empty hash must fail the fetch"))?;
    anyhow::ensure!(
        err.downcast_ref::<HashMismatch>().is_some(),
        "the fetch must fail with the typed HashMismatch, got: {err:#}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Run one `stream_fetch_tracked` against a [`Lie::InflatedGarbage`] server that
/// signs a 32 MiB `total_bytes` for `hash` and streams `frame`-byte garbage,
/// returning the error and the buyer's paid watermark.
async fn fetch_inflated_garbage(frame: usize) -> anyhow::Result<(anyhow::Error, VoucherProgress)> {
    // Any non-empty root the garbage cannot verify against.
    let hash = Hash::new(b"the blob the buyer actually asked for");
    let claimed_total: u64 = 32 << 20;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_lying_server(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        Vec::new(),
        claimed_total,
        Lie::InflatedGarbage { frame },
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    // A deposit that could pay for the whole inflated claim many times over, so
    // the spend bound under test is the verifier's, not the deposit's.
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(1_000_000_000u64),
    );
    let mut progress = VoucherProgress::default();
    let err = stream_fetch_tracked(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c0_ffee,
        PullDeadlines::whole_transfer(Duration::from_secs(20)),
        // No buyer-side size ceiling: the bound under test is verification, not
        // `max_blob_size_bytes`.
        0,
        0,
        &mut progress,
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("a garbage delivery must fail the fetch"))?;

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok((err, progress))
}

/// A provider that signs an inflated `total_bytes` and streams framed garbage
/// (#1985) bills NOTHING when its frames are smaller than the 1 MiB metering
/// interval: the verifier rejects the first chunk group as it lands, before one
/// reveal's worth of unproved bytes accrues, and the fetch surfaces the typed
/// [`HashMismatch`]. The signed claim never enters the buyer's accounting.
#[tokio::test(flavor = "multi_thread")]
async fn client_pays_nothing_for_an_inflated_garbage_claim() -> anyhow::Result<()> {
    let (err, progress) = fetch_inflated_garbage(LYING_FRAME).await?;
    anyhow::ensure!(
        err.downcast_ref::<HashMismatch>().is_some(),
        "garbage must surface the typed HashMismatch, got: {err:#}"
    );
    anyhow::ensure!(
        progress.advanced().is_none(),
        "the first chunk group fails before a metering interval accrues, so nothing is \
         paid: {:?}",
        progress.advanced()
    );
    Ok(())
}

/// The exposure bound (#1985): what an inflated-garbage provider can bill is the
/// wire bytes that arrived before the first unverifiable chunk group — here one
/// oversized 3 MiB frame, which releases its whole reveals before the decoder
/// sees a byte — and never the 32 MiB it signed for. A reveal pays for received
/// bytes, not verified ones, so the bound is a frame plus a metering interval,
/// not zero; pinning it here is what keeps verification from ever being
/// deferred to stream end, with every reveal released before it.
#[tokio::test(flavor = "multi_thread")]
async fn client_spend_on_a_garbage_stream_is_bounded_by_one_frame() -> anyhow::Result<()> {
    let frame: usize = 3 * 1024 * 1024;
    let (err, progress) = fetch_inflated_garbage(frame).await?;
    anyhow::ensure!(
        err.downcast_ref::<HashMismatch>().is_some(),
        "garbage must surface the typed HashMismatch, got: {err:#}"
    );
    // The bound under test is the UPPER one. A frame larger than the metering
    // interval releases its reveals before the decoder sees a byte, so the buyer
    // pays here; a stricter receiver that paid nothing would tighten the bound,
    // not break it.
    let paid_bytes = progress.advanced().map_or(U256::ZERO, |(bytes, _)| bytes);
    anyhow::ensure!(
        paid_bytes <= U256::from(frame),
        "paid {paid_bytes} bytes, more than the single {frame}-byte frame that arrived"
    );
    anyhow::ensure!(
        paid_bytes < U256::from(32u64 << 20),
        "paid {paid_bytes} bytes against a 32 MiB claim: the claim must never be billed"
    );
    Ok(())
}

/// The exposure bound with a verified prefix (#1985): a provider that streams
/// honest wire for the first ~2.5 MiB of a 4 MiB blob and garbage from there on
/// (under an honest `total_bytes`) is paid for the verified prefix and nothing
/// beyond it — not the corrupt group, not the rest of the blob. Pins the bound in
/// the shape that matters: payment for verified groups coexists with the
/// cut-off at the first unverifiable one, and the two 1 MiB reveals the prefix
/// earns prove the bound is about *where the decoder stops*, not "pay nothing".
#[tokio::test(flavor = "multi_thread")]
async fn client_pays_for_an_honest_prefix_and_stops_at_the_first_bad_group() -> anyhow::Result<()> {
    let payload = vec![0x5Du8; 4 * 1024 * 1024];
    let hash = Hash::new(&payload);
    let total_bytes = payload.len() as u64;
    let mut wire = honest_bao_wire(&payload)?;
    // Corrupt every byte from ~2.5 MiB of wire onward: the group holding that
    // position fails to verify, and nothing after it can.
    let corrupt_from = 2_500_000usize;
    for b in wire.iter_mut().skip(corrupt_from) {
        *b ^= 0xff;
    }

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_lying_server(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        wire,
        total_bytes,
        Lie::WrongBytes,
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(1_000_000_000u64),
    );
    let mut progress = VoucherProgress::default();
    let err = stream_fetch_tracked(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        0x00c0_ffee,
        PullDeadlines::whole_transfer(Duration::from_secs(20)),
        0,
        0,
        &mut progress,
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("a corrupt tail must fail the fetch"))?;
    anyhow::ensure!(
        err.downcast_ref::<HashMismatch>().is_some(),
        "the corrupt tail must surface the typed HashMismatch, got: {err:#}"
    );
    let (paid, _) = progress
        .advanced()
        .ok_or_else(|| anyhow::anyhow!("the verified prefix spans two metering intervals"))?;
    // The decoder consumed every honest byte before the corrupt group, so at least
    // the two whole 1 MiB intervals inside the prefix were revealed...
    anyhow::ensure!(
        paid >= U256::from(2u64 << 20),
        "paid {paid} wire bytes for a ~2.5 MiB verified prefix"
    );
    // ...and not one byte of the corrupt group: payment follows verification.
    let bound = U256::from(corrupt_from as u64);
    anyhow::ensure!(
        paid <= bound,
        "paid {paid} wire bytes, past the first corrupt byte at {bound}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The request-read timeout tears down a stream whose opener goes silent: a peer
/// that opens a bidi stream and sends no `StreamRequest` is reset once
/// `REQUEST_READ_TIMEOUT` elapses, with the no-error code (a stalled peer is not
/// a protocol fault) — the node never blocks a serve slot on a silent opener.
#[tokio::test(flavor = "multi_thread")]
async fn request_read_timeout_resets_a_silent_opener() -> anyhow::Result<()> {
    let payload = vec![0x61u8; 64 * 1024];
    let (cache, _hash, _cache_tmp) = cache_with_blob(&payload).await?;
    let (store, _signer, _deposit) = seeded_store()?;

    let (target, _server_eth, server_ep, server_task) =
        spawn_handler_server(cache, store, RATE_PER_MB, 16).await?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(target, ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;

    // Open a stream and send only a frame LENGTH prefix, withholding the body: the
    // stream reaches the server (an unwritten `open_bi` never does), which parks in
    // `read_first_message`'s framed read and must give up at the request-read
    // timeout (5s). `send` is held for the whole wait so the client does not FIN
    // and end the read early — the reset must be the server's timeout, not our EOF.
    let (mut send, mut recv) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi: {e}"))?;
    send.write_all(&[64u8])
        .await
        .map_err(|e| anyhow::anyhow!("write frame len: {e}"))?;

    // The parked read is reset (or the connection closed) once the timeout fires;
    // either way no frame is ever readable. A clean empty EOF would mean the peer
    // FIN'd — impossible here, `send` is still open — so it is not accepted.
    let ended = tokio::time::timeout(Duration::from_secs(15), read_frame(&mut recv)).await;
    match ended {
        Ok(Err(_)) => {}
        Ok(Ok(frame)) => {
            anyhow::bail!(
                "server answered a partial request with a {}-byte frame",
                frame.len()
            )
        }
        Err(_elapsed) => {
            anyhow::bail!("server never reset a silent opener within the request-read timeout")
        }
    }
    drop(send);

    conn.close(0u32.into(), b"done");
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// The proof wait tears down a parked paid delivery: a payer that reads the whole
/// blob and then withholds its closing voucher leaves the connection with no
/// transport progress, so it is cut off once `VOUCHER_READ_TIMEOUT` elapses (the
/// stream resets with no `StreamEnd`), and no watermark advances — a silent payer
/// cannot pin the serve loop indefinitely.
#[tokio::test(flavor = "multi_thread")]
async fn voucher_read_timeout_ends_a_parked_delivery() -> anyhow::Result<()> {
    // Under one credit-window floor, so the delivery parks at a single closing
    // voucher — the exact point `commit_one_proof` blocks under the timeout.
    let payload = vec![0x62u8; 64 * 1024];
    // Idle window well past the 10s no-progress proof wait the test is waiting
    // on, so the app-layer idle reaper never fires first.
    let fx = idle_fixture(&payload, Duration::from_secs(45)).await?;
    let blob = fx.blob(0)?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;
    let mut stalled = stall_delivery_at_closing_voucher(
        &conn,
        *blob.hash.as_bytes(),
        blob.wire_bytes,
        Some(&ext),
    )
    .await?;

    // Withhold the voucher. The server is parked in `commit_one_proof`'s proof
    // wait and must give up at the no-progress timeout (10s), ending the stream
    // with no `StreamEnd` — whether by a reset or a clean close, the payment never
    // completes, so the next read yields an error rather than a `StreamEnd`.
    let ended =
        tokio::time::timeout(Duration::from_secs(20), read_client_msg(&mut stalled.recv)).await;
    match ended {
        Ok(Err(_)) => {}
        Ok(Ok(ClientMessage::StreamEnd)) => {
            anyhow::bail!("the delivery must not complete without a paid closing voucher")
        }
        Ok(Ok(other)) => anyhow::bail!("expected the stream to end unpaid, got {other:?}"),
        Err(_elapsed) => {
            anyhow::bail!("server never ended the parked delivery within its proof wait")
        }
    }

    // No voucher was ever accepted, so the lane watermark stayed at zero.
    let persisted = fx.store.load_all()?;
    if let Some(lane) = persisted.first() {
        anyhow::ensure!(
            lane.last_bytes_delivered() == U256::ZERO,
            "a timed-out delivery must advance no watermark, got {}",
            lane.last_bytes_delivered()
        );
    }

    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// The proof wait counts transport progress, and only progress extends it
/// (#2230). A payer that stops reading and paying right after the response
/// leaves the node's first credit window in its receive buffer: the connection
/// sends no new STREAM frame, so the node gives up on proof 1 at the 10s
/// no-progress timeout, well before the 30s proof-wait ceiling.
#[tokio::test(flavor = "multi_thread")]
async fn a_payer_that_stops_reading_faults_at_the_no_progress_timeout() -> anyhow::Result<()> {
    // Several chunks, so the node writes one credit window, then waits for the
    // proof of its first chunk. One window fits the client's stream receive
    // window, so the node's writes complete although the client reads nothing.
    let payload: Vec<u8> = (0..3 * 1024 * 1024u32).map(|i| (i % 251) as u8).collect();
    // Idle window well past the 30s ceiling, so the app-layer idle reaper never
    // fires first.
    let fx = idle_fixture(&payload, Duration::from_secs(45)).await?;
    let blob = fx.blob(0)?;

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let conn = client_ep
        .connect(fx.target.clone(), ALPN_CLIENT)
        .await
        .map_err(|e| anyhow::anyhow!("connect: {e}"))?;
    let client_node_id = B256::from(*client_ep.id().as_bytes());
    let ext = binding_ext(&fx.client_signer, client_node_id)?;

    let (mut send, mut recv) = conn
        .open_bi()
        .await
        .map_err(|e| anyhow::anyhow!("open_bi: {e}"))?;
    let req = StreamRequest {
        hash: *blob.hash.as_bytes(),
        namespace_id: decdn_protocol::client::NO_NAMESPACE,
        pool_id: pool_id().into(),
        byte_offset: 0,
        byte_len: 0,
        timestamp_us: 0x0012_61a1,
    };
    let request = encode_stream_request(&req, Some(&ext))
        .map_err(|e| anyhow::anyhow!("encode request: {e}"))?;
    write_frame(&mut send, &request)
        .await
        .map_err(|e| anyhow::anyhow!("write request: {e}"))?;
    let (resp, resp_ext) = read_stream_response(&mut recv).await?;
    anyhow::ensure!(resp.body.ok, "delivery refused: {:?}", resp_ext.error);

    // Read nothing more and pay nothing. The node ends the stream by dropping
    // its receive half, which stops this send half.
    let waiting_since = Instant::now();
    let stopped = tokio::time::timeout(Duration::from_secs(25), send.stopped()).await;
    let waited = waiting_since.elapsed();
    match stopped {
        Ok(Ok(_)) => {}
        Ok(Err(e)) => anyhow::bail!("the stream ended without a stop: {e}"),
        Err(_elapsed) => anyhow::bail!("the node held a silent payer past 25s"),
    }
    anyhow::ensure!(
        waited >= Duration::from_secs(9),
        "the node faulted the payer after {waited:?}, before the 10s no-progress timeout"
    );
    anyhow::ensure!(
        waited < Duration::from_secs(15),
        "the node held a payer with no transport progress for {waited:?}; it must fault \
         at the 10s no-progress timeout, not at the 30s ceiling"
    );

    // The stall is the payer's fault: it ends on exactly one inbound reason
    // counter, and that counter is not the node-fault one.
    support::assert_inbound_failures_attributed(&fx.metrics, 1).await?;
    anyhow::ensure!(
        counter(&fx.metrics, "decdn_serve_stream_node_fault_total")? == 0,
        "a stalled payer must not count as a node fault"
    );

    // No proof was ever accepted, so the lane watermark stayed at zero.
    let persisted = fx.store.load_all()?;
    if let Some(lane) = persisted.first() {
        anyhow::ensure!(
            lane.last_bytes_delivered() == U256::ZERO,
            "an unpaid delivery must advance no watermark, got {}",
            lane.last_bytes_delivered()
        );
    }

    drop(recv);
    drop(send);
    conn.close(0u32.into(), b"done");
    shutdown([fx.server_task], [&client_ep, &fx.server_ep]).await?;
    Ok(())
}

/// The terminal signal [`serve_stop_send_then_signal`] sends once it has stopped
/// the buyer's send half — a clean end or a mid-stream rejection.
#[derive(Clone, Copy)]
enum StopThenSignal {
    /// A clean `StreamEnd` over the whole delivered blob — the completion race a
    /// node hits when it finishes and drops `recv`.
    End,
    /// A `StreamError::VoucherRejected` in place of a clean end — the typed
    /// rejection the node answers a spent pool with, whose reset otherwise masks
    /// the reason as an opaque write failure.
    Reject(VoucherRejectReason),
}

/// Where [`serve_stop_send_then_signal`] stops the buyer's send half.
#[derive(Clone, Copy)]
enum StopPoint {
    /// Before any chunk data: the buyer's FIRST proof write fails. For a blob under
    /// one chunk that is the closing voucher.
    BeforeData,
    /// After enough wire for one whole chunk and the verify lag has been served and
    /// the buyer's proofs for it (the anchoring voucher and the reveal) have been
    /// read: only the
    /// closing voucher for the residual fails, the reveals stand.
    AfterFirstReveal,
}

/// A raw `cdn/client/v1` upstream that signs a valid `StreamResponse`, STOPS the
/// buyer's send half at `stop` — *before* the closing voucher can be written —
/// streams the requested range, and finally sends a terminal signal.
///
/// The stop is issued causally before the chunk data the buyer must read to reach
/// its closing-voucher write: on localhost, in-order delivery means the buyer's
/// connection processes the `STOP_SENDING` before it has the bytes it needs, so the
/// buyer's write deterministically fails with the peer-stop. This is the exact
/// end-of-stream race a node produces when it writes `StreamEnd` and then drops its
/// `recv` (an implicit `STOP_SENDING(0)`) while the buyer is still flushing its
/// closing voucher.
async fn serve_stop_send_then_signal(
    conn: Connection,
    eth: &Arc<PrivateKeySigner>,
    slash: &Eip712Domain,
    payload: &[u8],
    stop: StopPoint,
    signal: StopThenSignal,
) -> anyhow::Result<()> {
    let total_bytes = u64::try_from(payload.len()).unwrap_or(u64::MAX);
    let (mut send, mut recv) = conn
        .accept_bi()
        .await
        .map_err(|e| anyhow::anyhow!("accept_bi: {e}"))?;
    let req = match read_client_msg(&mut recv).await? {
        ClientMessage::StreamRequest(req) => req,
        other => anyhow::bail!("stop-send upstream: expected a StreamRequest, got {other:?}"),
    };

    let body = StreamResponseBody {
        hash: req.hash,
        ok: true,
        rate_per_mb: RATE_PER_MB,
        total_bytes,
        pool_id: req.pool_id,
        timestamp_us: req.timestamp_us,
    };
    let slash_sig = StreamSlashData::from_response_body(&body)
        .sign(eth.as_ref(), slash)
        .map_err(|e| anyhow::anyhow!("slash sign: {e}"))?
        .as_bytes()
        .to_vec();
    let resp = StreamResponse { body, slash_sig };
    write_frame(
        &mut send,
        &encode_stream_response(&resp, Some(&StreamResponseExt { error: None }))?,
    )
    .await
    .map_err(|e| anyhow::anyhow!("write response: {e}"))?;

    // Honour the requested range: a gap-driven re-open lands at the paid frontier,
    // and the honest wire for `[byte_offset, byte_len)` is its own range encoding.
    let served_wire = support::honest_bao_wire_range(payload, req.byte_offset, req.byte_len)?;
    let mut frames = served_wire.chunks(LYING_FRAME);

    // A re-opened range too short to earn a reveal meets the stop before any data.
    // The buyer pays for a chunk only once it has verified the leaf that holds the
    // chunk's last byte, so a reveal needs the verify lag on the wire past it.
    let floor_bytes = usize::try_from(HARNESS_FLOOR_BYTES)?;
    if matches!(stop, StopPoint::AfterFirstReveal) && served_wire.len() >= floor_bytes {
        // Serve one whole chunk's worth of wire and the verify lag, then take the
        // buyer's proofs for it off the stream (the anchoring voucher, then the
        // reveal), so those stand and only the closing voucher below meets the stop.
        let mut served = 0usize;
        while served < floor_bytes {
            let chunk = frames
                .next()
                .ok_or_else(|| anyhow::anyhow!("wire shorter than one chunk"))?;
            served += chunk.len();
            write_client_msg(
                &mut send,
                &ClientMessage::ChunkData(ChunkData::new(chunk.to_vec())?),
            )
            .await?;
        }
        loop {
            match read_client_msg(&mut recv).await? {
                ClientMessage::ChunkPreimage(_) => break,
                ClientMessage::Voucher(_) => {}
                other => anyhow::bail!("stop-send upstream: expected a proof, got {other:?}"),
            }
        }
    }

    // Stop the buyer's send half NOW — before the chunk data below, so the
    // `STOP_SENDING(0)` is processed by the buyer before it can read the bytes it
    // needs to reach its closing-voucher write. `0` is the no-error code a node's
    // own teardown uses.
    recv.stop(VarInt::from_u32(0))
        .map_err(|e| anyhow::anyhow!("stop recv: {e}"))?;

    for chunk in frames {
        write_client_msg(
            &mut send,
            &ClientMessage::ChunkData(ChunkData::new(chunk.to_vec())?),
        )
        .await?;
    }

    match signal {
        StopThenSignal::End => {
            write_client_msg(&mut send, &ClientMessage::StreamEnd).await?;
        }
        StopThenSignal::Reject(reason) => {
            write_client_msg(
                &mut send,
                &ClientMessage::StreamError(StreamError::VoucherRejected {
                    reason,
                    bundle: None,
                }),
            )
            .await?;
        }
    }
    let _ = send.finish();
    conn.closed().await;
    Ok(())
}

/// Spawn a one-connection [`serve_stop_send_then_signal`] server.
fn spawn_stop_send_server(
    ep: Endpoint,
    eth: Arc<PrivateKeySigner>,
    slash: Eip712Domain,
    payload: Vec<u8>,
    signal: StopThenSignal,
) -> tokio::task::JoinHandle<()> {
    spawn_stop_send_server_counting(
        ep,
        eth,
        slash,
        payload,
        StopPoint::BeforeData,
        signal,
        1,
        Arc::default(),
    )
}

/// Spawn a [`serve_stop_send_then_signal`] server that accepts up to `max_conns`
/// connections, counting each accept into `accepted`. A gap-driven buyer that does
/// not take the stopped leg as paid re-opens the gap on a fresh connection; the cap
/// turns such a re-leg loop into a fast open failure rather than a hang, and the
/// count is what a test asserts on.
#[allow(clippy::too_many_arguments)]
fn spawn_stop_send_server_counting(
    ep: Endpoint,
    eth: Arc<PrivateKeySigner>,
    slash: Eip712Domain,
    payload: Vec<u8>,
    stop: StopPoint,
    signal: StopThenSignal,
    max_conns: usize,
    accepted: Arc<std::sync::atomic::AtomicUsize>,
) -> tokio::task::JoinHandle<()> {
    use std::sync::atomic::Ordering;
    tokio::spawn(async move {
        let payload = Arc::new(payload);
        let mut serves = Vec::new();
        for _ in 0..max_conns {
            let Ok(conn) = support::accept_one(&ep).await else {
                break;
            };
            accepted.fetch_add(1, Ordering::SeqCst);
            let (eth, slash, payload) = (Arc::clone(&eth), slash.clone(), Arc::clone(&payload));
            serves.push(tokio::spawn(async move {
                let _ =
                    serve_stop_send_then_signal(conn, &eth, &slash, &payload, stop, signal).await;
            }));
        }
        for serve in serves {
            let _ = serve.await;
        }
    })
}

/// A buyer whose send half is stopped before its closing voucher still COMPLETES
/// when the whole blob and a clean `StreamEnd` are on the wire: a voucher-write
/// peer-stop is not fatal when the node has already delivered everything and signed
/// off. This is the end-of-stream race — the node finishes, drops `recv`, and the
/// buyer's trailing voucher write loses to the implicit `STOP_SENDING(0)`.
#[tokio::test(flavor = "multi_thread")]
async fn client_completes_when_its_send_is_stopped_before_the_closing_voucher() -> anyhow::Result<()>
{
    // Under one chunk, so the buyer owes exactly one closing voucher — the single
    // write the node's teardown races.
    let payload = vec![0x5Au8; 256 * 1024];
    let hash = Hash::new(&payload);

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_stop_send_server(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        payload.clone(),
        StopThenSignal::End,
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(10_000_000u64),
    );
    let blob = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await?;
    anyhow::ensure!(
        blob.as_ref() == payload.as_slice(),
        "a fully delivered blob must survive a closing-voucher peer-stop"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// A buyer whose closing-voucher write is stopped surfaces the node's typed
/// `StreamError` — not an opaque write failure. When a node rejects a payer (a
/// spent pool) it writes `VoucherRejected` and resets; the reset otherwise masks
/// the typed reason as "write failed", and the fault classification that sends
/// a funding rejection to the recovery step keys on [`UpstreamVoucherRejected`]. Under one chunk, so the only voucher is the
/// closing one — the same end-of-stream write the sibling test covers, with a
/// rejection terminal in place of a clean `StreamEnd`. A write that fails mid-
/// delivery, with frames still in flight ahead of the terminal, is
/// `client_reads_past_in_flight_frames_to_a_typed_rejection`.
#[tokio::test(flavor = "multi_thread")]
async fn client_surfaces_typed_rejection_when_its_send_is_stopped_before_the_closing_voucher()
-> anyhow::Result<()> {
    let payload = vec![0x5Bu8; 256 * 1024];
    let hash = Hash::new(&payload);

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_stop_send_server(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        payload.clone(),
        StopThenSignal::Reject(VoucherRejectReason::SpendingCapExhausted),
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(10_000_000u64),
    );
    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffee,
        Duration::from_secs(20),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("a rejected fetch must fail"))?;
    anyhow::ensure!(
        err.downcast_ref::<UpstreamVoucherRejected>().is_some(),
        "the fetch must surface the typed UpstreamVoucherRejected, got: {err:#}"
    );

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(())
}

/// Fetch a 3 MiB blob from a [`spawn_stop_send_server`] that stops the buyer's
/// send half before any data, then sends the whole wire and `signal`. The
/// buyer's first proof write fails with most of the blob still in flight
/// ahead of the terminal message.
async fn fetch_with_frames_in_flight(signal: StopThenSignal) -> anyhow::Result<anyhow::Error> {
    let payload: Vec<u8> = (0..3 * 1024 * 1024u32).map(|i| (i % 239) as u8).collect();
    let hash = Hash::new(&payload);

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let server_task = spawn_stop_send_server(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        payload,
        signal,
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(10_000_000u64),
    );
    let err = stream_fetch(
        &client_ep,
        target,
        &ctx,
        &slash_domain(),
        server_eth.address(),
        *hash.as_bytes(),
        0,
        0x00c0_ffef,
        Duration::from_secs(20),
    )
    .await
    .err()
    .ok_or_else(|| anyhow::anyhow!("a fetch whose proof write fails mid-blob must fail"))?;
    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(err)
}

/// A node delivers ahead of payment within its credit window, so the frames it
/// sent before it rejected sit in front of its `StreamError`. The buyer whose
/// proof write fails reads past them to the typed rejection, which the reactive
/// top-up and the `UnderFold` heal key on (#2168).
#[tokio::test(flavor = "multi_thread")]
async fn client_reads_past_in_flight_frames_to_a_typed_rejection() -> anyhow::Result<()> {
    let err = fetch_with_frames_in_flight(StopThenSignal::Reject(
        VoucherRejectReason::SpendingCapExhausted,
    ))
    .await?;
    anyhow::ensure!(
        err.downcast_ref::<UpstreamVoucherRejected>().is_some(),
        "the fetch must surface the typed UpstreamVoucherRejected, got: {err:#}"
    );
    Ok(())
}

/// A `StreamEnd` behind frames the buyer passed over confirms nothing: the leg
/// did not take in those bytes, so it must not read as paid through its end.
#[tokio::test(flavor = "multi_thread")]
async fn a_stream_end_behind_skipped_frames_fails_the_leg() -> anyhow::Result<()> {
    let err = fetch_with_frames_in_flight(StopThenSignal::End).await?;
    anyhow::ensure!(
        format!("{err:#}").contains("did not take in"),
        "the fetch must fail on the skipped frames, got: {err:#}"
    );
    Ok(())
}

/// What one gap-driven `drive` against a stop-sending upstream left behind.
struct StopSendDrive {
    /// The `drive` outcome.
    result: anyhow::Result<()>,
    /// The lane the drive paid out of, read after `drive` returns.
    ledger: Arc<PoolLedger>,
    /// Connections the upstream accepted.
    accepted: usize,
    /// The bytes the ranged store promoted, if it finalized.
    promoted: Option<Vec<u8>>,
    /// The `decdn_client` events the drive emitted. The stop-send race only
    /// tests the recovery when the voucher write actually fails, and a write that
    /// wins the race leaves the ledger in the same end state. So the recovery's
    /// own event is the proof that it ran.
    logs: String,
}

/// A `std::io::Write` sink appending to a shared buffer, for capturing events.
#[derive(Clone)]
struct CapturedLogs(Arc<std::sync::Mutex<Vec<u8>>>);

impl std::io::Write for CapturedLogs {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        self.0
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .extend_from_slice(buf);
        Ok(buf.len())
    }

    fn flush(&mut self) -> std::io::Result<()> {
        Ok(())
    }
}

/// The event the voucher-write recovery emits when a `StreamEnd` confirms the
/// voucher whose write failed.
const CONFIRMED_EVENT: &str = "confirmed the voucher";

/// Capture `decdn_client` events on THIS thread until the guard drops.
///
/// Thread-local by design: `drive` is awaited inline on the test's thread and
/// spawns nothing on the buyer side, so every recovery event lands here. Only the
/// upstream's serve tasks run elsewhere, and they are not asserted on.
fn capture_client_events() -> (
    tracing::subscriber::DefaultGuard,
    Arc<std::sync::Mutex<Vec<u8>>>,
) {
    use tracing_subscriber::Layer as _;
    use tracing_subscriber::layer::SubscriberExt;
    use tracing_subscriber::util::SubscriberInitExt;
    let buf = Arc::new(std::sync::Mutex::new(Vec::new()));
    let sink = CapturedLogs(Arc::clone(&buf));
    let guard = tracing_subscriber::registry()
        .with(
            tracing_subscriber::fmt::layer()
                .with_writer(move || sink.clone())
                .with_ansi(false)
                .with_filter(
                    tracing_subscriber::filter::Targets::new()
                        .with_target("decdn_client", tracing::Level::DEBUG),
                ),
        )
        .set_default();
    (guard, buf)
}

/// Run the production gap-driven fetch — `drive` over a `PeerSource` into a
/// `ClientRangedStore` — against a [`spawn_stop_send_server_counting`] upstream
/// serving `payload`, wired as `decdn get` wires it. The upstream accepts up to
/// three connections so a buyer that re-opens the gap fails fast instead of hanging.
async fn drive_against_stop_send_server(
    payload: Vec<u8>,
    stop: StopPoint,
    signal: StopThenSignal,
) -> anyhow::Result<StopSendDrive> {
    use decdn_client::driver::drive;
    use decdn_client::{BudgetPacer, ClientRangedStore, PeerSource};
    use std::sync::atomic::{AtomicUsize, Ordering};

    let hash = Hash::new(&payload);
    let total_bytes = u64::try_from(payload.len())?;

    let server_sk = fresh_key();
    let server_id = server_sk.public();
    let server_eth = Arc::new(PrivateKeySigner::random());
    let (server_ep, server_addr) = local_endpoint(server_sk, vec![ALPN_CLIENT.to_vec()]).await?;
    let accepted = Arc::new(AtomicUsize::new(0));
    let server_task = spawn_stop_send_server_counting(
        server_ep.clone(),
        Arc::clone(&server_eth),
        slash_domain(),
        payload,
        stop,
        signal,
        3,
        Arc::clone(&accepted),
    );
    let target = EndpointAddr::new(server_id).with_ip_addr(server_addr);

    let (client_ep, _) = local_endpoint(fresh_key(), vec![]).await?;
    let ctx = pool_context(
        &client_ep,
        Arc::new(PrivateKeySigner::random()),
        U256::from(10_000_000u64),
    );
    let ledger = Arc::new(ctx.new_ledger());
    let ctx = Arc::new(std::sync::Mutex::new(ctx));
    let store_dir = tempfile::tempdir()?;
    let store = ClientRangedStore::create(store_dir.path(), "blob", *hash.as_bytes(), total_bytes)?;
    let slash = slash_domain();
    let source = PeerSource::new(
        &client_ep,
        target,
        Arc::clone(&ctx),
        Arc::clone(&ledger),
        &slash,
        server_eth.address(),
        decdn_protocol::client::NO_NAMESPACE,
        0,
        u64::MAX,
        PullDeadlines::new(Duration::from_secs(10), Duration::from_secs(10), 0)?,
        None,
    );
    let pacer = BudgetPacer::new();
    let (log_guard, log_buf) = capture_client_events();
    let result = drive(
        &store,
        &source,
        &pacer,
        &ctx,
        &ledger,
        *hash.as_bytes(),
        0,
        0,
        None,
        None,
        None,
        None,
    )
    .await;
    drop(log_guard);
    let logs = String::from_utf8_lossy(
        &log_buf
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner),
    )
    .into_owned();
    drop(source);
    let promoted = std::fs::read(store_dir.path().join("blob")).ok();

    shutdown([server_task], [&client_ep, &server_ep]).await?;
    Ok(StopSendDrive {
        result,
        ledger,
        accepted: accepted.load(Ordering::SeqCst),
        promoted,
        logs,
    })
}

/// A drive that completed on the one connection, with the closing voucher
/// COMMITTED (not merely armed) by the write-failure recovery and exactly one
/// honest wire billed.
fn ensure_one_leg_fully_paid(d: &StopSendDrive, payload: &[u8]) -> anyhow::Result<()> {
    let wire = honest_bao_wire(payload)?;
    anyhow::ensure!(
        d.logs.contains(CONFIRMED_EVENT),
        "the closing-voucher write must fail and the recovery must confirm it; captured \
         events:\n{}",
        d.logs
    );
    anyhow::ensure!(
        d.promoted.as_deref() == Some(payload),
        "the drive must finalize the whole blob into the ranged store"
    );
    anyhow::ensure!(
        d.accepted == 1,
        "the fetch must complete on one connection, dialled {}",
        d.accepted
    );
    let committed = d.ledger.committed();
    anyhow::ensure!(
        committed == d.ledger.settlement(),
        "the closing voucher must be committed, not merely armed: committed {committed:?} vs \
         settlement {:?}",
        d.ledger.settlement()
    );
    anyhow::ensure!(
        committed.bytes == U256::from(wire.len()),
        "exactly the one honest wire is billed, got {} for a {}-byte wire",
        committed.bytes,
        wire.len()
    );
    Ok(())
}

/// The same closing-voucher peer-stop on the PRODUCTION gap-driven path, where
/// completion is payment-based (`fill_gap` reads `ledger.committed()`), not
/// decoder-based. An honest node writes `StreamEnd` only once every interval — the
/// closing voucher included — is credited, so the recovery confirms the voucher whose
/// write failed. This upstream never reads that voucher; its `StreamEnd` stands in
/// for the honest guarantee. The leg is paid through its end, the fetch finalizes on
/// that ONE connection, and nothing is re-pulled or re-billed.
#[tokio::test(flavor = "multi_thread")]
async fn drive_completes_in_one_leg_when_its_send_is_stopped_before_the_closing_voucher()
-> anyhow::Result<()> {
    // Under one chunk, so the buyer owes exactly one closing voucher.
    let payload = vec![0x5Au8; 256 * 1024];
    let mut d =
        drive_against_stop_send_server(payload.clone(), StopPoint::BeforeData, StopThenSignal::End)
            .await?;
    std::mem::replace(&mut d.result, Ok(()))?;
    ensure_one_leg_fully_paid(&d, &payload)
}

/// The multi-chunk twin: the reveals for the whole chunks commit as they go, and
/// the residual's closing voucher — the one write the peer-stop fails — folds them
/// (rolling the chain). The recovery must confirm THAT voucher too, or the paid
/// frontier stops short of the gap end and the tail is re-pulled and re-billed.
#[tokio::test(flavor = "multi_thread")]
async fn drive_completes_in_one_leg_after_reveals_when_its_send_is_stopped_before_the_closing_voucher()
-> anyhow::Result<()> {
    let payload = vec![0x5Bu8; 3 * usize::try_from(CHUNK_BYTES)? / 2];
    let mut d = drive_against_stop_send_server(
        payload.clone(),
        StopPoint::AfterFirstReveal,
        StopThenSignal::End,
    )
    .await?;
    std::mem::replace(&mut d.result, Ok(()))?;
    ensure_one_leg_fully_paid(&d, &payload)
}

/// The typed-rejection twin on the gap-driven path: a `VoucherRejected` read in
/// place of the failed write surfaces as [`UpstreamVoucherRejected`] out of `drive`
/// on the one connection — never rescued into a completion, never re-legged (no
/// bundle to reseed from, and the deposit covers the next voucher so the refusal is
/// not a genuine exhaustion) — and confirms nothing on the ledger.
#[tokio::test(flavor = "multi_thread")]
async fn drive_surfaces_typed_rejection_when_its_send_is_stopped_before_the_closing_voucher()
-> anyhow::Result<()> {
    let payload = vec![0x5Au8; 256 * 1024];
    let d = drive_against_stop_send_server(
        payload,
        StopPoint::BeforeData,
        StopThenSignal::Reject(VoucherRejectReason::SpendingCapExhausted),
    )
    .await?;
    let err = d
        .result
        .err()
        .ok_or_else(|| anyhow::anyhow!("a rejected drive must fail"))?;
    anyhow::ensure!(
        err.downcast_ref::<UpstreamVoucherRejected>().is_some(),
        "the drive must surface the typed UpstreamVoucherRejected, got: {err:#}"
    );
    anyhow::ensure!(
        d.accepted == 1,
        "a rejection must not re-leg, dialled {}",
        d.accepted
    );
    anyhow::ensure!(
        d.promoted.is_none(),
        "a rejected drive must not promote the blob"
    );
    anyhow::ensure!(
        d.ledger.committed() == Cumulative::default(),
        "a rejection confirms nothing: committed {:?}",
        d.ledger.committed()
    );
    anyhow::ensure!(
        !d.logs.contains(CONFIRMED_EVENT),
        "a rejection confirms nothing; captured events:\n{}",
        d.logs
    );
    Ok(())
}