freenet_stdlib/client_api/

client_events.rs

use bytes::Bytes;
use flatbuffers::WIPOffset;
use std::borrow::Cow;
use std::fmt::Display;
use std::net::SocketAddr;

use serde::{de::DeserializeOwned, Deserialize, Serialize};

use crate::client_api::TryFromFbs;
use crate::generated::client_request::{
    root_as_client_request, ClientRequestType, ContractRequest as FbsContractRequest,
    ContractRequestType, DelegateRequest as FbsDelegateRequest, DelegateRequestType,
};

use crate::generated::common::{
    ApplicationMessage as FbsApplicationMessage, ApplicationMessageArgs, ContractCode,
    ContractCodeArgs, ContractContainer as FbsContractContainer, ContractContainerArgs,
    ContractInstanceId as FbsContractInstanceId, ContractInstanceIdArgs,
    ContractKey as FbsContractKey, ContractKeyArgs, ContractType, DeltaUpdate, DeltaUpdateArgs,
    RelatedDeltaUpdate, RelatedDeltaUpdateArgs, RelatedStateAndDeltaUpdate,
    RelatedStateAndDeltaUpdateArgs, RelatedStateUpdate, RelatedStateUpdateArgs,
    StateAndDeltaUpdate, StateAndDeltaUpdateArgs, StateUpdate, StateUpdateArgs,
    UpdateData as FbsUpdateData, UpdateDataArgs, UpdateDataType, WasmContractV1,
    WasmContractV1Args,
};
use crate::generated::host_response::{
    finish_host_response_buffer, ClientResponse as FbsClientResponse, ClientResponseArgs,
    ContextUpdated as FbsContextUpdated, ContextUpdatedArgs,
    ContractResponse as FbsContractResponse, ContractResponseArgs, ContractResponseType,
    DelegateKey as FbsDelegateKey, DelegateKeyArgs, DelegateResponse as FbsDelegateResponse,
    DelegateResponseArgs, GetResponse as FbsGetResponse, GetResponseArgs,
    HostResponse as FbsHostResponse, HostResponseArgs, HostResponseType, NotFound as FbsNotFound,
    NotFoundArgs, Ok as FbsOk, OkArgs, OutboundDelegateMsg as FbsOutboundDelegateMsg,
    OutboundDelegateMsgArgs, OutboundDelegateMsgType, PutResponse as FbsPutResponse,
    PutResponseArgs, RequestUserInput as FbsRequestUserInput, RequestUserInputArgs,
    StreamChunk as FbsHostStreamChunk, StreamChunkArgs as FbsHostStreamChunkArgs,
    UpdateNotification as FbsUpdateNotification, UpdateNotificationArgs,
    UpdateResponse as FbsUpdateResponse, UpdateResponseArgs,
};
use crate::prelude::ContractContainer::Wasm;
use crate::prelude::ContractWasmAPIVersion::V1;
use crate::prelude::UpdateData::{
    Delta, RelatedDelta, RelatedState, RelatedStateAndDelta, State, StateAndDelta,
};
use crate::{
    delegate_interface::{DelegateKey, InboundDelegateMsg, OutboundDelegateMsg},
    prelude::{
        ContractInstanceId, ContractKey, DelegateContainer, Parameters, RelatedContracts,
        SecretsId, StateSummary, UpdateData, WrappedState,
    },
    versioning::ContractContainer,
};

use super::WsApiError;

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ClientError {
    kind: Box<ErrorKind>,
}

impl ClientError {
    pub fn into_fbs_bytes(self) -> Result<Vec<u8>, Box<ClientError>> {
        use crate::generated::host_response::{Error, ErrorArgs};
        let mut builder = flatbuffers::FlatBufferBuilder::new();
        let msg_offset = builder.create_string(&self.to_string());
        let err_offset = Error::create(
            &mut builder,
            &ErrorArgs {
                msg: Some(msg_offset),
            },
        );
        let host_response_offset = FbsHostResponse::create(
            &mut builder,
            &HostResponseArgs {
                response_type: HostResponseType::Ok,
                response: Some(err_offset.as_union_value()),
            },
        );
        finish_host_response_buffer(&mut builder, host_response_offset);
        Ok(builder.finished_data().to_vec())
    }

    pub fn kind(&self) -> &ErrorKind {
        &self.kind
    }
}

impl From<ErrorKind> for ClientError {
    fn from(kind: ErrorKind) -> Self {
        ClientError {
            kind: Box::new(kind),
        }
    }
}

impl<T: Into<Cow<'static, str>>> From<T> for ClientError {
    fn from(cause: T) -> Self {
        ClientError {
            kind: Box::new(ErrorKind::Unhandled {
                cause: cause.into(),
            }),
        }
    }
}

#[derive(thiserror::Error, Debug, Serialize, Deserialize, Clone)]
#[non_exhaustive]
pub enum ErrorKind {
    #[error("comm channel between client/host closed")]
    ChannelClosed,
    #[error("error while deserializing: {cause}")]
    DeserializationError { cause: Cow<'static, str> },
    #[error("client disconnected")]
    Disconnect,
    #[error("failed while trying to unpack state for {0}")]
    IncorrectState(ContractKey),
    #[error("node not available")]
    NodeUnavailable,
    #[error("lost the connection with the protocol handling connections")]
    TransportProtocolDisconnect,
    #[error("unhandled error: {cause}")]
    Unhandled { cause: Cow<'static, str> },
    #[error("unknown client id: {0}")]
    UnknownClient(usize),
    #[error(transparent)]
    RequestError(#[from] RequestError),
    #[error("error while executing operation in the network: {cause}")]
    OperationError { cause: Cow<'static, str> },
    // TODO: identify requests by some id so we can inform clients which one failed exactly
    #[error("operation timed out")]
    FailedOperation,
    #[error("peer should shutdown")]
    Shutdown,
    #[error("no ring connections found")]
    EmptyRing,
    #[error("peer has not joined the network yet")]
    PeerNotJoined,
}

impl Display for ClientError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "client error: {}", self.kind)
    }
}

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

#[derive(Debug, thiserror::Error, Serialize, Deserialize, Clone)]
#[non_exhaustive]
pub enum RequestError {
    #[error(transparent)]
    ContractError(#[from] ContractError),
    #[error(transparent)]
    DelegateError(#[from] DelegateError),
    #[error("client disconnect")]
    Disconnect,
    #[error("operation timed out")]
    Timeout,
}

/// Errors that may happen while interacting with delegates.
#[derive(Debug, thiserror::Error, Serialize, Deserialize, Clone)]
#[non_exhaustive]
pub enum DelegateError {
    #[error("error while registering delegate {0}")]
    RegisterError(DelegateKey),
    #[error("execution error, cause {0}")]
    ExecutionError(Cow<'static, str>),
    #[error("missing delegate {0}")]
    Missing(DelegateKey),
    #[error("missing secret `{secret}` for delegate {key}")]
    MissingSecret { key: DelegateKey, secret: SecretsId },
    #[error("forbidden access to secret: {0}")]
    ForbiddenSecretAccess(SecretsId),
}

/// Errors that may happen while interacting with contracts.
#[derive(Debug, thiserror::Error, Serialize, Deserialize, Clone)]
#[non_exhaustive]
pub enum ContractError {
    #[error("failed to get contract {key}, reason: {cause}")]
    Get {
        key: ContractKey,
        cause: Cow<'static, str>,
    },
    #[error("put error for contract {key}, reason: {cause}")]
    Put {
        key: ContractKey,
        cause: Cow<'static, str>,
    },
    #[error("update error for contract {key}, reason: {cause}")]
    Update {
        key: ContractKey,
        cause: Cow<'static, str>,
    },
    #[error("failed to subscribe for contract {key}, reason: {cause}")]
    Subscribe {
        key: ContractKey,
        cause: Cow<'static, str>,
    },
    // todo: actually build a stack of the involved keys
    #[error("dependency contract stack overflow : {key}")]
    ContractStackOverflow {
        key: crate::contract_interface::ContractInstanceId,
    },
    #[error("missing related contract: {key}")]
    MissingRelated {
        key: crate::contract_interface::ContractInstanceId,
    },
    #[error("missing contract: {key}")]
    MissingContract {
        key: crate::contract_interface::ContractInstanceId,
    },
}

impl ContractError {
    const EXECUTION_ERROR: &'static str = "execution error";
    const INVALID_PUT: &'static str = "invalid put";

    pub fn update_exec_error(key: ContractKey, additional_info: impl std::fmt::Display) -> Self {
        Self::Update {
            key,
            cause: format!(
                "{exec_err}: {additional_info}",
                exec_err = Self::EXECUTION_ERROR
            )
            .into(),
        }
    }

    pub fn invalid_put(key: ContractKey) -> Self {
        Self::Put {
            key,
            cause: Self::INVALID_PUT.into(),
        }
    }

    pub fn invalid_update(key: ContractKey) -> Self {
        Self::Update {
            key,
            cause: Self::INVALID_PUT.into(),
        }
    }
}

/// A request from a client application to the host.
#[derive(Serialize, Deserialize, Debug, Clone)]
#[non_exhaustive]
// #[cfg_attr(test, derive(arbitrary::Arbitrary))]
pub enum ClientRequest<'a> {
    DelegateOp(#[serde(borrow)] DelegateRequest<'a>),
    ContractOp(#[serde(borrow)] ContractRequest<'a>),
    Disconnect {
        cause: Option<Cow<'static, str>>,
    },
    Authenticate {
        token: String,
    },
    NodeQueries(NodeQuery),
    /// Gracefully disconnect from the host.
    Close,
    /// A chunk of a larger streamed message.
    StreamChunk {
        stream_id: u32,
        index: u32,
        total: u32,
        data: Bytes,
    },
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ConnectedPeers {}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct NodeDiagnostics {
    /// Optional contract key to filter diagnostics for specific contract
    pub contract_key: Option<ContractKey>,
}

impl ClientRequest<'_> {
    pub fn into_owned(self) -> ClientRequest<'static> {
        match self {
            ClientRequest::ContractOp(op) => {
                let owned = match op {
                    ContractRequest::Put {
                        contract,
                        state,
                        related_contracts,
                        subscribe,
                        blocking_subscribe,
                    } => {
                        let related_contracts = related_contracts.into_owned();
                        ContractRequest::Put {
                            contract,
                            state,
                            related_contracts,
                            subscribe,
                            blocking_subscribe,
                        }
                    }
                    ContractRequest::Update { key, data } => {
                        let data = data.into_owned();
                        ContractRequest::Update { key, data }
                    }
                    ContractRequest::Get {
                        key,
                        return_contract_code,
                        subscribe,
                        blocking_subscribe,
                    } => ContractRequest::Get {
                        key,
                        return_contract_code,
                        subscribe,
                        blocking_subscribe,
                    },
                    ContractRequest::Subscribe { key, summary } => ContractRequest::Subscribe {
                        key,
                        summary: summary.map(StateSummary::into_owned),
                    },
                };
                owned.into()
            }
            ClientRequest::DelegateOp(op) => {
                let op = op.into_owned();
                ClientRequest::DelegateOp(op)
            }
            ClientRequest::Disconnect { cause } => ClientRequest::Disconnect { cause },
            ClientRequest::Authenticate { token } => ClientRequest::Authenticate { token },
            ClientRequest::NodeQueries(query) => ClientRequest::NodeQueries(query),
            ClientRequest::Close => ClientRequest::Close,
            ClientRequest::StreamChunk {
                stream_id,
                index,
                total,
                data,
            } => ClientRequest::StreamChunk {
                stream_id,
                index,
                total,
                data,
            },
        }
    }

    pub fn is_disconnect(&self) -> bool {
        matches!(self, Self::Disconnect { .. })
    }

    pub fn try_decode_fbs(msg: &[u8]) -> Result<ClientRequest<'_>, WsApiError> {
        let req = {
            match root_as_client_request(msg) {
                Ok(client_request) => match client_request.client_request_type() {
                    ClientRequestType::ContractRequest => {
                        let contract_request =
                            client_request.client_request_as_contract_request().unwrap();
                        ContractRequest::try_decode_fbs(&contract_request)?.into()
                    }
                    ClientRequestType::DelegateRequest => {
                        let delegate_request =
                            client_request.client_request_as_delegate_request().unwrap();
                        DelegateRequest::try_decode_fbs(&delegate_request)?.into()
                    }
                    ClientRequestType::Disconnect => {
                        let delegate_request =
                            client_request.client_request_as_disconnect().unwrap();
                        let cause = delegate_request
                            .cause()
                            .map(|cause_msg| cause_msg.to_string().into());
                        ClientRequest::Disconnect { cause }
                    }
                    ClientRequestType::Authenticate => {
                        let auth_req = client_request.client_request_as_authenticate().unwrap();
                        let token = auth_req.token();
                        ClientRequest::Authenticate {
                            token: token.to_owned(),
                        }
                    }
                    ClientRequestType::StreamChunk => {
                        let chunk = client_request.client_request_as_stream_chunk().unwrap();
                        ClientRequest::StreamChunk {
                            stream_id: chunk.stream_id(),
                            index: chunk.index(),
                            total: chunk.total(),
                            data: Bytes::from(chunk.data().bytes().to_vec()),
                        }
                    }
                    other => {
                        return Err(crate::client_api::unknown_union_discriminant(
                            "ClientRequestType",
                            other.0,
                        ))
                    }
                },
                Err(e) => {
                    let cause = format!("{e}");
                    return Err(WsApiError::deserialization(cause));
                }
            }
        };

        Ok(req)
    }
}

#[derive(Clone, Serialize, Deserialize, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum ContractRequest<'a> {
    /// Insert a new value in a contract corresponding with the provided key.
    Put {
        contract: ContractContainer,
        /// Value to upsert in the contract.
        state: WrappedState,
        /// Related contracts.
        #[serde(borrow)]
        related_contracts: RelatedContracts<'a>,
        /// If this flag is set then subscribe to updates for this contract.
        subscribe: bool,
        /// If true, the PUT response waits for the subscription to complete.
        /// Only meaningful when `subscribe` is true.
        #[serde(default)]
        blocking_subscribe: bool,
    },
    /// Update an existing contract corresponding with the provided key.
    Update {
        key: ContractKey,
        #[serde(borrow)]
        data: UpdateData<'a>,
    },
    /// Fetch the current state from a contract corresponding to the provided key.
    Get {
        /// Instance ID of the contract (the hash of code + params).
        /// Only the instance ID is needed since the client doesn't have the code hash yet.
        key: ContractInstanceId,
        /// If this flag is set then fetch also the contract itself.
        return_contract_code: bool,
        /// If this flag is set then subscribe to updates for this contract.
        subscribe: bool,
        /// If true, the GET response waits for the subscription to complete.
        /// Only meaningful when `subscribe` is true.
        #[serde(default)]
        blocking_subscribe: bool,
    },
    /// Subscribe to the changes in a given contract. Implicitly starts a get operation
    /// if the contract is not present yet.
    Subscribe {
        /// Instance ID of the contract.
        key: ContractInstanceId,
        summary: Option<StateSummary<'a>>,
    },
}

impl ContractRequest<'_> {
    pub fn into_owned(self) -> ContractRequest<'static> {
        match self {
            Self::Put {
                contract,
                state,
                related_contracts,
                subscribe,
                blocking_subscribe,
            } => ContractRequest::Put {
                contract,
                state,
                related_contracts: related_contracts.into_owned(),
                subscribe,
                blocking_subscribe,
            },
            Self::Update { key, data } => ContractRequest::Update {
                key,
                data: data.into_owned(),
            },
            Self::Get {
                key,
                return_contract_code: fetch_contract,
                subscribe,
                blocking_subscribe,
            } => ContractRequest::Get {
                key,
                return_contract_code: fetch_contract,
                subscribe,
                blocking_subscribe,
            },
            Self::Subscribe { key, summary } => ContractRequest::Subscribe {
                key,
                summary: summary.map(StateSummary::into_owned),
            },
        }
    }
}

impl<'a> From<ContractRequest<'a>> for ClientRequest<'a> {
    fn from(op: ContractRequest<'a>) -> Self {
        ClientRequest::ContractOp(op)
    }
}

/// Deserializes a `ContractRequest` from a Flatbuffers message.
impl<'a> TryFromFbs<&FbsContractRequest<'a>> for ContractRequest<'a> {
    fn try_decode_fbs(request: &FbsContractRequest<'a>) -> Result<Self, WsApiError> {
        let req = {
            match request.contract_request_type() {
                ContractRequestType::Get => {
                    let get = request.contract_request_as_get().unwrap();
                    // Extract just the instance ID - GET only needs the instance ID,
                    // not the full key (which may not be complete on the client side)
                    let fbs_key = get.key();
                    let key = crate::contract_interface::key::instance_id_from_fbs(
                        "ContractKey.instance.data",
                        fbs_key.instance().data().bytes(),
                    )?;
                    let fetch_contract = get.fetch_contract();
                    let subscribe = get.subscribe();
                    let blocking_subscribe = get.blocking_subscribe();
                    ContractRequest::Get {
                        key,
                        return_contract_code: fetch_contract,
                        subscribe,
                        blocking_subscribe,
                    }
                }
                ContractRequestType::Put => {
                    let put = request.contract_request_as_put().unwrap();
                    let contract = ContractContainer::try_decode_fbs(&put.container())?;
                    let state = WrappedState::new(put.wrapped_state().bytes().to_vec());
                    let related_contracts =
                        RelatedContracts::try_decode_fbs(&put.related_contracts())?.into_owned();
                    let subscribe = put.subscribe();
                    let blocking_subscribe = put.blocking_subscribe();
                    ContractRequest::Put {
                        contract,
                        state,
                        related_contracts,
                        subscribe,
                        blocking_subscribe,
                    }
                }
                ContractRequestType::Update => {
                    let update = request.contract_request_as_update().unwrap();
                    let key = ContractKey::try_decode_fbs(&update.key())?;
                    let data = UpdateData::try_decode_fbs(&update.data())?.into_owned();
                    ContractRequest::Update { key, data }
                }
                ContractRequestType::Subscribe => {
                    let subscribe = request.contract_request_as_subscribe().unwrap();
                    // Extract just the instance ID for Subscribe
                    let fbs_key = subscribe.key();
                    let key = crate::contract_interface::key::instance_id_from_fbs(
                        "ContractKey.instance.data",
                        fbs_key.instance().data().bytes(),
                    )?;
                    let summary = subscribe
                        .summary()
                        .map(|summary_data| StateSummary::from(summary_data.bytes()));
                    ContractRequest::Subscribe { key, summary }
                }
                // Reachable, not `unreachable!()`: the generated flatbuffers
                // verifier accepts any unknown union discriminant (`_ => Ok(())`)
                // and the union type field is a raw `u8` a client can set freely,
                // so a crafted request reaches here. Return a per-request error
                // instead of panicking the connection handler. (Mirrors the same
                // fix on `DelegateRequest::try_decode_fbs`.)
                other => {
                    return Err(crate::client_api::unknown_union_discriminant(
                        "ContractRequestType",
                        other.0,
                    ));
                }
            }
        };

        Ok(req)
    }
}

impl<'a> From<DelegateRequest<'a>> for ClientRequest<'a> {
    fn from(op: DelegateRequest<'a>) -> Self {
        ClientRequest::DelegateOp(op)
    }
}

#[derive(Serialize, Deserialize, Debug, Clone)]
#[non_exhaustive]
pub enum DelegateRequest<'a> {
    ApplicationMessages {
        key: DelegateKey,
        #[serde(deserialize_with = "Parameters::deser_params")]
        params: Parameters<'a>,
        #[serde(borrow)]
        inbound: Vec<InboundDelegateMsg<'a>>,
    },
    RegisterDelegate {
        delegate: DelegateContainer,
        cipher: [u8; 32],
        nonce: [u8; 24],
    },
    UnregisterDelegate(DelegateKey),
    /// Registers a delegate AND requests a one-shot, node-side copy-forward of
    /// the LOCAL-scope secrets belonging to `predecessors` into the newly
    /// registered delegate's own secret namespace.
    ///
    /// `predecessors` are the delegate keys of retired generations of this
    /// delegate. It is a **list** because a user may skip one or more
    /// generations between the version they last ran and the current one, so
    /// several prior namespaces can need forwarding in a single registration.
    /// The copy-forward is:
    ///   - **consent-gated on the client side** — the node performs NO
    ///     execution of any old delegate WASM; it only copies the
    ///     already-sealed LOCAL-scope secret bytes it holds for a predecessor
    ///     into the successor's namespace,
    ///   - **best-effort over unknown predecessors** — the server silently
    ///     ignores any predecessor key it does not hold, and
    ///   - **idempotent per `(predecessor -> successor)` pair** —
    ///     re-registering with the same predecessors copies nothing new.
    ///
    /// `cipher` and `nonce` mirror [`DelegateRequest::RegisterDelegate`] purely
    /// for field-shape parity. The node has ignored both since
    /// freenet-core#4140 (secrets are sealed client-side), so they carry no
    /// behavior here either; they exist only so the two registration variants
    /// stay structurally identical.
    RegisterDelegateWithPredecessors {
        delegate: DelegateContainer,
        cipher: [u8; 32],
        nonce: [u8; 24],
        predecessors: Vec<DelegateKey>,
    },
}

impl DelegateRequest<'_> {
    pub fn into_owned(self) -> DelegateRequest<'static> {
        match self {
            DelegateRequest::ApplicationMessages {
                key,
                inbound,
                params,
            } => DelegateRequest::ApplicationMessages {
                key,
                params: params.into_owned(),
                inbound: inbound.into_iter().map(|e| e.into_owned()).collect(),
            },
            DelegateRequest::RegisterDelegate {
                delegate,
                cipher,
                nonce,
            } => DelegateRequest::RegisterDelegate {
                delegate,
                cipher,
                nonce,
            },
            DelegateRequest::UnregisterDelegate(key) => DelegateRequest::UnregisterDelegate(key),
            DelegateRequest::RegisterDelegateWithPredecessors {
                delegate,
                cipher,
                nonce,
                predecessors,
            } => DelegateRequest::RegisterDelegateWithPredecessors {
                delegate,
                cipher,
                nonce,
                predecessors,
            },
        }
    }

    pub fn key(&self) -> &DelegateKey {
        match self {
            DelegateRequest::ApplicationMessages { key, .. } => key,
            DelegateRequest::RegisterDelegate { delegate, .. } => delegate.key(),
            DelegateRequest::UnregisterDelegate(key) => key,
            DelegateRequest::RegisterDelegateWithPredecessors { delegate, .. } => delegate.key(),
        }
    }
}

impl Display for ClientRequest<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ClientRequest::ContractOp(op) => match op {
                ContractRequest::Put {
                    contract, state, ..
                } => {
                    write!(
                        f,
                        "ContractRequest::Put for contract `{contract}` with state {state}"
                    )
                }
                ContractRequest::Update { key, .. } => write!(f, "update request for {key}"),
                ContractRequest::Get {
                    key,
                    return_contract_code: contract,
                    ..
                } => {
                    write!(
                        f,
                        "ContractRequest::Get for key `{key}` (fetch full contract: {contract})"
                    )
                }
                ContractRequest::Subscribe { key, .. } => {
                    write!(f, "ContractRequest::Subscribe for `{key}`")
                }
            },
            ClientRequest::DelegateOp(op) => match op {
                DelegateRequest::ApplicationMessages { key, inbound, .. } => {
                    write!(
                        f,
                        "DelegateRequest::ApplicationMessages for `{key}` with {} messages",
                        inbound.len()
                    )
                }
                DelegateRequest::RegisterDelegate { delegate, .. } => {
                    write!(
                        f,
                        "DelegateRequest::RegisterDelegate for delegate.key()=`{}`",
                        delegate.key()
                    )
                }
                DelegateRequest::UnregisterDelegate(key) => {
                    write!(f, "DelegateRequest::UnregisterDelegate for key `{key}`")
                }
                DelegateRequest::RegisterDelegateWithPredecessors {
                    delegate,
                    predecessors,
                    ..
                } => {
                    write!(
                        f,
                        "DelegateRequest::RegisterDelegateWithPredecessors for delegate.key()=`{}` with {} predecessor(s)",
                        delegate.key(),
                        predecessors.len()
                    )
                }
            },
            ClientRequest::Disconnect { .. } => write!(f, "client disconnected"),
            ClientRequest::Authenticate { .. } => write!(f, "authenticate"),
            ClientRequest::NodeQueries(query) => write!(f, "node queries: {:?}", query),
            ClientRequest::Close => write!(f, "close"),
            ClientRequest::StreamChunk {
                stream_id,
                index,
                total,
                ..
            } => write!(f, "stream chunk {index}/{total} (stream {stream_id})"),
        }
    }
}

/// Deserializes a `DelegateRequest` from a Flatbuffers message.
impl<'a> TryFromFbs<&FbsDelegateRequest<'a>> for DelegateRequest<'a> {
    fn try_decode_fbs(request: &FbsDelegateRequest<'a>) -> Result<Self, WsApiError> {
        let req = {
            match request.delegate_request_type() {
                DelegateRequestType::ApplicationMessages => {
                    let app_msg = request.delegate_request_as_application_messages().unwrap();
                    let key = DelegateKey::try_decode_fbs(&app_msg.key())?;
                    let params = Parameters::from(app_msg.params().bytes());
                    let inbound = app_msg
                        .inbound()
                        .iter()
                        .map(|msg| InboundDelegateMsg::try_decode_fbs(&msg))
                        .collect::<Result<Vec<_>, _>>()?;
                    DelegateRequest::ApplicationMessages {
                        key,
                        params,
                        inbound,
                    }
                }
                DelegateRequestType::RegisterDelegate => {
                    let register = request.delegate_request_as_register_delegate().unwrap();
                    let delegate = DelegateContainer::try_decode_fbs(&register.delegate())?;
                    // `cipher` and `nonce` are `(required)`, which the verifier
                    // reads as "present", not "32 and 24 bytes". The
                    // `try_from(..).unwrap()` this replaces panicked on any
                    // other length, killing the connection task. (The
                    // intermediate `.to_vec()` went with it: `bytes()` is
                    // already a slice.)
                    let cipher = crate::client_api::fixed_size_field::<32>(
                        "RegisterDelegate.cipher",
                        register.cipher().bytes(),
                    )?;
                    let nonce = crate::client_api::fixed_size_field::<24>(
                        "RegisterDelegate.nonce",
                        register.nonce().bytes(),
                    )?;
                    DelegateRequest::RegisterDelegate {
                        delegate,
                        cipher,
                        nonce,
                    }
                }
                DelegateRequestType::UnregisterDelegate => {
                    let unregister = request.delegate_request_as_unregister_delegate().unwrap();
                    let key = DelegateKey::try_decode_fbs(&unregister.key())?;
                    DelegateRequest::UnregisterDelegate(key)
                }
                // An unknown union discriminant is reachable, not `unreachable!()`:
                // the generated flatbuffers verifier accepts any discriminant it
                // doesn't recognize (`_ => Ok(())`), and the union type field is a
                // raw `u8` the (public) TS builder can set to any value. Panicking
                // here would let a single crafted request take down the connection
                // handler, so return a per-request error instead.
                other => {
                    return Err(crate::client_api::unknown_union_discriminant(
                        "DelegateRequestType",
                        other.0,
                    ));
                }
            }
        };

        Ok(req)
    }
}

/// A response to a previous [`ClientRequest`]
#[derive(Serialize, Deserialize, Debug, Clone)]
#[non_exhaustive]
pub enum HostResponse<T = WrappedState> {
    ContractResponse(#[serde(bound(deserialize = "T: DeserializeOwned"))] ContractResponse<T>),
    DelegateResponse {
        key: DelegateKey,
        values: Vec<OutboundDelegateMsg>,
    },
    QueryResponse(QueryResponse),
    /// A requested action which doesn't require an answer was performed successfully.
    Ok,
    /// A chunk of a larger streamed response.
    StreamChunk {
        stream_id: u32,
        index: u32,
        total: u32,
        data: Bytes,
    },
    /// Header message announcing the start of a streamed response.
    /// Sent before the corresponding [`StreamChunk`] messages so the client
    /// can set up incremental consumption via [`WsStreamHandle`].
    StreamHeader {
        stream_id: u32,
        total_bytes: u64,
        content: StreamContent,
    },
}

/// Describes what kind of response is being streamed.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub enum StreamContent {
    /// A streamed GetResponse — the large state is delivered via StreamChunks.
    GetResponse {
        key: ContractKey,
        includes_contract: bool,
    },
    /// Raw binary stream (future use).
    Raw,
}

type Peer = String;

#[derive(Serialize, Deserialize, Debug, Clone)]
pub enum QueryResponse {
    ConnectedPeers { peers: Vec<(Peer, SocketAddr)> },
    NetworkDebug(NetworkDebugInfo),
    NodeDiagnostics(NodeDiagnosticsResponse),
    NeighborHosting(NeighborHostingInfo),
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct NetworkDebugInfo {
    pub subscriptions: Vec<SubscriptionInfo>,
    pub connected_peers: Vec<(String, SocketAddr)>,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct NodeDiagnosticsResponse {
    /// Node information
    pub node_info: Option<NodeInfo>,

    /// Network connectivity information
    pub network_info: Option<NetworkInfo>,

    /// Contract subscription information
    pub subscriptions: Vec<SubscriptionInfo>,

    /// Contract states for specific contracts.
    ///
    /// Keys are the Base58-encoded contract id (i.e. `ContractKey::Display`),
    /// matching the convention every other field in this struct uses
    /// (`peer_id: String`, `connected_peers: Vec<(String, String)>`,
    /// `ContractHostingEntry::contract_key: String`). Pre-0.7 this was
    /// `HashMap<ContractKey, ContractState>`, which `serde_json` could not
    /// serialize because JSON object keys must be strings — every report
    /// from a node hosting at least one contract had its
    /// `network_status` silently dropped. See freenet/freenet-core#3987.
    pub contract_states: std::collections::HashMap<String, ContractState>,

    /// System metrics
    pub system_metrics: Option<SystemMetrics>,

    /// Information about connected peers with detailed data
    pub connected_peers_detailed: Vec<ConnectedPeerInfo>,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct NodeInfo {
    pub peer_id: String,
    pub is_gateway: bool,
    pub location: Option<String>,
    pub listening_address: Option<String>,
    pub uptime_seconds: u64,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct NetworkInfo {
    pub connected_peers: Vec<(String, String)>, // (peer_id, address)
    pub active_connections: usize,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ContractState {
    /// Number of nodes subscribed to this contract
    pub subscribers: u32,
    /// Peer IDs of nodes that are subscribed to this contract
    pub subscriber_peer_ids: Vec<String>,
    /// Size of the contract state in bytes
    #[serde(default)]
    pub size_bytes: u64,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct SystemMetrics {
    pub active_connections: u32,
    pub hosting_contracts: u32,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct SubscriptionInfo {
    pub contract_key: ContractInstanceId,
    pub client_id: usize,
}

/// Basic information about a connected peer
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ConnectedPeerInfo {
    pub peer_id: String,
    pub address: String,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub enum NodeQuery {
    ConnectedPeers,
    SubscriptionInfo,
    NodeDiagnostics {
        /// Diagnostic configuration specifying what information to collect
        config: NodeDiagnosticsConfig,
    },
    /// Query neighbor hosting information for update propagation
    NeighborHostingInfo,
}

/// Neighbor hosting information for update propagation
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct NeighborHostingInfo {
    /// Contracts this node is currently hosting
    pub my_hosted: Vec<ContractHostingEntry>,
    /// What we know about neighbor hosting
    pub neighbor_hosting: Vec<NeighborHostingDetail>,
    /// Hosting propagation statistics
    pub stats: HostingStats,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ContractHostingEntry {
    /// Full contract key as string
    pub contract_key: String,
    /// 32-bit hash for proximity matching
    pub hosting_hash: u32,
    /// When this contract was first hosted (Unix timestamp)
    pub hosted_since: u64,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct NeighborHostingDetail {
    /// Peer identifier
    pub peer_id: String,
    /// Contract hashes this neighbor is known to host
    pub known_contracts: Vec<u32>,
    /// Last update received from this neighbor (Unix timestamp)
    pub last_update: u64,
    /// Number of updates received from this neighbor
    pub update_count: u64,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct HostingStats {
    /// Number of hosting announcements sent
    pub hosting_announces_sent: u64,
    /// Number of hosting announcements received
    pub hosting_announces_received: u64,
    /// Updates forwarded via proximity (not subscription)
    pub updates_via_proximity: u64,
    /// Updates forwarded via subscription
    pub updates_via_subscription: u64,
    /// False positives due to hash collisions
    pub false_positive_forwards: u64,
    /// Average number of contracts per neighbor
    pub avg_neighbor_hosting_size: f32,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct NodeDiagnosticsConfig {
    /// Include basic node information (ID, location, uptime, etc.)
    pub include_node_info: bool,

    /// Include network connectivity information
    pub include_network_info: bool,

    /// Include contract subscription information
    pub include_subscriptions: bool,

    /// Include contract states for specific contracts (empty = all contracts)
    pub contract_keys: Vec<ContractKey>,

    /// Include memory and performance metrics
    pub include_system_metrics: bool,

    /// Include detailed information about connected peers (vs basic peer list)
    pub include_detailed_peer_info: bool,

    /// Include peer IDs of subscribers in contract state information
    pub include_subscriber_peer_ids: bool,
}

impl NodeDiagnosticsConfig {
    /// Create a comprehensive diagnostic config for debugging update propagation issues
    pub fn for_update_propagation_debugging(contract_key: ContractKey) -> Self {
        Self {
            include_node_info: true,
            include_network_info: true,
            include_subscriptions: true,
            contract_keys: vec![contract_key],
            include_system_metrics: true,
            include_detailed_peer_info: true,
            include_subscriber_peer_ids: true,
        }
    }

    /// Create a lightweight diagnostic config for basic node status
    pub fn basic_status() -> Self {
        Self {
            include_node_info: true,
            include_network_info: true,
            include_subscriptions: false,
            contract_keys: vec![],
            include_system_metrics: false,
            include_detailed_peer_info: false,
            include_subscriber_peer_ids: false,
        }
    }

    /// Create a full diagnostic config (all information)
    pub fn full() -> Self {
        Self {
            include_node_info: true,
            include_network_info: true,
            include_subscriptions: true,
            contract_keys: vec![], // empty = all contracts
            include_system_metrics: true,
            include_detailed_peer_info: true,
            include_subscriber_peer_ids: true,
        }
    }
}

impl HostResponse {
    pub fn unwrap_put(self) -> ContractKey {
        if let Self::ContractResponse(ContractResponse::PutResponse { key }) = self {
            key
        } else {
            panic!("called `HostResponse::unwrap_put()` on other than `PutResponse` value")
        }
    }

    pub fn unwrap_get(self) -> (WrappedState, Option<ContractContainer>) {
        if let Self::ContractResponse(ContractResponse::GetResponse {
            contract, state, ..
        }) = self
        {
            (state, contract)
        } else {
            panic!("called `HostResponse::unwrap_put()` on other than `PutResponse` value")
        }
    }

    pub fn into_fbs_bytes(self) -> Result<Vec<u8>, Box<ClientError>> {
        let mut builder = flatbuffers::FlatBufferBuilder::new();
        match self {
            HostResponse::ContractResponse(res) => match res {
                ContractResponse::PutResponse { key } => {
                    let instance_data = builder.create_vector(key.as_bytes());
                    let instance_offset = FbsContractInstanceId::create(
                        &mut builder,
                        &ContractInstanceIdArgs {
                            data: Some(instance_data),
                        },
                    );

                    let code = Some(builder.create_vector(&key.code_hash().0));
                    let key_offset = FbsContractKey::create(
                        &mut builder,
                        &ContractKeyArgs {
                            instance: Some(instance_offset),
                            code,
                        },
                    );

                    let put_offset = FbsPutResponse::create(
                        &mut builder,
                        &PutResponseArgs {
                            key: Some(key_offset),
                        },
                    );

                    let contract_response_offset = FbsContractResponse::create(
                        &mut builder,
                        &ContractResponseArgs {
                            contract_response: Some(put_offset.as_union_value()),
                            contract_response_type: ContractResponseType::PutResponse,
                        },
                    );

                    let response_offset = FbsHostResponse::create(
                        &mut builder,
                        &HostResponseArgs {
                            response: Some(contract_response_offset.as_union_value()),
                            response_type: HostResponseType::ContractResponse,
                        },
                    );

                    finish_host_response_buffer(&mut builder, response_offset);
                    Ok(builder.finished_data().to_vec())
                }
                ContractResponse::UpdateResponse { key, summary } => {
                    let instance_data = builder.create_vector(key.as_bytes());
                    let instance_offset = FbsContractInstanceId::create(
                        &mut builder,
                        &ContractInstanceIdArgs {
                            data: Some(instance_data),
                        },
                    );

                    let code = Some(builder.create_vector(&key.code_hash().0));

                    let key_offset = FbsContractKey::create(
                        &mut builder,
                        &ContractKeyArgs {
                            instance: Some(instance_offset),
                            code,
                        },
                    );

                    let summary_data = builder.create_vector(&summary.into_bytes());

                    let update_response_offset = FbsUpdateResponse::create(
                        &mut builder,
                        &UpdateResponseArgs {
                            key: Some(key_offset),
                            summary: Some(summary_data),
                        },
                    );

                    let contract_response_offset = FbsContractResponse::create(
                        &mut builder,
                        &ContractResponseArgs {
                            contract_response: Some(update_response_offset.as_union_value()),
                            contract_response_type: ContractResponseType::UpdateResponse,
                        },
                    );

                    let response_offset = FbsHostResponse::create(
                        &mut builder,
                        &HostResponseArgs {
                            response: Some(contract_response_offset.as_union_value()),
                            response_type: HostResponseType::ContractResponse,
                        },
                    );

                    finish_host_response_buffer(&mut builder, response_offset);
                    Ok(builder.finished_data().to_vec())
                }
                ContractResponse::GetResponse {
                    key,
                    contract: contract_container,
                    state,
                } => {
                    let instance_data = builder.create_vector(key.as_bytes());
                    let instance_offset = FbsContractInstanceId::create(
                        &mut builder,
                        &ContractInstanceIdArgs {
                            data: Some(instance_data),
                        },
                    );

                    let code = Some(builder.create_vector(&key.code_hash().0));
                    let key_offset = FbsContractKey::create(
                        &mut builder,
                        &ContractKeyArgs {
                            instance: Some(instance_offset),
                            code,
                        },
                    );

                    let container_offset = if let Some(contract) = contract_container {
                        let data = builder.create_vector(contract.key().as_bytes());

                        let instance_offset = FbsContractInstanceId::create(
                            &mut builder,
                            &ContractInstanceIdArgs { data: Some(data) },
                        );

                        let code = Some(builder.create_vector(&contract.key().code_hash().0));
                        let contract_key_offset = FbsContractKey::create(
                            &mut builder,
                            &ContractKeyArgs {
                                instance: Some(instance_offset),
                                code,
                            },
                        );

                        let contract_data =
                            builder.create_vector(contract.clone().unwrap_v1().data.data());
                        let contract_code_hash =
                            builder.create_vector(&contract.clone().unwrap_v1().data.hash().0);

                        let contract_code_offset = ContractCode::create(
                            &mut builder,
                            &ContractCodeArgs {
                                data: Some(contract_data),
                                code_hash: Some(contract_code_hash),
                            },
                        );

                        let contract_params =
                            builder.create_vector(&contract.clone().params().into_bytes());

                        let contract_offset = match contract {
                            Wasm(V1(..)) => WasmContractV1::create(
                                &mut builder,
                                &WasmContractV1Args {
                                    key: Some(contract_key_offset),
                                    data: Some(contract_code_offset),
                                    parameters: Some(contract_params),
                                },
                            ),
                        };

                        Some(FbsContractContainer::create(
                            &mut builder,
                            &ContractContainerArgs {
                                contract_type: ContractType::WasmContractV1,
                                contract: Some(contract_offset.as_union_value()),
                            },
                        ))
                    } else {
                        None
                    };

                    let state_data = builder.create_vector(&state);

                    let get_offset = FbsGetResponse::create(
                        &mut builder,
                        &GetResponseArgs {
                            key: Some(key_offset),
                            contract: container_offset,
                            state: Some(state_data),
                        },
                    );

                    let contract_response_offset = FbsContractResponse::create(
                        &mut builder,
                        &ContractResponseArgs {
                            contract_response_type: ContractResponseType::GetResponse,
                            contract_response: Some(get_offset.as_union_value()),
                        },
                    );

                    let response_offset = FbsHostResponse::create(
                        &mut builder,
                        &HostResponseArgs {
                            response: Some(contract_response_offset.as_union_value()),
                            response_type: HostResponseType::ContractResponse,
                        },
                    );

                    finish_host_response_buffer(&mut builder, response_offset);
                    Ok(builder.finished_data().to_vec())
                }
                ContractResponse::UpdateNotification { key, update } => {
                    let instance_data = builder.create_vector(key.as_bytes());
                    let instance_offset = FbsContractInstanceId::create(
                        &mut builder,
                        &ContractInstanceIdArgs {
                            data: Some(instance_data),
                        },
                    );

                    let code = Some(builder.create_vector(&key.code_hash().0));
                    let key_offset = FbsContractKey::create(
                        &mut builder,
                        &ContractKeyArgs {
                            instance: Some(instance_offset),
                            code,
                        },
                    );

                    let update_data = match update {
                        State(state) => {
                            let state_data = builder.create_vector(&state.into_bytes());
                            let state_update_offset = StateUpdate::create(
                                &mut builder,
                                &StateUpdateArgs {
                                    state: Some(state_data),
                                },
                            );
                            FbsUpdateData::create(
                                &mut builder,
                                &UpdateDataArgs {
                                    update_data_type: UpdateDataType::StateUpdate,
                                    update_data: Some(state_update_offset.as_union_value()),
                                },
                            )
                        }
                        Delta(delta) => {
                            let delta_data = builder.create_vector(&delta.into_bytes());
                            let update_offset = DeltaUpdate::create(
                                &mut builder,
                                &DeltaUpdateArgs {
                                    delta: Some(delta_data),
                                },
                            );
                            FbsUpdateData::create(
                                &mut builder,
                                &UpdateDataArgs {
                                    update_data_type: UpdateDataType::DeltaUpdate,
                                    update_data: Some(update_offset.as_union_value()),
                                },
                            )
                        }
                        StateAndDelta { state, delta } => {
                            let state_data = builder.create_vector(&state.into_bytes());
                            let delta_data = builder.create_vector(&delta.into_bytes());

                            let update_offset = StateAndDeltaUpdate::create(
                                &mut builder,
                                &StateAndDeltaUpdateArgs {
                                    state: Some(state_data),
                                    delta: Some(delta_data),
                                },
                            );

                            FbsUpdateData::create(
                                &mut builder,
                                &UpdateDataArgs {
                                    update_data_type: UpdateDataType::StateAndDeltaUpdate,
                                    update_data: Some(update_offset.as_union_value()),
                                },
                            )
                        }
                        RelatedState { related_to, state } => {
                            let state_data = builder.create_vector(&state.into_bytes());
                            // RAW 32 bytes, like every other `common.ContractInstanceId`
                            // producer. This wrote `related_to.encode()` — base58
                            // TEXT — into a field the schema and the TypeScript
                            // SDK both read as raw bytes. It is the encode half of
                            // the decode bug this change fixes: the same field, the
                            // same wrong transformation, mirrored.
                            let instance_data = builder.create_vector(related_to.as_bytes());

                            let instance_offset = FbsContractInstanceId::create(
                                &mut builder,
                                &ContractInstanceIdArgs {
                                    data: Some(instance_data),
                                },
                            );

                            let update_offset = RelatedStateUpdate::create(
                                &mut builder,
                                &RelatedStateUpdateArgs {
                                    related_to: Some(instance_offset),
                                    state: Some(state_data),
                                },
                            );

                            FbsUpdateData::create(
                                &mut builder,
                                &UpdateDataArgs {
                                    update_data_type: UpdateDataType::RelatedStateUpdate,
                                    update_data: Some(update_offset.as_union_value()),
                                },
                            )
                        }
                        RelatedDelta { related_to, delta } => {
                            // RAW 32 bytes, like every other `common.ContractInstanceId`
                            // producer. This wrote `related_to.encode()` — base58
                            // TEXT — into a field the schema and the TypeScript
                            // SDK both read as raw bytes. It is the encode half of
                            // the decode bug this change fixes: the same field, the
                            // same wrong transformation, mirrored.
                            let instance_data = builder.create_vector(related_to.as_bytes());
                            let delta_data = builder.create_vector(&delta.into_bytes());

                            let instance_offset = FbsContractInstanceId::create(
                                &mut builder,
                                &ContractInstanceIdArgs {
                                    data: Some(instance_data),
                                },
                            );

                            let update_offset = RelatedDeltaUpdate::create(
                                &mut builder,
                                &RelatedDeltaUpdateArgs {
                                    related_to: Some(instance_offset),
                                    delta: Some(delta_data),
                                },
                            );

                            FbsUpdateData::create(
                                &mut builder,
                                &UpdateDataArgs {
                                    update_data_type: UpdateDataType::RelatedDeltaUpdate,
                                    update_data: Some(update_offset.as_union_value()),
                                },
                            )
                        }
                        RelatedStateAndDelta {
                            related_to,
                            state,
                            delta,
                        } => {
                            // RAW 32 bytes, like every other `common.ContractInstanceId`
                            // producer. This wrote `related_to.encode()` — base58
                            // TEXT — into a field the schema and the TypeScript
                            // SDK both read as raw bytes. It is the encode half of
                            // the decode bug this change fixes: the same field, the
                            // same wrong transformation, mirrored.
                            let instance_data = builder.create_vector(related_to.as_bytes());
                            let state_data = builder.create_vector(&state.into_bytes());
                            let delta_data = builder.create_vector(&delta.into_bytes());

                            let instance_offset = FbsContractInstanceId::create(
                                &mut builder,
                                &ContractInstanceIdArgs {
                                    data: Some(instance_data),
                                },
                            );

                            let update_offset = RelatedStateAndDeltaUpdate::create(
                                &mut builder,
                                &RelatedStateAndDeltaUpdateArgs {
                                    related_to: Some(instance_offset),
                                    state: Some(state_data),
                                    delta: Some(delta_data),
                                },
                            );

                            FbsUpdateData::create(
                                &mut builder,
                                &UpdateDataArgs {
                                    update_data_type: UpdateDataType::RelatedStateAndDeltaUpdate,
                                    update_data: Some(update_offset.as_union_value()),
                                },
                            )
                        }
                    };

                    let update_notification_offset = FbsUpdateNotification::create(
                        &mut builder,
                        &UpdateNotificationArgs {
                            key: Some(key_offset),
                            update: Some(update_data),
                        },
                    );

                    let put_response_offset = FbsContractResponse::create(
                        &mut builder,
                        &ContractResponseArgs {
                            contract_response_type: ContractResponseType::UpdateNotification,
                            contract_response: Some(update_notification_offset.as_union_value()),
                        },
                    );

                    let host_response_offset = FbsHostResponse::create(
                        &mut builder,
                        &HostResponseArgs {
                            response_type: HostResponseType::ContractResponse,
                            response: Some(put_response_offset.as_union_value()),
                        },
                    );

                    finish_host_response_buffer(&mut builder, host_response_offset);
                    Ok(builder.finished_data().to_vec())
                }
                ContractResponse::SubscribeResponse { key, .. } => {
                    // SubscribeResponse FBS type not yet in generated code,
                    // serialize as PutResponse (same shape: just a key) so
                    // the client receives a valid response instead of a crash.
                    let instance_data = builder.create_vector(key.as_bytes());
                    let instance_offset = FbsContractInstanceId::create(
                        &mut builder,
                        &ContractInstanceIdArgs {
                            data: Some(instance_data),
                        },
                    );
                    let code = Some(builder.create_vector(&key.code_hash().0));
                    let key_offset = FbsContractKey::create(
                        &mut builder,
                        &ContractKeyArgs {
                            instance: Some(instance_offset),
                            code,
                        },
                    );
                    let put_offset = FbsPutResponse::create(
                        &mut builder,
                        &PutResponseArgs {
                            key: Some(key_offset),
                        },
                    );
                    let contract_response_offset = FbsContractResponse::create(
                        &mut builder,
                        &ContractResponseArgs {
                            contract_response_type: ContractResponseType::PutResponse,
                            contract_response: Some(put_offset.as_union_value()),
                        },
                    );
                    let host_response_offset = FbsHostResponse::create(
                        &mut builder,
                        &HostResponseArgs {
                            response_type: HostResponseType::ContractResponse,
                            response: Some(contract_response_offset.as_union_value()),
                        },
                    );
                    finish_host_response_buffer(&mut builder, host_response_offset);
                    Ok(builder.finished_data().to_vec())
                }
                ContractResponse::NotFound { instance_id } => {
                    let instance_data = builder.create_vector(instance_id.as_bytes());
                    let instance_offset = FbsContractInstanceId::create(
                        &mut builder,
                        &ContractInstanceIdArgs {
                            data: Some(instance_data),
                        },
                    );

                    let not_found_offset = FbsNotFound::create(
                        &mut builder,
                        &NotFoundArgs {
                            instance_id: Some(instance_offset),
                        },
                    );

                    let contract_response_offset = FbsContractResponse::create(
                        &mut builder,
                        &ContractResponseArgs {
                            contract_response_type: ContractResponseType::NotFound,
                            contract_response: Some(not_found_offset.as_union_value()),
                        },
                    );

                    let response_offset = FbsHostResponse::create(
                        &mut builder,
                        &HostResponseArgs {
                            response: Some(contract_response_offset.as_union_value()),
                            response_type: HostResponseType::ContractResponse,
                        },
                    );

                    finish_host_response_buffer(&mut builder, response_offset);
                    Ok(builder.finished_data().to_vec())
                }
            },
            HostResponse::DelegateResponse { key, values } => {
                let key_data = builder.create_vector(key.bytes());
                let code_hash_data = builder.create_vector(&key.code_hash().0);
                let key_offset = FbsDelegateKey::create(
                    &mut builder,
                    &DelegateKeyArgs {
                        key: Some(key_data),
                        code_hash: Some(code_hash_data),
                    },
                );
                let mut messages: Vec<WIPOffset<FbsOutboundDelegateMsg>> = Vec::new();
                values.iter().for_each(|msg| match msg {
                    OutboundDelegateMsg::ApplicationMessage(app) => {
                        let payload_data = builder.create_vector(&app.payload);
                        let delegate_context_data = builder.create_vector(app.context.as_ref());
                        let app_offset = FbsApplicationMessage::create(
                            &mut builder,
                            &ApplicationMessageArgs {
                                payload: Some(payload_data),
                                context: Some(delegate_context_data),
                                processed: app.processed,
                            },
                        );
                        let msg = FbsOutboundDelegateMsg::create(
                            &mut builder,
                            &OutboundDelegateMsgArgs {
                                inbound_type: OutboundDelegateMsgType::common_ApplicationMessage,
                                inbound: Some(app_offset.as_union_value()),
                            },
                        );
                        messages.push(msg);
                    }
                    OutboundDelegateMsg::RequestUserInput(input) => {
                        let message_data = builder.create_vector(input.message.bytes());
                        let mut responses: Vec<WIPOffset<FbsClientResponse>> = Vec::new();
                        input.responses.iter().for_each(|resp| {
                            let response_data = builder.create_vector(resp.bytes());
                            let response = FbsClientResponse::create(
                                &mut builder,
                                &ClientResponseArgs {
                                    data: Some(response_data),
                                },
                            );
                            responses.push(response)
                        });
                        let responses_offset = builder.create_vector(&responses);
                        let input_offset = FbsRequestUserInput::create(
                            &mut builder,
                            &RequestUserInputArgs {
                                request_id: input.request_id,
                                message: Some(message_data),
                                responses: Some(responses_offset),
                            },
                        );
                        let msg = FbsOutboundDelegateMsg::create(
                            &mut builder,
                            &OutboundDelegateMsgArgs {
                                inbound_type: OutboundDelegateMsgType::RequestUserInput,
                                inbound: Some(input_offset.as_union_value()),
                            },
                        );
                        messages.push(msg);
                    }
                    OutboundDelegateMsg::ContextUpdated(context) => {
                        let context_data = builder.create_vector(context.as_ref());
                        let context_offset = FbsContextUpdated::create(
                            &mut builder,
                            &ContextUpdatedArgs {
                                context: Some(context_data),
                            },
                        );
                        let msg = FbsOutboundDelegateMsg::create(
                            &mut builder,
                            &OutboundDelegateMsgArgs {
                                inbound_type: OutboundDelegateMsgType::ContextUpdated,
                                inbound: Some(context_offset.as_union_value()),
                            },
                        );
                        messages.push(msg);
                    }
                    OutboundDelegateMsg::GetContractRequest(_) => {
                        // GetContractRequest should be handled by the executor and never
                        // reach client serialization. If we get here, it's a bug.
                        tracing::error!(
                            "GetContractRequest reached client serialization - this is a bug"
                        );
                    }
                    OutboundDelegateMsg::PutContractRequest(_) => {
                        // PutContractRequest should be handled by the executor and never
                        // reach client serialization. If we get here, it's a bug.
                        tracing::error!(
                            "PutContractRequest reached client serialization - this is a bug"
                        );
                    }
                    OutboundDelegateMsg::UpdateContractRequest(_) => {
                        tracing::error!(
                            "UpdateContractRequest reached client serialization - this is a bug"
                        );
                    }
                    OutboundDelegateMsg::SubscribeContractRequest(_) => {
                        tracing::error!(
                            "SubscribeContractRequest reached client serialization - this is a bug"
                        );
                    }
                    OutboundDelegateMsg::SendDelegateMessage(_) => {
                        tracing::error!(
                            "SendDelegateMessage reached client serialization - this is a bug"
                        );
                    }
                });
                let messages_offset = builder.create_vector(&messages);
                let delegate_response_offset = FbsDelegateResponse::create(
                    &mut builder,
                    &DelegateResponseArgs {
                        key: Some(key_offset),
                        values: Some(messages_offset),
                    },
                );
                let host_response_offset = FbsHostResponse::create(
                    &mut builder,
                    &HostResponseArgs {
                        response_type: HostResponseType::DelegateResponse,
                        response: Some(delegate_response_offset.as_union_value()),
                    },
                );
                finish_host_response_buffer(&mut builder, host_response_offset);
                Ok(builder.finished_data().to_vec())
            }
            HostResponse::Ok => {
                let ok_offset = FbsOk::create(&mut builder, &OkArgs { msg: None });
                let host_response_offset = FbsHostResponse::create(
                    &mut builder,
                    &HostResponseArgs {
                        response_type: HostResponseType::Ok,
                        response: Some(ok_offset.as_union_value()),
                    },
                );
                finish_host_response_buffer(&mut builder, host_response_offset);
                Ok(builder.finished_data().to_vec())
            }
            HostResponse::QueryResponse(_) => unimplemented!(),
            HostResponse::StreamChunk {
                stream_id,
                index,
                total,
                data,
            } => {
                let data_offset = builder.create_vector(&data);
                let chunk_offset = FbsHostStreamChunk::create(
                    &mut builder,
                    &FbsHostStreamChunkArgs {
                        stream_id,
                        index,
                        total,
                        data: Some(data_offset),
                    },
                );
                let host_response_offset = FbsHostResponse::create(
                    &mut builder,
                    &HostResponseArgs {
                        response_type: HostResponseType::StreamChunk,
                        response: Some(chunk_offset.as_union_value()),
                    },
                );
                finish_host_response_buffer(&mut builder, host_response_offset);
                Ok(builder.finished_data().to_vec())
            }
            HostResponse::StreamHeader { .. } => {
                // StreamHeader is only sent over bincode (Native encoding) to
                // streaming-capable clients. Flatbuffers clients use transparent
                // reassembly via StreamChunk only.
                Err(Box::new(ClientError::from(ErrorKind::Unhandled {
                    cause: "StreamHeader is not supported over flatbuffers encoding".into(),
                })))
            }
        }
    }
}

impl Display for HostResponse {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            HostResponse::ContractResponse(res) => match res {
                ContractResponse::PutResponse { key } => {
                    f.write_fmt(format_args!("put response for `{key}`"))
                }
                ContractResponse::UpdateResponse { key, .. } => {
                    f.write_fmt(format_args!("update response for `{key}`"))
                }
                ContractResponse::GetResponse { key, .. } => {
                    f.write_fmt(format_args!("get response for `{key}`"))
                }
                ContractResponse::UpdateNotification { key, .. } => {
                    f.write_fmt(format_args!("update notification for `{key}`"))
                }
                ContractResponse::SubscribeResponse { key, .. } => {
                    f.write_fmt(format_args!("subscribe response for `{key}`"))
                }
                ContractResponse::NotFound { instance_id } => {
                    f.write_fmt(format_args!("not found for `{instance_id}`"))
                }
            },
            HostResponse::DelegateResponse { .. } => write!(f, "delegate responses"),
            HostResponse::Ok => write!(f, "ok response"),
            HostResponse::QueryResponse(_) => write!(f, "query response"),
            HostResponse::StreamChunk {
                stream_id,
                index,
                total,
                ..
            } => write!(f, "stream chunk {index}/{total} (stream {stream_id})"),
            HostResponse::StreamHeader {
                stream_id,
                total_bytes,
                ..
            } => write!(f, "stream header (stream {stream_id}, {total_bytes} bytes)"),
        }
    }
}

#[derive(Clone, Serialize, Deserialize, Debug)]
#[non_exhaustive]
pub enum ContractResponse<T = WrappedState> {
    GetResponse {
        key: ContractKey,
        contract: Option<ContractContainer>,
        #[serde(bound(deserialize = "T: DeserializeOwned"))]
        state: T,
    },
    PutResponse {
        key: ContractKey,
    },
    /// Message sent when there is an update to a subscribed contract.
    UpdateNotification {
        key: ContractKey,
        #[serde(deserialize_with = "UpdateData::deser_update_data")]
        update: UpdateData<'static>,
    },
    /// Successful update
    UpdateResponse {
        key: ContractKey,
        #[serde(deserialize_with = "StateSummary::deser_state_summary")]
        summary: StateSummary<'static>,
    },
    SubscribeResponse {
        key: ContractKey,
        subscribed: bool,
    },
    /// Contract was not found after exhaustive search.
    /// This is an explicit response that distinguishes "contract doesn't exist"
    /// from other failure modes like timeouts or network errors.
    NotFound {
        /// The instance ID that was searched for.
        instance_id: ContractInstanceId,
    },
}

impl<T> From<ContractResponse<T>> for HostResponse<T> {
    fn from(value: ContractResponse<T>) -> HostResponse<T> {
        HostResponse::ContractResponse(value)
    }
}

#[cfg(test)]
mod node_diagnostics_response_tests {
    use super::{
        ConnectedPeerInfo, ContractState, NetworkInfo, NodeDiagnosticsResponse, NodeInfo,
        SubscriptionInfo, SystemMetrics,
    };
    use crate::contract_interface::ContractInstanceId;
    use std::collections::HashMap;

    /// Regression for freenet/freenet-core#3987.
    ///
    /// Pre-0.7 `contract_states` was `HashMap<ContractKey, ContractState>`.
    /// `ContractKey` derives `Serialize` as a struct (`{instance, code}`),
    /// which `serde_json` rejects with `key must be a string` because JSON
    /// object keys must be strings. The wire path between core and clients
    /// is bincode (which doesn't care about key types), so the bug stayed
    /// invisible until the `freenet service report` binary tried to
    /// JSON-serialize the response for upload — every report from a node
    /// hosting at least one contract uploaded with empty `network_status`.
    ///
    /// All six fields are populated so that any future `pub` field added
    /// to the struct gets exercised by serde_json the moment a contributor
    /// sets a non-default value here. If a future field reintroduces the
    /// non-string-key pattern (e.g. `HashMap<PeerId, _>`), this test will
    /// fail at the source instead of silently breaking the report path.
    #[test]
    fn node_diagnostics_response_json_round_trips() {
        let mut contract_states = HashMap::new();
        contract_states.insert(
            "6kVs66bKaQAC6ohr8b43SvJ95r36tc2hnG7HezmaJHF9".to_string(),
            ContractState {
                subscribers: 3,
                subscriber_peer_ids: vec!["peer-a".to_string(), "peer-b".to_string()],
                size_bytes: 1024,
            },
        );

        let response = NodeDiagnosticsResponse {
            node_info: Some(NodeInfo {
                peer_id: "peer-self".to_string(),
                is_gateway: true,
                location: Some("0.5".to_string()),
                listening_address: Some("0.0.0.0:31337".to_string()),
                uptime_seconds: 3600,
            }),
            network_info: Some(NetworkInfo {
                connected_peers: vec![("peer-x".to_string(), "10.0.0.1:31337".to_string())],
                active_connections: 1,
            }),
            subscriptions: vec![SubscriptionInfo {
                contract_key: ContractInstanceId::new([7u8; 32]),
                client_id: 42,
            }],
            contract_states,
            system_metrics: Some(SystemMetrics {
                active_connections: 1,
                hosting_contracts: 1,
            }),
            connected_peers_detailed: vec![ConnectedPeerInfo {
                peer_id: "peer-x".to_string(),
                address: "10.0.0.1:31337".to_string(),
            }],
        };

        let json = serde_json::to_string(&response).expect("must serialize to JSON");
        let parsed: serde_json::Value = serde_json::from_str(&json).expect("output is valid JSON");

        // Every top-level field is present and distinguishable.
        let obj = parsed.as_object().expect("top-level must be object");
        assert_eq!(obj.len(), 6, "expected six top-level fields, got {obj:?}");
        assert_eq!(parsed["node_info"]["peer_id"], "peer-self");
        assert_eq!(parsed["network_info"]["active_connections"], 1);
        assert_eq!(parsed["subscriptions"][0]["client_id"], 42);
        assert_eq!(parsed["system_metrics"]["hosting_contracts"], 1);
        assert_eq!(parsed["connected_peers_detailed"][0]["peer_id"], "peer-x");

        let states = parsed["contract_states"]
            .as_object()
            .expect("contract_states must be a JSON object");
        assert_eq!(states.len(), 1);
        assert_eq!(
            states["6kVs66bKaQAC6ohr8b43SvJ95r36tc2hnG7HezmaJHF9"]["subscribers"],
            3
        );

        // Bincode round-trip must also still work for the same value
        // (the new wire format is the contract; older clients are
        // documented as incompatible in CHANGELOG).
        let bytes = bincode::serialize(&response).expect("bincode must serialize");
        let decoded: NodeDiagnosticsResponse =
            bincode::deserialize(&bytes).expect("bincode must round-trip");
        assert_eq!(
            decoded.contract_states.len(),
            1,
            "bincode round-trip preserves contract_states entries"
        );
    }
}

#[cfg(test)]
mod client_request_test {
    use crate::client_api::{ContractRequest, TryFromFbs, WsApiError};
    use crate::contract_interface::UpdateData;
    use crate::generated::client_request::root_as_client_request;

    const EXPECTED_ENCODED_CONTRACT_ID: &str = "6kVs66bKaQAC6ohr8b43SvJ95r36tc2hnG7HezmaJHF9";

    #[test]
    fn test_build_contract_put_op_from_fbs() -> Result<(), Box<dyn std::error::Error>> {
        let put_req_op = vec![
            4, 0, 0, 0, 244, 255, 255, 255, 16, 0, 0, 0, 0, 0, 0, 1, 8, 0, 12, 0, 11, 0, 4, 0, 8,
            0, 0, 0, 8, 0, 0, 0, 0, 0, 0, 1, 198, 255, 255, 255, 12, 0, 0, 0, 20, 0, 0, 0, 36, 0,
            0, 0, 170, 255, 255, 255, 4, 0, 0, 0, 0, 0, 0, 0, 8, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8,
            8, 0, 10, 0, 9, 0, 4, 0, 8, 0, 0, 0, 16, 0, 0, 0, 0, 1, 10, 0, 16, 0, 12, 0, 8, 0, 4,
            0, 10, 0, 0, 0, 12, 0, 0, 0, 76, 0, 0, 0, 92, 0, 0, 0, 176, 255, 255, 255, 8, 0, 0, 0,
            16, 0, 0, 0, 0, 0, 0, 0, 0, 0, 6, 0, 8, 0, 4, 0, 6, 0, 0, 0, 4, 0, 0, 0, 32, 0, 0, 0,
            85, 111, 11, 171, 40, 85, 240, 177, 207, 81, 106, 157, 173, 90, 234, 2, 250, 253, 75,
            210, 62, 7, 6, 34, 75, 26, 229, 230, 107, 167, 17, 108, 8, 0, 0, 0, 1, 2, 3, 4, 5, 6,
            7, 8, 8, 0, 12, 0, 8, 0, 4, 0, 8, 0, 0, 0, 8, 0, 0, 0, 16, 0, 0, 0, 8, 0, 0, 0, 1, 2,
            3, 4, 5, 6, 7, 8, 8, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8,
        ];
        let request = if let Ok(client_request) = root_as_client_request(&put_req_op) {
            let contract_request = client_request.client_request_as_contract_request().unwrap();
            ContractRequest::try_decode_fbs(&contract_request)?
        } else {
            panic!("failed to decode client request")
        };

        match request {
            ContractRequest::Put {
                contract,
                state,
                related_contracts: _,
                subscribe,
                blocking_subscribe,
            } => {
                assert_eq!(
                    contract.to_string(),
                    "WasmContainer([api=0.0.1](D8fdVLbRyMLw5mZtPRpWMFcrXGN2z8Nq8UGcLGPFBg2W))"
                );
                assert_eq!(contract.unwrap_v1().data.data(), &[1, 2, 3, 4, 5, 6, 7, 8]);
                assert_eq!(state.to_vec(), &[1, 2, 3, 4, 5, 6, 7, 8]);
                assert!(!subscribe);
                assert!(!blocking_subscribe);
            }
            _ => panic!("wrong contract request type"),
        }

        Ok(())
    }

    #[test]
    fn test_build_contract_get_op_from_fbs() -> Result<(), Box<dyn std::error::Error>> {
        let get_req_op = vec![
            4, 0, 0, 0, 244, 255, 255, 255, 16, 0, 0, 0, 0, 0, 0, 1, 8, 0, 12, 0, 11, 0, 4, 0, 8,
            0, 0, 0, 8, 0, 0, 0, 0, 0, 0, 3, 222, 255, 255, 255, 12, 0, 0, 0, 8, 0, 12, 0, 8, 0, 4,
            0, 8, 0, 0, 0, 8, 0, 0, 0, 16, 0, 0, 0, 0, 0, 0, 0, 0, 0, 6, 0, 8, 0, 4, 0, 6, 0, 0, 0,
            4, 0, 0, 0, 32, 0, 0, 0, 85, 111, 11, 171, 40, 85, 240, 177, 207, 81, 106, 157, 173,
            90, 234, 2, 250, 253, 75, 210, 62, 7, 6, 34, 75, 26, 229, 230, 107, 167, 17, 108,
        ];
        let request = if let Ok(client_request) = root_as_client_request(&get_req_op) {
            let contract_request = client_request.client_request_as_contract_request().unwrap();
            ContractRequest::try_decode_fbs(&contract_request)?
        } else {
            panic!("failed to decode client request")
        };

        match request {
            ContractRequest::Get {
                key,
                return_contract_code: fetch_contract,
                subscribe,
                blocking_subscribe,
            } => {
                assert_eq!(key.encode(), EXPECTED_ENCODED_CONTRACT_ID);
                assert!(!fetch_contract);
                assert!(!subscribe);
                assert!(!blocking_subscribe);
            }
            _ => panic!("wrong contract request type"),
        }

        Ok(())
    }

    /// A well-formed FlatBuffers `UpdateRequest` decodes to the expected key
    /// and delta.
    ///
    /// Built programmatically rather than from a hardcoded byte blob. The blob
    /// this replaces carried a present-but-ZERO-LENGTH `code` field, which is
    /// what the TypeScript SDK's `ContractKey.fromInstanceId(...)` emits: a
    /// request the node cannot serve, because an UPDATE supplies no contract
    /// code and freenet-core resolves the WASM by code hash. Nobody could see
    /// that from reading the test; it took instrumenting the decoder. So the
    /// fixture now carries a real 32-byte hash and says so in source.
    ///
    /// The empty and absent cases are covered in
    /// `contract_interface::key::fbs_tests`, next to the decoder that rejects
    /// them.
    #[test]
    fn test_build_contract_update_op_from_fbs() -> Result<(), Box<dyn std::error::Error>> {
        use crate::generated::client_request::{
            finish_client_request_buffer, ClientRequest as FbsClientRequest, ClientRequestArgs,
            ClientRequestType, ContractRequest as FbsContractRequest, ContractRequestArgs,
            ContractRequestType, Update as FbsUpdate, UpdateArgs,
        };
        use crate::generated::common::{
            ContractInstanceId as FbsContractInstanceId, ContractInstanceIdArgs,
            ContractKey as FbsContractKey, ContractKeyArgs, DeltaUpdate, DeltaUpdateArgs,
            UpdateData as FbsUpdateData, UpdateDataArgs, UpdateDataType,
        };
        use crate::prelude::ContractInstanceId;

        // Derive the instance bytes from the expected id rather than pasting a
        // magic array, so the assertion below can't drift from the fixture.
        let instance_id = ContractInstanceId::try_from(EXPECTED_ENCODED_CONTRACT_ID.to_string())?;
        // A distinct, arbitrary code hash: if the decoder ever re-hashes it
        // (the BLAKE3(BLAKE3(wasm)) bug this PR fixes), the assertion fails.
        let code_hash = [42u8; 32];
        let delta_bytes = [1u8, 2, 3, 4, 5, 6, 7, 8];

        let mut b = flatbuffers::FlatBufferBuilder::new();

        let instance_data = b.create_vector(instance_id.as_bytes());
        let instance_offset = FbsContractInstanceId::create(
            &mut b,
            &ContractInstanceIdArgs {
                data: Some(instance_data),
            },
        );
        let code = Some(b.create_vector(&code_hash));
        let key_offset = FbsContractKey::create(
            &mut b,
            &ContractKeyArgs {
                instance: Some(instance_offset),
                code,
            },
        );

        let delta = b.create_vector(&delta_bytes);
        let delta_offset = DeltaUpdate::create(&mut b, &DeltaUpdateArgs { delta: Some(delta) });
        let update_data_offset = FbsUpdateData::create(
            &mut b,
            &UpdateDataArgs {
                update_data_type: UpdateDataType::DeltaUpdate,
                update_data: Some(delta_offset.as_union_value()),
            },
        );

        let update_offset = FbsUpdate::create(
            &mut b,
            &UpdateArgs {
                key: Some(key_offset),
                data: Some(update_data_offset),
            },
        );
        let contract_offset = FbsContractRequest::create(
            &mut b,
            &ContractRequestArgs {
                contract_request_type: ContractRequestType::Update,
                contract_request: Some(update_offset.as_union_value()),
            },
        );
        let client_offset = FbsClientRequest::create(
            &mut b,
            &ClientRequestArgs {
                client_request_type: ClientRequestType::ContractRequest,
                client_request: Some(contract_offset.as_union_value()),
            },
        );
        finish_client_request_buffer(&mut b, client_offset);

        let update_op = b.finished_data().to_vec();
        let request = if let Ok(client_request) = root_as_client_request(&update_op) {
            let contract_request = client_request.client_request_as_contract_request().unwrap();
            ContractRequest::try_decode_fbs(&contract_request)?
        } else {
            panic!("failed to decode client request")
        };

        match request {
            ContractRequest::Update { key, data } => {
                assert_eq!(key.encoded_contract_id(), EXPECTED_ENCODED_CONTRACT_ID);
                assert_eq!(
                    key.code_hash().as_ref(),
                    &code_hash,
                    "the code hash must survive decode unchanged, not be re-hashed"
                );
                match data {
                    UpdateData::Delta(delta) => {
                        assert_eq!(delta.to_vec(), &delta_bytes)
                    }
                    _ => panic!("wrong update data type"),
                }
            }
            _ => panic!("wrong contract request type"),
        }

        Ok(())
    }

    /// The exact bytes the TypeScript SDK's own test suite asserts as a correct
    /// `UpdateRequest`: pinned here so the two suites cannot disagree silently.
    ///
    /// Copied verbatim from `typescript/tests/websocket-interface.test.ts`
    /// (`EXPECTED_UPDATE_REQ`). It is byte-for-byte the blob this PR deleted
    /// from the Rust side, which is exactly how the original double-hash bug
    /// survived: both suites pinned the same bytes in mirror, and neither ever
    /// crossed the language boundary, so a shape that no Rust decoder accepted
    /// stayed "verified" on the TypeScript side.
    ///
    /// Its `code` field is present and ZERO-LENGTH, which is what
    /// `ContractKey.fromInstanceId(...)` emits. After this change the Rust
    /// decoder hard-errors on it, while `npm test` still asserts it is correct
    /// and stays green. Both suites run in CI, so this test is the only thing
    /// that makes that disagreement visible.
    ///
    /// Scope, so this is not over-trusted: it is a COPY of the TypeScript
    /// array, not a reference to it. Nothing mechanically ties the two, so
    /// editing the TypeScript side fails nothing here. (`include_str!` across
    /// to `typescript/` is not the fix: `rust/` is the published package root
    /// and the path would escape it.) So this is a convention, and the
    /// convention is: if the TypeScript SDK is fixed (see
    /// freenet/freenet-core#4978, whose candidate is making `UpdateRequest`
    /// reject a key whose `code` is not 32 bytes), update the array and this
    /// constant together. Leaving one behind re-creates the mirror-pinning
    /// that hid the original bug.
    const TS_SDK_EXPECTED_UPDATE_REQ: &[u8] = &[
        4, 0, 0, 0, 220, 255, 255, 255, 8, 0, 0, 0, 0, 0, 0, 1, 232, 255, 255, 255, 8, 0, 0, 0, 0,
        0, 0, 2, 204, 255, 255, 255, 16, 0, 0, 0, 52, 0, 0, 0, 8, 0, 12, 0, 11, 0, 4, 0, 8, 0, 0,
        0, 8, 0, 0, 0, 0, 0, 0, 2, 210, 255, 255, 255, 4, 0, 0, 0, 8, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7,
        8, 8, 0, 12, 0, 8, 0, 4, 0, 8, 0, 0, 0, 8, 0, 0, 0, 16, 0, 0, 0, 0, 0, 0, 0, 0, 0, 6, 0, 8,
        0, 4, 0, 6, 0, 0, 0, 4, 0, 0, 0, 32, 0, 0, 0, 85, 111, 11, 171, 40, 85, 240, 177, 207, 81,
        106, 157, 173, 90, 234, 2, 250, 253, 75, 210, 62, 7, 6, 34, 75, 26, 229, 230, 107, 167, 17,
        108,
    ];

    /// The cross-language contract: what the TypeScript SDK emits for an
    /// instance-id-only UPDATE is rejected here, with the actionable message.
    ///
    /// Asserting the MESSAGE and not just the rejection is the point. The
    /// TypeScript developer whose request this is gets exactly this string
    /// back over the WebSocket, and it is the only thing telling them the key
    /// needs both parts. A revert to the bare `try_from` error would leave the
    /// rejection green while restoring `"invalid data"`.
    #[test]
    fn typescript_sdk_instance_only_update_is_rejected_with_guidance() {
        let client_request = root_as_client_request(TS_SDK_EXPECTED_UPDATE_REQ)
            .expect("the TS SDK blob must still be a well-formed ClientRequest");
        let contract_request = client_request
            .client_request_as_contract_request()
            .expect("the TS SDK blob must still be a ContractRequest");

        let err = ContractRequest::try_decode_fbs(&contract_request)
            .expect_err("an instance-id-only UPDATE must be rejected");
        let msg = err.to_string();

        assert!(
            msg.contains("ContractKey.code") && msg.contains("got 0 bytes"),
            "the TS SDK's zero-length code must be named explicitly, got: {msg}"
        );
        assert!(
            msg.contains("new ContractKey(instance, code)"),
            "the error must tell a TypeScript developer how to build the key, got: {msg}"
        );
        assert!(
            msg.contains("4978"),
            "the error must point at the tracking issue for the real fix, got: {msg}"
        );
    }

    /// Build a `ClientRequest` carrying a GET or SUBSCRIBE whose `ContractKey`
    /// has an `instance` vector of the given length.
    ///
    /// The length is a parameter because the flatbuffers verifier checks that a
    /// `(required)` vector is PRESENT, not that it is the right SIZE, so a
    /// wrong-length instance is a shape a peer can actually put on the wire and
    /// that `flatbuffers::root` will happily hand to the decoder.
    fn client_request_with_instance_len(instance_len: usize, subscribe: bool) -> Vec<u8> {
        use crate::generated::client_request::{
            finish_client_request_buffer, ClientRequest as FbsClientRequest, ClientRequestArgs,
            ClientRequestType, ContractRequest as FbsContractRequest, ContractRequestArgs,
            ContractRequestType, Get as FbsGet, GetArgs, Subscribe as FbsSubscribe, SubscribeArgs,
        };
        use crate::generated::common::{
            ContractInstanceId as FbsContractInstanceId, ContractInstanceIdArgs,
            ContractKey as FbsContractKey, ContractKeyArgs,
        };

        let mut b = flatbuffers::FlatBufferBuilder::new();
        let instance_data = b.create_vector(&vec![1u8; instance_len]);
        let instance_offset = FbsContractInstanceId::create(
            &mut b,
            &ContractInstanceIdArgs {
                data: Some(instance_data),
            },
        );
        let code = Some(b.create_vector(&[42u8; 32]));
        let key_offset = FbsContractKey::create(
            &mut b,
            &ContractKeyArgs {
                instance: Some(instance_offset),
                code,
            },
        );

        let (request_type, request_offset) = if subscribe {
            let sub = FbsSubscribe::create(
                &mut b,
                &SubscribeArgs {
                    key: Some(key_offset),
                    summary: None,
                },
            );
            (ContractRequestType::Subscribe, sub.as_union_value())
        } else {
            let get = FbsGet::create(
                &mut b,
                &GetArgs {
                    key: Some(key_offset),
                    fetch_contract: false,
                    subscribe: false,
                    blocking_subscribe: false,
                },
            );
            (ContractRequestType::Get, get.as_union_value())
        };

        let contract_offset = FbsContractRequest::create(
            &mut b,
            &ContractRequestArgs {
                contract_request_type: request_type,
                contract_request: Some(request_offset),
            },
        );
        let client_offset = FbsClientRequest::create(
            &mut b,
            &ClientRequestArgs {
                client_request_type: ClientRequestType::ContractRequest,
                client_request: Some(contract_offset.as_union_value()),
            },
        );
        finish_client_request_buffer(&mut b, client_offset);
        b.finished_data().to_vec()
    }

    fn decode_client_request(bytes: &[u8]) -> Result<ContractRequest<'_>, WsApiError> {
        let client_request =
            root_as_client_request(bytes).expect("must be a well-formed ClientRequest");
        let contract_request = client_request
            .client_request_as_contract_request()
            .expect("must be a ContractRequest");
        ContractRequest::try_decode_fbs(&contract_request)
    }

    /// A GET whose instance is the wrong length is rejected, not panicked on.
    ///
    /// Pinned at the REQUEST level rather than through `ContractKey`'s decoder,
    /// because GET does not go through `ContractKey::try_decode_fbs` at all: it
    /// reads the instance bytes directly. A test that only covers the UPDATE
    /// path leaves a revert of this site green, which is exactly the state this
    /// suite was in before: the panic fix reached three call sites and only one
    /// of them was pinned.
    #[test]
    fn get_with_wrong_length_instance_is_rejected_not_panicking() {
        let bytes = client_request_with_instance_len(8, false);
        let short = decode_client_request(&bytes)
            .expect_err("a GET with an 8-byte instance must be rejected");
        assert!(
            short.to_string().contains("ContractKey.instance")
                && short.to_string().contains("got 8 bytes"),
            "got: {short}"
        );

        let bytes = client_request_with_instance_len(64, false);
        let long = decode_client_request(&bytes)
            .expect_err("a GET with a 64-byte instance must be rejected");
        assert!(long.to_string().contains("got 64 bytes"), "got: {long}");
    }

    /// Same for SUBSCRIBE, which is a third independent decode site.
    #[test]
    fn subscribe_with_wrong_length_instance_is_rejected_not_panicking() {
        let bytes = client_request_with_instance_len(8, true);
        let short = decode_client_request(&bytes)
            .expect_err("a SUBSCRIBE with an 8-byte instance must be rejected");
        assert!(
            short.to_string().contains("ContractKey.instance")
                && short.to_string().contains("got 8 bytes"),
            "got: {short}"
        );

        let bytes = client_request_with_instance_len(64, true);
        let long = decode_client_request(&bytes)
            .expect_err("a SUBSCRIBE with a 64-byte instance must be rejected");
        assert!(long.to_string().contains("got 64 bytes"), "got: {long}");
    }

    /// A well-formed GET still decodes: the length guard must reject the wrong
    /// size without breaking the right one.
    #[test]
    fn get_with_valid_instance_still_decodes() {
        let bytes = client_request_with_instance_len(32, false);
        let req = decode_client_request(&bytes).expect("a 32-byte instance must still decode");
        assert!(
            matches!(req, ContractRequest::Get { .. }),
            "expected a Get, got {req:?}"
        );
    }

    /// The flatbuffers decode path must NOT panic on an unknown
    /// `ContractRequestType` discriminant. Same class as the `DelegateRequest`
    /// guard: the generated union verifier accepts any discriminant it doesn't
    /// recognize (`_ => Ok(())`), and the union type field is a raw `u8` a
    /// client can set to any value. Before the fix this hit `unreachable!()`
    /// and downed the connection handler; now it is a clean per-request error.
    #[test]
    fn fbs_decode_rejects_unknown_contract_discriminant() {
        use crate::generated::client_request::{
            finish_client_request_buffer, ClientRequest as FbsClientRequest, ClientRequestArgs,
            ClientRequestType, ContractRequest as FbsContractRequest, ContractRequestArgs,
            ContractRequestType, DelegateKey as FbsDelegateKey, DelegateKeyArgs,
            UnregisterDelegate, UnregisterDelegateArgs,
        };

        let mut b = flatbuffers::FlatBufferBuilder::new();
        // Any well-formed table satisfies the required union value; the
        // discriminant is unknown so the verifier never inspects it.
        let key = b.create_vector(&[0u8; 32]);
        let code_hash = b.create_vector(&[0u8; 32]);
        let dk = FbsDelegateKey::create(
            &mut b,
            &DelegateKeyArgs {
                key: Some(key),
                code_hash: Some(code_hash),
            },
        );
        let dummy = UnregisterDelegate::create(&mut b, &UnregisterDelegateArgs { key: Some(dk) });
        // 99 is past the max known ContractRequestType (Subscribe = 4).
        let contract = FbsContractRequest::create(
            &mut b,
            &ContractRequestArgs {
                contract_request_type: ContractRequestType(99),
                contract_request: Some(dummy.as_union_value()),
            },
        );
        let client = FbsClientRequest::create(
            &mut b,
            &ClientRequestArgs {
                client_request_type: ClientRequestType::ContractRequest,
                client_request: Some(contract.as_union_value()),
            },
        );
        finish_client_request_buffer(&mut b, client);
        let bytes = b.finished_data().to_vec();

        let client =
            root_as_client_request(&bytes).expect("verifier accepts an unknown union discriminant");
        let fbs_contract = client
            .client_request_as_contract_request()
            .expect("client_request is a ContractRequest");
        assert!(
            ContractRequest::try_decode_fbs(&fbs_contract).is_err(),
            "an unknown ContractRequestType discriminant must be a clean \
             per-request error, never a panic that downs the connection handler"
        );
    }
}

/// Wire-format pins for [`DelegateRequest`].
///
/// `DelegateRequest` crosses the client<->node boundary as bincode (the
/// `EncodingProtocol::Native` path in freenet-core; the Rust clients in this
/// crate — `browser.rs` and `regular.rs` — both `bincode::serialize` their
/// requests). Bincode encodes an enum's variant as a 4-byte little-endian
/// `u32` discriminant, so the *order* of the variants is the wire contract:
/// reordering or inserting a variant anywhere but the end silently reassigns
/// every following tag and breaks already-deployed clients (the v0.2.11
/// break class).
///
/// `RegisterDelegateWithPredecessors` was appended as the LAST variant
/// precisely so the three pre-existing tags stay byte-identical. These tests
/// exist because, before this module, `DelegateRequest` had NO wire-format
/// pin at all — a reorder would have shipped undetected.
#[cfg(test)]
mod delegate_request_wire_format {
    use super::DelegateRequest;
    use crate::code_hash::CodeHash;
    use crate::prelude::{
        ApplicationMessage, Delegate, DelegateCode, DelegateContainer, DelegateKey,
        DelegateWasmAPIVersion, InboundDelegateMsg, Parameters,
    };

    fn sample_container() -> DelegateContainer {
        let code = DelegateCode::from(vec![1u8, 2, 3, 4]);
        let params = Parameters::from(vec![9u8, 8, 7]);
        DelegateContainer::Wasm(DelegateWasmAPIVersion::V1(Delegate::from((&code, &params))))
    }

    fn sample_key(fill: u8) -> DelegateKey {
        DelegateKey::new([fill; 32], CodeHash::new([fill.wrapping_add(1); 32]))
    }

    // The four sample values whose complete bincode encodings are frozen in
    // `wire_format_is_frozen`. Kept byte-for-byte identical to the throwaway
    // generator that produced the frozen vectors, so the freeze is
    // reproducible: construct the value, `bincode::serialize`, compare.
    fn sample_app_messages() -> DelegateRequest<'static> {
        DelegateRequest::ApplicationMessages {
            key: DelegateKey::new([0x11; 32], CodeHash::new([0x22; 32])),
            params: Parameters::from(vec![0xDE, 0xAD, 0xBE, 0xEF]),
            inbound: vec![InboundDelegateMsg::ApplicationMessage(
                ApplicationMessage::new(vec![0x01, 0x02, 0x03]),
            )],
        }
    }

    fn sample_register() -> DelegateRequest<'static> {
        DelegateRequest::RegisterDelegate {
            delegate: sample_container(),
            cipher: [0x55; 32],
            nonce: [0x66; 24],
        }
    }

    fn sample_unregister() -> DelegateRequest<'static> {
        DelegateRequest::UnregisterDelegate(DelegateKey::new([0x11; 32], CodeHash::new([0x22; 32])))
    }

    fn sample_register_with_predecessors() -> DelegateRequest<'static> {
        DelegateRequest::RegisterDelegateWithPredecessors {
            delegate: sample_container(),
            cipher: [0x33; 32],
            nonce: [0x44; 24],
            predecessors: vec![sample_key(0xA0), sample_key(0xB0), sample_key(0xC0)],
        }
    }

    /// Complete-byte wire-format freeze for all four variants.
    ///
    /// The three pre-existing variants (`ApplicationMessages`,
    /// `RegisterDelegate`, `UnregisterDelegate`) are pinned to their FULL
    /// expected byte vectors — not just the 4-byte tag — so a field reorder or
    /// a change to a nested type's encoding (e.g. `DelegateContainer`,
    /// `DelegateKey`, `ApplicationMessage`) is caught, not only a variant
    /// reorder. Those three vectors were generated from **origin/main @
    /// 8b53702** (the shipped format) via a throwaway generator and confirmed
    /// byte-identical to this branch's output, so the pin anchors to what old
    /// clients actually speak. The fourth vector
    /// (`RegisterDelegateWithPredecessors`, multi-predecessor list) was
    /// generated from THIS branch.
    ///
    /// The test also DESERIALIZES each frozen vector, proving an old-format
    /// byte stream still decodes into the expected variant on this build.
    #[test]
    fn wire_format_is_frozen() {
        // --- origin/main @ 8b53702 (shipped format) ---
        const APP_MESSAGES: &[u8] = &[
            0, 0, 0, 0, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17,
            17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 34, 34, 34, 34, 34, 34, 34, 34, 34,
            34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34,
            34, 4, 0, 0, 0, 0, 0, 0, 0, 222, 173, 190, 239, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3,
            0, 0, 0, 0, 0, 0, 0, 1, 2, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        ];
        const REGISTER: &[u8] = &[
            1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0, 0, 0, 9, 8, 7, 4, 0, 0, 0, 0, 0,
            0, 0, 1, 2, 3, 4, 99, 120, 29, 23, 20, 37, 163, 99, 18, 250, 5, 141, 135, 18, 213, 208,
            81, 53, 169, 145, 236, 32, 53, 28, 233, 214, 92, 219, 25, 160, 84, 50, 88, 111, 44, 39,
            24, 219, 97, 92, 222, 20, 205, 248, 149, 154, 214, 38, 193, 144, 31, 141, 32, 222, 49,
            197, 66, 237, 16, 98, 165, 72, 6, 11, 99, 120, 29, 23, 20, 37, 163, 99, 18, 250, 5,
            141, 135, 18, 213, 208, 81, 53, 169, 145, 236, 32, 53, 28, 233, 214, 92, 219, 25, 160,
            84, 50, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85,
            85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 85, 102, 102, 102, 102, 102, 102, 102, 102,
            102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102,
        ];
        const UNREGISTER: &[u8] = &[
            2, 0, 0, 0, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17,
            17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 17, 34, 34, 34, 34, 34, 34, 34, 34, 34,
            34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34, 34,
            34,
        ];
        // --- this branch (the new variant) ---
        const REGISTER_WITH_PREDECESSORS: &[u8] = &[
            3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0, 0, 0, 9, 8, 7, 4, 0, 0, 0, 0, 0,
            0, 0, 1, 2, 3, 4, 99, 120, 29, 23, 20, 37, 163, 99, 18, 250, 5, 141, 135, 18, 213, 208,
            81, 53, 169, 145, 236, 32, 53, 28, 233, 214, 92, 219, 25, 160, 84, 50, 88, 111, 44, 39,
            24, 219, 97, 92, 222, 20, 205, 248, 149, 154, 214, 38, 193, 144, 31, 141, 32, 222, 49,
            197, 66, 237, 16, 98, 165, 72, 6, 11, 99, 120, 29, 23, 20, 37, 163, 99, 18, 250, 5,
            141, 135, 18, 213, 208, 81, 53, 169, 145, 236, 32, 53, 28, 233, 214, 92, 219, 25, 160,
            84, 50, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51,
            51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68,
            68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 68, 3, 0, 0, 0, 0, 0, 0, 0, 160,
            160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160,
            160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 160, 161, 161, 161,
            161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161,
            161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 161, 176, 176, 176, 176, 176,
            176, 176, 176, 176, 176, 176, 176, 176, 176, 176, 176, 176, 176, 176, 176, 176, 176,
            176, 176, 176, 176, 176, 176, 176, 176, 176, 176, 177, 177, 177, 177, 177, 177, 177,
            177, 177, 177, 177, 177, 177, 177, 177, 177, 177, 177, 177, 177, 177, 177, 177, 177,
            177, 177, 177, 177, 177, 177, 177, 177, 192, 192, 192, 192, 192, 192, 192, 192, 192,
            192, 192, 192, 192, 192, 192, 192, 192, 192, 192, 192, 192, 192, 192, 192, 192, 192,
            192, 192, 192, 192, 192, 192, 193, 193, 193, 193, 193, 193, 193, 193, 193, 193, 193,
            193, 193, 193, 193, 193, 193, 193, 193, 193, 193, 193, 193, 193, 193, 193, 193, 193,
            193, 193, 193, 193,
        ];

        // 1. Serialization is byte-stable for every variant.
        assert_eq!(
            bincode::serialize(&sample_app_messages()).unwrap(),
            APP_MESSAGES,
            "ApplicationMessages (tag 0) encoding changed"
        );
        assert_eq!(
            bincode::serialize(&sample_register()).unwrap(),
            REGISTER,
            "RegisterDelegate (tag 1) encoding changed"
        );
        assert_eq!(
            bincode::serialize(&sample_unregister()).unwrap(),
            UNREGISTER,
            "UnregisterDelegate (tag 2) encoding changed"
        );
        assert_eq!(
            bincode::serialize(&sample_register_with_predecessors()).unwrap(),
            REGISTER_WITH_PREDECESSORS,
            "RegisterDelegateWithPredecessors (tag 3) encoding changed"
        );

        // 2. The four variant tags are exactly 0,1,2,3 — appending the new
        //    variant did not shift the pre-existing three.
        assert_eq!(APP_MESSAGES[..4], 0u32.to_le_bytes());
        assert_eq!(REGISTER[..4], 1u32.to_le_bytes());
        assert_eq!(UNREGISTER[..4], 2u32.to_le_bytes());
        assert_eq!(REGISTER_WITH_PREDECESSORS[..4], 3u32.to_le_bytes());

        // 3. Each frozen (old-format) byte stream still DECODES into its
        //    variant on this build — an old client's bytes remain readable.
        assert!(matches!(
            bincode::deserialize::<DelegateRequest>(APP_MESSAGES).unwrap(),
            DelegateRequest::ApplicationMessages { .. }
        ));
        assert!(matches!(
            bincode::deserialize::<DelegateRequest>(REGISTER).unwrap(),
            DelegateRequest::RegisterDelegate { .. }
        ));
        assert!(matches!(
            bincode::deserialize::<DelegateRequest>(UNREGISTER).unwrap(),
            DelegateRequest::UnregisterDelegate(_)
        ));
        assert!(matches!(
            bincode::deserialize::<DelegateRequest>(REGISTER_WITH_PREDECESSORS).unwrap(),
            DelegateRequest::RegisterDelegateWithPredecessors { .. }
        ));
    }

    /// The new variant's tag is exactly `3u32` little-endian — a direct,
    /// self-documenting assertion that it was appended one past
    /// `UnregisterDelegate` (tag 2).
    #[test]
    fn register_with_predecessors_tag_is_three() {
        let req = DelegateRequest::RegisterDelegateWithPredecessors {
            delegate: sample_container(),
            cipher: [0; 32],
            nonce: [0; 24],
            predecessors: vec![],
        };
        assert_eq!(
            bincode::serialize(&req).unwrap()[..4],
            3u32.to_le_bytes(),
            "RegisterDelegateWithPredecessors must be the 4th variant (tag 3)"
        );
    }

    /// The new variant round-trips through bincode, including a multi-element
    /// `predecessors` list (the skip-generations case the variant exists for).
    #[test]
    fn register_with_predecessors_round_trips() {
        let predecessors = vec![sample_key(0xA0), sample_key(0xB0), sample_key(0xC0)];
        let delegate = sample_container();
        let expected_key = delegate.key().clone();

        let req = DelegateRequest::RegisterDelegateWithPredecessors {
            delegate,
            cipher: [0x33; 32],
            nonce: [0x44; 24],
            predecessors: predecessors.clone(),
        };

        let bytes = bincode::serialize(&req).unwrap();
        let decoded: DelegateRequest = bincode::deserialize(&bytes).unwrap();

        match decoded {
            DelegateRequest::RegisterDelegateWithPredecessors {
                delegate,
                cipher,
                nonce,
                predecessors: got,
            } => {
                assert_eq!(delegate.key(), &expected_key, "delegate preserved");
                assert_eq!(cipher, [0x33; 32], "cipher preserved");
                assert_eq!(nonce, [0x44; 24], "nonce preserved");
                assert_eq!(
                    got, predecessors,
                    "full predecessor list preserved in order"
                );
            }
            other => panic!("round-trip produced the wrong variant: {other:?}"),
        }
    }

    /// `key()` returns the newly-registered delegate's key (not a
    /// predecessor's), matching `RegisterDelegate`'s behavior.
    #[test]
    fn key_returns_the_new_delegate() {
        let delegate = sample_container();
        let expected_key = delegate.key().clone();
        let req = DelegateRequest::RegisterDelegateWithPredecessors {
            delegate,
            cipher: [0; 32],
            nonce: [0; 24],
            predecessors: vec![sample_key(0xA0)],
        };
        assert_eq!(req.key(), &expected_key);
    }

    /// The flatbuffers decode path must NOT panic on an unknown
    /// `DelegateRequestType` discriminant. The generated union verifier accepts
    /// any discriminant it doesn't recognize (`_ => Ok(())`), and the union
    /// type field is a raw `u8` that the public (TypeScript) builder can set to
    /// any value, so a crafted request reaches `DelegateRequest::try_decode_fbs`
    /// with an out-of-range discriminant. Before the fix this hit
    /// `unreachable!()` and took down the connection handler; now it is a clean
    /// per-request error. (Regression guard for the P2 finding on PR #86.)
    #[test]
    fn fbs_decode_rejects_unknown_discriminant() {
        use crate::client_api::TryFromFbs;
        use crate::generated::client_request::{
            finish_client_request_buffer, root_as_client_request,
            ClientRequest as FbsClientRequest, ClientRequestArgs, ClientRequestType,
            DelegateKey as FbsDelegateKey, DelegateKeyArgs, DelegateRequest as FbsDelegateRequest,
            DelegateRequestArgs, DelegateRequestType, UnregisterDelegate, UnregisterDelegateArgs,
        };

        let mut b = flatbuffers::FlatBufferBuilder::new();
        // A real, well-formed UnregisterDelegate table to hang off the union...
        let key = b.create_vector(&[0u8; 32]);
        let code_hash = b.create_vector(&[0u8; 32]);
        let dk = FbsDelegateKey::create(
            &mut b,
            &DelegateKeyArgs {
                key: Some(key),
                code_hash: Some(code_hash),
            },
        );
        let unreg = UnregisterDelegate::create(&mut b, &UnregisterDelegateArgs { key: Some(dk) });
        // ...but LIE about the union type: 99 is past the max known
        // discriminant (UnregisterDelegate = 3), yet the verifier accepts it.
        let dreq = FbsDelegateRequest::create(
            &mut b,
            &DelegateRequestArgs {
                delegate_request_type: DelegateRequestType(99),
                delegate_request: Some(unreg.as_union_value()),
            },
        );
        let creq = FbsClientRequest::create(
            &mut b,
            &ClientRequestArgs {
                client_request_type: ClientRequestType::DelegateRequest,
                client_request: Some(dreq.as_union_value()),
            },
        );
        finish_client_request_buffer(&mut b, creq);
        let bytes = b.finished_data().to_vec();

        let client =
            root_as_client_request(&bytes).expect("verifier accepts an unknown union discriminant");
        let fbs_delegate = client
            .client_request_as_delegate_request()
            .expect("client_request is a DelegateRequest");
        let decoded = DelegateRequest::try_decode_fbs(&fbs_delegate);
        assert!(
            decoded.is_err(),
            "an unknown DelegateRequestType discriminant must be a clean \
             per-request error, never a panic that downs the connection handler"
        );
    }
}

/// Hardening pins for the flatbuffers decode boundary.
///
/// Every test here exists because a real decode site panicked, or silently
/// produced a wrong value, on input a client can actually send. The boundary
/// has exactly one entry point — [`ClientRequest::try_decode_fbs`] over
/// `root_as_client_request` — so these drive the real entry point rather than
/// an inner decoder wherever possible.
///
/// Two facts about the flatbuffers verifier make this whole class possible, and
/// both are load-bearing for every test below:
///
/// 1. A `(required)` vector is checked for PRESENCE, not LENGTH
///    (`Verifiable for Vector<T>` runs `verify_vector_range` and stops there).
/// 2. Every generated union verifier ends in `_ => Ok(())`, so an unknown
///    discriminant — including `NONE` — reaches the decoder's match.
#[cfg(test)]
mod fbs_decode_hardening {
    use super::{ClientRequest, ContractRequest};
    use crate::client_api::TryFromFbs;
    use crate::contract_interface::UpdateData;
    use crate::generated::client_request::{
        finish_client_request_buffer, ApplicationMessages, ApplicationMessagesArgs,
        ClientRequest as FbsClientRequest, ClientRequestArgs, ClientRequestType,
        ContractRequest as FbsContractRequest, ContractRequestArgs, ContractRequestType,
        DelegateCode as FbsDelegateCode, DelegateCodeArgs,
        DelegateContainer as FbsDelegateContainer, DelegateContainerArgs,
        DelegateKey as FbsDelegateKey, DelegateKeyArgs, DelegateRequest as FbsDelegateRequest,
        DelegateRequestArgs, DelegateRequestType, DelegateType, Get as FbsGet, GetArgs,
        InboundDelegateMsg as FbsInboundDelegateMsg, InboundDelegateMsgArgs,
        InboundDelegateMsgType, Put as FbsPut, PutArgs, RegisterDelegate, RegisterDelegateArgs,
        RelatedContract, RelatedContractArgs, RelatedContracts as FbsRelatedContracts,
        RelatedContractsArgs, Update as FbsUpdate, UpdateArgs, WasmDelegateV1, WasmDelegateV1Args,
    };
    use crate::generated::common::{
        ApplicationMessage as FbsApplicationMessage, ApplicationMessageArgs,
        ContractCode as FbsContractCode, ContractCodeArgs,
        ContractContainer as FbsContractContainer, ContractContainerArgs,
        ContractInstanceId as FbsContractInstanceId, ContractInstanceIdArgs,
        ContractKey as FbsContractKey, ContractKeyArgs, ContractType, RelatedDeltaUpdate,
        RelatedDeltaUpdateArgs, RelatedStateAndDeltaUpdate, RelatedStateAndDeltaUpdateArgs,
        RelatedStateUpdate, RelatedStateUpdateArgs, StateUpdate, StateUpdateArgs,
        UpdateData as FbsUpdateData, UpdateDataArgs, UpdateDataType, WasmContractV1,
        WasmContractV1Args,
    };

    type Builder<'a> = flatbuffers::FlatBufferBuilder<'a>;

    /// The instance id the tests round-trip. Deliberately NOT all-ASCII: this is
    /// what a real 32-byte id looks like, and it is precisely what the old
    /// base58 decode choked on.
    const INSTANCE: [u8; 32] = [
        0x00, 0xff, 0x7a, 0x01, 0x30, 0x4f, 0x49, 0x6c, 0x2b, 0x2f, 0x5c, 0x7f, 0x80, 0xfe, 0x10,
        0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
        0x20, 0x21,
    ];
    const CODE_HASH: [u8; 32] = [42u8; 32];

    fn instance_offset<'a>(
        b: &mut Builder<'a>,
        bytes: &[u8],
    ) -> flatbuffers::WIPOffset<FbsContractInstanceId<'a>> {
        let data = b.create_vector(bytes);
        FbsContractInstanceId::create(b, &ContractInstanceIdArgs { data: Some(data) })
    }

    fn key_offset<'a>(
        b: &mut Builder<'a>,
        instance: &[u8],
        code: &[u8],
    ) -> flatbuffers::WIPOffset<FbsContractKey<'a>> {
        let instance = instance_offset(b, instance);
        let code = b.create_vector(code);
        FbsContractKey::create(
            b,
            &ContractKeyArgs {
                instance: Some(instance),
                code: Some(code),
            },
        )
    }

    fn delegate_key_offset<'a>(
        b: &mut Builder<'a>,
        key: &[u8],
        code_hash: &[u8],
    ) -> flatbuffers::WIPOffset<FbsDelegateKey<'a>> {
        let key = b.create_vector(key);
        let code_hash = b.create_vector(code_hash);
        FbsDelegateKey::create(
            b,
            &DelegateKeyArgs {
                key: Some(key),
                code_hash: Some(code_hash),
            },
        )
    }

    /// Finish a `ContractRequest`-carrying `ClientRequest` and return its bytes.
    fn finish_contract(
        b: &mut Builder<'_>,
        ty: ContractRequestType,
        req: flatbuffers::WIPOffset<flatbuffers::UnionWIPOffset>,
    ) -> Vec<u8> {
        let contract = FbsContractRequest::create(
            b,
            &ContractRequestArgs {
                contract_request_type: ty,
                contract_request: Some(req),
            },
        );
        let client = FbsClientRequest::create(
            b,
            &ClientRequestArgs {
                client_request_type: ClientRequestType::ContractRequest,
                client_request: Some(contract.as_union_value()),
            },
        );
        finish_client_request_buffer(b, client);
        b.finished_data().to_vec()
    }

    fn finish_delegate(
        b: &mut Builder<'_>,
        ty: DelegateRequestType,
        req: flatbuffers::WIPOffset<flatbuffers::UnionWIPOffset>,
    ) -> Vec<u8> {
        let delegate = FbsDelegateRequest::create(
            b,
            &DelegateRequestArgs {
                delegate_request_type: ty,
                delegate_request: Some(req),
            },
        );
        let client = FbsClientRequest::create(
            b,
            &ClientRequestArgs {
                client_request_type: ClientRequestType::DelegateRequest,
                client_request: Some(delegate.as_union_value()),
            },
        );
        finish_client_request_buffer(b, client);
        b.finished_data().to_vec()
    }

    // ---------------------------------------------------------------------
    // Per-union builders. Each produces a well-formed request whose ONE named
    // union discriminant is `d`, so a test can sweep `d` while everything else
    // stays valid.
    // ---------------------------------------------------------------------

    fn client_request_type(d: u8, force_defaults: bool) -> Vec<u8> {
        let mut b = Builder::new();
        b.force_defaults(force_defaults);
        let key = key_offset(&mut b, &INSTANCE, &CODE_HASH);
        let get = FbsGet::create(
            &mut b,
            &GetArgs {
                key: Some(key),
                fetch_contract: false,
                subscribe: false,
                blocking_subscribe: false,
            },
        );
        let contract = FbsContractRequest::create(
            &mut b,
            &ContractRequestArgs {
                contract_request_type: ContractRequestType::Get,
                contract_request: Some(get.as_union_value()),
            },
        );
        let client = FbsClientRequest::create(
            &mut b,
            &ClientRequestArgs {
                client_request_type: ClientRequestType(d),
                client_request: Some(contract.as_union_value()),
            },
        );
        finish_client_request_buffer(&mut b, client);
        b.finished_data().to_vec()
    }

    fn contract_request_type(d: u8, force_defaults: bool) -> Vec<u8> {
        let mut b = Builder::new();
        b.force_defaults(force_defaults);
        let key = key_offset(&mut b, &INSTANCE, &CODE_HASH);
        let get = FbsGet::create(
            &mut b,
            &GetArgs {
                key: Some(key),
                fetch_contract: false,
                subscribe: false,
                blocking_subscribe: false,
            },
        );
        finish_contract(&mut b, ContractRequestType(d), get.as_union_value())
    }

    fn delegate_request_type(d: u8, force_defaults: bool) -> Vec<u8> {
        let mut b = Builder::new();
        b.force_defaults(force_defaults);
        let dk = delegate_key_offset(&mut b, &[7u8; 32], &CODE_HASH);
        let params = b.create_vector(&[1u8, 2, 3]);
        let payload = b.create_vector(&[9u8; 4]);
        let context = b.create_vector(&[0u8; 2]);
        let app = FbsApplicationMessage::create(
            &mut b,
            &ApplicationMessageArgs {
                payload: Some(payload),
                context: Some(context),
                processed: false,
            },
        );
        let inbound_msg = FbsInboundDelegateMsg::create(
            &mut b,
            &InboundDelegateMsgArgs {
                inbound_type: InboundDelegateMsgType::common_ApplicationMessage,
                inbound: Some(app.as_union_value()),
            },
        );
        let inbound = b.create_vector(&[inbound_msg]);
        let msgs = ApplicationMessages::create(
            &mut b,
            &ApplicationMessagesArgs {
                key: Some(dk),
                params: Some(params),
                inbound: Some(inbound),
            },
        );
        finish_delegate(&mut b, DelegateRequestType(d), msgs.as_union_value())
    }

    /// A PUT whose `common.ContractContainer` union discriminant is `d`.
    fn contract_type(d: u8, force_defaults: bool) -> Vec<u8> {
        let mut b = Builder::new();
        b.force_defaults(force_defaults);
        let code_data = b.create_vector(&[0u8; 8]);
        let code_hash = b.create_vector(&CODE_HASH);
        let code = FbsContractCode::create(
            &mut b,
            &ContractCodeArgs {
                data: Some(code_data),
                code_hash: Some(code_hash),
            },
        );
        let key = key_offset(&mut b, &INSTANCE, &CODE_HASH);
        let params = b.create_vector(&[1u8, 2]);
        let wasm = WasmContractV1::create(
            &mut b,
            &WasmContractV1Args {
                data: Some(code),
                parameters: Some(params),
                key: Some(key),
            },
        );
        let container = FbsContractContainer::create(
            &mut b,
            &ContractContainerArgs {
                contract_type: ContractType(d),
                contract: Some(wasm.as_union_value()),
            },
        );
        let state = b.create_vector(&[3u8; 4]);
        let empty: Vec<flatbuffers::WIPOffset<RelatedContract>> = vec![];
        let contracts = b.create_vector(&empty);
        let related = FbsRelatedContracts::create(
            &mut b,
            &RelatedContractsArgs {
                contracts: Some(contracts),
            },
        );
        let put = FbsPut::create(
            &mut b,
            &PutArgs {
                container: Some(container),
                wrapped_state: Some(state),
                related_contracts: Some(related),
                subscribe: false,
                blocking_subscribe: false,
            },
        );
        finish_contract(&mut b, ContractRequestType::Put, put.as_union_value())
    }

    /// A RegisterDelegate whose `DelegateContainer` union discriminant is `d`.
    fn delegate_type(d: u8, force_defaults: bool) -> Vec<u8> {
        let mut b = Builder::new();
        b.force_defaults(force_defaults);
        let code_data = b.create_vector(&[0u8; 8]);
        let code_hash = b.create_vector(&CODE_HASH);
        let code = FbsDelegateCode::create(
            &mut b,
            &DelegateCodeArgs {
                data: Some(code_data),
                code_hash: Some(code_hash),
            },
        );
        let dk = delegate_key_offset(&mut b, &[7u8; 32], &CODE_HASH);
        let params = b.create_vector(&[1u8, 2]);
        let wasm = WasmDelegateV1::create(
            &mut b,
            &WasmDelegateV1Args {
                parameters: Some(params),
                data: Some(code),
                key: Some(dk),
            },
        );
        let container = FbsDelegateContainer::create(
            &mut b,
            &DelegateContainerArgs {
                delegate_type: DelegateType(d),
                delegate: Some(wasm.as_union_value()),
            },
        );
        let cipher = b.create_vector(&[1u8; 32]);
        let nonce = b.create_vector(&[2u8; 24]);
        let register = RegisterDelegate::create(
            &mut b,
            &RegisterDelegateArgs {
                delegate: Some(container),
                cipher: Some(cipher),
                nonce: Some(nonce),
            },
        );
        finish_delegate(
            &mut b,
            DelegateRequestType::RegisterDelegate,
            register.as_union_value(),
        )
    }

    /// An UPDATE whose `common.UpdateData` union discriminant is `d`.
    fn update_data_type(d: u8, force_defaults: bool) -> Vec<u8> {
        let mut b = Builder::new();
        b.force_defaults(force_defaults);
        let state = b.create_vector(&[5u8; 4]);
        let state_update = StateUpdate::create(&mut b, &StateUpdateArgs { state: Some(state) });
        let data = FbsUpdateData::create(
            &mut b,
            &UpdateDataArgs {
                update_data_type: UpdateDataType(d),
                update_data: Some(state_update.as_union_value()),
            },
        );
        let key = key_offset(&mut b, &INSTANCE, &CODE_HASH);
        let update = FbsUpdate::create(
            &mut b,
            &UpdateArgs {
                key: Some(key),
                data: Some(data),
            },
        );
        finish_contract(&mut b, ContractRequestType::Update, update.as_union_value())
    }

    /// An ApplicationMessages whose `InboundDelegateMsg` union discriminant is `d`.
    fn inbound_delegate_msg_type(d: u8, force_defaults: bool) -> Vec<u8> {
        let mut b = Builder::new();
        b.force_defaults(force_defaults);
        let payload = b.create_vector(&[9u8; 4]);
        let context = b.create_vector(&[0u8; 2]);
        let app = FbsApplicationMessage::create(
            &mut b,
            &ApplicationMessageArgs {
                payload: Some(payload),
                context: Some(context),
                processed: false,
            },
        );
        let inbound_msg = FbsInboundDelegateMsg::create(
            &mut b,
            &InboundDelegateMsgArgs {
                inbound_type: InboundDelegateMsgType(d),
                inbound: Some(app.as_union_value()),
            },
        );
        let inbound = b.create_vector(&[inbound_msg]);
        let dk = delegate_key_offset(&mut b, &[7u8; 32], &CODE_HASH);
        let params = b.create_vector(&[1u8, 2, 3]);
        let msgs = ApplicationMessages::create(
            &mut b,
            &ApplicationMessagesArgs {
                key: Some(dk),
                params: Some(params),
                inbound: Some(inbound),
            },
        );
        finish_delegate(
            &mut b,
            DelegateRequestType::ApplicationMessages,
            msgs.as_union_value(),
        )
    }

    /// `(union name, builder, the union's real discriminant)`.
    type UnionCase = (&'static str, fn(u8, bool) -> Vec<u8>, u8);

    /// **No union discriminant, for any of the seven unions on the decode path,
    /// may panic the decoder.**
    ///
    /// One sweep covering every union at once. Four of the seven were
    /// `unreachable!()` before this change, and all four are reachable: the
    /// generated verifiers end in `_ => Ok(())`, so an unrecognized discriminant
    /// passes verification and lands in the decoder's match.
    ///
    /// Scope, stated honestly: this covers a new *variant* on an existing union
    /// for free, but NOT a new *union* — `cases` and its builders are written by
    /// hand. `union_matches_never_use_unreachable` is the guard for that case.
    ///
    /// Four properties are pinned per union, and the third is the one that keeps
    /// the other three honest:
    ///
    /// - The 0..=255 sweep RETURNS. A panic anywhere inside fails the test.
    /// - An out-of-range discriminant is a clean error.
    /// - That error came from the DECODER, not the verifier. Without this the
    ///   sweep silently degrades to zero decoder coverage the moment a schema or
    ///   builder change makes verification fail earlier — which is exactly what
    ///   had happened to the NONE case below.
    /// - The real discriminant still decodes, so the guard did not break the
    ///   happy path.
    #[test]
    fn no_union_discriminant_panics_the_decoder() {
        let cases: [UnionCase; 7] = [
            ("ClientRequestType", client_request_type, 1),
            ("ContractRequestType", contract_request_type, 3),
            ("DelegateRequestType", delegate_request_type, 1),
            ("ContractType", contract_type, 1),
            ("DelegateType", delegate_type, 1),
            ("UpdateDataType", update_data_type, 1),
            (
                "InboundDelegateMsgType",
                inbound_delegate_msg_type,
                InboundDelegateMsgType::common_ApplicationMessage.0,
            ),
        ];

        for (union, build, valid) in cases {
            for d in 0..=u8::MAX {
                // Must return, never panic. A mismatched-but-known discriminant
                // may be rejected by the verifier rather than the decoder;
                // either is a clean error and both are acceptable here.
                let bytes = build(d, false);
                let _ = ClientRequest::try_decode_fbs(&bytes);
            }

            // An out-of-range discriminant must be rejected BY THE DECODER.
            // Asserting only `is_err()` would also pass on a verifier
            // rejection, which reaches none of the code this change touches.
            let out_of_range = build(200, false);
            let err = ClientRequest::try_decode_fbs(&out_of_range)
                .expect_err("{union}: an out-of-range discriminant must be a clean error");
            assert_eq!(
                err.to_string(),
                format!(
                    "Failed decoding message from client request: unknown {union} \
                     discriminant: 200"
                ),
                "{union}: the error must come from the decoder's union arm, not \
                 from the verifier — otherwise this sweep pins nothing"
            );

            // `NONE` needs `force_defaults`: both builders elide a field equal
            // to its default, so an ordinary `NONE` is written as ABSENT and
            // `visit_union` rejects the present-value/absent-type pair before
            // any decoder runs. Forcing defaults writes the zero explicitly,
            // which is the shape a non-flatc encoder can put on the wire and
            // the only one that actually reaches the match arm.
            let none = build(0, true);
            let err = ClientRequest::try_decode_fbs(&none)
                .expect_err("{union}: a NONE discriminant must be a clean error");
            assert_eq!(
                err.to_string(),
                format!(
                    "Failed decoding message from client request: unknown {union} \
                     discriminant: 0"
                ),
                "{union}: an explicit NONE must reach the decoder's union arm"
            );

            let good = build(valid, false);
            assert!(
                ClientRequest::try_decode_fbs(&good).is_ok(),
                "{union}: the real discriminant must still decode; the guard \
                 must not break the happy path"
            );
        }
    }

    // ---------------------------------------------------------------------
    // Per-site pins. Each of these fails if its own decode site is reverted,
    // so a partial revert cannot leave the suite green — the failure mode #85
    // shipped with, where the fix reached three call sites and only one was
    // pinned.
    // ---------------------------------------------------------------------

    /// Build an UPDATE carrying one of the three `related_*` update variants,
    /// with `id` as the raw `related_to` bytes.
    fn update_with_related(variant: UpdateDataType, id: &[u8]) -> Vec<u8> {
        let mut b = Builder::new();
        let related_to = instance_offset(&mut b, id);
        let payload = b.create_vector(&[5u8; 4]);
        let data_offset = match variant {
            UpdateDataType::RelatedStateUpdate => RelatedStateUpdate::create(
                &mut b,
                &RelatedStateUpdateArgs {
                    related_to: Some(related_to),
                    state: Some(payload),
                },
            )
            .as_union_value(),
            UpdateDataType::RelatedDeltaUpdate => RelatedDeltaUpdate::create(
                &mut b,
                &RelatedDeltaUpdateArgs {
                    related_to: Some(related_to),
                    delta: Some(payload),
                },
            )
            .as_union_value(),
            UpdateDataType::RelatedStateAndDeltaUpdate => {
                let delta = b.create_vector(&[6u8; 4]);
                RelatedStateAndDeltaUpdate::create(
                    &mut b,
                    &RelatedStateAndDeltaUpdateArgs {
                        related_to: Some(related_to),
                        state: Some(payload),
                        delta: Some(delta),
                    },
                )
                .as_union_value()
            }
            other => panic!("not a related update variant: {}", other.0),
        };
        let data = FbsUpdateData::create(
            &mut b,
            &UpdateDataArgs {
                update_data_type: variant,
                update_data: Some(data_offset),
            },
        );
        let key = key_offset(&mut b, &INSTANCE, &CODE_HASH);
        let update = FbsUpdate::create(
            &mut b,
            &UpdateArgs {
                key: Some(key),
                data: Some(data),
            },
        );
        finish_contract(&mut b, ContractRequestType::Update, update.as_union_value())
    }

    fn decoded_related_to(bytes: &[u8]) -> [u8; 32] {
        let req = ClientRequest::try_decode_fbs(bytes)
            .expect("a well-formed related update must decode, not panic");
        let ClientRequest::ContractOp(ContractRequest::Update { data, .. }) = req else {
            panic!("expected an UPDATE, got {req:?}");
        };
        match data {
            UpdateData::RelatedState { related_to, .. }
            | UpdateData::RelatedDelta { related_to, .. }
            | UpdateData::RelatedStateAndDelta { related_to, .. } => *related_to,
            other => panic!("expected a related update, got {other:?}"),
        }
    }

    /// `related_to` is 32 RAW bytes and must round-trip byte-for-byte.
    ///
    /// This decode used to be `ContractInstanceId::from_bytes(..).unwrap()` —
    /// a base58 *string* decoder pointed at bytes that are already the final
    /// id. It did not merely mishandle malformed input: a random 32-byte id
    /// essentially never consists solely of base58 characters, so EVERY
    /// well-formed related update panicked the connection task. `INSTANCE`
    /// contains `0x00`, `0xff` and the base58-excluded `0`/`O`/`I`/`l`
    /// characters precisely so a revert cannot pass by luck.
    #[test]
    fn related_state_update_round_trips_the_raw_instance_id() {
        let bytes = update_with_related(UpdateDataType::RelatedStateUpdate, &INSTANCE);
        assert_eq!(decoded_related_to(&bytes), INSTANCE);
    }

    #[test]
    fn related_delta_update_round_trips_the_raw_instance_id() {
        let bytes = update_with_related(UpdateDataType::RelatedDeltaUpdate, &INSTANCE);
        assert_eq!(decoded_related_to(&bytes), INSTANCE);
    }

    #[test]
    fn related_state_and_delta_update_round_trips_the_raw_instance_id() {
        let bytes = update_with_related(UpdateDataType::RelatedStateAndDeltaUpdate, &INSTANCE);
        assert_eq!(decoded_related_to(&bytes), INSTANCE);
    }

    /// A wrong-length `related_to` is a clean error naming the field, not a
    /// panic and not a silently truncated id.
    ///
    /// Parameterized over all three variants: with one case, copy-pasting the
    /// wrong variant's field name into the other two arms would fail nothing.
    #[test]
    fn related_to_wrong_length_is_rejected() {
        for (variant, field) in [
            (
                UpdateDataType::RelatedStateUpdate,
                "RelatedStateUpdate.related_to.data",
            ),
            (
                UpdateDataType::RelatedDeltaUpdate,
                "RelatedDeltaUpdate.related_to.data",
            ),
            (
                UpdateDataType::RelatedStateAndDeltaUpdate,
                "RelatedStateAndDeltaUpdate.related_to.data",
            ),
        ] {
            let bytes = update_with_related(variant, &[1u8; 8]);
            let err = ClientRequest::try_decode_fbs(&bytes)
                .expect_err("an 8-byte related_to must be rejected");
            let msg = err.to_string();
            assert!(
                msg.contains(field) && msg.contains("got 8 bytes"),
                "the error must name {field} and the observed length, got: {msg}"
            );
        }
    }

    fn put_with_related_contract(id: &[u8]) -> Vec<u8> {
        let mut b = Builder::new();
        let code_data = b.create_vector(&[0u8; 8]);
        let code_hash = b.create_vector(&CODE_HASH);
        let code = FbsContractCode::create(
            &mut b,
            &ContractCodeArgs {
                data: Some(code_data),
                code_hash: Some(code_hash),
            },
        );
        let key = key_offset(&mut b, &INSTANCE, &CODE_HASH);
        let params = b.create_vector(&[1u8, 2]);
        let wasm = WasmContractV1::create(
            &mut b,
            &WasmContractV1Args {
                data: Some(code),
                parameters: Some(params),
                key: Some(key),
            },
        );
        let container = FbsContractContainer::create(
            &mut b,
            &ContractContainerArgs {
                contract_type: ContractType::WasmContractV1,
                contract: Some(wasm.as_union_value()),
            },
        );
        let related_id = instance_offset(&mut b, id);
        let related_state = b.create_vector(&[8u8; 3]);
        let related_contract = RelatedContract::create(
            &mut b,
            &RelatedContractArgs {
                instance_id: Some(related_id),
                state: Some(related_state),
            },
        );
        let contracts = b.create_vector(&[related_contract]);
        let related = FbsRelatedContracts::create(
            &mut b,
            &RelatedContractsArgs {
                contracts: Some(contracts),
            },
        );
        let state = b.create_vector(&[3u8; 4]);
        let put = FbsPut::create(
            &mut b,
            &PutArgs {
                container: Some(container),
                wrapped_state: Some(state),
                related_contracts: Some(related),
                subscribe: false,
                blocking_subscribe: false,
            },
        );
        finish_contract(&mut b, ContractRequestType::Put, put.as_union_value())
    }

    /// The same base58 bug lived on the PUT path, in `RelatedContracts`. It went
    /// unnoticed because the loop body only runs when the vector is NON-empty,
    /// and the TypeScript suite's PUT fixture passes `new RelatedContractsT([])`.
    #[test]
    fn put_related_contract_round_trips_the_raw_instance_id() {
        let bytes = put_with_related_contract(&INSTANCE);
        let req = ClientRequest::try_decode_fbs(&bytes)
            .expect("a PUT carrying a related contract must decode, not panic");
        let ClientRequest::ContractOp(ContractRequest::Put {
            related_contracts, ..
        }) = req
        else {
            panic!("expected a PUT, got {req:?}");
        };
        let ids: Vec<[u8; 32]> = related_contracts
            .into_owned()
            .states()
            .map(|(id, _)| **id)
            .collect();
        assert_eq!(
            ids,
            vec![INSTANCE],
            "the related contract id must round-trip"
        );
    }

    #[test]
    fn put_related_contract_wrong_length_id_is_rejected() {
        let bytes = put_with_related_contract(&[1u8; 8]);
        let err = ClientRequest::try_decode_fbs(&bytes)
            .expect_err("an 8-byte related contract id must be rejected");
        let msg = err.to_string();
        assert!(
            msg.contains("RelatedContract.instance_id") && msg.contains("got 8 bytes"),
            "got: {msg}"
        );
    }

    fn unregister_delegate(key_len: usize) -> Vec<u8> {
        use crate::generated::client_request::{UnregisterDelegate, UnregisterDelegateArgs};
        let mut b = Builder::new();
        let dk = delegate_key_offset(&mut b, &vec![7u8; key_len], &CODE_HASH);
        let unregister =
            UnregisterDelegate::create(&mut b, &UnregisterDelegateArgs { key: Some(dk) });
        finish_delegate(
            &mut b,
            DelegateRequestType::UnregisterDelegate,
            unregister.as_union_value(),
        )
    }

    /// `DelegateKey.key` is `(required)` but length-unchecked by the verifier,
    /// and the decoder used to `copy_from_slice` it into a `[0; 32]` — which
    /// panics on a mismatch. This is the normal delegate path, and the
    /// TypeScript SDK exports `DelegateKey` as the raw generated type with no
    /// length validation (unlike `ContractKey`, which throws a `TypeError`).
    #[test]
    fn delegate_key_wrong_length_is_rejected_not_panicking() {
        let short = unregister_delegate(8);
        let err = ClientRequest::try_decode_fbs(&short)
            .expect_err("an 8-byte delegate key must be rejected");
        let msg = err.to_string();
        assert!(
            msg.contains("DelegateKey.key") && msg.contains("got 8 bytes"),
            "got: {msg}"
        );

        let long = unregister_delegate(64);
        let err = ClientRequest::try_decode_fbs(&long)
            .expect_err("a 64-byte delegate key must be rejected");
        assert!(err.to_string().contains("got 64 bytes"), "got: {err}");

        let good = unregister_delegate(32);
        assert!(
            ClientRequest::try_decode_fbs(&good).is_ok(),
            "a 32-byte delegate key must still decode"
        );
    }

    fn register_delegate(cipher_len: usize, nonce_len: usize) -> Vec<u8> {
        let mut b = Builder::new();
        let code_data = b.create_vector(&[0u8; 8]);
        let code_hash = b.create_vector(&CODE_HASH);
        let code = FbsDelegateCode::create(
            &mut b,
            &DelegateCodeArgs {
                data: Some(code_data),
                code_hash: Some(code_hash),
            },
        );
        let dk = delegate_key_offset(&mut b, &[7u8; 32], &CODE_HASH);
        let params = b.create_vector(&[1u8, 2]);
        let wasm = WasmDelegateV1::create(
            &mut b,
            &WasmDelegateV1Args {
                parameters: Some(params),
                data: Some(code),
                key: Some(dk),
            },
        );
        let container = FbsDelegateContainer::create(
            &mut b,
            &DelegateContainerArgs {
                delegate_type: DelegateType::WasmDelegateV1,
                delegate: Some(wasm.as_union_value()),
            },
        );
        let cipher = b.create_vector(&vec![1u8; cipher_len]);
        let nonce = b.create_vector(&vec![2u8; nonce_len]);
        let register = RegisterDelegate::create(
            &mut b,
            &RegisterDelegateArgs {
                delegate: Some(container),
                cipher: Some(cipher),
                nonce: Some(nonce),
            },
        );
        finish_delegate(
            &mut b,
            DelegateRequestType::RegisterDelegate,
            register.as_union_value(),
        )
    }

    /// `cipher` (32) and `nonce` (24) are the same shape: `(required)`, so the
    /// verifier guarantees presence and nothing about length, and the decoder
    /// used to `try_from(..).unwrap()` them.
    #[test]
    fn register_delegate_wrong_length_cipher_or_nonce_is_rejected() {
        let err = ClientRequest::try_decode_fbs(&register_delegate(16, 24))
            .expect_err("a 16-byte cipher must be rejected");
        let msg = err.to_string();
        assert!(
            msg.contains("RegisterDelegate.cipher") && msg.contains("got 16 bytes"),
            "got: {msg}"
        );

        let err = ClientRequest::try_decode_fbs(&register_delegate(32, 8))
            .expect_err("an 8-byte nonce must be rejected");
        let msg = err.to_string();
        assert!(
            msg.contains("RegisterDelegate.nonce") && msg.contains("got 8 bytes"),
            "got: {msg}"
        );

        assert!(
            ClientRequest::try_decode_fbs(&register_delegate(32, 24)).is_ok(),
            "correct cipher/nonce lengths must still decode"
        );
    }

    /// The ENCODE half of the same bug: `HostResponse`'s three related-update
    /// variants wrote `related_to.encode()` — base58 TEXT — into
    /// `common.ContractInstanceId.data`, a field every other producer and every
    /// consumer treats as 32 raw bytes.
    ///
    /// It survived because Rust only encodes host responses and only TypeScript
    /// decodes them, so no Rust round-trip test ever crossed it, and the
    /// TypeScript SDK has no test that reads `relatedTo` back out of a
    /// notification. Pinned here by decoding the encoder's own output, which is
    /// the cheapest thing that would have caught it.
    #[test]
    fn host_response_encodes_related_to_as_raw_bytes() {
        use crate::client_api::{ContractResponse, HostResponse};
        use crate::contract_interface::{ContractInstanceId, ContractKey, State};
        use crate::generated::host_response::{root_as_host_response, ContractResponseType};

        let related = ContractInstanceId::new(INSTANCE);
        let key = ContractKey::from_params_and_code(
            crate::parameters::Parameters::from(vec![1u8, 2]),
            crate::contract_interface::ContractCode::from(vec![0u8; 8]),
        );
        let response = HostResponse::ContractResponse(ContractResponse::UpdateNotification {
            key,
            update: UpdateData::RelatedState {
                related_to: related,
                state: State::from(vec![9u8; 4]),
            },
        });

        let bytes = response.into_fbs_bytes().expect("encoding must succeed");
        let host = root_as_host_response(&bytes).expect("the encoder must emit a valid buffer");
        let contract = host
            .response_as_contract_response()
            .expect("a ContractResponse");
        assert_eq!(
            contract.contract_response_type(),
            ContractResponseType::UpdateNotification
        );
        let notification = contract
            .contract_response_as_update_notification()
            .expect("an UpdateNotification");
        let related_update = notification
            .update()
            .update_data_as_related_state_update()
            .expect("a RelatedStateUpdate");

        assert_eq!(
            related_update.related_to().data().bytes(),
            &INSTANCE,
            "related_to must be the 32 RAW id bytes. Encoding it as base58 text \
             puts ~44 ASCII bytes in a field the TypeScript SDK reads as a raw \
             Uint8Array, and that our own decoder now rejects."
        );
    }

    /// `SecretsId::try_decode_fbs` has no production caller today, so it is
    /// pinned directly rather than through a request. Fixing it now means the
    /// first client to reach it does not find a panic waiting.
    #[test]
    fn secrets_id_wrong_length_hash_is_rejected_not_panicking() {
        use crate::delegate_interface::SecretsId;
        use crate::generated::common::{SecretsId as FbsSecretsId, SecretsIdArgs};

        let build = |hash_len: usize| {
            let mut b = Builder::new();
            let key = b.create_vector(&[1u8, 2, 3]);
            let hash = b.create_vector(&vec![4u8; hash_len]);
            let id = FbsSecretsId::create(
                &mut b,
                &SecretsIdArgs {
                    key: Some(key),
                    hash: Some(hash),
                },
            );
            b.finish_minimal(id);
            b.finished_data().to_vec()
        };

        let bytes = build(8);
        let fbs = flatbuffers::root::<FbsSecretsId>(&bytes)
            .expect("the verifier accepts a short required vector");
        let err = SecretsId::try_decode_fbs(&fbs).expect_err("an 8-byte hash must be rejected");
        assert!(
            err.to_string().contains("SecretsId.hash") && err.to_string().contains("got 8 bytes"),
            "got: {err}"
        );

        let bytes = build(32);
        let fbs = flatbuffers::root::<FbsSecretsId>(&bytes).expect("well-formed");
        assert!(
            SecretsId::try_decode_fbs(&fbs).is_ok(),
            "a 32-byte hash must still decode"
        );
    }
}