nros_rmw_cffi/

rust_adapter.rs

//! Phase 115.L.0 — Generic Rust-trait → C-vtable adapter.
//!
//! `RustBackendAdapter<R>` converts any `R: nros_rmw::Rmw` whose
//! associated types implement the matching `Session` / `Publisher` /
//! `Subscription` / `ServiceTrait` / `ClientTrait` traits
//! into a `static NrosRmwVtable`. Each per-backend cffi crate then
//! collapses to ~10 LOC:
//!
//! ```ignore
//! #[unsafe(no_mangle)]
//! pub extern "C" fn nros_rmw_zenoh_register() -> nros_rmw_cffi::NrosRmwRet {
//!     nros_rmw_cffi::RustBackendAdapter::<nros_rmw_zenoh::ZenohRmw>::register()
//! }
//! ```
//!
//! # Storage discipline
//!
//! - Session: boxed (fallibly, via `box_handle` — issue 1551) and stashed in
//!   `NrosRmwSession::backend_data`. `close` reclaims via
//!   `Box::from_raw` (drops the box, runs `Drop`, frees the alloc).
//! - Publisher / Subscription / Service / Client: same
//!   pattern with their respective handle types.
//!
//! # 'static
//!
//! Every handle must be `'static` (the `Box` outlives the call). We
//! deliberately do **not** require `Send`: the C runtime hands the
//! `backend_data` pointer back to the same caller that minted it,
//! and the executor's single-thread-per-session invariant matches
//! the Rust trait surface. Zenoh-pico's `ZenohSession`, for
//! instance, holds an unmovable `*const Context` which the
//! upstream library does not mark `Send`.
//!
//! # Bounds
//!
//! All error types must be `TransportError` (or `Into<TransportError>`).
//! This matches every in-tree backend today.

extern crate alloc;

use alloc::boxed::Box;
use core::{
    ffi::{c_char, c_void},
    marker::PhantomData,
};

use nros_rmw::{
    ClientTrait, Publisher, QoSProfile, Rmw, RmwConfig, ServiceTrait, Session, SessionMode,
    Subscription, TopicInfo, TransportError,
};

use crate::{
    EMPTY_VTABLE, MAX_SESSION_PROPERTIES, NROS_RMW_RET_BAD_ALLOC, NROS_RMW_RET_INVALID_ARGUMENT,
    NROS_RMW_RET_OK, NROS_RMW_RET_UNSUPPORTED, NrosRmwClient, NrosRmwEventCallback,
    NrosRmwEventKind, NrosRmwGid, NrosRmwNode, NrosRmwPublisher, NrosRmwQos, NrosRmwRet,
    NrosRmwService, NrosRmwSession, NrosRmwSessionOptions, NrosRmwSubscription, NrosRmwVtable,
    entity_wake::{EntityWakeCb, Hosted},
    event_kind_from_c, ret_from_error, rmw_publisher_options_t, rmw_subscription_options_t,
};
// phase-381 W3 — the endpoint-info slots marshal the generated ABI types
// directly. Imported from `generated` rather than re-exported through the crate
// root: these are bindgen output and the root deliberately re-exports only the
// hand-maintained surface.
use crate::generated::{
    NROS_RMW_DURABILITY_UNKNOWN, NROS_RMW_HISTORY_UNKNOWN, NROS_RMW_RELIABILITY_UNKNOWN,
    rmw_endpoint_type_t, rmw_gid_t, rmw_liveliness_kind_t, rmw_qos_profile_t,
    rmw_topic_endpoint_info_t,
};

#[cfg(all(target_os = "none", not(feature = "std")))]
mod static_subscriber_storage {
    use core::{cell::UnsafeCell, mem, ptr};

    use portable_atomic::{AtomicBool, Ordering};

    // Issue 0269 — the pool size is build-time configurable via
    // `NROS_RMW_SUBSCRIBER_SLOTS` (build.rs, default 8). The old
    // hardcoded 4 silently capped every embedded session at four
    // subscriptions: the fifth `create_subscription` hit the exhausted
    // pool, returned BAD_ALLOC, and the executor surfaced it as an
    // opaque `SubscriberCreationFailed` (the autoware_sentinel comp-all
    // wall — every std target Boxes instead and never sees a limit).
    const SLOT_COUNT: usize = crate::parse_env_usize(
        env!("NROS_RMW_SUBSCRIBER_SLOTS"),
        "NROS_RMW_SUBSCRIBER_SLOTS must be a decimal integer",
    );
    // issue 1322 — the slot WIDTH, which is a different quantity from the slot
    // COUNT above and now has its own knob. It was a bare `1024`, so the only
    // lever the tree offered against a handle that did not fit was
    // `NROS_RMW_SUBSCRIBER_SLOTS` — which buys more slots of the same too-small
    // width, at `SLOT_SIZE` bytes each, on the platform with the least RAM.
    //
    // AUTHORED, never derived: RFC-0100 D5 rules this out as a sizing input by
    // name, because no user fact answers "how big is a backend's private state
    // struct". So it takes the RFC-0049 ladder (env -> `$DOTCONFIG` ->
    // `[knobs.rmw] subscriber_slot_bytes` -> builtin 1024) and NOT the sizing
    // descriptor — the same shape as `NROS_RUNTIME_COMPONENT_SLOT_BYTES`, which
    // is this quantity one layer up in the component pool.
    const SLOT_SIZE: usize = crate::parse_env_usize(
        env!("NROS_RMW_SUBSCRIBER_SLOT_BYTES"),
        "NROS_RMW_SUBSCRIBER_SLOT_BYTES must be a decimal integer",
    );
    const SLOT_ALIGN: usize = 16;

    #[repr(align(16))]
    struct Slot {
        bytes: UnsafeCell<[u8; SLOT_SIZE]>,
    }

    // Phase 192.5 — `#[repr(align(16))]` can't take the `SLOT_ALIGN` const, so
    // assert they stay in lockstep (the insert() guard compares against SLOT_ALIGN).
    const _: () = assert!(mem::align_of::<Slot>() == SLOT_ALIGN);

    unsafe impl Sync for Slot {}

    impl Slot {
        const fn new() -> Self {
            Self {
                bytes: UnsafeCell::new([0; SLOT_SIZE]),
            }
        }
    }

    // issue 0739 — declare the arithmetic so the pool inventory can price it.
    // 0271 measured this pool at 8,192 bytes on an image that had never heard of
    // the knob. issue 1322 — both factors are knobs now, so the figure stays
    // derivable and the page names the width instead of hiding it in a literal.
    // nros-pool: SLOTS = NROS_RMW_SUBSCRIBER_SLOTS * NROS_RMW_SUBSCRIBER_SLOT_BYTES
    static USED: [AtomicBool; SLOT_COUNT] = [const { AtomicBool::new(false) }; SLOT_COUNT];
    static SLOTS: [Slot; SLOT_COUNT] = [const { Slot::new() }; SLOT_COUNT];

    /// Park `value` in a free slot. `None` means the pool is EXHAUSTED — and
    /// since issue 1322, nothing else.
    ///
    /// It used to mean two unrelated things, and the caller mapped both to
    /// `NROS_RMW_RET_BAD_ALLOC`: every slot claimed (raise
    /// `NROS_RMW_SUBSCRIBER_SLOTS`) *or* `size_of::<T>() > SLOT_SIZE`, which no
    /// value of that knob can fix. So the one remedy the failure pointed at was
    /// the wrong lever for half the failures, and the expensive one.
    ///
    /// The size cause is gone from this return because it was never a runtime
    /// fact. `size_of::<T>()` is known at compile time, so a given build either
    /// fits or never fits; the check is the `const` block below, i.e. a BUILD
    /// error naming the type instead of an image that links, boots, and then
    /// refuses to register a subscription.
    ///
    /// Be precise about WHEN that error arrives: an inline `const` in a generic
    /// fn is evaluated at MONOMORPHISATION, which `cargo check` does not reach
    /// (it emits metadata and never collects instantiations — measured). Any
    /// `cargo build` of a bare-metal image that creates a subscription does.
    /// That is weaker than a source gate and strictly stronger than the
    /// boot-time return it replaces.
    pub unsafe fn insert<T>(value: T) -> Option<*mut T> {
        const {
            // FIT GUARD — issue 1322. RFC-0100 D7's shape: the knob publishes a
            // WIDTH and the FLOOR lives at the pool, which is the only place
            // that can see `T`.
            //
            // Written as a SUBTRACTION rather than an `assert!` because a const
            // panic message cannot be FORMATTED. An assertion can say what to do
            // and never what the numbers are; the underflow diagnostic says both,
            // and the instantiation note names the backend handle. Measured, at
            // `NROS_RMW_SUBSCRIBER_SLOT_BYTES=1` on `thumbv7m-none-eabi`:
            //
            //     error[E0080]: attempt to compute `1_usize - 112_usize`,
            //                   which would overflow
            //     note: ... while instantiating
            //           `fn insert::<ZenohSubscriber>`
            //
            // The BINDING NAMES below are load-bearing, and this is the correction
            // to a first draft that put the remedy in these comments: rustc echoes
            // the offending SOURCE LINE, and it COLLAPSES the rest of the const
            // block to `...` — so a comment here reaches whoever opens the file and
            // never reaches the error text. The name does both.
            //
            // REMEDY: raise `NROS_RMW_SUBSCRIBER_SLOT_BYTES` to at least the second
            // operand — env, or `[knobs.rmw] subscriber_slot_bytes` on the
            // platform or board (it has no Kconfig symbol).
            // `NROS_RMW_SUBSCRIBER_SLOTS` is NOT the lever: it multiplies the same
            // too-small width, at `SLOT_SIZE` bytes of `.bss` a slot.
            let _raise_nros_rmw_subscriber_slot_bytes = SLOT_SIZE - mem::size_of::<T>();
            // The align arm, same reasoning. `SLOT_ALIGN` is what `Slot`'s
            // `repr(align)` gives every element of `SLOTS`, so an over-aligned
            // handle would be written to a misaligned address. No knob raises this
            // one — `repr(align)` cannot take a const — so the name says what a
            // reader has to do instead.
            let _over_aligned_for_the_cffi_subscriber_slot = SLOT_ALIGN - mem::align_of::<T>();
        };

        for index in 0..SLOT_COUNT {
            if USED[index]
                .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
                .is_err()
            {
                continue;
            }

            let ptr = SLOTS[index].bytes.get().cast::<T>();
            unsafe { ptr.write(value) };
            return Some(ptr);
        }

        // issue 1322 — the ONE cause left, said out loud beside the `None` with
        // the lever that answers it and what raising it costs. Before this the
        // caller's `BAD_ALLOC` was the whole diagnostic, and it could not
        // distinguish this from a fit failure. issue 0589 — `nros_log`, never
        // std stdio.
        nros_log::log_error!(
            nros_log::get_logger("nros_rmw_cffi"),
            "subscription pool exhausted: all {} static slot(s) are in use. \
             Raise NROS_RMW_SUBSCRIBER_SLOTS (each slot costs \
             NROS_RMW_SUBSCRIBER_SLOT_BYTES = {} bytes of .bss). A handle that \
             did not FIT cannot reach this path — that is a build error",
            SLOT_COUNT,
            SLOT_SIZE
        );
        None
    }

    pub unsafe fn take<T>(ptr: *mut T) -> bool {
        if ptr.is_null() {
            return false;
        }

        for index in 0..SLOT_COUNT {
            let slot_ptr = SLOTS[index].bytes.get().cast::<T>();
            if ptr != slot_ptr {
                continue;
            }

            unsafe { ptr::drop_in_place(ptr) };
            USED[index].store(false, Ordering::Release);
            return true;
        }

        false
    }
}

// ============================================================================
// Trait alias bundle
// ============================================================================
//
// `RustBackend` ties together every constraint the adapter needs. The
// alternative — long `where` clauses on every fn — is unreadable. This
// trait is sealed: backends don't impl it directly; the blanket impl
// below picks it up automatically for any `R: Rmw` whose associated
// types line up.

/// Bundle of trait bounds an `Rmw` backend must satisfy to be exposed
/// through [`RustBackendAdapter`]. Implemented automatically for any
/// `R: Rmw` whose handle types use `TransportError` and are
/// `'static`.
pub trait RustBackend: Sized {
    type Session: Session<
            Error = TransportError,
            PublisherHandle = Self::Publisher,
            SubscriptionHandle = Self::Subscription,
            ServiceHandle = Self::Service,
            ClientHandle = Self::Client,
        > + 'static;
    type Publisher: Publisher<Error = TransportError> + 'static;
    type Subscription: Subscription<Error = TransportError> + 'static;
    type Service: ServiceTrait<Error = TransportError> + 'static;
    type Client: ClientTrait<Error = TransportError> + 'static;

    /// Construct a fresh factory instance. Called inside the `open`
    /// trampoline. Equivalent to `R::default()` for backends that
    /// `derive(Default)`; the indirection keeps the door open for
    /// future per-backend registration knobs.
    fn factory() -> Self;

    /// Move the factory into a session per the `Rmw::open` contract.
    fn open(self, config: &RmwConfig) -> Result<Self::Session, TransportError>;
}

impl<R> RustBackend for R
where
    R: Rmw<Error = TransportError> + Default + Sized,
    R::Session: Session<Error = TransportError> + 'static,
    <R::Session as Session>::PublisherHandle: Publisher<Error = TransportError> + 'static,
    <R::Session as Session>::SubscriptionHandle: Subscription<Error = TransportError> + 'static,
    <R::Session as Session>::ServiceHandle: ServiceTrait<Error = TransportError> + 'static,
    <R::Session as Session>::ClientHandle: ClientTrait<Error = TransportError> + 'static,
{
    type Session = R::Session;
    type Publisher = <R::Session as Session>::PublisherHandle;
    type Subscription = <R::Session as Session>::SubscriptionHandle;
    type Service = <R::Session as Session>::ServiceHandle;
    type Client = <R::Session as Session>::ClientHandle;

    fn factory() -> Self {
        R::default()
    }

    fn open(self, config: &RmwConfig) -> Result<Self::Session, TransportError> {
        Rmw::open(self, config)
    }
}

// ============================================================================
// Helpers: C-string <-> &str
// ============================================================================

/// Read a null-terminated C string into a Rust `&str`. Returns the
/// empty string if `ptr` is null or contains invalid UTF-8.
///
/// # Safety
///
/// `ptr`, if non-null, must point to a valid null-terminated byte
/// sequence that outlives the returned borrow.
unsafe fn cstr_to_str<'a>(ptr: *const core::ffi::c_char) -> &'a str {
    if ptr.is_null() {
        return "";
    }
    let ptr = ptr.cast::<u8>();
    let mut len = 0usize;
    // Bound the scan so a missing terminator can't read off the end of
    // a small caller buffer. 1 KiB matches the typical NAME_BUF_LEN
    // (256) plus headroom for type-name / hash strings.
    while len < 4096 && unsafe { *ptr.add(len) } != 0 {
        len += 1;
    }
    let slice = unsafe { core::slice::from_raw_parts(ptr, len) };
    core::str::from_utf8(slice).unwrap_or("")
}

/// Borrow a NUL-terminated C string as `&str`, distinguishing "absent" and
/// "not text" from "empty" — which [`cstr_to_str`] deliberately does not.
///
/// `cstr_to_str` collapses NULL and invalid UTF-8 into `""` because its
/// callers (node names, topic names) treat an unusable name as an absent one.
/// A configuration property cannot: an empty key is not a key, and a value the
/// backend cannot read must be reported, not passed on as `""`.
unsafe fn cstr_to_str_strict<'a>(ptr: *const core::ffi::c_char) -> Option<&'a str> {
    if ptr.is_null() {
        return None;
    }
    let bytes = ptr.cast::<u8>();
    let mut len = 0usize;
    while len < 4096 && unsafe { *bytes.add(len) } != 0 {
        len += 1;
    }
    if len == 0 {
        return None;
    }
    let slice = unsafe { core::slice::from_raw_parts(bytes, len) };
    core::str::from_utf8(slice).ok()
}

/// Copy `options->properties` into `out`, returning how many entries were
/// written, or the `NrosRmwRet` to fail the session with.
///
/// # Safety
/// `options`, when non-NULL, must point at a valid `rmw_session_options_t`
/// whose `properties` array holds `property_count` valid entries.
unsafe fn collect_session_properties<'a>(
    options: *const NrosRmwSessionOptions,
    out: &mut [(&'a str, &'a str); MAX_SESSION_PROPERTIES],
) -> Result<usize, NrosRmwRet> {
    if options.is_null() {
        return Ok(0);
    }
    let opts = unsafe { &*options };
    let count = opts.property_count;
    if count == 0 {
        return Ok(0);
    }
    if opts.properties.is_null() || count > MAX_SESSION_PROPERTIES {
        return Err(NROS_RMW_RET_INVALID_ARGUMENT);
    }
    for (i, slot) in out.iter_mut().enumerate().take(count) {
        let entry = unsafe { &*opts.properties.add(i) };
        let (Some(key), Some(value)) = (unsafe { cstr_to_str_strict(entry.key) }, unsafe {
            cstr_to_str_strict(entry.value)
        }) else {
            return Err(NROS_RMW_RET_INVALID_ARGUMENT);
        };
        *slot = (key, value);
    }
    Ok(count)
}

/// Convert the cffi QoS view back into a `nros_rmw::QoSProfile`. The
/// adapter trampolines call this when forwarding `create_publisher` /
/// `create_subscription` into the Rust trait.
fn qos_from_cffi(q: &NrosRmwQos) -> QoSProfile {
    use crate::generated;
    use nros_rmw::{
        QoSDurabilityPolicy, QoSHistoryPolicy, QoSLivelinessPolicy, QoSReliabilityPolicy,
    };
    // Phase 376 W5/B2 — these were `== 0` tests against a dense 0/1 encoding.
    // Under upstream's numbering 0 is SYSTEM_DEFAULT for every policy, so each
    // test now has three cases, not two. Written as a match on the named
    // constants so an unrecognised value is visible rather than folded into
    // one arm.
    //
    // issue 0829 — SYSTEM_DEFAULT now RAISES to the sentinel variant instead
    // of being folded to the ROS default here. This function is the inbound
    // edge of a Rust backend, and resolving an absence is the BACKEND's job:
    // folding at the edge made every Rust backend answer the sentinel
    // identically, which is exactly what upstream does not do. UNKNOWN keeps
    // its old fold — it is a read-back artefact ("the backend could not
    // determine this"), not a request, so it has no sentinel meaning to carry.
    QoSProfile {
        reliability: match q.reliability as i32 {
            generated::NROS_RMW_RELIABILITY_SYSTEM_DEFAULT => QoSReliabilityPolicy::SystemDefault,
            generated::NROS_RMW_RELIABILITY_BEST_EFFORT => QoSReliabilityPolicy::BestEffort,
            generated::NROS_RMW_RELIABILITY_RELIABLE => QoSReliabilityPolicy::Reliable,
            // issue 1973 — RAISED like the sentinel, never folded: a Rust
            // backend reached past `CffiSession` (which resolves first) must
            // still see the request and resolve it against its own graph.
            generated::NROS_RMW_RELIABILITY_BEST_AVAILABLE => QoSReliabilityPolicy::BestAvailable,
            _ => QoSReliabilityPolicy::Reliable,
        },
        durability: match q.durability as i32 {
            generated::NROS_RMW_DURABILITY_SYSTEM_DEFAULT => QoSDurabilityPolicy::SystemDefault,
            generated::NROS_RMW_DURABILITY_TRANSIENT_LOCAL => QoSDurabilityPolicy::TransientLocal,
            generated::NROS_RMW_DURABILITY_BEST_AVAILABLE => QoSDurabilityPolicy::BestAvailable,
            _ => QoSDurabilityPolicy::Volatile,
        },
        history: match q.history as i32 {
            generated::NROS_RMW_HISTORY_SYSTEM_DEFAULT => QoSHistoryPolicy::SystemDefault,
            generated::NROS_RMW_HISTORY_KEEP_ALL => QoSHistoryPolicy::KeepAll,
            _ => QoSHistoryPolicy::KeepLast,
        },
        // The depth sentinel is a VALUE (0), so it needs no raising — it
        // already reads as `DEPTH_SYSTEM_DEFAULT` on the far side.
        depth: q.depth as u32,
        // phase-301 (issue 0240): the express hint left the QoS struct; the
        // create trampolines thread it via `TopicInfo` from the options param.
        tx_express: false,
        deadline_ms: q.deadline_ms,
        lifespan_ms: q.lifespan_ms,
        liveliness_kind: match q.liveliness_kind as u32 {
            generated::rmw_liveliness_kind_t::NROS_RMW_LIVELINESS_AUTOMATIC => {
                QoSLivelinessPolicy::Automatic
            }
            generated::rmw_liveliness_kind_t::NROS_RMW_LIVELINESS_MANUAL_BY_NODE => {
                QoSLivelinessPolicy::ManualByNode
            }
            generated::rmw_liveliness_kind_t::NROS_RMW_LIVELINESS_MANUAL_BY_TOPIC => {
                QoSLivelinessPolicy::ManualByTopic
            }
            generated::rmw_liveliness_kind_t::NROS_RMW_LIVELINESS_BEST_AVAILABLE => {
                QoSLivelinessPolicy::BestAvailable
            }
            _ => QoSLivelinessPolicy::None,
        },
        liveliness_lease_ms: q.liveliness_lease_ms,
        avoid_ros_namespace_conventions: q.avoid_ros_namespace_conventions != 0,
    }
}

// Phase 376 W5/B1 — ~~`session_node_name`~~ and ~~`session_namespace`~~ are GONE with
// the `entity_view` fabrication they served. They read the OWNING NODE's
// identity off a session struct the shim rewrote per call, which is how node
// identity reached a backend before the node itself did.

/// The node's own identity.
unsafe fn node_name_of<'a>(node: *const NrosRmwNode) -> Option<&'a str> {
    let name = unsafe { cstr_to_str((*node).name) };
    if name.is_empty() { None } else { Some(name) }
}

unsafe fn node_namespace_of<'a>(node: *const NrosRmwNode) -> &'a str {
    let namespace = unsafe { cstr_to_str((*node).namespace_) };
    if namespace.is_empty() { "/" } else { namespace }
}

// ============================================================================
// Adapter
// ============================================================================

/// Longest serialization-format name this seam can hand across the C ABI.
///
/// RFC-0088 D2 — the vtable slot carries the format's cross-image identity
/// STRING, and a Rust backend spells that identity as a `&'static str`
/// (`Session::SERIALIZATION_FORMAT`), which is not NUL-terminated. The
/// conversion therefore has to happen somewhere, and it happens HERE, at
/// compile time, into per-`R` static storage — never at call time into a
/// buffer whose lifetime the slot's `const char *` contract cannot express.
///
/// 32 is generous for a name like `"cdr"`; a longer one is a const-eval error
/// rather than a truncation, because a truncated format name is a different,
/// plausible format.
const FORMAT_NAME_CAP: usize = 32;

/// NUL-terminate a format name at compile time.
const fn format_name_cstr(name: &str) -> [u8; FORMAT_NAME_CAP] {
    let bytes = name.as_bytes();
    assert!(
        bytes.len() < FORMAT_NAME_CAP,
        "backend name (format or identifier) does not fit the vtable slot's buffer"
    );
    let mut out = [0u8; FORMAT_NAME_CAP];
    let mut i = 0;
    while i < bytes.len() {
        out[i] = bytes[i];
        i += 1;
    }
    out
}

/// `get_serialization_format` — RFC-0088 D4.
///
/// Takes no arguments, exactly as upstream's `rmw_get_serialization_format()`
/// does, because the answer is a property of the BACKEND and not of any entity
/// it created. What differs from upstream is who holds the question: upstream
/// has one middleware per process and can answer from a global, while
/// `nros_rmw_cffi_register_named` admits several backends in one image, so the
/// answer is per-vtable — which is per-session, since a session is opened
/// against one vtable.
unsafe extern "C" fn get_serialization_format_trampoline<R: RustBackend>() -> *const c_char {
    RustBackendAdapter::<R>::SERIALIZATION_FORMAT_CSTR
        .as_ptr()
        .cast()
}

/// `get_implementation_identifier` — the backend's name from its own
/// `Session::IMPLEMENTATION_IDENTIFIER`, installed only when that const is
/// `Some` (see `VTABLE`). Static storage, as for the format slot.
unsafe extern "C" fn get_implementation_identifier_trampoline<R: RustBackend>() -> *const c_char {
    RustBackendAdapter::<R>::IMPLEMENTATION_IDENTIFIER_CSTR
        .as_ptr()
        .cast()
}

/// issue 1329 — a Rust backend reached through the C ABI answers for ITSELF.
///
/// `Session::supported_qos_policies` is already the Rust-side answer, derived
/// from `nros-qos-honours:` claims in the backend's own sources (phase-428
/// W9). Without this trampoline a Rust backend registered through the C route
/// would answer `NONE` — the NULL-slot meaning — and every entity stating a
/// policy on it would be refused: the mask exists and the seam could not carry
/// it, which is issue 1329's shape one lane over.
///
/// # Safety
/// Called only by the runtime, with a session view this adapter created.
unsafe extern "C" fn supported_qos_policies_trampoline<R: RustBackend>(
    session: *const NrosRmwSession,
    out_mask: *mut u32,
) -> NrosRmwRet {
    if out_mask.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(s) = (unsafe { session_ref::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { *out_mask = Session::supported_qos_policies(s).0 };
    NROS_RMW_RET_OK
}

/// Wraps a Rust `Rmw` backend behind the canonical
/// [`NrosRmwVtable`] C ABI. See module docs.
pub struct RustBackendAdapter<R>(PhantomData<R>);

impl<R: RustBackend> RustBackendAdapter<R> {
    /// RFC-0088 D4 — `R`'s serialization format, NUL-terminated, in per-`R`
    /// static storage so the `get_serialization_format` slot can hand out a
    /// `const char *` that outlives the call.
    ///
    /// `&<const expr>` in a const initialiser is promoted to `'static`, which
    /// is what makes the slot's lifetime contract true rather than merely
    /// hoped for.
    const SERIALIZATION_FORMAT_CSTR: &'static [u8; FORMAT_NAME_CAP] =
        &format_name_cstr(<R::Session as Session>::SERIALIZATION_FORMAT);

    /// `R`'s implementation identifier, NUL-terminated, in per-`R` static
    /// storage. Empty when `R` states none — the slot is then NOT installed
    /// (see `VTABLE`), so this buffer is never handed out in that case.
    const IMPLEMENTATION_IDENTIFIER_CSTR: &'static [u8; FORMAT_NAME_CAP] =
        &format_name_cstr(match <R::Session as Session>::IMPLEMENTATION_IDENTIFIER {
            Some(name) => name,
            None => "",
        });

    /// Monomorphised vtable for backend `R`. The `const` is promoted
    /// to per-type static storage, so `&Self::VTABLE` has `'static`
    /// lifetime — safe to hand to `nros_rmw_cffi_register_named`.
    pub const VTABLE: NrosRmwVtable = NrosRmwVtable {
        create_session: Some(create_session_trampoline::<R>),
        destroy_session: Some(destroy_session_trampoline::<R>),
        drive_io: Some(drive_io_trampoline::<R>),
        create_publisher: Some(create_publisher_trampoline::<R>),
        destroy_publisher: Some(destroy_publisher_trampoline::<R>),
        publish: Some(publish_trampoline::<R>),
        create_subscription: Some(create_subscription_trampoline::<R>),
        destroy_subscription: Some(destroy_subscription_trampoline::<R>),
        take: Some(take_trampoline::<R>),
        has_data: Some(has_data_trampoline::<R>),
        create_service: Some(create_service_trampoline::<R>),
        destroy_service: Some(destroy_service_trampoline::<R>),
        take_request: Some(take_request_trampoline::<R>),
        has_request: Some(has_request_trampoline::<R>),
        send_response: Some(send_response_trampoline::<R>),
        create_client: Some(create_client_trampoline::<R>),
        destroy_client: Some(destroy_client_trampoline::<R>),
        // Phase-301 (issue 0240) — `send_request_raw` + `take_response_raw`
        // is the one request/reply path; the blocking `call_raw` slot is gone.
        send_request: Some(send_request_trampoline::<R>),
        take_response: Some(take_response_trampoline::<R>),
        // Issue 2136 — the reply's metadata, from `ClientTrait::response_info`.
        // Installed for every Rust backend: one that reports nothing hands
        // back the all-zero struct, which reads as `NOT_REPORTED`.
        take_response_with_info: Some(take_response_with_info_trampoline::<R>),
        subscription_event_init: Some(subscription_event_init_trampoline::<R>),
        publisher_event_init: Some(publisher_event_init_trampoline::<R>),
        publisher_assert_liveliness: Some(publisher_assert_liveliness_trampoline::<R>),
        get_gid_for_publisher: Some(get_gid_for_publisher_trampoline::<R>),
        next_deadline_ms: Some(next_deadline_ms_trampoline::<R>),
        set_wake_callback: Some(set_wake_callback_trampoline::<R>),
        // phase-521 W3 (RFC-0113 D4) — the backend's own answer. Installed
        // for every Rust backend because `set_wake_callback` above is too, so
        // the NULL-slot inference ("a wake slot means Notify") would claim
        // Notify for a backend whose trait method ignores the callback.
        readiness_source: Some(readiness_source_trampoline::<R>),
        // Phase 124.A — zero-copy slots default to NULL on the
        // generic adapter; per-backend opt-in via dedicated trampolines
        // (see `nros-rmw-zenoh` for the first implementation in 124.A.4).
        // Runtime falls back to the arena path when these are NULL.
        service_server_is_available: Some(service_server_is_available_trampoline::<R>),
        take_sequence: Some(take_sequence_trampoline::<R>),
        publish_streamed: Some(publish_streamed_trampoline::<R>),
        ping_session: Some(ping_session_trampoline::<R>),
        subscription_supports_in_place: Some(subscription_supports_in_place_trampoline::<R>),
        process_raw_in_place: Some(process_raw_in_place_trampoline::<R>),
        // phase-381 W3 — graph enumeration. The trait default is
        // `Unsupported`, so a backend with no graph (XRCE) answers that rather
        // than an empty one: "cannot tell you" and "nothing is there" are
        // different answers and W6 keeps them distinguishable.
        get_node_names: Some(get_node_names_trampoline::<R>),
        count_publishers: Some(count_publishers_trampoline::<R>),
        count_subscribers: Some(count_subscribers_trampoline::<R>),
        get_topic_names_and_types: Some(get_topic_names_and_types_trampoline::<R>),
        get_service_names_and_types: Some(get_service_names_and_types_trampoline::<R>),
        // phase-381 W3 — the last six. The trait defaults are `Unsupported`, so
        // a backend with no graph still answers "cannot tell you" rather than
        // an empty graph.
        get_publisher_names_and_types_by_node: Some(
            get_publisher_names_and_types_by_node_trampoline::<R>,
        ),
        get_subscriber_names_and_types_by_node: Some(
            get_subscriber_names_and_types_by_node_trampoline::<R>,
        ),
        get_service_names_and_types_by_node: Some(
            get_service_names_and_types_by_node_trampoline::<R>,
        ),
        get_client_names_and_types_by_node: Some(
            get_client_names_and_types_by_node_trampoline::<R>,
        ),
        get_publishers_info_by_topic: Some(get_publishers_info_by_topic_trampoline::<R>),
        get_subscriptions_info_by_topic: Some(get_subscriptions_info_by_topic_trampoline::<R>),
        // phase-467 Row 8 — the graph-CHANGE edge, the twelfth graph slot and
        // the last one that was empty. Unconditional for every
        // `R: RustBackend`, like the eleven above and for the same reason: the
        // trait default is `Unsupported`, so a backend with no graph answers
        // "cannot tell you" rather than accepting a callback nothing will
        // fire. That default is ALSO the capability probe the runtime makes
        // before it consumes an executor handle slot, so this row being
        // unconditional is what keeps the refusal reachable.
        node_get_graph_guard_condition: Some(node_get_graph_guard_condition_trampoline::<R>),
        // RFC-0088 D4 / phase-421 W2 — every Rust backend answers with its own
        // `Session::SERIALIZATION_FORMAT`, so a bridge image can ask each
        // session rather than trusting one image-wide constant. The trait
        // default is `"cdr"`; a backend that speaks something else overrides
        // it and this slot reports the override with no work here.
        get_serialization_format: Some(get_serialization_format_trampoline::<R>),
        // The backend's name, when `R` states one. Conditional, unlike the
        // format slot: the identifier has no honest default, and a NULL slot
        // makes the runtime answer with the name the vtable was REGISTERED
        // under, which is a fact rather than a guess (`rmw_vtable.h`).
        get_implementation_identifier: if <R::Session as Session>::IMPLEMENTATION_IDENTIFIER
            .is_some()
        {
            Some(get_implementation_identifier_trampoline::<R>)
        } else {
            None
        },
        // issue 1329 — `R`'s own mask, so the C route stops answering a union
        // on its behalf. Unconditional for every `R: RustBackend`: the trait
        // default is `QoSPolicyMask::NONE`, which is the same answer a NULL
        // slot carries, so installing it for a backend that declares nothing
        // changes nothing.
        supported_qos_policies: Some(supported_qos_policies_trampoline::<R>),
        // The granted-QoS read-back. See the trampolines for why these are
        // unconditional.
        publisher_get_actual_qos: Some(publisher_get_actual_qos_trampoline::<R>),
        subscription_get_actual_qos: Some(subscription_get_actual_qos_trampoline::<R>),
        client_request_publisher_get_actual_qos: Some(
            client_request_publisher_get_actual_qos_trampoline::<R>,
        ),
        client_response_subscription_get_actual_qos: Some(
            client_response_subscription_get_actual_qos_trampoline::<R>,
        ),
        service_request_subscription_get_actual_qos: Some(
            service_request_subscription_get_actual_qos_trampoline::<R>,
        ),
        service_response_publisher_get_actual_qos: Some(
            service_response_publisher_get_actual_qos_trampoline::<R>,
        ),
        // Issue 1940 — every Rust backend's `register_waker`, reached from C.
        // Unconditional: a backend whose `register_waker` returns `false` (the
        // trait default) makes the slot answer UNSUPPORTED, the same verdict a
        // NULL slot carries.
        subscription_set_on_new_message_callback: Some(
            subscription_set_on_new_message_callback_trampoline::<R>,
        ),
        service_set_on_new_request_callback: Some(
            service_set_on_new_request_callback_trampoline::<R>,
        ),
        client_set_on_new_response_callback: Some(
            client_set_on_new_response_callback_trampoline::<R>,
        ),
        // Issue 1978 — the Jazzy contract's four ADOPT slots. Unconditional
        // for the same reason as the graph slots above: each trait default
        // (`Unsupported`, `Unsupported`, `Unsupported`, `false`) is the answer
        // a NULL slot would carry, so a backend that overrides nothing still
        // answers honestly.
        count_clients: Some(count_clients_trampoline::<R>),
        count_services: Some(count_services_trampoline::<R>),
        get_gid_for_client: Some(get_gid_for_client_trampoline::<R>),
        event_type_is_supported: Some(event_type_is_supported_trampoline::<R>),
        ..EMPTY_VTABLE
    };

    /// Install the per-`R` vtable into the cffi registry under the
    /// implicit name `"default"`. Idempotent — re-registering the
    /// same vtable is a no-op from the runtime's perspective.
    ///
    /// Most backends should use [`register_named`](Self::register_named)
    /// instead so they show up in the registry under their canonical
    /// name (`"zenoh"`, `"dds"`, `"xrce"`, …). Phase 128.B.5 routes
    /// the implicit-name path through `_register_named` too, so the
    /// legacy unnamed C shim no longer participates in registration.
    pub fn register() -> NrosRmwRet {
        // SAFETY: `&Self::VTABLE` is a reference to a const-promoted
        // static; address stable for the program's lifetime.
        unsafe { crate::nros_rmw_cffi_register_named(c"default".as_ptr(), &Self::VTABLE) }
    }

    /// Phase 104.B.2 — install the per-`R` vtable under a stable
    /// name. Multiple backends can coexist via this entry point.
    ///
    /// # Safety
    /// `name` must be a valid NUL-terminated UTF-8 string.
    pub unsafe fn register_named(name: *const core::ffi::c_char) -> NrosRmwRet {
        // SAFETY: `&Self::VTABLE` is a reference to a const-promoted
        // static; address stable for the program's lifetime.
        unsafe { crate::nros_rmw_cffi_register_named(name, &Self::VTABLE) }
    }
}

// ============================================================================
// Trampolines — session lifecycle
// ============================================================================

unsafe extern "C" fn create_session_trampoline<R: RustBackend>(
    locator: *const core::ffi::c_char,
    mode: u8,
    domain_id: u32,
    node_name: *const core::ffi::c_char,
    options: *const NrosRmwSessionOptions,
    out: *mut NrosRmwSession,
) -> NrosRmwRet {
    if out.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    // phase-206 W3 — marshal the caller's session properties into the slice
    // `RmwConfig` takes. This used to read `let _ = options;` with
    // `properties: &[]` hard-coded, which made every backend-specific
    // transport setting unreachable from C and C++: the Rust trait had carried
    // `properties` since it existed, and only a hosted Rust caller building an
    // `RmwConfig` by hand could fill it.
    //
    // Refused rather than truncated (each is INVALID_ARGUMENT):
    //   - `property_count > 0` with a NULL `properties` pointer,
    //   - more than `RMW_SESSION_MAX_PROPERTIES` entries,
    //   - a NULL, empty, or non-UTF-8 key or value.
    // Dropping any of these silently is the failure this work item exists to
    // remove; a caller that cannot see its configuration was ignored debugs
    // the transport instead of the typo.
    let mut prop_buf: [(&str, &str); MAX_SESSION_PROPERTIES] = [("", ""); MAX_SESSION_PROPERTIES];
    let prop_count = match unsafe { collect_session_properties(options, &mut prop_buf) } {
        Ok(n) => n,
        Err(ret) => return ret,
    };
    let cfg = RmwConfig {
        locator: unsafe { cstr_to_str(locator) },
        mode: if mode == 0 {
            SessionMode::Client
        } else {
            SessionMode::Peer
        },
        domain_id,
        node_name: unsafe { cstr_to_str(node_name) },
        // Issue 1444 — the INBOUND half. `node_name` arrives as its own
        // argument; the namespace arrives on the session view, which
        // `rmw_vtable.h` says the runtime hands over "with `node_name` /
        // `namespace_` already filled". This read `""` unconditionally, so
        // even once the runtime filled the buffer a Rust backend behind this
        // adapter — which is every in-tree zenoh build — would still have seen
        // nothing. Both halves move together or neither is observable.
        //
        // SAFETY: `out` is non-null (checked above) and its `namespace_` is
        // either the runtime's NUL-terminated buffer or NULL; `cstr_to_str`
        // answers `""` for NULL, which is the root.
        namespace: unsafe { cstr_to_str((*out).namespace_) },
        properties: &prop_buf[..prop_count],
    };
    let factory = R::factory();
    match factory.open(&cfg) {
        Ok(session) => match box_handle("session", session) {
            Ok(boxed) => {
                unsafe {
                    (*out).backend_data = boxed;
                }
                NROS_RMW_RET_OK
            }
            // An unboxable session must not stay open with nobody holding it:
            // close then drop, the order `destroy_session_trampoline` uses.
            Err(mut session) => {
                let _ = Session::close(&mut session);
                drop(session);
                NROS_RMW_RET_BAD_ALLOC
            }
        },
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn destroy_session_trampoline<R: RustBackend>(
    session: *mut NrosRmwSession,
) -> NrosRmwRet {
    let Some(boxed) = (unsafe { take_box::<R::Session>(session_data_mut(session)) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let mut s = boxed;
    let ret = match Session::close(&mut *s) {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    };
    drop(s);
    ret
}

unsafe extern "C" fn drive_io_trampoline<R: RustBackend>(
    session: *mut NrosRmwSession,
    timeout_ms: i32,
) -> NrosRmwRet {
    let Some(s) = (unsafe { session_mut::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    match Session::drive_io(s, timeout_ms) {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

// ============================================================================
// Trampolines — publisher
// ============================================================================

unsafe extern "C" fn create_publisher_trampoline<R: RustBackend>(
    node: *const NrosRmwNode,
    // phase-406 W1 — the identity arrives as ONE argument, in upstream's
    // position. Unpacked immediately below so the body is unchanged.
    type_support: *const crate::generated::rmw_message_type_support_t,
    topic_name: *const core::ffi::c_char,
    domain_id: u32,
    qos: *const NrosRmwQos,
    options: *const rmw_publisher_options_t,
    out: *mut NrosRmwPublisher,
) -> NrosRmwRet {
    // phase-406 W1 — unpack once, so the body below is untouched. A NULL
    // `type_support` is INVALID_ARGUMENT rather than a silent empty type: the
    // identity is what the backend keys its entity on, and an entity created
    // with no type is a subscription that matches nothing and reports nothing.
    let Some(ts) = (unsafe { type_support.as_ref() }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (type_name, type_hash) = (ts.type_name, ts.type_hash);
    if out.is_null() || qos.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    // Phase 376 W5/B1 — the node carries both halves now: its own identity, and
    // the route to its session (upstream's `context`). Reading the name off the
    // session was the `entity_view` fabrication, and it is gone.
    if node.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let session = unsafe { (*node).session };
    let Some(s) = (unsafe { session_mut::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let node_name = unsafe { node_name_of(node) };
    let namespace = unsafe { node_namespace_of(node) };
    let topic = TopicInfo {
        name: unsafe { cstr_to_str(topic_name) },
        type_name: unsafe { cstr_to_str(type_name) },
        type_hash: unsafe { cstr_to_str(type_hash) },
        domain_id,
        node_name,
        namespace,
        // Publisher side — the receive-buffer hint is subscription-only.
        rx_buffer_hint: 0,
        arrival_rate_mhz: 0,
        // phase-301 (issue 0240) — express hint from the NULLable options
        // struct (NULL = default, not express).
        tx_express: unsafe { options.as_ref() }.is_some_and(|o| o.tx_express != 0),
    };
    let qos_settings = qos_from_cffi(unsafe { &*qos });
    match Session::create_publisher(s, &topic, qos_settings) {
        Ok(pub_handle) => match box_handle("publisher", pub_handle) {
            Ok(boxed) => {
                unsafe {
                    (*out).backend_data = boxed;
                }
                NROS_RMW_RET_OK
            }
            // Dropping the handle undeclares the entity the backend just made.
            Err(pub_handle) => {
                drop(pub_handle);
                NROS_RMW_RET_BAD_ALLOC
            }
        },
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn destroy_publisher_trampoline<R: RustBackend>(
    publisher: *mut NrosRmwPublisher,
) -> NrosRmwRet {
    let _ = unsafe { take_box::<R::Publisher>(publisher_data_mut(publisher)) };

    NROS_RMW_RET_OK
}

unsafe extern "C" fn publish_trampoline<R: RustBackend>(
    publisher: *const NrosRmwPublisher,
    // phase-406 W2 — by VALUE; unpacked so the body is unchanged.
    payload: crate::generated::rmw_byte_span_t,
) -> NrosRmwRet {
    let (data, len) = (payload.data, payload.len);
    let Some(p) = (unsafe { publisher_ref::<R::Publisher>(publisher) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    if data.is_null() && len != 0 {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let slice = unsafe { core::slice::from_raw_parts(data, len) };
    match Publisher::publish_raw(p, slice) {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

// ============================================================================
// Trampolines — subscriber
// ============================================================================

unsafe extern "C" fn create_subscription_trampoline<R: RustBackend>(
    node: *const NrosRmwNode,
    // phase-406 W1 — the identity arrives as ONE argument, in upstream's
    // position. Unpacked immediately below so the body is unchanged.
    type_support: *const crate::generated::rmw_message_type_support_t,
    topic_name: *const core::ffi::c_char,
    domain_id: u32,
    qos: *const NrosRmwQos,
    options: *const rmw_subscription_options_t,
    out: *mut NrosRmwSubscription,
) -> NrosRmwRet {
    // phase-406 W1 — unpack once, so the body below is untouched. A NULL
    // `type_support` is INVALID_ARGUMENT rather than a silent empty type: the
    // identity is what the backend keys its entity on, and an entity created
    // with no type is a subscription that matches nothing and reports nothing.
    let Some(ts) = (unsafe { type_support.as_ref() }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (type_name, type_hash) = (ts.type_name, ts.type_hash);
    if out.is_null() || qos.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    // Phase 376 W5/B1 — the node carries both halves now: its own identity, and
    // the route to its session (upstream's `context`). Reading the name off the
    // session was the `entity_view` fabrication, and it is gone.
    if node.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let session = unsafe { (*node).session };
    let Some(s) = (unsafe { session_mut::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let node_name = unsafe { node_name_of(node) };
    let namespace = unsafe { node_namespace_of(node) };
    // The NULLable options struct, read once for both of its fields.
    let opts = unsafe { options.as_ref() };
    let topic = TopicInfo {
        name: unsafe { cstr_to_str(topic_name) },
        type_name: unsafe { cstr_to_str(type_name) },
        type_hash: unsafe { cstr_to_str(type_hash) },
        domain_id,
        node_name,
        namespace,
        // Phase 231 (RFC-0038) / phase-301 (issue 0240) — receive-buffer size
        // hint from the NULLable options struct (NULL = unset), so the backend
        // can size-class its receive storage.
        rx_buffer_hint: opts.map_or(0, |o| o.rx_buffer_hint as usize),
        // phase-519 W3 — the declared arrival rate (RFC-0074), same struct.
        arrival_rate_mhz: opts.map_or(0, |o| o.arrival_rate_mhz),
        // Subscription side — express is a publisher-only hint.
        tx_express: false,
    };
    let qos_settings = qos_from_cffi(unsafe { &*qos });
    match Session::create_subscription(s, &topic, qos_settings) {
        Ok(sub_handle) => {
            // Issue 1940 — the handle travels inside a `Hosted`, which carries
            // its C wake registration. `backend_data` still reads as a
            // `*const R::Subscription` everywhere else (`repr(C)`, inner first).
            let sub_handle = Hosted::new(sub_handle, |t: &R::Subscription, w| {
                Subscription::register_waker(t, w)
            });
            #[cfg(all(target_os = "none", not(feature = "std")))]
            {
                let Some(ptr) = (unsafe { static_subscriber_storage::insert(sub_handle) }) else {
                    return crate::NROS_RMW_RET_BAD_ALLOC;
                };
                unsafe {
                    (*out).backend_data = ptr as *mut c_void;
                }
                NROS_RMW_RET_OK
            }
            #[cfg(not(all(target_os = "none", not(feature = "std"))))]
            {
                match box_handle("subscription", sub_handle) {
                    Ok(boxed) => {
                        unsafe {
                            (*out).backend_data = boxed;
                        }
                        NROS_RMW_RET_OK
                    }
                    // Dropping the handle undeclares the entity the backend
                    // just made.
                    Err(sub_handle) => {
                        drop(sub_handle);
                        NROS_RMW_RET_BAD_ALLOC
                    }
                }
            }
        }
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn destroy_subscription_trampoline<R: RustBackend>(
    subscriber: *mut NrosRmwSubscription,
) -> NrosRmwRet {
    let slot = unsafe { subscription_data_mut(subscriber) };
    #[cfg(all(target_os = "none", not(feature = "std")))]
    {
        if unsafe {
            static_subscriber_storage::take::<Hosted<R::Subscription>>(
                *slot as *mut Hosted<R::Subscription>,
            )
        } {
            *slot = core::ptr::null_mut();
            return NROS_RMW_RET_OK;
        }
    }
    let _ = unsafe { take_box::<Hosted<R::Subscription>>(slot) };

    NROS_RMW_RET_OK
}

unsafe extern "C" fn take_trampoline<R: RustBackend>(
    subscriber: *const NrosRmwSubscription,
    // phase-406 W2 — by POINTER; `capacity` in, `len` out.
    out: *mut crate::generated::rmw_mut_byte_span_t,
    taken: *mut bool,
) -> NrosRmwRet {
    let Some(span) = (unsafe { out.as_mut() }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (buf, buf_len) = (span.data, span.capacity);
    let out_len: *mut usize = &mut span.len;
    // Phase 376 W3.b/W3.d step A — upstream's `rmw_take` shape: status in the
    // return, `taken` and the byte count in out-parameters. `Ok(None)` is no
    // longer the NO_DATA sentinel.
    if out_len.is_null() || taken.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(s) = (unsafe { subscription_mut::<R::Subscription>(subscriber) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    if buf.is_null() && buf_len != 0 {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let slice = unsafe { core::slice::from_raw_parts_mut(buf, buf_len) };
    let key = unsafe { (*subscriber).backend_data as usize };

    // SAFETY (all four writes below): both pointers checked non-null above.
    #[cfg(feature = "safety-e2e")]
    if crate::take_cffi_integrity_request(key) {
        return match Subscription::take_validated(s, slice) {
            Ok(Some((n, status))) => {
                crate::store_cffi_integrity_status(key, status);
                unsafe {
                    *out_len = n;
                    *taken = true;
                }
                NROS_RMW_RET_OK
            }
            Ok(None) => {
                unsafe { *taken = false };
                NROS_RMW_RET_OK
            }
            Err(e) => refused_take_ret(s, &e, out_len),
        };
    }

    match Subscription::take_serialized_with_info(s, slice) {
        Ok(Some((n, info))) => {
            crate::store_cffi_message_info(key, info);
            unsafe {
                *out_len = n;
                *taken = true;
            }
            NROS_RMW_RET_OK
        }
        Ok(None) => {
            unsafe { *taken = false };
            NROS_RMW_RET_OK
        }
        Err(e) => refused_take_ret(s, &e, out_len),
    }
}

/// Issue 1612 — a Rust backend's refused take, carried across the C ABI.
///
/// The status alone says THAT the sample did not fit; `rmw_vtable.h` now
/// also asks for `out->len` to say how big it was. The Rust backend answers
/// through [`Subscription::refused_sample_len`], so this is where the two
/// halves meet. Unknown leaves `len` at the caller's
/// `NROS_RMW_TAKE_LEN_UNKNOWN`, which is the answer the header gives for it.
fn refused_take_ret<S: Subscription<Error = TransportError>>(
    s: &S,
    e: &TransportError,
    out_len: *mut usize,
) -> NrosRmwRet {
    refused_ret(e, s.refused_sample_len(), out_len)
}

/// Issues 1612 / 1632 — the ONE place a Rust backend's refused size crosses
/// the C ABI, for all three take slots: on `BufferTooSmall` the span's `len`
/// gets the size the backend reported; unknown leaves the caller's
/// `NROS_RMW_TAKE_LEN_UNKNOWN`.
fn refused_ret(e: &TransportError, needed: Option<usize>, out_len: *mut usize) -> NrosRmwRet {
    if matches!(e, TransportError::BufferTooSmall)
        && let Some(needed) = needed
    {
        // SAFETY: every caller checked the span (and so `out_len`) non-null
        // before the take.
        unsafe { *out_len = needed };
    }
    ret_from_error(e)
}

unsafe extern "C" fn has_data_trampoline<R: RustBackend>(
    subscription: *mut NrosRmwSubscription,
    out_has_data: *mut bool,
) -> NrosRmwRet {
    // Phase 376 W3.d step A — the flag moves to an out-parameter so the return
    // carries only a status. Written on OK only.
    if out_has_data.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    // `subscription_ref`, not `_mut`: the probe is logically read-only and the
    // header says a backend must not mutate state here.
    let Some(s) = (unsafe { subscription_ref::<R::Subscription>(subscription) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { *out_has_data = Subscription::has_data(s) };
    NROS_RMW_RET_OK
}

// Phase 231 (RFC-0038) — in-place subscription take across the C ABI.

unsafe extern "C" fn subscription_supports_in_place_trampoline<R: RustBackend>(
    subscriber: *mut NrosRmwSubscription,
    out_supports: *mut bool,
) -> NrosRmwRet {
    // Phase 376 W3.d step A — capability out, status returned.
    if out_supports.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(s) = (unsafe { subscription_ref::<R::Subscription>(subscriber) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { *out_supports = Subscription::supports_process_in_place(s) };
    NROS_RMW_RET_OK
}

unsafe extern "C" fn process_raw_in_place_trampoline<R: RustBackend>(
    subscriber: *mut NrosRmwSubscription,
    ctx: *mut core::ffi::c_void,
    cb: Option<
        unsafe extern "C" fn(
            ctx: *mut core::ffi::c_void,
            message: crate::generated::rmw_byte_span_t,
        ),
    >,
    out_processed: *mut bool,
) -> NrosRmwRet {
    // Phase 376 W3.d step A — "did it process one" is the out-parameter, and
    // `Ok(false)` is no longer reported as the NO_DATA sentinel.
    if out_processed.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(s) = (unsafe { subscription_mut::<R::Subscription>(subscriber) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let Some(cb) = cb else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    match Subscription::process_raw_in_place(s, |raw| unsafe {
        cb(
            ctx,
            crate::generated::rmw_byte_span_t {
                data: raw.as_ptr(),
                len: raw.len(),
            },
        )
    }) {
        Ok(processed) => {
            // SAFETY: checked non-null above.
            unsafe { *out_processed = processed };
            NROS_RMW_RET_OK
        }
        Err(e) => ret_from_error(&e),
    }
}

// ============================================================================
// Trampolines — service server
// ============================================================================

unsafe extern "C" fn create_service_trampoline<R: RustBackend>(
    node: *const NrosRmwNode,
    // phase-406 W1 — the identity arrives as ONE argument, in upstream's
    // position. Unpacked immediately below so the body is unchanged.
    type_support: *const crate::generated::rmw_service_type_support_t,
    service_name: *const core::ffi::c_char,
    domain_id: u32,
    qos: *const NrosRmwQos,
    out: *mut NrosRmwService,
) -> NrosRmwRet {
    // phase-406 W1 — unpack once, so the body below is untouched. A NULL
    // `type_support` is INVALID_ARGUMENT rather than a silent empty type: the
    // identity is what the backend keys its entity on, and an entity created
    // with no type is a subscription that matches nothing and reports nothing.
    let Some(ts) = (unsafe { type_support.as_ref() }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (type_name, type_hash) = (ts.type_name, ts.type_hash);
    if out.is_null() || qos.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    // Phase 376 W5/B1 — the node carries both halves now: its own identity, and
    // the route to its session (upstream's `context`). Reading the name off the
    // session was the `entity_view` fabrication, and it is gone.
    if node.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let session = unsafe { (*node).session };
    let Some(s) = (unsafe { session_mut::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let node_name = unsafe { node_name_of(node) };
    let namespace = unsafe { node_namespace_of(node) };
    let info = nros_rmw::ServiceInfo {
        name: unsafe { cstr_to_str(service_name) },
        type_name: unsafe { cstr_to_str(type_name) },
        type_hash: unsafe { cstr_to_str(type_hash) },
        domain_id,
        node_name,
        namespace,
    };
    let qos_settings = qos_from_cffi(unsafe { &*qos });
    match Session::create_service(s, &info, qos_settings) {
        Ok(server) => match box_handle(
            "service server",
            Hosted::new(server, |t: &R::Service, w| {
                ServiceTrait::register_waker(t, w)
            }),
        ) {
            Ok(boxed) => {
                unsafe {
                    (*out).backend_data = boxed;
                }
                NROS_RMW_RET_OK
            }
            // Dropping the handle undeclares the entity the backend just made.
            Err(server) => {
                drop(server);
                NROS_RMW_RET_BAD_ALLOC
            }
        },
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn destroy_service_trampoline<R: RustBackend>(
    server: *mut NrosRmwService,
) -> NrosRmwRet {
    let _ = unsafe { take_box::<Hosted<R::Service>>(service_data_mut(server)) };

    NROS_RMW_RET_OK
}

unsafe extern "C" fn take_request_trampoline<R: RustBackend>(
    server: *const NrosRmwService,
    request: *mut crate::generated::rmw_mut_byte_span_t,
    seq_out: *mut i64,
    taken: *mut bool,
) -> NrosRmwRet {
    // Phase 376 W3.b/W3.d step A — upstream `rmw_take_request`'s shape;
    // phase-406 W2 — the byte range is one span, and `written` lands in it.
    if request.is_null() || taken.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(s) = (unsafe { service_mut::<R::Service>(server) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (buf, buf_len) = unsafe { ((*request).data, (*request).capacity) };
    let out_len = unsafe { &raw mut (*request).len };
    if (buf.is_null() && buf_len != 0) || seq_out.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let slice = unsafe { core::slice::from_raw_parts_mut(buf, buf_len) };
    let buf_start = slice.as_ptr() as usize;
    match ServiceTrait::take_request(s, slice) {
        Ok(Some(req)) => {
            // The handle's `data` slice borrows from `buf`. Use its
            // offset within the caller's buffer to compute the payload
            // length; some backends prepend an envelope header so the
            // payload doesn't start at offset 0.
            let offset = (req.data.as_ptr() as usize).saturating_sub(buf_start);
            let len = req.data.len();
            unsafe {
                *seq_out = req.sequence_number;
            }
            // Issue 1942 — the C slot has nowhere for the per-request
            // metadata, so it rides the subscription `MessageInfo` side
            // channel (`store_cffi_service_info`).
            let key = unsafe { (*server).backend_data as usize };
            crate::store_cffi_service_info(key, ServiceTrait::request_info(s));
            // Move the payload to the start of the buffer so the C
            // caller sees a `(buf, len)` pair starting at offset 0,
            // matching the cyclonedds backend's contract.
            if offset != 0 {
                let total = offset + len;
                // SAFETY: `slice[..total]` is initialised by the
                // backend; copy_within respects overlapping ranges.
                slice.copy_within(offset..total, 0);
            }
            // SAFETY: both checked non-null above.
            unsafe {
                *out_len = len;
                *taken = true;
            }
            NROS_RMW_RET_OK
        }
        Ok(None) => {
            // SAFETY: checked non-null above.
            unsafe { *taken = false };
            NROS_RMW_RET_OK
        }
        Err(e) => refused_ret(&e, ServiceTrait::refused_request_len(s), out_len),
    }
}

unsafe extern "C" fn has_request_trampoline<R: RustBackend>(
    server: *mut NrosRmwService,
    out_has_request: *mut bool,
) -> NrosRmwRet {
    // Phase 376 W3.d step A — see `has_data_trampoline`.
    if out_has_request.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(s) = (unsafe { service_ref::<R::Service>(server) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { *out_has_request = ServiceTrait::has_request(s) };
    NROS_RMW_RET_OK
}

unsafe extern "C" fn send_response_trampoline<R: RustBackend>(
    server: *const NrosRmwService,
    seq: i64,
    response: crate::generated::rmw_byte_span_t,
) -> NrosRmwRet {
    let Some(s) = (unsafe { service_mut::<R::Service>(server) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (data, len) = (response.data, response.len);
    if data.is_null() && len != 0 {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let slice = unsafe { core::slice::from_raw_parts(data, len) };
    match ServiceTrait::send_response(s, seq, slice) {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

// ============================================================================
// Trampolines — service client
// ============================================================================

unsafe extern "C" fn create_client_trampoline<R: RustBackend>(
    node: *const NrosRmwNode,
    // phase-406 W1 — the identity arrives as ONE argument, in upstream's
    // position. Unpacked immediately below so the body is unchanged.
    type_support: *const crate::generated::rmw_service_type_support_t,
    service_name: *const core::ffi::c_char,
    domain_id: u32,
    qos: *const NrosRmwQos,
    out: *mut NrosRmwClient,
) -> NrosRmwRet {
    // phase-406 W1 — unpack once, so the body below is untouched. A NULL
    // `type_support` is INVALID_ARGUMENT rather than a silent empty type: the
    // identity is what the backend keys its entity on, and an entity created
    // with no type is a subscription that matches nothing and reports nothing.
    let Some(ts) = (unsafe { type_support.as_ref() }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (type_name, type_hash) = (ts.type_name, ts.type_hash);
    if out.is_null() || qos.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    // Phase 376 W5/B1 — the node carries both halves now: its own identity, and
    // the route to its session (upstream's `context`). Reading the name off the
    // session was the `entity_view` fabrication, and it is gone.
    if node.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let session = unsafe { (*node).session };
    let Some(s) = (unsafe { session_mut::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let node_name = unsafe { node_name_of(node) };
    let namespace = unsafe { node_namespace_of(node) };
    let info = nros_rmw::ServiceInfo {
        name: unsafe { cstr_to_str(service_name) },
        type_name: unsafe { cstr_to_str(type_name) },
        type_hash: unsafe { cstr_to_str(type_hash) },
        domain_id,
        node_name,
        namespace,
    };
    let qos_settings = qos_from_cffi(unsafe { &*qos });
    match Session::create_client(s, &info, qos_settings) {
        Ok(client) => match box_handle(
            "service client",
            Hosted::new(client, |t: &R::Client, w| ClientTrait::register_waker(t, w)),
        ) {
            Ok(boxed) => {
                unsafe {
                    (*out).backend_data = boxed;
                }
                NROS_RMW_RET_OK
            }
            // Dropping the handle undeclares the entity the backend just made.
            Err(client) => {
                drop(client);
                NROS_RMW_RET_BAD_ALLOC
            }
        },
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn destroy_client_trampoline<R: RustBackend>(
    client: *mut NrosRmwClient,
) -> NrosRmwRet {
    let _ = unsafe { take_box::<Hosted<R::Client>>(client_data_mut(client)) };

    NROS_RMW_RET_OK
}

// Non-blocking send/recv trampolines — the one request/reply path
// (phase-301: the blocking `call_raw` slot is deleted).
unsafe extern "C" fn send_request_trampoline<R: RustBackend>(
    client: *const NrosRmwClient,
    request: crate::generated::rmw_byte_span_t,
    sequence_id: *mut i64,
) -> NrosRmwRet {
    let Some(c) = (unsafe { client_mut::<R::Client>(client) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (request, req_len) = (request.data, request.len);
    if request.is_null() && req_len != 0 {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let req = unsafe { core::slice::from_raw_parts(request, req_len) };
    match ClientTrait::send_request_raw(c, req) {
        Ok(seq) => {
            // Issue 0778 — hand the id back. NULL is tolerated for a caller
            // that genuinely has one call in flight and does not want it.
            if !sequence_id.is_null() {
                // SAFETY: checked non-null.
                unsafe { *sequence_id = seq };
            }
            NROS_RMW_RET_OK
        }
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn take_response_trampoline<R: RustBackend>(
    client: *const NrosRmwClient,
    reply: *mut crate::generated::rmw_mut_byte_span_t,
    seq_out: *mut i64,
    taken: *mut bool,
) -> NrosRmwRet {
    unsafe { take_response_impl::<R>(client, reply, seq_out, taken, core::ptr::null_mut()) }
}

/// Issue 2136 — `take_response` plus the reply's `rmw_service_info_t`, from
/// the backend's [`ClientTrait::response_info`] for the reply just taken.
unsafe extern "C" fn take_response_with_info_trampoline<R: RustBackend>(
    client: *const NrosRmwClient,
    reply: *mut crate::generated::rmw_mut_byte_span_t,
    seq_out: *mut i64,
    taken: *mut bool,
    service_info: *mut crate::generated::rmw_service_info_t,
) -> NrosRmwRet {
    if service_info.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    unsafe { take_response_impl::<R>(client, reply, seq_out, taken, service_info) }
}

/// Issue 2136 — [`nros_rmw::ServiceRequestInfo`] → `rmw_service_info_t`, the
/// inverse of `service_info_from_raw`: `None` becomes the ABI's zero.
fn service_info_to_raw(
    info: &nros_rmw::ServiceRequestInfo,
    out: &mut crate::generated::rmw_service_info_t,
) {
    out.source_timestamp = info.source_timestamp.map_or(0, |t| t.to_nanos());
    out.received_timestamp = info.received_timestamp.map_or(0, |t| t.to_nanos());
    match info.request_id {
        Some(id) => {
            for (dst, src) in out
                .request_id
                .writer_guid
                .iter_mut()
                .zip(id.writer_guid.iter())
            {
                *dst = *src as i8;
            }
            out.request_id.sequence_number = id.sequence_number;
        }
        None => {
            out.request_id.writer_guid = [0; 16];
            out.request_id.sequence_number = 0;
        }
    }
}

unsafe fn take_response_impl<R: RustBackend>(
    client: *const NrosRmwClient,
    reply: *mut crate::generated::rmw_mut_byte_span_t,
    seq_out: *mut i64,
    taken: *mut bool,
    service_info: *mut crate::generated::rmw_service_info_t,
) -> NrosRmwRet {
    // Phase 376 W3.b/W3.d step A — upstream `rmw_take_response`'s shape;
    // phase-406 W2 — one span in place of the buf/len/out_len triple.
    if reply.is_null() || taken.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(c) = (unsafe { client_mut::<R::Client>(client) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (reply_buf, reply_buf_len) = unsafe { ((*reply).data, (*reply).capacity) };
    let out_len = unsafe { &raw mut (*reply).len };
    if reply_buf.is_null() && reply_buf_len != 0 {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let reply = unsafe { core::slice::from_raw_parts_mut(reply_buf, reply_buf_len) };
    match ClientTrait::take_response_raw(c, reply) {
        Ok(Some((n, seq))) => {
            // SAFETY: both checked non-null above.
            unsafe {
                *out_len = n;
                *taken = true;
                if !seq_out.is_null() {
                    *seq_out = seq;
                }
            }
            if !service_info.is_null() {
                // SAFETY: checked non-null; caller-owned for the call.
                service_info_to_raw(&ClientTrait::response_info(c), unsafe {
                    &mut *service_info
                });
            }
            NROS_RMW_RET_OK
        }
        Ok(None) => {
            // SAFETY: checked non-null above.
            unsafe { *taken = false };
            NROS_RMW_RET_OK
        }
        Err(e) => refused_ret(&e, ClientTrait::refused_response_len(c), out_len),
    }
}

// ============================================================================
// Event-callback bridge (Phase 115.L.0.events)
// ============================================================================
//
// Events / liveliness / deadline are wired through the vtable (see the
// `subscription_event_init` / `publisher_event_init` /
// `publisher_assert_liveliness` / `next_deadline_ms` trampolines registered
// above) — the stale "TODO: wire through" header was removed (Phase 192.9).
//
// `NrosRmwEventCallback` (cffi shape) and `nros_rmw::EventCallback`
// (trait shape) have *layout-identical* arguments:
//
//   * NrosRmwEventKind  ↔ EventKind     — both `#[repr(u8)]`, same variant ids.
//   * *const NrosRmwEventPayload ↔ *const c_void  — fn-ptr-width pointer; the
//     trait callback dereferences as `*const LivelinessChangedStatus` /
//     `*const CountStatus`, the cffi callback dereferences as the matching
//     union member. The field-by-field layout matches today (see the
//     `const _: () = { … }` size/align asserts below).
//   * *mut c_void       ↔ *mut c_void   — identical.
//
// Therefore the cffi callback can be transmuted into a trait callback
// pointer; the receiving Rust trait code calls it via the trait
// signature, but the bytes on the wire are the cffi struct.

const _: () = {
    use core::mem::{align_of, size_of};
    assert!(
        size_of::<crate::NrosRmwLivelinessChangedStatus>()
            == size_of::<nros_rmw::LivelinessChangedStatus>()
    );
    assert!(
        align_of::<crate::NrosRmwLivelinessChangedStatus>()
            == align_of::<nros_rmw::LivelinessChangedStatus>()
    );
    assert!(size_of::<crate::NrosRmwCountStatus>() == size_of::<nros_rmw::CountStatus>());
    assert!(align_of::<crate::NrosRmwCountStatus>() == align_of::<nros_rmw::CountStatus>());
    // Issue 1972 — the matched and incompatible-type payloads.
    assert!(
        size_of::<crate::generated::rmw_matched_status_t>() == size_of::<nros_rmw::MatchedStatus>()
    );
    assert!(
        align_of::<crate::generated::rmw_matched_status_t>()
            == align_of::<nros_rmw::MatchedStatus>()
    );
    assert!(
        size_of::<crate::generated::rmw_incompatible_type_status_t>()
            == size_of::<nros_rmw::IncompatibleTypeStatus>()
    );
    assert!(
        align_of::<crate::generated::rmw_incompatible_type_status_t>()
            == align_of::<nros_rmw::IncompatibleTypeStatus>()
    );
    // EventKind tags must round-trip 0..=8 between the generated C
    // discriminants and the `#[repr(u8)]` trait enum.
    use crate::rmw_event_type_t as ck;
    assert!(
        ck::NROS_RMW_EVENT_LIVELINESS_CHANGED == nros_rmw::EventKind::LivelinessChanged as ck::Type
    );
    assert!(
        ck::NROS_RMW_EVENT_REQUESTED_DEADLINE_MISSED
            == nros_rmw::EventKind::RequestedDeadlineMissed as ck::Type
    );
    assert!(ck::NROS_RMW_EVENT_MESSAGE_LOST == nros_rmw::EventKind::MessageLost as ck::Type);
    assert!(ck::NROS_RMW_EVENT_LIVELINESS_LOST == nros_rmw::EventKind::LivelinessLost as ck::Type);
    assert!(
        ck::NROS_RMW_EVENT_OFFERED_DEADLINE_MISSED
            == nros_rmw::EventKind::OfferedDeadlineMissed as ck::Type
    );
    assert!(
        ck::NROS_RMW_EVENT_PUBLICATION_MATCHED
            == nros_rmw::EventKind::PublicationMatched as ck::Type
    );
    assert!(
        ck::NROS_RMW_EVENT_SUBSCRIPTION_MATCHED
            == nros_rmw::EventKind::SubscriptionMatched as ck::Type
    );
    assert!(
        ck::NROS_RMW_EVENT_PUBLISHER_INCOMPATIBLE_TYPE
            == nros_rmw::EventKind::PublisherIncompatibleType as ck::Type
    );
    assert!(
        ck::NROS_RMW_EVENT_SUBSCRIPTION_INCOMPATIBLE_TYPE
            == nros_rmw::EventKind::SubscriptionIncompatibleType as ck::Type
    );
};

unsafe extern "C" fn subscription_event_init_trampoline<R: RustBackend>(
    subscriber: *const NrosRmwSubscription,
    kind: NrosRmwEventKind,
    deadline_ms: u32,
    cb: NrosRmwEventCallback,
    user_context: *mut c_void,
) -> NrosRmwRet {
    let Some(s) = (unsafe { subscription_mut::<R::Subscription>(subscriber) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // Explicit conversion, not a transmute: `NrosRmwEventKind` is
    // C-uint-sized (#238) while trait `EventKind` is `#[repr(u8)]` —
    // reinterpreting bytes would be UB.
    let trait_kind: nros_rmw::EventKind = event_kind_from_c(kind);
    // The generated callback type is nullable; a NULL callback can't be
    // forwarded into the trait's non-null callback surface.
    let Some(cb) = cb else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: see module-level note. `cb`'s parameter types
    // `(NrosRmwEventKind, *const NrosRmwEventPayload, *mut c_void)` are
    // ABI-compatible with the trait's `(EventKind, *const c_void, *mut c_void)`.
    let trait_cb: nros_rmw::EventCallback = unsafe { core::mem::transmute(cb) };
    let res = unsafe {
        Subscription::register_event_callback(s, trait_kind, deadline_ms, trait_cb, user_context)
    };
    match res {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => {
            // Backend's `Unsupported` mapping for events is its
            // `serialization_error()` by trait-doc default; the cffi
            // contract for "this event kind unsupported" is its own
            // ret code, so map any error here to UNSUPPORTED rather
            // than e.g. SERIALIZATION_ERROR — the caller's mental
            // model is "vtable said no events," not "marshalling
            // failed."
            let _ = e;
            NROS_RMW_RET_UNSUPPORTED
        }
    }
}

unsafe extern "C" fn publisher_event_init_trampoline<R: RustBackend>(
    publisher: *const NrosRmwPublisher,
    kind: NrosRmwEventKind,
    deadline_ms: u32,
    cb: NrosRmwEventCallback,
    user_context: *mut c_void,
) -> NrosRmwRet {
    // Publisher::register_event_callback takes `&mut self`. Need a
    // mut-ptr to the boxed handle.
    if publisher.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let p_ptr = unsafe { (*publisher).backend_data } as *mut R::Publisher;
    if p_ptr.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let p = unsafe { &mut *p_ptr };
    // Explicit conversion, not a transmute (see subscriber trampoline / #238).
    let trait_kind: nros_rmw::EventKind = event_kind_from_c(kind);
    let Some(cb) = cb else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let trait_cb: nros_rmw::EventCallback = unsafe { core::mem::transmute(cb) };
    let res = unsafe {
        Publisher::register_event_callback(p, trait_kind, deadline_ms, trait_cb, user_context)
    };
    match res {
        Ok(()) => NROS_RMW_RET_OK,
        Err(_) => NROS_RMW_RET_UNSUPPORTED,
    }
}

// --------------------------------------------------------------------------
// Granted-QoS read-back — the six slots
// --------------------------------------------------------------------------
//
// A Rust backend answers these from its `actual_qos` family, whose trait
// default is `QOS_PROFILE_UNKNOWN`. Installed UNCONDITIONALLY for every `R`,
// on the same reasoning as `supported_qos_policies`: the default answer is
// every policy an absence, which is exactly what a NULL slot already means to
// the caller (`read_granted_qos` stores `qos_unknown_c()` for one), so
// installing them for a backend that determines nothing changes nothing.
//
// The lowering is `NrosRmwQos::try_from`, whose one failure is a depth past
// `u16::MAX`. A backend cannot GRANT a depth it could not have been asked for
// — the request came through the same conversion — so this is a real
// `NROS_RMW_RET_ERROR` rather than a case to paper over.

/// Write one Rust-side profile into a C read-back out-parameter.
///
/// # Safety
/// `out` must be non-null and point at writable `rmw_qos_profile_t` storage.
unsafe fn write_actual_qos(out: *mut NrosRmwQos, qos: QoSProfile) -> NrosRmwRet {
    let Ok(lowered) = NrosRmwQos::try_from(qos) else {
        return crate::NROS_RMW_RET_ERROR;
    };
    // SAFETY: the caller's contract.
    unsafe { *out = lowered };
    NROS_RMW_RET_OK
}

unsafe extern "C" fn publisher_get_actual_qos_trampoline<R: RustBackend>(
    publisher: *const NrosRmwPublisher,
    out: *mut NrosRmwQos,
) -> NrosRmwRet {
    if out.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(p) = (unsafe { publisher_ref::<R::Publisher>(publisher) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { write_actual_qos(out, Publisher::actual_qos(p)) }
}

unsafe extern "C" fn subscription_get_actual_qos_trampoline<R: RustBackend>(
    subscription: *const NrosRmwSubscription,
    out: *mut NrosRmwQos,
) -> NrosRmwRet {
    if out.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(sub) = (unsafe { subscription_ref::<R::Subscription>(subscription) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { write_actual_qos(out, Subscription::actual_qos(sub)) }
}

unsafe extern "C" fn client_request_publisher_get_actual_qos_trampoline<R: RustBackend>(
    client: *const NrosRmwClient,
    out: *mut NrosRmwQos,
) -> NrosRmwRet {
    if out.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(c) = (unsafe { client_mut::<R::Client>(client) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { write_actual_qos(out, ClientTrait::request_publisher_actual_qos(c)) }
}

unsafe extern "C" fn client_response_subscription_get_actual_qos_trampoline<R: RustBackend>(
    client: *const NrosRmwClient,
    out: *mut NrosRmwQos,
) -> NrosRmwRet {
    if out.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(c) = (unsafe { client_mut::<R::Client>(client) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { write_actual_qos(out, ClientTrait::response_subscription_actual_qos(c)) }
}

unsafe extern "C" fn service_request_subscription_get_actual_qos_trampoline<R: RustBackend>(
    service: *const NrosRmwService,
    out: *mut NrosRmwQos,
) -> NrosRmwRet {
    if out.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(sv) = (unsafe { service_ref::<R::Service>(service) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { write_actual_qos(out, ServiceTrait::request_subscription_actual_qos(sv)) }
}

unsafe extern "C" fn service_response_publisher_get_actual_qos_trampoline<R: RustBackend>(
    service: *const NrosRmwService,
    out: *mut NrosRmwQos,
) -> NrosRmwRet {
    if out.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(sv) = (unsafe { service_ref::<R::Service>(service) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: checked non-null above.
    unsafe { write_actual_qos(out, ServiceTrait::response_publisher_actual_qos(sv)) }
}

unsafe extern "C" fn publisher_assert_liveliness_trampoline<R: RustBackend>(
    publisher: *const NrosRmwPublisher,
) -> NrosRmwRet {
    let Some(p) = (unsafe { publisher_ref::<R::Publisher>(publisher) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    match Publisher::assert_liveliness(p) {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

/// Upstream `rmw_get_gid_for_publisher` — the phase-467 RMW gap-closure
/// design study's Q1.
///
/// This slot was NULL on the Rust adapter table until that study, so a Rust
/// backend with a real publisher identity — zenoh has one, the gid it stamps
/// into every outgoing attachment — could not report it through any language
/// surface. `Publisher::get_gid`'s default is `Unsupported`, so a backend
/// that does not override it still answers honestly here.
///
/// Only `data` is written. `implementation_identifier` is left as the caller
/// found it: `CffiPublisher::get_gid` discards it (the identifier a caller
/// needs is the one on the session it asked), and writing a pointer the
/// trampoline would have to source from a second slot is a second place for
/// it to disagree.
unsafe extern "C" fn get_gid_for_publisher_trampoline<R: RustBackend>(
    publisher: *const NrosRmwPublisher,
    gid: *mut NrosRmwGid,
) -> NrosRmwRet {
    if gid.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(p) = (unsafe { publisher_ref::<R::Publisher>(publisher) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    match Publisher::get_gid(p) {
        Ok(bytes) => {
            // SAFETY: checked non-null above; the caller owns the storage.
            unsafe {
                (*gid).data = bytes;
            }
            NROS_RMW_RET_OK
        }
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn next_deadline_ms_trampoline<R: RustBackend>(
    session: *const NrosRmwSession,
    out_ms: *mut u32,
    has_deadline: *mut bool,
) -> NrosRmwRet {
    // Phase 376 W3.d step A — value and presence out, status returned.
    if out_ms.is_null() || has_deadline.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    // A NULL session was previously reported as `-1`, indistinguishable from a
    // link with nothing scheduled. It is an invalid argument.
    let Some(s) = (unsafe { session_ref::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    match Session::next_deadline_ms(s) {
        Some(ms) => {
            // SAFETY: both checked non-null above.
            unsafe {
                *out_ms = ms;
                *has_deadline = true;
            }
        }
        None => {
            // SAFETY: checked non-null above.
            unsafe { *has_deadline = false };
        }
    }
    NROS_RMW_RET_OK
}

unsafe extern "C" fn set_wake_callback_trampoline<R: RustBackend>(
    session: *mut NrosRmwSession,
    cb: Option<unsafe extern "C" fn(ctx: *mut core::ffi::c_void)>,
    ctx: *mut core::ffi::c_void,
) -> NrosRmwRet {
    let Some(s) = (unsafe { session_mut::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // Phase 124.B.1 — delegate to the Rust backend. Default trait
    // body ignores; concrete backends opt in.
    // SAFETY: this trampoline forwards the C ABI's callback/context
    // lifetime contract to the Rust backend.
    unsafe { Session::set_wake_callback(s, cb, ctx) };
    NROS_RMW_RET_OK
}

unsafe extern "C" fn readiness_source_trampoline<R: RustBackend>(
    session: *const NrosRmwSession,
    out_kind: *mut u8,
    out_handle: *mut i32,
) -> NrosRmwRet {
    if out_kind.is_null() || out_handle.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(s) = (unsafe { session_ref::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (kind, handle) = match Session::readiness_source(s) {
        nros_rmw::ReadinessSource::None => (crate::generated::NROS_RMW_READINESS_NONE, -1),
        nros_rmw::ReadinessSource::Notify => (crate::generated::NROS_RMW_READINESS_NOTIFY, -1),
        nros_rmw::ReadinessSource::Waitable(fd) => {
            (crate::generated::NROS_RMW_READINESS_WAITABLE, fd)
        }
    };
    // SAFETY: both checked non-null above.
    unsafe {
        *out_kind = kind as u8;
        *out_handle = handle;
    }
    NROS_RMW_RET_OK
}

/// Issue 1940 — the bytes the adapter allocates for a subscription, service
/// or client handle of type `T`: the handle plus its wake registration
/// (`crate::entity_wake::Hosted`). For a test that refuses that allocation,
/// such as `tests/adapter_oom.rs`, which must not re-derive the wrapper's
/// layout.
#[doc(hidden)]
pub const fn entity_box_size<T>() -> usize {
    core::mem::size_of::<Hosted<T>>()
}

// Issue 1940 — the per-entity new-data callback slots. The registration lives in the
// entity's `Hosted` wrapper; see `crate::entity_wake`.
unsafe extern "C" fn subscription_set_on_new_message_callback_trampoline<R: RustBackend>(
    subscription: *mut NrosRmwSubscription,
    cb: Option<EntityWakeCb>,
    user_data: *const c_void,
) -> NrosRmwRet {
    if subscription.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let data = unsafe { *subscription_data_mut(subscription) };
    unsafe { Hosted::<R::Subscription>::set_wake(data, cb, user_data) }
}

unsafe extern "C" fn service_set_on_new_request_callback_trampoline<R: RustBackend>(
    service: *mut NrosRmwService,
    cb: Option<EntityWakeCb>,
    user_data: *const c_void,
) -> NrosRmwRet {
    if service.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let data = unsafe { *service_data_mut(service) };
    unsafe { Hosted::<R::Service>::set_wake(data, cb, user_data) }
}

unsafe extern "C" fn client_set_on_new_response_callback_trampoline<R: RustBackend>(
    client: *mut NrosRmwClient,
    cb: Option<EntityWakeCb>,
    user_data: *const c_void,
) -> NrosRmwRet {
    if client.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let data = unsafe { *client_data_mut(client) };
    unsafe { Hosted::<R::Client>::set_wake(data, cb, user_data) }
}

/// phase-467 Row 8 — the graph-CHANGE edge for every Rust backend.
///
/// Unlike `set_wake_callback_trampoline` above, the STATUS is carried: a
/// backend with no graph must be able to say `UNSUPPORTED`, because the
/// runtime probes with a `NULL` clear before it consumes an executor handle
/// slot, and a trampoline that always answered `OK` would hand back a guard
/// condition nothing can trigger. That is precisely the silent difference this
/// row exists to remove.
unsafe extern "C" fn node_get_graph_guard_condition_trampoline<R: RustBackend>(
    session: *mut NrosRmwSession,
    callback: crate::generated::rmw_event_callback_t,
    user_data: *const core::ffi::c_void,
) -> NrosRmwRet {
    let Some(s) = (unsafe { session_mut::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: forwards the C ABI's callback/user_data lifetime contract to the
    // Rust backend; the installer owes the matching clear.
    match unsafe { Session::set_graph_change_callback(s, callback, user_data) } {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn service_server_is_available_trampoline<R: RustBackend>(
    client: *const NrosRmwClient,
    out_available: *mut bool,
) -> NrosRmwRet {
    // Phase 124.C.1 — delegate to the Rust backend's
    // `ClientTrait::server_available` impl. Default trait
    // body returns `Err(TransportError::Unsupported)`; concrete
    // backends opt in by overriding.
    //
    // Phase 376 W3.d step A — status in the return, answer in the
    // out-parameter. `*out_available` is written ONLY on OK, so an
    // error leaves whatever the caller initialised it to; that is
    // upstream's contract and it is also what keeps a caller who
    // ignores the status from reading a stale `true` as fresh.
    if out_available.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(c) = (unsafe { client_mut::<R::Client>(client) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    match ClientTrait::service_is_ready(c) {
        Ok(available) => {
            // SAFETY: checked non-null above; the caller owns a `bool`.
            unsafe { *out_available = available };
            NROS_RMW_RET_OK
        }
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn ping_session_trampoline<R: RustBackend>(
    session: *mut NrosRmwSession,
    timeout_ms: i32,
) -> NrosRmwRet {
    // Phase 124.F.1 — delegate to the Rust backend's
    // `Session::ping_session` impl. Default trait body returns
    // `Err(TransportError::Unsupported)`; concrete backends opt in
    // by overriding.
    let Some(s) = (unsafe { session_mut::<R::Session>(session) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    match Session::ping_session(s, timeout_ms) {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

/// phase-381 W3 — bridge the C visitor to the Rust `Session::get_node_names`.
///
/// The C side hands a `rmw_node_visit_fn` plus an opaque `ctx`; the Rust trait
/// takes a closure. This wraps the former in the latter, and the strings it
/// passes are NUL-terminated on the stack because the C contract borrows them
/// for the call only — no allocation on either side of the seam.
///
/// A name that does not fit the stack buffer is SKIPPED rather than truncated:
/// a truncated node name is a different, plausible node.
unsafe extern "C" fn get_node_names_trampoline<R: RustBackend>(
    session: *const NrosRmwSession,
    // phase-406 W2 — the pair as one argument. The NODE visitor: its callback
    // takes an enclave, which the names-and-types one does not.
    visitor: crate::generated::rmw_node_visitor_t,
) -> NrosRmwRet {
    let (visit, ctx) = (visitor.visit, visitor.ctx);
    let Some(visit) = visit else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let Some(s) = (unsafe { session_mut::<R::Session>(session.cast_mut()) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };

    /// Longest node name / namespace this seam will pass through.
    const NAME_MAX: usize = 256;

    let mut cb = |name: &str, namespace: &str, enclave: Option<&str>| -> bool {
        let mut name_buf = [0u8; NAME_MAX];
        let mut ns_buf = [0u8; NAME_MAX];
        let mut enc_buf = [0u8; NAME_MAX];
        // `< NAME_MAX`, not `<= `: the buffer must hold the bytes AND the NUL
        // the C side reads to. Spelled as the strict compare clippy wants
        // (`int_plus_one`) rather than the `len + 1 <= cap` that says it.
        if name.len() >= NAME_MAX || namespace.len() >= NAME_MAX {
            return true; // skip this one, keep enumerating
        }
        name_buf[..name.len()].copy_from_slice(name.as_bytes());
        ns_buf[..namespace.len()].copy_from_slice(namespace.as_bytes());
        let enc_ptr = match enclave {
            Some(e) if e.len() < NAME_MAX => {
                enc_buf[..e.len()].copy_from_slice(e.as_bytes());
                enc_buf.as_ptr() as *const c_char
            }
            // NULL is the contract's "this backend does not track one", which
            // is what lets one slot answer both `rmw_get_node_names` and
            // `rmw_get_node_names_with_enclaves`.
            _ => core::ptr::null(),
        };
        unsafe {
            visit(
                ctx,
                name_buf.as_ptr() as *const c_char,
                ns_buf.as_ptr() as *const c_char,
                enc_ptr,
            )
        }
    };

    match Session::get_node_names(s, &mut cb) {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

/// phase-381 W3 — `count_publishers` / `count_subscribers` share one body.
macro_rules! count_trampoline {
    ($name:ident, $method:ident) => {
        unsafe extern "C" fn $name<R: RustBackend>(
            session: *const NrosRmwSession,
            topic_name: *const c_char,
            count: *mut usize,
        ) -> NrosRmwRet {
            if topic_name.is_null() || count.is_null() {
                return NROS_RMW_RET_INVALID_ARGUMENT;
            }
            let Some(s) = (unsafe { session_mut::<R::Session>(session.cast_mut()) }) else {
                return NROS_RMW_RET_INVALID_ARGUMENT;
            };
            let Ok(topic) = (unsafe { core::ffi::CStr::from_ptr(topic_name) }).to_str() else {
                return NROS_RMW_RET_INVALID_ARGUMENT;
            };
            match Session::$method(s, topic) {
                Ok(n) => {
                    unsafe { *count = n };
                    NROS_RMW_RET_OK
                }
                Err(e) => ret_from_error(&e),
            }
        }
    };
}

count_trampoline!(count_publishers_trampoline, count_publishers);
count_trampoline!(count_subscribers_trampoline, count_subscribers);
// Issue 1978 — the service twins. The name is a SERVICE name; the body is the
// same.
count_trampoline!(count_clients_trampoline, count_clients);
count_trampoline!(count_services_trampoline, count_services);

/// Issue 1978 — upstream (Jazzy) `rmw_get_gid_for_client`, the client twin of
/// [`get_gid_for_publisher_trampoline`], and like it writes only `data`.
unsafe extern "C" fn get_gid_for_client_trampoline<R: RustBackend>(
    client: *const NrosRmwClient,
    gid: *mut NrosRmwGid,
) -> NrosRmwRet {
    if gid.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(c) = (unsafe { client_mut::<R::Client>(client) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    match ClientTrait::get_gid(&*c) {
        Ok(bytes) => {
            // SAFETY: checked non-null above; the caller owns the storage.
            unsafe {
                (*gid).data = bytes;
            }
            NROS_RMW_RET_OK
        }
        Err(e) => ret_from_error(&e),
    }
}

/// Issue 1978 — upstream (Jazzy) `rmw_event_type_is_supported`, answered from
/// the backend TYPE (`Session::event_type_is_supported`, a static fn: the slot
/// carries no session). A discriminant outside the nine known kinds is
/// `false` — `event_kind_from_c` folds unknown values into `MessageLost`,
/// which would answer for a kind nobody asked about.
unsafe extern "C" fn event_type_is_supported_trampoline<R: RustBackend>(
    event_type: NrosRmwEventKind,
) -> bool {
    use crate::rmw_event_type_t as ck;
    let known = matches!(
        event_type,
        ck::NROS_RMW_EVENT_LIVELINESS_CHANGED
            | ck::NROS_RMW_EVENT_REQUESTED_DEADLINE_MISSED
            | ck::NROS_RMW_EVENT_MESSAGE_LOST
            | ck::NROS_RMW_EVENT_LIVELINESS_LOST
            | ck::NROS_RMW_EVENT_OFFERED_DEADLINE_MISSED
            | ck::NROS_RMW_EVENT_PUBLICATION_MATCHED
            | ck::NROS_RMW_EVENT_SUBSCRIPTION_MATCHED
            | ck::NROS_RMW_EVENT_PUBLISHER_INCOMPATIBLE_TYPE
            | ck::NROS_RMW_EVENT_SUBSCRIPTION_INCOMPATIBLE_TYPE
    );
    known && <R::Session as Session>::event_type_is_supported(event_kind_from_c(event_type))
}

/// phase-381 W3 — `get_topic_names_and_types` / `get_service_names_and_types`.
///
/// The C visitor takes `(name, types[], types_count)`. Rust hands over
/// `&[&str]`, so each call builds a bounded array of NUL-terminated pointers on
/// the stack — the strings are borrowed for the call only, which is the
/// contract on both sides.
///
/// A name or type that does not fit is SKIPPED, never truncated: a truncated
/// type name is a different, plausible type.
macro_rules! names_and_types_trampoline {
    // The topic form carries `no_demangle`; the service form does not — that
    // asymmetry is upstream's, mirrored rather than smoothed over.
    ($name:ident, $method:ident, demangle_flag) => {
        unsafe extern "C" fn $name<R: RustBackend>(
            session: *const NrosRmwSession,
            no_demangle: bool,
            // phase-406 W2 — the pair as one argument.
            visitor: crate::generated::rmw_names_and_types_visitor_t,
        ) -> NrosRmwRet {
            // `no_demangle` asks for the WIRE spelling. This backend reports ROS
            // names, so honouring it would mean re-mangling what was just
            // demangled; refused rather than silently ignored, because ignoring
            // it answers a different question than the caller asked.
            if no_demangle {
                return NROS_RMW_RET_UNSUPPORTED;
            }
            $crate::names_and_types_body!(R, $method, session, visitor)
        }
    };
    ($name:ident, $method:ident) => {
        unsafe extern "C" fn $name<R: RustBackend>(
            session: *const NrosRmwSession,
            // phase-406 W2 — the pair as one argument.
            visitor: crate::generated::rmw_names_and_types_visitor_t,
        ) -> NrosRmwRet {
            $crate::names_and_types_body!(R, $method, session, visitor)
        }
    };
}

/// The shared body, so the two arms above differ only by the parameter list.
#[macro_export]
#[doc(hidden)]
macro_rules! names_and_types_body {
    ($R:ident, $method:ident, $session:ident, $visitor:ident) => {{
        // phase-406 W2 — unpack HERE: a `let` in the caller's expansion is not
        // visible in this one (macro hygiene), so the struct crosses instead.
        let (visit_fn, ctx) = ($visitor.visit, $visitor.ctx);
        let Some(visit) = visit_fn else {
            return NROS_RMW_RET_INVALID_ARGUMENT;
        };
        let Some(s) = (unsafe { session_mut::<$R::Session>($session.cast_mut()) }) else {
            return NROS_RMW_RET_INVALID_ARGUMENT;
        };

        const NAME_MAX: usize = 256;
        const TYPES_MAX: usize = 8;

        let mut cb = |name: &str, types: &[&str]| -> bool {
            let mut name_buf = [0u8; NAME_MAX];
            if name.len() >= NAME_MAX {
                return true; // skip, keep enumerating
            }
            name_buf[..name.len()].copy_from_slice(name.as_bytes());

            let mut type_bufs = [[0u8; NAME_MAX]; TYPES_MAX];
            let mut ptrs: [*const c_char; TYPES_MAX] = [core::ptr::null(); TYPES_MAX];
            let mut n = 0usize;
            for t in types.iter().take(TYPES_MAX) {
                if t.len() >= NAME_MAX {
                    continue;
                }
                type_bufs[n][..t.len()].copy_from_slice(t.as_bytes());
                ptrs[n] = type_bufs[n].as_ptr() as *const c_char;
                n += 1;
            }
            unsafe { visit(ctx, name_buf.as_ptr() as *const c_char, ptrs.as_ptr(), n) }
        };

        match Session::$method(s, &mut cb) {
            Ok(()) => NROS_RMW_RET_OK,
            Err(e) => ret_from_error(&e),
        }
    }};
}

names_and_types_trampoline!(
    get_topic_names_and_types_trampoline,
    get_topic_names_and_types,
    demangle_flag
);
names_and_types_trampoline!(
    get_service_names_and_types_trampoline,
    get_service_names_and_types
);

/// phase-381 W3 — the four `*_by_node` slots, one body.
///
/// Longhand callers, shared implementation: they differ only by which
/// `GraphEntityKind` they pass, and four copies of this marshalling is four
/// chances for one of them to drift.
///
/// # Safety
/// Same contract as the slots that call it.
unsafe fn by_node_impl<R: RustBackend>(
    session: *const NrosRmwSession,
    node_name: *const c_char,
    node_namespace: *const c_char,
    no_demangle: bool,
    // phase-406 W2 — the pair as one argument.
    visitor: crate::generated::rmw_names_and_types_visitor_t,
    kind: nros_rmw::GraphEntityKind,
) -> NrosRmwRet {
    let (visit, ctx) = (visitor.visit, visitor.ctx);
    // `no_demangle` asks for the WIRE spelling; we report ROS names, so
    // honouring it would mean re-mangling what was just demangled. Refused
    // rather than ignored — ignoring answers a different question than asked.
    if no_demangle {
        return NROS_RMW_RET_UNSUPPORTED;
    }
    if node_name.is_null() || node_namespace.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(visit) = visit else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let Some(s) = (unsafe { session_mut::<R::Session>(session.cast_mut()) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let (Ok(name), Ok(ns)) = (
        unsafe { core::ffi::CStr::from_ptr(node_name) }.to_str(),
        unsafe { core::ffi::CStr::from_ptr(node_namespace) }.to_str(),
    ) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };

    const NAME_MAX: usize = 256;
    const TYPES_MAX: usize = 8;
    let mut cb = |n: &str, types: &[&str]| -> bool {
        let mut name_buf = [0u8; NAME_MAX];
        if n.len() >= NAME_MAX {
            return true;
        }
        name_buf[..n.len()].copy_from_slice(n.as_bytes());
        let mut type_bufs = [[0u8; NAME_MAX]; TYPES_MAX];
        let mut ptrs: [*const c_char; TYPES_MAX] = [core::ptr::null(); TYPES_MAX];
        let mut count = 0usize;
        for t in types.iter().take(TYPES_MAX) {
            if t.len() >= NAME_MAX {
                continue;
            }
            type_bufs[count][..t.len()].copy_from_slice(t.as_bytes());
            ptrs[count] = type_bufs[count].as_ptr() as *const c_char;
            count += 1;
        }
        unsafe {
            visit(
                ctx,
                name_buf.as_ptr() as *const c_char,
                ptrs.as_ptr(),
                count,
            )
        }
    };
    match Session::get_names_and_types_by_node(s, kind, name, ns, &mut cb) {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

macro_rules! by_node_trampoline {
    // Upstream gives `no_demangle` to the publisher and subscriber forms and
    // NOT to the service and client ones. Mirrored rather than smoothed over —
    // RFC-0054 makes these headers the ABI SSoT, so an asymmetry upstream has
    // is one we have.
    ($name:ident, $kind:ident, no_demangle) => {
        unsafe extern "C" fn $name<R: RustBackend>(
            session: *const NrosRmwSession,
            node_name: *const c_char,
            node_namespace: *const c_char,
            no_demangle: bool,
            // phase-406 W2 — the pair as one argument.
            visitor: crate::generated::rmw_names_and_types_visitor_t,
        ) -> NrosRmwRet {
            unsafe {
                by_node_impl::<R>(
                    session,
                    node_name,
                    node_namespace,
                    no_demangle,
                    visitor,
                    nros_rmw::GraphEntityKind::$kind,
                )
            }
        }
    };
    // The service and client forms, which upstream gives no `no_demangle`.
    ($name:ident, $kind:ident) => {
        unsafe extern "C" fn $name<R: RustBackend>(
            session: *const NrosRmwSession,
            node_name: *const c_char,
            node_namespace: *const c_char,
            // phase-406 W2 — the pair as one argument.
            visitor: crate::generated::rmw_names_and_types_visitor_t,
        ) -> NrosRmwRet {
            unsafe {
                by_node_impl::<R>(
                    session,
                    node_name,
                    node_namespace,
                    false,
                    visitor,
                    nros_rmw::GraphEntityKind::$kind,
                )
            }
        }
    };
}

by_node_trampoline!(
    get_publisher_names_and_types_by_node_trampoline,
    Publisher,
    no_demangle
);
by_node_trampoline!(
    get_subscriber_names_and_types_by_node_trampoline,
    Subscriber,
    no_demangle
);
by_node_trampoline!(get_service_names_and_types_by_node_trampoline, Service);
by_node_trampoline!(get_client_names_and_types_by_node_trampoline, Client);

/// phase-381 W3 — the two `*_info_by_topic` slots, one body.
///
/// # Safety
/// Same contract as the slots that call it.
unsafe fn endpoint_info_impl<R: RustBackend>(
    session: *const NrosRmwSession,
    topic_name: *const c_char,
    no_mangle: bool,
    // phase-406 W2 — the pair as one argument.
    visitor: crate::generated::rmw_topic_endpoint_info_visitor_t,
    publishers: bool,
) -> NrosRmwRet {
    let (visit, ctx) = (visitor.visit, visitor.ctx);
    if no_mangle {
        return NROS_RMW_RET_UNSUPPORTED;
    }
    if topic_name.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    let Some(visit) = visit else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let Some(s) = (unsafe { session_mut::<R::Session>(session.cast_mut()) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    let Ok(topic) = (unsafe { core::ffi::CStr::from_ptr(topic_name) }).to_str() else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };

    const NAME_MAX: usize = 256;
    let mut cb = |info: &nros_rmw::GraphEndpointInfo<'_>| -> bool {
        let mut name_buf = [0u8; NAME_MAX];
        let mut ns_buf = [0u8; NAME_MAX];
        let mut ty_buf = [0u8; NAME_MAX];
        if info.node_name.len() >= NAME_MAX
            || info.node_namespace.len() >= NAME_MAX
            || info.topic_type.len() >= NAME_MAX
        {
            return true; // skip, never truncate
        }
        name_buf[..info.node_name.len()].copy_from_slice(info.node_name.as_bytes());
        ns_buf[..info.node_namespace.len()].copy_from_slice(info.node_namespace.as_bytes());
        ty_buf[..info.topic_type.len()].copy_from_slice(info.topic_type.as_bytes());
        // The struct has no "qos known" flag, by design: the ABI expresses an
        // unreadable policy with the `*_UNKNOWN` sentinels and the contract on
        // `publisher_get_actual_qos` spells it out — write UNKNOWN for what you
        // cannot determine and return OK; `UNSUPPORTED` means no read-back AT
        // ALL, not "I know some of it".
        //
        // issue 1973 — the backend's own answer crosses now
        // (`GraphEndpointInfo::qos`; zenoh decodes the token's QoS chunk). It
        // is already `QOS_PROFILE_UNKNOWN` where the backend could not read
        // one; a depth the C ABI's u16 cannot carry also degrades to that,
        // never to a truncated guess.
        let qos: rmw_qos_profile_t = match NrosRmwQos::try_from(info.qos) {
            Ok(q) => q,
            Err(_) => {
                let mut q: rmw_qos_profile_t = unsafe { core::mem::zeroed() };
                q.reliability = NROS_RMW_RELIABILITY_UNKNOWN as u8;
                q.durability = NROS_RMW_DURABILITY_UNKNOWN as u8;
                q.history = NROS_RMW_HISTORY_UNKNOWN as u8;
                q.liveliness_kind = rmw_liveliness_kind_t::NROS_RMW_LIVELINESS_UNKNOWN as u8;
                q
            }
        };
        let c_info = rmw_topic_endpoint_info_t {
            node_name: name_buf.as_ptr() as *const c_char,
            node_namespace: ns_buf.as_ptr() as *const c_char,
            topic_type: ty_buf.as_ptr() as *const c_char,
            endpoint_type: if info.is_publisher {
                rmw_endpoint_type_t::RMW_ENDPOINT_PUBLISHER
            } else {
                rmw_endpoint_type_t::RMW_ENDPOINT_SUBSCRIPTION
            },
            endpoint_gid: rmw_gid_t {
                implementation_identifier: core::ptr::null(),
                data: info.endpoint_gid,
            },
            qos_profile: qos,
        };
        unsafe { visit(ctx, &c_info as *const rmw_topic_endpoint_info_t) }
    };
    match Session::get_endpoint_info_by_topic(s, publishers, topic, &mut cb) {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

macro_rules! endpoint_info_trampoline {
    ($name:ident, $publishers:expr) => {
        unsafe extern "C" fn $name<R: RustBackend>(
            session: *const NrosRmwSession,
            topic_name: *const c_char,
            no_mangle: bool,
            // phase-406 W2 — the pair as one argument.
            visitor: crate::generated::rmw_topic_endpoint_info_visitor_t,
        ) -> NrosRmwRet {
            unsafe { endpoint_info_impl::<R>(session, topic_name, no_mangle, visitor, $publishers) }
        }
    };
}

endpoint_info_trampoline!(get_publishers_info_by_topic_trampoline, true);
endpoint_info_trampoline!(get_subscriptions_info_by_topic_trampoline, false);

unsafe extern "C" fn publish_streamed_trampoline<R: RustBackend>(
    publisher: *mut NrosRmwPublisher,
    size_cb: Option<unsafe extern "C" fn(out_total_len: *mut usize, user_ctx: *mut c_void)>,
    chunk_cb: Option<
        unsafe extern "C" fn(
            out_buf: *mut u8,
            cap: usize,
            out_written: *mut usize,
            user_ctx: *mut c_void,
        ),
    >,
    user_ctx: *mut c_void,
) -> NrosRmwRet {
    // Phase 124.E.1 — delegate to the Rust backend's
    // `Publisher::publish_streamed` impl. Default trait body fires
    // the staging-buffer fallback (124.E.2); concrete backends opt
    // in by overriding for true streamed publish into the network
    // buffer.
    let Some(p) = (unsafe { publisher_ref::<R::Publisher>(publisher) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // Generated ABI marks the callbacks nullable; the trait surface is not.
    let (Some(size_cb), Some(chunk_cb)) = (size_cb, chunk_cb) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    // SAFETY: this trampoline is entered from the C ABI with the same
    // callback/user_ctx lifetime contract required by `Publisher::publish_streamed`.
    match unsafe { Publisher::publish_streamed(p, size_cb, chunk_cb, user_ctx) } {
        Ok(()) => NROS_RMW_RET_OK,
        Err(e) => ret_from_error(&e),
    }
}

unsafe extern "C" fn take_sequence_trampoline<R: RustBackend>(
    subscriber: *const NrosRmwSubscription,
    buf: *mut u8,
    per_msg_cap: usize,
    max_msgs: usize,
    out_lens: *mut usize,
    taken: *mut usize,
) -> NrosRmwRet {
    // Phase 376 W3.b/W3.d step A — the COUNT is an out-parameter, matching
    // upstream's `size_t *taken`.
    if taken.is_null() {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    // Phase 124.D.1 — delegate to the Rust backend's
    // `Subscription::take_sequence` impl. Default trait body
    // loop-drives `take_serialized`; concrete backends opt in by
    // overriding for a native batch take.
    let Some(s) = (unsafe { subscription_mut::<R::Subscription>(subscriber) }) else {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    };
    if buf.is_null() || out_lens.is_null() || per_msg_cap == 0 {
        return NROS_RMW_RET_INVALID_ARGUMENT;
    }
    // SAFETY: caller pinky-promised a contiguous block of
    // `max_msgs * per_msg_cap` bytes at `buf` and at least
    // `max_msgs` `usize` slots at `out_lens`. The buffer is
    // exclusively borrowed for the duration of this call.
    let buf_slice =
        unsafe { core::slice::from_raw_parts_mut(buf, max_msgs.saturating_mul(per_msg_cap)) };
    let lens_slice = unsafe { core::slice::from_raw_parts_mut(out_lens, max_msgs) };
    match Subscription::take_sequence(s, buf_slice, per_msg_cap, max_msgs, lens_slice) {
        Ok(count) => {
            // SAFETY: checked non-null above.
            unsafe { *taken = count };
            NROS_RMW_RET_OK
        }
        Err(e) => ret_from_error(&e),
    }
}

// ============================================================================
// Pointer plumbing — keep one place where each entity's
// `backend_data` is dereferenced.
// ============================================================================
//
// Validity contract:
//
//   - The C-side wrappers (`CffiSession`, `CffiPublisher`, …) hand
//     each trampoline an entity-struct pointer whose `backend_data`
//     was last written by *this* adapter's create-trampoline. That
//     write is `box_handle(handle)` (a fallible `Box`) of `R::Session` /
//     `R::Publisher` / … so the pointer aliases a valid Box<T>.
//   - `_mut` variants give `&mut T`; the runtime serialises access
//     per the executor's single-thread invariant.
//   - `take_box` reclaims ownership; subsequent calls see a null
//     `backend_data` and return `INVALID_ARGUMENT`.

#[inline]
unsafe fn session_data_mut(session: *mut NrosRmwSession) -> &'static mut *mut c_void {
    unsafe { &mut (*session).backend_data }
}

#[inline]
unsafe fn publisher_data_mut(publisher: *mut NrosRmwPublisher) -> &'static mut *mut c_void {
    unsafe { &mut (*publisher).backend_data }
}

#[inline]
unsafe fn subscription_data_mut(subscriber: *mut NrosRmwSubscription) -> &'static mut *mut c_void {
    unsafe { &mut (*subscriber).backend_data }
}

#[inline]
unsafe fn service_data_mut(server: *mut NrosRmwService) -> &'static mut *mut c_void {
    unsafe { &mut (*server).backend_data }
}

#[inline]
unsafe fn client_data_mut(client: *mut NrosRmwClient) -> &'static mut *mut c_void {
    unsafe { &mut (*client).backend_data }
}

#[inline]
unsafe fn session_mut<'a, T>(session: *mut NrosRmwSession) -> Option<&'a mut T> {
    if session.is_null() {
        return None;
    }
    let p = unsafe { (*session).backend_data } as *mut T;
    if p.is_null() {
        None
    } else {
        Some(unsafe { &mut *p })
    }
}

#[inline]
unsafe fn session_ref<'a, T>(session: *const NrosRmwSession) -> Option<&'a T> {
    if session.is_null() {
        return None;
    }
    let p = unsafe { (*session).backend_data } as *const T;
    if p.is_null() {
        None
    } else {
        Some(unsafe { &*p })
    }
}

#[inline]
unsafe fn publisher_ref<'a, T>(publisher: *const NrosRmwPublisher) -> Option<&'a T> {
    if publisher.is_null() {
        return None;
    }
    let p = unsafe { (*publisher).backend_data } as *const T;
    if p.is_null() {
        None
    } else {
        Some(unsafe { &*p })
    }
}

#[inline]
unsafe fn subscription_mut<'a, T>(subscriber: *const NrosRmwSubscription) -> Option<&'a mut T> {
    if subscriber.is_null() {
        return None;
    }
    let p = unsafe { (*subscriber).backend_data } as *mut T;
    if p.is_null() {
        None
    } else {
        Some(unsafe { &mut *p })
    }
}

#[inline]
unsafe fn subscription_ref<'a, T>(subscriber: *const NrosRmwSubscription) -> Option<&'a T> {
    if subscriber.is_null() {
        return None;
    }
    let p = unsafe { (*subscriber).backend_data } as *const T;
    if p.is_null() {
        None
    } else {
        Some(unsafe { &*p })
    }
}

#[inline]
unsafe fn service_mut<'a, T>(server: *const NrosRmwService) -> Option<&'a mut T> {
    if server.is_null() {
        return None;
    }
    let p = unsafe { (*server).backend_data } as *mut T;
    if p.is_null() {
        None
    } else {
        Some(unsafe { &mut *p })
    }
}

#[inline]
unsafe fn service_ref<'a, T>(server: *const NrosRmwService) -> Option<&'a T> {
    if server.is_null() {
        return None;
    }
    let p = unsafe { (*server).backend_data } as *const T;
    if p.is_null() {
        None
    } else {
        Some(unsafe { &*p })
    }
}

#[inline]
unsafe fn client_mut<'a, T>(client: *const NrosRmwClient) -> Option<&'a mut T> {
    if client.is_null() {
        return None;
    }
    let p = unsafe { (*client).backend_data } as *mut T;
    if p.is_null() {
        None
    } else {
        Some(unsafe { &mut *p })
    }
}

/// Issue 1551 (defect 2) — box a handle the backend just created, FALLIBLY.
///
/// This used to be `Box::into_raw(Box::new(handle))` at five sites. `Box::new`
/// cannot fail: on an exhausted heap it calls `handle_alloc_error`, and in a
/// `std` build libstd's OOM hook writes to fd 2 — which on Zephyr
/// `native_sim` is issue 0589's `zvfs_write` recursion, so the image died
/// with SIGSEGV (exit 139, ~104,735 frames deep) and the hook's own message
/// never appeared. Every C caller of these trampolines already handles
/// `NROS_RMW_RET_BAD_ALLOC`; the allocation simply never gave it the chance.
///
/// On `Err` the handle comes BACK to the caller, which disposes of it (for an
/// entity, dropping it undeclares what the backend declared; a session is
/// closed first, as `destroy_session_trampoline` does). The diagnostic goes
/// through `nros_log` (issue 0589: never std stdio), whose formatting is a
/// fixed stack buffer, so reporting an exhausted heap does not itself need
/// the heap.
fn box_handle<T>(kind: &str, value: T) -> Result<*mut c_void, T> {
    match nros_rmw::fallible::try_box(value) {
        Ok(boxed) => Ok(Box::into_raw(boxed) as *mut c_void),
        Err(value) => {
            nros_log::log_error!(
                nros_log::get_logger("nros_rmw_cffi"),
                "heap exhausted: could not allocate {} bytes for a {} handle; \
                 the {} is NOT created (NROS_RMW_RET_BAD_ALLOC). Raise the \
                 platform heap (Zephyr: CONFIG_NROS_ZEPHYR_HEAP_SIZE)",
                core::mem::size_of::<T>(),
                kind,
                kind
            );
            Err(value)
        }
    }
}

#[inline]
unsafe fn take_box<T>(slot: &mut *mut c_void) -> Option<Box<T>> {
    if slot.is_null() {
        return None;
    }
    let ptr = *slot as *mut T;
    *slot = core::ptr::null_mut();
    if ptr.is_null() {
        None
    } else {
        // SAFETY: this pointer was minted by `Box::into_raw` in the
        // corresponding create-trampoline; we are taking ownership
        // back and the slot has been cleared so no second take is
        // possible.
        Some(unsafe { Box::from_raw(ptr) })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// issue 0829 — the inbound edge RAISES a 0 policy back to the sentinel, so
    /// a C caller's "unstated" survives to the Rust backend that has to resolve
    /// it. Before this, `qos_from_cffi` folded 0 to RELIABLE / VOLATILE /
    /// KEEP_LAST here at the edge, which made every Rust backend answer the
    /// sentinel identically — the thing upstream deliberately does not do.
    ///
    /// This is the round trip: profile -> C struct -> profile.
    #[test]
    fn a_zero_filled_c_profile_reads_back_as_the_sentinel() {
        let raised = qos_from_cffi(&crate::NROS_RMW_QOS_PROFILE_SYSTEM_DEFAULT);
        assert_eq!(raised, nros_rmw::QoSProfile::QOS_PROFILE_SYSTEM_DEFAULT);
        assert!(raised.has_unresolved_system_default());
    }

    /// UNKNOWN is NOT the sentinel and must keep its old fold: it is a
    /// read-back artefact ("the backend could not determine this"), not a
    /// request, so there is no absence to carry.
    #[test]
    fn unknown_is_not_raised_to_the_sentinel() {
        let mut q = crate::NROS_RMW_QOS_PROFILE_SYSTEM_DEFAULT;
        q.reliability = crate::generated::NROS_RMW_RELIABILITY_UNKNOWN as u8;
        let raised = qos_from_cffi(&q);
        assert_eq!(
            raised.reliability,
            nros_rmw::QoSReliabilityPolicy::Reliable,
            "UNKNOWN must keep folding to the ROS default, not become a sentinel"
        );
    }
}