nros_node/executor/

spin.rs

//! Executor struct and core spin methods.

use core::{marker::PhantomData, mem::MaybeUninit};

use nros_core::{RosMessage, RosService, ViewableMessage};
use nros_rmw::{QoSProfile, ServiceInfo, Session, TopicInfo, TransportError};

use crate::{session, timer::TimerDuration};

#[cfg(feature = "safety-e2e")]
use super::arena::{
    SubSafetyEntry, sub_safety_has_data, sub_safety_pre_sample, sub_safety_try_process,
};
#[cfg(feature = "rmw-cffi")]
use super::types::ExecutorConfig;
// phase-427 — unconditional: `spin_forever` takes `SpinOptions` and is not
// `alloc`-gated (a bare-metal entry is exactly the caller that needs it).
use super::{
    arena::{
        BufferStrategy, CallbackMeta, EntryKind, GuardConditionEntry, ServiceClientCallbackEntry,
        ServiceClientRawArenaEntry, ServiceClientSendHeader, SrvEntry, SrvRawEntry,
        SubBufferedEntry, SubBufferedRawCEntry, SubBufferedRawEntry, SubBufferedRawInfoCEntry,
        SubBufferedRawInfoEntry, SubBufferedTypedCEntry, SubBufferedViewEntry, SubInfoEntry,
        SubInplaceEntry, TimerClockSource, TimerEntry, TimerHeader, TimerOverrunPolicy, TraceName,
        always_ready, buffered_region_size, drop_entry, guard_has_data, guard_try_process,
        no_pre_sample, service_client_callback_try_process, service_client_raw_try_process,
        srv_has_data, srv_raw_has_data, srv_raw_try_process, srv_try_process,
        sub_buffered_has_data, sub_buffered_raw_c_has_data, sub_buffered_raw_c_try_process,
        sub_buffered_raw_has_data, sub_buffered_raw_info_c_has_data,
        sub_buffered_raw_info_c_try_process, sub_buffered_raw_info_has_data,
        sub_buffered_raw_info_try_process, sub_buffered_raw_try_process, sub_buffered_try_process,
        sub_buffered_typed_c_has_data, sub_buffered_typed_c_try_process,
        sub_buffered_view_has_data, sub_buffered_view_try_process, sub_info_has_data,
        sub_info_pre_sample, sub_info_try_process, sub_inplace_has_data, sub_inplace_try_process,
        timer_try_process,
    },
    node::NodeHandle,
    spsc_ring::SpscRing,
    triple_buffer::TripleBuffer,
    types::{
        ExecutorSemantics, GuardCondition, HandleId, InvocationMode, NodeError,
        RawMessageDeserializeFn, RawResponseCallback, RawServiceCallback, RawSubscriptionCallback,
        RawSubscriptionInfoCallback, ReadinessSnapshot, SpinOnceResult, SpinOptions,
        SpinPeriodPollingResult, Trigger, TypedSubscriptionCallback,
    },
};

// ============================================================================
// phase-456 W8 — one subscription registration, stated as one value
// ============================================================================

/// What a subscription registration STATES — phase-456 W8.
///
/// The thirteen `register_subscription_*` / `add_arena_subscription_*` entry
/// points differ in their DELIVERY SHAPE (typed, raw, borrowed, with-info,
/// validated) and used to differ in their LANGUAGE, and each re-derived the
/// same prologue from positional parameters: node identity, topic info, the
/// declared-depth check, the backend call. Twelve copies of it, and exactly
/// ONE of them asked the backend whether it dispatches in place.
///
/// This is that prologue's argument, as one value. A struct rather than nine
/// parameters because the fields are independently optional and a caller must
/// be able to say "I state nothing here" without reordering a call — the same
/// reason `DescriptorInputs` is a struct one layer up.
///
/// Two of its fields are the axes phase-456 W8 found under issue 1319's five
/// rows: [`backend_hint`](Self::backend_hint) is "does this site know the
/// type's bound", and [`in_place_capable`](Self::in_place_capable) is what
/// lets `Executor::open_subscription` ask the third axis once, for every
/// caller, in every language.
pub(crate) struct SubscriptionRequest<'a> {
    /// `None` is the legacy single-node path: identity comes from the
    /// executor's own name and namespace and the session is slot 0.
    pub(crate) node_id: Option<super::node_record::NodeId>,
    pub(crate) topic_name: &'a str,
    pub(crate) type_name: &'a str,
    pub(crate) type_hash: &'a str,
    pub(crate) qos: QoSProfile,
    /// Bytes the CALL SITE says it expects to receive, for the BACKEND's
    /// payload size class (phase-231 / RFC-0038, phase-402 W2).
    ///
    /// `None` — and, for a C caller whose ABI spells it `0`, a zero — means
    /// "this site stated nothing", which is a different claim from "zero
    /// bytes": `with_rx_buffer_hint(0)` would be the second.
    pub(crate) backend_hint: Option<usize>,
    /// Bytes ONE receive slot claims from the arena, already derived by the
    /// caller that has the type.
    ///
    /// Not the same number as [`Self::backend_hint`] — the typed Rust path
    /// hints the type's bound and sizes the slot from
    /// `default_subscription_rx_bytes`, which may differ — so both travel.
    /// Ignored entirely when [`SubscriptionOpen::in_place`] comes back true.
    pub(crate) slot_bytes: usize,
    /// Can THIS delivery shape dispatch out of the backend's own receive slot?
    ///
    /// A property of the shape, not of the backend: `process_raw_in_place`
    /// hands the callback borrowed BYTES and nothing else, so a shape that
    /// must also deliver a wire attachment (`_info`), an integrity status
    /// (`_validated` / `_safety`) or a `MessageInfo` cannot use it however
    /// capable the backend is. Stated per call site so an omission is a line
    /// someone wrote rather than a question nobody asked — which is exactly
    /// what the C path was before W8.
    pub(crate) in_place_capable: bool,
}

/// The result of `Executor::open_subscription`: a claimed slot, a live backend
/// subscriber, and the ONE answer to the in-place question.
pub(crate) struct SubscriptionOpen {
    /// The claimed entry slot. Claimed BEFORE the fallible work, per
    /// `Executor::emplace_entry`'s rule.
    pub(crate) slot: usize,
    pub(crate) handle: session::RmwSubscriber,
    /// **The only place in this crate that
    /// `Subscription::supports_process_in_place` is read.**
    ///
    /// Before phase-456 W8 the read lived inside
    /// `register_subscription_buffered_on`, which is the Rust typed path and
    /// only that: every C and C++ subscription on zenoh or XRCE therefore
    /// allocated a receive region the backend does not need, at the same order
    /// as issue 1340's ~9.7 KiB per subscription. The irony phase-456 W8
    /// measured is that the C callback is the BETTER candidate —
    /// `RawSubscriptionCallback` is already `(const uint8_t*, size_t, void*)`,
    /// a borrowed-bytes signature, where the Rust typed path has to produce an
    /// owned `&M` from somewhere.
    pub(crate) in_place: bool,
    /// [`SubscriptionRequest::slot_bytes`], carried through so a caller's arena
    /// arithmetic reads ONE local rather than re-deriving it.
    pub(crate) slot_bytes: usize,
    /// The QoS the backend was actually given — phase-454 W13 through
    /// phase-456 W8.
    ///
    /// NOT the caller's `req.qos`. `declared_qos::honour` REWRITES the depth
    /// when the system declared one, and the twelve prologues this function
    /// replaced each passed that rewritten value on to the entry they built.
    /// Returning it is what keeps that true with one honouring site: a caller
    /// that stored `req.qos` instead would size its entry from a depth the
    /// backend never saw, and nothing would fail — the subscription would
    /// simply hold a different number of samples than the build reserved for
    /// it.
    pub(crate) qos: QoSProfile,
}

// ============================================================================
// Phase 8 — callback registration event (paired stubs)
// ============================================================================
//
// `docs/design/callback_tracing.rst`. Paired stubs (the `entry_tiers.rs`
// idiom) so `emplace_entry` reads identically whether or not the feature is
// on, and the `#[cfg]` lives in exactly one place.

/// Emit `nros_callback_register(handle, kind, name)` for a newly installed
/// executor entry.
#[cfg(feature = "trace-callbacks")]
#[inline]
fn trace_register(slot: usize, kind: EntryKind, name: TraceName<'_>) {
    super::callback_trace::register(slot, kind, name);
}

#[cfg(not(feature = "trace-callbacks"))]
#[inline]
fn trace_register(_slot: usize, _kind: EntryKind, _name: TraceName<'_>) {}

// ============================================================================
// Executor::open() factory method
// ============================================================================

/// phase-271 / phase-392 W6 — the `'static` `u64` backing the `alloc`
/// convenience constructors borrow, sized to `sizing`.
///
/// **The named static first, the heap second.** phase-271 made this a
/// `Box::leak`, and a leak has no symbol: `mem-report` reads an ELF's symbol
/// table, so the largest single RAM consumer of every Rust image was the one
/// thing the memory instrument could not see (RFC-0002 § 4.4b). It is served
/// from `executor::backing::EXECUTOR_BACKING` now — same bytes, same
/// executor-lifetime reservation, in `.bss` where the linker can print them and
/// out of the allocator arena that used to pay for them.
///
/// The heap arm is still reached, and both cases are legitimate rather than
/// degraded: a SECOND executor opened through an `alloc` convenience
/// constructor, and an entry sized past the build-time default. A tiered boot's
/// spawned tiers are NOT that second executor any more: they open over the
/// entry's `TierExecutorBacking` slots (`open_with_session_slot`, issue 1571). Neither is an error, so neither
/// warns — `report_arena_headroom` is where an over-provisioned executor gets
/// told about itself, and a duplicate line here would just be noise.
///
/// `alloc`-only — no_std-no-alloc entries supply their own `static`/stack
/// backing via `open_in` / `from_session_in`.
#[cfg(feature = "alloc")]
fn default_backing(sizing: super::storage::ExecutorSizing) -> &'static mut [MaybeUninit<u64>] {
    let words = sizing.u64_len();
    match super::backing::take(words) {
        Some(backing) => backing,
        None => alloc::boxed::Box::leak(alloc::boxed::Box::new_uninit_slice(words)),
    }
}

#[cfg(feature = "rmw-cffi")]
impl<'s> Executor<'s> {
    /// phase-271 — open a new executor session over caller-supplied `backing`,
    /// sized by `sizing` (per-entry sizing). The core, non-generic sized entry
    /// point: the `alloc` [`open`](Self::open) convenience leaks a default
    /// backing and delegates here, and the `nros::main!` macro emits a backing
    /// sized to the entry's own entity count.
    ///
    /// Phase 115.M.4 — auto-registers the cffi vtable for whichever
    /// backend the build was configured for, mirroring the C++ side's
    /// `#ifdef NROS_RMW_<NAME>` fan-out in `<rclcpp/node.hpp>`. The
    /// runtime's atomic vtable slot is idempotent: a re-call of any
    /// backend's `register()` is a no-op, so the fan-out below is safe
    /// to invoke on every `Executor::open` (cheaper than a `Once` and
    /// doesn't pull in `std::sync` for no_std targets).
    ///
    /// Connects to the middleware at the locator specified in `config`.
    ///
    /// # Safety
    /// `backing` must be ≥ `sizing.u64_len()` words, live for `'s`, and be
    /// otherwise untouched while the executor lives (see
    /// [`from_session_in`](Self::from_session_in)).
    pub unsafe fn open_in(
        config: &ExecutorConfig<'_>,
        backing: &'s mut [MaybeUninit<u64>],
        sizing: super::storage::ExecutorSizing,
    ) -> Result<Self, NodeError> {
        use nros_rmw::Rmw;

        // Phase 128.A.3 / 249 P4b.1 — manifest-driven backend selection.
        //
        // Every linked backend self-registered via its `.init_array`
        // ctor before `main` (RFC-0042 §D3.3), so the registry is
        // already populated — no runtime section walk.
        //
        // 1. Honour `config.rmw` — the caller's explicit backend selection,
        //    mirroring ROS 2's `RMW_IMPLEMENTATION`. On a hosted build
        //    `nros::ExecutorConfigEnvExt::from_env` / `nros::env::resolve_hosted`
        //    fill it from `$NROS_RMW`; issue 0687 moved that read to the edge,
        //    because reading a process environment is what kept `std` in this
        //    crate and an RTOS image has no environment to read.
        // 2. With no selector, pick the unique registered backend.
        //    Zero registered → `NoBackend`; more than one →
        //    `Ambiguous` (user must select one, or use
        //    `Executor::open_multi`).
        let selector = config.rmw;
        match nros_rmw_cffi::resolve_backend(selector.map(str::as_bytes)) {
            nros_rmw_cffi::BackendResolution::Single(_) => {}
            // Issue 0436 — these are SELECTION outcomes, not transport failures,
            // and calling them `ConnectionFailed` actively misleads: a PX4 bridge
            // that registered two backends reported "connection failed", which
            // reads as a router/network problem and was chased as one. Nothing is
            // connected at this point — the resolver has not chosen a backend yet.
            //
            // The variant still collapses into `NodeError::Transport` (the enum has
            // no selection arm, and adding one is an ABI change across the C/C++
            // seams), but `InvalidConfig` at least says "your configuration is
            // unresolvable", and the std-gated line below names WHICH outcome.
            other => {
                {
                    let why: &str = match other {
                        nros_rmw_cffi::BackendResolution::NoBackend => {
                            "no RMW backend is registered"
                        }
                        nros_rmw_cffi::BackendResolution::Ambiguous => {
                            "more than one RMW backend is registered and no \
                             $NROS_RMW selector was set — name one (e.g. \
                             NROS_RMW=uorb), or open per-backend sessions"
                        }
                        nros_rmw_cffi::BackendResolution::Unknown => {
                            "$NROS_RMW names a backend that is not registered"
                        }
                        nros_rmw_cffi::BackendResolution::Single(_) => unreachable!(),
                    };
                    nros_log::log_error!(
                        nros_log::get_logger("nros"),
                        "cannot select an RMW backend — {why}"
                    );
                }
                let _ = other;
                return Err(NodeError::Transport(TransportError::InvalidConfig));
            }
        }

        let rmw_config = nros_rmw::RmwConfig {
            locator: config.locator,
            mode: config.mode,
            domain_id: config.domain_id,
            node_name: config.node_name,
            namespace: config.namespace,
            properties: &[],
        };
        let session = if let Some(name) = selector {
            // Selector path: route to the specific named backend so
            // the env-var-disambiguated outcome matches what the
            // resolver above identified.
            nros_rmw_cffi::CffiRmw::open_with_rmw(name, &rmw_config)
        } else {
            nros_rmw_cffi::CffiRmw.open(&rmw_config)
        }
        .map_err(|e| {
            // Issue 0465 — do not relabel. This used to discard the backend's
            // error and report `ConnectionFailed` for every open failure, so an
            // exhausted session pool (`InvalidConfig`) and a router that is not
            // there produced the same sentence. Same lesson as the selection
            // arm above: say which failure happened.
            nros_log::log_error!(
                nros_log::get_logger("nros"),
                "RMW session open failed — {e:?}"
            );
            NodeError::Transport(e)
        })?;
        // SAFETY: forwarded from this fn's contract — `backing`/`sizing` sized
        // + alive for `'s`.
        let mut executor = unsafe { Self::from_session_in(session, backing, sizing) };
        {
            // `config.clock_us` overrides the constructor's platform default
            // (issue: assigning `None` here clobbered it and re-enabled the
            // credit-the-requested-timeout fallback).
            if let Some(clock) = config.clock_us {
                executor.clock_us_fn = Some(clock);
                executor.last_spin_end_us = Some(clock());
            }
            // issue 0671 — the SAME rule as `clock_us` directly above, which is
            // why that one is guarded: a config that does not SPECIFY an epoch
            // must not be read as "this target HAS no epoch". Assigning `None`
            // here clobbered the constructor's platform default
            // (`Some(default_epoch_us)`), and `ExecutorConfig::new` — the path
            // `nros::init_*` + `ctx.config()` takes — leaves `epoch_us: None`,
            // so EVERY hosted node built that way silently lost its wall clock.
            // With no epoch, `Node::subscription` never attaches the age cell
            // (it needs `(STAMP_OFFSET, epoch)` both `Some`), so a baked
            // `max_age_ms` contract becomes a silently-dead monitor — the exact
            // outcome RFC-0052 says must never happen. The rate monitor rides
            // the GUARDED `clock_us_fn` and kept working, which is why only the
            // age half went quiet.
            if let Some(epoch) = config.epoch_us {
                executor.epoch_us_fn = Some(epoch);
            }
        }
        executor.set_node_identity(config.node_name, config.namespace);
        // Issue 0656 — beside the identity, for the same reason: an entity needs
        // both to be addressable, and this half used to be dropped here.
        executor.domain_id = config.domain_id;
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        executor.install_wake_signal_on_primary();
        // Phase 277 W2.c — readiness marker for E2E harnesses. This is the
        // single call-through `open()`/`open_sized()` share, so it fires on
        // every platform that reaches here (native, freertos, zephyr,
        // threadx, …) regardless of which RMW backend or board owns the
        // boot path. It replaces the per-example synthetic
        // `log::info!("Publishing messages")` markers W4 removes — those
        // only proved a callback had fired at least once; this line proves
        // the session itself is up, before any node/callback exists.
        //
        // STABILITY CONTRACT: the leading `"nros: session open"` text is
        // load-bearing — test harnesses grep for it verbatim. Keep it
        // stable even if the trailing `(rmw=...)` detail changes.
        #[cfg(feature = "log")]
        {
            if let Some(name) = selector {
                log::info!("nros: session open (rmw={name})");
            } else {
                log::info!("nros: session open");
            }
        }
        Ok(executor)
    }
}

#[cfg(all(feature = "rmw-cffi", feature = "alloc"))]
impl Executor<'static> {
    /// Open a new executor session using the active RMW backend, at the
    /// build-time default sizing. Convenience over
    /// [`open_in`](Self::open_in): leaks a default-sized backing (executor-
    /// lifetime) so existing callers keep the zero-storage-arg signature.
    /// Per-entry sizing goes through `open_in` / the `nros::main!` macro.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let config = ExecutorConfig::from_env().node_name("my_node");
    /// let mut executor = Executor::open(&config)?;
    /// ```
    pub fn open(config: &ExecutorConfig<'_>) -> Result<Self, NodeError> {
        Self::open_sized(config, super::storage::ExecutorSizing::DEFAULT)
    }

    /// phase-271 — like [`open`](Self::open) but sized to a caller-supplied
    /// `sizing` (its own declared topology) instead of the build-time default.
    /// The `alloc` entry point the `nros::main!` macro's native board path uses
    /// to size a fat entry (>default `MAX_CBS` callbacks) without a
    /// workspace-global `NROS_EXECUTOR_MAX_CBS`. Leaks a `sizing`-sized backing
    /// (executor-lifetime); no-alloc entries use `open_in` with their own static.
    pub fn open_sized(
        config: &ExecutorConfig<'_>,
        sizing: super::storage::ExecutorSizing,
    ) -> Result<Self, NodeError> {
        // SAFETY: the backing is exactly `sizing.u64_len()` words, `'static`,
        // uniquely owned by the returned executor.
        unsafe { Self::open_in(config, default_backing(sizing), sizing) }
    }

    /// Phase 128.F.1 — explicit per-backend session declaration for
    /// bridge mode. `specs[0]` becomes the primary session; `specs[1..]`
    /// open as extras keyed by RMW name. After construction, every
    /// `create_node_on(name, rmw)` call dispatches to whichever
    /// session was opened under that RMW name (or, when the rmw name
    /// matches the primary, the primary session itself).
    ///
    /// Single-backend callers should keep using
    /// [`open`](Self::open) — this entry costs an extra
    /// `open_with_rmw` per spec and adds no value when only one
    /// backend is linked.
    ///
    /// `$NROS_RMW` env is ignored: bridge mode wants explicit names.
    ///
    /// Default-sized `alloc` convenience over
    /// [`open_multi_in`](Self::open_multi_in) (leaks a default backing).
    #[cfg(feature = "rmw-cffi")]
    pub fn open_multi(specs: &[SessionSpec<'_>]) -> Result<Self, NodeError> {
        let sizing = super::storage::ExecutorSizing::DEFAULT;
        // SAFETY: the backing is exactly `sizing.u64_len()` words, `'static`.
        unsafe { Self::open_multi_in(specs, default_backing(sizing), sizing) }
    }

    /// Phase 104.C.1 — open the Executor against a specific RMW
    /// backend by name. Selects from the named registry (Phase
    /// 104.B.2). `rmw_name` must match one of the names a backend
    /// registered under (`"zenoh"`, `"cyclonedds"`, `"xrce"`, …).
    ///
    /// Equivalent to [`Executor::open`] when the registry has exactly
    /// one backend (the default-backend fast path). Use this entry
    /// point in multi-backend builds where `Executor::open` would
    /// pick the first-registered slot.
    ///
    /// Single-Executor multi-Node multi-RMW (the long-term Design X
    /// from `docs/roadmap/phase-104-multi-backend-bridges.md`) is
    /// follow-up work — Phase 104.C.2 + C.3.
    ///
    /// Default-sized `alloc` convenience over
    /// [`open_with_rmw_in`](Self::open_with_rmw_in) (leaks a default backing).
    #[cfg(feature = "rmw-cffi")]
    pub fn open_with_rmw(rmw_name: &str, config: &ExecutorConfig<'_>) -> Result<Self, NodeError> {
        let sizing = super::storage::ExecutorSizing::DEFAULT;
        // SAFETY: the backing is exactly `sizing.u64_len()` words, `'static`.
        unsafe { Self::open_with_rmw_in(rmw_name, config, default_backing(sizing), sizing) }
    }
}

// phase-271 — no-alloc sized cores for the bridge/named open paths. In
// `impl<'s>` (not the `'static` alloc block) so they stay available in
// `rmw-cffi`-without-`alloc` builds (e.g. the `nros-bridge` no_std default),
// which is where `open_multi`/`open_with_rmw` lived before.
#[cfg(feature = "rmw-cffi")]
impl<'s> Executor<'s> {
    /// Per-entry-sized [`open_multi`](Self::open_multi): carves `backing` for
    /// the executor's tables instead of leaking a default one.
    ///
    /// # Safety
    /// `backing`/`sizing` as in [`from_session_in`](Self::from_session_in).
    pub unsafe fn open_multi_in(
        specs: &[SessionSpec<'_>],
        backing: &'s mut [MaybeUninit<u64>],
        sizing: super::storage::ExecutorSizing,
    ) -> Result<Self, NodeError> {
        // Phase 249 P4b.1 — backends self-registered via their
        // `.init_array` ctor before `main`; no runtime section walk.
        let primary = specs
            .first()
            .ok_or(NodeError::Transport(TransportError::ConnectionFailed))?;
        let primary_session =
            nros_rmw_cffi::CffiRmw::open_with_rmw(primary.rmw, &primary.to_rmw_config())
                .map_err(NodeError::Transport)?;
        // SAFETY: forwarded from this fn's contract.
        let mut executor = unsafe { Self::from_session_in(primary_session, backing, sizing) };
        executor.set_node_identity("", "/");
        // Phase 156 — see `Executor::open` for primary-identity
        // recording rationale.
        let _ = executor.primary_rmw_name.push_str(primary.rmw);
        let _ = executor.primary_locator.push_str(primary.locator);
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        executor.install_wake_signal_on_primary();

        for spec in specs.iter().skip(1) {
            let session = nros_rmw_cffi::CffiRmw::open_with_rmw(spec.rmw, &spec.to_rmw_config())
                .map_err(NodeError::Transport)?;
            executor
                .extra_sessions
                .push(session)
                .map_err(|_| NodeError::NodeTableFull)?;
            // Issue 0436 — record WHICH backend/locator this extra is, so
            // `NodeBuilder::rmw(name)` can find it instead of opening a second
            // session against the same (singleton) backend.
            {
                let mut rmw_s = heapless::String::<32>::new();
                let _ = rmw_s.push_str(spec.rmw);
                let mut loc_s = heapless::String::<128>::new();
                let _ = loc_s.push_str(spec.locator);
                let _ = executor.extra_session_ids.push((rmw_s, loc_s));
            }
            #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
            {
                let idx = executor.extra_sessions.len() - 1;
                executor.install_wake_signal_on_extra(idx);
            }
        }

        Ok(executor)
    }

    /// Per-entry-sized [`open_with_rmw`](Self::open_with_rmw): carves `backing`
    /// for the executor's tables instead of leaking a default one.
    ///
    /// # Safety
    /// `backing`/`sizing` as in [`from_session_in`](Self::from_session_in).
    pub unsafe fn open_with_rmw_in(
        rmw_name: &str,
        config: &ExecutorConfig<'_>,
        backing: &'s mut [MaybeUninit<u64>],
        sizing: super::storage::ExecutorSizing,
    ) -> Result<Self, NodeError> {
        if !nros_rmw_cffi::backend_registered() {
            return Err(NodeError::Transport(TransportError::ConnectionFailed));
        }

        let rmw_config = nros_rmw::RmwConfig {
            locator: config.locator,
            mode: config.mode,
            domain_id: config.domain_id,
            node_name: config.node_name,
            namespace: config.namespace,
            properties: &[],
        };
        let session = nros_rmw_cffi::CffiRmw::open_with_rmw(rmw_name, &rmw_config)
            .map_err(|_| NodeError::Transport(TransportError::ConnectionFailed))?;
        // SAFETY: forwarded from this fn's contract.
        let mut executor = unsafe { Self::from_session_in(session, backing, sizing) };
        {
            // `config.clock_us` overrides the constructor's platform default
            // (issue: assigning `None` here clobbered it and re-enabled the
            // credit-the-requested-timeout fallback).
            if let Some(clock) = config.clock_us {
                executor.clock_us_fn = Some(clock);
                executor.last_spin_end_us = Some(clock());
            }
            // issue 0671 — the SAME rule as `clock_us` directly above, which is
            // why that one is guarded: a config that does not SPECIFY an epoch
            // must not be read as "this target HAS no epoch". Assigning `None`
            // here clobbered the constructor's platform default
            // (`Some(default_epoch_us)`), and `ExecutorConfig::new` — the path
            // `nros::init_*` + `ctx.config()` takes — leaves `epoch_us: None`,
            // so EVERY hosted node built that way silently lost its wall clock.
            // With no epoch, `Node::subscription` never attaches the age cell
            // (it needs `(STAMP_OFFSET, epoch)` both `Some`), so a baked
            // `max_age_ms` contract becomes a silently-dead monitor — the exact
            // outcome RFC-0052 says must never happen. The rate monitor rides
            // the GUARDED `clock_us_fn` and kept working, which is why only the
            // age half went quiet.
            if let Some(epoch) = config.epoch_us {
                executor.epoch_us_fn = Some(epoch);
            }
        }
        executor.set_node_identity(config.node_name, config.namespace);
        // Phase 156 — record primary identity for the session-
        // cache hit path. See `Executor::open` for the rationale.
        let _ = executor.primary_rmw_name.push_str(rmw_name);
        let _ = executor.primary_locator.push_str(config.locator);
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        executor.install_wake_signal_on_primary();
        Ok(executor)
    }
}

/// Phase 128.F.1 — per-backend session declaration for
/// [`Executor::open_multi`]. Each spec names an RMW backend (must
/// match one a backend registered under via
/// `nros_rmw_cffi_register_named` / the `RMW_INIT_ENTRIES` linker
/// section) and the locator + domain id to open against it.
#[cfg(feature = "rmw-cffi")]
#[derive(Clone, Copy)]
pub struct SessionSpec<'cfg> {
    pub rmw: &'cfg str,
    pub locator: &'cfg str,
    pub domain_id: u32,
    pub node_name: &'cfg str,
    pub namespace: &'cfg str,
}

#[cfg(feature = "rmw-cffi")]
impl<'cfg> SessionSpec<'cfg> {
    /// Minimal spec — just RMW name + locator. Domain id defaults to
    /// 0; node name and namespace are empty.
    pub const fn new(rmw: &'cfg str, locator: &'cfg str) -> Self {
        Self {
            rmw,
            locator,
            domain_id: 0,
            node_name: "",
            namespace: "",
        }
    }

    pub const fn domain_id(mut self, domain_id: u32) -> Self {
        self.domain_id = domain_id;
        self
    }

    pub const fn node_name(mut self, name: &'cfg str) -> Self {
        self.node_name = name;
        self
    }

    pub const fn namespace(mut self, ns: &'cfg str) -> Self {
        self.namespace = ns;
        self
    }

    fn to_rmw_config(self) -> nros_rmw::RmwConfig<'cfg> {
        nros_rmw::RmwConfig {
            locator: self.locator,
            mode: nros_rmw::SessionMode::Client,
            domain_id: self.domain_id,
            node_name: self.node_name,
            namespace: self.namespace,
            properties: &[],
        }
    }
}

// Phase 128.A.3 — selector for the single-backend resolution path.
//
// On hosted (`std`) builds, read `$NROS_RMW`; mirrors ROS 2's
// `RMW_IMPLEMENTATION`. Returns the name as a byte vector so the
// caller can pass it to `nros_rmw_cffi::resolve_backend` and (when
// `Some`) to `CffiRmw::open_with_rmw`.
//
// On `no_std` / bare-metal builds, environment variables are not
// available; resolution always falls through to the single-backend
// or ambiguous path. Embedded users with multiple backends use the
// bridge surface `Executor::open_multi` instead.
// phase-359 W10 / issue 0687 — the private reader that stood here is gone, and
// so is the shared one that briefly replaced it. `ExecutorConfig::rmw` carries
// the selection instead: `nros::rmw_selector` reads the variable ONCE, at the
// hosted edge, and every consumer takes the value.

// ============================================================================
// SessionStore — owned or borrowed session
// ============================================================================

/// Session storage: owned or borrowed via raw pointer.
///
/// The C API creates a session in `rclc_support_init()` before the
/// executor. `Borrowed` lets the executor use that session without owning it.
#[allow(clippy::large_enum_variant)]
pub(crate) enum SessionStore {
    Owned(session::ConcreteSession),
    Borrowed(*mut session::ConcreteSession),
}

impl core::ops::Deref for SessionStore {
    type Target = session::ConcreteSession;
    fn deref(&self) -> &session::ConcreteSession {
        match self {
            SessionStore::Owned(s) => s,
            SessionStore::Borrowed(ptr) => unsafe { &**ptr },
        }
    }
}

impl core::ops::DerefMut for SessionStore {
    fn deref_mut(&mut self) -> &mut session::ConcreteSession {
        match self {
            SessionStore::Owned(s) => s,
            SessionStore::Borrowed(ptr) => unsafe { &mut **ptr },
        }
    }
}

/// Phase 228.E — an opaque, `Send` handle to an [`Executor`]'s RMW session.
///
/// In the per-tier model the boot executor opens the one session and hands each
/// spawned tier task a handle (not a borrow) so the task opens its own
/// [`Executor`] over that *same* session across the RTOS task boundary. Wrapping
/// the `pub(crate)` session pointer lets board crates (`nros-board-linux`,
/// `nros-board-freertos`, …) name + move the handle without naming the session
/// type. Obtain via [`Executor::session_handle`]; consume via
/// [`Executor::open_with_session_handle`].
#[cfg(any(has_rmw, test))]
pub struct SessionHandle(*mut session::ConcreteSession);

// SAFETY: the per-tier model deliberately shares one session across RTOS tasks;
// concurrent access is serialized by the RMW backend's internal locks (the RTOS
// targets build zenoh-pico `Z_FEATURE_MULTI_THREAD=1` — RFC-0032 §5.0). The
// boot executor owns the session and outlives every tier task.
#[cfg(any(has_rmw, test))]
unsafe impl Send for SessionHandle {}

#[cfg(any(has_rmw, test))]
impl SessionHandle {
    /// Phase 274.W1 — convert to an opaque `*mut c_void` for C/C++ FFI.
    ///
    /// The returned pointer encodes the session address and is valid as long as
    /// the owning executor lives. Reconstruct via [`Self::from_raw`].
    pub fn into_raw(self) -> *mut core::ffi::c_void {
        self.0 as *mut core::ffi::c_void
    }

    /// Phase 274.W1 — reconstruct a `SessionHandle` from an opaque pointer
    /// returned by [`Self::into_raw`].
    ///
    /// # Safety
    /// `ptr` must be a pointer obtained from `into_raw()` on a `SessionHandle`
    /// whose underlying session is still live and owned by its original executor.
    pub unsafe fn from_raw(ptr: *mut core::ffi::c_void) -> Self {
        Self(ptr as *mut session::ConcreteSession)
    }
}

/// Phase 228.C — pure callback-group filter decision. `None` = wildcard (accept
/// every group); `Some` = accept only listed groups. Backs
/// [`Executor::group_active`]; split out so the logic is unit-testable without a
/// live session.
pub(crate) fn group_filter_accepts(
    active: Option<&[super::storage::ActiveGroup]>,
    node: u64,
    group: &str,
) -> bool {
    match active {
        None => true,
        Some(v) => v.iter().any(|(n, g)| *n == node && g.as_str() == group),
    }
}

/// Bytes the parameter store asks the platform heap for, in ONE allocation.
///
/// Issue 1706 -- the size of THIS build's store, which folds every knob that
/// shapes it (`MAX_PARAMETERS`, which a contract's `params:` derives, and the
/// board's string/array capacities). No formula and no measured constant: the
/// compiler's own answer, so the number reported below cannot drift from the
/// allocation it describes.
#[cfg(all(feature = "param-store", feature = "alloc"))]
pub const PARAMETER_STORE_BYTES: usize = core::mem::size_of::<nros_params::ParameterStorage>();

/// Issue 1706 -- a TEST seam standing in for a platform heap that returns NULL
/// for the store's request, on the current thread only (tests run in
/// parallel). Not a test `#[global_allocator]`: `check-feature-contract`
/// clause (e) allows exactly one, `nros-platform`'s.
#[cfg(all(test, feature = "std", feature = "param-store"))]
pub(crate) struct RefuseParameterStore;

#[cfg(all(test, feature = "std", feature = "param-store"))]
std::thread_local! {
    static REFUSE_PARAMETER_STORE: core::cell::Cell<bool> = const { core::cell::Cell::new(false) };
}

#[cfg(all(test, feature = "std", feature = "param-store"))]
impl RefuseParameterStore {
    // Only `executor::tests` arms it, and that module is mock-session only.
    #[cfg(not(feature = "rmw-cffi"))]
    pub(crate) fn arm() -> Self {
        REFUSE_PARAMETER_STORE.with(|c| c.set(true));
        Self
    }

    fn armed() -> bool {
        REFUSE_PARAMETER_STORE.with(core::cell::Cell::get)
    }
}

#[cfg(all(test, feature = "std", feature = "param-store"))]
impl Drop for RefuseParameterStore {
    fn drop(&mut self) {
        REFUSE_PARAMETER_STORE.with(|c| c.set(false));
    }
}

/// Issue 1706 -- say, once, that the parameter store did not fit.
///
/// The RFC-0100 D11 shape, one layer up from Cyclone's boot check: the
/// failure is named where it is decided, with the number a reader needs to
/// size the heap, instead of surfacing as an anonymous halt in the allocator.
/// What it can name is the REQUEST; the heap's own report (Zephyr's `HEAP
/// EXHAUSTED` line, the board's `nros: heap peak` line) carries the capacity.
#[cfg(feature = "param-store")]
#[cold]
fn report_parameter_store_refused() {
    // Issue 1812 -- with no heap there was no allocation to refuse: the
    // backing carved no store, and that is the whole story.
    #[cfg(not(feature = "alloc"))]
    {
        let logger = nros_log::get_logger("nros");
        nros_log::log_error!(
            logger,
            "parameter store refused: this executor's backing carves none and the build has no heap"
        );
        nros_log::log_error!(
            logger,
            "every parameter declaration on this executor is refused (issue 1812)"
        );
        nros_log::log_error!(
            logger,
            "open it with ExecutorSizing::params > 0 (NROS_PARAM_STORE=1, NROS_MAX_PARAMETERS)"
        );
    }
    #[cfg(feature = "alloc")]
    report_parameter_heap_store_refused();
}

/// The `alloc` half of [`report_parameter_store_refused`]: the heap refused
/// the store's one allocation (issue 1706).
#[cfg(all(feature = "param-store", feature = "alloc"))]
#[cold]
fn report_parameter_heap_store_refused() {
    let slots = nros_params::MAX_PARAMETERS;
    // THREE short lines, not one sentence: a log backend truncates a long
    // line (Zephyr's cut the first draft at its slot count), and the number
    // is the one part that must survive.
    let logger = nros_log::get_logger("nros");
    nros_log::log_error!(
        logger,
        "parameter store refused: needs {} bytes in one allocation ({} slots x {})",
        PARAMETER_STORE_BYTES,
        slots,
        PARAMETER_STORE_BYTES / if slots == 0 { 1 } else { slots }
    );
    nros_log::log_error!(
        logger,
        "every parameter declaration on this executor is refused (issue 1706)"
    );
    // phase-382 W3' -- the remedy that takes the store OUT of the heap comes
    // first: a build that knows the image builds a store carves it from the
    // executor backing instead (`nros_params::IMPLIED_STORE_SLOTS`).
    nros_log::log_error!(
        logger,
        "declare the parameters in the contract (params:) or state NROS_PARAM_STORE=1"
    );
    nros_log::log_error!(
        logger,
        "and the store is carved from the executor backing; or raise the image heap"
    );
}

/// `text` typed as `declared`'s type — phase-482 W5. `None` when it does not
/// parse as that type, or the type takes no override yet (arrays).
///
/// A `NotSet` declaration has no type to follow, so the text decides: `true` /
/// `false`, then an integer, then a double, then a string — the order rcl's
/// YAML reading gives an unquoted scalar.
#[cfg(all(feature = "param-store", feature = "alloc"))]
fn typed_param_override(
    text: &str,
    declared: &nros_params::ParameterValue,
) -> Option<nros_params::ParameterValue> {
    use nros_params::ParameterValue as V;
    let boolean = |t: &str| match t {
        "true" | "True" | "TRUE" => Some(true),
        "false" | "False" | "FALSE" => Some(false),
        _ => None,
    };
    let string = |t: &str| heapless::String::try_from(t).ok().map(V::String);
    match declared {
        V::Bool(_) => boolean(text).map(V::Bool),
        V::Integer(_) => text.parse::<i64>().ok().map(V::Integer),
        V::Double(_) => text.parse::<f64>().ok().map(V::Double),
        V::String(_) => string(text),
        V::NotSet => boolean(text)
            .map(V::Bool)
            .or_else(|| text.parse::<i64>().ok().map(V::Integer))
            .or_else(|| text.parse::<f64>().ok().map(V::Double))
            .or_else(|| string(text)),
        _ => None,
    }
}

#[cfg(test)]
mod group_filter_tests {
    use super::group_filter_accepts;
    use crate::executor::storage::{ActiveGroup, node_identity_hash};

    type Group = heapless::String<32>;

    fn entry(node: &str, ns: &str, g: &str) -> ActiveGroup {
        let mut s = Group::new();
        s.push_str(g).unwrap();
        (node_identity_hash(node, ns), s)
    }

    #[test]
    fn wildcard_accepts_all() {
        assert!(group_filter_accepts(
            None,
            node_identity_hash("n", "/"),
            "anything"
        ));
    }

    #[test]
    fn set_accepts_only_listed_groups() {
        let active = [entry("n", "/", "ctrl")];
        let n = node_identity_hash("n", "/");
        assert!(group_filter_accepts(Some(&active[..]), n, "ctrl"));
        assert!(!group_filter_accepts(Some(&active[..]), n, "telem"));
    }

    /// issue 1172 — the SAME group id on a DIFFERENT node is not this tier's.
    ///
    /// This is the case the whole change exists for: two nodes may legitimately
    /// declare `ctrl`, pinned to different tiers, and the old filter — keyed on
    /// the group name alone — admitted both onto whichever tier asked first.
    #[test]
    fn the_same_group_on_another_node_is_not_accepted() {
        let active = [entry("talker", "/", "ctrl")];
        assert!(group_filter_accepts(
            Some(&active[..]),
            node_identity_hash("talker", "/"),
            "ctrl"
        ));
        assert!(
            !group_filter_accepts(
                Some(&active[..]),
                node_identity_hash("listener", "/"),
                "ctrl"
            ),
            "another node's identically-named group must NOT be admitted"
        );
    }

    /// The namespace is part of the identity, not decoration: two nodes may
    /// share a bare name under different namespaces, which is legal in ROS.
    #[test]
    fn the_same_name_under_another_namespace_is_a_different_node() {
        let active = [entry("talker", "/left", "ctrl")];
        assert!(!group_filter_accepts(
            Some(&active[..]),
            node_identity_hash("talker", "/right"),
            "ctrl"
        ));
    }

    /// An empty namespace and `/` are the SAME node. Both ends normalise, and
    /// if only one did, a filter would never match what it named.
    #[test]
    fn an_empty_namespace_normalises_to_root() {
        assert_eq!(
            node_identity_hash("talker", ""),
            node_identity_hash("talker", "/")
        );
    }

    /// The separator is load-bearing: without it `("ab","c")` and `("a","bc")`
    /// would hash alike, and a node name may contain any namespace character.
    #[test]
    fn the_name_namespace_split_cannot_be_forged() {
        assert_ne!(
            node_identity_hash("ab", "/c"),
            node_identity_hash("a", "b/c")
        );
    }

    /// phase-409 — the wildcard and an EMPTY filter are different answers, and
    /// the carved table cannot tell them apart on its own (the old
    /// `Option<Vec>` could). `Executor::active_groups_filtering` is what keeps
    /// them apart; this pins the distinction at the decision itself.
    #[test]
    fn an_empty_filter_is_not_the_wildcard() {
        let empty: [ActiveGroup; 0] = [];
        let n = node_identity_hash("n", "/");
        assert!(!group_filter_accepts(Some(&empty[..]), n, "anything"));
        assert!(group_filter_accepts(None, n, "anything"));
    }
}

// ============================================================================
// Executor
// ============================================================================

/// Backend-agnostic executor that owns a session.
///
/// Provides `create_node()` for entity creation and `drive_io()` for polling.
///
/// # Callback Mode
///
/// The executor supports arena-based callback registration via the
/// `node_mut(id).subscription(t)` builder and
/// [`register_service()`](Self::register_service), with dispatch via
/// [`spin_once()`](Self::spin_once). No heap allocation is needed.
///
/// The sizes are set via `NROS_EXECUTOR_MAX_CBS` (default 4) and
/// `NROS_EXECUTOR_ARENA_SIZE` (default 4096) environment variables at build time.
///
/// Phase 124.B.2 — opaque context handed to the runtime wake
/// callback. Backends store the raw pointer + invoke the callback;
/// the callback decodes back to `&WakeCtx`.
#[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
pub(crate) struct WakeCtx {
    pub(crate) flag: portable_atomic_util::Arc<portable_atomic::AtomicBool>,
    /// The wake primitive. Phase 130.3 added it beside a `std::sync::Condvar`
    /// pair and noted that "a future migration to a single primitive flips one
    /// branch instead of two"; phase-359 W10 is that migration, and this is the
    /// one that survived.
    pub(crate) node_wake: Option<portable_atomic_util::Arc<super::node_wake::NodeWake>>,
}

/// Phase 124.B.2 — runtime wake callback.
///
/// RT-context contract:
///
/// * **Thread-safe**: callable from any thread. The cb is lock-free
///   on the cv path — no mutex held during `notify_all`. Lost-wakeup
///   is prevented by the waiter checking `wake_flag` under
///   `wake_mu` via the `wait_timeout_while` predicate.
/// * **NOT async-signal-safe on POSIX**: `pthread_cond_signal`
///   isn't on the POSIX async-signal-safe function list. For POSIX
///   signal handler wake, use a `signalfd` + select pattern in a
///   thread that owns the wake duty — that pattern is Linux-only
///   (`signalfd`/`eventfd` are Linux syscalls, not POSIX), which is
///   why the `WakeSignalFd` worker is gated `target_os = "linux"`.
/// * **RTOS ISR**: per-RTOS platform layer wraps the cv with an
///   ISR-safe primitive (`xSemaphoreGiveFromISR`,
///   `tx_event_flags_set` from ISR, `k_sem_give` from ISR on
///   Zephyr). Backend's ISR caller routes through the platform's
///   `signal_from_isr` API instead of this cb directly.
/// * **Bounded execution time**: O(1) — atomic store + cv notify.
///   No allocation, no contended lock.
///
/// The cb is the symbol backends invoke from their async wake path
/// (datagram arrival, worker-thread enqueue, etc.). It does
/// flag-write + condvar-signal in that order, lock-free.
#[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
pub(crate) unsafe extern "C" fn nros_rmw_runtime_wake_cb(ctx: *mut core::ffi::c_void) {
    if ctx.is_null() {
        return;
    }
    // Phase 141.B.2 — capture T0 at cb entry. No-op when the
    // probe feature is off or no cycle reader is installed.
    #[cfg(feature = "wake-latency-probe")]
    super::wake_probe::on_wake();
    // SAFETY: ctx points at a `WakeCtx` owned by an Executor still
    // alive at the time of the call. `Executor::clear_wake_signal`
    // discharges that obligation — `set_wake_callback(None, _)` on the
    // primary and every extra session — from `Executor::close` (before
    // the session closes) and from the end of `Executor::drop` (before
    // `wake_ctx` is dropped). Issue 1385: until then this comment named
    // an "`install_wake_*` teardown path" that did not exist, and
    // `set_wake_callback(None` occurred nowhere in the tree but here.
    let wake = unsafe { &*(ctx as *const WakeCtx) };
    // Lock-free: the `flag` store is SeqCst and therefore happens-before any
    // subsequent acquire in the waiter, so a wake cannot be missed even though
    // nothing is held here.
    wake.flag.store(true, core::sync::atomic::Ordering::SeqCst);
    // phase-359 W10 — ONE primitive. This used to signal both a
    // `std::sync::Condvar` and (since phase 130.3) the `NodeWake`, "so the cb
    // keeps working whichever wait primitive spin_once is using". `spin_once`
    // now has only one, so this has only one to signal.
    if let Some(nw) = wake.node_wake.as_ref() {
        nw.signal();
    }
}

/// phase-436 — the callback a backend holds when several executors share its
/// session: signal every member of the [`WakeFanout`](super::wake_fanout)
/// whose address is `ctx`. The entry is a `static`, so `ctx` never dangles.
#[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
pub(crate) unsafe extern "C" fn nros_rmw_fanout_wake_cb(ctx: *mut core::ffi::c_void) {
    if ctx.is_null() {
        return;
    }
    // SAFETY: `ctx` is `WakeFanout::as_ctx` of a `static` pool entry.
    let fanout = unsafe { &*(ctx as *const super::wake_fanout::WakeFanout) };
    fanout.fire(nros_rmw_runtime_wake_cb);
}

/// phase-467 Row 8 — the symbol a backend invokes when the ROS GRAPH changes.
///
/// `rmw_event_callback_t`'s shape, so it fits the ABI slot unchanged:
/// `user_data` plus a coalesced count, and no payload. The count is IGNORED on
/// purpose — a guard condition is a level, not a queue, so N changes observed
/// before the executor spins are one dispatch. That is the same collapse
/// `guard_try_process` already performs on a flag several `trigger()`s set.
///
/// RT-context contract: identical to [`nros_rmw_runtime_wake_cb`] and for the
/// same reason — a relaxed-store-plus-wake, O(1), no allocation, no lock. Both
/// are called from a transport or worker thread.
///
/// # Safety
///
/// `user_data` must be the pointer `Executor::install_graph_change_guard`
/// passed: a `GuardCondition` in a box that executor owns. The obligation is
/// discharged by `clear_graph_change_signal`, which retires the pointer from
/// the backend BEFORE the box is freed, from `close()` and from `drop`. Issue
/// 1385 is what the other ordering costs.
#[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
pub(crate) unsafe extern "C" fn nros_rmw_runtime_graph_change_cb(
    user_data: *const core::ffi::c_void,
    _count: usize,
) {
    if user_data.is_null() {
        return;
    }
    // SAFETY: see this function's `# Safety`.
    let guard = unsafe { &*(user_data as *const GuardCondition) };
    guard.trigger();
}

/// Phase 124.B.7.c — Linux signalfd worker.
///
/// Owns a Linux `eventfd` plus a worker task that `read()`s the
/// fd and forwards it as a wake. The eventfd
/// write side is async-signal-safe per the kernel contract
/// (`write(2)` to an eventfd is permitted from signal handlers),
/// closing the gap that `pthread_cond_signal` leaves open on POSIX.
///
/// Lifecycle:
///   * Constructed lazily in `Executor::signal_fd()` on first
///     caller request.
///   * `Drop` writes a shutdown sentinel + joins the worker.
///
/// Caller flow (signal handler):
///   1. Get fd via `Executor::signal_fd()` before installing the
///      handler.
///   2. Handler does `eventfd_write(fd, 1)` (equivalently,
///      `write(fd, &1u64, 8)`).
///   3. Worker thread reads the fd, signals wake_cv. spin_once
///      blocked in cv.wait_timeout_while sees flag=true and exits.
///
/// phase-359 W10 — the worker is a PLATFORM TASK, not a `std::thread`, and it
/// forwards through the same [`NodeWake`](super::node_wake::NodeWake) the
/// runtime wake callback uses rather than a `std::sync::Condvar`. The eventfd
/// itself is still Linux — that is what makes the write async-signal-safe — so
/// this stays `target_os = "linux"`; what it no longer is, is std-only.
#[cfg(all(feature = "signal-fd-wake", target_os = "linux"))]
pub struct WakeSignalFd {
    fd: core::ffi::c_int,
    ctx: portable_atomic_util::Arc<SignalFdCtx>,
    task: Option<nros_platform_api::task::PlatformTask>,
}

/// What the signalfd worker task needs, reachable through one pointer.
#[cfg(all(feature = "signal-fd-wake", target_os = "linux"))]
struct SignalFdCtx {
    fd: core::ffi::c_int,
    shutdown: portable_atomic::AtomicBool,
    /// The executor's wake state — the same `WakeCtx` the runtime callback
    /// decodes, reached as an address so the context is plainly `Send`.
    wake_ctx: usize,
}

/// Worker entry: read the eventfd, forward as a wake, until shut down.
///
/// # Safety
/// `arg` must point at a live [`SignalFdCtx`] whose `wake_ctx` addresses a
/// `WakeCtx` that outlives this task.
#[cfg(all(feature = "signal-fd-wake", target_os = "linux"))]
unsafe extern "C" fn signal_fd_worker(arg: *mut core::ffi::c_void) -> *mut core::ffi::c_void {
    // SAFETY: the spawn site passes `Arc::as_ptr` of a ctx it keeps alive until
    // after the join in `Drop`.
    let ctx = unsafe { &*(arg as *const SignalFdCtx) };
    loop {
        let mut buf = [0u8; 8];
        // SAFETY: reading 8 bytes from an eventfd into an 8-byte buffer.
        let n = unsafe { libc::read(ctx.fd, buf.as_mut_ptr() as *mut core::ffi::c_void, 8) };
        if ctx.shutdown.load(portable_atomic::Ordering::Acquire) {
            return core::ptr::null_mut();
        }
        if n <= 0 {
            // EINTR / EOF — shutdown was re-checked above, so loop.
            continue;
        }
        // Same effect as `nros_rmw_runtime_wake_cb`, reached directly because
        // the shutdown check above plus `Drop`'s join is what guarantees the
        // `WakeCtx` is still alive.
        // SAFETY: `wake_ctx` addresses the executor's `WakeCtx`, which outlives
        // this task by that same guarantee.
        unsafe {
            let w = &*(ctx.wake_ctx as *const WakeCtx);
            w.flag.store(true, portable_atomic::Ordering::SeqCst);
            if let Some(wake) = w.node_wake.as_ref() {
                wake.signal();
            }
        }
    }
}

#[cfg(all(feature = "signal-fd-wake", target_os = "linux"))]
impl WakeSignalFd {
    /// Spawn the worker. `wake_ctx_ptr` is the `*const WakeCtx`
    /// produced by `Executor::wake_ctx_ptr` — same value the
    /// runtime wake cb decodes.
    ///
    /// phase-359 W10 — returns `NodeError` rather than `std::io::Error`. The
    /// only caller is `Executor::signal_fd`, and the errno detail it used to
    /// carry had no consumer: the one failure a caller can act on is "this
    /// platform would not give me the worker", which is what
    /// `NotInitialized` says — the eventfd and the task are both subsystems
    /// this capability requires and neither is guaranteed.
    fn new(wake_ctx_ptr: *const WakeCtx) -> Result<Self, NodeError> {
        // SAFETY: `eventfd(2)` with a valid flag; returns -1 on failure.
        let fd = unsafe { libc::eventfd(0, libc::EFD_CLOEXEC) };
        if fd < 0 {
            return Err(NodeError::NotInitialized);
        }
        let ctx = portable_atomic_util::Arc::new(SignalFdCtx {
            fd,
            shutdown: portable_atomic::AtomicBool::new(false),
            wake_ctx: wake_ctx_ptr as usize,
        });
        let arg = portable_atomic_util::Arc::as_ptr(&ctx) as *mut core::ffi::c_void;
        // SAFETY: `arg` points at a ctx this struct owns and keeps alive until
        // after the join in `Drop`.
        let Some(task) = (unsafe {
            nros_platform_api::task::PlatformTask::spawn(
                signal_fd_worker,
                arg,
                // A read(2) loop and one atomic store — the smallest stack any
                // port will honour is plenty.
                8192,
                c"nros-wakefd".as_ptr(),
            )
        }) else {
            // SAFETY: nothing else holds the fd — the task never started.
            unsafe { libc::close(fd) };
            return Err(NodeError::NotInitialized);
        };
        Ok(Self {
            fd,
            ctx,
            task: Some(task),
        })
    }

    /// Returns the writable eventfd. The caller (typically a POSIX
    /// signal handler) writes any non-zero 8-byte value to trigger
    /// a wake. `write(2)` on an eventfd is async-signal-safe per
    /// `eventfd(2)` man page.
    pub fn fd(&self) -> core::ffi::c_int {
        self.fd
    }
}

#[cfg(all(feature = "signal-fd-wake", target_os = "linux"))]
impl Drop for WakeSignalFd {
    fn drop(&mut self) {
        self.ctx
            .shutdown
            .store(true, portable_atomic::Ordering::Release);
        // Wake the worker so it re-checks shutdown: it is blocked in `read`,
        // which only this write can release.
        let one: u64 = 1;
        // SAFETY: an 8-byte write to our own eventfd.
        unsafe {
            libc::write(self.fd, &one as *const u64 as *const core::ffi::c_void, 8);
        }
        if let Some(task) = self.task.take() {
            task.join();
        }
        // SAFETY: the worker has exited, so nothing else touches the fd.
        unsafe { libc::close(self.fd) };
    }
}

/// Phase 124.B.7.b — ISR / interrupt-context wake callback.
///
/// Same semantics as [`nros_rmw_runtime_wake_cb`] but constrained to
/// async-signal-safe / ISR-safe primitives.
///
/// Per-platform routing:
///
/// * **POSIX (std)**: `pthread_cond_signal` is NOT on the POSIX
///   async-signal-safe function list. Calling from a SIGUSR1
///   handler is technically UB. Real fix (Phase 124.B.7.c) routes
///   via `signalfd`/`eventfd` + a runtime worker thread — Linux
///   only, since neither syscall is POSIX; until that lands,
///   signal-handler callers MUST use
///   `rclc_guard_condition_trigger` from a **separate thread** (not
///   from the handler itself), OR set the wake_flag and rely on
///   the next poll deadline. This cb currently aliases the regular
///   `wake_cb` and is safe only from non-signal-handler ISR-like
///   contexts (e.g. timer thread, kernel callback).
///
/// * **RTOS no_std (Zephyr/FreeRTOS/ThreadX)**: routes through the
///   platform-cffi `condvar_signal_from_isr` slot. Each backend
///   uses its ISR-safe variant — `xSemaphoreGiveFromISR`,
///   `tx_semaphore_put`, `k_condvar_signal`.
///
/// `ctx` semantics identical to [`nros_rmw_runtime_wake_cb`].
#[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
#[allow(dead_code)] // Public exposure pending B.7.c signalfd worker.
pub(crate) unsafe extern "C" fn nros_rmw_runtime_wake_cb_from_isr(ctx: *mut core::ffi::c_void) {
    // Today: alias regular wake_cb. POSIX signal-handler safety
    // pending B.7.c (signalfd worker-thread forward). Documented in
    // the contract above so callers know the boundary.
    unsafe { nros_rmw_runtime_wake_cb(ctx) };
}

/// Phase 216 follow-up — per-Node dispatch trampoline registered with
/// [`Executor::register_dispatch_slot`].
///
/// The board-side dispatch task (RTIC `__nros_run` / Embassy
/// `__nros_run_task`) dequeues a `nros_platform::SignaledCallback`
/// envelope and forwards `(cb_id, ctx_ptr)` into
/// [`Executor::dispatch_callback`]; that method linear-scans this
/// slot table and invokes every registered `on_callback` with the
/// owning Node's per-Node `state` blob. Each Node's
/// `__nros_node_<pkg>_on_callback` self-filters on its own
/// `CallbackId` tag set, so a slot whose Node doesn't own this
/// callback is a cheap no-op string compare.
///
/// The shape mirrors the per-pkg `__nros_node_<pkg>_on_callback`
/// extern "C" trampoline emitted by the `nros::node!()` macro
/// (see `packages/core/nros-macros/src/lib.rs` Phase 216.A.5).
///
/// # Why not `linkme`
///
/// `linkme::distributed_slice` hangs on bare-metal Cortex-M /
/// RISC-V because `cortex_m_rt`'s link script doesn't provide the
/// `__start_/__stop_` section anchors in a shape that lets the
/// iterator terminate (see
/// `packages/rmw/cffi/src/section.rs` Phase 142). Since
/// stm32f4 RTIC / Embassy boards are the whole point of Phase 216,
/// the registry uses the explicit `register()` pattern from Phase
/// 104.A.
#[derive(Clone, Copy)]
pub struct DispatchSlot {
    /// Owning Node's `State` blob — produced by the macro-emitted
    /// `i()` and round-tripped through
    /// `nros::__private_node_state_into_raw`. Opaque to the
    /// executor.
    pub state: *mut core::ffi::c_void,
    /// Per-Node `extern "C"` trampoline; signature matches the
    /// `__nros_node_<pkg>_on_callback` symbol the `nros::node!()`
    /// macro emits.
    pub on_callback: unsafe extern "C" fn(
        state: *mut core::ffi::c_void,
        cb_id_ptr: *const u8,
        cb_id_len: usize,
        ctx: *mut core::ffi::c_void,
    ),
}

// SAFETY: `DispatchSlot` carries two raw pointers (`state` + an
// extern "C" fn pointer). The fn pointer is `Send`/`Sync` by
// definition; the `state` pointer's `Send`/`Sync` story matches the
// owning `Executor` (which is `unsafe impl Send`). Treating the
// slot itself as `Send` keeps the existing `Executor` Send impl
// intact — see `unsafe impl Send for Executor {}` later in this
// file.
unsafe impl Send for DispatchSlot {}
unsafe impl Sync for DispatchSlot {}

/// Phase 258 (Track 2, 2a) — executor-owned component tick slot.
///
/// The layering-clean half of the W0-B `install` seam's tick fix
/// (phase-257 D2). A `nros`-layer `install`/`register_node_borrowed`
/// builds an `Arc<ComponentCell>` (the typed/poll-driven component
/// state) and enrolls it here via [`Executor::enroll_component`]; the
/// executor then drives `tick` on every enrolled slot at the tail of
/// each [`spin_once`](Executor::spin_once) — so `install`'d nodes
/// (C, C++, **and Rust owned-spin**) tick, closing the
/// service-client/action poll gap that the callback-`Arc`-only
/// lifetime left open.
///
/// Like [`DispatchSlot`] the executor only sees raw pointers + `extern
/// "C"` fn pointers (no `nros` dep — `nros-node` is the lower layer):
///
/// * `state` — a *leaked* `Arc<ComponentCell>` (via `Arc::into_raw`),
///   re-borrowed by the `nros`-side `tick`/`drop` fns. Unlike a
///   pub/sub/timer component (kept alive by the executor's per-entity
///   callback `Arc` clones), a poll-only component has no callbacks, so
///   the slot must own a clone of the cell — hence the paired `drop`.
/// * `tick` — `nros`-side `extern "C"` fn that casts `state` back to
///   `&ComponentCell`, casts `exec_ctx` back to `*mut Executor`, and
///   runs that one cell's tick (mirrors `ExecutorNodeRuntime::run_ticks`).
/// * `drop` — `nros`-side `extern "C"` fn run on `Executor::drop` that
///   reconstitutes + drops the leaked `Arc`, so the executor owns the
///   cell's lifetime.
///
/// Kept a SEPARATE registry from [`DispatchSlot`] on purpose: framework
/// dispatch (RTIC / Embassy) is interrupt-driven, name-keyed, and has no
/// tick/own concern — mixing the two risks that path.
#[derive(Clone, Copy)]
pub struct ComponentSlot {
    /// Leaked `Arc<ComponentCell>` (opaque to the executor). Owned by
    /// this slot — dropped via `drop` on `Executor::drop`.
    pub state: *mut core::ffi::c_void,
    /// `nros`-side tick trampoline: `(state, exec_ctx)` where `exec_ctx`
    /// is `*mut Executor`. Drives one component's `tick`.
    pub tick: unsafe extern "C" fn(state: *mut core::ffi::c_void, exec_ctx: *mut core::ffi::c_void),
    /// `nros`-side drop trampoline: reconstitutes + drops the leaked
    /// `Arc<ComponentCell>` at `state`. Run once on `Executor::drop`.
    pub drop: unsafe extern "C" fn(state: *mut core::ffi::c_void),
}

// SAFETY: same story as `DispatchSlot` — two raw pointers + two extern
// "C" fn pointers. The `state` pointer's Send/Sync matches the owning
// `Executor` (`unsafe impl Send for Executor`); the fn pointers are
// Send/Sync by definition.
unsafe impl Send for ComponentSlot {}
unsafe impl Sync for ComponentSlot {}

/// phase-271 — fixed capacity of the per-spin ready-sets (FIFO bitmap + EDF
/// heap) and the dispatch loop's upper bound. The executor's callback index is
/// carried in a `u64` active-mask (`1u64 << i`), so a callback table can hold at
/// most 64 entries regardless of per-entry sizing; the ready-sets are sized to
/// this ceiling (stack-transient) so any entry slice up to 64 dispatches
/// correctly. `EdfReadySet`'s presence bitmap independently asserts `N <= 64`.
pub(crate) const MAX_CALLBACK_SLOTS: usize = 64;

/// Issue 1667 — the arena's allocation grain. Every region the arena hands out
/// starts on it and is a multiple of it, so a released region is always big
/// enough, and aligned enough, to hold its own free-list node.
pub(crate) const ARENA_GRAIN: usize = core::mem::align_of::<u64>();

/// Issue 1667 — the smallest region the arena hands out: one free-list node
/// (`next`, `len`), rounded to the grain.
pub(crate) const ARENA_MIN_REGION: usize =
    (2 * core::mem::size_of::<usize>()).next_multiple_of(ARENA_GRAIN);

/// Issue 1667 — the end of the free list.
const ARENA_FREE_NONE: usize = usize::MAX;

/// Issue 1496 — one arena region, as an allocation hands it out.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct FreedRegion {
    pub(crate) offset: usize,
    pub(crate) len: usize,
}

/// Phase 305 W3 (issue 0255) — upper bound on launch remap rules held by one
/// executor (across all its nodes). Launch files carry a handful per node;
/// raise here if a plan legitimately outgrows it.
pub const MAX_REMAPS: usize = 16;

/// Which of [`crate::names::resolve_name_layered`]'s two tiers a stored rule
/// belongs to.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum RemapTier {
    /// Projected from the launch file (`declare_remap`, which the generated
    /// entry calls). AUTHORITATIVE, scoped to one `(name, namespace)`.
    Launch,
    /// Parsed from `--ros-args` (`crate::ros_args::install_argv_remaps`).
    /// FALLBACK — consulted only when no launch rule matched. Scoped to every
    /// node, or to the nodes of one NAME (rcl matches a `node:` prefix
    /// against the name alone).
    Argv,
}

/// Phase 305 W3 (issue 0255) — one remap rule. `from`/`to` are stored RAW (as
/// written); the lookup in [`Executor::resolve_entity_name_for`] expands both
/// sides against the owning node's identity via `crate::names` (exact-FQN
/// match, no wildcards).
///
/// The table holds BOTH tiers, so each rule records which one it belongs to.
/// The tier is still decided at resolution, by
/// [`crate::names::resolve_name_layered`]'s two parameters, never by where a
/// rule sits in this table — `tier_rules` splits the table into those two
/// arguments. That is what keeps declaration order from deciding between the
/// channels: an argv rule installed before a launch rule still loses to it.
pub(crate) struct RemapRule {
    /// For [`RemapTier::Launch`]: the owning node. For [`RemapTier::Argv`]:
    /// the node name a `name:from:=to` rule was restricted to, or EMPTY for a
    /// rule that applies to every node.
    pub(crate) node_name: heapless::String<64>,
    /// For [`RemapTier::Launch`] only (normalised, `/` for root). Unused by
    /// argv rules, whose node prefix carries no namespace.
    pub(crate) namespace: heapless::String<64>,
    pub(crate) from: heapless::String<{ crate::names::MAX_RESOLVED_NAME_LEN }>,
    pub(crate) to: heapless::String<{ crate::names::MAX_RESOLVED_NAME_LEN }>,
    pub(crate) tier: RemapTier,
}

impl RemapRule {
    /// Does this rule belong to `tier` and apply to the node `(node_name, ns)`?
    /// `ns` must already be normalised (`/` for root).
    fn applies(&self, tier: RemapTier, node_name: &str, ns: &str) -> bool {
        self.tier == tier
            && match tier {
                RemapTier::Launch => {
                    self.node_name.as_str() == node_name && self.namespace.as_str() == ns
                }
                RemapTier::Argv => {
                    self.node_name.is_empty() || self.node_name.as_str() == node_name
                }
            }
    }
}

/// The rules of one tier that apply to one node, in declaration order, as the
/// `(from, to)` pairs [`crate::names::resolve_name_layered`] takes. The ONE
/// place a stored table is split into the two tiers — the executor's resolver,
/// `NodeHandle`, and the Rust component road (through
/// `crate::ros_args::argv_fallback`) all read through it.
pub(crate) fn tier_rules<'r>(
    table: &'r [Option<RemapRule>],
    tier: RemapTier,
    node_name: &'r str,
    namespace: &'r str,
) -> impl Iterator<Item = (&'r str, &'r str)> + 'r {
    let ns = if namespace.is_empty() { "/" } else { namespace };
    table
        .iter()
        .flatten()
        .filter(move |r| r.applies(tier, node_name, ns))
        .map(|r| (r.from.as_str(), r.to.as_str()))
}

/// The executor's halt flag, in the one shape each configuration can hold.
///
/// Issue 1177. With an allocator it is refcounted, because `halt_flag()` hands
/// a caller its own handle to set from a signal handler or another thread.
/// Without one there is no handle to hand out -- a C caller reaches the
/// executor through its own pointer and calls `cancel()` directly -- so a plain
/// atomic is the whole requirement.
///
/// `Arc<AtomicBool>` derefs to `AtomicBool`, so every `load`/`store` below is
/// written once and only construction and the getter are cfg'd.
#[cfg(feature = "alloc")]
pub(crate) type HaltFlag = portable_atomic_util::Arc<portable_atomic::AtomicBool>;
/// See [`HaltFlag`] above -- the no-allocator shape.
#[cfg(not(feature = "alloc"))]
pub(crate) type HaltFlag = portable_atomic::AtomicBool;

pub struct Executor<'s> {
    /// Issue 0656 — the ROS domain this executor's entities belong to.
    ///
    /// Retained because it was NOT: `open_in` passed `config.domain_id` into
    /// `RmwConfig` and dropped it, so every entity built from the executor
    /// (rather than from a `Node`, which keeps its own) declared on domain 0
    /// whatever `ROS_DOMAIN_ID` said. The value was read, printed, and then not
    /// used where it counts — issue 0161's shape.
    pub(crate) domain_id: u32,
    pub(crate) session: SessionStore,
    /// phase-271 (issue 0110) — the six sized tables are no longer inline
    /// arrays baked to `nros-node`'s build-time consts; they borrow
    /// caller-owned, per-entry-sized storage (`&'s mut` slices carved from a
    /// raw `[MaybeUninit<u64>]` backing by [`super::storage::carve`]). Lets a
    /// fat native entry and a lean embedded entry in one shared-target
    /// workspace each size to its own topology. `Executor` stays non-generic
    /// (lifetime only) so the C/C++ FFI keeps wrapping one concrete type.
    pub(crate) arena: &'s mut [MaybeUninit<u8>],
    pub(crate) arena_used: usize,
    /// Issue 1496 / 1667 — the head of the FREE LIST: arena regions given back
    /// by a released entry, reused first-fit by the next allocation that fits.
    ///
    /// The list is INTRUSIVE — each free region holds its own node
    /// (`next`, `len`) in its first bytes — and kept in address order, so a
    /// release coalesces with both neighbours and nothing bounds how many holes
    /// there are. 1496's form was a fixed table of 8 that dropped a region when
    /// full and dropped any split tail under 64 B, and those bytes were gone
    /// for good: measured under a churning workload (issue 1667), three live
    /// entries leaked the whole 74 KiB arena inside 20 000 create/release
    /// rounds. A hole that ends at `arena_used` is given back to the bump
    /// pointer instead of being listed.
    pub(crate) arena_free_head: usize,
    /// Issue 1631 — the region the most recent ENTRY allocation handed out,
    /// waiting for `emplace_entry` to record it in the entry's
    /// `CallbackMeta::arena_len`. Every registration allocates its entry and
    /// then emplaces it, so the pair is adjacent; a registration that fails
    /// between them leaves a stale value that the next allocation overwrites.
    pub(crate) pending_region: Option<FreedRegion>,
    pub(crate) entries: &'s mut [Option<CallbackMeta>],
    /// Phase 110.B — registered scheduling contexts. Slot 0 is
    /// auto-populated with a `Fifo` SC at construction; every entry
    /// without an explicit binding maps to it via
    /// `sched_context_bindings`.
    pub(crate) sched_contexts: &'s mut [Option<super::sched_context::SchedContext>],
    /// Per-entry SC binding parallel to `entries`. Defaults to
    /// `SchedContextId(0)` (the auto-created Fifo SC).
    pub(crate) sched_context_bindings: &'s mut [super::sched_context::SchedContextId],
    /// Phase 110.E — user-space sporadic-server budget state per
    /// Sporadic-class SC. Slot indices match `sched_contexts`; non-
    /// Sporadic slots stay `None`.
    pub(crate) sporadic_states: &'s mut [Option<super::sched_context::SporadicState>],
    /// Phase 110.E.b — atomic sporadic state + opaque platform-timer
    /// handle for ISR-driven refill. Populated by
    /// `register_sporadic_timer`; dropped on Executor `Drop` via the
    /// stored `destroy_fn`.
    #[cfg(feature = "alloc")]
    pub(crate) sporadic_atomic_states: &'s mut [Option<(
        portable_atomic_util::Arc<super::sched_context::AtomicSporadicState>,
        OpaqueTimerHandle,
    )>],
    /// Phase 110.G — major-frame length for time-triggered dispatch.
    /// `0` (default) disables the TT gate entirely; non-zero enables
    /// gating per
    /// `SchedContext.tt_window_offset_us / tt_window_duration_us`.
    pub(crate) major_frame_us: u32,
    /// Phase 110.F — per-OS-priority worker pool. Lazily populated
    /// on first dispatch routing to a non-zero `os_pri`.
    ///
    /// phase-359 W10 — was `std::collections::HashMap<u8, OsPriorityWorker>`
    /// behind `feature = "std"`, because the workers were `std::thread` +
    /// `mpsc`. They are platform tasks now (`super::os_priority`), so the pool
    /// needs only `alloc` and this capability is no longer std-only.
    #[cfg(all(
        feature = "alloc",
        feature = "rmw-cffi",
        feature = "scheduler-os-priority"
    ))]
    pub(crate) os_priority_pool: super::os_priority::OsPriorityPool,
    /// Phase 110.F — caller-supplied `apply_policy` function pointer
    /// each worker invokes at startup to elevate its OS priority.
    /// `None` = the worker pool is disabled; entries bound to non-
    /// zero `os_pri` SCs fall back to the cooperative path.
    /// Mirrors `Executor::open_threaded`'s `apply_policy: fn(...)`
    /// shape — keeps Executor non-generic over Platform.
    // phase-359 W10 — the POLICY is separable from the POOL. Registering it
    // needs nothing but the feature; hosting workers needs a platform
    // (`rmw-cffi`, the same proxy `node_wake` uses). A build that can register
    // but not host falls back to cooperative dispatch, so the public
    // `register_os_priority_dispatcher` keeps its old availability.
    #[cfg(all(feature = "alloc", feature = "scheduler-os-priority"))]
    pub(crate) os_priority_apply_policy:
        Option<fn(nros_platform_api::SchedPolicy) -> Result<(), nros_platform_api::SchedError>>,
    pub(crate) trigger: Trigger,
    pub(crate) semantics: ExecutorSemantics,
    /// Node name for entities created via `register_subscription`/`register_service`.
    /// Empty means unset — no liveliness tokens will be declared.
    pub(crate) node_name: heapless::String<64>,
    /// Phase 228.C — per-tier callback-group filter. Wildcard (register every
    /// callback — the single-tier degenerate case + today's behaviour) until
    /// [`set_active_groups`](Self::set_active_groups) names a non-empty set;
    /// after that this tier's executor accepts only callbacks whose
    /// `.callback_group()` is in it, and skips the others at registration.
    ///
    /// phase-409 — CARVED, and the wildcard is a separate flag rather than an
    /// `Option` around the table, because the table itself no longer lives in
    /// the value. "Filtering with an empty set" and "not filtering" stay
    /// distinguishable, which is the whole content of the old `Option`.
    pub(crate) active_groups: super::storage::CarvedVec<'s, super::storage::ActiveGroup>,
    /// Whether [`active_groups`](Self::active_groups) is a filter at all.
    /// `false` = wildcard (the old `None`).
    pub(crate) active_groups_filtering: bool,
    /// Node namespace (default: "/").
    pub(crate) namespace: heapless::String<64>,
    /// Phase 104.C.2 — rclcpp-style `add_node` table. Holds the
    /// per-Node metadata (name, namespace, rmw, locator, default
    /// SchedContext) for every Node attached to this Executor. The
    /// implicit "primary" Node (NodeId(0)) mirrors `node_name` +
    /// `namespace` above and is auto-populated on first use.
    ///
    /// phase-409 — CARVED. `NodeId` IS an index into this table, so the
    /// carved vector must keep push order and never gain a `swap_remove`.
    pub(crate) nodes: super::storage::CarvedVec<'s, super::node_record::NodeRecord>,
    /// Phase 272 (RFC-0047) — config-seeded node → sched-context bindings, keyed by the node's
    /// fully-qualified `(name, namespace)` pair. `NodeBuilder::build` consults this table to set a
    /// node's `default_sched` when no explicit `.sched()` was given. Empty ⇒ every node stays
    /// `SchedContextId(0)` (byte-identical to pre-272 behaviour). Sized by `MAX_NODES` (at most
    /// one tier per node — RFC-0047 OQ1).
    ///
    /// phase-409 — CARVED.
    pub(crate) node_sched_table: super::storage::CarvedVec<'s, super::storage::NodeSchedEntry>,
    /// Phase 273 (RFC-0047) — config-seeded per-callback-group sched bindings, keyed by the node's
    /// fully-qualified `(name, namespace)` pair PLUS the callback-group name. Overrides the node
    /// default for a callback created in that group. Empty ⇒ no per-group binding (node default
    /// stands). Sized by `MAX_CBS` — an upper bound on distinct callback-group bindings (you can
    /// never have more distinct group bindings than max callbacks).
    ///
    /// phase-409 (issue 0961) — CARVED, and it is the reason the phase exists:
    /// at ~168 B per slot this was `MAX_CBS` * 168 bytes INSIDE the value, so
    /// raising the handle limit from 14 to 36 — a fix for an unrelated failure —
    /// added ~3.7 KiB to the stack frame of every function that moves an
    /// `Executor`, and overflowed a 320 KiB part's main thread.
    pub(crate) group_sched_table: super::storage::CarvedVec<'s, super::storage::GroupSchedEntry>,
    /// Phase 305 W3 (issue 0255) — launch-baked per-node remap rules, keyed by
    /// the declaring node's `(name, namespace)` identity. Entries store the
    /// rule RAW (as written in launch); [`Self::resolve_entity_name`] expands
    /// both sides against the owning node's identity at lookup, via the shared
    /// `crate::names` seam (the same semantics the Rust `ExecutorSink` path
    /// applies). Declaration order is match order (first rule wins).
    /// Issue 0563 — CARVED, not inline. As a `heapless::Vec<RemapRule,
    /// MAX_REMAPS>` this one field was 6664 bytes of an 11632-byte `Executor`
    /// (57%), which is what made building an executor a ~9.3 KB stack
    /// temporary and overflowed the Zephyr Cortex-M main stack (issue 0552).
    /// It is the seventh sized table; phase-271 moved the other six here.
    /// `remap_len` is the fill cursor — occupied slots are `[0, remap_len)`.
    pub(crate) remap_table: &'s mut [Option<RemapRule>],
    pub(crate) remap_len: usize,
    /// Phase 216 follow-up — per-Node dispatch trampoline registry.
    ///
    /// Populated by [`Executor::register_dispatch_slot`]; walked by
    /// [`Executor::dispatch_callback`] each time the board-side
    /// dispatch task hands off a `SignaledCallback` envelope.
    /// Sized by `MAX_NODES` because the upper-bound is one slot per
    /// Node pkg deployed on this executor (the same upper bound used
    /// by `nodes` and `extra_sessions`). `MAX_NODES` is driven by the
    /// `NROS_EXECUTOR_MAX_NODES` build-script env var (default 4);
    /// boards that deploy more Node pkgs raise it at build time.
    ///
    /// Default is `heapless::Vec::new()` (empty) — Nodes register
    /// themselves explicitly via the `register_dispatch_slot` API.
    /// The fallback shape avoids the `linkme` hazard on bare-metal
    /// Cortex-M / RISC-V (see `DispatchSlot` doc).
    ///
    /// phase-409 — CARVED (sized by `ExecutorSizing::nodes`, which is what
    /// `MAX_NODES` now seeds).
    pub(crate) dispatch_slots: super::storage::CarvedVec<'s, DispatchSlot>,
    /// Phase 258 (Track 2, 2a) — executor-owned component tick registry.
    /// Enrolled by [`Executor::enroll_component`] (from `nros`'s
    /// `install`/`register_node_borrowed`); each slot's `tick` runs at the
    /// tail of [`spin_once`](Self::spin_once); each slot's `drop` runs on
    /// `Executor::drop`. Bounded `MAX_NODES` (matches `dispatch_slots` /
    /// `nodes`). See [`ComponentSlot`] for why it's separate from
    /// `dispatch_slots`.
    ///
    /// phase-409 — CARVED.
    pub(crate) component_slots: super::storage::CarvedVec<'s, ComponentSlot>,
    /// Phase 104.C.3 — extra sessions opened by `node_builder.rmw()`
    /// calls that named a backend different from the Executor's
    /// primary session. Indexed by `NodeRecord.session_idx`
    /// (1..=N maps to `extra_sessions[N-1]`; idx 0 is the primary
    /// `self.session`). Sized by `NROS_EXECUTOR_MAX_NODES` since one
    /// extra session per Node is the worst case.
    ///
    /// phase-409 — CARVED, and the biggest single win: `ConcreteSession` is
    /// 524 B on the island, so this table alone was ~3.1 KiB of the value.
    /// Declared AFTER `session` so field-order drop still closes the primary
    /// session before the extras (`CarvedVec` owns its elements' drop).
    pub(crate) extra_sessions: super::storage::CarvedVec<'s, session::ConcreteSession>,
    /// Issue 0436 — `(rmw_name, locator)` for each entry of `extra_sessions`,
    /// the extras' equivalent of `primary_rmw_name` / `primary_locator`.
    ///
    /// Without it an extra session is ANONYMOUS, and
    /// `NodeBuilder::resolve_session_slot` could only recognise one by finding a
    /// previously-registered `NodeRecord` bound to it. Sessions opened by
    /// `open_multi*` have no such Node yet, so the FIRST `.rmw("zenoh")` node fell
    /// through to "open a new session" — a SECOND zenoh session, with an empty
    /// locator, which fails (see `primary_rmw_name`'s note: zenoh-pico's global
    /// state is a process singleton). That is why the PX4 bridge could open both
    /// sessions and then fail to bind its outward Node.
    ///
    /// Written unconditionally by `open_multi*`, but the only READER is
    /// `NodeBuilder::resolve_session_slot`, which is `rmw-cffi`-gated — so
    /// without that feature the field is genuinely unread and the
    /// workspace's `-D dead_code` is right to say so. Allow it exactly
    /// there rather than blanket-allowing a field that must stay live in
    /// every configuration that can reach the reader.
    ///
    /// phase-409 — CARVED.
    #[cfg_attr(not(feature = "rmw-cffi"), allow(dead_code))]
    pub(crate) extra_session_ids: super::storage::CarvedVec<'s, super::storage::ExtraSessionId>,
    /// Phase 156 — primary session's rmw name + locator, captured
    /// at `open*` time so `NodeBuilder::resolve_session_slot`'s
    /// cache lookup can detect when a `.rmw(name).locator(loc)`
    /// matches the primary (slot 0) instead of falling through to
    /// `CffiRmw::open_with_rmw` and trying to open a SECOND
    /// session against the same backend. zenoh-pico's global state
    /// is a process singleton; opening twice fails. Empty when
    /// constructed via `from_session(_ptr)` without `open*`
    /// recording the metadata; in that case the cache check
    /// degrades to "always miss" (today's behaviour).
    pub(crate) primary_rmw_name: heapless::String<32>,
    pub(crate) primary_locator: heapless::String<128>,
    // phase-359 W3 — `portable_atomic_util::Arc`, not `std::sync::Arc`. Same
    // atomically-refcounted pointer, available without `std`, and it compiles on
    // std too. W3 left the GATE on `std` because the public `halt_flag()` getter
    // was std-gated; W10 split that impl, so the field joined `wake_flag` on
    // `alloc`.
    //
    // Issue 1177 — the ALLOCATOR was never the requirement of the FLAG, only of
    // SHARING it. The flag is an `AtomicBool`; what needs an allocator is
    // `halt_flag()`, the getter that hands a caller its own refcounted handle to
    // set from a signal handler or another thread. Gating the flag on `alloc`
    // therefore gated the ability to STOP a no_std executor on a feature it does
    // not need -- and `nros-c`'s spin loop calls `cancel`/`is_halted`/
    // `enter_spin_loop`/`exit_spin_loop`/`is_spinning` unconditionally, so an
    // embedded image did not merely lose cancellation, it failed to compile.
    //
    // `HaltFlag` is the one type name that differs, so every reader below is
    // written once: `Arc<AtomicBool>` derefs to `AtomicBool`, so `load`/`store`
    // are identical on both sides and only construction and the getter are
    // cfg'd.
    pub(crate) halt_flag: HaltFlag,
    /// Is a spin loop running right now? — the observable behind
    /// `is_spinning()` (phase-417 W4.c, rclcpp's `Executor::is_spinning`).
    ///
    /// A plain atomic, not refcounted like `halt_flag`: nothing hands this one
    /// out. `halt_flag()` is a public getter that gives a caller its own
    /// handle to set from another thread; `spinning` is only ever set by the
    /// executor's own loops through `&self`, so it needs no shared ownership.
    ///
    /// Issue 1177 — this used to ride `alloc` "for the same reason the impl
    /// that reads it does". It never needed an allocator itself; it was gated
    /// by ASSOCIATION with `halt_flag`, and when that association turned out to
    /// be wrong this went with it.
    pub(crate) spinning: portable_atomic::AtomicBool,
    /// Phase 104.C.6 — shared executor wake flag. Any source of work
    /// (foreign thread handing off a callback, signal handler, future
    /// per-session vtable wake hook) sets this; `spin_once` swaps it to
    /// `false` on entry and, if it was `true`, polls every session with
    /// a 0-ms timeout instead of blocking. Lets one notification wake
    /// the executor regardless of which session the user is currently
    /// blocked on (the multi-RMW bridge case).
    // phase-359 W3 — ONE wake flag, both flavours. W2 had to leave this pair
    // alone because `wake_handle()` hands it out as a `std::sync::Arc`;
    // converting that signature is what lets the two collapse. Gated on
    // `alloc` (which `std` implies) because the Arc needs an allocator.
    #[cfg(feature = "alloc")]
    pub(crate) wake_flag: portable_atomic_util::Arc<portable_atomic::AtomicBool>,
    /// Phase 124.B.2 — wake condvar paired with `wake_flag`. The
    /// runtime-supplied wake callback (`nros_rmw_runtime_wake_cb` in
    /// nros-rmw-cffi) writes `wake_flag = true` AND signals
    /// `wake_cv` atomically under `wake_mu`. `spin_once` blocks on
    /// the cv with a deadline instead of calling `drive_io` with the
    /// user's timeout — sub-poll-period wake latency.
    ///
    /// Poll-only backends (NULL `set_wake_callback` slot) leave the
    /// cb uninstalled; the cv wait still fires on its deadline,
    /// then drive_io(0) drains whatever the backend's internal
    /// poll has buffered.
    /// Phase 130.3 — Zephyr+std uses `nros_platform_wake_*` (k_sem)
    /// instead of `std::sync::Condvar` because Zephyr's libc
    /// `pthread_cond_timedwait` hangs past its deadline. `None`
    /// when the platform provider didn't link a wake primitive
    /// (e.g. test builds with `rmw-cffi` but no `platform-*`
    /// feature); spin_once falls back to driving the transport
    /// for the full timeout in that case.
    // phase-359 W2 — ONE field, not one per flavour. `portable_atomic_util::Arc`
    // compiles on std too, and `std` implies `alloc`, so the std and alloc arms
    // were two spellings of the same thing. The inner `NodeWake` was already
    // shared; only the Arc differed.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) node_wake: Option<portable_atomic_util::Arc<super::node_wake::NodeWake>>,
    /// Phase 130.4 — true when at least one session's backend
    /// installed the wake callback. Drives whether `spin_once`
    /// uses the wake-primitive wait (`NodeWake` / `Condvar`) or
    /// just `drive_io(timeout_ms)`. Poll-only backends
    /// (XRCE-DDS-Client, the dust-DDS shim) leave this `false`;
    /// Cyclone sets it — it fills the slot and backs it with a real
    /// `dds_set_listener` listener; the wait then becomes a no-op sleep that
    /// starves reliable retransmission (Phase 127.C.4 root
    /// cause: server's `send_response` flushes 100 ms once, then a
    /// blind `wait_ms(100)` sleeps with zero session activity, so
    /// the agent's ACK arrives into a stalled session and reliable
    /// redelivery never fires).
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) has_async_wake: bool,
    /// Phase 124.B.2 — opaque context Arc handed to backends via
    /// `set_wake_callback`. Lazy-allocated on first install; stays
    /// alive for the Executor's lifetime so the raw pointer stored
    /// in backends remains valid.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) wake_ctx: Option<portable_atomic_util::Arc<WakeCtx>>,
    /// Issue 1385 — has THIS executor handed `wake_ctx`'s pointer to a
    /// backend? The predicate `clear_wake_signal` reads at teardown.
    ///
    /// Not `wake_ctx.is_some()`: the ctx is also allocated by `signal_fd()`
    /// and by every guard condition, neither of which installs anything on a
    /// session. Clearing on those would clear a callback this executor never
    /// owned. (Since phase-436 a tier over a BORROWED session does install: it
    /// joins the session's wake fan-out, and its teardown is leaving it.)
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) wake_cb_installed: bool,
    /// phase-436 (RFC-0106 D5) — something other than the backend can signal
    /// this executor's wake object: a guard condition, triggered from another
    /// thread. A poll-only backend waits inside its own `recv`, which that
    /// signal cannot end, so the wait is driven in slices of
    /// [`POLL_ONLY_WAKE_SLICE_MS`] while this is set. Never cleared: a guard
    /// outliving its registration costs slicing, never a missed wake.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) has_cross_thread_waker: bool,
    /// phase-436 — this executor's place in the wake fan-out of its PRIMARY
    /// session, when it has one. Every executor over a session joins the same
    /// entry, so an arrival wakes all of them, not only the one that happened
    /// to install into the backend's single slot. See `wake_fanout`.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) wake_membership: Option<super::wake_fanout::Membership>,
    /// phase-467 Row 8 — the graph-change target the BACKEND holds a pointer
    /// to, owned here.
    ///
    /// This box is the whole answer to issue 1385 on this path. The backend
    /// fires the graph-change edge from a transport or worker thread, so
    /// whatever it dereferences must outlive every such call — and the thing
    /// the caller has in hand is a `rcl_guard_condition_t` in ITS storage,
    /// which the caller may free or reuse at any time. Handing that pointer
    /// over would BE 1385. So the executor keeps its own handle to the same
    /// arena flag, at a heap address that does not move when the executor
    /// does, and [`clear_graph_change_signal`] retires the backend's pointer
    /// BEFORE this box drops.
    ///
    /// [`clear_graph_change_signal`]: Self::clear_graph_change_signal
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) graph_change_target: Option<alloc::boxed::Box<GuardCondition>>,
    /// Phase 124.B.7.c — lazily-allocated Linux signalfd worker.
    /// Owned by the Executor; spawned on first `signal_fd()` call.
    /// Drop joins the worker thread and closes the fd.
    #[cfg(all(feature = "signal-fd-wake", target_os = "linux"))]
    pub(crate) signal_fd: Option<WakeSignalFd>,
    /// Issue 1812 — CARVED from the backing's [`ParamHome`](super::storage::ParamHome)
    /// when the sizing carves a store; with `alloc`, one heap allocation
    /// otherwise. Without `alloc` there is no heap arm, and an executor whose
    /// backing carves no home refuses parameters by name instead.
    #[cfg(feature = "param-store")]
    pub(crate) params: Option<crate::param_store::Placed<'s, crate::param_store::ParamState<'s>>>,
    /// phase-382 W3' — the parameter store's slots, CARVED from this
    /// executor's backing and still uninitialised. Taken (left empty) the
    /// first time something builds the store; empty from the start when the
    /// sizing carved none, in which case the store comes from the heap.
    #[cfg(feature = "param-store")]
    pub(crate) param_slots: &'s mut [MaybeUninit<nros_params::ParameterSlot>],
    /// Issue 1812 — the services' home, CARVED beside the store's slots and
    /// still uninitialised. Taken with them; empty when the sizing carved no
    /// store.
    #[cfg(feature = "param-store")]
    pub(crate) param_home: &'s mut [MaybeUninit<super::storage::ParamHome>],
    /// Issue 1706 -- the parameter store's one allocation was refused by the
    /// platform heap. Recorded so the refusal is REPORTED once and not retried
    /// on every declaration: a retry cannot succeed on a heap that only shrinks
    /// from here, and on Zephyr each attempt prints its own `HEAP EXHAUSTED`.
    #[cfg(feature = "param-store")]
    pub(crate) param_store_refused: bool,
    /// phase-446 W6 -- the parameters each node's contract DECLARES, baked by
    /// the entry from the SystemModel. Empty (nothing checked) until an entry
    /// hands one over with [`Self::set_declared_params`].
    #[cfg(feature = "param-store")]
    pub(crate) declared_params: nros_params::DeclaredParams,
    /// phase-425 W3b — the `/clock` subscription this image installed, if any.
    /// `None` means no time source; the value is the handle so it can be
    /// cancelled when `use_sim_time` goes false.
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    pub(crate) sim_time_source: Option<HandleId>,
    /// phase-425 W3b — the LAST REQUESTED state of `use_sim_time`, which is not
    /// the same thing as the installed state: a request can arrive before any
    /// node exists (`nros::main!` declares parameters BEFORE it registers
    /// components), and there is no node to hang a subscription on until then.
    /// `reconcile_ros_time_source` closes the gap on each spin.
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    pub(crate) sim_time_requested: bool,
    /// Whether `use_sim_time` was ever stated to THIS executor.
    ///
    /// `sim_time_requested` alone cannot answer it: `false` is both "told to
    /// turn it off" and "never told anything", and the two license opposite
    /// actions on a PROCESS-GLOBAL gate. Without this, every executor that
    /// never heard of the parameter wrote `set_active(false)` on its first
    /// spin -- because the gate defaults to TRUE, so `false != is_active()`
    /// held -- and switched off a simulated clock somebody else installed.
    /// One `cargo test` process is exactly that situation: 344 sibling tests
    /// spin an executor each, and the sim-time test failed 3 runs of 3 while
    /// passing alone.
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    pub(crate) sim_time_stated: bool,
    /// phase-430 W1 — the one-shot that says "`use_sim_time` is on and `/clock`
    /// has never spoken", so a MISCONFIGURED image is distinguishable from a
    /// merely PAUSED one. Armed when the source attaches, disarmed by the first
    /// sample or by the report. The policy, and the argument for its unit, are
    /// in [`crate::time_source::SilenceWatch`].
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    pub(crate) sim_time_silence: crate::time_source::SilenceWatch,
    #[cfg(feature = "lifecycle-services")]
    pub(crate) lifecycle:
        Option<alloc::boxed::Box<crate::lifecycle_services::LifecycleRuntimeState>>,
    /// Wall-clock instant at which the previous `spin_once` exited. The
    /// timer delta on the next call is measured from this point so any
    /// time the caller spent between `spin_once` invocations (e.g. an
    /// explicit `thread::sleep`) counts toward timer accumulation just
    /// like time spent inside `drive_io`.

    /// Monotonic clock endpoint for no_std timer accounting.
    // phase-359 W4 — ONE field. The std twin held an `Instant`; both now hold
    // µs from the single `now_us()` read.
    pub(crate) last_spin_end_us: Option<u64>,
    /// The executor's monotonic µs clock: `ExecutorConfig::clock_us` when the
    /// caller supplied one, else [`default_clock_us_fn`].
    ///
    /// phase-359 W10 — no longer `no_std`-only. The std build read an
    /// `Instant` through a separate field instead, which is how "what time is
    /// it" had two answers in one crate.
    pub(crate) clock_us_fn: Option<fn() -> u64>,

    /// Consecutive `drive_io` failures on the PRIMARY session (issue 0324).
    ///
    /// Reset to 0 by any successful drive. A session that has died — router
    /// gone, lease expired, socket closed — used to keep returning `Ok(())`
    /// from `spin()` forever: the node looked alive, publishes went nowhere,
    /// and no callback fired. Nothing in the crate could report it; a
    /// `git grep` for a health surface found none, so every such
    /// investigation started from packet captures (issue 0268 burned days
    /// this way).
    ///
    /// A COUNTER rather than propagating the error out of `spin_once`,
    /// deliberately: `drive_io` returns `Err` for any non-OK backend code, and
    /// whether a benign poll timeout maps to one is backend-specific. Aborting
    /// the spin on a single failure would risk turning a transient into a dead
    /// node. A counter cannot regress behaviour and still makes the condition
    /// observable via [`Executor::session_io_failures`].
    pub(crate) consecutive_io_failures: u32,
    /// RFC-0052 W3b.2 — wall-clock (epoch µs) source for age monitors.
    pub(crate) epoch_us_fn: Option<fn() -> u64>,
    /// phase-483 W3 — the component registration frame the `nros` facade
    /// installs for the duration of a component's `register`, so the
    /// declarative entity constructors on [`Node`](super::node::Node) can reach
    /// the sink that owns the component's cell. Opaque here: nros-node sits
    /// below the crate that defines the frame. `None` outside a registration.
    pub(crate) component_frame: Option<core::ptr::NonNull<()>>,
    /// RFC-0052 W3b.4 — baked contract-monitor table (empty = uncontracted
    /// image; every monitor path below folds away).
    pub(crate) monitor_table: &'static [super::monitor::MonitorSpec],
    pub(crate) monitor_states: [super::monitor::MonitorState; super::monitor::MAX_MONITORS],
    /// Alive supervision, one record per SchedContext: dispatches are counted
    /// in the dispatch path where the SC index is already resolved, and read
    /// once per monitor tick. CARVED from the backing like `sporadic_states`.
    /// It began as an inline `[_; MAX_SC]` pair on the claim that `MAX_SC` is a
    /// build-time constant; it is a SIZING KNOB (`ExecutorSizing::sc`), so the
    /// header grew with it and `the_executor_value_does_not_scale_with_the_knobs`
    /// caught it (issue 0961).
    pub(crate) alive_slots: &'s mut [super::monitor::AliveSlot],
    /// phase-476 W0 — per-callback-slot lifetime tags, parallel to
    /// `entries`: the generation a handle must match, and the owning node.
    pub(crate) slot_tags: &'s mut [super::types::SlotTag],
    /// W3b.5 — baked subscriber age-contract table (empty = none).
    pub(crate) age_table: &'static [super::monitor::AgeMonitorSpec],
    pub(crate) age_states: [super::monitor::AgeState; super::monitor::MAX_AGE_MONITORS],
    /// phase-462 W3b — baked hazard table (empty = no contracted hazard). Its
    /// state lives in the rows' own `static` cells, so a hazard costs this
    /// value nothing.
    pub(crate) hazard_table: &'static [super::monitor::HazardSpec],
    /// W3b.5 — hook invoked on `DeadlineAction::Fault` (panic when unset).
    pub(crate) fault_fn: Option<fn(&super::monitor::Violation)>,
    /// phase-503 — the reaction hook and its context: called when a
    /// supervised route passes its deadline (`route-deadline-runtime`), and on
    /// `DeadlineAction::Fault` when no `fault_fn` is set.
    pub(crate) reaction_hook: Option<(super::monitor::ReactionHookFn, *mut core::ffi::c_void)>,
    /// Issue #515 — the spin cadence audit runs once, on the first spin
    /// that carries a non-zero timeout (which is where the tier's
    /// declared spin period becomes visible to the executor).
    pub(crate) spin_quantization_checked: bool,
    /// phase-436 W1 — the cadence the quantization audit (issue 0515) actually
    /// ran against. Recorded because the audit only LOGS: without this a
    /// regression that fed it the wrong number is invisible to a test, and
    /// capping the park by the timer deadline is exactly such a regression
    /// waiting to happen.
    pub(crate) spin_quantization_us: u64,
    /// Release jitter: worst observed lateness of a `spin_period` wake
    /// against its own nominal schedule, in microseconds.
    ///
    /// Issue #515 added a STATIC audit for one cause of cadence error --
    /// a period that is not a multiple of the spin period. Nothing measured
    /// the actual release instants, and `audit_spin_quantization` says so in
    /// as many words: "the rate is preserved and no activation is dropped,
    /// so every runtime rule is (correctly) silent -- the jitter stays
    /// invisible until someone measures cadence on target."
    ///
    /// This is that measurement, and it is the one `cyclictest` exists to
    /// report: the deviation between a timer's programmed wake-up and the
    /// instant the task actually resumed, whose MAXIMUM is the figure of
    /// merit for a real-time system.
    ///
    /// `spin_period` already holds both numbers -- `next_us` is the nominal
    /// deadline and `now_us()` the actual -- and when the loop is late it
    /// skips the sleep and discards the difference. That difference is the
    /// jitter.
    pub(crate) max_release_jitter_us: u64,
    /// Clock reading at the previous `spin_once` entry, for the interval the
    /// jitter is measured over. `None` until the first spin, and reset by
    /// `clear_release_jitter_stats` so a window starts clean.
    pub(crate) last_spin_entry_us: Option<u64>,
    /// phase-474 I11 -- the release grid of a `spin_once(timeout)` loop with
    /// no declared cadence. See [`ReleaseGrid`].
    pub(crate) grid: ReleaseGrid,
    /// Jitter high-water at the previous `release-jitter-runtime` check, so
    /// the rule reports the DELTA. Same shape as `overruns_reported` on a
    /// timer header, and for the same reason: a maximum that has not moved
    /// is the fault already reported, not a new one.
    pub(crate) jitter_reported_us: u64,
    /// Declared minimum stack headroom in bytes for the thread this executor
    /// spins on; `0` (default) disables the rule.
    ///
    /// An executor-level install rather than a contract field, because the
    /// bound cannot be derived from anything already declared -- see
    /// `check_stack_headroom`. The entry that spawned the thread is the one
    /// that knows what it gave it, so that is where the number comes from.
    pub(crate) min_stack_headroom_bytes: usize,
    /// Lowest headroom already reported, so the rule fires on new lows only.
    /// `usize::MAX` = nothing reported yet.
    pub(crate) stack_headroom_reported: usize,
    /// phase-436 E3 — a minimum is set but the port reports no stack data,
    /// so `check_stack_headroom_rule` will skip every tick. Recorded when the
    /// bound is set; see `stack_headroom_blind`.
    pub(crate) stack_headroom_blind: bool,
    /// phase-436 E4 — when the headroom query last ran (`None` = never; a
    /// clockless build stores `Some(0)` to mean "has run"), spins since, and
    /// how many queries actually reached the port.
    pub(crate) stack_headroom_last_check_us: Option<u64>,
    pub(crate) stack_headroom_spins_since_check: u32,
    pub(crate) stack_headroom_checks: u32,
    /// The pacing quantum the spin loop was last driven at, in microseconds.
    /// This is the bound the jitter rule judges against -- the caller's own
    /// declared cadence, so nothing further has to be declared.
    pub(crate) spin_nominal_us: u64,
    /// Cadence DECLARED by the driver, in microseconds; `0` = not declared.
    ///
    /// Takes precedence over the `spin_once` timeout when judging release
    /// jitter, because the two are not the same quantity. The timeout is how
    /// long a spin may BLOCK waiting for work; the cadence is how often the
    /// loop intends to come round. A driver that blocks up to 10 ms and then
    /// sleeps 30 ms has a 30 ms cadence and a 10 ms timeout, and judging it
    /// against the timeout reports a loop that is late on every single wake.
    pub(crate) spin_nominal_declared_us: u64,
    /// phase-436 A2b -- the declared cadence is met by the `spin_once` WAIT
    /// itself (`set_spin_nominal_wait_paced_us`), not by a sleep the caller
    /// adds between spins (`set_spin_nominal_us`). A wait-paced cadence runs
    /// on the release grid and is worth one park granule; a self-paced one is
    /// judged from entry to entry and is worth a microsecond.
    pub(crate) spin_nominal_wait_paced: bool,
    /// phase-436 — the bound the last park was computed with, in us, and the
    /// source that won it. See `WakeSourceId`.
    pub(crate) last_park_bound_us: u64,
    pub(crate) last_park_source: WakeSourceId,
    /// phase-436 W2 — the park bound after rounding UP to what the platform's
    /// wake primitive can express. Kept beside the request rather than
    /// replacing it: reporting both is what makes the rounding auditable
    /// instead of silent (issue 1194).
    pub(crate) last_park_achieved_us: u64,
    /// phase-436 W6 — registered platform deadline sources, and how many are
    /// live. Inline table: no allocator on the targets this exists for.
    pub(crate) wake_sources: [Option<WakeSourceSlot>; MAX_WAKE_SOURCES],
    pub(crate) wake_source_count: usize,
    /// The single thing that actually blocks. Many sources say WHEN; one
    /// primitive does the waiting.
    pub(crate) park_primitive: Option<(ParkUntilFn, *mut core::ffi::c_void)>,
    /// phase-436 W7.b (issue 1242) — the finest park the INSTALLED primitive
    /// can actually express, in microseconds. `0` = none installed, fall back
    /// to the `wake_wait_ms` ABI floor.
    pub(crate) park_granularity_declared_us: u64,
    /// Wakes that were already past their nominal deadline, and wakes total.
    ///
    /// The maximum alone cannot distinguish one bad wake from a loop that is
    /// late every single cycle, and those are different faults: the first is
    /// a glitch, the second means the period cannot be met at all.
    pub(crate) late_wakes: u32,
    pub(crate) total_wakes: u32,
    /// phase-436 A2c -- late wakes whose lateness exceeds the granularity the
    /// measurement was made at (`release_jitter_granularity_us`). On a loop
    /// paced by a tick-granular park nearly every wake is late by a fraction
    /// of a tick, by design; `late_wakes` counts those, this does not.
    pub(crate) late_wakes_beyond_granule: u32,
    /// Issue 0514 / 1635 / phase-474 I1 -- what happens to a detected contract
    /// violation: the log switch, the drain-and-report hook, the image's sink,
    /// and the ring (CARVED, phase-409) with its total and dropped counters.
    /// See [`super::monitor::ViolationChannel`].
    pub(crate) violations: super::monitor::ViolationChannel<'s>,
    /// Issue 0790 — hooks that run BEFORE the session is closed, while every
    /// entity still works. The load-bearing half: a device releasing a bus or
    /// parking an actuator has to publish its final state / answer its last
    /// request from HERE, because after teardown it cannot.
    ///
    /// `[Option<_>; N]` rather than a `heapless::Vec`, deliberately: the handle
    /// a caller holds IS the slot index, so a removal must leave every other
    /// index where it was. A `Vec`'s `swap_remove` would silently re-point one
    /// live handle at a different callback, and its `remove` would re-point all
    /// of them. Clearing a slot to `None` also lets the next registration reuse
    /// it, which a fill cursor could not.
    pub(crate) pre_shutdown_hooks:
        [Option<super::types::ShutdownHook>; crate::config::MAX_SHUTDOWN_CBS],
    /// Issue 0790 — hooks that run AFTER the session is closed. rclcpp's
    /// `add_on_shutdown_callback` / `rclcpp::on_shutdown`. See
    /// [`Self::pre_shutdown_hooks`] for why this is an array.
    pub(crate) on_shutdown_hooks:
        [Option<super::types::ShutdownHook>; crate::config::MAX_SHUTDOWN_CBS],
}

impl<'s> Executor<'s> {
    /// phase-271 — assemble an executor over already-carved, caller-owned
    /// storage (`slices`, from [`super::storage::carve`]). Fills every
    /// non-storage field and reserves SC slot 0 for the default Fifo SC (carve
    /// left it `None`). The single builder shared by every constructor path.
    fn assemble(session: SessionStore, slices: super::storage::ExecutorSlices<'s>) -> Self {
        let super::storage::ExecutorSlices {
            arena,
            entries,
            sched_contexts,
            sched_context_bindings,
            sporadic_states,
            #[cfg(feature = "alloc")]
            sporadic_atomic_states,
            remaps,
            nodes,
            extra_sessions,
            extra_session_ids,
            node_sched_table,
            dispatch_slots,
            component_slots,
            active_groups,
            group_sched_table,
            monitor_violations,
            alive_slots,
            slot_tags,
            params: param_slots,
            param_home,
        } = slices;
        // phase-382 W3' — only an executor that can build a store keeps the
        // carved slots; without `param-services` the region (sized by the
        // build, not by a feature, so the layout never depends on one) is
        // simply never initialised. The services' home (issue 1812) is
        // zero-sized without the feature.
        #[cfg(not(feature = "param-store"))]
        let _ = (param_slots, param_home);
        // Slot 0 = the auto-created default Fifo SC (see field doc). carve
        // initialised the whole table to `None`; populate the reserved slot.
        if let Some(slot0) = sched_contexts.first_mut() {
            *slot0 = Some(super::sched_context::SchedContext::default());
        }
        // phase-412 -- stamp the self-report before anything can fail. `init`
        // is idempotent, so an image with two executors need not decide which
        // one owns the record, and `note_arena_capacity` records the slice this
        // executor was actually handed rather than the compiled constant: the
        // arena's placement is the caller's choice (issue 0900), so the two can
        // legitimately differ and the difference is worth seeing.
        crate::boot_report::init();
        crate::boot_report::note_arena_capacity(arena.len());
        crate::boot_report::checkpoint(crate::boot_report::Stage::ExecutorReady);
        Self {
            // `assemble` is reached from session-only entry points that have no
            // config, so 0 is the floor rather than a choice; `open_in` and any
            // binding that knows better overwrite it via `set_domain_id`.
            domain_id: 0,
            session,
            arena,
            arena_used: 0,
            arena_free_head: ARENA_FREE_NONE,
            pending_region: None,
            entries,
            sched_contexts,
            sched_context_bindings,
            sporadic_states,
            #[cfg(feature = "alloc")]
            sporadic_atomic_states,
            major_frame_us: 0,
            #[cfg(all(
                feature = "alloc",
                feature = "rmw-cffi",
                feature = "scheduler-os-priority"
            ))]
            os_priority_pool: super::os_priority::OsPriorityPool::new(),
            #[cfg(all(feature = "alloc", feature = "scheduler-os-priority"))]
            os_priority_apply_policy: None,
            trigger: Trigger::Any,
            semantics: ExecutorSemantics::RclcppExecutor,
            node_name: heapless::String::new(),
            active_groups,
            active_groups_filtering: false,
            nodes,
            node_sched_table,
            group_sched_table,
            remap_table: remaps,
            remap_len: 0,
            dispatch_slots,
            component_slots,
            extra_sessions,
            extra_session_ids,
            primary_rmw_name: heapless::String::new(),
            primary_locator: heapless::String::new(),
            namespace: {
                let mut ns = heapless::String::new();
                let _ = ns.push_str("/");
                ns
            },
            // Issue 1177 -- the only cfg the halt flag still needs. `HaltFlag`
            // is refcounted with an allocator and plain without one, and
            // nothing below this line can tell the difference.
            #[cfg(feature = "alloc")]
            halt_flag: portable_atomic_util::Arc::new(portable_atomic::AtomicBool::new(false)),
            #[cfg(not(feature = "alloc"))]
            halt_flag: portable_atomic::AtomicBool::new(false),
            spinning: portable_atomic::AtomicBool::new(false),
            #[cfg(feature = "alloc")]
            wake_flag: portable_atomic_util::Arc::new(portable_atomic::AtomicBool::new(false)),
            #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
            node_wake: super::node_wake::NodeWake::new().map(portable_atomic_util::Arc::new),
            #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
            wake_ctx: None,
            #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
            wake_cb_installed: false,
            #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
            has_cross_thread_waker: false,
            #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
            wake_membership: None,
            #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
            graph_change_target: None,
            #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
            has_async_wake: false,
            // Phase 141.A.3 — alloc-mode wake state init. Constructed
            // eagerly (NodeWake allocation) so the runtime cb can be
            // installed lazily on first session without a fallible
            // alloc inside spin_once. `None` when the platform
            // provider reports the primitive unavailable (matches
            // the std-RTOS path's `node_wake: Option<...>`).
            #[cfg(all(feature = "signal-fd-wake", target_os = "linux"))]
            signal_fd: None,
            #[cfg(feature = "param-store")]
            params: None,
            #[cfg(feature = "param-store")]
            param_slots,
            #[cfg(feature = "param-store")]
            param_home,
            #[cfg(feature = "param-store")]
            param_store_refused: false,
            #[cfg(feature = "param-store")]
            declared_params: nros_params::DeclaredParams::EMPTY,
            #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
            sim_time_source: None,
            #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
            sim_time_requested: false,
            #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
            sim_time_stated: false,
            #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
            sim_time_silence: crate::time_source::SilenceWatch::new(),
            #[cfg(feature = "lifecycle-services")]
            lifecycle: None,
            // Initialise the spin endpoint to construction time so the
            // very first `spin_once` credits time the caller spent
            // *before* it (e.g. setup, an explicit pre-spin sleep) just
            // like time spent between later calls.
            // One field, one seed now (phase-359 W10): the clock is absolute
            // on every flavour, so it is READ here rather than assumed to be
            // zero at construction. The std arm used to seed `Some(0)` because
            // its epoch WAS construction; with one provider that special case
            // is gone.
            last_spin_end_us: default_clock_us_fn().map(|clock| clock()),
            clock_us_fn: default_clock_us_fn(),
            consecutive_io_failures: 0,
            // RFC-0052 W3b.5 — a build with a wall clock gets one by default so
            // age monitors activate without extra wiring; a build with neither a
            // platform port nor a host gets `None`, and its board installs
            // `config.epoch_us` in `from_session_in`/`open`.
            //
            // phase-359 W10 — the cfg pair that used to be here moved into
            // `default_epoch_us_fn`, beside the `default_clock_us_fn` it
            // mirrors. (The old comment pointed at "the `not(std)` blocks
            // above" for the board install; those blocks are no longer
            // cfg-gated — the config override applies on every flavour now.)
            epoch_us_fn: super::types::default_epoch_us_fn(),
            component_frame: None,
            monitor_table: &[],
            monitor_states: [super::monitor::MonitorState::default(); super::monitor::MAX_MONITORS],
            age_table: &[],
            age_states: [super::monitor::AgeState::default(); super::monitor::MAX_AGE_MONITORS],
            hazard_table: &[],
            fault_fn: None,
            reaction_hook: None,
            spin_quantization_checked: false,
            spin_quantization_us: 0,
            max_release_jitter_us: 0,
            last_spin_entry_us: None,
            grid: ReleaseGrid {
                period_us: 0,
                next_us: 0,
                skipped: 0,
            },
            jitter_reported_us: 0,
            min_stack_headroom_bytes: 0,
            stack_headroom_reported: usize::MAX,
            stack_headroom_blind: false,
            stack_headroom_last_check_us: None,
            stack_headroom_spins_since_check: 0,
            stack_headroom_checks: 0,
            spin_nominal_us: 0,
            spin_nominal_declared_us: 0,
            spin_nominal_wait_paced: false,
            last_park_bound_us: 0,
            last_park_source: WakeSourceId::CallerBudget,
            last_park_achieved_us: 0,
            wake_sources: [None; MAX_WAKE_SOURCES],
            wake_source_count: 0,
            park_primitive: None,
            park_granularity_declared_us: 0,
            late_wakes: 0,
            total_wakes: 0,
            late_wakes_beyond_granule: 0,
            violations: super::monitor::ViolationChannel::new(monitor_violations),
            alive_slots,
            slot_tags,
            // Issue 0790 — both phase tables start empty. An image that
            // registers nothing pays these `None`s and a two-slot scan at
            // teardown, and nothing else.
            pre_shutdown_hooks: [None; crate::config::MAX_SHUTDOWN_CBS],
            on_shutdown_hooks: [None; crate::config::MAX_SHUTDOWN_CBS],
        }
    }

    /// Create an owning executor over caller-supplied `backing`, sized by
    /// `sizing`. The core, non-generic, per-entry entry point (the `alloc`
    /// [`from_session`](Self::from_session) convenience leaks a default backing
    /// and calls this; the macro / C FFI pass an entry-sized backing).
    ///
    /// # Safety
    /// `backing` must be ≥ `sizing.u64_len()` words, stay alive for `'s`, and
    /// not be otherwise accessed while the executor lives (it aliases it).
    /// `sizing.cbs` must be ≤ 64 (the `u64` ready-set bitmask ceiling).
    pub unsafe fn from_session_in(
        session: session::ConcreteSession,
        backing: &'s mut [MaybeUninit<u64>],
        sizing: super::storage::ExecutorSizing,
    ) -> Self {
        let slices = unsafe { super::storage::carve(backing, sizing) };
        Self::assemble(SessionStore::Owned(session), slices)
    }

    /// Create a borrowing executor over caller-supplied `backing`, sized by
    /// `sizing`. Counterpart to [`from_session_in`](Self::from_session_in) for
    /// the per-tier / C model (the session is borrowed, not owned).
    ///
    /// # Safety
    /// - `session_ptr` must point to a valid session that outlives the executor
    ///   and is not moved/dropped while it exists.
    /// - `backing` obligations as in [`from_session_in`](Self::from_session_in).
    pub unsafe fn from_session_ptr_in(
        session_ptr: *mut session::ConcreteSession,
        backing: &'s mut [MaybeUninit<u64>],
        sizing: super::storage::ExecutorSizing,
    ) -> Self {
        let slices = unsafe { super::storage::carve(backing, sizing) };
        Self::assemble(SessionStore::Borrowed(session_ptr), slices)
    }
}

impl Executor<'static> {
    /// Create an executor from an already-opened session, using the build-time
    /// default sizing (`MAX_CBS`/`MAX_SC`/`ARENA_SIZE`). Convenience for
    /// std/alloc callers that don't size per-entry: it leaks a default-sized
    /// backing (executor-lifetime, one-time) and calls
    /// [`from_session_in`](Self::from_session_in). Per-entry sizing goes through
    /// the macro / `open_in` instead.
    #[cfg(feature = "alloc")]
    pub fn from_session(session: session::ConcreteSession) -> Self {
        let sizing = super::storage::ExecutorSizing::DEFAULT;
        // SAFETY: the backing is exactly `sizing.u64_len()` words,
        // `'static`, and uniquely owned by this executor.
        unsafe { Self::from_session_in(session, default_backing(sizing), sizing) }
    }

    /// [`from_session`](Self::from_session) with an [`ExecutorConfig`], so a
    /// caller that brings its own session can also bring its own clock.
    ///
    /// issue 0709 / issue 0687 — `from_session` takes no config, and that is
    /// the path the no-port population uses: it accepts any `Session`, so a
    /// consumer with a non-cffi backend reaches the executor through it and had
    /// NO way to install `clock_us`. phase-359 W10 argued the `std`-without-a-
    /// port clock fallbacks could go because "a caller with a clock installs it
    /// through `ExecutorConfig::clock_us`" — true for `open`, false here, which
    /// is half of why that deletion was reverted.
    ///
    /// Only the timing sources are read from `config`; identity (locator,
    /// domain, names) belongs to the session the caller already opened. As in
    /// [`open_in`](Self::open_in), a `None` field does NOT clobber the
    /// platform default — it means "not specified" (the bug issue 0671
    /// records).
    #[cfg(feature = "alloc")]
    pub fn from_session_with(
        session: session::ConcreteSession,
        config: &super::types::ExecutorConfig<'_>,
    ) -> Self {
        let mut executor = Self::from_session(session);
        if let Some(clock) = config.clock_us {
            executor.clock_us_fn = Some(clock);
            executor.last_spin_end_us = Some(clock());
        }
        if let Some(epoch) = config.epoch_us {
            executor.epoch_us_fn = Some(epoch);
        }
        executor
    }

    /// Create an executor from a borrowed session pointer, default-sized. The
    /// `alloc` convenience wrapper over
    /// [`from_session_ptr_in`](Self::from_session_ptr_in) — leaks a default
    /// backing so existing callers keep the zero-storage-arg signature.
    ///
    /// # Safety
    /// - `session_ptr` must point to a valid, initialized session that lives at
    ///   least as long as this executor.
    /// - The caller must not move or drop the session while the executor exists.
    #[cfg(feature = "alloc")]
    pub unsafe fn from_session_ptr(session_ptr: *mut session::ConcreteSession) -> Self {
        let sizing = super::storage::ExecutorSizing::DEFAULT;
        // SAFETY: the backing as in `from_session`; session_ptr contract
        // forwarded to `from_session_ptr_in`.
        unsafe { Self::from_session_ptr_in(session_ptr, default_backing(sizing), sizing) }
    }
}

/// phase-474 I11 -- the release grid of a `spin_once(timeout)` loop with no
/// declared cadence: the period it was built for (`0` = no grid yet), the next
/// scheduled release, and the releases skipped because the loop came back a
/// whole period or more after they were due (the timer `Skip` policy: the
/// latest due point is served once, the older ones are dropped and counted,
/// never released in a burst). The park is bounded by `next_us`, so a loop is
/// released on `anchor + k * period` instead of `period` after its previous
/// spin ended. Scales with no knob; named in the header-size budget.
#[derive(Clone, Copy, Debug, Default)]
pub(crate) struct ReleaseGrid {
    pub(crate) period_us: u64,
    pub(crate) next_us: u64,
    pub(crate) skipped: u32,
}

/// The two cadences a `period_us` timer alternates between under a `spin_us`
/// spin period, or `None` when the audit (issue #515) has nothing to say.
///
/// Split out of `audit_spin_quantization` so the decision can be asserted:
/// the audit only LOGS, so a regression in what it decides is otherwise
/// invisible to a test.
///
/// `None` for a period of zero, for a period that divides the spin period —
/// and, since issue 1321, for a timer whose activations are NOT paced by the
/// spin period at all. The warning's arithmetic is wall microseconds on both
/// sides; a `Ros` timer's activations are quantised by the `/clock` STEP, so
/// the sentence it would print ("activations will alternate between X and Y
/// us") is about nothing.
pub(crate) fn spin_quantization_span(
    clock_source: TimerClockSource,
    period_us: u64,
    spin_us: u64,
) -> Option<(u64, u64)> {
    if spin_us == 0 || period_us == 0 || period_us.is_multiple_of(spin_us) {
        return None;
    }
    if !clock_source.remaining_is_wall_time() {
        return None;
    }
    let early_us = (period_us / spin_us) * spin_us;
    Some((early_us, early_us.saturating_add(spin_us)))
}

/// phase-436 — which deadline source bounded the last park.
///
/// Attribution is what turns "why did we wake" from a guess into a number.
/// Recording it costs one byte per spin and is the difference between a
/// schedulability argument you can audit and one you have to trust.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum WakeSourceId {
    /// The `spin_once` caller's own timeout — always a member of the source
    /// set, which is why the park is never unbounded.
    CallerBudget,
    /// A registered timer's next expiry (issue 1192).
    Timer,
    /// The backend's next internal event (lease keepalive, heartbeat,
    /// ACK-NACK). Folded into the same `min` as everything else rather than
    /// capping the budget separately upstream, so one rule decides the park
    /// and one attribution explains it.
    Session,
    /// A source the PLATFORM registered: a `k_poll` event set, an `epoll`
    /// group, a FreeRTOS queue set, a ThreadX event-flags group, or a
    /// bare-metal device ISR. The core never names an RTOS; it only asks each
    /// registered source when it will next need the executor.
    Platform(u8),
    /// phase-503 — the earliest deadline of a pending supervised route: the
    /// park ends there so `route-deadline-runtime` judges it on time.
    RouteDeadline,
}

/// How many platform sources one executor can carry. A plain const, not a
/// sizing knob: the table is inline, so no allocator is required on the no_std
/// targets this seam mainly exists for.
pub const MAX_WAKE_SOURCES: usize = 8;

/// phase-436 (RFC-0106 D5) — the slice a poll-only backend's transport wait is
/// cut into while a guard condition can signal the executor from another
/// thread: the worst-case latency of such a trigger, and the period at which
/// an otherwise idle executor re-enters the backend's `recv`.
#[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
pub(crate) const POLL_ONLY_WAKE_SLICE_MS: i32 = 10;

/// When this source will next need the executor, in the executor's clock,
/// as microseconds FROM NOW.
///
/// `u64::MAX` means "nothing pending" — the source does not shorten the park.
/// That is how an ASYNC source spells itself: a socket or a DDS listener
/// contributes no deadline and instead breaks the park by signalling the wake
/// primitive, so async and deadline sources compose without a second
/// mechanism.
pub type NextDeadlineFn = unsafe extern "C" fn(ctx: *mut core::ffi::c_void) -> u64;

/// Park until `deadline_us` from now, or until something signals, whichever
/// comes first.
///
/// Returns `0` when woken by an event, `1` when the deadline expired, and a
/// negative value when this build cannot park at all.
///
/// A DEADLINE, not a duration, and that distinction is what makes bare metal
/// work: `nros-baremetal-common`'s own note says `wfi` with no pending
/// interrupt deadlocks, so a board must arm a timer compare BEFORE waiting.
/// A `sleep(duration)` seam cannot express that — the sleeper does not know
/// whether anyone armed an interrupt. `park_until(deadline)` does, because the
/// deadline is exactly what the compare is armed to.
pub type ParkUntilFn = unsafe extern "C" fn(ctx: *mut core::ffi::c_void, deadline_us: u64) -> i8;

/// A registered deadline contributor.
#[derive(Clone, Copy)]
pub(crate) struct WakeSourceSlot {
    pub(crate) next: NextDeadlineFn,
    pub(crate) ctx: *mut core::ffi::c_void,
}

impl<'s> Executor<'s> {
    /// Phase 228.B (RFC-0015) — construct a tier task's executor that **shares**
    /// a session opened once by the orchestration `main()`.
    ///
    /// In the per-tier execution model `main()` opens one RMW session, then
    /// spawns one RTOS task per priority tier; each task calls this to get an
    /// [`Executor`] over the *same* session (the `Borrowed` session store — this
    /// executor neither owns nor closes it), registers its tier's callback
    /// groups, and spins. Thin alias over [`Executor::from_session_ptr`].
    ///
    /// # Safety
    /// `session` must outlive every executor/task built from it (the
    /// orchestration `main()` holds it and never returns / WFIs), and must not
    /// be mutated except through these executors' spin calls.
    #[cfg(feature = "alloc")]
    pub unsafe fn open_with_session(session: *mut session::ConcreteSession) -> Executor<'static> {
        #[allow(unused_mut)]
        let mut exec = unsafe { Executor::<'static>::from_session_ptr(session) };
        // phase-436 — join the session's wake fan-out, so this tier is woken
        // by its arrivals instead of sleeping out its whole bound.
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        exec.install_wake_signal_on_primary();
        exec
    }

    /// phase-271 — per-tier borrowed-session constructor over caller-supplied,
    /// per-tier-sized `backing`. The sized counterpart to
    /// [`open_with_session`](Self::open_with_session): each RTOS tier task owns
    /// its own backing so tiers size independently.
    ///
    /// # Safety
    /// `session` obligations as in [`open_with_session`](Self::open_with_session);
    /// `backing`/`sizing` as in [`from_session_ptr_in`](Self::from_session_ptr_in).
    pub unsafe fn open_with_session_in(
        session: *mut session::ConcreteSession,
        backing: &'s mut [MaybeUninit<u64>],
        sizing: super::storage::ExecutorSizing,
    ) -> Self {
        #[allow(unused_mut)]
        let mut exec = unsafe { Self::from_session_ptr_in(session, backing, sizing) };
        // phase-436 — as `open_with_session`.
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        exec.install_wake_signal_on_primary();
        exec
    }

    /// Raw pointer to this executor's RMW session, for the per-tier model:
    /// the boot task opens the one session via [`Executor::open`] (the RMW
    /// session is a process-wide singleton — opening twice fails), then hands
    /// this pointer to each spawned tier task's
    /// [`Executor::open_with_session`]. The boot task's executor owns the
    /// session and outlives every borrower, so the pointer stays valid for the
    /// program's life. Works for both `Owned` and `Borrowed` stores.
    ///
    /// # Safety
    /// The returned pointer aliases `self.session`. Callers must keep `self`
    /// alive (not moved/dropped) for as long as any tier executor uses the
    /// pointer, and must only touch the session through executor spin calls
    /// (the RMW backend serializes concurrent access through its own locks).
    pub fn session_ptr(&mut self) -> *mut session::ConcreteSession {
        let ptr = &mut *self.session as *mut session::ConcreteSession;
        // phase-436 — the owner of an OWNED session claimed its wake fan-out
        // while this executor value could still move (inside `open*`). The
        // address handed out here is the one every tier is opened over, so
        // the entry is keyed by it from now on.
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        if let (SessionStore::Owned(_), Some(m)) = (&self.session, self.wake_membership) {
            m.fanout().rekey(ptr as *mut core::ffi::c_void);
        }
        ptr
    }

    /// Opaque, `Send` form of [`session_ptr`](Self::session_ptr) — the per-tier
    /// model hands this to each spawned tier task (it can cross the RTOS task /
    /// thread boundary, which a bare `*mut` cannot). See [`SessionHandle`].
    ///
    /// # Safety
    /// Same contract as [`session_ptr`](Self::session_ptr): `self` (the session
    /// owner) must outlive every executor built from the handle.
    pub fn session_handle(&mut self) -> SessionHandle {
        SessionHandle(self.session_ptr())
    }

    /// Open an [`Executor`] over the session a [`SessionHandle`] refers to (the
    /// `Borrowed` store — neither owns nor closes it). The tier-task counterpart
    /// to [`session_handle`](Self::session_handle).
    ///
    /// # Safety
    /// The handle's session must still be alive (its owning executor not moved
    /// or dropped); access only through executor spin calls.
    #[cfg(feature = "alloc")]
    pub unsafe fn open_with_session_handle(handle: SessionHandle) -> Executor<'static> {
        unsafe { Executor::<'static>::open_with_session(handle.0) }
    }

    /// phase-271 — sized counterpart to
    /// [`open_with_session_handle`](Self::open_with_session_handle) (per-tier
    /// backing).
    ///
    /// # Safety
    /// As [`open_with_session_handle`](Self::open_with_session_handle) +
    /// [`from_session_ptr_in`](Self::from_session_ptr_in).
    pub unsafe fn open_with_session_handle_in(
        handle: SessionHandle,
        backing: &'s mut [MaybeUninit<u64>],
        sizing: super::storage::ExecutorSizing,
    ) -> Self {
        unsafe { Self::open_with_session_in(handle.0, backing, sizing) }
    }

    /// issue 1571 — a SPAWNED tier's executor over its slot of the entry's
    /// [`TierExecutorBacking`](super::TierExecutorBacking) — the road every
    /// board's `run_tiers` takes for each tier but the boot one.
    ///
    /// The slot's TYPE is the size: it is `ExecutorSizing::DEFAULT.u64_len()`
    /// words and this opens with `ExecutorSizing::DEFAULT`, so the pairing is
    /// exact by construction and lives here, once, rather than at five boards.
    /// [`open_with_session`](Self::open_with_session) is the heap twin this
    /// replaced on those roads.
    ///
    /// # Safety
    /// `session` obligations as in [`open_with_session`](Self::open_with_session).
    #[cfg(feature = "alloc")]
    pub unsafe fn open_with_session_slot(
        session: *mut session::ConcreteSession,
        slot: &'s mut super::TierExecutorBackingSlot,
    ) -> Self {
        unsafe {
            Self::open_with_session_in(
                session,
                &mut slot[..],
                super::storage::ExecutorSizing::DEFAULT,
            )
        }
    }

    /// issue 1571 — [`open_with_session_slot`](Self::open_with_session_slot)
    /// over a [`SessionHandle`], for the boards whose tier tasks carry one.
    ///
    /// # Safety
    /// As [`open_with_session_handle`](Self::open_with_session_handle).
    #[cfg(feature = "alloc")]
    pub unsafe fn open_with_session_handle_slot(
        handle: SessionHandle,
        slot: &'s mut super::TierExecutorBackingSlot,
    ) -> Self {
        unsafe { Self::open_with_session_slot(handle.0, slot) }
    }

    /// Phase 228.C — set this tier executor's active callback-group filter. The
    /// generated per-tier task calls this before registering nodes; afterwards
    /// only callbacks whose `.callback_group()` is in `groups` register here.
    /// An empty slice (or never calling it) leaves the wildcard — register all
    /// callbacks (the single-tier degenerate case + today's behaviour).
    pub fn set_active_groups(
        &mut self,
        groups: &[(&str, &str, &str)],
    ) -> Result<(), super::types::BindError> {
        // phase-409 — the table is CARVED and reused, so clear before refilling;
        // the old `Option<heapless::Vec>` got a fresh empty vector each call.
        self.active_groups.clear();
        if groups.is_empty() {
            self.active_groups_filtering = false;
            return Ok(());
        }
        for (name, ns, group) in groups {
            // issue 1172 — this used to be `if s.push_str(g).is_ok()`, which
            // DROPPED an oversized group name and left the tier filtering on a
            // set that silently lacked it. It fails closed (the entity is never
            // created), so the symptom is a missing entity with nothing to read
            // that says why. Same contract as `declare_remap` below: too long,
            // or table full, is the caller's error.
            let key = super::storage::node_identity_hash(name, ns);
            let mut s = heapless::String::new();
            let why = if s.push_str(group).is_err() {
                Some(super::types::BindError::NameTooLong)
            } else if self.active_groups.push((key, s)).is_err() {
                Some(super::types::BindError::TableFull)
            } else {
                None
            };
            if let Some(why) = why {
                // FAIL CLOSED, and say so. Returning here with a PARTIAL table
                // would leave the tier filtering on a subset — the same silent
                // narrowing, one step later. An empty table with filtering ON
                // accepts NOTHING (`group_filter_accepts` matches on an empty
                // slice), so the tier registers no entities at all: visible in
                // behaviour, where a missing entry is not. The `Err` is for the
                // caller that can report it; the state is safe for the one that
                // cannot.
                self.active_groups.clear();
                self.active_groups_filtering = true;
                return Err(why);
            }
        }
        self.active_groups_filtering = true;
        Ok(())
    }

    /// The current callback-group filter, or `None` for the wildcard.
    fn active_group_filter(&self) -> Option<&[super::storage::ActiveGroup]> {
        self.active_groups_filtering
            .then(|| self.active_groups.as_slice())
    }

    /// Phase 228.C — whether a callback in `group` should register in this
    /// executor under the current filter. The wildcard accepts everything.
    pub fn group_active(&self, node_name: &str, node_namespace: &str, group: &str) -> bool {
        group_filter_accepts(
            self.active_group_filter(),
            super::storage::node_identity_hash(node_name, node_namespace),
            group,
        )
    }

    /// Set the node name and namespace used for liveliness tokens.
    ///
    /// Called by `open()` to propagate config values. When `register_subscription`
    /// or `register_service` creates entities, these values are attached to the
    /// Phase 156 — record the primary session's backend identity
    /// (rmw name + locator) so `NodeBuilder::resolve_session_slot`
    /// can detect when a `.rmw(name)` matches the primary instead
    /// of opening a SECOND backend session against the same
    /// singleton (zenoh-pico's `g_session` is process-wide;
    /// opening twice fails). `Executor::open*` calls this
    /// automatically; the C surface (`rclc_executor_init`) calls
    /// it manually because it constructs via `from_session_ptr`
    /// which doesn't know the open metadata. Empty strings = "no
    /// primary identity tracked"; the cache check degrades to
    /// always-miss.
    pub fn set_primary_identity(&mut self, rmw_name: &str, locator: &str) {
        self.primary_rmw_name.clear();
        let _ = self.primary_rmw_name.push_str(rmw_name);
        self.primary_locator.clear();
        let _ = self.primary_locator.push_str(locator);
    }

    /// `TopicInfo`/`ServiceInfo` so the zenoh backend can declare liveliness.
    /// Issue 0656 — set the ROS domain for entities this executor declares.
    ///
    /// For bindings that build an executor from an existing session
    /// (`from_session_ptr_in`), where no `ExecutorConfig` is available and the
    /// domain would otherwise stay at its 0 floor.
    pub fn set_domain_id(&mut self, domain_id: u32) {
        self.domain_id = domain_id;
    }

    /// The ROS domain this executor declares entities on.
    pub fn domain_id(&self) -> u32 {
        self.domain_id
    }

    pub fn set_node_identity(&mut self, node_name: &str, namespace: &str) {
        self.node_name.clear();
        let _ = self.node_name.push_str(node_name);
        if !namespace.is_empty() {
            self.namespace.clear();
            let _ = self.namespace.push_str(namespace);
        }
    }

    // =========================================================================
    // Phase 305 W3 (issue 0255) — per-node launch remap table
    // =========================================================================

    /// Record one launch `<remap from= to=/>` rule for the node identified by
    /// `(node_name, namespace)`. Rules are matched in declaration order (first
    /// wins) by [`Self::resolve_entity_name_for`]. Errors when a string
    /// overflows its slot or the table is at `MAX_REMAPS` — callers surface
    /// this rather than silently dropping a routing rule.
    ///
    /// **This declares an AUTHORITATIVE rule.** Declaration order settles
    /// which of two launch rules for one name wins; it is not how an argv rule
    /// is ranked against a launch rule. The `--ros-args` rules share this table
    /// but are tagged as the fallback tier, and resolution reads both tiers
    /// through [`crate::names::resolve_name_layered`] — so an argv rule
    /// installed BEFORE a launch rule still loses to it.
    #[allow(clippy::result_unit_err)]
    pub fn declare_remap(
        &mut self,
        node_name: &str,
        namespace: &str,
        from: &str,
        to: &str,
    ) -> Result<(), ()> {
        let mut rule = RemapRule {
            node_name: heapless::String::new(),
            namespace: heapless::String::new(),
            from: heapless::String::new(),
            to: heapless::String::new(),
            tier: RemapTier::Launch,
        };
        rule.node_name.push_str(node_name)?;
        let ns = if namespace.is_empty() { "/" } else { namespace };
        rule.namespace.push_str(ns)?;
        rule.from.push_str(from)?;
        rule.to.push_str(to)?;
        // Same contract as the `heapless::Vec::push` this replaces: full table
        // is an error the caller surfaces, never a silently dropped rule.
        let slot = self.remap_table.get_mut(self.remap_len).ok_or(())?;
        *slot = Some(rule);
        self.remap_len += 1;
        Ok(())
    }

    /// Resolve a source-level entity name for the node identified by
    /// `(node_name, namespace)`: ROS 2 name expansion (`~`/relative → FQN)
    /// plus this node's declared remap rules (exact-FQN match, first rule
    /// wins). Nodes with no rules still get expansion. Errors on an
    /// unexpandable name (see `crate::names::expand_name`).
    ///
    /// Two tiers, through [`crate::names::resolve_name_layered`]: the rules
    /// [`Self::declare_remap`] recorded for this node are AUTHORITATIVE (the
    /// generated entry declares the launch projection there), and the
    /// `--ros-args` rules `crate::ros_args::install_argv_remaps` put in the
    /// same table are the FALLBACK, consulted only when no launch rule
    /// matched. rcl does the same with its local and global arguments
    /// (`rcl_remap_topic_name`, Humble `rcl/remap.h`).
    #[allow(clippy::result_unit_err)]
    pub fn resolve_entity_name_for(
        &self,
        node_name: &str,
        namespace: &str,
        source: &str,
    ) -> Result<crate::names::ResolvedName, ()> {
        let ns = if namespace.is_empty() { "/" } else { namespace };
        let table = &self.remap_table[..self.remap_len];
        crate::names::resolve_name_layered(
            source,
            node_name,
            ns,
            tier_rules(table, RemapTier::Launch, node_name, ns),
            tier_rules(table, RemapTier::Argv, node_name, ns),
        )
    }

    /// [`Self::resolve_entity_name_for`] against the executor's CURRENT node
    /// identity (`set_node_identity`) — the nros-c registration sites set that
    /// identity per node immediately before registering each entity.
    #[allow(clippy::result_unit_err)]
    pub fn resolve_entity_name(&self, source: &str) -> Result<crate::names::ResolvedName, ()> {
        self.resolve_entity_name_for(self.node_name.as_str(), self.namespace.as_str(), source)
    }

    // =========================================================================
    // Phase 272 (RFC-0047) — node-name → sched-context table
    // =========================================================================

    /// Seed a config-resolved tier binding by `(name, namespace)` before the
    /// node is built. `NodeBuilder::build` consults this table when no
    /// explicit `.sched()` override is given — the table entry then wins over
    /// the `SchedContextId(0)` default (precedence: explicit > table > 0).
    ///
    /// Call BEFORE `node_builder(name).build()`. An existing entry for the
    /// same `(name, namespace)` key is overwritten (last-write wins). Overflow
    /// past `MAX_NODES` is an `Err`, never a dropped binding — issue 1172. An
    /// empty `namespace` is normalised
    /// to `"/"` to match what `NodeBuilder::build` computes for a root-NS node.
    pub fn bind_node_name_sched(
        &mut self,
        name: &str,
        namespace: &str,
        sc: super::sched_context::SchedContextId,
    ) -> Result<(), super::types::BindError> {
        let norm_ns = if namespace.is_empty() { "/" } else { namespace };
        // Overwrite if there is already an entry for this (name, ns) pair.
        for entry in self.node_sched_table.iter_mut() {
            if entry.0.as_str() == name && entry.1.as_str() == norm_ns {
                entry.2 = sc;
                return Ok(());
            }
        }
        // New entry. Too long, or table full, is an ERROR the caller surfaces
        // — never a dropped binding. A binding that vanishes leaves the node on
        // the wrong sched context with nothing to read that says so.
        let mut name_s = heapless::String::<64>::new();
        let mut ns_s = heapless::String::<64>::new();
        name_s
            .push_str(name)
            .map_err(|_| super::types::BindError::NameTooLong)?;
        ns_s.push_str(norm_ns)
            .map_err(|_| super::types::BindError::NameTooLong)?;
        self.node_sched_table
            .push((name_s, ns_s, sc))
            .map_err(|_| super::types::BindError::TableFull)?;
        Ok(())
    }

    /// Look up the seeded sched-context for `(name, namespace)`. Returns
    /// `None` when the table has no entry for this pair (unseed → default 0).
    /// `pub(super)` — visible only within the `executor` module (sibling
    /// `node_record` calls it from `NodeBuilder::build`).
    pub(super) fn lookup_node_sched(
        &self,
        name: &str,
        namespace: &str,
    ) -> Option<super::sched_context::SchedContextId> {
        for entry in self.node_sched_table.iter() {
            if entry.0.as_str() == name && entry.1.as_str() == namespace {
                return Some(entry.2);
            }
        }
        None
    }

    // =========================================================================
    // Phase 273 (RFC-0047) — per-callback-group → sched-context table
    // =========================================================================

    /// Seed a config-resolved tier binding by `(name, namespace, group)` before
    /// entities are registered. `apply_node_default_sched` consults this table
    /// first (group table > node default > `SchedContextId(0)`).
    ///
    /// Call BEFORE entity creation. An existing entry for the same
    /// `(name, namespace, group)` key is overwritten (last-write wins). Overflow
    /// past `MAX_CBS` is an `Err`, never a dropped binding — issue 1172. An
    /// empty `namespace` is normalised to
    /// `"/"` to match `NodeBuilder::build`. Mirror of `bind_node_name_sched`.
    pub fn bind_group_sched(
        &mut self,
        name: &str,
        namespace: &str,
        group: &str,
        sc: super::sched_context::SchedContextId,
    ) -> Result<(), super::types::BindError> {
        let norm_ns = if namespace.is_empty() { "/" } else { namespace };
        // Overwrite if there is already an entry for this (name, ns, group).
        for entry in self.group_sched_table.iter_mut() {
            if entry.0.as_str() == name && entry.1.as_str() == norm_ns && entry.2.as_str() == group
            {
                entry.3 = sc;
                return Ok(());
            }
        }
        // Same contract as the two above.
        let mut name_s = heapless::String::<64>::new();
        let mut ns_s = heapless::String::<64>::new();
        let mut grp_s = heapless::String::<32>::new();
        name_s
            .push_str(name)
            .map_err(|_| super::types::BindError::NameTooLong)?;
        ns_s.push_str(norm_ns)
            .map_err(|_| super::types::BindError::NameTooLong)?;
        grp_s
            .push_str(group)
            .map_err(|_| super::types::BindError::NameTooLong)?;
        self.group_sched_table
            .push((name_s, ns_s, grp_s, sc))
            .map_err(|_| super::types::BindError::TableFull)?;
        Ok(())
    }

    /// Look up the seeded sched-context for `(name, namespace, group)`. Returns
    /// `None` when the table has no entry for this triple.
    fn lookup_group_sched(
        &self,
        name: &str,
        namespace: &str,
        group: &str,
    ) -> Option<super::sched_context::SchedContextId> {
        for entry in self.group_sched_table.iter() {
            if entry.0.as_str() == name
                && entry.1.as_str() == namespace
                && entry.2.as_str() == group
            {
                return Some(entry.3);
            }
        }
        None
    }

    // =========================================================================
    // Phase 110.B — SchedContext API
    // =========================================================================

    /// Identifier of the auto-created default `Fifo`-class scheduling
    /// context. Every callback registered without an explicit
    /// [`Self::bind_handle_to_sched_context`] binds to this SC.
    pub fn default_sched_context_id(&self) -> super::sched_context::SchedContextId {
        super::sched_context::SchedContextId(0)
    }

    /// Register a new scheduling context. Returns a [`SchedContextId`](crate::executor::sched_context::SchedContextId)
    /// callers pass to [`Self::bind_handle_to_sched_context`] to attach
    /// callbacks. Phase 110.B.
    pub fn create_sched_context(
        &mut self,
        sc: super::sched_context::SchedContext,
    ) -> Result<super::sched_context::SchedContextId, NodeError> {
        // Slot 0 is reserved for the default Fifo SC; search 1..MAX_SC.
        for (i, slot) in self.sched_contexts.iter_mut().enumerate().skip(1) {
            if slot.is_none() {
                *slot = Some(sc);
                // Phase 110.E — Sporadic-class SCs get a sibling
                // `SporadicState` entry that the spin_once dispatch
                // path consults each cycle to refill the budget at
                // period boundaries and skip dispatch when budget
                // is exhausted.
                if matches!(sc.class, super::sched_context::SchedClass::Sporadic) {
                    let budget = sc.budget_us.get().map(|nz| nz.get()).unwrap_or(u32::MAX);
                    let period = sc.period_us.get().map(|nz| nz.get()).unwrap_or(u32::MAX);
                    self.sporadic_states[i] =
                        Some(super::sched_context::SporadicState::new(budget, period));
                }
                return Ok(super::sched_context::SchedContextId(i as u8));
            }
        }
        Err(NodeError::NoSchedContextSlot)
    }

    /// RFC-0052 W3b.2 — wall-clock µs since the UNIX epoch, when this
    /// target has an epoch source (config `epoch_us`, defaulted from
    /// `SystemTime` on hosted configs). `None` = no wall clock; age
    /// monitors must not have been baked (the emitter refuses).
    pub fn epoch_now_us(&self) -> Option<u64> {
        self.epoch_us_fn.map(|f| f())
    }

    /// RFC-0052 W3b.4 — install the baked contract-monitor table. Call
    /// BEFORE entity creation so `create_publisher` can attach each
    /// contracted endpoint's counter cell. Mirrors `set_qos_overrides`:
    /// `&'static`, codegen-baked, empty by default.
    ///
    /// phase-496 W1 -- the executor watches at most
    /// [`MAX_MONITORS`](super::monitor::MAX_MONITORS) rows
    /// (`NROS_EXECUTOR_MAX_MONITORS`). A generated entry cannot reach this with
    /// more: its table carries a compile-time assertion that names the knob,
    /// and the C++ installer refuses at runtime. A hand-written longer table is
    /// a debug-build panic naming the knob, because in release the spin loop
    /// would inspect only the first `MAX_MONITORS` and leave the rest silently
    /// unwatched.
    pub fn set_monitor_table(&mut self, table: &'static [super::monitor::MonitorSpec]) {
        if let Err(full) = super::monitor::check_table_capacity(table.len(), 0)
            && cfg!(debug_assertions)
        {
            panic!("set_monitor_table: {full}");
        }
        self.monitor_table = table;
    }

    /// phase-496 W1 -- install BOTH baked monitor tables, or neither.
    ///
    /// The refusing installer: a table longer than this executor watches
    /// (`MAX_MONITORS` / `MAX_AGE_MONITORS`) is `Err`, and its `Display` names
    /// the knob to raise, before anything is installed. Nothing is truncated:
    /// the spin loop inspects only the first `MAX_*` specs, so accepting a
    /// longer table would boot with its tail silently unwatched. The C ABI's
    /// `nros_cpp_install_monitors` refuses on the same check.
    pub fn try_set_monitor_tables(
        &mut self,
        table: &'static [super::monitor::MonitorSpec],
        ages: &'static [super::monitor::AgeMonitorSpec],
    ) -> Result<(), super::monitor::MonitorTableFull> {
        super::monitor::check_table_capacity(table.len(), ages.len())?;
        self.monitor_table = table;
        self.age_table = ages;
        Ok(())
    }

    /// The installed monitor table (empty unless the entry set one).
    #[must_use]
    pub fn monitor_table(&self) -> &'static [super::monitor::MonitorSpec] {
        self.monitor_table
    }

    /// Issue 1676 — the counter cell a publisher on `topic_name` bumps, by
    /// exact topic match against the installed table (`None` = uncontracted).
    pub(crate) fn publisher_monitor_cell(
        &self,
        topic_name: &str,
    ) -> Option<&'static super::monitor::PubMonitorCell> {
        self.monitor_table
            .iter()
            .find(|m| m.topic == topic_name)
            .map(|m| m.cell)
    }

    /// W3b.5 — install the baked subscriber age-contract table. Call
    /// BEFORE entity creation so `create_subscription` can attach each
    /// contracted endpoint's age cell (needs an epoch source — see
    /// `ExecutorConfig::epoch_us`; without one the take path records
    /// nothing and age monitors stay silent).
    ///
    /// phase-496 W1 -- at most
    /// [`MAX_AGE_MONITORS`](super::monitor::MAX_AGE_MONITORS) rows
    /// (`NROS_EXECUTOR_MAX_AGE_MONITORS`), on the same terms as
    /// [`Self::set_monitor_table`].
    pub fn set_age_table(&mut self, table: &'static [super::monitor::AgeMonitorSpec]) {
        if let Err(full) = super::monitor::check_table_capacity(0, table.len())
            && cfg!(debug_assertions)
        {
            panic!("set_age_table: {full}");
        }
        self.age_table = table;
    }

    /// The installed age table (empty unless the entry set one).
    #[must_use]
    pub fn age_table(&self) -> &'static [super::monitor::AgeMonitorSpec] {
        self.age_table
    }

    /// phase-462 W3b — install the baked hazard table. Each row's guards name
    /// rows of the tables [`Self::set_monitor_table`] and
    /// [`Self::set_age_table`] install, so install those first; a guard whose
    /// row is absent never faults. The observer runs after the monitor rows on
    /// every monitor tick and reports `hazard-detected`, `hazard-reaction` and
    /// `hazard-recovered` on the same drain.
    pub fn set_hazard_table(&mut self, table: &'static [super::monitor::HazardSpec]) {
        self.hazard_table = table;
    }

    /// The installed hazard table (empty unless the entry set one).
    #[must_use]
    pub fn hazard_table(&self) -> &'static [super::monitor::HazardSpec] {
        self.hazard_table
    }

    /// W3b.5 — override the wall-clock (epoch µs) source age monitors take
    /// message stamps against. Hosted builds default to `SystemTime`; a
    /// board with a synced RTC installs its own here (or via
    /// `ExecutorConfig::epoch_us`). Call BEFORE entity creation — the age
    /// hook captures this at `create_subscription` time.
    pub fn set_epoch_clock(&mut self, epoch_us: fn() -> u64) {
        self.epoch_us_fn = Some(epoch_us);
    }

    /// W3b.5 — resolve a subscription's age hook at registration time:
    /// exact topic match against the baked age table, only for stamped
    /// types (`M::STAMP_OFFSET`) and only when an epoch source exists.
    fn age_lookup<M: RosMessage>(&self, topic: &str) -> Option<super::arena::AgeMon> {
        M::STAMP_OFFSET?;
        let epoch = self.epoch_us_fn?;
        self.age_table
            .iter()
            .find(|a| a.topic == topic)
            .map(|a| (a.cell, epoch))
    }

    /// W3b.5 — install the `DeadlineAction::Fault` hook. Without one a
    /// fault-class deadline miss panics (watchdog-visible stop on
    /// embedded targets).
    /// Plan one `spin_once` against the caller's intended cadence, and return
    /// the park budget in microseconds.
    ///
    /// phase-474 I11 -- two cases:
    ///
    /// * **No declared cadence, non-zero timeout** (the generated entries'
    ///   `spin_once(10)` loop, `spin`, `spin_period`): the timeout is the
    ///   period and the loop runs on an absolute RELEASE GRID. The budget is
    ///   the time to the next grid point, not a whole period from now, so the
    ///   previous spin's work no longer pushes every later release back. A
    ///   loop that comes back after its next point was due is released at
    ///   once, late by the difference; one that comes back a whole period or
    ///   more after it is released once for the LATEST due point and the
    ///   older ones are skipped and counted -- the timer `Skip` policy, never
    ///   a burst. Lateness is judged at the release (`record_grid_release`).
    ///   A change of timeout re-anchors the grid at this entry.
    /// * **A declared cadence** (`set_spin_nominal_us`, the tier loops that
    ///   sleep between spins themselves): unchanged. Late is
    ///   `(now - last_entry) - cadence`, clamped at zero, and the budget is
    ///   the timeout.
    ///
    /// A zero timeout claims no cadence and is skipped entirely, which keeps
    /// `Future::wait`-style busy spins out of the statistic and off the grid.
    fn record_release_jitter(&mut self, timeout: core::time::Duration) -> u64 {
        let timeout_us = timeout.as_micros().min(u64::MAX as u128) as u64;
        if !self.spin_nominal_self_paced() {
            if timeout_us == 0 {
                return 0;
            }
            let Some(now) = self.now_us() else {
                return timeout_us;
            };
            // phase-436 A2b -- a wait-paced declaration supplies the grid's
            // period; otherwise the timeout stands in for it.
            let period_us = if self.spin_nominal_declared_us != 0 {
                self.spin_nominal_declared_us
            } else {
                timeout_us
            };
            self.spin_nominal_us = period_us;
            if self.grid.period_us != period_us {
                // First periodic spin, or a new period: anchor here, so the
                // first park is a whole period exactly as before.
                self.grid.period_us = period_us;
                self.grid.next_us = now.saturating_add(period_us);
            } else if now >= self.grid.next_us.saturating_add(period_us) {
                // The loop came back a whole period or more after its next
                // release was due: serve the latest due point once and drop
                // the ones before it. The first dropped point is a release
                // that never happened, so its lateness at this moment (a
                // period or more) is what the jitter rule judges.
                let missed = (now - self.grid.next_us) / period_us;
                self.note_dropped_release(now - self.grid.next_us);
                self.grid.skipped = self
                    .grid
                    .skipped
                    .saturating_add(missed.min(u32::MAX as u64) as u32);
                self.grid.next_us = self
                    .grid
                    .next_us
                    .saturating_add(missed.saturating_mul(period_us));
            }
            // The timeout still bounds the wait. With a declared period it
            // may be shorter than the period (a caller that passes whole
            // milliseconds for a 1.5 ms cadence); a wake before the grid
            // point is then not a release, and the next spin parks again.
            return self.grid.next_us.saturating_sub(now).min(timeout_us);
        }
        // phase-474 I7 -- the violation reporter's own time since the last
        // sample is not a late release (see `flush_violation_reports`). Taken
        // first, so a spin that judges nothing does not carry it forward.
        let report_us = core::mem::take(&mut self.violations.reports.debt_us);
        let nominal_us = self.spin_nominal_declared_us;
        let Some(now) = self.now_us() else {
            return timeout_us;
        };
        self.spin_nominal_us = nominal_us;
        if let Some(last) = self.last_spin_entry_us {
            let interval = now.saturating_sub(last).saturating_sub(report_us);
            self.total_wakes = self.total_wakes.saturating_add(1);
            if let Some(late) = interval.checked_sub(nominal_us)
                && late > 0
            {
                self.count_late_wake(late);
            }
        }
        self.last_spin_entry_us = Some(now);
        timeout_us
    }

    /// phase-474 I11 -- judge a grid release, at the clock read after the
    /// park. A spin that wakes before its grid point (data arrived, a timer
    /// or another source was due first) is not a release: it dispatches and
    /// leaves the grid where it was. One that wakes at or after it is THE
    /// release of that point, late by `now - grid.next_us` (less the
    /// violation reporter's own time, phase-474 I7), and the grid advances by
    /// one period. Points the park itself overslept by a whole period are
    /// skipped at the next entry, not served in a burst.
    fn record_grid_release(&mut self, now: u64) {
        if self.spin_nominal_self_paced() || self.grid.period_us == 0 {
            return;
        }
        if now < self.grid.next_us {
            return;
        }
        let report_us = core::mem::take(&mut self.violations.reports.debt_us);
        let late = now
            .saturating_sub(self.grid.next_us)
            .saturating_sub(report_us);
        self.total_wakes = self.total_wakes.saturating_add(1);
        if late > 0 {
            self.count_late_wake(late);
        }
        self.grid.next_us = self.grid.next_us.saturating_add(self.grid.period_us);
        if now >= self.grid.next_us {
            // The park overslept the following point(s) too. This wake serves
            // one release; the points it ran past are skipped, not released
            // back to back on the next spins.
            let missed = (now - self.grid.next_us) / self.grid.period_us + 1;
            self.grid.skipped = self
                .grid
                .skipped
                .saturating_add(missed.min(u32::MAX as u64) as u32);
            self.grid.next_us = self
                .grid
                .next_us
                .saturating_add(missed.saturating_mul(self.grid.period_us));
        }
    }

    /// One wake that came back `late_us` (> 0) after its release was due.
    fn count_late_wake(&mut self, late_us: u64) {
        self.late_wakes = self.late_wakes.saturating_add(1);
        if late_us > self.release_jitter_granularity_us() {
            self.late_wakes_beyond_granule = self.late_wakes_beyond_granule.saturating_add(1);
        }
        if late_us > self.max_release_jitter_us {
            self.max_release_jitter_us = late_us;
        }
    }

    /// A cadence the caller meets with its own sleep between spins.
    fn spin_nominal_self_paced(&self) -> bool {
        self.spin_nominal_declared_us != 0 && !self.spin_nominal_wait_paced
    }

    /// The lateness of a grid release that was dropped rather than served,
    /// into the high-water the jitter rule reads (not into the wake counts:
    /// no wake happened).
    fn note_dropped_release(&mut self, late_us: u64) {
        let late = late_us.saturating_sub(core::mem::take(&mut self.violations.reports.debt_us));
        if late > self.max_release_jitter_us {
            self.max_release_jitter_us = late;
        }
    }

    /// phase-474 I11 -- grid releases skipped since the last
    /// `clear_release_jitter_stats`, because the loop came back after they
    /// were due. Zero for a declared-cadence or zero-timeout caller.
    pub fn skipped_releases(&self) -> u32 {
        self.grid.skipped
    }

    /// Release-jitter statistics from the spin loop: worst lateness in
    /// microseconds, the number of wakes that were already late, and the
    /// number of wakes total.
    ///
    /// The maximum is the figure of merit, and the ratio is what tells the
    /// two failures apart: one late wake in ten thousand is a glitch, ten
    /// thousand in ten thousand means the period cannot be met at all.
    ///
    /// Zero on a build with no clock -- `spin_period` refuses to run at all
    /// there (issue 0709), so there is nothing to have measured.
    pub fn release_jitter(&self) -> (u64, u32, u32) {
        (
            self.max_release_jitter_us,
            self.late_wakes,
            self.total_wakes,
        )
    }

    /// phase-436 A2c -- of the `late` wakes `release_jitter` counts, those
    /// late by more than [`Self::release_jitter_granularity_us`].
    ///
    /// A wake is late at one microsecond past its release. A loop paced by a
    /// tick-granular park comes back up to a tick past it on every wake, by
    /// design, so `late` approaches `total` on a loop that is keeping its
    /// period perfectly well. This count leaves that rounding out: it is the
    /// lateness the measurement can actually resolve. Cleared with the rest.
    pub fn late_wakes_beyond_granularity(&self) -> u32 {
        self.late_wakes_beyond_granule
    }

    /// Reset the release-jitter statistics. For monitoring code that logs
    /// and clears per window, so a single early outlier does not pin the
    /// maximum for the life of the process.
    pub fn clear_release_jitter_stats(&mut self) {
        self.max_release_jitter_us = 0;
        self.late_wakes = 0;
        self.late_wakes_beyond_granule = 0;
        self.total_wakes = 0;
        self.last_spin_entry_us = None;
        self.jitter_reported_us = 0;
        self.grid.skipped = 0;
    }

    pub fn set_fault_handler(&mut self, f: fn(&super::monitor::Violation)) {
        self.fault_fn = Some(f);
    }

    /// phase-503 — install the REACTION hook: `f(event, ctx)` is called on the
    /// spin thread when a supervised route passes its deadline
    /// (`route-deadline-runtime`), with the row's reaction id, row index and
    /// mechanism. It also stands in for [`Self::set_fault_handler`] on a
    /// `DeadlineAction::Fault` when no fault handler is set (reaction id 0,
    /// the sched-context slot as the row), so a C or C++ image has a fault
    /// path that does not panic. Replaces any earlier hook; `None` removes it.
    ///
    /// The hook must not block and must not re-enter this executor: it starts
    /// the fallback, or hands it to another thread, and returns.
    pub fn set_reaction_hook(
        &mut self,
        hook: Option<(super::monitor::ReactionHookFn, *mut core::ffi::c_void)>,
    ) {
        self.reaction_hook = hook;
    }

    /// phase-503 — microseconds from now to the earliest deadline of a pending
    /// supervised route (0 when one is due), or `None` when none is waiting or
    /// the executor has no clock. A port that supervises with its own timer
    /// (`MECHANISM_TIMER`) re-arms it from this after each spin.
    pub fn route_next_due_us(&self) -> Option<u64> {
        // No table, no clock read: this runs on every park.
        if self.monitor_table.is_empty() {
            return None;
        }
        let clock = self.clock_us_fn?;
        super::monitor::route_next_due_us(self.monitor_table, clock())
    }

    /// Issue #515 — warn about periods the spin cadence cannot express.
    ///
    /// A timer fires on the first spin at or after its period elapses, so
    /// a period that is not an integer multiple of the executor's spin
    /// period lands on the spin grid instead of the declared cadence: a
    /// 33 ms timer on a 5 ms spin alternates 35 ms / 30 ms, mean 33.0.
    /// The rate is preserved and no activation is dropped, so every
    /// runtime rule is (correctly) silent — the jitter stays invisible
    /// until someone measures cadence on target.
    ///
    /// Runs ONCE, on the first spin carrying a non-zero timeout, because
    /// that timeout is where the tier's declared spin period becomes
    /// visible down here. A resolve-time diagnostic would be better
    /// still — the toolchain holds both numbers before the image is
    /// built — but this backstop needs no board or codegen change and
    /// catches hand-written spin loops too.
    /// phase-436 W1 (issue 1192) — how long the executor may park, in
    /// microseconds, given the caller's budget.
    ///
    /// The park used to be bounded by the caller's timeout narrowed by exactly
    /// one input, the BACKEND's `next_deadline_ms`. A registered timer is a
    /// deadline the EXECUTOR owns, and nothing let it shorten the sleep — so
    /// `spin_default`'s 50 ms slept straight past a 10 ms timer, and the
    /// activations then arrived in the burst issue 0505 describes.
    ///
    /// This is the `min` over the deadline sources phase-436 names. The
    /// caller's budget is always a member, so the result is never unbounded
    /// and never zero-by-omission: with no timers registered the budget
    /// stands, which keeps a long idle wait a wait rather than a poll.
    ///
    /// Distinct from issue 0515's audit, which warns that a period does not
    /// divide the spin grid. That takes the grid as given; this moves it.
    ///
    /// `#[cfg(test)]`-gated (matching `mod tests`'s own gate in `mod.rs`):
    /// production code calls `next_wake_bound_attributed_us` directly to get
    /// the source alongside the bound, so this `.0`-only convenience has no
    /// caller outside the test module and is dead code in any build that
    /// does not compile it (every `cargo check`/`cargo doc`, and `cargo test
    /// --features rmw-cffi`, which excludes `mod tests` too).
    #[cfg(all(test, feature = "alloc", not(feature = "rmw-cffi")))]
    pub(crate) fn next_wake_bound_us(&self, budget_us: u64) -> u64 {
        self.next_wake_bound_attributed_us(budget_us, None).0
    }

    /// phase-436 W6 — contribute a deadline source.
    ///
    /// The core never names an RTOS: a port registers `k_poll`, `epoll`, a
    /// queue set or a device ISR here, and the executor only ever asks "when
    /// will you next need me?".
    ///
    /// Refuses past capacity rather than dropping silently. A source that was
    /// quietly discarded would leave the executor sleeping past a deadline it
    /// had been told about, which is the failure this whole phase exists to
    /// remove.
    pub fn register_wake_source(
        &mut self,
        next: NextDeadlineFn,
        ctx: *mut core::ffi::c_void,
    ) -> Result<WakeSourceId, NodeError> {
        if self.wake_source_count >= MAX_WAKE_SOURCES {
            return Err(NodeError::ExecutorFull);
        }
        let idx = self.wake_source_count;
        self.wake_sources[idx] = Some(WakeSourceSlot { next, ctx });
        self.wake_source_count += 1;
        Ok(WakeSourceId::Platform(idx as u8))
    }

    /// Install THE thing that blocks. Singular by nature — only one primitive
    /// can actually wait — so this replaces whatever was there.
    /// `granularity_us` is the finest park this primitive can actually
    /// express. The port states it because only the port knows: the ABI
    /// signature is not the limit — an RTOS tick is a second, coarser one, and
    /// a timespec primitive is a finer one.
    pub fn set_park_primitive(
        &mut self,
        park: ParkUntilFn,
        ctx: *mut core::ffi::c_void,
        granularity_us: u64,
    ) {
        self.park_primitive = Some((park, ctx));
        self.park_granularity_declared_us = granularity_us;
    }

    /// The wake primitive a port must hand its `ParkUntilFn` as `ctx`, or NULL
    /// when this build has none.
    ///
    /// phase-436 W7 — a park that waits on its own fresh object is NOT
    /// breakable by the backend's listener, and installing one makes latency
    /// worse: once a port has parked, the transport drain drops to
    /// non-blocking, so an unbreakable park sleeps out its full deadline with
    /// data already waiting. Waiting on THIS object keeps the async break.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub fn wake_raw_ptr(&self) -> *mut core::ffi::c_void {
        match self.node_wake.as_ref() {
            Some(w) => w.raw_ptr(),
            None => core::ptr::null_mut(),
        }
    }

    /// Whether a platform park primitive is installed.
    pub fn has_park_primitive(&self) -> bool {
        self.park_primitive.is_some()
    }

    /// The bound and the source that produced it: the `min` over every
    /// deadline source, with the caller's budget as an ordinary member.
    ///
    /// The budget being a member is what makes the result never unbounded and
    /// never zero-by-omission, and it is why "no sources registered" needs no
    /// special case.
    pub(crate) fn next_wake_bound_attributed_us(
        &self,
        budget_us: u64,
        session_us: Option<u64>,
    ) -> (u64, WakeSourceId) {
        let mut best = (budget_us, WakeSourceId::CallerBudget);

        // The backend's next internal event is a MEMBER, not a pre-cap. It was
        // folded into the budget upstream, which meant a park the session
        // actually won reported `CallerBudget` — the attribution named the
        // wrong source, and "why did we wake" is the question attribution
        // exists to answer.
        if let Some(s) = session_us
            && s < best.0
        {
            best = (s, WakeSourceId::Session);
        }

        if let Some(timer_us) = self.next_timer_deadline_us()
            && timer_us < best.0
        {
            best = (timer_us, WakeSourceId::Timer);
        }

        // phase-503 — a supervised route's deadline is the executor's own, like
        // a timer's: the park must end there, or a route whose output never
        // comes is judged only when something else wakes the loop.
        if let Some(due_us) = self.route_next_due_us()
            && due_us < best.0
        {
            best = (due_us, WakeSourceId::RouteDeadline);
        }

        for (i, slot) in self.wake_sources.iter().enumerate() {
            let Some(slot) = slot else { continue };
            // SAFETY: the callback and ctx were supplied together by the port
            // through `register_wake_source` and outlive the executor by its
            // contract; the call takes no ownership.
            let due = unsafe { (slot.next)(slot.ctx) };
            // `u64::MAX` is "nothing pending" — an async source spells itself
            // this way and breaks the park by signalling instead.
            if due != u64::MAX && due < best.0 {
                best = (due, WakeSourceId::Platform(i as u8));
            }
        }

        best
    }

    /// phase-436 — the bound the last park used, and which source won it.
    pub fn last_park(&self) -> (u64, WakeSourceId) {
        (self.last_park_bound_us, self.last_park_source)
    }

    /// phase-436 W2 — the park the platform was actually asked for, after
    /// rounding the request up to an expressible value.
    ///
    /// Differs from `last_park().0` exactly when the request did not land on
    /// the platform's grid. Both are reported because a cadence that cannot be
    /// waited in must not be presented as if it were met.
    pub fn last_park_achieved_us(&self) -> u64 {
        self.last_park_achieved_us
    }

    /// phase-436 W3 (issue 1194) — the granularity the release-jitter
    /// measurement was actually made at, in microseconds.
    ///
    /// The jitter statistic is reported in microseconds, but the mechanism
    /// that PACES the loop decides how fine it can honestly be, and there are
    /// two mechanisms:
    ///
    /// * **No declared cadence** — the loop is paced by the blocking wait
    ///   itself, so it cannot come round more precisely than one park granule.
    ///   Reporting µs there is precision the wait cannot deliver.
    /// * **A declared cadence** (`set_spin_nominal_us`) — the caller paces
    ///   itself, as nros-cpp's tiers do with `platform_sleep_us` between
    ///   spins. That sleep is finer than the wait, so the measurement really
    ///   is good to a microsecond and coarsening it would understate it.
    ///
    /// Reported rather than applied: this does not change what the monitor
    /// judges, because silently coarsening a bound could mask real lateness.
    /// It says what the number is worth.
    pub fn release_jitter_granularity_us(&self) -> u64 {
        if self.spin_nominal_self_paced() {
            1
        } else {
            self.park_granularity_us()
        }
    }

    /// The finest park this build can actually express, in microseconds.
    ///
    /// Comes from the INSTALLED primitive, because only the port knows. The
    /// exported ABI signature is not the limit in either direction (issue
    /// 1242):
    ///
    /// * an RTOS tick is a COARSER limit — ThreadX pins
    ///   `TX_TIMER_TICKS_PER_SECOND = 100`, a 10 ms tick, so a 1 ms park is not
    ///   achievable there however the ABI is spelled;
    /// * a timespec primitive is a FINER one — POSIX's `sem_timedwait` and
    ///   `pthread_cond_timedwait` are nanosecond-native, and only the
    ///   `uint32_t timeout_ms` signature floors them at a millisecond.
    ///
    /// This was a hardcoded `1_000` justified by "every `nros_platform_wake_*`
    /// port takes `uint32_t timeout_ms`". That was right for FreeRTOS by
    /// coincidence and wrong for the other two, and it made the W3 jitter
    /// report over-claim on ThreadX — the failure W3 exists to prevent,
    /// reproduced one layer below W3 in its own dependency.
    ///
    /// With nothing installed the fallback is 1 ms, which IS the honest floor
    /// of the `wake_wait_ms` ABI every port exports today.
    ///
    /// The declared granularity counts only while the park is USABLE. An
    /// executor whose backend has no live wake (XRCE, or a session whose
    /// callback is gone) never parks: `spin_once` waits in the transport's
    /// own receive instead, whose timeout is whole milliseconds. Claiming a
    /// POSIX park's 1 us there over-claimed the jitter report, and worse,
    /// rounded the bound to microseconds that the millisecond wait then
    /// truncated, so a sub-millisecond deadline became a non-blocking receive
    /// and the loop spun hot until it passed.
    pub fn park_granularity_us(&self) -> u64 {
        if self.park_granularity_declared_us != 0
            && self.park_primitive.is_some()
            && self.park_can_be_woken()
        {
            self.park_granularity_declared_us
        } else {
            1_000
        }
    }

    /// phase-436 — whether a park could be ended early by data arriving.
    ///
    /// A park ends on its bound or on the wake object. With a poll-only
    /// backend (XRCE), or a session whose wake callback is gone, nothing
    /// signals that object, so a park would be a blind sleep and data
    /// arriving mid-park would wait out the whole bound — the Phase 127.C.4
    /// stall (a reliable stream whose ACK lands in a session nobody drives).
    /// Builds without `alloc` + `rmw-cffi` have no wake callback at all and
    /// park as they always did.
    pub(crate) fn park_can_be_woken(&self) -> bool {
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        {
            self.async_wake_live()
        }
        #[cfg(not(all(feature = "alloc", feature = "rmw-cffi")))]
        {
            true
        }
    }

    /// Drive the primary session for `timeout_ms`, the transport-side half of
    /// the wait.
    ///
    /// phase-436 (RFC-0106 D5) — on a poll-only backend this wait IS the
    /// executor's park, and it waits inside the backend's own `recv`, which a
    /// guard condition triggered from another thread cannot end: the trigger
    /// signals the wake object and nobody is waiting on it. Measured on XRCE
    /// before this: a trigger 20 ms into a 100 / 500 / 1000 ms spin was
    /// dispatched 79 / 480 / 979 ms later, i.e. it waited out the bound. So
    /// when such a waker exists and nothing can wake the park, the drive is
    /// cut into slices of [`POLL_ONLY_WAKE_SLICE_MS`] and stops at the first
    /// slice that ends with the wake flag set. The latency becomes one slice;
    /// an executor with no cross-thread waker keeps the single blocking drive.
    fn drive_primary(&mut self, timeout_ms: i32) -> Result<(), ()> {
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        if self.has_cross_thread_waker
            && !self.async_wake_live()
            && timeout_ms > POLL_ONLY_WAKE_SLICE_MS
        {
            let mut remaining = timeout_ms;
            while remaining > 0 {
                let slice = remaining.min(POLL_ONLY_WAKE_SLICE_MS);
                self.session.drive_io(slice).map_err(|_| ())?;
                remaining -= slice;
                if self
                    .wake_flag
                    .swap(false, portable_atomic::Ordering::SeqCst)
                {
                    // Issue 1385 — consume the primitive too, or the next
                    // spin's wait returns at once on a signal already acted on.
                    if let Some(wake) = self.node_wake.as_ref() {
                        let _ = wake.wait_ms(0);
                    }
                    break;
                }
            }
            return Ok(());
        }
        self.session.drive_io(timeout_ms).map_err(|_| ())
    }

    pub(crate) fn round_park_up_us(&self, requested_us: u64) -> u64 {
        if requested_us == 0 {
            return 0;
        }
        let g = self.park_granularity_us();
        if g <= 1 {
            return requested_us;
        }
        requested_us.div_ceil(g).saturating_mul(g)
    }

    /// Microseconds until the soonest live timer is due, or `None` when no
    /// timer is pending.
    ///
    /// A timer that is cancelled, or a one-shot that already fired, owes
    /// nothing and must not hold the park short — otherwise the executor keeps
    /// waking on a deadline nobody is waiting for.
    ///
    /// So does a timer whose remainder is not WALL microseconds
    /// ([`TimerClockSource::remaining_is_wall_time`], issue 1321): the number
    /// this returns is handed to the port's park primitive, so a ROS-time
    /// timer's simulated remainder would be a units error — and on a paused
    /// `/clock` a frozen one, waking the image once per timer period forever.
    /// Its wake source is a `/clock` message, which reaches `drive_io` like
    /// any sample.
    pub(crate) fn next_timer_deadline_us(&self) -> Option<u64> {
        let arena_ptr = self.arena.as_ptr() as *const u8;
        let mut soonest: Option<u64> = None;
        for meta in self.entries.iter().flatten() {
            if !matches!(meta.kind, EntryKind::Timer) {
                continue;
            }
            // SAFETY: a Timer entry's arena slot holds a `TimerEntry<F>`, whose
            // leading layout is `TimerHeader` — the same projection
            // `audit_spin_quantization` relies on.
            let header = unsafe { &*(arena_ptr.add(meta.offset) as *const TimerHeader) };
            if header.cancelled || header.period_us == 0 {
                continue;
            }
            if header.oneshot && header.fired {
                continue;
            }
            // Issue 1321 — the park is WALL microseconds, so only a timer
            // whose own clock runs in them may bound it.
            if !header.clock_source.remaining_is_wall_time() {
                continue;
            }
            // Already due: the bound is zero, and no other timer can beat it.
            let remaining = header.period_us.saturating_sub(header.elapsed_us);
            soonest = Some(match soonest {
                Some(cur) => cur.min(remaining),
                None => remaining,
            });
            if remaining == 0 {
                break;
            }
        }
        soonest
    }

    fn audit_spin_quantization(&mut self, spin_us: u64) {
        if spin_us == 0 {
            return;
        }
        let arena_ptr = self.arena.as_ptr() as *const u8;
        for i in 0..self.entries.len() {
            let Some(meta) = self.entries[i].as_ref() else {
                continue;
            };
            if !matches!(meta.kind, EntryKind::Timer) {
                continue;
            }
            // SAFETY: a Timer entry's arena slot holds a `TimerEntry<F>`,
            // whose leading layout is `TimerHeader`.
            let header = unsafe { &*(arena_ptr.add(meta.offset) as *const TimerHeader) };
            let period_us = header.period_us;
            let Some((early_us, late_us)) =
                spin_quantization_span(header.clock_source, period_us, spin_us)
            else {
                continue;
            };
            nros_log::log_warn!(
                nros_log::get_logger("nros"),
                "timer period {} us is not a multiple of the {} us spin period: activations will alternate between {} us and {} us (mean cadence preserved)",
                period_us,
                spin_us,
                early_us,
                late_us
            );
        }
    }

    /// Issue #514 — whether the executor logs each violation as it is
    /// detected (the default).
    ///
    /// Turn this off in an application that reports violations its own
    /// way via [`Self::drain_violations`]; the ring is unaffected
    /// either way.
    pub fn set_report_violations(&mut self, enabled: bool) {
        self.violations.report = enabled;
    }

    /// phase-474 I1 -- the drain-and-report hook: at the end of every spin,
    /// drain the ring and log each entry with its sequence number and the
    /// `total` / `dropped` counters (`contract violation #N: <rule> <fqn>
    /// measured=.. declared=.. (total=.. dropped=..)`).
    ///
    /// While on it REPLACES the log line at detection, so one verdict is one
    /// line, and an application that wanted to drain the ring itself sees an
    /// empty one. The generated C/C++ entries turn it on when the image sets
    /// `CONFIG_NROS_VIOLATION_DRAIN_REPORT` (off by default). The trace marker
    /// (`callback_trace::MARKER_VIOLATION`) and the SWD record do not depend
    /// on it: both are written at detection.
    pub fn set_violation_drain_report(&mut self, enabled: bool) {
        self.violations.drain_report = enabled;
    }

    /// Issue #514 / phase-474 I1 -- violations evicted from the full ring
    /// before any drain took them.
    ///
    /// The ring keeps the LATEST `MAX_VIOLATIONS`, so non-zero means the
    /// OLDEST verdicts were lost, never the newest. (Before phase-474 a full
    /// ring refused the push, which kept the first verdicts since boot and
    /// lost every later one.)
    pub fn violations_dropped(&self) -> u32 {
        self.violations.counts.dropped
    }

    /// phase-474 I1 -- contract violations this executor stored since boot
    /// (wrapping). The newest entry in the ring is number `violations_total()`;
    /// `total - dropped - pending` is how many drains have taken.
    pub fn violations_total(&self) -> u32 {
        self.violations.counts.total
    }

    /// RFC-0052 W3b.4 -- drain pending contract violations, OLDEST first.
    /// Draining clears the ring. Call between spins, never from a callback.
    pub fn drain_violations(&mut self, mut f: impl FnMut(&super::monitor::Violation)) {
        self.violations.drain(|_, v| f(v));
    }

    /// [`Self::drain_violations`] with each entry's sequence number (1-based,
    /// per executor; the same number the drain-and-report line and the trace
    /// marker carry), so a reader can tell a gap from a quiet interval.
    pub fn drain_violations_numbered(&mut self, f: impl FnMut(u32, &super::monitor::Violation)) {
        self.violations.drain(f);
    }

    /// phase-474 I2 -- choose when this executor's contract monitors arm,
    /// overriding the build default (`NROS_MONITOR_ARM_ON_CALL`,
    /// `NROS_MONITOR_ARM_GRACE_MS`). Call before the first spin (an
    /// `arm_monitors` made before it is undone by this); after the first spin
    /// an executor that already armed stays armed.
    ///
    /// `on_call`: wait for [`Self::arm_monitors`] or
    /// [`super::monitor::request_monitor_arming`] (`rclc_monitors_arm()`).
    /// `grace_ms`: arm anyway that long after the first spin (0 = never by
    /// deadline; with `on_call == false`, 0 means "at the first spin").
    pub fn set_monitor_arming(&mut self, on_call: bool, grace_ms: u32) {
        let v = &mut self.violations.counts;
        v.arm_on_call = on_call;
        v.arm_grace_ms = grace_ms;
        if !v.spun {
            // Before the first spin, "armed" is just the policy's answer (no
            // rule has run yet); the first spin counts the arming once.
            v.armed = super::monitor::MonitorArming { on_call, grace_ms }.armed_at_first_spin();
        }
    }

    /// phase-474 I2 -- the application says its start-up is over: this
    /// executor's monitors start judging now. Idempotent.
    ///
    /// Judgement restarts at arming: every rate/age/silence window reopens,
    /// a latency or age measured before arming is discarded, the release-
    /// jitter statistics are cleared (so the figure after RUN is RUN's), and a
    /// stack low-water mark already past the declared minimum is reported
    /// again, because stack depth reached at start-up is a real fault, not
    /// start-up noise.
    pub fn arm_monitors(&mut self) {
        self.arm_now("the application armed them");
    }

    /// phase-474 I2 -- whether this executor's monitors are armed.
    pub fn monitors_armed(&self) -> bool {
        self.violations.counts.armed
    }

    /// phase-474 I2 -- verdicts reached before the monitors armed: counted,
    /// never stored, logged, sunk or traced.
    pub fn violations_suppressed_before_arm(&self) -> u32 {
        self.violations.counts.suppressed_before_arm
    }

    fn arm_now(&mut self, why: &str) {
        if self.violations.counts.armed {
            return;
        }
        self.violations.counts.armed = true;
        for st in self.monitor_states.iter_mut() {
            *st = super::monitor::MonitorState::default();
        }
        for st in self.age_states.iter_mut() {
            *st = super::monitor::AgeState::default();
        }
        for spec in self.monitor_table.iter() {
            spec.cell
                .max_latency_us
                .store(0, core::sync::atomic::Ordering::Relaxed);
        }
        // phase10-B3 -- a take waiting since start-up is not a route of RUN's.
        super::monitor::route_reset(self.monitor_table);
        for spec in self.age_table.iter() {
            spec.cell
                .max_age_ms
                .store(0, core::sync::atomic::Ordering::Relaxed);
            spec.cell
                .takes
                .store(0, core::sync::atomic::Ordering::Relaxed);
        }
        self.clear_release_jitter_stats();
        self.stack_headroom_reported = usize::MAX;
        self.stack_headroom_last_check_us = None;
        // Counted once per executor: here once it has spun, else by the first
        // spin (which counts an executor that is armed by then either way).
        #[cfg(nros_boot_report)]
        if self.violations.counts.spun {
            super::monitor::NROS_VIOLATION_RECORD
                .armed
                .fetch_add(1, core::sync::atomic::Ordering::Relaxed);
        }
        nros_log::log_info!(
            nros_log::get_logger("nros"),
            "contract monitors armed ({}); {} verdict(s) before arming suppressed",
            why,
            self.violations.counts.suppressed_before_arm
        );
    }

    /// phase-474 I2 -- once per spin, before any rule runs: note the first
    /// spin, and arm when the policy says so.
    fn update_monitor_arming(&mut self, now_us: Option<u64>) {
        // Milliseconds in a wrapping `u32`, like the silence rule's lease
        // (`AgeState::last_take_ms`): this state is inline in the `Executor`
        // value, whose size is budgeted (issue 0961).
        let now_ms = now_us.map(|us| (us / 1_000) as u32);
        let v = &mut self.violations.counts;
        if !v.spun {
            v.spun = true;
            v.first_spin_ms = now_ms.unwrap_or(0);
            if v.armed {
                // Armed from the start (the default), or by a call made before
                // the first spin: count it in the record so a reader sees how
                // many executors are judging.
                #[cfg(nros_boot_report)]
                super::monitor::NROS_VIOLATION_RECORD
                    .armed
                    .fetch_add(1, core::sync::atomic::Ordering::Relaxed);
                return;
            }
            if (super::monitor::MonitorArming {
                on_call: v.arm_on_call,
                grace_ms: v.arm_grace_ms,
            })
            .armed_at_first_spin()
            {
                self.arm_now("at the first spin");
                return;
            }
        }
        if v.armed {
            return;
        }
        if super::monitor::arm_requests() != v.arm_requests_seen {
            self.arm_now("the application asked: rclc_monitors_arm");
            return;
        }
        let grace_ms = v.arm_grace_ms;
        if grace_ms == 0 {
            return;
        }
        match now_ms {
            Some(now) if now.wrapping_sub(v.first_spin_ms) >= grace_ms => {
                self.arm_now("the grace period after the first spin elapsed");
            }
            // No clock: a grace period cannot elapse, and waiting forever would
            // leave the image unmonitored. Arm rather than guess a duration.
            None if !v.arm_on_call => {
                self.arm_now("no clock to time the grace period");
            }
            _ => {}
        }
    }

    /// Issue 1635 -- hand every stored violation to `sink`, beside the log line
    /// (issue 0514's floor) and the ring push.
    ///
    /// phase-474 I7 -- not at detection any more: the verdict is queued and
    /// leaves from `Executor::flush_violation_reports` at the end of a spin with
    /// slack, so the report never costs the dispatch it judges.
    ///
    /// Before this nothing in a generated image drained the ring, so the log
    /// line was the only output and `/diagnostics` stayed silent on every C
    /// and C++ road. A report point the RUNTIME owns reaches every road at
    /// once — every board's spin loop goes through the executor — where one
    /// per entry template would have to be rebuilt for each board runner. The
    /// ring is still filled, so an application (or a fixture) that drains it
    /// with [`Self::drain_violations`] sees exactly what it did before.
    /// `None` removes the sink.
    ///
    /// # Safety
    /// `ctx` must stay valid for every call of the sink until it is replaced
    /// or this executor is dropped (see [`super::monitor::ViolationSink`]).
    pub unsafe fn set_violation_sink(
        &mut self,
        sink: Option<(super::monitor::ViolationSink, *mut core::ffi::c_void)>,
    ) {
        self.violations.sink = sink.map(|(f, ctx)| (f, ctx as usize));
        if self.violations.sink.is_none() {
            // Nothing is left to send them to.
            self.violations.reports.pending.clear();
            self.violations.reports.since_us = None;
        }
    }

    /// phase-474 I7 -- hand the queued verdicts to the sink, if this is a slot
    /// for it. Called at the end of every spin, after its dispatches and its
    /// rules, so the report never runs inside the tick being judged.
    ///
    /// A slot is a spin end whose next timer is due no sooner than the last
    /// report took (`ReportQueue::last_cost_us`; 0 before the first report, so
    /// the first goes at the first spin end with no timer already due), or
    /// any spin end once the oldest pending verdict has waited
    /// [`REPORT_DEFER_MAX_US`](super::monitor::REPORT_DEFER_MAX_US). Without a
    /// clock there is nothing to measure slack with, so every spin end is a
    /// slot. The sink takes as many as it coalesces into one message; the rest
    /// wait for the next slot.
    ///
    /// The time the sink takes is the reporter's own and is stated by
    /// [`Self::violation_report_cost_us`]; the release-jitter rule does not
    /// charge it to the spin's cadence (it is not a late release of any
    /// application work), which is what used to turn one verdict into a
    /// `release-jitter-runtime` verdict of its own on the safety island.
    pub(crate) fn flush_violation_reports(&mut self) {
        let Some((sink, ctx)) = self.violations.sink else {
            return;
        };
        if self.violations.reports.pending.is_empty() {
            return;
        }
        let now = self.now_us();
        if let Some(now) = now {
            let since = *self.violations.reports.since_us.get_or_insert(now);
            let overdue = now.saturating_sub(since) >= super::monitor::REPORT_DEFER_MAX_US;
            let cost = self.violations.reports.last_cost_us as u64;
            let slack = match self.next_timer_deadline_us() {
                None => true,
                Some(remaining) => remaining > 0 && remaining >= cost,
            };
            if !slack && !overdue {
                return;
            }
        }
        // SAFETY: `Executor::set_violation_sink`'s contract -- `ctx` is valid
        // for every call until the sink is replaced or the executor dropped.
        let taken = unsafe {
            sink(
                ctx as *mut core::ffi::c_void,
                &self.violations.reports.pending[..],
            )
        };
        let q = &mut self.violations.reports;
        if taken == 0 {
            // The sink counted its failure; drop the oldest so a report that
            // can never be sent does not stall the queue. It stays in the ring
            // and the record.
            q.pending.remove(0);
            q.failed = q.failed.saturating_add(1);
        } else {
            let n = taken.min(q.pending.len());
            for _ in 0..n {
                q.pending.remove(0);
            }
        }
        q.since_us = None;
        if let (Some(t0), Some(t1)) = (now, self.now_us()) {
            let q = &mut self.violations.reports;
            let cost = t1.saturating_sub(t0);
            q.last_cost_us = cost.min(u32::MAX as u64) as u32;
            q.max_cost_us = q.max_cost_us.max(q.last_cost_us);
            q.debt_us = q.debt_us.saturating_add(cost);
        }
    }

    /// phase-474 I7 -- what handing verdicts to the violation sink has cost
    /// this executor: `(last_us, max_us, pending, overflowed)`. `overflowed`
    /// counts verdicts evicted from the report queue by newer ones before a
    /// slot came (they are still in the ring and the SWD record).
    pub fn violation_report_cost_us(&self) -> (u32, u32, usize, u32) {
        let q = &self.violations.reports;
        (q.last_cost_us, q.max_cost_us, q.pending.len(), q.overflowed)
    }

    /// THE monotonic-µs read. phase-359 W4 — every consumer goes through here.
    ///
    /// Before this there were FIVE spellings of "what time is it": this one,
    /// `last_spin_end: Instant`, and two ad-hoc `static EPOCH: OnceLock<Instant>`
    /// blocks — plus `PlatformClock`, which nothing called because `Executor` is
    /// deliberately non-generic and the trait's methods are associated fns.
    ///
    /// `None` means no clock is available (no_std with no injected hook).
    /// Callers must degrade, not guess: a missing clock is why the sporadic
    /// refill and the major-frame phase behaved differently on no_std.
    fn now_us(&mut self) -> Option<u64> {
        self.clock_us_fn.map(|clock| clock())
    }

    /// Run the rate/latency/age checks over the baked tables (single
    /// branch each when empty).
    fn run_contract_monitors(&mut self) {
        if !self.monitor_table.is_empty()
            && let Some(now_us) = self.now_us()
        {
            {
                for (i, spec) in self
                    .monitor_table
                    .iter()
                    .take(super::monitor::MAX_MONITORS)
                    .enumerate()
                {
                    if let Some(v) =
                        super::monitor::check_rate(spec, &mut self.monitor_states[i], now_us)
                    {
                        self.violations.record(v);
                    }
                    if let Some(v) =
                        super::monitor::check_latency(spec, &mut self.monitor_states[i])
                    {
                        self.violations.record(v);
                    }
                }
            }
        }
        if !self.age_table.is_empty() {
            // phase-462 W2 -- the age loop needs the clock now: `silence-runtime`
            // judges how long an endpoint has taken NOTHING, and `None` (a
            // build with no clock) makes that rule abstain rather than guess.
            // Read before the loop because the borrow of `age_states` below
            // outlives the `&mut self` the reader wants.
            let now_us = self.now_us();
            for (i, spec) in self
                .age_table
                .iter()
                .take(super::monitor::MAX_AGE_MONITORS)
                .enumerate()
            {
                if let Some(v) = super::monitor::check_age(spec, &mut self.age_states[i], now_us) {
                    self.violations.record(v);
                }
            }
        }
        // phase-462 W3b -- the hazard observer reads the verdict STATE the rows
        // above just updated, so it runs after them and on the same tick.
        if !self.hazard_table.is_empty()
            && let Some(now_us) = self.now_us()
        {
            let now_ms = (now_us / 1_000) as u32;
            let violations = &mut self.violations;
            for spec in self.hazard_table {
                super::monitor::check_hazard(
                    spec,
                    self.monitor_table,
                    &self.monitor_states,
                    &self.age_states,
                    now_ms,
                    |v| violations.record(v),
                );
            }
        }
        self.check_route_deadlines();
    }

    /// phase-503 — `route-deadline-runtime`: every pending supervised route
    /// past `take + route_deadline_ms` is reported (once until a route is
    /// within budget again) and its reaction requested through the hook.
    /// Runs right after the park, whose bound includes the earliest due time
    /// ([`WakeSourceId::RouteDeadline`]), so a route whose output never comes
    /// is judged within one park granule of its deadline. A callback that does
    /// not return holds this check too: that is `MECHANISM_TIMER`'s case.
    fn check_route_deadlines(&mut self) {
        let table = self.monitor_table;
        if table.is_empty() || !super::monitor::route_deadline_active(table) {
            return;
        }
        let Some(now_us) = self.now_us() else {
            return;
        };
        // Start-up is not RUN (phase-474 I2): before arming a verdict is only
        // counted, and no reaction is requested for it either.
        let hook = self.reaction_hook.filter(|_| self.violations.counts.armed);
        let violations = &mut self.violations;
        super::monitor::route_overdue(table, now_us, |row, v, first| {
            call_route_reaction(hook, table, row, &v);
            if first {
                violations.record(v);
            }
        });
    }

    /// Issue #505 — report activations dropped by
    /// [`TimerOverrunPolicy::Skip`](super::arena::TimerOverrunPolicy)
    /// since the last check.
    ///
    /// Unlike the rate/age/latency rules this needs no baked spec table:
    /// every periodic timer counts its own overruns, and a dropped
    /// activation is a contract failure for any declared period. It runs
    /// on the same tick so violations land in the same ring the entry
    /// glue drains.
    /// Declare the minimum stack headroom this executor's thread must keep,
    /// in bytes. `0` (the default) disables the `stack-headroom-runtime`
    /// rule.
    ///
    /// Set by the entry that spawned the thread, because it is the only
    /// party that knows what stack it handed over: the executor never sees
    /// `stack_bytes`, and no portable query returns a task's total stack, so
    /// neither an absolute floor nor a percentage can be inferred here.
    /// Declare how often this executor's loop intends to come round, in
    /// microseconds. `0` (the default) falls back to the `spin_once` timeout.
    ///
    /// Needed because a driver's pacing and its blocking bound are separate
    /// numbers. nros-cpp's tier loops sleep `spin_period_us` between spins but
    /// pass a fixed 10 ms timeout, so the release-jitter rule judged every
    /// tier against 10 ms regardless of what the contract declared -- too lax
    /// for a 1 ms tier and far too strict for a 30 ms one.
    ///
    /// This also says the CALLER paces the loop (a sleep finer than the
    /// park), so the measurement is reported at 1 us. A loop paced by the
    /// `spin_once` wait itself declares with
    /// [`Self::set_spin_nominal_wait_paced_us`] instead.
    pub fn set_spin_nominal_us(&mut self, us: u64) {
        self.spin_nominal_declared_us = us;
        self.spin_nominal_wait_paced = false;
    }

    /// phase-436 A2b -- declare the loop's cadence, in microseconds, for a
    /// loop paced by the `spin_once` wait itself. `0` withdraws it.
    ///
    /// [`Self::set_spin_nominal_us`] couples two facts: the period to judge
    /// against, and that the caller paces the loop with its own sleep. A loop
    /// like `for (;;) spin_once(period_ms)` has the first without the second.
    /// Declaring through the coupled setter would report its jitter at 1 us
    /// when the park it waits on is tick-granular (issue 1194's failure); not
    /// declaring at all makes the timeout the period, which is wrong whenever
    /// the timeout is not the period (a cadence that is not whole
    /// milliseconds, or one raised to a floor).
    ///
    /// Here the cadence is the period of the release grid that a
    /// `spin_once(timeout)` loop already runs on, and the timeout stays a
    /// bound on each wait. The jitter is judged at grid releases and reported
    /// at the park granularity.
    pub fn set_spin_nominal_wait_paced_us(&mut self, us: u64) {
        self.spin_nominal_declared_us = us;
        self.spin_nominal_wait_paced = us != 0;
    }

    pub fn set_min_stack_headroom_bytes(&mut self, bytes: usize) {
        self.min_stack_headroom_bytes = bytes;
        // phase-436 E4 — a new bound is checked on the next spin, not up to an
        // interval later.
        self.stack_headroom_last_check_us = None;
        // phase-436 E3 — `check_stack_headroom_rule` treats a 0 from the port as
        // "not instrumented" and skips, which is right for the rule and wrong
        // for the reader: an armed rule that can never judge reports nothing,
        // exactly like one that judged and found the stack healthy. Ask the
        // port once, here. Entries set the bound at boot on the thread it
        // describes, so the answer is about the right stack and the warning
        // lands once per tier, next to the tier's other boot lines.
        // phase-436 E5 -- "does the port answer at all?" needs one byte, not
        // the whole unused region the full query would scan.
        self.stack_headroom_blind =
            bytes != 0 && nros_platform_api::stack_unused_bytes_upto(1) == 0;
        if self.stack_headroom_blind {
            nros_log::log_warn!(
                nros_log::get_logger("nros"),
                "stack-headroom-runtime: a {} B minimum is set but this port reports no stack \
                 data, so the rule will never check (Zephyr: enable CONFIG_INIT_STACKS)",
                bytes
            );
        }
    }

    /// phase-436 E3 — whether `stack-headroom-runtime` is armed on a port that
    /// cannot measure, and so will never report a violation.
    ///
    /// `true` means the rule's silence is not evidence of headroom. Zephyr
    /// answers only with `CONFIG_INIT_STACKS && CONFIG_THREAD_STACK_INFO`;
    /// POSIX never does.
    pub fn stack_headroom_blind(&self) -> bool {
        self.stack_headroom_blind
    }

    /// Report a spin thread that has come closer to the end of its stack
    /// than `set_min_stack_headroom_bytes` allows.
    ///
    /// Runs on the same tick as the other rules and feeds the same ring.
    /// Queries the port at most once per `STACK_HEADROOM_CHECK_INTERVAL_US`
    /// (phase-436 E4): on a painted Zephyr stack the full query scans every
    /// unused byte, so an every-spin query put that scan inside the control
    /// loop. Since E5 the query is capped at the declared minimum, so a scan
    /// reads at most that many bytes.
    /// Nothing at all when no minimum was declared.
    fn check_stack_headroom_rule(&mut self) {
        if self.min_stack_headroom_bytes == 0 {
            return;
        }
        self.stack_headroom_spins_since_check =
            self.stack_headroom_spins_since_check.saturating_add(1);
        let now_us = self.now_us();
        if !super::monitor::stack_headroom_check_due(
            now_us,
            self.stack_headroom_last_check_us,
            self.stack_headroom_spins_since_check,
        ) {
            return;
        }
        self.stack_headroom_last_check_us = Some(now_us.unwrap_or(0));
        self.stack_headroom_spins_since_check = 0;
        self.stack_headroom_checks = self.stack_headroom_checks.saturating_add(1);
        // phase-436 E5 -- the CAPPED query. The rule only asks whether
        // `min_stack_headroom_bytes` are unused, and a port that scans for
        // paint answers that by reading those bytes alone. Below the cap the
        // answer is the exact headroom, which is what a breach reports, so
        // no second, full scan is needed. E4's throttle still applies.
        let unused = nros_platform_api::stack_unused_bytes_upto(self.min_stack_headroom_bytes);
        // 0 means the port does not instrument stacks, not that the stack is
        // full. Reporting a violation there would be a fault invented from an
        // absence of data.
        if unused == 0 {
            return;
        }
        if let Some(v) = super::monitor::check_stack_headroom(
            unused,
            self.min_stack_headroom_bytes,
            &mut self.stack_headroom_reported,
        ) {
            self.violations.record(v);
        }
    }

    /// AUTOSAR-style ALIVE supervision: report a SchedContext that produced
    /// no dispatch at all over a full window while declaring a period.
    ///
    /// Every other rule here fires when something happens and is wrong. This
    /// one fires when nothing happens, which is the failure a watchdog
    /// exists for and the one `rate-hierarchy-runtime` cannot see: that rule
    /// counts publishes on an endpoint, so a callback that stops firing while
    /// its topic is published from elsewhere leaves it satisfied.
    fn check_alive_supervision(&mut self) {
        let Some(now_us) = self.now_us() else {
            // No clock, no windows. Silence here is honest: the rule cannot
            // tell a stalled context from a fast one without time.
            return;
        };
        let n = self.alive_slots.len().min(self.sched_contexts.len());
        for i in 0..n {
            let period_us = match self.sched_contexts[i].as_ref() {
                Some(sc) => sc.period_us.get().map(|nz| nz.get() as u64).unwrap_or(0),
                None => continue,
            };
            let slot = &mut self.alive_slots[i];
            if let Some(v) =
                super::monitor::check_alive(period_us, slot.dispatches, &mut slot.state, now_us)
            {
                self.violations.record(v);
            }
        }
    }

    /// Issue #515 — report a spin wake a whole period late.
    ///
    /// Runs on the same tick as `check_timer_overruns` and feeds the same
    /// ring, so the entry glue drains it with the other rules and no caller
    /// needs to know this one exists. Like that rule it needs no spec table:
    /// the bound is the spin period the caller already passes in.
    fn check_release_jitter_rule(&mut self) {
        let (max_us, _late, _total) = self.release_jitter();
        let period_us = self.spin_nominal_us;
        if let Some(v) =
            super::monitor::check_release_jitter(max_us, &mut self.jitter_reported_us, period_us)
        {
            self.violations.record(v);
        }
    }

    fn check_timer_overruns(&mut self) {
        let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
        for i in 0..self.entries.len() {
            let Some(meta) = self.entries[i].as_ref() else {
                continue;
            };
            if !matches!(meta.kind, EntryKind::Timer) {
                continue;
            }
            // SAFETY: a Timer entry's arena slot holds a `TimerEntry<F>`,
            // which shares its leading layout with `TimerHeader`. The
            // baseline lives in the header too, so this needs no state
            // parallel to `entries` (whose capacity is a runtime slice
            // length, not a const).
            let header = unsafe { &mut *(arena_ptr.add(meta.offset) as *mut TimerHeader) };
            if let Some(v) = super::monitor::check_timer_overrun(
                header.overruns,
                &mut header.overruns_reported,
                0,
            ) {
                self.violations.record(v);
            }
        }
    }

    /// RFC-0052 / phase-296 W3a — replace the DEFAULT scheduling context
    /// (slot 0, the SC every unbound callback dispatches through).
    ///
    /// The run_tiers model runs one Executor per tier, so a tier-wide
    /// scheduling policy (`[tiers.<t>] class/budget_us/period_us` and the
    /// TT window) is exactly "this executor's default SC". Boards call
    /// this once, before entity creation; explicit per-handle/per-group
    /// bindings still take precedence (they never resolve to slot 0).
    ///
    /// Sporadic-class SCs get the same sibling `SporadicState` the
    /// `create_sched_context` path builds, so budget refill/exhaustion
    /// applies to the default queue too.
    pub fn set_default_sched_context(&mut self, sc: super::sched_context::SchedContext) {
        self.sched_contexts[0] = Some(sc);
        if matches!(sc.class, super::sched_context::SchedClass::Sporadic) {
            let budget = sc.budget_us.get().map(|nz| nz.get()).unwrap_or(u32::MAX);
            let period = sc.period_us.get().map(|nz| nz.get()).unwrap_or(u32::MAX);
            self.sporadic_states[0] =
                Some(super::sched_context::SporadicState::new(budget, period));
        } else {
            self.sporadic_states[0] = None;
        }
    }

    /// Bind a registered callback to a scheduling context. The next
    /// `spin_once` cycle dispatches the callback through that SC's
    /// queue (FIFO bitmap or EDF heap). Phase 110.B.
    pub fn bind_handle_to_sched_context(
        &mut self,
        handle: HandleId,
        sc_id: super::sched_context::SchedContextId,
    ) -> Result<(), NodeError> {
        let i = self.live_slot(handle);
        if i >= self.entries.len() {
            return Err(NodeError::InvalidSchedContextBinding);
        }
        if self.entries[i].is_none() {
            return Err(NodeError::InvalidSchedContextBinding);
        }
        let sc_idx = sc_id.0 as usize;
        if sc_idx >= self.sched_contexts.len() || self.sched_contexts[sc_idx].is_none() {
            return Err(NodeError::InvalidSchedContextBinding);
        }
        self.sched_context_bindings[i] = sc_id;
        Ok(())
    }

    /// Phase 110.F — opt in to per-callback OS-priority dispatch.
    /// Once registered, every `spin_once` cycle routes ready entries
    /// whose bound SC has `os_pri > 0` onto a worker thread the OS
    /// scheduler has elevated to that numeric priority. Workers are
    /// spawned lazily on first use and self-halt when the Executor
    /// drops.
    ///
    /// `apply_policy` is the same `fn(SchedPolicy) -> Result<(),
    /// SchedError>` shape `open_threaded` takes — keeps the
    /// Executor non-generic over Platform.
    ///
    /// Calling this with `apply_policy = noop` is fine for testing
    /// (workers spawn but don't actually elevate priority); real
    /// hard-RT use needs `CAP_SYS_NICE` on Linux or the equivalent
    /// kernel config on RTOSes.
    #[cfg(all(feature = "alloc", feature = "scheduler-os-priority"))]
    pub fn register_os_priority_dispatcher(
        &mut self,
        apply_policy: fn(
            nros_platform_api::SchedPolicy,
        ) -> Result<(), nros_platform_api::SchedError>,
    ) {
        self.os_priority_apply_policy = Some(apply_policy);
    }

    /// Phase 110.G — enable time-triggered dispatch by setting the
    /// executor's major-frame length. Once set, every `spin_once`
    /// cycle gates dispatch through each entry's bound SC's
    /// `tt_window_offset_us` / `tt_window_duration_us` fields:
    /// dispatch only fires when the current monotonic time falls
    /// inside the window `[off, off + duration) mod major_frame`.
    ///
    /// `major_frame_us = 0` disables the TT gate (default state).
    /// Setting a non-zero major frame after callbacks are already
    /// registered is allowed — TT gates take effect on the next
    /// `spin_once` cycle.
    pub fn register_time_triggered_dispatcher(&mut self, major_frame_us: u32) {
        self.major_frame_us = major_frame_us;
    }

    /// Phase 110.G — apply a declarative cyclic schedule.
    ///
    /// One-shot helper that wraps the underlying primitives:
    /// validates the schedule (`major_frame > 0`, no overlapping
    /// windows, every window fits inside the major frame), sets the
    /// executor's major-frame length, then materialises one
    /// `SchedContext` per window with `class = TimeTriggered` +
    /// the window's offset / duration. Returns the per-window
    /// [`SchedContextId`](crate::executor::sched_context::SchedContextId) array so callers can immediately
    /// `bind_handle_to_sched_context(handle, sc_id)` for their
    /// subscription / timer handles.
    ///
    /// `N` is the schedule's *declared* maximum window count;
    /// `schedule.window_count` gates how many SCs are actually
    /// created. Unused trailing slots return
    /// `SchedContextId::default()` (sentinel — callers must respect
    /// `window_count`).
    pub fn apply_time_triggered_schedule<const N: usize>(
        &mut self,
        schedule: &super::sched_context::TimeTriggeredSchedule<N>,
    ) -> Result<
        [super::sched_context::SchedContextId; N],
        super::sched_context::TimeTriggeredScheduleError,
    > {
        schedule.validate()?;
        self.major_frame_us = schedule.major_frame_us;
        // SC slot 0 is the auto-created default; reusing it as a
        // sentinel for unused trailing slots is safe because the
        // caller respects `schedule.window_count`.
        let mut ids: [super::sched_context::SchedContextId; N] =
            [super::sched_context::SchedContextId(0); N];
        for (i, window) in schedule.windows[..schedule.window_count].iter().enumerate() {
            // TT is not a scheduling class (phase-482 W6 deleted the
            // `SchedClass::TimeTriggered` variant): it is a per-SC *window gate* on top of
            // the existing class-based dispatch (Fifo here keeps
            // the EDF / Sporadic budgets out of the picture for
            // pure cyclic schedules). The window-gate fields set
            // below are what `spin_once`'s 110.G runtime gate
            // actually reads.
            let sc = super::sched_context::SchedContext {
                tt_window_offset_us: super::sched_context::OptUs::from_us(window.offset_us),
                tt_window_duration_us: super::sched_context::OptUs::from_us(window.duration_us),
                ..super::sched_context::SchedContext::new_fifo()
            };
            ids[i] = self.create_sched_context(sc).map_err(|_| {
                super::sched_context::TimeTriggeredScheduleError::WindowCountOverflow
            })?;
        }
        Ok(ids)
    }

    /// Phase 110.E.b — register an ISR-driven refill timer for an
    /// already-created Sporadic SC. The caller invokes their
    /// platform's `PlatformTimer::create_periodic` with the returned
    /// `Arc<AtomicSporadicState>` as `user_data` and the
    /// `atomic_sporadic_refill_thunk` as the callback, then hands
    /// the resulting platform handle to this method via
    /// `OpaqueTimerHandle::new(handle, destroy_fn)`.
    ///
    /// The Executor stores both the Arc and the handle so Drop can
    /// clean them up. Calling this on a non-Sporadic SC returns
    /// `Err(InvalidSchedContextBinding)`.
    #[cfg(feature = "alloc")]
    pub fn register_sporadic_timer(
        &mut self,
        sc_id: super::sched_context::SchedContextId,
        timer: OpaqueTimerHandle,
    ) -> Result<portable_atomic_util::Arc<super::sched_context::AtomicSporadicState>, NodeError>
    {
        let i = sc_id.0 as usize;
        if i >= self.sched_contexts.len() {
            return Err(NodeError::InvalidSchedContextBinding);
        }
        let sc = self.sched_contexts[i]
            .as_ref()
            .ok_or(NodeError::InvalidSchedContextBinding)?;
        if !matches!(sc.class, super::sched_context::SchedClass::Sporadic) {
            return Err(NodeError::InvalidSchedContextBinding);
        }
        let budget = sc.budget_us.get().map(|nz| nz.get()).unwrap_or(u32::MAX);
        let period = sc.period_us.get().map(|nz| nz.get()).unwrap_or(u32::MAX);
        let state = portable_atomic_util::Arc::new(super::sched_context::AtomicSporadicState::new(
            budget, period,
        ));
        self.sporadic_atomic_states[i] = Some((portable_atomic_util::Arc::clone(&state), timer));
        Ok(state)
    }

    /// Inspect a registered scheduling context. Phase 110.B.
    pub fn sched_context(
        &self,
        sc_id: super::sched_context::SchedContextId,
    ) -> Option<&super::sched_context::SchedContext> {
        self.sched_contexts.get(sc_id.0 as usize)?.as_ref()
    }

    /// Phase 104.C.2 — start a rclcpp-style Node builder for this
    /// Executor. The returned [`NodeBuilder`](super::node_record::NodeBuilder)
    /// is chainable:
    ///
    /// ```ignore
    /// let id = exec.node_builder("ingress")
    ///     .rmw("zenoh")
    ///     .locator("tcp/127.0.0.1:7447")
    ///     .sched(my_sc_id)
    ///     .build()?;
    /// ```
    ///
    /// In Phase 104.C.2 the Node table is storage-only — all
    /// registered Nodes share the Executor's primary session. Per-
    /// Node session binding (the bridge feature) lands in Phase
    /// 104.C.3 when the session cache is wired.
    pub fn node_builder<'a, 'cfg>(
        &'a mut self,
        name: &'cfg str,
    ) -> super::node_record::NodeBuilder<'a, 'cfg, 's> {
        super::node_record::NodeBuilder {
            executor: self,
            name,
            namespace: None,
            rmw_name: None,
            locator: None,
            domain_id: None,
            sched: None,
            session_idx: None,
        }
    }

    /// Return the Node table — Phase 104.C.2 read accessor.
    pub fn nodes(&self) -> &[super::node_record::NodeRecord] {
        &self.nodes
    }

    /// Borrow a Node's metadata by id, returning `None` if the id
    /// is out of range.
    pub fn node(&self, id: super::node_record::NodeId) -> Option<&super::node_record::NodeRecord> {
        self.nodes.get(id.index())
    }

    /// Phase 189.M1 — an executor-borrowing node handle for the entity builders
    /// (`exec.node_mut(id).subscription(t)...` / `.create_subscription(...)`).
    /// A short-lived `&mut Executor` borrow — use one at a time; entity handles
    /// are owned and outlive it (see `Node`).
    /// phase-483 W3 — the component registration frame, for the `nros`
    /// facade's declarative constructors. Not a user API.
    #[doc(hidden)]
    pub fn __component_frame(&self) -> Option<core::ptr::NonNull<()>> {
        self.component_frame
    }

    /// phase-483 W3 — install or clear the component registration frame.
    /// The caller guarantees the pointee outlives the installation.
    #[doc(hidden)]
    pub fn __set_component_frame(&mut self, frame: Option<core::ptr::NonNull<()>>) {
        self.component_frame = frame;
    }

    pub fn node_mut(&mut self, id: super::node_record::NodeId) -> super::node::Node<'_, 's> {
        super::node::Node::new(self, id)
    }

    /// Issue #52 — install the baked QoS-override table on one node. Every
    /// entity created on it AFTERWARDS folds the matching `(topic, role)`
    /// entries into its QoS, before the backend-compat check — so an override
    /// the active RMW cannot honour still errors loudly rather than silently
    /// downgrading.
    ///
    /// Called by the generated entry (`nros::main!` → the register seam) right
    /// after the node is created and before the component declares entities.
    /// Unknown `node_id` is a no-op.
    pub fn set_node_qos_overrides(
        &mut self,
        node_id: super::node_record::NodeId,
        overrides: &'static [super::node_record::QoSOverrideCode],
    ) {
        if let Some(r) = self.nodes.get_mut(node_id.index()) {
            r.qos_overrides = overrides;
        }
    }

    /// Phase 104.C.3 — resolve a session-slot index to a mutable
    /// session reference. Slot 0 = the Executor's primary session;
    /// slots 1..=N = the `extra_sessions` vec opened by
    /// `node_builder.rmw(name)` calls that named a backend
    /// different from the primary.
    pub(crate) fn session_at_mut(&mut self, idx: u8) -> Option<&mut session::ConcreteSession> {
        if idx == 0 {
            Some(&mut *self.session)
        } else {
            self.extra_sessions.get_mut((idx - 1) as usize)
        }
    }

    /// [`Self::session_at_mut`] plus a shared borrow of the remap table, for
    /// building a [`NodeHandle`] — which needs both at once, and gets them
    /// here as two disjoint field borrows rather than through two `&mut self`
    /// calls the borrow checker could not split.
    pub(crate) fn session_and_remaps_at_mut(
        &mut self,
        idx: u8,
    ) -> Option<(&mut session::ConcreteSession, &[Option<RemapRule>])> {
        let remaps = &self.remap_table[..self.remap_len];
        let session = if idx == 0 {
            Some(&mut *self.session)
        } else {
            self.extra_sessions.get_mut((idx - 1) as usize)
        };
        session.map(|s| (s, remaps))
    }

    /// Phase 104.C.9.b — resolve the per-Node session for direct
    /// entity creation paths (C++ FFI publisher / subscription /
    /// service that bypass the `register_*_on` arena dispatch).
    /// Returns `None` when `node_id` is out of range or the Node's
    /// `session_idx` lands outside the executor's session table.
    pub fn node_session_mut(
        &mut self,
        node_id: super::node_record::NodeId,
    ) -> Option<&mut session::ConcreteSession> {
        let session_idx = self.nodes.get(node_id.index())?.session_idx;
        self.session_at_mut(session_idx)
    }

    /// Phase 189.M1 — create a typed publisher bound to a node's session.
    /// Backs `node.publisher(t).typed::<M>().build()` on the
    /// executor-borrowing [`Node`](super::node::Node); the returned
    /// handle is owned and outlives the `Node`.
    pub fn create_publisher_on<M: crate::rmw_type_registry::MessageForRmw>(
        &mut self,
        node_id: super::node_record::NodeId,
        topic_name: &str,
        qos: QoSProfile,
    ) -> Result<crate::executor::handles::EmbeddedPublisher<M>, NodeError> {
        // RFC-0088 / phase-421 W1 — the message's declared format must be the
        // one the linked backend speaks. Universal: the const lives on
        // `RosMessage`, which `MessageForRmw` requires under every backend.
        crate::format_check::assert_message_format::<M>();
        // Phase 212.K.7.6.b — register `M`'s cyclonedds descriptor before
        // creating the underlying publisher handle. No-op for other RMWs.
        crate::rmw_type_registry::register_type::<M>()?;
        let handle = self.create_raw_publisher_handle_on(
            node_id,
            topic_name,
            <M as RosMessage>::TYPE_NAME,
            <M as RosMessage>::TYPE_HASH,
            qos,
        )?;
        // RFC-0052 W3b.4 — attach the contracted endpoint's counter cell.
        let monitor = self
            .monitor_table
            .iter()
            .find(|m| m.topic == topic_name)
            .map(|m| m.cell);
        Ok(crate::executor::handles::EmbeddedPublisher {
            handle,
            event_regs: crate::executor::handles::empty_event_regs(),
            monitor,
            epoch: self.epoch_us_fn,
            _phantom: PhantomData,
        })
    }

    /// Phase 189.M1 — create a generic (type-erased) publisher bound to a
    /// node's session. Backs `node.publisher(t).generic(ty, hash).build()`;
    /// the bridge re-publishes through this handle on the dest session.
    pub fn create_publisher_raw_on(
        &mut self,
        node_id: super::node_record::NodeId,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
    ) -> Result<crate::executor::handles::EmbeddedRawPublisher, NodeError> {
        let handle =
            self.create_raw_publisher_handle_on(node_id, topic_name, type_name, type_hash, qos)?;
        Ok(crate::executor::handles::EmbeddedRawPublisher {
            handle,
            arena: crate::executor::handles::TxArena::new(),
            event_regs: crate::executor::handles::empty_event_regs(),
            // Issue 1676 — attach the contracted endpoint's counter cell by
            // exact topic match against the installed table, the rule
            // `NodeHandle::create_publisher` applies. This is the publisher
            // the Rust component road creates, so without it no contracted
            // Rust publisher was ever counted.
            monitor: self.publisher_monitor_cell(topic_name),
        })
    }

    /// Shared prelude for the publisher-on-node paths: resolve the node's
    /// identity + session slot, build the [`TopicInfo`], validate QoS, and
    /// create the backend publisher handle. Mirrors
    /// `register_subscription_buffered_raw_on`'s session resolution so a
    /// bridge's source sub + dest pub agree on topic construction.
    fn create_raw_publisher_handle_on(
        &mut self,
        node_id: super::node_record::NodeId,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
    ) -> Result<session::RmwPublisher, NodeError> {
        let (node_name, ns, session_idx, overrides) = {
            let r = self
                .nodes
                .get(node_id.index())
                .ok_or(NodeError::InvalidSchedContextBinding)?;
            (
                r.name.clone(),
                r.namespace.clone(),
                r.session_idx,
                r.qos_overrides,
            )
        };
        // Issue #52 — fold the node's baked overrides for this topic BEFORE
        // `validate_against`, so an override the backend cannot honour errors
        // loudly instead of being silently dropped.
        let qos = super::node_record::apply_qos_override_codes(
            qos,
            topic_name,
            nros_rmw::QoSOverrideRole::Publisher,
            overrides,
        );
        let mut topic = TopicInfo::new(topic_name, type_name, type_hash)
            .with_domain(self.domain_id)
            .with_namespace(&ns);
        if !node_name.is_empty() {
            topic = topic.with_node_name(&node_name);
        }
        // issue 1608 -- the publisher half of the declared-QoS check, before
        // validation so a policy the contract raises this publisher to is one
        // the backend is asked about. See `declared_qos::honour_publisher`.
        let qos = crate::declared_qos::honour_publisher(topic.type_name, topic.name, qos)?;
        let session = self
            .session_at_mut(session_idx)
            .ok_or(NodeError::BackendMismatch)?;
        super::node::validate_qos_or_report(
            &qos,
            Session::supported_qos_policies(session),
            "publisher",
            topic_name,
        )?;
        session
            .create_publisher(&topic, qos)
            .map_err(|_| NodeError::Transport(TransportError::PublisherCreationFailed))
    }

    /// Phase 124.B.1 — install the executor's wake callback onto the
    /// primary session. Best-effort: backends that don't override
    /// `Session::set_wake_callback` (poll-only XRCE, bare-metal)
    /// ignore the call and continue to be drained on the executor's
    /// deadline-bound cv-wait boundary.
    ///
    /// `pub` for issue 1385, and for the same reason
    /// [`set_primary_identity`](Self::set_primary_identity) is: the three
    /// `Executor::open*` paths call this automatically, and a binding that
    /// builds its executor over a session it BORROWS
    /// ([`from_session_ptr_in`](Self::from_session_ptr_in)) reaches none of
    /// them, so it has to call it itself. `rclc_executor_init` is that
    /// binding, and until 1385 it did not — leaving `has_async_wake` false
    /// for the life of every C executor on every backend.
    ///
    /// Pairs with `clear_wake_signal`, which the
    /// executor runs from `close()` and from `drop`. A caller that installs
    /// owes nothing further: the teardown is the executor's.
    ///
    /// phase-436 — the backend's slot holds a `WakeFanout`
    /// and this executor JOINS it, so every executor over one session is woken
    /// by an arrival: the boot executor and each spawned tier
    /// (`open_with_session*` now installs too), or several C executors over
    /// one support context. Idempotent. If the fan-out pool is exhausted the
    /// executor installs its own context directly, as before; if the entry's
    /// member table is full it joins nothing and reads as having no async
    /// wake, so it never parks on a wake nobody will signal.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub fn install_wake_signal_on_primary(&mut self) {
        use nros_rmw::Session as _;
        if self.wake_membership.is_some() {
            return;
        }
        let ctx = self.wake_ctx_ptr();
        let key = self.session_ptr() as *mut core::ffi::c_void;
        let supports = self.session.supports_wake_callback();
        let fanout = match super::wake_fanout::find(key) {
            Some(f) => Some(f),
            None => super::wake_fanout::claim(key).inspect(|f| {
                f.set_live(supports);
                // SAFETY: the context is a `static` pool entry, valid for the
                // program's life; `clear_wake_signal` takes the callback off
                // before returning the entry to the pool.
                unsafe {
                    self.session
                        .set_wake_callback(Some(nros_rmw_fanout_wake_cb), f.as_ctx());
                }
            }),
        };
        match fanout {
            Some(f) => {
                if let Some(m) = f.join(ctx) {
                    self.wake_membership = Some(m);
                    // Issue 1385 — this executor now owes a teardown: leaving
                    // the fan-out (and, for the session's owner or its last
                    // member, taking the callback off the backend).
                    self.wake_cb_installed = true;
                }
            }
            None => {
                // SAFETY: `ctx` points at executor-owned wake state that
                // outlives the installation and is cleared by
                // `clear_wake_signal` on `close()`/drop.
                unsafe {
                    self.session
                        .set_wake_callback(Some(nros_rmw_runtime_wake_cb), ctx);
                }
                self.wake_cb_installed = true;
                if supports {
                    self.has_async_wake = true;
                }
            }
        }
    }

    /// phase-436 — does an arrival on any of this executor's sessions signal
    /// its wake object? Through the primary's fan-out (live until the
    /// session's owner takes the callback down), or a direct install on the
    /// primary or an extra session.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) fn async_wake_live(&self) -> bool {
        self.has_async_wake || self.wake_membership.is_some_and(|m| m.is_live())
    }

    /// Phase 124.B.1 — install the wake callback onto an extra
    /// session opened by `node_builder.rmw(...)`. Called from
    /// `NodeBuilder::build()` right after `extra_sessions.push(...)`.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) fn install_wake_signal_on_extra(&mut self, idx: usize) {
        use nros_rmw::Session as _;
        let ctx = self.wake_ctx_ptr();
        if let Some(s) = self.extra_sessions.get_mut(idx) {
            // SAFETY: same executor-owned wake state as the primary session;
            // the extra session is owned by this executor.
            unsafe {
                s.set_wake_callback(Some(nros_rmw_runtime_wake_cb), ctx);
            }
            // Issue 1385 — as on the primary.
            self.wake_cb_installed = true;
            if s.supports_wake_callback() {
                self.has_async_wake = true;
            }
        }
    }

    /// Issue 1385 — the teardown half of `install_wake_signal_on_*`, and the
    /// obligation `nros_rmw_runtime_wake_cb`'s own SAFETY comment has asserted
    /// since phase 124: *"Executor::drop must clear the callback via
    /// `set_wake_callback(None, _)` on all sessions before dropping
    /// wake_ctx"*. Nothing did. The string `set_wake_callback(None` occurred
    /// exactly once in the tree — in that comment.
    ///
    /// The context the backend holds is `Arc::as_ptr(&self.wake_ctx)`, freed
    /// with this executor. Leaving it installed is a dangling callback the
    /// backend may invoke from a worker thread or an ISR. On the Rust `open*`
    /// paths the session is `SessionStore::Owned` and dies in the same drop,
    /// so the window is narrow; on the C path it is arbitrary —
    /// `rclc_executor_fini` drops the executor and zero-fills `_opaque` while
    /// the session lives on in `rclc_support_t` until `rclc_support_fini`.
    ///
    /// Clears the primary and every extra session, then latches off, so
    /// `close()` followed by drop clears once.
    ///
    /// Only fires when THIS executor installed (see
    /// `install_wake_signal_on_primary`). Executors sharing one session were
    /// last-writer-wins on the backend's single slot until phase-436: the first
    /// to tear down cleared the other's wake. The slot now holds a wake
    /// fan-out, so a member's teardown is leaving it, and the callback comes
    /// off the backend only with the session's owner or its last member.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) fn clear_wake_signal(&mut self) {
        use nros_rmw::Session as _;
        if !self.wake_cb_installed {
            return;
        }
        self.wake_cb_installed = false;
        // phase-436 — a fan-out member leaves first; the callback comes off
        // the backend only when the session's OWNER leaves (the session dies
        // with it) or the last member does. A membership from an entry the
        // owner already released is a no-op, and must not touch the entry's
        // next tenant.
        let take_off_primary = match self.wake_membership.take() {
            Some(m) => {
                let fanout = m.fanout();
                let current = m.is_current();
                m.leave(nros_platform_api::yield_now);
                let owned = matches!(self.session, SessionStore::Owned(_));
                if current && (owned || fanout.member_count() == 0) {
                    // SAFETY: as below; the entry is released only after the
                    // backend can no longer start a callback on it.
                    unsafe { self.session.set_wake_callback(None, core::ptr::null_mut()) };
                    fanout.release(nros_platform_api::yield_now);
                }
                false
            }
            None => true,
        };
        // SAFETY: clearing takes no context, and both sessions are still live
        // here — this runs BEFORE `Session::close` in `close()` and before the
        // session field is dropped in `Drop`.
        unsafe {
            if take_off_primary {
                self.session.set_wake_callback(None, core::ptr::null_mut());
            }
            for s in self.extra_sessions.iter_mut() {
                s.set_wake_callback(None, core::ptr::null_mut());
            }
        }
        self.has_async_wake = false;
    }

    /// phase-467 Row 8 — hand the PRIMARY session a graph-change target it may
    /// trigger from a worker thread, and take ownership of that target.
    ///
    /// The install half of the pair; [`clear_graph_change_signal`] is the
    /// other and the executor owes it. `guard` is CLONED, so the caller keeps
    /// its own handle to the same arena flag — that is the whole point: the
    /// pointer the backend receives is the executor's box, never the caller's
    /// storage. Issue 1385 is the same hazard on the wake slot, found after
    /// the fact; this is the shape that cannot reach it.
    ///
    /// PRIMARY only, deliberately. A graph is a property of a session, and the
    /// extra sessions of `node_builder.rmw(...)` each have their own — feeding
    /// several into one guard would make "the graph changed" unattributable
    /// while costing the caller the ability to ask which. A caller wanting a
    /// second backend's graph asks that session for its own.
    ///
    /// Returns `Err(Unsupported)` from a backend with no graph. A previously
    /// installed target is retired first, so an executor never has two.
    ///
    /// [`clear_graph_change_signal`]: Self::clear_graph_change_signal
    ///
    /// `pub(crate)`, not `pub`: the public verb is
    /// [`register_graph_change_guard_on`], which does the probe, the
    /// registration and this in the one order that cannot hand back a guard
    /// nothing fires. Exposing the install alone would let a caller reach the
    /// second step without the first.
    ///
    /// [`register_graph_change_guard_on`]: Self::register_graph_change_guard_on
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) fn install_graph_change_guard(
        &mut self,
        guard: &GuardCondition,
    ) -> Result<(), NodeError> {
        use nros_rmw::Session as _;
        self.clear_graph_change_signal();
        let boxed = alloc::boxed::Box::new(guard.clone());
        let ptr = (&*boxed) as *const GuardCondition as *const core::ffi::c_void;
        // SAFETY: `ptr` names heap storage this executor owns and which
        // `clear_graph_change_signal` retires from the backend before it is
        // freed. `GuardCondition` is `Send + Sync` and its `trigger()` is a
        // relaxed store plus the runtime wake hook, which is what a foreign
        // thread is allowed to do here.
        let rc = unsafe {
            self.session
                .set_graph_change_callback(Some(nros_rmw_runtime_graph_change_cb), ptr)
        };
        match rc {
            Ok(()) => {
                self.graph_change_target = Some(boxed);
                Ok(())
            }
            // `boxed` drops here, and nothing holds its pointer: the backend
            // either refused or failed, so there is no installed callback to
            // retire first.
            Err(e) => Err(NodeError::Transport(e)),
        }
    }

    /// phase-467 Row 8 — can the primary session deliver a graph-change edge?
    ///
    /// Asked by CLEARING, which is the one probe that costs nothing and cannot
    /// lie: a backend with no graph answers `Unsupported` to a `None` install
    /// just as it does to a real one, and an idempotent clear on a backend
    /// that HAS a graph is a no-op. Nullity of the vtable slot cannot answer
    /// it — `rust_adapter.rs` fills the slot for every Rust backend whether or
    /// not that backend overrides the trait method, which
    /// `check-rmw-slot-producers`'s own report says in as many words.
    ///
    /// The caller is `register_graph_change_guard_on`, which asks BEFORE it
    /// consumes an executor handle slot, so an unsupported backend costs
    /// nothing and the caller is never handed a guard nothing fires.
    /// `pub(crate)` for the same reason the install is: asking costs a CLEAR,
    /// so a caller that asks and then does nothing has silently retired a live
    /// target. The public verb asks once, on the caller's behalf.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) fn supports_graph_change_callback(&mut self) -> bool {
        use nros_rmw::Session as _;
        // Retire whatever is installed first — the probe IS a clear, so doing
        // it without this would silently drop a live target.
        self.clear_graph_change_signal();
        // SAFETY: a `None` install takes no context and installs nothing.
        unsafe {
            self.session
                .set_graph_change_callback(None, core::ptr::null())
                .is_ok()
        }
    }

    /// phase-467 Row 8 — the teardown half of
    /// [`install_graph_change_guard`](Self::install_graph_change_guard), and
    /// the reason that install cannot recreate issue 1385.
    ///
    /// Order is the whole content: tell the backend to stop FIRST, then drop
    /// the box it was pointing at. Reversed, the window between the free and
    /// the clear is exactly 1385's dangling callback — and on the C path that
    /// window is arbitrary, because the session outlives the executor.
    ///
    /// Latched on `graph_change_target.is_some()`, not on a separate flag: the
    /// box IS the record of having installed, so `close()` followed by drop
    /// clears once and an executor that never installed clears nothing. That
    /// is the same predicate `clear_wake_signal` needs a bool for only because
    /// its context is shared with `signal_fd()` and every guard condition.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub(crate) fn clear_graph_change_signal(&mut self) {
        use nros_rmw::Session as _;
        if self.graph_change_target.is_none() {
            return;
        }
        // SAFETY: clearing takes no context, and the session is still live
        // here — this runs BEFORE `Session::close` in `close()` and before the
        // session field is dropped in `Drop`.
        unsafe {
            let _ = self
                .session
                .set_graph_change_callback(None, core::ptr::null());
        }
        // Only now. The backend has been told, so nothing can be holding this
        // pointer when it is freed.
        self.graph_change_target = None;
    }

    /// Phase 124.B.2 — opaque context pointer the runtime wake
    /// callback receives. Encodes `(flag, mu, cv)` as a borrowed
    /// `&WakeCtx` reference; the callback decodes via
    /// `*const WakeCtx`.
    ///
    /// Lifetime: tied to the Executor instance. WakeCtx storage
    /// lives inside Executor (lazy-allocated on first install), so
    /// the pointer stays valid as long as the Executor is.
    /// Phase 124.B.7.c — POSIX signal-handler-safe wake fd.
    ///
    /// Returns a Linux `eventfd` that callers (typically POSIX
    /// signal handlers) can `write(fd, &1u64, 8)` to from any
    /// context, including signal handlers. A runtime-owned worker
    /// thread reads the fd and signals `wake_cv`, unblocking
    /// `spin_once`.
    ///
    /// The worker thread is spawned lazily on first call and
    /// joined on Executor drop. Linux-only and gated behind
    /// `feature = "signal-fd-wake"`; binaries that don't install
    /// signal handlers shouldn't enable it.
    ///
    /// Returns the raw fd. The Executor retains ownership; do not
    /// `close()` it from the caller.
    #[cfg(all(feature = "signal-fd-wake", feature = "rmw-cffi", target_os = "linux"))]
    /// phase-359 W10 — was `std::io::Result`. Same values, an error type that
    /// does not require `std`.
    pub fn signal_fd(&mut self) -> Result<core::ffi::c_int, NodeError> {
        let ctx_ptr = self.wake_ctx_ptr() as *const WakeCtx;
        if self.signal_fd.is_none() {
            self.signal_fd = Some(WakeSignalFd::new(ctx_ptr)?);
        }
        Ok(self.signal_fd.as_ref().expect("just set").fd())
    }

    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    fn wake_ctx_ptr(&mut self) -> *mut core::ffi::c_void {
        if self.wake_ctx.is_none() {
            self.wake_ctx = Some(portable_atomic_util::Arc::new(WakeCtx {
                flag: self.wake_flag.clone(),
                node_wake: self.node_wake.clone(),
            }));
        }
        let arc = self.wake_ctx.as_ref().expect("just set");
        portable_atomic_util::Arc::as_ptr(arc) as *mut core::ffi::c_void
    }

    /// Phase 104.C.4 — apply a Node's default SchedContext to a
    /// freshly-registered handle. Called from every `_inner`
    /// register variant after the entry slot is committed. No-op
    /// when `node_id` is None (legacy path), when the Node is
    /// out of range, or when the Node's `default_sched` is the
    /// auto-created Fifo slot (0) which matches the executor's
    /// default binding already.
    ///
    /// Phase 273 (RFC-0047) — extends with an optional `group` name.
    /// Precedence: **group table > node default > no binding** (SC 0).
    /// When `group` is `Some(g)`, consults `group_sched_table` first;
    /// if no entry exists for `(name, namespace, g)` falls back to the
    /// node's `default_sched`. When `group` is `None` the group table
    /// is not consulted (unchanged phase-272 path).
    ///
    /// Handles can still override per-call via
    /// `bind_handle_to_sched_context(handle, sc_id)` post-register.
    pub(crate) fn apply_node_default_sched(
        &mut self,
        slot: usize,
        node_id: Option<super::node_record::NodeId>,
        group: Option<&str>,
    ) {
        let Some(id) = node_id else { return };
        // Copy name, namespace, and default_sched out so the borrow on
        // `self.nodes` is released before the immutable `lookup_group_sched`
        // borrow and the mutable `sched_context_bindings` write below.
        let (name, namespace, node_sc) = {
            let Some(rec) = self.nodes.get(id.index()) else {
                return;
            };
            (rec.name.clone(), rec.namespace.clone(), rec.default_sched)
        };
        // Phase 273: group table > node default.
        let sc = match group {
            Some(g) => self
                .lookup_group_sched(name.as_str(), namespace.as_str(), g)
                .unwrap_or(node_sc),
            None => node_sc,
        };
        if sc.0 == 0 {
            return;
        }
        if slot >= self.entries.len() {
            return;
        }
        let sc_idx = sc.0 as usize;
        if sc_idx >= self.sched_contexts.len() || self.sched_contexts[sc_idx].is_none() {
            return;
        }
        self.sched_context_bindings[slot] = sc;
    }

    /// Phase 104.C.3.2 — scoped Node-handle access. The closure
    /// receives a [`NodeHandle`](crate::executor::NodeHandle) bound to the
    /// requested [`NodeId`](crate::executor::NodeId)'s
    /// session + identity. Use the standard `Node::create_publisher`,
    /// `create_subscription`, etc. APIs inside.
    ///
    /// rclcpp-aligned bridge pattern:
    ///
    /// ```ignore
    /// let node_in = exec.node_builder("ingress").rmw("zenoh").build()?;
    /// let node_out = exec.node_builder("egress").rmw("xrce").build()?;
    ///
    /// let pub_out = exec.with_node(node_out, |n| {
    ///     n.create_publisher::<Int32>("/fwd")
    /// })??;
    ///
    /// exec.with_node(node_in, |n| {
    ///     n.create_subscription_buffered::<Int32, _, 1024>(
    ///         "/src", qos(), move |m| { let _ = pub_out.publish(m); }
    ///     )
    /// })??;
    /// ```
    ///
    /// The closure can return any type; double-`?` unwraps the
    /// outer `Result<R, NodeError>` from `with_node` and the inner
    /// result returned by the closure.
    /// Phase 104.C.3.3.d — flat-Result variant of
    /// [`with_node`](Self::with_node). When the closure already
    /// returns `Result<R, NodeError>`, this avoids the double-`?`:
    ///
    /// ```ignore
    /// // Without `with_node_try`:
    /// let pub_ = exec.with_node(id, |n| n.create_publisher(...))??;
    ///
    /// // With `with_node_try`:
    /// let pub_ = exec.with_node_try(id, |n| n.create_publisher(...))?;
    /// ```
    pub fn with_node_try<R>(
        &mut self,
        id: super::node_record::NodeId,
        f: impl FnOnce(&mut NodeHandle<'_>) -> Result<R, NodeError>,
    ) -> Result<R, NodeError> {
        self.with_node(id, f)?
    }

    pub fn with_node<R>(
        &mut self,
        id: super::node_record::NodeId,
        f: impl FnOnce(&mut NodeHandle<'_>) -> R,
    ) -> Result<R, NodeError> {
        let (name, ns, session_idx) = {
            let r = self
                .nodes
                .get(id.index())
                .ok_or(NodeError::InvalidSchedContextBinding)?;
            (r.name.clone(), r.namespace.clone(), r.session_idx)
        };
        let monitors = self.monitor_table;
        let age_monitors = self.age_table;
        let epoch = self.epoch_us_fn;
        let domain_id = self.domain_id;
        let (session, remaps) = self
            .session_and_remaps_at_mut(session_idx)
            .ok_or(NodeError::BackendMismatch)?;
        // SAFETY: short-lived scoped reference. `Node::new` takes
        // `&mut ConcreteSession`; lifetime is bound to this fn's
        // body via the closure's borrow of `node`.
        // issue 0801 (second half) — the executor's domain, NOT a literal 0.
        // 429d5a581 fixed the ELEVEN arena `TopicInfo`s and left the THREE
        // `NodeHandle::new` sites, so an entity created through a node HANDLE
        // (`with_node`, `node`, `node_on`) still declared on domain 0 while the
        // arena path declared on the configured one. Same split the issue is
        // about, one constructor over: `loan_e2e` publishes through a handle and
        // subscribes through the arena, so it delivered on domain 0 and on
        // nothing else.
        let mut node = NodeHandle::new(name, ns, session, remaps, domain_id);
        // RFC-0052 W3b.4/.5 — seed the baked monitor tables so contracted
        // publishers/subscribers attach their cells without entry glue.
        node.set_monitors(monitors);
        node.set_age_monitors(age_monitors, epoch);
        Ok(f(&mut node))
    }

    /// Find a registered executor node by final name and namespace.
    pub fn node_id_by_name(
        &self,
        name: &str,
        namespace: &str,
    ) -> Option<super::node_record::NodeId> {
        self.nodes
            .iter()
            .enumerate()
            .find(|(_, node)| node.name.as_str() == name && node.namespace.as_str() == namespace)
            .map(|(index, _)| super::node_record::NodeId::from_raw(index as u8))
    }

    /// Create a node on this executor.
    ///
    /// Registers the node in the executor's table, deduplicating on
    /// `(name, namespace)` — phase-376 W5/B1.
    ///
    /// # This is `rclrs::Executor::create_node`
    ///
    /// phase-427 W10 (RFC-0089 "Context and `init`, settled"). Same name, same
    /// place in the sequence — `Context` → executor → node — so a ported rclrs
    /// `main` lands here unchanged:
    ///
    /// ```ignore
    /// let context = nros::Context::default_from_env()?;
    /// let mut executor = context.create_executor()?;
    /// let mut node = executor.create_node("talker")?;
    /// ```
    ///
    /// Two differences from upstream, both structural and both named in the
    /// ledger row (`rust:Executor::create_node`): ours takes `&mut self`,
    /// because the node is registered in the executor's compile-time-sized
    /// table rather than allocated, and it hands back a borrowing
    /// [`NodeHandle`] rather than an `Arc<Node>`, because there is no
    /// allocator. Neither is silent — the compiler names both.
    ///
    /// The name comes from HERE, not from
    /// [`ExecutorConfig::node_name`](crate::ExecutorConfig::node_name), whose
    /// builder spelling is deprecated for exactly this reason: one executor
    /// holds several named nodes (RFC-0047), so a name on the session config
    /// can only ever describe the first of them.
    ///
    /// Until 2026-08-24 this path registered NOTHING. It built a `NodeHandle`
    /// and returned it, so `node_id_by_name` could not find a node the caller
    /// had just created, and two calls with one name handed out two handles the
    /// executor had never heard of. `create_node_on_with_domain` had the dedup
    /// (phase-267 added it there when N bridge endpoints overflowed the table);
    /// the plain path never got it.
    ///
    /// That is a prerequisite for the `create_node` vtable slot, whose contract
    /// is that the runtime calls it ONCE per distinct `(name, namespace)`:
    /// without a registry to check, the runtime would call it once per
    /// `create_node` and every backend would need its own dedup — which is the
    /// registry the slot exists to delete (zenoh's `ensure_node_liveliness`
    /// linear-scans `per_node_liveliness` for exactly this reason).
    ///
    /// The table is bounded by `MAX_NODES` (`NROS_EXECUTOR_MAX_NODES`, default
    /// 4), so a caller creating a fifth DISTINCT node now gets
    /// `NodeError::NodeTableFull` where it previously got a handle. That is the
    /// bound doing its job: a node the executor does not know about cannot
    /// carry a sched context, a QoS override, or a graph identity. Repeated
    /// calls with the SAME name are free.
    pub fn create_node(&mut self, name: &str) -> Result<super::node::Node<'_, 's>, NodeError> {
        if name.len() > 64 {
            return Err(NodeError::NameTooLong);
        }
        // Dedup against the executor's own namespace, which is the namespace
        // `node_builder` gives a node when none is named. phase-483 W2: this
        // returns THE node type (`Node`, re-exported as `nros::Node`), the
        // same handle `node_mut` gives a component, where it used to return a
        // session-borrowing `NodeHandle` with a different method set.
        let id = match self.node_id_by_name(name, self.namespace.clone().as_str()) {
            Some(id) => id,
            None => self.node_builder(name).build()?,
        };
        Ok(super::node::Node::new(self, id))
    }

    /// Phase 128.F.2 — bridge-mode node factory. Registers a Node
    /// bound to the named RMW backend by opening (or reusing) an
    /// extra session via `node_builder().rmw(rmw).build()`, then
    /// returns a [`NodeHandle`](crate::executor::NodeHandle) borrowing that
    /// session. Use when the
    /// binary intentionally links more than one backend and a Node
    /// must speak a specific one.
    ///
    /// The single-backend common case should keep using
    /// [`create_node`](Self::create_node) — this entry costs an
    /// extra session lookup and serves no purpose when only one
    /// backend is registered.
    #[cfg(feature = "rmw-cffi")]
    pub fn create_node_on(
        &mut self,
        name: &str,
        rmw: &str,
    ) -> Result<super::node::Node<'_, 's>, NodeError> {
        self.create_node_on_with_domain(name, rmw, None, None)
    }

    /// Like [`create_node_on`](Self::create_node_on) but pins the extra
    /// session's domain id. Required for a multi-domain config-driven bridge:
    /// an extra RMW session's participant domain follows the **node builder's**
    /// `domain_id` (`resolve_session_slot` → `domain_id.unwrap_or(0)`), NOT the
    /// `SessionSpec`'s — so without this an egress on a non-zero domain silently
    /// opens on domain 0 and never matches its receiver (phase-267 issue 0109).
    /// `None` domain preserves the legacy domain-0 default. `locator` pins the
    /// extra session's address — REQUIRED for an agent-based backend (xrce: the
    /// Micro-XRCE-DDS Agent addr) whose session can't be opened locator-less;
    /// `None` keeps the rmw-default (cyclonedds is domain-discovered, no locator).
    pub fn create_node_on_with_domain(
        &mut self,
        name: &str,
        rmw: &str,
        domain_id: Option<u32>,
        locator: Option<&str>,
    ) -> Result<super::node::Node<'_, 's>, NodeError> {
        if name.len() > 64 {
            return Err(NodeError::NameTooLong);
        }
        // Reuse an existing Node of this name rather than growing the node table
        // (phase-267 non-flat): a config-driven bridge calls this once per bridge
        // ENDPOINT, and the same session node (`s0`/`s1`) recurs across every
        // `[[bridge]]`. Without dedup, N bridges push 2N records and overflow
        // `MAX_NODES`. Names are unique per session in a generated bridge config,
        // so matching by name is unambiguous.
        let id = if let Some(i) = self.nodes.iter().position(|n| n.name.as_str() == name) {
            super::node_record::NodeId::from_raw(i as u8)
        } else {
            let mut builder = self.node_builder(name).rmw(rmw);
            if let Some(d) = domain_id {
                builder = builder.domain_id(d);
            }
            if let Some(loc) = locator {
                builder = builder.locator(loc);
            }
            builder.build()?
        };
        Ok(super::node::Node::new(self, id))
    }

    /// Drive transport I/O (poll network, dispatch callbacks).
    #[allow(dead_code)]
    pub(crate) fn drive_io(&mut self, timeout_ms: i32) -> Result<(), NodeError> {
        self.session
            .drive_io(timeout_ms)
            .map_err(|_| NodeError::Transport(TransportError::PollFailed))
    }

    /// Close the underlying session, running the shutdown hooks around it.
    ///
    /// Issue 0790. The order is the feature:
    ///
    /// 1. every registered PRE-shutdown hook, while the session is still open
    ///    and every entity still works — this is where a node publishes a final
    ///    state, answers a last request, parks an actuator or releases a bus;
    /// 2. the session close;
    /// 3. every registered ON-shutdown hook.
    ///
    /// A hook runs EXACTLY ONCE: each phase table is emptied before its first
    /// hook is invoked, so a second `close()` — or the [`Drop`] sweep after one
    /// — finds nothing left to run. Step 2 runs even
    /// if a pre-shutdown hook was registered and step 3 even if the close
    /// failed — a hook cannot strand the session, and a dead session must not
    /// strand the hooks.
    ///
    /// # This is a CLEAN-STOP facility and nothing more
    ///
    /// A watchdog reset, a hard fault or a panic does not come through here, so
    /// these hooks do not run then. Nothing in a fixed static table can promise
    /// otherwise, and an API that implied it would be worse than none: hardware
    /// that must be safe across an abnormal stop needs a hardware answer (a
    /// pull-down, a watchdog-driven output disable), not a callback.
    pub fn close(&mut self) -> Result<(), NodeError> {
        self.run_shutdown_hooks(super::types::ShutdownPhase::Pre);
        // Issue 1385 — hand the callback back BEFORE closing the session that
        // holds it. `close()` leaves the executor alive, so without this a
        // later `set_wake_callback` from the drop sweep would reach a session
        // the backend has already torn down.
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        self.clear_wake_signal();
        // phase-467 Row 8 — the same obligation on the graph-change slot, and
        // it has to be discharged in the same place for the same reason.
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        self.clear_graph_change_signal();
        let result = self
            .session
            .close()
            .map_err(|_| NodeError::Transport(TransportError::ConnectionFailed));
        self.run_shutdown_hooks(super::types::ShutdownPhase::Post);
        result
    }

    /// Register a hook to run BEFORE the session is closed (issue 0790).
    ///
    /// rclcpp's `Context::add_pre_shutdown_callback`. Returns the handle
    /// [`Self::remove_pre_shutdown_callback`] takes, or
    /// [`NodeError::ShutdownCallbacksFull`] when the phase table is full —
    /// raise `NROS_EXECUTOR_MAX_SHUTDOWN_CBS` (default 2) at build time.
    ///
    /// # Safety
    /// `callback` must be safe to invoke exactly once with `context`, and
    /// `context` must stay valid until the hook runs or is removed. The hook
    /// runs on whichever task calls [`Self::close`] (or drops the executor),
    /// which is not necessarily the task that registered it.
    pub unsafe fn add_pre_shutdown_callback(
        &mut self,
        callback: super::types::ShutdownCallbackFn,
        context: *mut core::ffi::c_void,
    ) -> Result<super::types::ShutdownCallbackHandle, NodeError> {
        Self::claim_shutdown_slot(
            &mut self.pre_shutdown_hooks,
            super::types::ShutdownPhase::Pre,
            callback,
            context,
        )
    }

    /// Register a hook to run AFTER the session is closed (issue 0790).
    ///
    /// rclcpp's `Context::add_on_shutdown_callback` / `rclcpp::on_shutdown`.
    /// Entities are gone by the time it runs, so anything that needs the wire
    /// belongs in [`Self::add_pre_shutdown_callback`] instead.
    ///
    /// # Safety
    /// Same contract as [`Self::add_pre_shutdown_callback`].
    pub unsafe fn add_on_shutdown_callback(
        &mut self,
        callback: super::types::ShutdownCallbackFn,
        context: *mut core::ffi::c_void,
    ) -> Result<super::types::ShutdownCallbackHandle, NodeError> {
        Self::claim_shutdown_slot(
            &mut self.on_shutdown_hooks,
            super::types::ShutdownPhase::Post,
            callback,
            context,
        )
    }

    /// Remove a pre-shutdown hook. `true` if `handle` named a live one.
    ///
    /// rclcpp's `Context::remove_pre_shutdown_callback`, and `bool` for the
    /// same reason: "it was not there" is an ordinary answer (the hook may
    /// already have run), not an error. A handle issued for the OTHER phase
    /// returns `false` and removes nothing — that is what the phase tag in
    /// [`ShutdownCallbackHandle`] buys.
    ///
    /// [`ShutdownCallbackHandle`]: super::types::ShutdownCallbackHandle
    pub fn remove_pre_shutdown_callback(
        &mut self,
        handle: super::types::ShutdownCallbackHandle,
    ) -> bool {
        Self::release_shutdown_slot(
            &mut self.pre_shutdown_hooks,
            super::types::ShutdownPhase::Pre,
            handle,
        )
    }

    /// Remove an on-shutdown hook. See [`Self::remove_pre_shutdown_callback`].
    pub fn remove_on_shutdown_callback(
        &mut self,
        handle: super::types::ShutdownCallbackHandle,
    ) -> bool {
        Self::release_shutdown_slot(
            &mut self.on_shutdown_hooks,
            super::types::ShutdownPhase::Post,
            handle,
        )
    }

    /// How many hooks are currently registered for `phase`. Diagnostic /
    /// test surface, and what a "did my registration land?" assertion reads.
    pub fn shutdown_callback_count(&self, phase: super::types::ShutdownPhase) -> usize {
        let table = match phase {
            super::types::ShutdownPhase::Pre => &self.pre_shutdown_hooks,
            super::types::ShutdownPhase::Post => &self.on_shutdown_hooks,
        };
        table.iter().flatten().count()
    }

    /// Claim the first free slot of a phase table.
    fn claim_shutdown_slot(
        table: &mut [Option<super::types::ShutdownHook>],
        phase: super::types::ShutdownPhase,
        callback: super::types::ShutdownCallbackFn,
        context: *mut core::ffi::c_void,
    ) -> Result<super::types::ShutdownCallbackHandle, NodeError> {
        for (index, slot) in table.iter_mut().enumerate() {
            if slot.is_some() {
                continue;
            }
            let handle = super::types::ShutdownCallbackHandle::new(phase, index)
                .ok_or(NodeError::ShutdownCallbacksFull)?;
            *slot = Some(super::types::ShutdownHook { callback, context });
            return Ok(handle);
        }
        Err(NodeError::ShutdownCallbacksFull)
    }

    /// Clear a slot of a phase table, rejecting a handle from the other phase.
    fn release_shutdown_slot(
        table: &mut [Option<super::types::ShutdownHook>],
        phase: super::types::ShutdownPhase,
        handle: super::types::ShutdownCallbackHandle,
    ) -> bool {
        if handle.phase() != Some(phase) {
            return false;
        }
        match table.get_mut(handle.index()) {
            Some(slot) => slot.take().is_some(),
            None => false,
        }
    }

    /// Run — and consume — every hook registered for `phase`, in registration
    /// order.
    ///
    /// The table is EMPTIED BEFORE the first callback runs, not slot by slot as
    /// the loop walks it, and both halves of that matter:
    ///
    /// * "exactly once" becomes a property of the table rather than of the
    ///   caller — a second `close()`, or the `Drop` sweep after one, finds
    ///   nothing left to run;
    /// * the `&mut self` borrow ENDS before any foreign code is invoked. A hook
    ///   is an `extern "C" fn` that may hold a raw pointer back to this
    ///   executor (the C and C++ shims hand out exactly that), so a hook that
    ///   registers or removes another one must not be running inside a live
    ///   `&mut` into the table it is touching.
    pub(crate) fn run_shutdown_hooks(&mut self, phase: super::types::ShutdownPhase) {
        let table = match phase {
            super::types::ShutdownPhase::Pre => &mut self.pre_shutdown_hooks,
            super::types::ShutdownPhase::Post => &mut self.on_shutdown_hooks,
        };
        // `ShutdownHook` is `Copy` (a fn pointer and a raw pointer), so this is
        // a register-width move of a table whose default size is two slots —
        // not a reason to keep the borrow open across the calls.
        let hooks = *table;
        *table = [None; crate::config::MAX_SHUTDOWN_CBS];
        for hook in hooks.iter().flatten() {
            // SAFETY: the `add_*_shutdown_callback` caller promised `callback`
            // is safe to invoke once with `context`, and that `context` stays
            // valid until the hook runs or is removed. This is that one call,
            // and the table is already cleared so it cannot happen again.
            unsafe {
                (hook.callback)(hook.context);
            }
        }
    }

    /// Phase 216 follow-up — register a per-Node dispatch trampoline.
    ///
    /// The board-side Entry pkg (or the macro-emitted
    /// `register_dispatch(executor)` wrapper, once wired) calls this
    /// once per deployed Node pkg, handing in the
    /// `__nros_node_<pkg>_on_callback` symbol + the Node's per-pkg
    /// `state` blob. [`Executor::dispatch_callback`] then linear-scans
    /// the registered slots when the dispatch task hands off a
    /// `SignaledCallback`.
    ///
    /// Returns `Err(())` when the registry is full (`MAX_NODES`
    /// entries — raise via `NROS_EXECUTOR_MAX_NODES` at build time).
    ///
    /// # Safety
    ///
    /// `state` must outlive the executor (the typical shape is a
    /// `*mut State` produced by
    /// `nros::__private_node_state_into_raw` from the
    /// macro-emitted `i()`; that pointer's lifetime IS the
    /// `Executor`'s by construction). `on_callback` must be safe to
    /// invoke with `(state, cb_id_ptr, cb_id_len, ctx)` matching the
    /// per-Node `__nros_node_<pkg>_on_callback` ABI emitted by the
    /// `nros::node!()` macro (Phase 216.A.5).
    #[allow(clippy::result_unit_err)]
    pub fn register_dispatch_slot(
        &mut self,
        state: *mut core::ffi::c_void,
        on_callback: unsafe extern "C" fn(
            *mut core::ffi::c_void,
            *const u8,
            usize,
            *mut core::ffi::c_void,
        ),
    ) -> Result<(), ()> {
        self.dispatch_slots
            .push(DispatchSlot { state, on_callback })
            .map_err(|_| ())
    }

    /// Phase 216 follow-up — current registered dispatch-slot count.
    /// Diagnostic / test surface.
    pub fn dispatch_slot_count(&self) -> usize {
        self.dispatch_slots.len()
    }

    /// Phase 258 (Track 2, 2a) — enroll a component into the executor-owned
    /// tick registry. Called by `nros`'s `install`/`register_node_borrowed`
    /// after it builds the `Arc<ComponentCell>`: `state` is the leaked
    /// `Arc<ComponentCell>` (the slot takes ownership), `tick`/`drop` are the
    /// `nros`-side trampolines (see `ComponentSlot`). The slot's `tick`
    /// runs at the tail of every [`spin_once`](Self::spin_once); its `drop`
    /// runs once on `Executor::drop`.
    ///
    /// Returns `Err(())` when the registry is full (`MAX_NODES` — raise via
    /// `NROS_EXECUTOR_MAX_NODES` at build time). On error the caller still
    /// owns `state` (the slot was not stored) and must drop it.
    ///
    /// # Safety
    /// `state` must be a `*mut` produced by leaking the component cell the
    /// `tick`/`drop` trampolines expect (an `Arc<ComponentCell>` via
    /// `Arc::into_raw` in the canonical `nros` caller), and must remain valid
    /// until the matching `drop` runs. `tick` must be safe to invoke with
    /// `(state, exec_ctx = *mut Executor)` each spin; `drop` must be safe to
    /// invoke exactly once with `state`.
    #[allow(clippy::result_unit_err)]
    pub unsafe fn enroll_component(
        &mut self,
        state: *mut core::ffi::c_void,
        tick: unsafe extern "C" fn(*mut core::ffi::c_void, *mut core::ffi::c_void),
        drop: unsafe extern "C" fn(*mut core::ffi::c_void),
    ) -> Result<(), ()> {
        self.component_slots
            .push(ComponentSlot { state, tick, drop })
            .map_err(|_| ())
    }

    /// Phase 258 (Track 2, 2a) — current enrolled component-slot count.
    /// Diagnostic / test surface.
    pub fn component_slot_count(&self) -> usize {
        self.component_slots.len()
    }

    /// issue #140 — the enrolled components' opaque `state` pointers, in enroll
    /// order. Each is the *leaked* `Arc<ComponentCell>` `enroll_component` was
    /// handed (see `ComponentSlot::state`); the `nros` layer re-borrows them
    /// to fold per-component dispatch counters into
    /// `observed_callback_counts` — install-seam components
    /// (`register_node_borrowed`) live ONLY here, not in
    /// `ExecutorNodeRuntime::components`, so the hosted-spin counts read zero
    /// without this surface.
    pub fn enrolled_component_states(&self) -> impl Iterator<Item = *mut core::ffi::c_void> + '_ {
        self.component_slots.iter().map(|slot| slot.state)
    }

    /// Phase 216 final dispatch hook — stable entry point the
    /// framework's dispatch task (RTIC `__nros_run` /
    /// Embassy `__nros_run_task`) calls for each `SignaledCallback`
    /// envelope it dequeues from the board-side SPSC / Embassy
    /// channel.
    ///
    /// ## Signature shape
    ///
    /// `nros-node` sits below `nros` in the dep graph, so the typed
    /// `nros::CallbackId<'_>` / `nros::CallbackCtx<'_>` types
    /// referenced in the Phase 216 design notes cannot appear in the
    /// signature here. The macro emit translates the dequeued
    /// envelope to the layer-clean `(cb_id: &str, ctx: *mut c_void)`
    /// pair before calling this method; the per-Node `on_callback`
    /// trampoline ABI (Phase 216.A.5,
    /// `__nros_node_<pkg>_on_callback(state, cb_id_ptr, cb_id_len,
    /// ctx)`) uses the same untyped shape on the other side of the
    /// fence, so the round-trip stays type-consistent.
    ///
    /// ## Body — linear scan of the dispatch registry
    ///
    /// Each registered `DispatchSlot` holds an
    /// `__nros_node_<pkg>_on_callback` fn pointer + the owning Node's
    /// `state` blob. The macro-emitted trampoline body
    /// `match`es on `CallbackId` tags the Node declared and is a
    /// no-op for non-matching `cb_id`s — at most one Node per
    /// `cb_id` actually acts, the rest are cheap string-compare
    /// no-ops. This mirrors the strategy
    /// `ExecutorNodeRuntime::dispatch_callback` uses in
    /// `packages/api/nros/src/node_runtime.rs:470`.
    ///
    /// ## What's NOT auto-wired today
    ///
    /// The `nros::node!()` macro doesn't yet emit a
    /// `register_dispatch(executor)` wrapper that pushes the per-pkg
    /// `(state, on_callback)` into this registry. Until that wiring
    /// lands (Phase 216 follow-up — see commit msg), downstream
    /// consumers (board's `init_hardware`, or the codegen-emitted
    /// `run_plan`) must call
    /// [`Executor::register_dispatch_slot`] explicitly with the
    /// `__nros_node_<pkg>_on_callback` symbol + a `state` blob from
    /// the macro-emitted `i()`.
    //
    // `ctx` is an opaque FFI cookie forwarded verbatim to each slot's
    // `on_callback`; this fn never dereferences it (the registered callback
    // does, under the `register_dispatch_slot` safety contract), so it is sound
    // to call from safe code.
    #[allow(clippy::not_unsafe_ptr_arg_deref)]
    pub fn dispatch_callback(&mut self, cb_id: &str, ctx: *mut core::ffi::c_void) {
        let cb_id_ptr = cb_id.as_ptr();
        let cb_id_len = cb_id.len();
        // Snapshot pointer + length to avoid an outstanding borrow
        // across the unsafe fn calls below; each `DispatchSlot` is
        // `Copy`, so iterating by value sidesteps any aliasing
        // worry the borrow checker would flag if a slot's
        // `on_callback` re-entered the executor.
        for slot in self.dispatch_slots.iter().copied() {
            // SAFETY: caller of `register_dispatch_slot` guaranteed
            // `state` outlives the executor + `on_callback` matches
            // the per-Node `__nros_node_<pkg>_on_callback` ABI;
            // `cb_id_ptr`/`cb_id_len` describe the live `&str` the
            // caller passed in.
            unsafe {
                (slot.on_callback)(slot.state, cb_id_ptr, cb_id_len, ctx);
            }
        }
    }

    /// Get a reference to the underlying session.
    pub fn session(&self) -> &session::ConcreteSession {
        &self.session
    }

    /// Get a mutable reference to the underlying session.
    pub fn session_mut(&mut self) -> &mut session::ConcreteSession {
        &mut self.session
    }

    /// Phase 124.F.3 — session-level connectivity probe. Wire-level
    /// round-trip "is the peer / agent / router still reachable?"
    /// — cheaper than the service-availability probe (no discovery
    /// state required).
    ///
    /// Returns `Ok(())` on reply within `timeout_ms`,
    /// `Err(NodeError::Transport(Timeout))` on no reply,
    /// `Err(NodeError::Transport(Unsupported))` when the active
    /// backend can't probe.
    ///
    /// Mirrors micro-ROS's `rmw_uros_ping_agent`. Useful for
    /// reconnect-on-link-loss patterns: bare-metal code can call
    /// `ping(100)` periodically and tear down / re-open the session
    /// on timeout.
    pub fn ping(&mut self, timeout_ms: i32) -> Result<(), NodeError> {
        use nros_rmw::Session;
        self.session
            .ping_session(timeout_ms)
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — every node on the graph, with its namespace.
    ///
    /// `visit(name, namespace, enclave)` is called once per node and returns
    /// `false` to stop early. A VISITOR rather than a returned collection
    /// because there is no allocator at this layer and the graph has no bound
    /// the caller can know; peak extra memory is one entry. Every string is
    /// BORROWED for the duration of the call.
    ///
    /// `enclave` is `None` where the backend does not track one, which is what
    /// lets one call answer both `rmw_get_node_names` and
    /// `rmw_get_node_names_with_enclaves`.
    ///
    /// **This reports what has already been DISCOVERED, and never blocks.** The
    /// first call after startup legitimately sees a partial graph — the backend
    /// keeps a standing query fed by `spin`, so the view fills in over
    /// successive calls. Code that waits for a peer should poll, not call once
    /// and conclude. An empty result is "nobody seen yet", never "nobody
    /// exists".
    ///
    /// `Err(Transport(Unsupported))` from a backend with no graph — distinct
    /// from an empty graph, deliberately.
    pub fn get_node_names(
        &mut self,
        visit: &mut dyn FnMut(&str, &str, Option<&str>) -> bool,
    ) -> Result<(), NodeError> {
        use nros_rmw::Session;
        self.session
            .get_node_names(visit)
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — every topic on the graph, with the types on it.
    ///
    /// `visit(topic_name, types)` is called once per distinct TOPIC — a topic
    /// carrying two types is one call with two entries, not two calls. `types`
    /// may legitimately be empty on a partially discovered graph: reporting the
    /// name without a type beats dropping it.
    ///
    /// Same discovery caveat as [`Self::get_node_names`].
    pub fn get_topic_names_and_types(
        &mut self,
        visit: &mut dyn FnMut(&str, &[&str]) -> bool,
    ) -> Result<(), NodeError> {
        use nros_rmw::Session;
        self.session
            .get_topic_names_and_types(visit)
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — every service on the graph, with its types.
    /// As [`Self::get_topic_names_and_types`], over servers and clients.
    pub fn get_service_names_and_types(
        &mut self,
        visit: &mut dyn FnMut(&str, &[&str]) -> bool,
    ) -> Result<(), NodeError> {
        use nros_rmw::Session;
        self.session
            .get_service_names_and_types(visit)
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — how many publishers are visible on `topic_name`.
    ///
    /// `topic_name` is a ROS name (`"/chatter"`). A count reflects what has
    /// been DISCOVERED, so it can be low right after startup and is never a
    /// proof of absence — see [`Self::get_node_names`].
    pub fn count_publishers(&mut self, topic_name: &str) -> Result<usize, NodeError> {
        use nros_rmw::Session;
        self.session
            .count_publishers(topic_name)
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — how many subscribers are visible on `topic_name`.
    /// See [`Self::count_publishers`] for the caveats.
    pub fn count_subscribers(&mut self, topic_name: &str) -> Result<usize, NodeError> {
        use nros_rmw::Session;
        self.session
            .count_subscribers(topic_name)
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — what one named node PUBLISHES, with the types.
    ///
    /// `visit(topic_name, types)` per distinct topic. A node the graph has not
    /// discovered yields no visits, which is not an error — see
    /// [`Self::get_node_names`] for why an empty answer means "not seen yet".
    pub fn get_publisher_names_and_types_by_node(
        &mut self,
        node_name: &str,
        node_namespace: &str,
        visit: &mut dyn FnMut(&str, &[&str]) -> bool,
    ) -> Result<(), NodeError> {
        use nros_rmw::{GraphEntityKind, Session};
        self.session
            .get_names_and_types_by_node(
                GraphEntityKind::Publisher,
                node_name,
                node_namespace,
                visit,
            )
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — what one named node SUBSCRIBES to, with the types.
    ///
    /// **`subscription`, not `subscriber`** — this is rclrs's spelling
    /// (`get_subscription_names_and_types_by_node`), and the Rust surface takes
    /// its vocabulary from rclrs so a user porting Rust ROS 2 code types what
    /// they already know. The C surface says `subscriber` because rcl does, and
    /// the vtable slot says `subscriber` because upstream rmw does. Three
    /// layers, three upstreams, one word each — not drift. Issue 0788 owns the
    /// wider verb sweep.
    pub fn get_subscription_names_and_types_by_node(
        &mut self,
        node_name: &str,
        node_namespace: &str,
        visit: &mut dyn FnMut(&str, &[&str]) -> bool,
    ) -> Result<(), NodeError> {
        use nros_rmw::{GraphEntityKind, Session};
        self.session
            .get_names_and_types_by_node(
                GraphEntityKind::Subscriber,
                node_name,
                node_namespace,
                visit,
            )
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — what services one named node SERVES, with the types.
    pub fn get_service_names_and_types_by_node(
        &mut self,
        node_name: &str,
        node_namespace: &str,
        visit: &mut dyn FnMut(&str, &[&str]) -> bool,
    ) -> Result<(), NodeError> {
        use nros_rmw::{GraphEntityKind, Session};
        self.session
            .get_names_and_types_by_node(GraphEntityKind::Service, node_name, node_namespace, visit)
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — what services one named node CALLS, with the types.
    pub fn get_client_names_and_types_by_node(
        &mut self,
        node_name: &str,
        node_namespace: &str,
        visit: &mut dyn FnMut(&str, &[&str]) -> bool,
    ) -> Result<(), NodeError> {
        use nros_rmw::{GraphEntityKind, Session};
        self.session
            .get_names_and_types_by_node(GraphEntityKind::Client, node_name, node_namespace, visit)
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — the publishers on `topic_name`, one visit each.
    ///
    /// Each `GraphEndpointInfo` BORROWS its strings for the duration of the
    /// visit; copy anything kept.
    ///
    /// It carries no QoS. The granted profile is what would answer "why is
    /// nothing arriving", and no backend can read one back yet — reporting the
    /// remote's DECLARED profile instead would be a confident wrong answer, so
    /// the field is absent rather than misleading.
    pub fn get_publishers_info_by_topic(
        &mut self,
        topic_name: &str,
        visit: &mut dyn FnMut(&nros_rmw::GraphEndpointInfo<'_>) -> bool,
    ) -> Result<(), NodeError> {
        use nros_rmw::Session;
        self.session
            .get_endpoint_info_by_topic(true, topic_name, visit)
            .map_err(NodeError::Transport)
    }

    /// phase-381 W4 — the subscriptions on `topic_name`, one visit each.
    /// See [`Self::get_publishers_info_by_topic`].
    pub fn get_subscriptions_info_by_topic(
        &mut self,
        topic_name: &str,
        visit: &mut dyn FnMut(&nros_rmw::GraphEndpointInfo<'_>) -> bool,
    ) -> Result<(), NodeError> {
        use nros_rmw::Session;
        self.session
            .get_endpoint_info_by_topic(false, topic_name, visit)
            .map_err(NodeError::Transport)
    }

    /// phase-444 — block until at least `count` publishers are visible on
    /// `topic_name`, or `timeout` elapses. Upstream's `rcl_wait_for_publishers`.
    ///
    /// Returns `Ok(true)` when the graph showed at least `count` inside the
    /// budget, `Ok(false)` on timeout. The startup-ordering primitive one
    /// entity kind over from [`EmbeddedServiceClient::wait_for_service`](super::handles::EmbeddedServiceClient::wait_for_service),
    /// and built the same way: a spin on a discovery read, so other
    /// subscriptions and timers keep making progress while it waits.
    ///
    /// **This is the one blocking member of the graph family, and it does not
    /// weaken the family's contract — it composes it.** The query underneath
    /// ([`count_publishers`](Self::count_publishers)) still reports only what
    /// has been DISCOVERED and still never blocks; what waits is this loop,
    /// and it waits by POLLING that query. RFC-0021 is the rule that governs
    /// it, and that rule does not forbid blocking: it requires a blocking
    /// helper to take an executor and drive it, which is what makes the
    /// timeout reliable on a single-threaded transport and what makes the
    /// reentrancy visible at the call site.
    ///
    /// **`Unsupported` is propagated IMMEDIATELY, not waited out** — and this
    /// is the one place it deliberately differs from `wait_for_service`, which
    /// treats a backend that cannot answer as "keep waiting" and reports
    /// `Ok(false)` at the deadline (issue 1087). That is right for a service
    /// probe, where not-yet-answerable is a transient. It is wrong here: a
    /// backend with no graph (XRCE) can never answer, so spending the budget
    /// to return `Ok(false)` would report "no publishers appeared" for a
    /// backend that cannot see publishers at all — collapsing "cannot tell
    /// you" into "not there", which is exactly the distinction RFC-0036 exists
    /// to keep and which every other method in this family promises to keep.
    ///
    /// `count == 0` is satisfied immediately and without asking the backend —
    /// including on a backend with no graph, because "at least zero" is true
    /// of every graph and needs no discovery to establish.
    pub fn wait_for_publishers(
        &mut self,
        topic_name: &str,
        count: usize,
        timeout: core::time::Duration,
    ) -> Result<bool, NodeError> {
        self.wait_for_endpoints(true, topic_name, count, timeout)
    }

    /// phase-444 — block until at least `count` subscribers are visible on
    /// `topic_name`. Upstream's `rcl_wait_for_subscribers`. See
    /// [`wait_for_publishers`](Self::wait_for_publishers) for the contract,
    /// and for why `Unsupported` returns rather than waits.
    pub fn wait_for_subscribers(
        &mut self,
        topic_name: &str,
        count: usize,
        timeout: core::time::Duration,
    ) -> Result<bool, NodeError> {
        self.wait_for_endpoints(false, topic_name, count, timeout)
    }

    /// The one loop both `wait_for_*` verbs run — a shared helper rather than
    /// a second spelling, because the pair differs only in which counter it
    /// polls and a copied loop is how the two drift.
    fn wait_for_endpoints(
        &mut self,
        publishers: bool,
        topic_name: &str,
        count: usize,
        timeout: core::time::Duration,
    ) -> Result<bool, NodeError> {
        if count == 0 {
            return Ok(true);
        }
        // `?`, not a swallow: a backend that cannot see the graph says so now.
        if self.count_endpoints(publishers, topic_name)? >= count {
            return Ok(true);
        }
        let spin_interval =
            core::time::Duration::from_millis(super::handles::DEFAULT_SPIN_INTERVAL_MS);
        let max_spins =
            (timeout.as_millis() as u64 / super::handles::DEFAULT_SPIN_INTERVAL_MS).max(1);
        let mut budget = super::handles::WaitBudget::new(max_spins, timeout);
        loop {
            self.spin_once(budget.next_spin_interval(spin_interval));
            if self.count_endpoints(publishers, topic_name)? >= count {
                return Ok(true);
            }
            if !budget.tick() {
                return Ok(false);
            }
        }
    }

    /// Which counter a `wait_for_*` polls. Keeps the boolean's meaning in ONE
    /// place instead of at both call sites.
    fn count_endpoints(&mut self, publishers: bool, topic_name: &str) -> Result<usize, NodeError> {
        if publishers {
            self.count_publishers(topic_name)
        } else {
            self.count_subscribers(topic_name)
        }
    }

    /// Get a mutable reference to an action client core in the arena by entry index.
    ///
    /// # Safety
    /// The caller must ensure that `entry_index` refers to an `ActionClientRawArenaEntry`.
    pub unsafe fn action_client_core_mut(
        &mut self,
        entry_index: usize,
    ) -> Option<&mut super::action_core::ActionClientCore> {
        let meta = self.entries.get(self.slot_of_raw(entry_index)?)?.as_ref()?;
        if !matches!(meta.kind, EntryKind::ActionClient) {
            return None;
        }
        let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
        unsafe {
            let entry_ptr = arena_ptr.add(meta.offset)
                as *mut super::arena::ActionClientRawArenaEntry<
                    { crate::config::DEFAULT_RX_BUF_SIZE },
                    { crate::config::DEFAULT_RX_BUF_SIZE },
                    { crate::config::DEFAULT_RX_BUF_SIZE },
                >;
            Some(&mut (*entry_ptr).core)
        }
    }

    /// Get a mutable reference to a service-client arena entry (Phase 82).
    ///
    /// Returns `None` if `entry_index` doesn't refer to a service client
    /// entry. The default reply buffer size is assumed because the C API
    /// always uses the default — the entry was registered via
    /// `register_service_client_raw_sized::<DEFAULT_RX_BUF_SIZE>`.
    ///
    /// # Safety
    /// `entry_index` must refer to a `ServiceClientRawArenaEntry`.
    pub unsafe fn service_client_entry_mut(
        &mut self,
        entry_index: usize,
    ) -> Option<&mut super::arena::ServiceClientRawArenaEntry<{ crate::config::DEFAULT_RX_BUF_SIZE }>>
    {
        let meta = self.entries.get(self.slot_of_raw(entry_index)?)?.as_ref()?;
        if !matches!(meta.kind, EntryKind::ServiceClient) {
            return None;
        }
        let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
        unsafe {
            let entry_ptr = arena_ptr.add(meta.offset)
                as *mut super::arena::ServiceClientRawArenaEntry<
                    { crate::config::DEFAULT_RX_BUF_SIZE },
                >;
            Some(&mut *entry_ptr)
        }
    }

    // ------------------------------------------------------------------
    // issue 1437 / phase-444 — the ARENA half of the granted-QoS read-back.
    //
    // An entity registered with a callback lives in the executor arena, and
    // the C / C++ handle the user holds is then bookkeeping: its inline
    // storage is untouched and the only identity it carries is the entry
    // index. So an accessor that reads the user's own storage answers for
    // the POLL road and returns an absence on the CALLBACK road — which is
    // the road a ported `rclcpp` node takes, i.e. the common one. These
    // three close that reach.
    //
    // Each reads the entry's HANDLE and nothing else, which is why one
    // function per kind serves every entry SHAPE of that kind: every arena
    // entry is `#[repr(C)]` with its handle as the first field (12
    // subscription shapes, 2 service-server, 2 service-client), so
    // `arena_base + offset` IS the handle pointer whatever buffer sizes and
    // callback types the shape was monomorphised with.
    // `service_client_entry_mut` above has to name ONE shape because it
    // reaches past the handle; these do not, and that is the whole
    // difference. `arena::tests::every_arena_entry_begins_with_its_handle`
    // pins the invariant.

    /// The `RmwSubscriber` of an arena-registered subscription, by entry index.
    ///
    /// `None` when `entry_index` names no entry, or names one that is not a
    /// subscription.
    ///
    /// # Safety
    /// `entry_index` must be an index this executor handed out. The borrow is
    /// valid only while the arena is not re-entered.
    pub unsafe fn subscription_handle(
        &self,
        entry_index: usize,
    ) -> Option<&session::RmwSubscriber> {
        let meta = self.entries.get(self.slot_of_raw(entry_index)?)?.as_ref()?;
        if !matches!(meta.kind, EntryKind::Subscription) {
            return None;
        }
        let arena_ptr = self.arena.as_ptr() as *const u8;
        // SAFETY: `meta.offset` is inside the arena by construction, and every
        // subscription entry shape begins with its `RmwSubscriber`.
        Some(unsafe { &*(arena_ptr.add(meta.offset) as *const session::RmwSubscriber) })
    }

    /// The `RmwServiceServer` of an arena-registered service, by entry index.
    ///
    /// # Safety
    /// See [`Executor::subscription_handle`].
    pub unsafe fn service_server_handle(
        &self,
        entry_index: usize,
    ) -> Option<&session::RmwServiceServer> {
        let meta = self.entries.get(self.slot_of_raw(entry_index)?)?.as_ref()?;
        if !matches!(meta.kind, EntryKind::Service) {
            return None;
        }
        let arena_ptr = self.arena.as_ptr() as *const u8;
        // SAFETY: as above; every service-server entry shape begins with its
        // `RmwServiceServer`.
        Some(unsafe { &*(arena_ptr.add(meta.offset) as *const session::RmwServiceServer) })
    }

    /// The `RmwServiceClient` of an arena-registered client, by entry index.
    ///
    /// # Safety
    /// See [`Executor::subscription_handle`].
    pub unsafe fn service_client_handle(
        &self,
        entry_index: usize,
    ) -> Option<&session::RmwServiceClient> {
        let meta = self.entries.get(self.slot_of_raw(entry_index)?)?.as_ref()?;
        if !matches!(meta.kind, EntryKind::ServiceClient) {
            return None;
        }
        let arena_ptr = self.arena.as_ptr() as *const u8;
        // SAFETY: as above; both service-client entry shapes begin with their
        // `RmwServiceClient` — the typed one through `ServiceClientSendHeader`,
        // itself `#[repr(C)]` and handle-first.
        Some(unsafe { &*(arena_ptr.add(meta.offset) as *const session::RmwServiceClient) })
    }

    /// Set the executor-level trigger condition.
    ///
    /// Controls which handles must be ready before `spin_once` dispatches
    /// callbacks. Defaults to [`Trigger::AnyReady`](crate::Trigger).
    pub fn set_trigger(&mut self, trigger: Trigger) {
        self.trigger = trigger;
    }

    /// Set the executor data communication semantics.
    ///
    /// Choose between `Direct` (process in place) and `LET`
    /// (snapshot-then-process) semantics. See [`ExecutorSemantics`].
    pub fn set_semantics(&mut self, semantics: ExecutorSemantics) {
        self.semantics = semantics;
    }

    /// Set the invocation mode for a specific handle.
    ///
    /// Controls whether the callback fires on every spin
    /// ([`Always`](InvocationMode::Always)) or only when new data
    /// arrives ([`OnNewData`](InvocationMode::OnNewData), the default).
    pub fn set_invocation(&mut self, id: HandleId, mode: InvocationMode) {
        let slot = self.live_slot(id);
        if let Some(Some(meta)) = self.entries.get_mut(slot) {
            meta.invocation = mode;
        }
    }

    // ========================================================================
    // Arena-based callback registration
    // ========================================================================

    /// Arena bytes claimed by registered entities so far.
    ///
    /// EXACT, not a worst case: the arena is a bump allocator and every
    /// `arena_alloc` charges `size_of::<T>()`, so nothing is reserved per slot.
    /// `ARENA_SIZE` itself is derived the other way — every slot budgeted at
    /// the ActionClient worst case — which is issue 0900, and this accessor is
    /// how an image can find out what it actually needs.
    pub fn arena_used(&self) -> usize {
        self.arena_used
    }

    /// Total arena bytes this executor was given.
    ///
    /// The arena is a borrowed slice; where its storage lives is the caller's
    /// choice, not a property of this type. Three answers are real — a `.bss`
    /// static (the C/C++ entries, and the `alloc` constructors since phase-392
    /// W6), the heap (those constructors' fallback), and a stack-declared
    /// `rclc_executor_t`. See `super::backing` and `report_arena_headroom`.
    pub fn arena_capacity(&self) -> usize {
        self.arena.len()
    }

    /// Bump-allocate space for `T` in the arena. Returns the byte offset.
    pub(crate) fn arena_alloc<T>(&mut self) -> Result<usize, NodeError> {
        // Issue 1667 — every region is grain-aligned and at least one free-list
        // node long, so it can be listed when it is released.
        let align = core::mem::align_of::<T>().max(ARENA_GRAIN);
        let size = Self::arena_region_len(core::mem::size_of::<T>());
        if let Some((offset, granted)) = self.arena_take_freed(size, align) {
            crate::boot_report::note_alloc(size, self.arena_used);
            self.note_entry_region(offset, granted);
            return Ok(offset);
        }
        let aligned_offset = (self.arena_used + align - 1) & !(align - 1);
        let new_used = aligned_offset + size;
        if new_used > self.arena.len() {
            // issue 0900 — `BufferTooSmall` is returned by a dozen other paths,
            // so on a target where a return code is all you get, arena
            // exhaustion is indistinguishable from a message that did not fit.
            return Err(self.arena_exhausted(
                core::any::type_name::<T>(),
                size,
                new_used - self.arena.len(),
            ));
        }
        self.arena_used = new_used;
        crate::boot_report::note_alloc(size, new_used);
        self.note_entry_region(aligned_offset, size);
        Ok(aligned_offset)
    }

    /// Issue 1631 — remember the region an ENTRY allocation handed out, for
    /// `emplace_entry` to record. Only the two entry allocators call this; a
    /// callback capture rides inside the entry's trailing region (phase-476
    /// W0), so it is part of what they record.
    fn note_entry_region(&mut self, offset: usize, len: usize) {
        self.pending_region = Some(FreedRegion { offset, len });
    }

    /// Issue 1667 — the length a region of `len` requested bytes occupies:
    /// rounded up to the grain, and never shorter than a free-list node.
    const fn arena_region_len(len: usize) -> usize {
        let len = len.next_multiple_of(ARENA_GRAIN);
        if len < ARENA_MIN_REGION {
            ARENA_MIN_REGION
        } else {
            len
        }
    }

    /// Bytes a callback CAPTURE takes in an entry's trailing region: its length
    /// rounded up to the arena's `u64` grain. 0 for no capture.
    ///
    /// phase-476 W0 — a capture used to be a SEPARATE arena allocation
    /// (`stow_capture` over `arena_alloc_bytes`), which `release_entry` never
    /// gave back: it frees exactly the region `emplace_entry` recorded, and that
    /// was the entry's. Placing the capture at the END of the entry's own
    /// trailing region puts it inside the recorded region, so releasing the
    /// entry releases its capture.
    pub(crate) fn capture_trailing_len(capture: Option<&[u8]>) -> usize {
        match capture {
            Some(b) if !b.is_empty() => b.len().next_multiple_of(core::mem::align_of::<u64>()),
            _ => 0,
        }
    }

    /// Copy a caller's callback CAPTURE to arena offset `at` and return the
    /// context pointer the entry should dispatch with — phase-456 W1, made a
    /// runtime length by W8, made part of the entry's region by phase-476 W0.
    ///
    /// `context` is one pointer. That carries a C++ `[this]` capture and not a
    /// `[this, state]` (two) or a `[obj, method]` (three, because a
    /// pointer-to-member-function is two words on the Itanium ABI) — the
    /// distribution phase-442 W0 measured over this tree and the porting corpus.
    /// So the capture lives in the arena beside the registration that uses it:
    /// arena bytes never move once allocated, and the returned pointer is into
    /// them rather than into anything of the caller's, so the C++ side keeps
    /// nothing.
    ///
    /// `at` must start [`capture_trailing_len`](Self::capture_trailing_len)
    /// bytes the caller's entry allocation reserved for it. `None` and an empty
    /// slice both mean "no capture", and both give the caller's own `context`
    /// straight back, which is every pre-W1 caller.
    pub(crate) fn place_capture(
        &mut self,
        at: usize,
        capture: Option<&[u8]>,
        context: *mut core::ffi::c_void,
    ) -> *mut core::ffi::c_void {
        let bytes = match capture {
            Some(b) if !b.is_empty() => b,
            _ => return context,
        };
        debug_assert!(at + bytes.len() <= self.arena.len());
        // SAFETY: the caller's entry allocation reserved
        // `capture_trailing_len(capture)` bytes at `at` for exactly this, and
        // `bytes` is a caller slice that cannot alias the arena (the arena is
        // borrowed mutably by `self` for the whole call).
        unsafe {
            let dst = (self.arena.as_mut_ptr() as *mut u8).add(at);
            core::ptr::copy_nonoverlapping(bytes.as_ptr(), dst, bytes.len());
            dst as *mut core::ffi::c_void
        }
    }

    /// Bump-allocate space for `T` plus `trailing_bytes` extra bytes.
    ///
    /// Returns `(entry_offset, trailing_offset)`. The trailing region starts
    /// immediately after `T` (aligned to 8 bytes).
    pub(crate) fn arena_alloc_with_trailing<T>(
        &mut self,
        trailing_bytes: usize,
    ) -> Result<(usize, usize), NodeError> {
        let align = core::mem::align_of::<T>().max(ARENA_GRAIN);
        let entry_size = core::mem::size_of::<T>();
        // Issue 1496 — a released region that holds the entry AND its trailing
        // region is reused whole. The trailing region keeps its rule: it starts
        // on a `u64` boundary after the entry, so the request is sized by that.
        let u64_align = core::mem::align_of::<u64>();
        let whole = Self::arena_region_len(entry_size.next_multiple_of(u64_align) + trailing_bytes);
        if let Some((entry_offset, granted)) = self.arena_take_freed(whole, align) {
            let trailing_offset = (entry_offset + entry_size).next_multiple_of(u64_align);
            crate::boot_report::note_alloc(whole, self.arena_used);
            self.note_entry_region(entry_offset, granted);
            return Ok((entry_offset, trailing_offset));
        }
        let entry_offset = self.arena_used.next_multiple_of(align);
        // Trailing region starts on an 8-byte (u64) boundary after the entry.
        let trailing_offset =
            (entry_offset + entry_size).next_multiple_of(core::mem::align_of::<u64>());
        // Issue 1667 — the region ends on the grain and is at least a node.
        let new_used = entry_offset + whole;
        debug_assert!(new_used >= trailing_offset + trailing_bytes);
        if new_used > self.arena.len() {
            // This path reported NOTHING until phase-412's self-report went in,
            // while its sibling `arena_alloc` has named the knob since issue
            // 0900. Half of arena exhaustion was therefore silent -- and it is
            // the half carrying buffered subscriptions and action entries,
            // which is what an island image actually allocates.
            return Err(self.arena_exhausted(
                core::any::type_name::<T>(),
                new_used - entry_offset,
                new_used - self.arena.len(),
            ));
        }
        self.arena_used = new_used;
        crate::boot_report::note_alloc(new_used - entry_offset, new_used);
        self.note_entry_region(entry_offset, new_used - entry_offset);
        Ok((entry_offset, trailing_offset))
    }

    /// The ONE exhaustion path every arena allocator goes through — issues
    /// 0900, 1036, 1496.
    ///
    /// It names the knob (`report_arena_exhausted`), writes the first failure
    /// and its shortfall to the boot record (the only channel a console-less
    /// board has), says whether the failure is a SHAPE problem rather than a
    /// size one (released regions that together hold the request, none of
    /// which alone does), and — where the image asked for it — halts through
    /// the platform's fatal hook, so the record survives instead of the board
    /// running on with an entity missing. Three spellings of this existed, and
    /// the `_with_trailing` one reported nothing until phase-412.
    fn arena_exhausted(&self, entity: &'static str, request: usize, shortfall: usize) -> NodeError {
        super::arena::report_arena_exhausted(
            entity,
            shortfall,
            self.arena_used,
            self.arena.len(),
            self.arena_released(),
            request,
        );
        crate::boot_report::note_alloc_failed(request, shortfall);
        super::arena::arena_exhaustion_is_fatal();
        NodeError::BufferTooSmall
    }

    /// Issue 1667 — read the free-list node at `offset`: `(next, len)`.
    fn arena_hole(&self, offset: usize) -> (usize, usize) {
        // SAFETY: `offset` is a listed free region: in bounds, grain-aligned and
        // at least `ARENA_MIN_REGION` long, written by `arena_set_hole`.
        unsafe {
            let p = (self.arena.as_ptr() as *const u8).add(offset) as *const usize;
            (p.read_unaligned(), p.add(1).read_unaligned())
        }
    }

    /// Issue 1667 — write the free-list node at `offset`.
    fn arena_set_hole(&mut self, offset: usize, next: usize, len: usize) {
        debug_assert!(len >= ARENA_MIN_REGION && offset + len <= self.arena.len());
        // SAFETY: as `arena_hole`; the region is free, so nothing else reads it.
        unsafe {
            let p = (self.arena.as_mut_ptr() as *mut u8).add(offset) as *mut usize;
            p.write_unaligned(next);
            p.add(1).write_unaligned(len);
        }
    }

    /// Point `prev`'s node (or the head, for `ARENA_FREE_NONE`) at `next`.
    fn arena_link(&mut self, prev: usize, next: usize) {
        if prev == ARENA_FREE_NONE {
            self.arena_free_head = next;
        } else {
            let (_, len) = self.arena_hole(prev);
            self.arena_set_hole(prev, next, len);
        }
    }

    /// Issue 1496 / 1667 — first-fit over the free list. Returns the offset and
    /// the length GRANTED, which is the request plus any tail too short to list
    /// on its own: that tail belongs to the allocation, so its release gives it
    /// back. A hole whose alignment slack would be too short to list is skipped
    /// rather than split, for the same reason — no byte is ever orphaned.
    fn arena_take_freed(&mut self, size: usize, align: usize) -> Option<(usize, usize)> {
        let mut prev = ARENA_FREE_NONE;
        let mut cur = self.arena_free_head;
        while cur != ARENA_FREE_NONE {
            let (next, len) = self.arena_hole(cur);
            let start = cur.next_multiple_of(align);
            let head = start - cur;
            let fits = start + size <= cur + len;
            if fits && (head == 0 || head >= ARENA_MIN_REGION) {
                let tail = cur + len - (start + size);
                let granted = if tail < ARENA_MIN_REGION {
                    size + tail
                } else {
                    size
                };
                // What stays listed: the head slack, the tail, both, or neither.
                let mut after = next;
                if tail >= ARENA_MIN_REGION {
                    let t = start + size;
                    self.arena_set_hole(t, after, tail);
                    after = t;
                }
                if head > 0 {
                    self.arena_set_hole(cur, after, head);
                } else {
                    self.arena_link(prev, after);
                }
                return Some((start, granted));
            }
            prev = cur;
            cur = next;
        }
        None
    }

    /// Issue 1496 / 1667 — give a region back. It is inserted in address order
    /// and coalesced with both neighbours, so a loop that frees what it
    /// allocated returns the arena to the shape it had; a hole that then ends
    /// at `arena_used` is handed back to the bump pointer.
    pub(crate) fn arena_release(&mut self, offset: usize, len: usize) {
        debug_assert!(len >= ARENA_MIN_REGION && len.is_multiple_of(ARENA_GRAIN));
        // `pprev` -> `prev` -> [offset] -> `cur`, in address order.
        let mut pprev = ARENA_FREE_NONE;
        let mut prev = ARENA_FREE_NONE;
        let mut cur = self.arena_free_head;
        while cur != ARENA_FREE_NONE && cur < offset {
            pprev = prev;
            prev = cur;
            cur = self.arena_hole(cur).0;
        }
        let (mut start, mut size) = (offset, len);
        let mut next = cur;
        if next != ARENA_FREE_NONE && start + size == next {
            let (after, next_len) = self.arena_hole(next);
            size += next_len;
            next = after;
        }
        if prev != ARENA_FREE_NONE {
            let (_, prev_len) = self.arena_hole(prev);
            if prev + prev_len == start {
                start = prev;
                size += prev_len;
                // `prev` is absorbed: link from ITS predecessor.
                prev = pprev;
            }
        }
        if start + size == self.arena_used {
            // The top of the arena: give it back to the bump pointer.
            self.arena_used = start;
            self.arena_link(prev, next);
            return;
        }
        self.arena_set_hole(start, next, size);
        self.arena_link(prev, start);
    }

    /// Issue 1496 — bytes released back to the arena and not yet reused.
    /// Bytes handed back to the bump pointer are not counted: `arena_used`
    /// already went down by them.
    pub fn arena_released(&self) -> usize {
        let mut total = 0;
        let mut cur = self.arena_free_head;
        while cur != ARENA_FREE_NONE {
            let (next, len) = self.arena_hole(cur);
            total += len;
            cur = next;
        }
        total
    }

    /// Issue 1667 — how many separate holes the free list holds. For tests and
    /// diagnostics.
    pub fn arena_holes(&self) -> usize {
        let mut count = 0;
        let mut cur = self.arena_free_head;
        while cur != ARENA_FREE_NONE {
            count += 1;
            cur = self.arena_hole(cur).0;
        }
        count
    }

    /// Issue 1496 — RELEASE one callback entry: drop the entry in place (its
    /// RMW handles' `Drop`s destroy the backend entities, so nothing stays
    /// advertised), free its callback slot, and give its arena bytes back for
    /// reuse. `false`, touching nothing, when `index` is not a live entry of
    /// `kind`.
    ///
    /// Issue 1631 — the bytes released are the ones `emplace_entry` RECORDED
    /// from the allocator (`CallbackMeta::arena_len`), entry and trailing
    /// region together. 1496's form took the size from the caller, which had
    /// to restate the concrete entry type — impossible for a buffered
    /// subscription (its trailing region is sized at runtime) or a timer (its
    /// closure type is the registering crate's).
    ///
    /// # Safety
    /// No handle naming `index` may be used afterwards: the slot and its bytes
    /// go to the next registration.
    pub(crate) unsafe fn release_entry(&mut self, index: usize, kind: EntryKind) -> bool {
        let live = self
            .entries
            .get(index)
            .and_then(|e| e.as_ref())
            .is_some_and(|m| m.kind == kind);
        if !live {
            return false;
        }
        // Issue 1667 — the entry's own callback is running (it, or something it
        // called, asked for this release). Mark it and let `finish_dispatch` do
        // the release when the callback returns. The handle stops resolving
        // now, so a second request answers `false` and nothing dispatches it.
        //
        // Issue 1705 — the same for an entry an OS-priority WORKER holds
        // (`WORKER_QUEUED`): its callback may be running on the worker task, or
        // its item may still be queued. The worker skips an item whose release
        // is pending, and `reap_deferred_releases` completes the release once
        // the worker has let go. This is also the whole of what a release
        // requested FROM the worker thread does: one atomic flag, nothing the
        // spin thread is touching.
        if let Some(tag) = self.slot_tags.get(index)
            && tag.flags() & super::types::SlotTag::IN_FLIGHT != 0
        {
            let was = tag.set(super::types::SlotTag::RELEASE_PENDING);
            return was & super::types::SlotTag::RELEASE_PENDING == 0;
        }
        let Some(meta) = self.entries[index].take() else {
            return false;
        };
        // SAFETY: the entry was written by its registration and not yet
        // dropped; `drop_fn` matches its concrete type.
        unsafe {
            let data_ptr = (self.arena.as_mut_ptr() as *mut u8).add(meta.offset);
            (meta.drop_fn)(data_ptr);
        }
        self.sched_context_bindings[index] = super::sched_context::SchedContextId(0);
        if let Some(st) = self.sporadic_states.get_mut(index) {
            *st = None;
        }
        // phase10-B3 -- a released trigger subscription stops starting routes.
        if matches!(kind, EntryKind::Subscription) {
            super::monitor::route_unbind(self.monitor_table, index);
        }
        if let Some(len) = meta.arena_len.get() {
            self.arena_release(meta.offset, len);
        }
        if let Some(tag) = self.slot_tags.get_mut(index) {
            tag.owner = 0;
            tag.reset_flags();
        }
        true
    }

    /// Issue 1667 — mark `slot`'s callback as running, so a release it requests
    /// is deferred rather than dropping the entry under it.
    #[inline]
    fn begin_dispatch(slot_tags: &[super::types::SlotTag], slot: usize) {
        if let Some(tag) = slot_tags.get(slot) {
            tag.set(super::types::SlotTag::IN_DISPATCH);
        }
    }

    /// Issue 1705 — `slot`'s entry is not to be touched by the spin thread
    /// this pass: an OS-priority worker holds it (`WORKER_QUEUED` — its item
    /// is queued or its callback is running, so even READING its state for
    /// readiness races the worker), or its release is pending (it is never
    /// dispatched again).
    #[inline]
    fn slot_held(slot_tags: &[super::types::SlotTag], slot: usize) -> bool {
        slot_tags.get(slot).is_some_and(|t| {
            t.flags()
                & (super::types::SlotTag::WORKER_QUEUED | super::types::SlotTag::RELEASE_PENDING)
                != 0
        })
    }

    /// Issue 1667 — `slot`'s callback has returned. Complete a release it
    /// requested while running.
    fn finish_dispatch(&mut self, slot: usize) {
        let Some(tag) = self.slot_tags.get(slot) else {
            return;
        };
        let was = tag.clear(super::types::SlotTag::IN_DISPATCH);
        if was & super::types::SlotTag::RELEASE_PENDING != 0 {
            self.complete_deferred_release(slot);
        }
    }

    /// Issue 1667 / 1705 — finish a release that was deferred while a dispatch
    /// of the entry was in flight, if none is any more. A no-op while one still
    /// is (a worker holding the entry): `reap_deferred_releases` retries.
    fn complete_deferred_release(&mut self, slot: usize) {
        let Some(tag) = self.slot_tags.get(slot) else {
            return;
        };
        let f = tag.flags();
        if f & super::types::SlotTag::RELEASE_PENDING == 0
            || f & super::types::SlotTag::IN_FLIGHT != 0
        {
            return;
        }
        if let Some(kind) = self
            .entries
            .get(slot)
            .and_then(|e| e.as_ref())
            .map(|m| m.kind)
        {
            // SAFETY: the release was requested through a generation-checked
            // handle, and `resolve_handle` has refused the slot since; no
            // dispatch holds the entry (`IN_FLIGHT` is clear, read Acquire, so
            // a worker's writes before it let go are visible).
            let _ = unsafe { self.release_entry(slot, kind) };
        }
    }

    /// Issue 1705 — complete every deferred release whose last dispatch has
    /// finished. A release deferred behind an OS-priority WORKER cannot be
    /// completed by the worker (it may not touch the executor), so the spin
    /// thread picks it up here, at the top of every `spin_once`.
    pub(crate) fn reap_deferred_releases(&mut self) {
        for slot in 0..self.slot_tags.len() {
            if self.slot_tags[slot].flags() & super::types::SlotTag::RELEASE_PENDING != 0 {
                self.complete_deferred_release(slot);
            }
        }
    }

    /// Issue 1631 — release a SUBSCRIPTION entry, whatever registration shape
    /// made it (typed, raw, in-place, buffered, with-info). See
    /// `release_entry` (crate-private): the entry is dropped, so its
    /// subscriber leaves the graph; its slot and arena bytes are reused by the
    /// next registration. `false`, touching nothing, when `handle` is not a
    /// live subscription.
    ///
    /// # Safety
    /// No copy of `handle` may be used afterwards — the slot is handed to the
    /// next registration, which may be of any kind.
    pub unsafe fn release_subscription(&mut self, handle: HandleId) -> bool {
        match self.resolve_handle(handle) {
            Some(slot) => unsafe { self.release_entry(slot, EntryKind::Subscription) },
            None => false,
        }
    }

    /// Issue 1631 — release a TIMER entry; the timer's callback (and anything
    /// its closure captured) is dropped and never fires again. As
    /// [`release_subscription`](Self::release_subscription).
    ///
    /// # Safety
    /// As [`release_subscription`](Self::release_subscription).
    pub unsafe fn release_timer(&mut self, handle: HandleId) -> bool {
        match self.resolve_handle(handle) {
            Some(slot) => unsafe { self.release_entry(slot, EntryKind::Timer) },
            None => false,
        }
    }

    /// Issue 1631 — release a SERVICE SERVER entry; the server leaves the
    /// graph. As [`release_subscription`](Self::release_subscription).
    ///
    /// # Safety
    /// As [`release_subscription`](Self::release_subscription).
    pub unsafe fn release_service(&mut self, handle: HandleId) -> bool {
        match self.resolve_handle(handle) {
            Some(slot) => unsafe { self.release_entry(slot, EntryKind::Service) },
            None => false,
        }
    }

    /// Issue 1631 — release a SERVICE CLIENT entry; the client leaves the
    /// graph and any reply it was waiting for is abandoned with it. As
    /// [`release_subscription`](Self::release_subscription).
    ///
    /// # Safety
    /// As [`release_subscription`](Self::release_subscription).
    pub unsafe fn release_service_client(&mut self, handle: HandleId) -> bool {
        match self.resolve_handle(handle) {
            Some(slot) => unsafe { self.release_entry(slot, EntryKind::ServiceClient) },
            None => false,
        }
    }

    /// Issue 1667 — release a GUARD CONDITION entry: its callback is dropped and
    /// `spin_once` stops polling it; the slot and its arena bytes go to the next
    /// registration.
    ///
    /// Unlike the other release verbs this one has a contract a generation
    /// cannot discharge. The [`GuardCondition`] trigger handle holds a pointer
    /// to the flag INSIDE the entry, and it is `Clone` + `Send`, so a clone on
    /// another thread (an ISR, a worker) would write into whatever reuses those
    /// bytes. The C++ `GuardCondition` is non-copyable and the one holder of its
    /// trigger handle, which is why its destructor can call this.
    ///
    /// # Safety
    /// No [`GuardCondition`] trigger handle for this entry — the one
    /// registration returned, or any clone of it — may be used afterwards.
    pub unsafe fn release_guard_condition(&mut self, handle: HandleId) -> bool {
        match self.resolve_handle(handle) {
            Some(slot) => unsafe { self.release_entry(slot, EntryKind::GuardCondition) },
            None => false,
        }
    }

    /// Find the next free entry slot index.
    pub(crate) fn next_entry_slot(&self) -> Result<usize, NodeError> {
        self.entries
            .iter()
            .position(|e| e.is_none())
            // Issue 0095 — the callback-entry table (`NROS_EXECUTOR_MAX_CBS`,
            // default 4) is full. Distinct from `BufferTooSmall` so the register
            // seam can tell the user to raise the knob.
            .ok_or(NodeError::ExecutorFull)
    }

    /// Install a finished [`CallbackMeta`] into its slot.
    ///
    /// phase-8 (`docs/design/callback_tracing.rst`) — the ONE choke point
    /// every registration site funnels through, so the
    /// `nros_callback_register(handle, kind, name)` event is emitted once,
    /// here, rather than at the 25 sites that build a `CallbackMeta`. The
    /// design's registration half is deliberately EXHAUSTIVE across every
    /// `EntryKind` even though the leaf hooks are staged: a callback that was
    /// registered but never observed then prints as "registered, not
    /// instrumented" instead of being silently absent, so an incomplete hook
    /// set announces itself in the output rather than looking like a
    /// measurement.
    ///
    /// It is the assignment — not [`next_entry_slot`](Self::next_entry_slot)
    /// — because a slot is claimed BEFORE the fallible work (session lookup,
    /// arena allocation, handle creation) that can still return `Err`.
    /// Emitting at slot-claim time would announce callbacks that do not
    /// exist.
    pub(crate) fn emplace_entry(
        &mut self,
        slot: usize,
        mut meta: CallbackMeta,
        name: TraceName<'_>,
    ) {
        // Issue 1631 — record the region the entry's allocation handed out,
        // so `release_entry` gives back exactly that. Matched on the OFFSET so
        // a stale region (a registration that failed after allocating) is
        // never attributed to a different entry.
        meta.arena_len = match self.pending_region.take() {
            Some(r) if r.offset == meta.offset => super::arena::ArenaLen::new(r.len),
            _ => super::arena::ArenaLen::UNRECORDED,
        };
        trace_register(slot, meta.kind, name);
        // phase10-B3 -- a subscription on a route's trigger topic is the
        // route's trigger. The table is installed before any node exists.
        if let (EntryKind::Subscription, TraceName::Text(topic)) = (meta.kind, &name) {
            super::monitor::route_bind(self.monitor_table, topic, slot);
        }
        // phase-463 W7 — the slot's identity for the host profile, keyed on the
        // arena base the dispatch sees (stable for the executor's life).
        #[cfg(feature = "profile-mode")]
        super::profile::on_register(self.arena.as_ptr() as usize, slot, meta.kind, name);
        self.entries[slot] = Some(meta);
        // phase-476 W0 — a new occupant gets a new generation, so every handle
        // issued for the slot's previous occupant stops resolving. Owner is
        // cleared; a registration made for a node sets it after this
        // (`set_entry_owner`).
        if let Some(tag) = self.slot_tags.get_mut(slot) {
            tag.generation = tag.next_generation();
            tag.owner = 0;
            tag.reset_flags();
        }
    }

    /// phase-476 W0 — the handle for the CURRENT occupant of `slot`. Every
    /// registration returns this, after `emplace_entry` has stamped the slot.
    pub(crate) fn handle_for(&self, slot: usize) -> HandleId {
        let generation = self.slot_tags.get(slot).map_or(0, |t| t.generation);
        HandleId::new(slot, generation)
    }

    /// phase-476 W0 (issue 1667) — the slot `id` names, if and only if `id` was
    /// issued for the entry that occupies it NOW. A handle whose entry was
    /// released, or whose slot has since been taken by another registration of
    /// any kind, answers `None`, never the next occupant.
    pub fn resolve_handle(&self, id: HandleId) -> Option<usize> {
        let slot = id.slot();
        let live = self.entries.get(slot).is_some_and(|e| e.is_some())
            && self
                .slot_tags
                .get(slot)
                .is_none_or(|t| t.flags() & super::types::SlotTag::RELEASE_PENDING == 0);
        // Generation 0 is `HandleId::for_owned_slot`: a uniquely-owned holder
        // naming its own live slot. Every ISSUED handle carries >= 1.
        let current = id.generation() == 0
            || self
                .slot_tags
                .get(slot)
                .is_some_and(|t| t.generation == id.generation());
        (live && current).then_some(slot)
    }

    /// Issue 1703 — the slot behind a by-index accessor's `entry_index`
    /// argument, which callers hand in in TWO spellings: a bare slot (nros-c's
    /// stored `arena_entry_index`, `node_runtime`'s resolved slot, an action's
    /// owned slot) or the PACKED handle an FFI issued (`HandleId::to_raw`,
    /// what nros-cpp's `handle_id_` and nros-c's `subscription.handle_id`
    /// hold since phase-476 W0). A bare slot has generation 0, so both decode
    /// through [`HandleId::from_raw`] and resolve here: the slot for a live
    /// entry, generation-checked when one was issued, `None` for a stale or
    /// foreign handle.
    ///
    /// The five accessors indexed `entries` with the argument as given. W0 made
    /// the FFI value a packed `(generation << 16) | slot`, so every packed
    /// caller read past the table and got `None` — `async_send_request` on a
    /// C++ callback client returned `INVALID_ARGUMENT` on every call, and the
    /// granted-QoS read-backs answered for no entity.
    fn slot_of_raw(&self, entry_index: usize) -> Option<usize> {
        self.resolve_handle(HandleId::from_raw(entry_index))
    }

    /// phase-476 W0 — [`resolve_handle`](Self::resolve_handle) as an index that
    /// is OUT OF RANGE for a stale handle, so an existing `entries.get(..)`
    /// chain answers `None` for it with no further change.
    pub(crate) fn live_slot(&self, id: HandleId) -> usize {
        self.resolve_handle(id).unwrap_or(usize::MAX)
    }

    /// phase-476 W0 — record that `node` registered the entry `id` names, so
    /// [`release_node`](Self::release_node) can find it. `false` when `id` is
    /// stale.
    pub fn set_entry_owner(&mut self, id: HandleId, node: crate::executor::NodeId) -> bool {
        let Some(slot) = self.resolve_handle(id) else {
            return false;
        };
        let Ok(biased) = u8::try_from(node.index() + 1) else {
            return false;
        };
        self.slot_tags[slot].owner = biased;
        true
    }

    /// phase-476 W0 — release every entry `node` registered, whatever its kind.
    /// Returns how many were released.
    ///
    /// This is what a node's destruction calls. A C++ callback's capture is
    /// copied into the arena and commonly holds the node's `this`, so an entry
    /// that outlived its node would dispatch into freed memory.
    ///
    /// # Safety
    /// No handle to any of those entries may be used afterwards except through
    /// a lookup that checks the generation ([`resolve_handle`](Self::resolve_handle)),
    /// which every public lookup on this type does.
    pub unsafe fn release_node(&mut self, node: crate::executor::NodeId) -> usize {
        let Ok(biased) = u8::try_from(node.index() + 1) else {
            return 0;
        };
        let mut released = 0;
        for slot in 0..self.entries.len() {
            if self.slot_tags.get(slot).is_some_and(|t| t.owner == biased) {
                let kind = match self.entries[slot].as_ref() {
                    Some(m) => m.kind,
                    None => continue,
                };
                // SAFETY: forwarded from this function's contract.
                if unsafe { self.release_entry(slot, kind) } {
                    released += 1;
                }
            }
        }
        released
    }

    /// Open a subscription: claim a slot, resolve the node's identity, create
    /// the backend subscriber, and answer the in-place question ONCE.
    ///
    /// **phase-456 W8 — the one prologue.** Every registration that creates its
    /// own subscriber goes through here, in every language. The two callers
    /// that do not are the two that cannot: `add_arena_subscription_callback`
    /// is handed a subscriber someone else built (uORB needs a
    /// `&'static orb_metadata`, which no `TopicInfo` can express), so there is
    /// no topic to resolve and no session to reach — a fourth axis under issue
    /// 1319's rows that W8's three-axis decomposition did not predict: WHO
    /// CREATED THE SUBSCRIBER. It is a real axis, it is orthogonal to the other
    /// three, and it has exactly one member.
    ///
    /// Everything downstream of this function differs per delivery shape: the
    /// arena entry's type, its `try_process`, and whether it has a receive
    /// region at all. That part is irreducible and stays at the call site.
    pub(crate) fn open_subscription(
        &mut self,
        req: &SubscriptionRequest<'_>,
    ) -> Result<SubscriptionOpen, NodeError> {
        let slot = self.next_entry_slot()?;
        let (node_name, ns, session_idx) = match req.node_id {
            Some(id) => {
                let r = self
                    .nodes
                    .get(id.index())
                    .ok_or(NodeError::InvalidSchedContextBinding)?;
                (r.name.clone(), r.namespace.clone(), r.session_idx)
            }
            None => (self.node_name.clone(), self.namespace.clone(), 0u8),
        };
        let mut topic = TopicInfo::new(req.topic_name, req.type_name, req.type_hash)
            .with_domain(self.domain_id)
            .with_namespace(&ns);
        if !node_name.is_empty() {
            topic = topic.with_node_name(&node_name);
        }
        // Phase 231 (RFC-0038) / phase-402 W2 — hand the backend a
        // receive-buffer size so it can size-class its receive storage
        // (zenoh-pico: small vs large). Only when the caller actually stated
        // one: `with_rx_buffer_hint(0)` would be a claim of "zero bytes", not
        // "no opinion".
        if let Some(hint) = req.backend_hint {
            if hint != 0 {
                topic = topic.with_rx_buffer_hint(hint);
            }
        }
        // phase-454 W10/W13 — the depth this registration asks for against the
        // depth this system DECLARED for the topic. Before the backend call AND
        // before the arena claim, so the region this registration takes and the
        // one the build reserved are the same number; unchanged when nothing
        // was declared, which is every image with no contract sidecar. See
        // `declared_qos::honour` for why Rust TAKES the declared depth where C
        // and C++ assert it at the call site.
        //
        // phase-456 W8 — this used to be `declared_qos::check` here and
        // `honour` in each of the twelve hand-rolled prologues this function
        // replaced. Collapsing them onto `check` would have silently reverted
        // W13 for every Rust registration: `check` validates and returns, while
        // `honour` REWRITES the depth the backend is then given. One consulting
        // site is the point of this function, and it has to be the honouring
        // one.
        let qos = crate::declared_qos::honour(topic.type_name, topic.name, req.qos)?;
        let handle = {
            let session = self
                .session_at_mut(session_idx)
                .ok_or(NodeError::BackendMismatch)?;
            session
                .create_subscription(&topic, qos)
                .map_err(NodeError::Transport)?
        };
        // Phase 231 Wave 0.2 (RFC-0038), phase-456 W8 — THE consulting site.
        // Deliberately `&&`-guarded by the delivery shape rather than by the
        // language: a shape that must hand the callback more than borrowed
        // bytes cannot use the capability however capable the backend is.
        let in_place = req.in_place_capable && {
            use nros_rmw::Subscription as _;
            handle.supports_process_in_place()
        };
        // phase-457 W3 — tell a metadata probe what this CALL SITE answered.
        //
        // `req.in_place_capable` and NOT `in_place`: the conjunction above
        // includes the backend a probe links, which is the RECORDING backend and
        // not the one the image ships. The sizing descriptor knows the shipped
        // backend from the image's `rmw` name and composes the two halves
        // itself; what it cannot see is this half, which is why nine of the
        // eleven registration entry points were previously credited with a
        // capability they do not have (issue 1340).
        //
        // AFTER the backend call, so a registration that failed reports
        // nothing — a row for a subscription that does not exist would raise the
        // probe's count, and an over-count of subscriptions is a real cost in
        // every pool that derives from it.
        #[cfg(feature = "registration-observer")]
        super::registration_observer::observe(super::registration_observer::ObservedRegistration {
            topic: topic.name,
            type_name: topic.type_name,
            in_place_capable: req.in_place_capable,
            // Issue 1648 -- the slot this registration is about to claim, read
            // off the request rather than inferred: `DEFAULT_RX_BUF_SIZE`
            // (`RX_BUF`) is the closure buffer (`unbounded`), anything else a
            // stated bound.
            claims_closure_buffer: req.slot_bytes == crate::config::DEFAULT_RX_BUF_SIZE,
        });
        Ok(SubscriptionOpen {
            slot,
            handle,
            qos,
            in_place,
            slot_bytes: req.slot_bytes,
        })
    }

    /// Typed buffered subscription core (the `node_mut(id).subscription(t)
    /// .typed::<M>()` builder lowers here). Routes the typed subscription
    /// through the [`NodeId`]'s session + identity (rclcpp `add_node` pattern).
    ///
    /// Phase 403 W2 -- `rx_bytes` says how many bytes each buffer slot claims
    /// from the arena.
    ///
    /// phase-392 W3c -- `Some(n)` is verbatim; **`None` now means DERIVE from
    /// `M`**, falling back to `RX_BUF` only where no bound is reachable (an
    /// unbounded type, or a backend whose `MessageForRmw` carries no schema).
    /// It used to mean `RX_BUF` unconditionally, so a subscription that named no
    /// number was charged the global for every slot and a consumer who did not
    /// know `.rx_buffer_from_type()` existed paid it silently. The opt-out is
    /// now the explicit one: `.rx_buffer::<N>()` passes `Some(N)`.
    ///
    /// It is a RUNTIME `usize` and not a second const generic because on THIS
    /// path `RX_BUF` was never an array length -- it reaches
    /// `buffered_region_size`, `TripleBuffer::init` and `SpscRing::init`, all of
    /// which take a plain `usize`. That is the only reason W2's per-type sizing
    /// is expressible here at all: `Sub<{ M::BOUND }>` is
    /// `error: generic parameters may not be used in const operations` on stable
    /// (rustc 1.97.1), so the sibling `register_subscription_with_info_sized_inner`
    /// / `..._with_safety_sized_inner`, whose entries really do hold
    /// `[u8; RX_BUF]`, still need `nros::rx_buffer_for!` at the call site.
    pub(crate) fn register_subscription_buffered_on<M, F, const RX_BUF: usize>(
        &mut self,
        node_id: super::node_record::NodeId,
        topic_name: &str,
        qos: QoSProfile,
        callback: F,
        group: Option<&str>,
        rx_bytes: Option<usize>,
    ) -> Result<HandleId, NodeError>
    where
        M: crate::rmw_type_registry::MessageForRmw + 'static,
        F: FnMut(&M) + 'static,
    {
        type Entry<M, F> = SubBufferedEntry<M, F>;

        // RFC-0088 / phase-421 W1 — the message's declared format must be the
        // one the linked backend speaks. Universal: the const lives on
        // `RosMessage`, which `MessageForRmw` requires under every backend.
        crate::format_check::assert_message_format::<M>();
        // Phase 212.K.7.6.b — see `create_publisher_on`.
        crate::rmw_type_registry::register_type::<M>()?;

        // W3b.5 — contracted-endpoint age hook (None = free).
        let age_mon = self.age_lookup::<M>(topic_name);

        // Phase 403 W2 -- one number for the whole allocation. The region size,
        // the strategy's slot size and the pointer arithmetic must agree, so
        // they read the same local rather than each spelling `RX_BUF`.
        //
        // phase-392 W3c -- and `None` no longer means `RX_BUF`, it means DERIVE.
        // This is the one choke point every default registration funnels
        // through, so putting the derivation here is what makes it the default
        // at all four of them (`create_subscription`, `create_subscription_in_group`,
        // the builder's `build()`, and the `/clock` time source) instead of at
        // whichever one a wave happened to touch. An explicit `Some(n)` -- what
        // `.rx_buffer::<N>()` and `.rx_buffer_from_type()` pass -- is still
        // verbatim, so the opt-out and the opt-in both bypass this line.
        let slot_bytes = crate::rmw_type_registry::subscription_slot_bytes::<M>(rx_bytes, RX_BUF);

        let open = self.open_subscription(&SubscriptionRequest {
            node_id: Some(node_id),
            topic_name,
            type_name: <M as RosMessage>::TYPE_NAME,
            type_hash: <M as RosMessage>::TYPE_HASH,
            qos,
            // Phase 392 W3a — the TYPE's bound, not `RX_BUF`. The arena slot
            // size says nothing about the message: a 64-byte type and a 4 KiB
            // type both hinted the same number, so the class was chosen from a
            // value unrelated to what arrives. Falls back to `RX_BUF` for an
            // unbounded type, where no bound exists to state (phase 380).
            backend_hint: Some(crate::rmw_type_registry::subscription_rx_hint::<M>(RX_BUF)),
            slot_bytes,
            // A typed Rust callback takes `&M` and nothing else, so borrowed
            // bytes are enough: deserialize straight from the backend's slot.
            in_place_capable: true,
        })?;
        let SubscriptionOpen {
            slot,
            handle,
            qos,
            in_place,
            slot_bytes,
        } = open;

        // Phase 231 Wave 0.2 (RFC-0038) — in-place dispatch when the backend
        // advertises it: deserialize straight from the borrowed receive slot,
        // no arena buffer (copy #1 removed). Else the buffered path below.
        if in_place {
            let entry_offset = self.arena_alloc::<SubInplaceEntry<M, F>>()?;
            unsafe {
                let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
                let entry_ptr = arena_ptr.add(entry_offset) as *mut SubInplaceEntry<M, F>;
                core::ptr::write(
                    entry_ptr,
                    SubInplaceEntry {
                        handle,
                        callback,
                        age_mon,
                        _phantom: PhantomData,
                    },
                );
            }
            let meta = CallbackMeta {
                offset: entry_offset,
                kind: EntryKind::Subscription,
                arena_len: super::arena::ArenaLen::UNRECORDED,
                try_process: sub_inplace_try_process::<M, F>,
                has_data: sub_inplace_has_data::<M, F>,
                pre_sample: no_pre_sample,
                invocation: InvocationMode::OnNewData,
                drop_fn: drop_entry::<SubInplaceEntry<M, F>>,
            };
            self.emplace_entry(slot, meta, TraceName::Text(topic_name));
            self.apply_node_default_sched(slot, Some(node_id), group);
            return Ok(self.handle_for(slot));
        }

        let (_slot_count, trailing_bytes) = buffered_region_size(qos.depth, slot_bytes);

        let (entry_offset, trailing_offset) =
            self.arena_alloc_with_trailing::<Entry<M, F>>(trailing_bytes)?;

        let buf_ptr = unsafe { (self.arena.as_mut_ptr() as *mut u8).add(trailing_offset) };

        let buffer = if qos.depth <= 1 {
            BufferStrategy::Triple(unsafe { TripleBuffer::init(buf_ptr, slot_bytes) })
        } else {
            BufferStrategy::Ring(unsafe { SpscRing::init(buf_ptr, slot_bytes, qos.depth as usize) })
        };

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(entry_offset) as *mut Entry<M, F>;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    buffer,
                    callback,
                    age_mon,
                    _phantom: PhantomData,
                },
            );
        }

        let meta = CallbackMeta {
            offset: entry_offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_buffered_try_process::<M, F>,
            has_data: sub_buffered_has_data::<M, F>,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry<M, F>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        // Phase 104.C.4 — apply Node's default SchedContext.
        self.apply_node_default_sched(slot, Some(node_id), group);
        Ok(self.handle_for(slot))
    }

    /// Generic (type-erased) buffered subscription core (the
    /// `node_mut(id).subscription(t).generic(ty, hash)` builder lowers here).
    /// Routes the subscriber creation through the [`NodeId`]'s
    /// session + identity (rclcpp `add_node` pattern).
    ///
    /// Use this in bridge code where two Nodes bind to different RMW
    /// backends:
    ///
    /// ```ignore
    /// let node_in = exec.node_builder("ingress").rmw("zenoh").build()?;
    /// let pub_out = exec.with_node(node_out, |n| {
    ///     n.create_publisher_raw("/fwd", TYPE, HASH)
    /// })??;
    /// exec.register_subscription_buffered_raw_on::<_, 1024>(
    ///     node_in, "/src", TYPE, HASH, qos(),
    ///     move |bytes: &[u8]| { let _ = pub_out.publish_raw(bytes); },
    /// )?;
    /// ```
    pub(crate) fn register_subscription_buffered_raw_on<F, const RX_BUF: usize>(
        &mut self,
        node_id: super::node_record::NodeId,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut(&[u8]) + 'static,
    {
        // Issue #52 — fold the node's baked overrides for this topic before the
        // backend-compat check runs inside `create_subscription`.
        //
        // **This is the one registration that does it**, which phase-456 W8
        // noticed while collapsing the twelve prologues into one and did NOT
        // change: the other eleven reach `create_subscription` with the QoS
        // their caller passed. Whether that is a defect or a deliberate limit
        // of the generic bridge path is a question with a measurable answer and
        // no answer here, so the asymmetry stays where it was, stated.
        let overrides = self
            .nodes
            .get(node_id.index())
            .ok_or(NodeError::InvalidSchedContextBinding)?
            .qos_overrides;
        let qos = super::node_record::apply_qos_override_codes(
            qos,
            topic_name,
            nros_rmw::QoSOverrideRole::Subscription,
            overrides,
        );

        let SubscriptionOpen {
            slot,
            handle,
            qos,
            in_place,
            slot_bytes,
        } = self.open_subscription(&SubscriptionRequest {
            node_id: Some(node_id),
            topic_name,
            type_name,
            type_hash,
            qos,
            backend_hint: None,
            slot_bytes: RX_BUF,
            // Issue 1340 — `FnMut(&[u8])` IS a borrowed-bytes callback, which is
            // exactly what `process_raw_in_place` hands over, so this shape takes
            // the in-place row the way the C raw path does.
            //
            // This used to be `false` because the buffered entry is shared with
            // `Self::add_arena_subscription_callback` and "an in-place twin would
            // have to serve both". It does not: that caller supplies its own
            // subscriber and never reaches `open_subscription`, so no in-place
            // report can arrive there. The branch below is local to this entry
            // point, and the shared buffered emplace is untouched.
            //
            // phase-457 W5 (issue 1522) — spelled as the SHAPE rather than as a
            // literal, because the declarative registrar lowers here and the
            // metadata probe must state the same bool without registering. One
            // definition (`DeclaredSubscriptionShape::in_place_capable`), two
            // readers, so the row the build prices and the claim made here
            // moved together when it flipped.
            in_place_capable: super::declared_shape::DeclaredSubscriptionShape::BufferedRaw
                .in_place_capable(),
        })?;

        if in_place {
            // No receive region: the backend's slot is the buffer for the
            // duration of the callback. This is the whole of issue 1340's saving
            // on the generic path — `buffered_region_size(depth, RX_BUF)` is
            // never reserved.
            type Entry<F> = super::arena::SubInplaceRawEntry<F>;
            let entry_offset = self.arena_alloc::<Entry<F>>()?;
            unsafe {
                let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
                let entry_ptr = arena_ptr.add(entry_offset) as *mut Entry<F>;
                core::ptr::write(entry_ptr, Entry { handle, callback });
            }
            let meta = CallbackMeta {
                offset: entry_offset,
                kind: EntryKind::Subscription,
                arena_len: super::arena::ArenaLen::UNRECORDED,
                try_process: super::arena::sub_inplace_raw_try_process::<F>,
                has_data: super::arena::sub_inplace_raw_has_data::<F>,
                pre_sample: no_pre_sample,
                invocation: InvocationMode::OnNewData,
                drop_fn: drop_entry::<Entry<F>>,
            };
            // Same trace name as the buffered arm, so a trace reads the same
            // whichever dispatch the backend chose.
            self.emplace_entry(slot, meta, TraceName::Slot("sub", slot));
        } else {
            self.emplace_raw_buffered_subscription(slot, handle, qos, slot_bytes, callback)?;
        }
        // Phase 104.C.4 — apply Node's default SchedContext.
        self.apply_node_default_sched(slot, Some(node_id), None);
        Ok(self.handle_for(slot))
    }

    /// Register a borrowed (zero-copy) buffered subscription (Phase 229.6,
    /// issue 0007 / RFC-0033 `borrowed` mode).
    ///
    /// `B` is the code-generated borrowed-message marker (e.g. `ImageViewable`)
    /// implementing [`ViewableMessage`](nros_core::ViewableMessage); the
    /// callback receives `&B::View<'a>` — a lifetime-carrying message whose
    /// unbounded sequence/string fields borrow directly from the receive buffer
    /// (no `heapless::Vec` copy). The view is valid only for the callback's
    /// duration.
    ///
    /// **Triple-buffer only.** A borrowed view must reference exactly one
    /// well-defined buffer slot for the callback's duration; an SPSC ring
    /// (`qos.depth > 1`) keeps several samples in flight with no single such
    /// slot. `qos.depth > 1` is therefore rejected with
    /// [`TransportError::Unsupported`].
    pub(crate) fn register_subscription_buffered_borrowed_on<B, F, const RX_BUF: usize>(
        &mut self,
        node_id: super::node_record::NodeId,
        topic_name: &str,
        qos: QoSProfile,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        B: nros_core::ViewableMessage + 'static,
        F: for<'a> FnMut(&B::View<'a>) + 'static,
    {
        type Entry<B, F> = SubBufferedViewEntry<B, F>;

        // Borrowed views require a single well-defined slot (triple buffer).
        if qos.depth > 1 {
            return Err(NodeError::Transport(TransportError::Unsupported));
        }

        let SubscriptionOpen { slot, handle, .. } =
            self.open_subscription(&SubscriptionRequest {
                node_id: Some(node_id),
                topic_name,
                type_name: <B as ViewableMessage>::TYPE_NAME,
                type_hash: <B as ViewableMessage>::TYPE_HASH,
                qos,
                backend_hint: None,
                slot_bytes: RX_BUF,
                // The view borrows the arena's own triple-buffer slot for the
                // callback's duration and `ViewableMessage::deserialize_view` is
                // what produces it, so there is no `FnMut(&[u8])` here to hand a
                // backend slot to. Making this shape in-place is a real option and
                // a separate change: it would move the borrow from the arena to the
                // backend's ring, which is a lifetime argument this item did not
                // make.
                in_place_capable: false,
            })?;

        let (_slot_count, trailing_bytes) = buffered_region_size(qos.depth, RX_BUF);
        let (entry_offset, trailing_offset) =
            self.arena_alloc_with_trailing::<Entry<B, F>>(trailing_bytes)?;
        let buf_ptr = unsafe { (self.arena.as_mut_ptr() as *mut u8).add(trailing_offset) };

        // depth <= 1 guaranteed above → always triple buffer.
        let buffer = BufferStrategy::Triple(unsafe { TripleBuffer::init(buf_ptr, RX_BUF) });

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(entry_offset) as *mut Entry<B, F>;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    buffer,
                    callback,
                    _phantom: PhantomData,
                },
            );
        }

        let meta = CallbackMeta {
            offset: entry_offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_buffered_view_try_process::<B, F>,
            has_data: sub_buffered_view_has_data::<B, F>,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry<B, F>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        self.apply_node_default_sched(slot, Some(node_id), None);
        Ok(self.handle_for(slot))
    }

    /// Register a raw (type-erased) buffered subscription whose callback
    /// also receives a [`RawMessageInfo`](nros_core::RawMessageInfo)
    /// carrying the sample's wire **attachment** (Phase 189.M1).
    ///
    /// Backs the `node.subscription(t).generic(..).message_info().build(cb)`
    /// builder — the cross-RMW bridge reads the `bridge_origin` tag from
    /// `info.attachment()` for echo suppression. One sample per
    /// `spin_once`; the attachment is staged in a flat per-entry buffer
    /// (cap `RAW_INFO_ATT_CAP`).
    pub fn register_subscription_buffered_raw_info_on<F, const RX_BUF: usize>(
        &mut self,
        node_id: super::node_record::NodeId,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut(&[u8], &nros_core::RawMessageInfo) + 'static,
    {
        type Entry<F> = SubBufferedRawInfoEntry<F>;

        let SubscriptionOpen {
            slot,
            handle,
            slot_bytes,
            ..
        } = self.open_subscription(&SubscriptionRequest {
            node_id: Some(node_id),
            topic_name,
            type_name,
            type_hash,
            qos,
            backend_hint: None,
            slot_bytes: RX_BUF,
            // The callback also receives the sample's wire ATTACHMENT, which
            // `process_raw_in_place` does not carry: it hands over borrowed
            // payload bytes and nothing else. Not a limitation of the backend.
            in_place_capable: false,
        })?;

        // Issue 1860 -- in the trailing region, as the C twin. A raw subscription
        // has no type to derive from, so the size is still `RX_BUF`.
        let (offset, trailing) = self.arena_alloc_with_trailing::<Entry<F>>(slot_bytes)?;
        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let buffer = super::arena::TrailingBuf::init(arena_ptr.add(trailing), slot_bytes);
            let entry_ptr = arena_ptr.add(offset) as *mut Entry<F>;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    buffer,
                    att: [0u8; super::arena::RAW_INFO_ATT_CAP],
                    callback,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_buffered_raw_info_try_process::<F>,
            has_data: sub_buffered_raw_info_has_data::<F>,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry<F>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        self.apply_node_default_sched(slot, Some(node_id), None);
        Ok(self.handle_for(slot))
    }

    /// Phase 250 (Wave 2) — register a generic (type-erased) raw subscription
    /// that surfaces E2E [`IntegrityStatus`](nros_rmw::IntegrityStatus) (CRC +
    /// sequence gap/dup) alongside the raw CDR bytes
    /// (`FnMut(&[u8], &IntegrityStatus)`). The type-erased analog of
    /// `register_subscription_with_safety_sized_inner`: the validator lives in
    /// the `RmwSubscriber` (`take_validated`), so the subscriber is created
    /// plainly and no `register_type::<M>()` is needed (the declarative `Node`
    /// path is generic). Used by the declarative runtime's `.safety()` opt-in.
    #[cfg(feature = "safety-e2e")]
    pub fn register_subscription_buffered_raw_safety_on<F, const RX_BUF: usize>(
        &mut self,
        node_id: super::node_record::NodeId,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut(&[u8], &nros_rmw::IntegrityStatus) + 'static,
    {
        use super::arena::{
            SubBufferedRawSafetyEntry, sub_buffered_raw_safety_has_data,
            sub_buffered_raw_safety_try_process,
        };
        type Entry<F> = SubBufferedRawSafetyEntry<F>;

        let SubscriptionOpen {
            slot,
            handle,
            slot_bytes,
            ..
        } = self.open_subscription(&SubscriptionRequest {
            node_id: Some(node_id),
            topic_name,
            type_name,
            type_hash,
            qos,
            backend_hint: None,
            slot_bytes: RX_BUF,
            // The sample is taken through `take_validated`, which computes the
            // integrity status as it copies. `process_raw_in_place` has no
            // validating form, so this shape cannot use it.
            //
            // phase-457 W5 (issue 1522) — as the SHAPE, for the reason its
            // sibling in `register_subscription_buffered_raw_on` gives.
            in_place_capable: super::declared_shape::DeclaredSubscriptionShape::BufferedRawSafety
                .in_place_capable(),
        })?;

        // Issue 1860 -- in the trailing region; untyped, so still `RX_BUF` bytes.
        let (offset, trailing) = self.arena_alloc_with_trailing::<Entry<F>>(slot_bytes)?;
        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let buffer = super::arena::TrailingBuf::init(arena_ptr.add(trailing), slot_bytes);
            let entry_ptr = arena_ptr.add(offset) as *mut Entry<F>;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    buffer,
                    callback,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_buffered_raw_safety_try_process::<F>,
            has_data: sub_buffered_raw_safety_has_data::<F>,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry<F>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        self.apply_node_default_sched(slot, Some(node_id), None);
        Ok(self.handle_for(slot))
    }

    /// Register a raw byte-shaped callback against a pre-built
    /// `RmwSubscriber` handle.
    ///
    /// Backend-agnostic primitive — the caller is responsible for
    /// obtaining the handle by whatever route the active backend
    /// supports:
    ///
    /// - **Generic ROS-typed flow**: call `Session::create_subscription`
    ///   on `self.session_mut()` with a [`TopicInfo`]. The
    ///   `node_mut(id).subscription(t).generic(ty, hash)` builder is the
    ///   convenience wrapper for this path.
    /// - **Backend-specific flow** (e.g. uORB needs `&'static orb_metadata`):
    ///   reach into the concrete session via [`Self::session_mut`] and
    ///   call its backend-specific create method, then hand the handle
    ///   here. `nros-px4::uorb::create_subscription_with_callback` is
    ///   the example.
    ///
    /// The arena-store + vtable wiring is identical to
    /// `register_subscription_buffered_raw`; the only thing that varies is
    /// where the handle came from. Callback fires on every message
    /// delivery during [`spin_once`](Self::spin_once); bytes are
    /// passed as `&[u8]`.
    pub fn add_arena_subscription_callback<F, const RX_BUF: usize>(
        &mut self,
        handle: session::RmwSubscriber,
        qos: QoSProfile,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut(&[u8]) + 'static,
    {
        let slot = self.next_entry_slot()?;
        self.emplace_raw_buffered_subscription(slot, handle, qos, RX_BUF, callback)?;
        Ok(self.handle_for(slot))
    }

    /// Write a raw buffered subscription entry into an already-claimed slot —
    /// phase-456 W8.
    ///
    /// The shared tail of [`Self::add_arena_subscription_callback`] and
    /// `register_subscription_buffered_raw_on`, which differ only in where the
    /// subscriber came from: one is handed a live `RmwSubscriber`, the other
    /// resolves a topic through [`Self::open_subscription`] and gets one back.
    /// Both then build exactly this entry, and they used to build it twice —
    /// the bridge path by CALLING the other, which meant it claimed a slot,
    /// resolved a topic, and then let the callee claim a second slot it did not
    /// need.
    fn emplace_raw_buffered_subscription<F>(
        &mut self,
        slot: usize,
        handle: session::RmwSubscriber,
        qos: QoSProfile,
        slot_bytes: usize,
        callback: F,
    ) -> Result<(), NodeError>
    where
        F: FnMut(&[u8]) + 'static,
    {
        type Entry<F> = SubBufferedRawEntry<F>;

        let (_slot_count, trailing_bytes) = buffered_region_size(qos.depth, slot_bytes);

        let (entry_offset, trailing_offset) =
            self.arena_alloc_with_trailing::<Entry<F>>(trailing_bytes)?;

        let buf_ptr = unsafe { (self.arena.as_mut_ptr() as *mut u8).add(trailing_offset) };

        let buffer = if qos.depth <= 1 {
            BufferStrategy::Triple(unsafe { TripleBuffer::init(buf_ptr, slot_bytes) })
        } else {
            BufferStrategy::Ring(unsafe { SpscRing::init(buf_ptr, slot_bytes, qos.depth as usize) })
        };

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(entry_offset) as *mut Entry<F>;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    buffer,
                    callback,
                },
            );
        }

        let meta = CallbackMeta {
            offset: entry_offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_buffered_raw_try_process::<F>,
            has_data: sub_buffered_raw_has_data::<F>,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry<F>>,
        };
        self.emplace_entry(slot, meta, TraceName::Slot("sub", slot));
        Ok(())
    }

    pub(crate) fn register_subscription_with_info_sized_inner<M, F, const RX_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        topic_name: &str,
        qos: QoSProfile,
        callback: F,
        // Issue 1860 -- `Some(n)` is a size the caller NAMED (`.rx_buffer::<N>()`),
        // used verbatim; `None` derives it from `M` exactly as the buffered path
        // does, falling back to `RX_BUF` only where `M` states no bound.
        rx_bytes: Option<usize>,
    ) -> Result<HandleId, NodeError>
    where
        M: crate::rmw_type_registry::MessageForRmw + 'static,
        F: FnMut(&M, Option<&nros_core::MessageInfo>) + 'static,
    {
        type Entry<M, F> = SubInfoEntry<M, F>;

        // Phase 212.K.7.6.b — see `create_publisher_on`.
        crate::rmw_type_registry::register_type::<M>()?;

        let SubscriptionOpen {
            slot,
            handle,
            slot_bytes,
            ..
        } = self.open_subscription(&SubscriptionRequest {
            node_id,
            topic_name,
            type_name: <M as RosMessage>::TYPE_NAME,
            type_hash: <M as RosMessage>::TYPE_HASH,
            qos,
            backend_hint: None,
            slot_bytes: crate::rmw_type_registry::subscription_slot_bytes::<M>(rx_bytes, RX_BUF),
            // The entry's `pre_sample` hook stages a `MessageInfo` beside the
            // payload before the callback runs; an in-place drain has no
            // pre-sample step to hang it on.
            in_place_capable: false,
        })?;

        let (offset, trailing) = self.arena_alloc_with_trailing::<Entry<M, F>>(slot_bytes)?;

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let buffer = super::arena::TrailingBuf::init(arena_ptr.add(trailing), slot_bytes);
            let entry_ptr = arena_ptr.add(offset) as *mut Entry<M, F>;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    buffer,
                    sampled_len: 0,
                    callback,
                    _phantom: PhantomData,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_info_try_process::<M, F>,
            has_data: sub_info_has_data::<M, F>,
            pre_sample: sub_info_pre_sample::<M, F>,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry<M, F>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        self.apply_node_default_sched(slot, node_id, None);
        Ok(self.handle_for(slot))
    }

    #[cfg(feature = "safety-e2e")]
    pub(crate) fn register_subscription_with_safety_sized_inner<M, F, const RX_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        topic_name: &str,
        qos: QoSProfile,
        callback: F,
        // Issue 1860 -- as `register_subscription_with_info_sized_inner`.
        rx_bytes: Option<usize>,
    ) -> Result<HandleId, NodeError>
    where
        M: crate::rmw_type_registry::MessageForRmw + 'static,
        F: FnMut(&M, &nros_rmw::IntegrityStatus) + 'static,
    {
        type Entry<M, F> = SubSafetyEntry<M, F>;

        // Phase 212.K.7.6.b — see `create_publisher_on`.
        crate::rmw_type_registry::register_type::<M>()?;

        let SubscriptionOpen {
            slot,
            handle,
            slot_bytes,
            ..
        } = self.open_subscription(&SubscriptionRequest {
            node_id,
            topic_name,
            type_name: <M as RosMessage>::TYPE_NAME,
            type_hash: <M as RosMessage>::TYPE_HASH,
            qos,
            backend_hint: None,
            slot_bytes: crate::rmw_type_registry::subscription_slot_bytes::<M>(rx_bytes, RX_BUF),
            // Same as the raw safety sibling: the status comes out of
            // `take_validated`, which is a copying take.
            in_place_capable: false,
        })?;

        let (offset, trailing) = self.arena_alloc_with_trailing::<Entry<M, F>>(slot_bytes)?;

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let buffer = super::arena::TrailingBuf::init(arena_ptr.add(trailing), slot_bytes);
            let entry_ptr = arena_ptr.add(offset) as *mut Entry<M, F>;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    buffer,
                    sampled_len: 0,
                    callback,
                    _phantom: PhantomData,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_safety_try_process::<M, F>,
            has_data: sub_safety_has_data::<M, F>,
            pre_sample: sub_safety_pre_sample::<M, F>,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry<M, F>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        self.apply_node_default_sched(slot, node_id, None);
        Ok(self.handle_for(slot))
    }

    /// Register a service callback with the default buffer size.
    ///
    /// The callback is stored in the arena and invoked during [`spin_once()`](Self::spin_once).
    pub fn register_service<Svc, F>(
        &mut self,
        service_name: &str,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        Svc: RosService + 'static,
        Svc::Request: crate::rmw_type_registry::MessageForRmw,
        Svc::Reply: crate::rmw_type_registry::MessageForRmw,
        F: FnMut(&Svc::Request) -> Svc::Reply + 'static,
    {
        self.register_service_sized::<Svc, F, { crate::config::DEFAULT_RX_BUF_SIZE }, { crate::config::DEFAULT_RX_BUF_SIZE }>(service_name, callback)
    }

    /// Register a service callback with custom request/reply buffer sizes.
    pub fn register_service_sized<Svc, F, const REQ_BUF: usize, const REPLY_BUF: usize>(
        &mut self,
        service_name: &str,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        Svc: RosService + 'static,
        Svc::Request: crate::rmw_type_registry::MessageForRmw,
        Svc::Reply: crate::rmw_type_registry::MessageForRmw,
        F: FnMut(&Svc::Request) -> Svc::Reply + 'static,
    {
        type Entry<Svc, F, const RQ: usize, const RP: usize> = SrvEntry<Svc, F, RQ, RP>;

        // Phase 212.K.7.7.b — register both halves of the service round-trip
        // under cyclonedds. No-op for other RMWs. Mirrors the K.7.6.b hook
        // on `Node::create_service_sized`.
        crate::rmw_type_registry::register_type::<Svc::Request>()?;
        crate::rmw_type_registry::register_type::<Svc::Reply>()?;

        let slot = self.next_entry_slot()?;
        let node_name: heapless::String<64> = self.node_name.clone();
        let ns: heapless::String<64> = self.namespace.clone();
        let mut info = ServiceInfo::new(service_name, Svc::SERVICE_NAME, Svc::SERVICE_HASH)
            .with_domain(self.domain_id)
            .with_namespace(&ns);
        if !node_name.is_empty() {
            info = info.with_node_name(&node_name);
        }
        let handle = self
            .session
            .create_service(&info, QoSProfile::services_default())
            .map_err(NodeError::Transport)?;

        let offset = self.arena_alloc::<Entry<Svc, F, REQ_BUF, REPLY_BUF>>()?;

        // SAFETY: same guarantees as register_subscription_sized.
        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(offset) as *mut Entry<Svc, F, REQ_BUF, REPLY_BUF>;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    req_buffer: [0u8; REQ_BUF],
                    reply_buffer: [0u8; REPLY_BUF],
                    callback,
                    _phantom: PhantomData,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Service,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: srv_try_process::<Svc, F, REQ_BUF, REPLY_BUF>,
            has_data: srv_has_data::<Svc, F, REQ_BUF, REPLY_BUF>,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry<Svc, F, REQ_BUF, REPLY_BUF>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(service_name));
        Ok(self.handle_for(slot))
    }

    /// Phase 104.C.3.3.a — Node-aware variant of
    /// [`register_service_sized`](Self::register_service_sized).
    pub fn register_service_sized_on<Svc, F, const REQ_BUF: usize, const REPLY_BUF: usize>(
        &mut self,
        node_id: super::node_record::NodeId,
        service_name: &str,
        qos: QoSProfile,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        Svc: RosService + 'static,
        Svc::Request: crate::rmw_type_registry::MessageForRmw,
        Svc::Reply: crate::rmw_type_registry::MessageForRmw,
        F: FnMut(&Svc::Request) -> Svc::Reply + 'static,
    {
        type Entry<Svc, F, const RQ: usize, const RP: usize> = SrvEntry<Svc, F, RQ, RP>;

        // Phase 212.K.7.7.b — see `register_service_sized`.
        crate::rmw_type_registry::register_type::<Svc::Request>()?;
        crate::rmw_type_registry::register_type::<Svc::Reply>()?;

        let slot = self.next_entry_slot()?;
        let (node_name, ns, session_idx) = {
            let r = self
                .nodes
                .get(node_id.index())
                .ok_or(NodeError::InvalidSchedContextBinding)?;
            (r.name.clone(), r.namespace.clone(), r.session_idx)
        };
        let mut info = ServiceInfo::new(service_name, Svc::SERVICE_NAME, Svc::SERVICE_HASH)
            .with_domain(self.domain_id)
            .with_namespace(&ns);
        if !node_name.is_empty() {
            info = info.with_node_name(&node_name);
        }
        let handle = {
            let session = self
                .session_at_mut(session_idx)
                .ok_or(NodeError::BackendMismatch)?;
            // Phase 193.5 — validate against the backend's supported policies
            // (no silent downgrade); request/reply effectively requires RELIABLE.
            super::node::validate_qos_or_report(
                &qos,
                session.supported_qos_policies(),
                "service",
                service_name,
            )?;
            session
                .create_service(&info, qos)
                .map_err(NodeError::Transport)?
        };

        let offset = self.arena_alloc::<Entry<Svc, F, REQ_BUF, REPLY_BUF>>()?;
        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(offset) as *mut Entry<Svc, F, REQ_BUF, REPLY_BUF>;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    req_buffer: [0u8; REQ_BUF],
                    reply_buffer: [0u8; REPLY_BUF],
                    callback,
                    _phantom: PhantomData,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Service,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: srv_try_process::<Svc, F, REQ_BUF, REPLY_BUF>,
            has_data: srv_has_data::<Svc, F, REQ_BUF, REPLY_BUF>,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry<Svc, F, REQ_BUF, REPLY_BUF>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(service_name));
        self.apply_node_default_sched(slot, Some(node_id), None);
        Ok(self.handle_for(slot))
    }

    /// Phase 104.C.3.3.a — Node-aware variant of
    /// [`register_service`](Self::register_service).
    pub fn register_service_on<Svc, F>(
        &mut self,
        node_id: super::node_record::NodeId,
        service_name: &str,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        Svc: RosService + 'static,
        Svc::Request: crate::rmw_type_registry::MessageForRmw,
        Svc::Reply: crate::rmw_type_registry::MessageForRmw,
        F: FnMut(&Svc::Request) -> Svc::Reply + 'static,
    {
        self.register_service_sized_on::<
            Svc,
            F,
            { crate::config::DEFAULT_RX_BUF_SIZE },
            { crate::config::DEFAULT_RX_BUF_SIZE },
        >(node_id, service_name, QoSProfile::services_default(), callback)
    }

    // ========================================================================
    // Timer registration
    // ========================================================================

    /// The ONE timer registration in the tree (phase-430 W4).
    ///
    /// Every timer verb — the four `Executor::register_timer*` entry points
    /// below, `Node::create_timer_in_group` / `create_timer_on_clock*`, the
    /// declarative `nros::Node` timer, and the C/C++ FFI that lower to them —
    /// constructs its arena entry HERE. Until W4 there were four copies of this
    /// body differing only in `oneshot`, `clock_source` and whether the sched
    /// binding was applied, and phase-425's clock axis reached exactly one of
    /// them; that is how a `nros::main!` component could declare a timer but
    /// not a ROS-time one.
    ///
    /// `node_id` / `group` feed `apply_node_default_sched` (phase 273: group
    /// table > node default > SC 0). `node_id == None` is the legacy unscoped
    /// path and makes that call a no-op.
    pub(crate) fn register_timer_entry<F>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        period: TimerDuration,
        source: TimerClockSource,
        oneshot: bool,
        group: Option<&str>,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut() + 'static,
    {
        self.register_timer_entry_with(
            node_id,
            period,
            source,
            oneshot,
            group,
            None,
            core::ptr::null_mut(),
            move |_| callback,
        )
    }

    /// [`register_timer_entry`](Self::register_timer_entry), with a CAPTURE
    /// the arena holds — phase-476 W2.
    ///
    /// The callback is BUILT after the allocation, by `make`, from the context
    /// pointer the entry should dispatch with: `place_capture`'s copy of
    /// `capture` when there is one, otherwise `context` unchanged. That is what
    /// lets the capture ride in the timer entry's own trailing region (so a
    /// release frees it) while the closure that reads it is still a plain
    /// `TimerEntry<F>`.
    #[allow(clippy::too_many_arguments)]
    pub(crate) fn register_timer_entry_with<F, M>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        period: TimerDuration,
        source: TimerClockSource,
        oneshot: bool,
        group: Option<&str>,
        capture: Option<&[u8]>,
        context: *mut core::ffi::c_void,
        make: M,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut() + 'static,
        M: FnOnce(*mut core::ffi::c_void) -> F,
    {
        let slot = self.next_entry_slot()?;
        let capture_len = Self::capture_trailing_len(capture);
        // No capture keeps the exact pre-W2 allocation, so a timer that captures
        // nothing costs what it always did.
        let (offset, context) = if capture_len == 0 {
            (self.arena_alloc::<TimerEntry<F>>()?, context)
        } else {
            let (offset, at) = self.arena_alloc_with_trailing::<TimerEntry<F>>(capture_len)?;
            (offset, self.place_capture(at, capture, context))
        };
        let callback = make(context);

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(offset) as *mut TimerEntry<F>;
            core::ptr::write(
                entry_ptr,
                TimerEntry {
                    period_us: period.as_micros(),
                    elapsed_us: 0,
                    overruns: 0,
                    overruns_reported: 0,
                    oneshot,
                    fired: false,
                    cancelled: false,
                    overrun_policy: TimerOverrunPolicy::default(),
                    clock_source: source,
                    // Seeded HERE rather than on the first poll: a zero would
                    // make the first delta the whole epoch, which `Skip` would
                    // then coalesce into one immediate activation and `CatchUp`
                    // into a replay burst of ~10^9 periods. `Steady` reads no
                    // clock at all, so its seed is 0 and is never read.
                    last_clock_ns: source.now_ns(),
                    callback,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Timer,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: timer_try_process::<F>,
            has_data: always_ready,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::Always,
            drop_fn: drop_entry::<TimerEntry<F>>,
        };
        self.emplace_entry(slot, meta, TraceName::TimerPeriod(period.as_micros()));
        // Phase 273 — apply group sched binding (group > node default > SC 0).
        self.apply_node_default_sched(slot, node_id, group);
        Ok(self.handle_for(slot))
    }

    /// Register a repeating timer callback.
    ///
    /// The callback fires every `period` milliseconds during [`spin_once()`](Self::spin_once).
    /// The timer delta is approximated by the `timeout_ms` argument to `spin_once`.
    pub fn register_timer<F>(
        &mut self,
        period: TimerDuration,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut() + 'static,
    {
        self.register_timer_entry(
            None,
            period,
            TimerClockSource::Steady,
            false,
            None,
            callback,
        )
    }

    /// Register a repeating timer driven by a CLOCK rather than by the spin
    /// delta — phase-425 W4, the shape rclcpp spells
    /// `create_timer(node, clock, period, cb)`.
    ///
    /// [`register_timer`](Self::register_timer) is the wall timer: it consumes
    /// the executor's monotonic spin delta and no simulator can slow it down.
    /// This one reads `source` on every poll and advances by the difference, so
    /// a [`TimerClockSource::Ros`] timer follows `/clock` — it stops while the
    /// simulator is paused, halves with a bag replayed at 0.5x, and restarts
    /// its period on a backwards jump instead of stalling for the length of it.
    ///
    /// With no `/clock` source installed, a `Ros` timer reads system time and
    /// behaves like a wall timer with NTP steps, which is the same fallback
    /// `rclcpp::Clock` has: a node written for simulation still runs standalone.
    ///
    /// The node-level spellings of this are `Node::create_timer_on_clock`
    /// and the declarative `DeclaredNode::create_timer_on_clock` (phase-430 W4);
    /// all of them reach `register_timer_entry`, which is the only place a
    /// timer entry is built.
    pub fn register_timer_on_clock<F>(
        &mut self,
        period: TimerDuration,
        source: TimerClockSource,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut() + 'static,
    {
        self.register_timer_entry(None, period, source, false, None, callback)
    }

    /// Register a one-shot timer callback.
    ///
    /// The callback fires once after `delay` milliseconds, then becomes inert.
    pub fn register_timer_oneshot<F>(
        &mut self,
        delay: TimerDuration,
        callback: F,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut() + 'static,
    {
        self.register_timer_entry(None, delay, TimerClockSource::Steady, true, None, callback)
    }

    /// phase-476 W2 — register a timer whose callback is a C function pointer
    /// and whose CAPTURE the arena holds: the `nros-cpp` road for a C++
    /// lambda, the timer twin of
    /// [`add_arena_subscription_c_callback_with_capture`](Self::add_arena_subscription_c_callback_with_capture).
    ///
    /// `capture`'s bytes are copied into the timer entry's trailing region and
    /// `callback` is called with a pointer to that copy, so the caller keeps
    /// nothing — which is what lets the C++ side hand back a two-word handle
    /// instead of a heap cell the node had to keep alive. Releasing the timer
    /// releases the capture with it.
    ///
    /// `source` picks the clock: [`TimerClockSource::Steady`] is the wall timer
    /// that advances with the spin delta.
    ///
    /// `capture_drop`, when given, is called with the same pointer when the
    /// entry is dropped (released, or the executor torn down), BEFORE its bytes
    /// go back to the arena. A C++ capture is a callable that may own something
    /// (a `std::shared_ptr`, a `std::string`), and its bytes were MOVED here by
    /// copy, so this is the only place its destructor can run.
    pub fn register_timer_c_capturing(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        period: TimerDuration,
        source: TimerClockSource,
        callback: unsafe extern "C" fn(*mut core::ffi::c_void),
        capture: Option<&[u8]>,
        capture_drop: Option<unsafe extern "C" fn(*mut core::ffi::c_void)>,
    ) -> Result<HandleId, NodeError> {
        self.register_timer_entry_with(
            node_id,
            period,
            source,
            false,
            None,
            capture,
            core::ptr::null_mut(),
            move |ctx| {
                let held = super::arena::CapturedCallback {
                    callback,
                    guard: super::arena::CaptureGuard {
                        ctx,
                        drop: capture_drop,
                    },
                };
                move || held.call()
            },
        )
    }

    /// Phase 273 (RFC-0047) — register a repeating timer callback bound to a
    /// specific node and optional callback group. The group name is threaded to
    /// `apply_node_default_sched` so the seeded `group_sched_table` assigns
    /// the timer's callback to the group's `SchedContext`. When `group` is
    /// `None` the node's `default_sched` applies (phase-272 behavior).
    ///
    /// This is the executor-level primitive called by the Rust `_in_group` API
    /// (`Node::create_timer_in_group`) and the C/C++ group-aware timer FFI.
    pub fn register_timer_on<F>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        period: TimerDuration,
        callback: F,
        group: Option<&str>,
    ) -> Result<HandleId, NodeError>
    where
        F: FnMut() + 'static,
    {
        self.register_timer_entry(
            node_id,
            period,
            TimerClockSource::Steady,
            false,
            group,
            callback,
        )
    }

    // ========================================================================
    // Raw callback registration (for C API)
    // ========================================================================

    /// The kept C-FFI subscription core (Phase 189.M2.b): registers a
    /// raw `RawSubscriptionCallback` fn-ptr + `context` against an
    /// optional node's session. The Rust ergonomic surface is the
    /// `node.subscription(t)` builder (closures); this is the single
    /// primitive the `nros-c` thin wrapper lowers to. `node_id == None`
    /// is the legacy single-node path.
    #[allow(clippy::too_many_arguments)]
    pub fn add_arena_subscription_c_callback<const RX_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
        callback: RawSubscriptionCallback,
        context: *mut core::ffi::c_void,
        group: Option<&str>,
        rx_buffer_hint: usize,
    ) -> Result<HandleId, NodeError> {
        self.add_arena_subscription_c_callback_with_capture::<RX_BUF>(
            node_id,
            topic_name,
            type_name,
            type_hash,
            qos,
            callback,
            context,
            group,
            rx_buffer_hint,
            None,
            None,
        )
    }

    /// The same registration, with the caller's CAPTURE held by the arena —
    /// phase-456 W1.
    ///
    /// `context` is one pointer, which carries a C++ `[this]` capture and not a
    /// `[this, state]` or a `[obj, method]`. When `capture` is `Some`, its
    /// bytes are copied into the arena and `context` is repointed at that copy,
    /// so the caller keeps nothing and nothing the caller owns is referenced
    /// after this returns. When it is `None` the behaviour is exactly the
    /// pre-existing one, which is why the plain entry point above is a wrapper
    /// rather than a second implementation.
    ///
    /// **phase-456 W8 changed two things here.** The capture is a RUNTIME
    /// length — see `Self::place_capture` — so there is no constant the C++
    /// side has to match and no `BufferTooSmall` reachable only by drifting
    /// from it. And this path now reaches the in-place dispatch that the Rust
    /// typed path has had since phase-231: `RawSubscriptionCallback` is
    /// `(const uint8_t*, size_t, void*)`, so the backend's borrowed receive
    /// slot IS the argument, and a C or C++ subscription on zenoh or XRCE
    /// claims no receive region at all.
    #[allow(clippy::too_many_arguments)]
    pub fn add_arena_subscription_c_callback_with_capture<const RX_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
        callback: RawSubscriptionCallback,
        context: *mut core::ffi::c_void,
        group: Option<&str>,
        // phase-402 W2 / issue 0896 — bytes the caller expects to receive; 0 =
        // no opinion. A size-classing backend (zenoh-pico) routes on this, and
        // a subscription that states nothing takes the SMALL class whatever its
        // message type. The C path had no way to say it until the options
        // struct existed.
        rx_buffer_hint: usize,
        capture: Option<&[u8]>,
        // phase-476 W2 — called on the arena's copy of `capture` when the entry
        // is dropped; see `CaptureGuard`. `None` when the capture owns nothing.
        capture_drop: Option<unsafe extern "C" fn(*mut core::ffi::c_void)>,
    ) -> Result<HandleId, NodeError> {
        // phase-403 W3/W5 -- size the arena slot from the TYPE, not from the
        // image-wide default. `rx_buffer_hint` already arrives here (phase-402
        // routed it to the backend's payload class and stopped); spending it on
        // the allocation as well is what makes the buffer per-type.
        //
        // This is the whole saving on the raw path. `RX_BUF` is
        // DEFAULT_RX_BUF_SIZE, so every slot -- publishers and timers included --
        // was charged the largest subscription's buffer. Measured on
        // mr-canhubk344: 36 handles at the correct 2052-byte bound wanted a
        // 242096-byte arena of a 77968-byte region; only 13 of those handles
        // receive anything.
        //
        // 0 keeps the old behaviour, and it means "this CALLER stated nothing"
        // rather than "this type is unbounded" -- an unbounded type is a build
        // error now, so a zero here is a caller that did not ask, never a type
        // that could not answer.
        let slot_bytes = if rx_buffer_hint != 0 {
            rx_buffer_hint
        } else {
            RX_BUF
        };

        let SubscriptionOpen {
            slot,
            handle,
            qos,
            in_place,
            slot_bytes,
        } = self.open_subscription(&SubscriptionRequest {
            node_id,
            topic_name,
            type_name,
            type_hash,
            qos,
            backend_hint: Some(rx_buffer_hint),
            slot_bytes,
            // phase-456 W8 — `RawSubscriptionCallback` takes borrowed bytes and
            // a context, which is exactly what `process_raw_in_place` hands it.
            in_place_capable: true,
        })?;

        // The capture is placed AFTER the backend call and BEFORE either entry
        // is written, so both dispatch shapes get the same context and a failed
        // `create_subscription` costs no arena bytes. phase-476 W0 — it rides
        // at the end of the entry's own trailing region, so releasing the entry
        // gives it back.
        let capture_len = Self::capture_trailing_len(capture);

        if in_place {
            let (entry_offset, capture_at) =
                self.arena_alloc_with_trailing::<super::arena::SubInplaceRawCEntry>(capture_len)?;
            let context = self.place_capture(capture_at, capture, context);
            unsafe {
                let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
                let entry_ptr =
                    arena_ptr.add(entry_offset) as *mut super::arena::SubInplaceRawCEntry;
                core::ptr::write(
                    entry_ptr,
                    super::arena::SubInplaceRawCEntry {
                        handle,
                        callback,
                        context,
                        capture: super::arena::CaptureGuard {
                            ctx: context,
                            drop: capture_drop,
                        },
                    },
                );
            }
            let meta = CallbackMeta {
                offset: entry_offset,
                kind: EntryKind::Subscription,
                arena_len: super::arena::ArenaLen::UNRECORDED,
                try_process: super::arena::sub_inplace_raw_c_try_process,
                has_data: super::arena::sub_inplace_raw_c_has_data,
                pre_sample: no_pre_sample,
                invocation: InvocationMode::OnNewData,
                drop_fn: drop_entry::<super::arena::SubInplaceRawCEntry>,
            };
            self.emplace_entry(slot, meta, TraceName::Text(topic_name));
            self.apply_node_default_sched(slot, node_id, group);
            return Ok(self.handle_for(slot));
        }

        let (_slot_count, trailing_bytes) = buffered_region_size(qos.depth, slot_bytes);

        // The ring first, then the capture on the next `u64` boundary after it.
        let ring_len = trailing_bytes.next_multiple_of(core::mem::align_of::<u64>());
        let (entry_offset, trailing_offset) =
            self.arena_alloc_with_trailing::<SubBufferedRawCEntry>(ring_len + capture_len)?;
        let context = self.place_capture(trailing_offset + ring_len, capture, context);

        let buf_ptr = unsafe { (self.arena.as_mut_ptr() as *mut u8).add(trailing_offset) };

        let buffer = if qos.depth <= 1 {
            BufferStrategy::Triple(unsafe { TripleBuffer::init(buf_ptr, slot_bytes) })
        } else {
            BufferStrategy::Ring(unsafe { SpscRing::init(buf_ptr, slot_bytes, qos.depth as usize) })
        };

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(entry_offset) as *mut SubBufferedRawCEntry;
            core::ptr::write(
                entry_ptr,
                SubBufferedRawCEntry {
                    handle,
                    buffer,
                    callback,
                    context,
                    capture: super::arena::CaptureGuard {
                        ctx: context,
                        drop: capture_drop,
                    },
                },
            );
        }

        let meta = CallbackMeta {
            offset: entry_offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_buffered_raw_c_try_process,
            has_data: sub_buffered_raw_c_has_data,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<SubBufferedRawCEntry>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        self.apply_node_default_sched(slot, node_id, group);
        Ok(self.handle_for(slot))
    }

    /// phase-417 W5.a (RFC-0089 stage 5) — the TYPED C-FFI subscription core:
    /// the same registration as [`Self::add_arena_subscription_c_callback`],
    /// plus caller-owned message storage and the erased deserialiser for its
    /// type, so the callback receives a DESERIALISED message instead of CDR
    /// bytes.
    ///
    /// This is the Rust half of rclc's
    /// `rclc_executor_add_subscription(executor, subscription, msg, callback,
    /// invocation)`. rclc has no allocator on that path either — it makes the
    /// CALLER own the storage, which is exactly what `msg` is here. The C
    /// ledger recorded our byte-oriented delivery as forced by "no allocator";
    /// the compared surface operates under the same constraint, so the reason
    /// was false and the divergence was avoidable (issue 1022 / W-C3).
    ///
    /// The raw path is untouched and stays: a byte-oriented subscriber is a
    /// legitimate thing to want, and this is additive.
    ///
    /// # Contract on failure
    /// If `deserialize` returns non-zero the callback is **not** invoked, the
    /// sample is dropped, `try_process` reports
    /// `TransportError::DeserializationError` (so it lands in
    /// `SpinOnceResult::subscription_errors`), and a rate-limited `nros_log`
    /// error names the length and the return code. A message that does not fit
    /// the caller's storage arrives here as exactly that failure: both the
    /// bounded-string and bounded-sequence decoders refuse rather than
    /// truncate, so there is no silent short read.
    ///
    /// # Safety
    /// `msg` must point to storage of the type `deserialize` writes, valid for
    /// as long as the subscription is registered. Nothing here drops it.
    #[allow(clippy::too_many_arguments)]
    pub unsafe fn add_arena_subscription_c_typed_callback<const RX_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
        msg: core::ptr::NonNull<core::ffi::c_void>,
        deserialize: RawMessageDeserializeFn,
        callback: TypedSubscriptionCallback,
        context: *mut core::ffi::c_void,
        group: Option<&str>,
        // Same meaning as on the raw path: bytes the caller expects to receive,
        // 0 = no opinion. A typed caller normally HAS an answer — the generated
        // `<Msg>_RX_MAX_SERIALIZED_SIZE` — which is why the C entry point takes
        // it rather than defaulting.
        rx_buffer_hint: usize,
    ) -> Result<HandleId, NodeError> {
        let SubscriptionOpen {
            slot,
            handle,
            qos,
            slot_bytes: rx_bytes,
            ..
        } = self.open_subscription(&SubscriptionRequest {
            node_id,
            topic_name,
            type_name,
            type_hash,
            qos,
            backend_hint: Some(rx_buffer_hint),
            // phase-403 W3/W5, unchanged: the hint sizes the arena slot, and 0
            // means "this caller stated nothing", never "this type is zero
            // bytes".
            slot_bytes: if rx_buffer_hint != 0 {
                rx_buffer_hint
            } else {
                RX_BUF
            },
            // The callback receives the caller's DESERIALISED storage, written
            // by `deserialize` from the sample's bytes, so borrowed bytes would
            // be enough and this shape could take the in-place row. It does not
            // yet: `SubBufferedTypedCEntry` also owns the `msg` pointer and the
            // deserialiser, so an in-place twin is a second entry type rather
            // than a flag, and phase-456 W8's acceptance is the RAW C path.
            // Stated here rather than left blank because a `false` nobody wrote
            // down is what this whole item is about.
            in_place_capable: false,
        })?;

        let (_slot_count, trailing_bytes) = buffered_region_size(qos.depth, rx_bytes);

        let (entry_offset, trailing_offset) =
            self.arena_alloc_with_trailing::<SubBufferedTypedCEntry>(trailing_bytes)?;

        let buf_ptr = unsafe { (self.arena.as_mut_ptr() as *mut u8).add(trailing_offset) };

        let buffer = if qos.depth <= 1 {
            BufferStrategy::Triple(unsafe { TripleBuffer::init(buf_ptr, rx_bytes) })
        } else {
            BufferStrategy::Ring(unsafe { SpscRing::init(buf_ptr, rx_bytes, qos.depth as usize) })
        };

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(entry_offset) as *mut SubBufferedTypedCEntry;
            core::ptr::write(
                entry_ptr,
                SubBufferedTypedCEntry {
                    handle,
                    buffer,
                    msg: msg.as_ptr(),
                    deserialize,
                    callback,
                    context,
                },
            );
        }

        let meta = CallbackMeta {
            offset: entry_offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_buffered_typed_c_try_process,
            has_data: sub_buffered_typed_c_has_data,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<SubBufferedTypedCEntry>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        self.apply_node_default_sched(slot, node_id, group);
        Ok(self.handle_for(slot))
    }

    /// Phase 189.M3.4 — register a raw C-fn-ptr subscription whose callback
    /// also receives the sample's wire **attachment**
    /// ([`RawSubscriptionInfoCallback`]: `(data, len, attachment, att_len,
    /// context)`) — the C analog of the Rust
    /// `node.subscription(t).generic(..).message_info()` builder. Backs the C
    /// FFI `rclc_executor_add_subscription_raw_with_info`. Flat per-entry
    /// payload + attachment buffers (cap `RAW_INFO_ATT_CAP`);
    /// one sample per `spin_once`.
    #[allow(clippy::too_many_arguments)]
    pub fn add_arena_subscription_c_info_callback<const RX_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
        callback: RawSubscriptionInfoCallback,
        context: *mut core::ffi::c_void,
        // phase-408 W5a/W5b — bytes the caller expects to receive; 0 = no
        // opinion. It now buys BOTH halves: the BACKEND's payload size-class
        // routing (W5a, below) and the ARENA slot (W5b, further down). `RX_BUF`
        // survives only as the fallback for a caller that states nothing, which
        // is exactly its role on the plain C path.
        rx_buffer_hint: usize,
    ) -> Result<HandleId, NodeError> {
        type Entry = SubBufferedRawInfoCEntry;

        let SubscriptionOpen {
            slot,
            handle,
            slot_bytes: rx_bytes,
            ..
        } = self.open_subscription(&SubscriptionRequest {
            node_id,
            topic_name,
            type_name,
            type_hash,
            qos,
            backend_hint: Some(rx_buffer_hint),
            // phase-408 W5b — the hint sizes the ARENA too, not just the
            // backend's size class. 0 still means "this caller stated nothing",
            // so `RX_BUF` -- `DEFAULT_RX_BUF_SIZE` at every call site -- is what
            // it falls back to, and an unhinted registration claims the same
            // bytes it always did.
            slot_bytes: if rx_buffer_hint != 0 {
                rx_buffer_hint
            } else {
                RX_BUF
            },
            // Carries the wire attachment — see the Rust `_raw_info_on` twin.
            in_place_capable: false,
        })?;

        let (offset, trailing_offset) = self.arena_alloc_with_trailing::<Entry>(rx_bytes)?;
        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let buf = super::arena::TrailingBuf::init(arena_ptr.add(trailing_offset), rx_bytes);
            let entry_ptr = arena_ptr.add(offset) as *mut Entry;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    buffer: buf,
                    att: [0u8; super::arena::RAW_INFO_ATT_CAP],
                    callback,
                    context,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_buffered_raw_info_c_try_process,
            has_data: sub_buffered_raw_info_c_has_data,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        self.apply_node_default_sched(slot, node_id, None);
        Ok(self.handle_for(slot))
    }

    /// Phase 269 W3 — register a raw C-fn-ptr subscription whose callback
    /// ALSO surfaces the sample's E2E integrity status (CRC + sequence gap/dup)
    /// alongside the CDR bytes — the C/C++ component-callback analog of Rust's
    /// `register_subscription_buffered_raw_safety_on` (`FnMut(&[u8], &IntegrityStatus)`).
    ///
    /// The executor validates the sample via `take_validated` and unpacks the
    /// [`nros_rmw::IntegrityStatus`] into three plain scalars (gap, duplicate,
    /// crc_valid) before calling `callback`. This avoids introducing a
    /// cbindgen-visible struct at the executor layer; the C/C++ headers pack them
    /// back into their local integrity-status typedef.
    ///
    /// Requires the `safety-e2e` feature. Backed by `SubBufferedRawSafetyCEntry`.
    #[cfg(feature = "safety-e2e")]
    #[allow(clippy::too_many_arguments)]
    pub fn add_arena_subscription_c_validated_callback<const RX_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        topic_name: &str,
        type_name: &str,
        type_hash: &str,
        qos: QoSProfile,
        callback: super::types::RawSubscriptionSafetyCallback,
        context: *mut core::ffi::c_void,
        // phase-408 W5a/W5b — bytes the caller expects to receive; 0 = no
        // opinion. It now buys BOTH halves: the BACKEND's payload size-class
        // routing (W5a, below) and the ARENA slot (W5b, further down). `RX_BUF`
        // survives only as the fallback for a caller that states nothing, which
        // is exactly its role on the plain C path.
        rx_buffer_hint: usize,
    ) -> Result<HandleId, NodeError> {
        use super::arena::{
            SubBufferedRawSafetyCEntry, TrailingBuf, sub_buffered_raw_safety_c_has_data,
            sub_buffered_raw_safety_c_try_process,
        };
        type Entry = SubBufferedRawSafetyCEntry;

        let SubscriptionOpen {
            slot,
            handle,
            slot_bytes: rx_bytes,
            ..
        } = self.open_subscription(&SubscriptionRequest {
            node_id,
            topic_name,
            type_name,
            type_hash,
            qos,
            backend_hint: Some(rx_buffer_hint),
            // phase-408 W5b — same as the info sibling: one flat slot in the
            // trailing region, sized from the hint, `RX_BUF` only as the
            // stated-nothing fallback.
            slot_bytes: if rx_buffer_hint != 0 {
                rx_buffer_hint
            } else {
                RX_BUF
            },
            // Carries the integrity status, which comes from `take_validated`.
            in_place_capable: false,
        })?;

        let (offset, trailing_offset) = self.arena_alloc_with_trailing::<Entry>(rx_bytes)?;
        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let buf = TrailingBuf::init(arena_ptr.add(trailing_offset), rx_bytes);
            let entry_ptr = arena_ptr.add(offset) as *mut Entry;
            core::ptr::write(
                entry_ptr,
                Entry {
                    handle,
                    buffer: buf,
                    callback,
                    context,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Subscription,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: sub_buffered_raw_safety_c_try_process,
            has_data: sub_buffered_raw_safety_c_has_data,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<Entry>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(topic_name));
        self.apply_node_default_sched(slot, node_id, None);
        Ok(self.handle_for(slot))
    }

    /// Register a raw (untyped) service callback.
    ///
    /// Register a raw (untyped) service callback with the default buffer size.
    ///
    /// The callback receives and produces CDR bytes without typed
    /// deserialization/serialization. Used by the C API wrapper.
    pub fn register_service_raw(
        &mut self,
        service_name: &str,
        service_type: &str,
        service_hash: &str,
        callback: RawServiceCallback,
        context: *mut core::ffi::c_void,
    ) -> Result<HandleId, NodeError> {
        self.register_service_raw_sized::<{ crate::config::DEFAULT_RX_BUF_SIZE }, { crate::config::DEFAULT_RX_BUF_SIZE }>(
            service_name,
            service_type,
            service_hash,
            QoSProfile::services_default(),
            callback,
            context,
        )
    }

    /// Register a raw (untyped) service callback with custom buffer sizes + QoS.
    ///
    /// `REQ_BUF` and `REPLY_BUF` set the stack-allocated CDR buffers
    /// for the request and reply respectively. Increase for services
    /// with large payloads (e.g., parameter services). `qos` applies to both
    /// the request + reply endpoints (Phase 193.2c).
    #[allow(clippy::too_many_arguments)]
    pub fn register_service_raw_sized<const REQ_BUF: usize, const REPLY_BUF: usize>(
        &mut self,
        service_name: &str,
        service_type: &str,
        service_hash: &str,
        qos: QoSProfile,
        callback: RawServiceCallback,
        context: *mut core::ffi::c_void,
    ) -> Result<HandleId, NodeError> {
        self.register_service_raw_sized_inner::<REQ_BUF, REPLY_BUF>(
            None,
            service_name,
            service_type,
            service_hash,
            qos,
            callback,
            context,
        )
    }

    /// Phase 104.C.3.3.a — Node-aware variant of
    /// [`Self::register_service_raw_sized`]. C-FFI path.
    #[allow(clippy::too_many_arguments)]
    pub fn register_service_raw_sized_on<const REQ_BUF: usize, const REPLY_BUF: usize>(
        &mut self,
        node_id: super::node_record::NodeId,
        service_name: &str,
        service_type: &str,
        service_hash: &str,
        qos: QoSProfile,
        callback: RawServiceCallback,
        context: *mut core::ffi::c_void,
    ) -> Result<HandleId, NodeError> {
        self.register_service_raw_sized_inner::<REQ_BUF, REPLY_BUF>(
            Some(node_id),
            service_name,
            service_type,
            service_hash,
            qos,
            callback,
            context,
        )
    }

    #[allow(clippy::too_many_arguments)]
    fn register_service_raw_sized_inner<const REQ_BUF: usize, const REPLY_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        service_name: &str,
        service_type: &str,
        service_hash: &str,
        qos: QoSProfile,
        callback: RawServiceCallback,
        context: *mut core::ffi::c_void,
    ) -> Result<HandleId, NodeError> {
        let slot = self.next_entry_slot()?;
        let (node_name, ns, session_idx) = match node_id {
            Some(id) => {
                let r = self
                    .nodes
                    .get(id.index())
                    .ok_or(NodeError::InvalidSchedContextBinding)?;
                (r.name.clone(), r.namespace.clone(), r.session_idx)
            }
            None => (self.node_name.clone(), self.namespace.clone(), 0u8),
        };
        let mut info = ServiceInfo::new(service_name, service_type, service_hash)
            .with_domain(self.domain_id)
            .with_namespace(&ns);
        if !node_name.is_empty() {
            info = info.with_node_name(&node_name);
        }
        let handle = {
            let session = self
                .session_at_mut(session_idx)
                .ok_or(NodeError::BackendMismatch)?;
            // Phase 193.5 — validate against the backend's supported policies
            // (no silent downgrade); request/reply effectively requires RELIABLE.
            super::node::validate_qos_or_report(
                &qos,
                session.supported_qos_policies(),
                "service",
                service_name,
            )?;
            session
                .create_service(&info, qos)
                .map_err(NodeError::Transport)?
        };

        let offset = self.arena_alloc::<SrvRawEntry<REQ_BUF, REPLY_BUF>>()?;

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(offset) as *mut SrvRawEntry<REQ_BUF, REPLY_BUF>;
            core::ptr::write(
                entry_ptr,
                SrvRawEntry {
                    handle,
                    req_buffer: [0u8; REQ_BUF],
                    reply_buffer: [0u8; REPLY_BUF],
                    callback,
                    context,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::Service,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: srv_raw_try_process::<REQ_BUF, REPLY_BUF>,
            has_data: srv_raw_has_data::<REQ_BUF, REPLY_BUF>,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::OnNewData,
            drop_fn: drop_entry::<SrvRawEntry<REQ_BUF, REPLY_BUF>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(service_name));
        self.apply_node_default_sched(slot, node_id, None);
        Ok(self.handle_for(slot))
    }

    // ========================================================================
    // Raw service client registration (Phase 82)
    // ========================================================================

    /// Register a raw (untyped) service client with the default reply
    /// buffer size.
    ///
    /// The client is owned by the executor's arena. Each `spin_once`
    /// dispatch polls the in-flight reply slot via `take_response_raw`
    /// and fires the registered callback when the response arrives.
    /// Used by the C API thin wrapper — see Phase 82.
    pub fn register_service_client_raw(
        &mut self,
        service_name: &str,
        service_type: &str,
        service_hash: &str,
        callback: Option<RawResponseCallback>,
        context: *mut core::ffi::c_void,
    ) -> Result<HandleId, NodeError> {
        self.register_service_client_raw_sized::<{ crate::config::DEFAULT_RX_BUF_SIZE }>(
            service_name,
            service_type,
            service_hash,
            QoSProfile::services_default(),
            callback,
            context,
        )
    }

    /// Register a raw service client with a custom reply buffer size + QoS.
    ///
    /// `qos` applies to the client's request + reply endpoints (Phase 193.3b);
    /// defaults to [`QoSProfile::services_default`] via the convenience
    /// wrapper.
    #[allow(clippy::too_many_arguments)]
    pub fn register_service_client_raw_sized<const REPLY_BUF: usize>(
        &mut self,
        service_name: &str,
        service_type: &str,
        service_hash: &str,
        qos: QoSProfile,
        callback: Option<RawResponseCallback>,
        context: *mut core::ffi::c_void,
    ) -> Result<HandleId, NodeError> {
        self.register_service_client_raw_sized_inner::<REPLY_BUF>(
            None,
            service_name,
            service_type,
            service_hash,
            qos,
            callback,
            context,
        )
    }

    /// Phase 104.C.3.3.a — Node-aware variant of
    /// [`Self::register_service_client_raw_sized`]. Routes the client
    /// creation through the named Node's session.
    #[allow(clippy::too_many_arguments)]
    pub fn register_service_client_raw_sized_on<const REPLY_BUF: usize>(
        &mut self,
        node_id: super::node_record::NodeId,
        service_name: &str,
        service_type: &str,
        service_hash: &str,
        qos: QoSProfile,
        callback: Option<RawResponseCallback>,
        context: *mut core::ffi::c_void,
    ) -> Result<HandleId, NodeError> {
        self.register_service_client_raw_sized_inner::<REPLY_BUF>(
            Some(node_id),
            service_name,
            service_type,
            service_hash,
            qos,
            callback,
            context,
        )
    }

    #[allow(clippy::too_many_arguments)]
    fn register_service_client_raw_sized_inner<const REPLY_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        service_name: &str,
        service_type: &str,
        service_hash: &str,
        qos: QoSProfile,
        callback: Option<RawResponseCallback>,
        context: *mut core::ffi::c_void,
    ) -> Result<HandleId, NodeError> {
        let slot = self.next_entry_slot()?;
        let (node_name, ns, session_idx) = match node_id {
            Some(id) => {
                let r = self
                    .nodes
                    .get(id.index())
                    .ok_or(NodeError::InvalidSchedContextBinding)?;
                (r.name.clone(), r.namespace.clone(), r.session_idx)
            }
            None => (self.node_name.clone(), self.namespace.clone(), 0u8),
        };
        let mut info = ServiceInfo::new(service_name, service_type, service_hash)
            .with_domain(self.domain_id)
            .with_namespace(&ns);
        if !node_name.is_empty() {
            info = info.with_node_name(&node_name);
        }
        let handle = {
            let session = self
                .session_at_mut(session_idx)
                .ok_or(NodeError::BackendMismatch)?;
            // Phase 193.5 — validate against the backend's supported policies
            // (no silent downgrade); request/reply effectively requires RELIABLE.
            super::node::validate_qos_or_report(
                &qos,
                session.supported_qos_policies(),
                "client",
                service_name,
            )?;
            session
                .create_client(&info, qos)
                .map_err(|_| NodeError::Transport(TransportError::ServiceClientCreationFailed))?
        };

        let offset = self.arena_alloc::<ServiceClientRawArenaEntry<REPLY_BUF>>()?;
        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(offset) as *mut ServiceClientRawArenaEntry<REPLY_BUF>;
            core::ptr::write(
                entry_ptr,
                ServiceClientRawArenaEntry {
                    handle,
                    reply_buffer: [0u8; REPLY_BUF],
                    pending: false,
                    reply_ready: core::sync::atomic::AtomicBool::new(false),
                    callback,
                    context,
                },
            );
        }

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::ServiceClient,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: service_client_raw_try_process::<REPLY_BUF>,
            has_data: always_ready,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::Always,
            drop_fn: drop_entry::<ServiceClientRawArenaEntry<REPLY_BUF>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(service_name));
        self.apply_node_default_sched(slot, node_id, None);
        Ok(self.handle_for(slot))
    }

    /// RFC-0041 / Phase 239.1 — register a **typed callback** service client.
    /// The reply is eager-drained at `spin_once` and dispatched to `callback` as
    /// a deserialized `Svc::Reply`. Returns the scheduling [`HandleId`] and a
    /// `*mut` to the arena entry's send header (used to build the typed
    /// [`ServiceClientCallback`](super::handles::ServiceClientCallback)).
    #[allow(clippy::too_many_arguments)]
    pub(crate) fn register_service_client_callback<Svc, F, const REPLY_BUF: usize>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        service_name: &str,
        service_type: &str,
        service_hash: &str,
        qos: QoSProfile,
        callback: F,
    ) -> Result<(HandleId, *mut ServiceClientSendHeader<REPLY_BUF>), NodeError>
    where
        Svc: nros_core::RosService + 'static,
        F: FnMut(&Svc::Reply) + 'static,
    {
        let slot = self.next_entry_slot()?;
        let (node_name, ns, session_idx) = match node_id {
            Some(id) => {
                let r = self
                    .nodes
                    .get(id.index())
                    .ok_or(NodeError::InvalidSchedContextBinding)?;
                (r.name.clone(), r.namespace.clone(), r.session_idx)
            }
            None => (self.node_name.clone(), self.namespace.clone(), 0u8),
        };
        let mut info = ServiceInfo::new(service_name, service_type, service_hash)
            .with_domain(self.domain_id)
            .with_namespace(&ns);
        if !node_name.is_empty() {
            info = info.with_node_name(&node_name);
        }
        let handle = {
            let session = self
                .session_at_mut(session_idx)
                .ok_or(NodeError::BackendMismatch)?;
            super::node::validate_qos_or_report(
                &qos,
                session.supported_qos_policies(),
                "client",
                service_name,
            )?;
            session
                .create_client(&info, qos)
                .map_err(|_| NodeError::Transport(TransportError::ServiceClientCreationFailed))?
        };

        let offset = self.arena_alloc::<ServiceClientCallbackEntry<Svc, F, REPLY_BUF>>()?;
        let hdr_ptr = unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr =
                arena_ptr.add(offset) as *mut ServiceClientCallbackEntry<Svc, F, REPLY_BUF>;
            core::ptr::write(
                entry_ptr,
                ServiceClientCallbackEntry {
                    hdr: ServiceClientSendHeader {
                        handle,
                        reply_buffer: [0u8; REPLY_BUF],
                        pending: false,
                        reply_ready: core::sync::atomic::AtomicBool::new(false),
                    },
                    callback,
                    _phantom: core::marker::PhantomData,
                },
            );
            &mut (*entry_ptr).hdr as *mut ServiceClientSendHeader<REPLY_BUF>
        };

        let meta = CallbackMeta {
            offset,
            kind: EntryKind::ServiceClient,
            arena_len: super::arena::ArenaLen::UNRECORDED,
            try_process: service_client_callback_try_process::<Svc, F, REPLY_BUF>,
            has_data: always_ready,
            pre_sample: no_pre_sample,
            invocation: InvocationMode::Always,
            drop_fn: drop_entry::<ServiceClientCallbackEntry<Svc, F, REPLY_BUF>>,
        };
        self.emplace_entry(slot, meta, TraceName::Text(service_name));
        self.apply_node_default_sched(slot, node_id, None);
        Ok((self.handle_for(slot), hdr_ptr))
    }

    // ========================================================================
    // Guard condition registration
    // ========================================================================

    /// Register a guard condition with a callback, on no particular node.
    ///
    /// Returns both the [`HandleId`] for trigger configuration and a
    /// [`GuardCondition`] for triggering from other threads.
    ///
    /// **This is the ours-only PRIMITIVE, not the verb a user reaches for.**
    /// phase-417 W4.e settled that the NODE owns a guard condition in all three
    /// languages, so the spelling an application writes is
    /// [`Node::create_guard_condition`](crate::executor::Node::create_guard_condition)
    /// — which is this function with a node bound, so the guard inherits that
    /// node's `SchedContext` like every other entity the node creates. This one
    /// stays because the executor is what owns the arena the flag lives in, and
    /// because an image with no node at all (a bare `Executor::open` plus a
    /// wake source) still has to be able to make one.
    pub fn register_guard_condition<F>(
        &mut self,
        callback: F,
    ) -> Result<(HandleId, GuardCondition), NodeError>
    where
        F: FnMut() + 'static,
    {
        self.register_guard_condition_on(None, callback)
    }

    /// The node-bound form of [`register_guard_condition`](Self::register_guard_condition)
    /// — phase-417 W4.e.
    ///
    /// `node_id == None` is the legacy nodeless path and behaves exactly as
    /// `register_guard_condition` always did. With a node, the registered slot
    /// takes that node's default `SchedContext`, which is what "the node owns
    /// it" has to mean for a callback that shares one executor with every other
    /// tier in the image (RFC-0047).
    pub fn register_guard_condition_on<F>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        callback: F,
    ) -> Result<(HandleId, GuardCondition), NodeError>
    where
        F: FnMut() + 'static,
    {
        let slot = self.next_entry_slot()?;
        let offset = self.arena_alloc::<GuardConditionEntry<F>>()?;

        unsafe {
            let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
            let entry_ptr = arena_ptr.add(offset) as *mut GuardConditionEntry<F>;
            core::ptr::write(
                entry_ptr,
                GuardConditionEntry {
                    flag: portable_atomic::AtomicBool::new(false),
                    callback,
                },
            );

            // Create a handle pointing to the flag in the arena
            let flag_ptr = &(*entry_ptr).flag as *const portable_atomic::AtomicBool;
            #[allow(unused_mut)]
            let mut guard_handle = GuardCondition::new(flag_ptr);
            // Phase 124.B.5 — wire the wake callback so trigger()
            // also signals the executor's wake_cv.
            #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
            {
                let ctx = self.wake_ctx_ptr();
                guard_handle.set_wake_cb(nros_rmw_runtime_wake_cb, ctx);
                self.has_cross_thread_waker = true;
            }

            let meta = CallbackMeta {
                offset,
                kind: EntryKind::GuardCondition,
                arena_len: super::arena::ArenaLen::UNRECORDED,
                try_process: guard_try_process::<F>,
                has_data: guard_has_data::<F>,
                pre_sample: no_pre_sample,
                invocation: InvocationMode::OnNewData,
                drop_fn: drop_entry::<GuardConditionEntry<F>>,
            };
            self.emplace_entry(slot, meta, TraceName::Slot("guard", slot));
            self.apply_node_default_sched(slot, node_id, None);

            Ok((self.handle_for(slot), guard_handle))
        }
    }

    /// phase-467 Row 8 — a guard condition the BACKEND triggers when the ROS
    /// graph changes. Upstream's `rcl_node_get_graph_guard_condition`, under
    /// this project's guard-condition shape.
    ///
    /// **The verb is upstream's, the shape is ours, and the difference is
    /// stated rather than silent.** `rcl_node_get_graph_guard_condition`
    /// RETURNS a borrowed handle to a guard the node owns, which the caller
    /// then adds to a wait set. RFC-0018/0019 forbids returning an owned
    /// handle across the C seam, we decline wait sets (RFC-0002: one executor
    /// per RTOS task), and a guard condition here is created into CALLER
    /// storage with its callback bound at creation. So this CREATES one —
    /// exactly as [`register_guard_condition_on`] does — and differs from it
    /// only in who pulls the trigger.
    ///
    /// Order matters and is the reason this is one verb rather than two. The
    /// backend is asked whether it HAS a graph before a handle slot is
    /// consumed, so a caller on XRCE or uORB gets `Unsupported` and an
    /// unchanged executor, never a guard condition nothing will ever fire.
    ///
    /// [`register_guard_condition_on`]: Self::register_guard_condition_on
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub fn register_graph_change_guard_on<F>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        callback: F,
    ) -> Result<(HandleId, GuardCondition), NodeError>
    where
        F: FnMut() + 'static,
    {
        // The probe FIRST — see the doc comment. `supports_*` asks by
        // clearing, which is idempotent and costs nothing.
        if !self.supports_graph_change_callback() {
            return Err(NodeError::Transport(TransportError::Unsupported));
        }
        let (handle_id, guard) = self.register_guard_condition_on(node_id, callback)?;
        self.install_graph_change_guard(&guard)?;
        Ok((handle_id, guard))
    }

    /// The nodeless form of
    /// [`register_graph_change_guard_on`](Self::register_graph_change_guard_on),
    /// for an image with a session and no node — the same pairing
    /// [`register_guard_condition`](Self::register_guard_condition) has.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub fn register_graph_change_guard<F>(
        &mut self,
        callback: F,
    ) -> Result<(HandleId, GuardCondition), NodeError>
    where
        F: FnMut() + 'static,
    {
        self.register_graph_change_guard_on(None, callback)
    }

    /// The same two verbs on a build with no `rmw-cffi` backend seam, or no
    /// allocator — they REFUSE rather than disappear.
    ///
    /// The cfg'd-out spelling was the first shape and it was wrong in a way
    /// `just check fast` cannot see: `rclc_node_get_graph_guard_condition` is
    /// a C ABI symbol and calls this unconditionally, so a feature
    /// combination without the seam stopped `nros-c` from COMPILING
    /// (`check-build`'s `workspace-features`, which is the lane that unifies
    /// nothing and therefore sees each combination as a user would).
    ///
    /// Refusing is also the honest answer rather than a compile fix. The
    /// graph-change edge is installed on a SESSION through the backend seam;
    /// without that seam there is no backend to install it on, and the
    /// executor-owned target needs an allocator for the box the backend holds
    /// a pointer to. `Unsupported` is what a caller gets from a backend with
    /// no graph too, so the C entry point answers `RCL_RET_UNSUPPORTED` in
    /// both cases and a ported program sees one behaviour, not two.
    #[cfg(not(all(feature = "alloc", feature = "rmw-cffi")))]
    pub fn register_graph_change_guard_on<F>(
        &mut self,
        node_id: Option<super::node_record::NodeId>,
        callback: F,
    ) -> Result<(HandleId, GuardCondition), NodeError>
    where
        F: FnMut() + 'static,
    {
        let _ = (node_id, callback);
        Err(NodeError::Transport(TransportError::Unsupported))
    }

    /// The nodeless form on a build with no backend seam — see
    /// [`register_graph_change_guard_on`](Self::register_graph_change_guard_on).
    #[cfg(not(all(feature = "alloc", feature = "rmw-cffi")))]
    pub fn register_graph_change_guard<F>(
        &mut self,
        callback: F,
    ) -> Result<(HandleId, GuardCondition), NodeError>
    where
        F: FnMut() + 'static,
    {
        self.register_graph_change_guard_on(None, callback)
    }

    // ========================================================================
    // Timer control methods
    // ========================================================================

    /// Cancel a timer. A cancelled timer will not fire but still accumulates
    /// elapsed time. The timer can be restarted with [`reset_timer()`](Self::reset_timer).
    pub fn cancel_timer(&mut self, id: HandleId) -> Result<(), NodeError> {
        let meta = self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
            .ok_or(NodeError::BufferTooSmall)?;
        if !matches!(meta.kind, EntryKind::Timer) {
            return Err(NodeError::BufferTooSmall);
        }
        let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
        // SAFETY: meta.offset points to a valid TimerEntry<F> which shares
        // layout with TimerHeader for its initial fields (both #[repr(C)]).
        let header = unsafe { &mut *(arena_ptr.add(meta.offset) as *mut TimerHeader) };
        header.cancelled = true;
        Ok(())
    }

    /// Reset a timer. Clears the cancelled state and resets the elapsed time
    /// to zero, so the timer starts a fresh period.
    pub fn reset_timer(&mut self, id: HandleId) -> Result<(), NodeError> {
        let meta = self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
            .ok_or(NodeError::BufferTooSmall)?;
        if !matches!(meta.kind, EntryKind::Timer) {
            return Err(NodeError::BufferTooSmall);
        }
        let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
        let header = unsafe { &mut *(arena_ptr.add(meta.offset) as *mut TimerHeader) };
        header.cancelled = false;
        header.elapsed_us = 0;
        Ok(())
    }

    /// Check if a timer is cancelled.
    pub fn timer_is_canceled(&self, id: HandleId) -> bool {
        let meta = match self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
        {
            Some(m) if matches!(m.kind, EntryKind::Timer) => m,
            _ => return false,
        };
        let arena_ptr = self.arena.as_ptr() as *const u8;
        let header = unsafe { &*(arena_ptr.add(meta.offset) as *const TimerHeader) };
        header.cancelled
    }

    /// Get the period of a timer in milliseconds (truncated — see
    /// [`Self::timer_period_us`]), or `None` if the handle is not a
    /// valid timer.
    pub fn timer_period_ms(&self, id: HandleId) -> Option<u64> {
        let meta = self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
            .filter(|m| matches!(m.kind, EntryKind::Timer))?;
        let arena_ptr = self.arena.as_ptr() as *const u8;
        let header = unsafe { &*(arena_ptr.add(meta.offset) as *const TimerHeader) };
        Some(header.period_us / 1000)
    }

    /// Get the period of a timer in microseconds, or `None` if the
    /// handle is not a valid timer.
    pub fn timer_period_us(&self, id: HandleId) -> Option<u64> {
        let meta = self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
            .filter(|m| matches!(m.kind, EntryKind::Timer))?;
        let arena_ptr = self.arena.as_ptr() as *const u8;
        // SAFETY: same layout invariant as `timer_period_ms`.
        let header = unsafe { &*(arena_ptr.add(meta.offset) as *const TimerHeader) };
        Some(header.period_us)
    }

    /// Swap a registered timer's period, in microseconds, returning the one
    /// it had — or `None` if the handle is not a valid timer.
    ///
    /// `TimerHeader::period_us` is the number `arena::timer_try_process`
    /// compares `elapsed_us` against, so this writes the period the
    /// DISPATCHER honours rather than a second copy of it (RFC-0019). The C
    /// entry point `rcl_timer_exchange_period` also keeps
    /// `rcl_timer_t::period_ns` in step, because that field is the
    /// registration input a later `rclc_executor_add_timer` would re-read.
    ///
    /// `elapsed_us` is deliberately NOT rewound, which is rcl's own behaviour:
    /// `rcl_timer_exchange_period` swaps the period and touches nothing else,
    /// so a timer shortened below its accumulated elapsed time becomes ready
    /// at once and one lengthened past it simply waits longer. A caller that
    /// wants the new period to start fresh calls
    /// [`reset_timer`](Self::reset_timer) after it.
    ///
    /// phase-417 W5.c — the Rust half of `c:timer_exchange_period`, the last
    /// timer row the C ledger filed as `gap`. The answer lives here and only
    /// the spelling lives in the wrapper, the same split
    /// [`timer_elapsed_us`](Self::timer_elapsed_us) made.
    pub fn exchange_timer_period_us(&mut self, id: HandleId, new_period_us: u64) -> Option<u64> {
        let offset = self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
            .filter(|m| matches!(m.kind, EntryKind::Timer))?
            .offset;
        let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
        // SAFETY: same layout invariant as `timer_period_us`.
        let header = unsafe { &mut *(arena_ptr.add(offset) as *mut TimerHeader) };
        let old_period_us = header.period_us;
        header.period_us = new_period_us;
        Some(old_period_us)
    }

    /// Set a timer's overrun policy (issue #505). Timers default to
    /// [`TimerOverrunPolicy::Skip`]; switch to
    /// [`TimerOverrunPolicy::CatchUp`] for timers whose every activation
    /// is a unit of work that must not be lost.
    pub fn set_timer_overrun_policy(
        &mut self,
        id: HandleId,
        policy: TimerOverrunPolicy,
    ) -> Result<(), NodeError> {
        let meta = self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
            .ok_or(NodeError::BufferTooSmall)?;
        if !matches!(meta.kind, EntryKind::Timer) {
            return Err(NodeError::BufferTooSmall);
        }
        let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
        // SAFETY: same layout invariant as `cancel_timer`.
        let header = unsafe { &mut *(arena_ptr.add(meta.offset) as *mut TimerHeader) };
        header.overrun_policy = policy;
        Ok(())
    }

    /// Periods this timer missed and dropped under
    /// [`TimerOverrunPolicy::Skip`] (issue #505), or `None` if the handle
    /// is not a valid timer.
    ///
    /// Monotonic and saturating. A growing count is the on-target signal
    /// that a tier is not keeping up with its declared cadence — the
    /// symptom an external observer would otherwise have to infer by
    /// differencing timestamps.
    pub fn timer_overruns(&self, id: HandleId) -> Option<u32> {
        let meta = self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
            .filter(|m| matches!(m.kind, EntryKind::Timer))?;
        let arena_ptr = self.arena.as_ptr() as *const u8;
        let header = unsafe { &*(arena_ptr.add(meta.offset) as *const TimerHeader) };
        Some(header.overruns)
    }

    /// Microseconds accumulated since this timer last fired, or `None` if the
    /// handle is not a valid timer.
    ///
    /// This is `TimerHeader::elapsed_us` — the SAME counter
    /// `arena::timer_try_process` compares against the period and rewinds on
    /// every activation, so it is the executor's own answer rather than a
    /// second one derived from a clock. `None` is not "zero elapsed": a caller
    /// that cannot tell them apart reports a timer that has just fired and a
    /// handle that is not a timer identically.
    ///
    /// phase-417 W5.c — added because the state was already here and nothing
    /// exposed it, which is why `c:timer_get_time_since_last_call` and
    /// `c:timer_is_ready` were both filed as gaps. The C forwarders
    /// (`rcl_timer_get_time_since_last_call`, `nros_timer_is_ready`) read
    /// this; RFC-0019 puts the answer in Rust and only the spelling in the
    /// wrapper.
    pub fn timer_elapsed_us(&self, id: HandleId) -> Option<u64> {
        let meta = self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
            .filter(|m| matches!(m.kind, EntryKind::Timer))?;
        let arena_ptr = self.arena.as_ptr() as *const u8;
        // SAFETY: same layout invariant as `timer_period_us`.
        let header = unsafe { &*(arena_ptr.add(meta.offset) as *const TimerHeader) };
        Some(header.elapsed_us)
    }

    /// Would this timer fire on the next dispatch pass? `None` if the handle
    /// is not a valid timer.
    ///
    /// The predicate is `arena::timer_try_process`'s own guard, in the same
    /// order: a cancelled timer is never ready, a one-shot that already fired
    /// is never ready again, and otherwise readiness is `elapsed >= period`.
    /// Keeping the two in one shape is the point — a readiness answer that
    /// disagrees with the dispatcher is worse than no answer at all.
    pub fn timer_is_ready(&self, id: HandleId) -> Option<bool> {
        let meta = self
            .entries
            .get(self.live_slot(id))
            .and_then(|e| e.as_ref())
            .filter(|m| matches!(m.kind, EntryKind::Timer))?;
        let arena_ptr = self.arena.as_ptr() as *const u8;
        // SAFETY: same layout invariant as `timer_period_us`.
        let header = unsafe { &*(arena_ptr.add(meta.offset) as *const TimerHeader) };
        if header.cancelled || (header.oneshot && header.fired) {
            return Some(false);
        }
        Some(header.elapsed_us >= header.period_us)
    }

    /// Nanoseconds until this timer next fires — NEGATIVE when it is overdue.
    /// `None` if the handle is not a valid timer.
    ///
    /// phase-417 G6. THE computation, and it has to be: rcl's own pair are
    /// `next_call_time` and `next_call_time - now`, so upstream cannot have
    /// them disagree either. Before this it lived in `nros-c`
    /// (`remaining_period_ns` + `time_until_next_call_ns_of`), and the C++
    /// half of `cpp:Timer::time_until_trigger` would have been a second
    /// derivation of the same subtraction in a second crate — the shape
    /// CLAUDE.md's "fix the CLASS, add ONE shared helper rather than a second
    /// spelling" rule names. `nros-c` forwards here now; so does `nros-cpp`.
    ///
    /// **The unit is nanoseconds and the RESOLUTION is microseconds.** The
    /// arena's timer accounting is microsecond-based (issue #505), so this is a
    /// microsecond quantity scaled by 1000. The unit is rcl's; the resolution
    /// is ours.
    ///
    /// Saturating rather than wrapping: `period_us` and `elapsed_us` are both
    /// `u64`, so their difference in nanoseconds can leave `i64` in either
    /// direction, and a wrap would turn "overdue by a lot" into "due in a
    /// long time" — the sign is the whole answer here.
    pub fn timer_time_until_next_call_ns(&self, id: HandleId) -> Option<i64> {
        let period_us = self.timer_period_us(id)?;
        let elapsed_us = self.timer_elapsed_us(id)?;
        let delta_ns = (period_us as i128 - elapsed_us as i128).saturating_mul(1_000);
        Some(if delta_ns > i64::MAX as i128 {
            i64::MAX
        } else if delta_ns < i64::MIN as i128 {
            i64::MIN
        } else {
            delta_ns as i64
        })
    }

    // ========================================================================
    // spin_once (three-phase: readiness -> trigger -> dispatch)
    // ========================================================================

    /// Drive I/O and dispatch registered callbacks once.
    ///
    /// Three-phase execution:
    /// 1. **Readiness scan** — query each handle's `has_data()`.
    /// 2. **Trigger evaluation** — check if the executor-level trigger passes.
    /// 3. **Dispatch** — invoke callbacks according to their `InvocationMode`.
    ///
    /// Returns a [`SpinOnceResult`] with counts of processed items and errors.
    ///
    /// # Arguments
    /// * `timeout` — upper bound on the I/O wait. Saturated at
    ///   `i32::MAX` ms (~24 days) for the underlying transport call.
    ///
    /// Phase 84.D7: unified on `core::time::Duration`. The previous
    /// `timeout_ms: i32` signature had a latent footgun where
    /// `spin_once(-1)` silently froze timers while still polling I/O;
    /// `Duration` has no negative sentinel.
    /// Consecutive `drive_io` failures on the primary session (issue 0324).
    ///
    /// `0` means the last drive succeeded. A value that keeps climbing across
    /// spins is a session that is no longer doing I/O — router gone, lease
    /// expired, socket closed — which otherwise presents as a node that spins
    /// `Ok(())` forever while publishing nowhere and firing no callbacks.
    ///
    /// Transient failures happen, so a single non-zero reading is not a fault;
    /// a threshold (say, "more than a few consecutive spins") is the useful
    /// signal. Extra (bridge / multi-domain) sessions are best-effort and are
    /// deliberately NOT counted here.
    pub fn session_io_failures(&self) -> u32 {
        self.consecutive_io_failures
    }

    /// Whether the primary session drove I/O successfully on the last spin.
    ///
    /// Convenience over [`Self::session_io_failures`] for the common
    /// "is my transport alive?" check.
    pub fn session_io_healthy(&self) -> bool {
        self.consecutive_io_failures == 0
    }

    /// Drive I/O once, then dispatch EVERY callback that is ready — the tick
    /// primitive the rest of the family is built from.
    ///
    /// OURS-ONLY (RFC-0089): rclcpp's `spin_once` executes the NEXT ready item
    /// and has no timeout; rclpy's is `spin_once(node, timeout_sec)`. Ours is a
    /// blocking wait with a budget, which an RTOS task that must not spin-poll
    /// needs and which neither upstream has a verb for. What it DOES when work
    /// is ready is rclcpp's `spin_some` — the whole ready set, one pass
    /// (RFC-0002 §3) — so [`spin_some`](Self::spin_some) is the drain verb and
    /// this is the waiting one.
    ///
    /// `timeout` is the upper bound on the I/O wait. Since phase-436 W2 it is
    /// carried in MICROSECONDS all the way to the park (issue 1193 — an
    /// `as_millis()` here truncated `from_micros(500)` to `0`, and a zero
    /// timeout selects the non-blocking path, so a sub-millisecond `spin()`
    /// was a 100 % CPU loop with no warning); the conversion to whatever the
    /// platform primitive accepts happens once, at the park, and rounds UP.
    /// `Duration` has no negative sentinel, which is what the pre-phase-84
    /// `timeout_ms: i32` signature used to silently mean "freeze the timers
    /// and poll I/O forever".
    pub fn spin_once(&mut self, timeout: core::time::Duration) -> SpinOnceResult {
        let mut discarded = None;
        self.spin_once_capturing(timeout, &mut discarded)
    }

    /// [`spin_once`](Self::spin_once), plus the FIRST failing callback's
    /// error.
    ///
    /// phase-427 — [`SpinOnceResult`] counts errors and drops their values,
    /// and `SpinOnceResult` is `Copy`, so widening it to carry a
    /// (non-`Copy`, `alloc`-variant-bearing) [`TransportError`] would change a
    /// public type every consumer copies. The value is needed in exactly one
    /// place — `SpinOptions::stop_on_first_error`, where `spin` has to return
    /// the first error rather than a count — so it is threaded out through an
    /// out-parameter that lives in the caller's frame. Nothing is added to
    /// `Executor`, so a no-alloc image pays nothing for it.
    ///
    /// `first_error` is written at most once: subsequent failures in the same
    /// pass are counted in the result and their values dropped, exactly as
    /// before.
    fn spin_once_capturing(
        &mut self,
        timeout: core::time::Duration,
        first_error: &mut Option<TransportError>,
    ) -> SpinOnceResult {
        // Issue 1705 — releases deferred behind a dispatch that has since
        // finished (an OS-priority worker's) are completed here, before this
        // pass looks at the entries.
        self.reap_deferred_releases();
        // phase-436 W2 (issue 1193) — the budget is carried in MICROSECONDS.
        // This was `as_millis()`, which truncates: `from_micros(500)` became
        // `0`, and a zero timeout selects the non-blocking path — so a
        // sub-millisecond `spin()` was a 100 % CPU loop with no warning. The
        // conversion to whatever the platform primitive accepts happens once,
        // at the park, and rounds UP. The budget itself is `grid_budget_us`
        // below (phase-474 I11).

        // phase-425 W3b — bring the `/clock` subscription in line with
        // `use_sim_time`. One bool comparison in the settled case; the work only
        // happens on a transition, or while a request is waiting for its first
        // node to exist.
        #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
        self.reconcile_ros_time_source();

        // phase-426 W3 — attach the six parameter services to any node that
        // does not have them yet. Same reason as the reconcile above: the
        // request routinely arrives before there is a node to publish under
        // (`nros::main!` emits `apply_param_services` ahead of its per-node
        // `register` calls, by design). One length comparison once settled.
        //
        // Issue 1271 -- a failure is LOGGED, once, rather than discarded. On
        // Cyclone this fails on every spin with `Transport(Unsupported)`
        // (issue 1268), and with the result dropped "this node has no
        // parameter services" was a fact nothing on the image stated.
        #[cfg(feature = "param-services")]
        if self.parameter_services_pending()
            && let Err(e) = self.reconcile_parameter_services()
        {
            self.report_parameter_service_reconcile_failure(e);
        }

        // Release jitter, measured HERE rather than in `spin_period`, because
        // this is the function every driver goes through.
        //
        // The first version instrumented `spin_period` only, and that was the
        // same mistake issue 0736 records one layer down: a measurement placed
        // on a path no shipped image takes. `nros-cpp`'s tier trampoline paces
        // itself with a `spin_once` loop at `spin_period_us` (see its
        // `run_components` docs, step 4), so `spin_period` is not what the C++
        // entry -- and therefore not what the Zephyr lane -- actually calls.
        // The field recorded zero forever while claiming to measure cadence.
        //
        // `timeout` is the caller's intended pacing quantum: `spin_period`
        // passes its period, and the generated entries pass 10 ms. phase-474
        // I11 -- with no declared cadence it is the period of an absolute
        // release grid, and the park budget is the time to the next grid
        // point (see `record_release_jitter`); the release is judged after the
        // park, against the grid (`record_grid_release`). A zero timeout means
        // "poll, no cadence claimed", so it is neither judged nor gridded.
        let grid_budget_us = self.record_release_jitter(timeout);

        // issue 0900 — one-shot advisory when the arena is far larger than what
        // registered. First spin rather than "end of registration", because
        // there is no such point: an app may register lazily.
        super::arena::maybe_report_arena_headroom(self.arena_used, self.arena.len());

        // phase-412 -- the same moment, recorded where a board with no log sink
        // can still be asked. Reaching this stage is the positive result the
        // advisory above cannot deliver on the island: registration completed.
        crate::boot_report::checkpoint(crate::boot_report::Stage::FirstSpin);

        // Phase 110.0 — the backend's next internal-event deadline (lease
        // keepalive, heartbeat, ACK-NACK timeout, ...). Default backend impl
        // returns `None`, so this contributes nothing unless the active
        // backend opts in.
        //
        // phase-436 W6 — a CANDIDATE now, not a pre-cap. Folding it into the
        // budget here meant a park the session won was attributed to
        // `CallerBudget`, so the one number that explains a wake named the
        // wrong source.
        let session_us = self
            .session
            .next_deadline_ms()
            .map(|next| (next as u64).saturating_mul(1000));

        // phase-436 W1 (issue 1192) — and by the next TIMER deadline, which is
        // the one class of deadline the executor itself owns. Before this the
        // park was bounded by the caller's budget narrowed only by the
        // BACKEND's next event, so `spin_default`'s 50 ms slept straight past
        // a registered 10 ms timer.
        //
        // Attribution is recorded here rather than derived later: this is the
        // only point where the losing candidates are still in hand.
        let (park_bound_us, park_source) =
            self.next_wake_bound_attributed_us(grid_budget_us, session_us);
        self.last_park_bound_us = park_bound_us;
        self.last_park_source = park_source;
        // phase-436 W2 (issue 1193) — round UP to what the primitive can
        // express. The old `as_millis()` truncated, so a sub-millisecond
        // request became a zero park: the non-blocking path, a busy loop.
        let park_achieved_us = self.round_park_up_us(park_bound_us);
        self.last_park_achieved_us = park_achieved_us;

        // phase-436 W6 — a port that installed a park primitive does its
        // waiting HERE, on the bound every source agreed on, and the transport
        // is then drained non-blockingly.
        //
        // This is the path bare metal needs: `park_until(deadline)` can arm a
        // timer compare before `wfi`, which `sleep(duration)` cannot express —
        // and `nros-baremetal-common` notes that `wfi` with no pending
        // interrupt deadlocks, so arming first is not optional there.
        //
        // Additive by construction: with no primitive installed this is a
        // no-op and every existing port keeps the behaviour it has.
        // phase-436 — park only when something can END the park early. A
        // park ends on the bound or on the wake object; with a poll-only
        // backend (XRCE), or a session whose wake callback is gone, nothing
        // signals that object, so the park would be a blind sleep and data
        // arriving mid-park would wait out the whole bound — the Phase
        // 127.C.4 stall (a reliable stream whose ACK lands in a session nobody
        // drives). Those executors keep the receive-blocking wait below.
        let park_can_be_woken = self.park_can_be_woken();
        let parked = match self.park_primitive {
            Some((park, ctx)) if park_achieved_us > 0 && park_can_be_woken => {
                // SAFETY: `park` and `ctx` were supplied together by the port
                // through `set_park_primitive` and outlive the executor by its
                // contract.
                //
                // phase-436 — a negative answer is "cannot park": the ABI's
                // own contract, and what a Rust-implemented port's trait
                // default returns at once. Counting that as a park would
                // drop the drain below to non-blocking and spin hot, so the
                // spin falls back to the wait it would have had uninstalled.
                (unsafe { park(ctx, park_achieved_us) }) >= 0
            }
            _ => false,
        };

        // Having already waited, the transport drain must not block again —
        // otherwise the park and the drive would sum, and the cadence would be
        // up to twice what was asked. Same trap as passing a period to
        // `spin_once` instead of declaring it (#648).
        let timeout_ms = if parked {
            0
        } else {
            (park_achieved_us / 1000).min(i32::MAX as u64) as i32
        };

        // Wall-clock-accurate timer accumulation. Measure real time
        // since the previous `spin_once` exited (or, on the first call,
        // since `drive_io` started). Two failure modes the requested
        // `timeout_ms` doesn't capture:
        //  1. `drive_io` returns early — e.g. zenoh-pico's condvar wakes
        //     on data arrival, well under 1 ms.
        //  2. The caller spends time outside `spin_once` (explicit sleep,
        //     ROS-2 cooperative scheduling, etc.) and that time should
        //     still count toward timers.
        // Crediting the requested timeout to timers in either case ticks
        // them faster than wall-clock — observed as a 30 Hz control loop
        // overshooting to >200 Hz under sustained traffic. Carry the
        // sub-ms remainder across calls so precision is preserved.
        // phase-359 W4 — the spin-ENTRY read, one spelling. Kept distinct from
        // the post-IO read below because the first spin's delta is measured from
        // entry; collapsing them would make that delta 0 on the first call only.
        let spin_start_us = self.now_us();

        // phase-474 I2 -- arm the monitors when the policy says start-up is over,
        // before any rule of this spin can judge.
        self.update_monitor_arming(spin_start_us);

        // RFC-0052 W3b.4 — contract monitors tick once per spin (window
        // logic inside; single branch when the baked table is empty).
        self.run_contract_monitors();

        // Phase 104.C.6 — shared executor wake. Swap-and-clear the
        // wake flag; if it was set before this `spin_once` entered,
        // skip the blocking wait on the primary session and poll
        // every session non-blockingly. Lets a wake signal from any
        // thread (or, post-104.C.6.b, any backend's vtable hook)
        // pre-empt whichever session the executor would otherwise
        // sleep on. Cost on the no-wake path is one atomic swap.
        // phase-359 W10 — ONE swap, at `alloc` scope.
        //
        // This was `#[cfg(feature = "std")]` while the alloc wait arm did its
        // own swap further down. Merging the two arms made that two swaps of
        // one flag per spin, the first consuming what the second tested, so the
        // arm would have read `was_woken == false` forever. Deleting the outer
        // one instead broke a different thing: `wake_flag` is `alloc`-gated and
        // "spin_once consumes the wake flag" is an invariant of every alloc
        // build, but the merged arm only runs with `rmw-cffi` — so a
        // `std`-without-`rmw-cffi` build stopped clearing it, which
        // `test_wake_cleared_each_spin` catches. It belongs here, at the scope
        // of the field it reads.
        #[cfg(feature = "alloc")]
        #[allow(unused_variables)]
        let was_woken = self
            .wake_flag
            .swap(false, portable_atomic::Ordering::SeqCst);

        // Phase 124.B.4 — condvar-blocked wait.
        //
        // RT contract:
        //  * cv.wait_timeout_while: bounded by `timeout_ms`.
        //    Predicate is O(1) — one atomic swap + Instant::now.
        //    No allocation. PI-mutex consideration: wake_mu held
        //    only during predicate check (microseconds);
        //    contended worst-case = notify_all execution time
        //    (~10s of µs).
        //  * Backend's `set_wake_callback`-installed cb is called
        //    on async data arrival from its transport-notify path
        //    (worker thread, ISR-safe variant via 124.B.7). The
        //    runtime cb writes wake_flag + signals wake_cv,
        //    unblocking this loop sub-poll-period.
        //  * Poll-only backends (XRCE, bare-metal) leave the slot
        //    NULL; the cv wait still fires on its deadline, then
        //    drive_io(0) drains whatever the backend's internal
        //    poll has buffered. Equivalent to their pre-124
        //    behaviour minus the blocking wait inside drive_io.
        //
        // Lost-wakeup safe: SeqCst flag write happens-before
        // notify, and the waiter checks the flag under wake_mu in
        // the predicate. If wake fires between drain and cv.wait
        // entry, the predicate sees flag=true on first eval and
        // exits immediately.
        // Phase 130.4 — only sleep in the wake wait when a backend actually
        // installed `set_wake_callback`. Poll-only backends (XRCE) leave the
        // vtable slot NULL → `has_async_wake == false` →
        // drive_io for the caller's full timeout instead of sleeping in a
        // never-signaled wait that starves reliable retransmission (Phase
        // 127.C.4 root cause: the server's `send_response` flushes 100 ms once,
        // then a blind `wait_ms(100)` sleeps with zero session activity, so the
        // agent's ACK arrives into a stalled session and reliable redelivery
        // never fires).
        //
        // Phase 248 (C2) — which primitive is a RUNTIME choice from the
        // platform vtable's wake probe, not a compile-time per-RTOS `cfg`:
        // `node_wake.is_some()` means `nros_platform_wake_*` is linked and
        // `nros_rmw_runtime_wake_cb` signals it on transport arrival.
        // phase-359 W10 — ONE arm. This was a `std` arm and an `alloc` arm with
        // the same body: block on the platform wake primitive when a backend
        // installed the callback and nothing has woken us yet, else drive the
        // transport for the caller's full timeout. They stopped differing when
        // the condvar fallback was deleted — the std arm's `else` branch had
        // already become "drive for the full timeout", which is what the alloc
        // arm always did — so keeping two was keeping a fork that agreed.
        // phase-417 W4.e — the FIRST arm is what the swap-and-clear above says
        // it is for, and it was missing: a wake that landed BETWEEN two spins
        // set the flag, and this expression then took the `else` and drove the
        // transport for the caller's FULL timeout, so the pending work waited
        // out the very budget the wake exists to cut short. Measured with a
        // guard condition triggered from another thread just before a 400 ms
        // spin: 400 ms to dispatch, against 50 ms for the same trigger issued
        // while the spin was already parked in `wait_ms`. Being woken means
        // there IS work, so the right timeout is 0 — poll every session
        // non-blockingly and go dispatch it, which is what the comment at the
        // swap has claimed since Phase 104.C.6.
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        let primary_drive_timeout_ms = {
            if was_woken {
                // Issue 1385 — drain the wake PRIMITIVE too.
                //
                // `nros_rmw_runtime_wake_cb` sets both halves of one signal:
                // the flag, and the platform primitive. The swap above
                // consumed the flag and this arm returns without entering the
                // wait, so a primitive left posted makes the NEXT spin's
                // `wait_ms` return instantly on a signal already acted on —
                // that spin does not wait at all, and whatever it should have
                // waited for is dispatched a whole spin late.
                //
                // `wait_ms(0)` is the non-blocking take: every port's wait is a
                // deadline (`sem_timedwait`, `k_sem_take`, `xSemaphoreTake`),
                // so zero means "take it if it is there", never "wait
                // forever".
                //
                // Measured, not reasoned: with the C executor installing a
                // callback (the other half of 1385), an arrival taken by this
                // arm left the spin after it returning in 0 ms where it owed
                // 60 ms of waiting — which is what `node_guard_condition.c`'s
                // mid-spin case caught, and what `executor_backend_wake.c`'s
                // second lower bound now pins. Latent until then only because
                // no C spin had ever entered the wait arm.
                if let Some(wake) = self.node_wake.as_ref() {
                    let _ = wake.wait_ms(0);
                }
                0
            } else if self.async_wake_live()
                && let Some(wake) = self.node_wake.as_ref()
            {
                // phase-436 — after a park this wait has a zero timeout and
                // the park has already waited on this same object, so it is a
                // second syscall that can only time out. Measured on a native
                // tier: one extra futex wait per iteration, doubling the idle
                // context switches. A signal that lands between the park's
                // return and here stays posted and ends the next park at once,
                // which costs one spin and loses nothing.
                if !parked {
                    let _ = wake.wait_ms(timeout_ms as u32);
                }
                // Drain any flag the cb set while we were waiting.
                let _ = self
                    .wake_flag
                    .swap(false, portable_atomic::Ordering::SeqCst);
                0
            } else {
                // No wake primitive linked, or a poll-only backend: drive the
                // transport for the full timeout. It still BLOCKS — in the
                // transport's own recv — which is where every flavour ended up
                // anyway.
                timeout_ms
            }
        };

        // std builds without rmw-cffi (mock-session tests, future alternative
        // backends) keep the original "drive_io is non-blocking" assumption.
        // `std` implies `alloc`, so this is the only std configuration the arm
        // above does not cover.
        #[cfg(all(feature = "std", not(feature = "rmw-cffi")))]
        let primary_drive_timeout_ms = 0;

        // no_std without (alloc + rmw-cffi) keeps the legacy
        // full-timeout drive_io call.
        #[cfg(all(
            not(feature = "std"),
            not(all(feature = "alloc", feature = "rmw-cffi"))
        ))]
        let primary_drive_timeout_ms = timeout_ms;

        // issue 0324 — the primary session's I/O result is TRACKED, not
        // discarded. See `consecutive_io_failures` for why this is a counter
        // rather than an early return.
        match self.drive_primary(primary_drive_timeout_ms) {
            Ok(()) => self.consecutive_io_failures = 0,
            Err(_) => self.consecutive_io_failures = self.consecutive_io_failures.saturating_add(1),
        }
        for extra in self.extra_sessions.iter_mut() {
            // Best-effort BY DESIGN: extra sessions are bridge / multi-domain
            // attachments, and one of them failing must not stall the primary
            // spin. The old code expressed this the same way it expressed the
            // primary's discarded error — identically — so the intent was
            // invisible. It is now the only `let _ =` of the two.
            let _ = extra.drive_io(0);
        }

        // phase-359 W4 — ONE clock read per spin, shared by the delta below and
        // every consumer further down. Replaces the std/no_std delta pair AND
        // two ad-hoc `static EPOCH: OnceLock<Instant>` blocks that each kept
        // their own std-only epoch.
        let now_us_this_spin = self.now_us();
        // phase-474 I11 -- the release instant is the end of the park, so it
        // is judged on this read, before any dispatch of this spin.
        if let Some(now) = now_us_this_spin {
            self.record_grid_release(now);
        }

        // Same rule on both flavours: measure elapsed when a clock exists, else
        // credit the REQUESTED timeout. That fallback was previously reachable
        // only on no_std; on std `Instant` always answered. It stays unreachable
        // on std for the same reason — `now_us()` is infallible there — so this
        // is one expression, not a behaviour change.
        let delta_us = match now_us_this_spin {
            Some(now) => {
                let prev = self
                    .last_spin_end_us
                    .unwrap_or_else(|| spin_start_us.unwrap_or(now));
                self.last_spin_end_us = Some(now);
                now.saturating_sub(prev)
            }
            None => (timeout_ms as u64).saturating_mul(1000),
        };

        // phase-430 W1 — the silence watch is credited the SAME `delta_us` the
        // wall timers below are, which is the whole of its unit argument: the
        // diagnostic arrives after as much time as this image's own wall timers
        // believe has passed, on whatever clock it actually has.
        #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
        self.note_sim_time_silence(delta_us);

        if !self.spin_quantization_checked && timeout_ms > 0 {
            self.spin_quantization_checked = true;
            // The TIER's declared cadence, not the capped park bound. Since
            // phase-436 W1 the two differ whenever a timer is due sooner than
            // the budget, and auditing the cap would compare the timer period
            // against itself — an exact multiple every time, so issue 0515's
            // warning would go silent on precisely the images that have a
            // timer to quantize. `spin_nominal_us` is the declared cadence
            // (`set_spin_nominal_us`, else the caller's timeout), recorded at
            // the top of this spin before any capping.
            self.spin_quantization_us = self.spin_nominal_us;
            self.audit_spin_quantization(self.spin_quantization_us);
        }

        let arena_ptr = self.arena.as_mut_ptr() as *mut u8;

        // Phase 1: Readiness scan (Phase 110.A.b — backed by FifoReadySet).
        //
        // `bits` carries data-readiness only (used by trigger eval +
        // by `InvocationMode::OnNewData`). `always_mask` carries the
        // `InvocationMode::Always` entries that fire regardless of
        // data presence. The dispatcher drains
        // `FifoReadySet(bits | always_mask)` after the trigger
        // passes; `pop_next` yields registration order (lowest bit
        // first) so behavior is bit-identical to the pre-refactor
        // `for (i, meta) in entries.iter().enumerate()` loop.
        let mut bits: u64 = 0;
        let mut count: usize = 0;
        let mut non_timer_mask: u64 = 0;
        let mut always_mask: u64 = 0;

        for (i, meta) in self.entries.iter().enumerate() {
            if let Some(meta) = meta
                && !Self::slot_held(self.slot_tags, i)
            {
                let data_ptr = unsafe { arena_ptr.add(meta.offset) as *const u8 };
                if unsafe { (meta.has_data)(data_ptr) } {
                    bits |= 1u64 << i;
                }
                if !matches!(meta.kind, EntryKind::Timer | EntryKind::GuardCondition) {
                    non_timer_mask |= 1u64 << i;
                }
                if matches!(meta.invocation, InvocationMode::Always) {
                    always_mask |= 1u64 << i;
                }
                count += 1;
            }
        }

        let snapshot = ReadinessSnapshot { bits, count };

        // Phase 2: Trigger evaluation
        let trigger_passes = match &self.trigger {
            Trigger::Any => bits & non_timer_mask != 0 || non_timer_mask == 0,
            Trigger::All => bits & non_timer_mask == non_timer_mask,
            Trigger::One(id) => snapshot.is_ready(*id),
            Trigger::AllOf(set) => snapshot.all_ready(*set),
            Trigger::AnyOf(set) => snapshot.any_ready(*set),
            Trigger::Always => true,
            Trigger::Predicate(f) => f(&snapshot),
            Trigger::RawPredicate { callback, context } => {
                // Convert ReadinessSnapshot bitmask to a bool array for the C callback
                let mut ready_array = [false; 64];
                for (i, slot) in ready_array
                    .iter_mut()
                    .enumerate()
                    .take(snapshot.count.min(64))
                {
                    *slot = snapshot.bits & (1u64 << i) != 0;
                }
                // SAFETY: The callback and context are provided by the C API caller.
                // The ready_array is valid for snapshot.count elements.
                unsafe { callback(ready_array.as_ptr(), snapshot.count, *context) }
            }
        };

        if !trigger_passes {
            // Timers still need delta accumulation even when trigger doesn't pass
            //
            // phase-8 — `.enumerate()` (rather than a bare `.flatten()`) because
            // `try_process` now carries the entry's slot index for the callback
            // trace hooks. This sweep FIRES timer callbacks, so it is a real
            // dispatch path and must attribute them like the drain below does.
            //
            // phase-474 I6 -- and it must TIME them like the drain does. This
            // is the path every timer takes on a node that also subscribes
            // (the default `Trigger::Any` fails whenever no subscription has
            // a sample), and it measured nothing, so `max-latency-runtime`
            // never judged a timer path: the safety island's 250 ms overrun of
            // a 206 ms path stored no verdict. One clock read before and one
            // after each timer's `try_process`, only when a latency contract
            // exists and a clock is injected; the publish-count snapshot is a
            // fixed array on the stack, nothing allocates. The measured span
            // is callback entry to exit, as in the drains; release jitter is
            // `release-jitter-runtime`'s.
            let mon_table = self.monitor_table;
            // phase10-B3 -- the route rule reads the same clock and snapshot:
            // a timer tick is where a sampled route's output is published.
            let lat_clock = self.clock_us_fn.filter(|_| {
                mon_table.iter().any(|m| m.max_latency_ms > 0)
                    || super::monitor::route_active(mon_table)
            });
            for i in 0..self.entries.len() {
                let Some(meta) = self.entries[i].as_ref() else {
                    continue;
                };
                if matches!(meta.kind, EntryKind::Timer) && !Self::slot_held(self.slot_tags, i) {
                    let data_ptr = unsafe { arena_ptr.add(meta.offset) };
                    let try_process = meta.try_process;
                    let counts_before = snapshot_pub_counts(mon_table, lat_clock.is_some());
                    let start_us = lat_clock.map(|c| c());
                    Self::begin_dispatch(self.slot_tags, i);
                    // phase-463 W7 -- the host profile times this sweep too:
                    // it is the path every timer of a node that also
                    // subscribes takes (see above), so missing it measured
                    // the talker's timer at zero invocations.
                    //
                    // The OFF arm is the original `let _ =`, untouched, and
                    // that is MEASURED rather than tidy: every binding tried
                    // in its place (`let _p`, `let p; drop(p)`) moved
                    // `spin_once_capturing` by 49-64 B in the Zephyr image
                    // (phase-463 W5 I3c). Hence the second `unsafe` block,
                    // recorded in the unsafe census.
                    #[cfg(not(feature = "profile-mode"))]
                    let _ = unsafe { try_process(data_ptr, delta_us, i as u8) };
                    #[cfg(feature = "profile-mode")]
                    {
                        super::profile::dispatch_begin(arena_ptr as usize, i);
                        let processed = unsafe { try_process(data_ptr, delta_us, i as u8) };
                        super::profile::dispatch_end(matches!(processed, Ok(true)));
                    }
                    if let (Some(clock), Some(t0)) = (lat_clock, start_us) {
                        let end_us = clock();
                        let elapsed_us = end_us.saturating_sub(t0).min(u32::MAX as u64) as u32;
                        attribute_latency(mon_table, true, &counts_before, elapsed_us);
                        let hook = self.reaction_hook.filter(|_| self.violations.counts.armed);
                        let violations = &mut self.violations;
                        super::monitor::route_judge(
                            mon_table,
                            &counts_before,
                            end_us,
                            |row, v, record, react| {
                                if react {
                                    call_route_reaction(hook, mon_table, row, &v);
                                }
                                if record {
                                    violations.record(v)
                                }
                            },
                        );
                    }
                    self.finish_dispatch(i);
                }
            }

            // Parameter services live outside the arena and must be processed
            // regardless of trigger state, otherwise ROS 2 param queries time out.
            #[cfg(feature = "param-store")]
            {
                #[allow(unused_mut)] // only the services add to it
                let mut handled = 0usize;
                #[cfg(feature = "param-services")]
                if let Some(params) = &mut self.params {
                    {
                        let crate::param_store::ParamState {
                            server,
                            services,
                            buffers,
                            staged,
                            ..
                        } = &mut **params;
                        // phase-426 W3 — one set per node; every set is pumped,
                        // because `ros2 param list` addresses each node's own
                        // six and a set nobody polls times out.
                        //
                        // Issue 1270 -- all of them through ONE buffer pair.
                        // Issue 1271 -- a request that got no reply is logged
                        // inside, once per service; there is no error to drop.
                        if let Some(buffers) = buffers {
                            for set in services.iter_mut() {
                                handled += set.process(server, staged, buffers);
                            }
                        }
                    }
                }
                // phase-425 W3b — a `ros2 param set … use_sim_time true` arrives
                // through this path.
                self.note_param_services_ran(handled);
            }

            // Same treatment for lifecycle services — `ros2 lifecycle get`
            // must succeed even when no callbacks fired this tick.
            //
            // Issue 1587 — `process` also drains the state machine's
            // announcement queue onto `~/transition_event`, so a transition
            // triggered from application code between two spins (autostart is
            // the common one) reaches a watching supervisor here.
            // SAFETY: see the matching invariant on the later call site.
            #[cfg(feature = "lifecycle-services")]
            if let Some(lc) = &mut self.lifecycle {
                let _ = unsafe { lc.process() };
            }

            // phase-474 I7 -- an idle spin is the natural slot for the queued
            // reports.
            self.flush_violation_reports();

            return SpinOnceResult::new();
        }

        // Phase 2.5: LET pre-sample (only when LogicalExecutionTime)
        //
        // Sample all subscription data into entry buffers BEFORE dispatching
        // any callbacks. This ensures all callbacks in this cycle see a
        // consistent snapshot of data from the same point in time.
        // Services are NOT pre-sampled (request-reply is sequential).
        if matches!(self.semantics, ExecutorSemantics::LogicalExecutionTime) {
            for (i, meta) in self.entries.iter().enumerate() {
                let Some(meta) = meta else { continue };
                if matches!(meta.kind, EntryKind::Subscription)
                    && !Self::slot_held(self.slot_tags, i)
                {
                    let data_ptr = unsafe { arena_ptr.add(meta.offset) };
                    unsafe { (meta.pre_sample)(data_ptr) };
                }
            }
        }

        // Phase 3: Dispatch (Phase 110.C — bucketed by SC.priority).
        //
        // Two ready-set families, each split across `Priority::COUNT`
        // buckets (Critical / Normal / BestEffort). Per-entry SC
        // `class` selects FIFO bitmap vs EDF heap; SC `priority`
        // selects the bucket within. Drain order:
        //   for each bucket in priority order (Critical first):
        //     drain EDF heap (deadline-priority), then FIFO bitmap
        //     (registration-order)
        // Default workloads — every entry on the auto-default Fifo SC
        // (Normal priority) — populate only `fifo[Normal]`, so
        // dispatch order is bit-identical to 110.B.b for those.
        const NB: usize = super::sched_context::Priority::COUNT;
        let mut result = SpinOnceResult::new();
        let mut fifo: super::ready_set::BucketedFifoSet<NB, { MAX_CALLBACK_SLOTS }> =
            super::ready_set::BucketedFifoSet::new();
        let mut edf: super::ready_set::BucketedEdfSet<NB, { MAX_CALLBACK_SLOTS }> =
            super::ready_set::BucketedEdfSet::new();
        let active_mask = bits | always_mask;

        // Phase 110.E — refill any Sporadic SC budgets at period
        // boundaries before deciding what to dispatch this cycle.
        // Refill is polled (not ISR-driven) — coarse but correct
        // upper-bound bandwidth limiter.
        // phase-359 W4 — was `#[cfg(feature = "std")]` with NO no_std arm, so
        // polled Sporadic budgets never refilled on embedded: they exhausted
        // once and stayed exhausted. That was a consequence of "no clock on
        // no_std", which is false whenever a `clock_us` hook is injected. Now it
        // runs on either flavour when a clock exists, and is skipped when none
        // does — identical to today's behaviour in that case.
        if let Some(now_us) = now_us_this_spin {
            let now_ms = now_us / 1000;
            // issue 0736 — REFILL only. This used to also charge the cycle's
            // `delta_us` as the per-SC consumption estimate ("worst-case
            // attribution", pending a higher-precision clock hook). That hook
            // landed, and the attribution was not merely coarse: `delta_us` is
            // the wall-clock gap between spins, not CPU the callbacks spent, so
            // wherever the gap exceeds the budget the SC is exhausted on every
            // spin regardless of what it ran. Consumption is charged from
            // measured callback runtime in `consume_dispatch_runtime_us`.
            for slot in self.sporadic_states.iter_mut().flatten() {
                let _ = slot.refill(now_ms);
            }
        }

        for i in 0..self.entries.len() {
            if active_mask & (1u64 << i) == 0 {
                continue;
            }
            let sc_idx = self.sched_context_bindings[i].0 as usize;
            let sc_class_priority_deadline = self
                .sched_contexts
                .get(sc_idx)
                .and_then(|s| s.as_ref())
                .map(|sc| {
                    (
                        sc.class,
                        sc.priority.index(),
                        sc.deadline_us.get().map(|nz| nz.get()).unwrap_or(u32::MAX),
                    )
                });
            let (sc_class, bucket, deadline_us) = sc_class_priority_deadline.unwrap_or((
                super::sched_context::SchedClass::Fifo,
                super::sched_context::Priority::Normal.index(),
                u32::MAX,
            ));
            // Phase 110.E — Sporadic SC dispatch is suppressed when
            // its budget is exhausted. Atomic path (110.E.b PlatformTimer
            // refill) takes precedence when registered; polled path
            // (cycle-level delta_us attribution) handles the unregistered
            // case. Either way, exhausted budget skips dispatch.
            if matches!(sc_class, super::sched_context::SchedClass::Sporadic) {
                #[cfg(feature = "alloc")]
                let atomic_has_budget = self
                    .sporadic_atomic_states
                    .get(sc_idx)
                    .and_then(|s| s.as_ref())
                    .map(|(state, _)| state.has_budget());
                #[cfg(not(feature = "alloc"))]
                let atomic_has_budget: Option<bool> = None;
                let has_budget = match atomic_has_budget {
                    Some(b) => b,
                    None => self
                        .sporadic_states
                        .get(sc_idx)
                        .and_then(|s| s.as_ref())
                        .map(|s| s.budget_remaining_us > 0)
                        .unwrap_or(true),
                };
                if !has_budget {
                    // issue 0736 — keep the TIMER'S CLOCK honest even while the
                    // budget gates its dispatch.
                    //
                    // A timer's `elapsed_us` only advances inside
                    // `timer_try_process`, which is reached only when the entry
                    // is DISPATCHED, and each dispatch is handed just THIS
                    // cycle's `delta_us`. So every cycle skipped here was
                    // dropped from the timer's sense of time: it did not fire,
                    // it did not learn that its period had passed, and — because
                    // the overrun counter is driven by that same `elapsed_us` —
                    // it did not count the activation it missed.
                    //
                    // That is why the throttle was invisible. Measured on
                    // nuttx-arm/rust: ~238 activations lost against ~40
                    // reported, so five in six missed firings were unaccounted
                    // ANYWHERE. The tier ran at a quarter of its declared rate
                    // and the only honest signal was the delivery count itself.
                    //
                    // Advancing the clock here does not dispatch anything and
                    // does not defeat the budget. It makes the entry's own
                    // accounting independent of whether the executor CHOSE to
                    // run it, which is the property every "did this meet its
                    // declaration?" question needs, and it lets the existing
                    // `Skip` policy count the backlog and the existing
                    // `timer-overrun-runtime` rule report it.
                    if let Some(meta) = self.entries[i].as_ref()
                        && matches!(meta.kind, EntryKind::Timer)
                    {
                        // SAFETY: a Timer entry's arena slot holds a
                        // `TimerEntry<F>`, whose leading layout IS
                        // `TimerHeader` — the same cast the overrun reporter
                        // one screen up already relies on.
                        let header =
                            unsafe { &mut *(arena_ptr.add(meta.offset) as *mut TimerHeader) };
                        // Issue 1321 — on the TIMER'S clock, not the
                        // executor's. This line read
                        // `header.elapsed_us += delta_us`, which is wall
                        // microseconds: for a `Ros` timer that advanced a
                        // simulated-time counter by wall time, so a paused
                        // `/clock` no longer paused the timer — the one
                        // property a ROS-time timer has. Unbounded, unlike
                        // 1321's park bound, because it can fire a callback
                        // that no clock step earned.
                        super::arena::timer_advance_without_dispatch(header, delta_us);
                    }
                    // issue 0736 — a budget skip used to be a bare `continue`,
                    // which is the silent-drop shape 0737 gated one layer out:
                    // the entry is simply not dispatched and nothing anywhere
                    // says so, so a permanently starved tier is
                    // indistinguishable from an idle one. It took a hand-run
                    // 45 s image and a per-executor probe to learn that this
                    // line was skipping 96 % of one tier's spins.
                    // The rolling window catches a budget that THROTTLES; the
                    // streak below catches one that starves outright. issue
                    // 0736 needed both: the measured case skipped ~3 spins in
                    // 4 without ever reaching a streak, so the tier ran at a
                    // quarter of its declared rate in silence.
                    if let Some((skips, total)) = self
                        .sporadic_states
                        .get_mut(sc_idx)
                        .and_then(|st| st.as_mut())
                        .and_then(|st| st.take_budget_window())
                    {
                        nros_log::log_warn!(
                            nros_log::get_logger("nros"),
                            "sporadic budget throttled sched context {}: {} of the last {} dispatch opportunities were skipped for want of budget. The declared budget_us/period_us cannot sustain this tier's callbacks on this target.",
                            sc_idx,
                            skips,
                            total
                        );
                    }
                    if let Some(streak) = self
                        .sporadic_states
                        .get_mut(sc_idx)
                        .and_then(|st| st.as_mut())
                        .and_then(|st| st.note_budget_skip())
                    {
                        nros_log::log_warn!(
                            nros_log::get_logger("nros"),
                            "sporadic budget exhausted for {} consecutive spins (sched context {}): its callbacks are not being dispatched. Either the callback runtime exceeds the declared budget_us per period_us, or the declaration is unsatisfiable on this target.",
                            streak,
                            sc_idx
                        );
                    }
                    continue;
                }
                // Phase 110.E.b follow-up — per-callback runtime
                // accounting (replaces this cycle-level attribution)
                // is applied at dispatch time below via
                // `consume_dispatch_runtime_us`. We only update the
                // polled-path `SporadicState` (no_std fallback) here
                // because the atomic path now records actual
                // wall-clock per-callback runtime. The
                // `delta_us` over-attribution that previously hit the
                // atomic state was a worst-case bandwidth limiter;
                // per-callback measurement is strictly tighter.
                #[cfg(not(feature = "alloc"))]
                {
                    let _ = sc_idx; // polled-state path lives in
                    // `sporadic_states`; this branch is a no-op when
                    // the atomic path is enabled.
                }
            }
            // Phase 110.F — per-callback OS priority routing. Entries
            // bound to an SC with `os_pri > 0` dispatch onto a worker
            // thread the OS has elevated to that priority; the
            // cooperative path is skipped for those entries. Workers
            // are spawned lazily.
            #[cfg(all(
                feature = "alloc",
                feature = "rmw-cffi",
                feature = "scheduler-os-priority"
            ))]
            {
                let os_pri = self
                    .sched_contexts
                    .get(sc_idx)
                    .and_then(|s| s.as_ref())
                    .map(|sc| sc.os_pri)
                    .unwrap_or(0);
                if os_pri > 0
                    && let Some(apply_policy) = self.os_priority_apply_policy
                    && let Some(meta) = self.entries[i].as_ref()
                {
                    // Issue 1705 — a worker still holds this entry (its item is
                    // queued or its callback is running). Sending it again, or
                    // running it here, would put two threads in one
                    // `try_process`; it gets its next turn once the worker lets
                    // go.
                    let tag = &self.slot_tags[i];
                    if tag.set(super::types::SlotTag::WORKER_QUEUED)
                        & super::types::SlotTag::WORKER_QUEUED
                        != 0
                    {
                        continue;
                    }
                    let item = super::os_priority::WorkItem {
                        arena_base: arena_ptr as usize,
                        arena_offset: meta.offset,
                        try_process: meta.try_process,
                        delta_us,
                        // phase-8 — the worker runs the leaf on a DIFFERENT
                        // thread, so it has to carry the slot index with it;
                        // nothing on the far side can recover it from the
                        // arena address alone.
                        desc_idx: i as u8,
                        tag: tag as *const super::types::SlotTag as usize,
                    };
                    // phase-359 W10 — `try_dispatch` now reports whether the
                    // entry was actually handed to a worker. It can decline:
                    // the mailbox is bounded, the pool is capacity-limited, and
                    // a platform without a wake primitive hosts no workers at
                    // all. Previously the spawn was infallible (`.expect`) and
                    // an unbounded `mpsc` never refused, so this branch always
                    // `continue`d. Falling through to the cooperative path is
                    // the honest answer to a decline — the callback still runs,
                    // just without the OS priority guarantee, which is exactly
                    // what an entry got before this feature existed.
                    if self
                        .os_priority_pool
                        .try_dispatch(os_pri, apply_policy, item)
                    {
                        continue;
                    }
                    // Declined: no worker took it, so the bit set above is
                    // released and the entry runs cooperatively.
                    self.slot_tags[i].clear(super::types::SlotTag::WORKER_QUEUED);
                }
            }
            // Phase 110.G — TT window gate, orthogonal to class.
            // Skips dispatch when the SC has a TT window AND the
            // current monotonic time is outside it. Both gates apply
            // independently — a Sporadic SC with a TT window must
            // pass both.
            if self.major_frame_us > 0 {
                let sc_opt = self.sched_contexts.get(sc_idx).and_then(|s| s.as_ref());
                if let Some(sc) = sc_opt {
                    let off = sc.tt_window_offset_us.get().map(|nz| nz.get()).unwrap_or(0);
                    let dur = sc
                        .tt_window_duration_us
                        .get()
                        .map(|nz| nz.get())
                        .unwrap_or(0);
                    if dur > 0 {
                        // Compute current phase within the major
                        // frame using the accumulated `delta_us` clock
                        // (std-only precise; no_std uses `delta_us`
                        // approximation from spin cadence).
                        // phase-359 W4 — the shared read. The no_std arm used
                        // to be `now_us = delta_us`, i.e. a per-spin INTERVAL
                        // used as an absolute phase clock, which the comment
                        // above called an approximation. It is now the real
                        // clock when one is injected, and falls back to the old
                        // approximation only when none is.
                        let now_us = now_us_this_spin.unwrap_or(delta_us);
                        let phase = (now_us % self.major_frame_us as u64) as u32;
                        let in_window = if off + dur <= self.major_frame_us {
                            phase >= off && phase < off + dur
                        } else {
                            // Window wraps the major frame boundary.
                            let end = (off as u64 + dur as u64) % self.major_frame_us as u64;
                            phase >= off || (phase as u64) < end
                        };
                        if !in_window {
                            continue;
                        }
                    }
                }
            }
            let is_edf = matches!(sc_class, super::sched_context::SchedClass::Edf);
            let job = super::types::ActiveJob {
                sort_key: if is_edf { deadline_us } else { i as u32 },
                desc_idx: i as super::types::DescIdx,
            };
            if is_edf {
                let _ = edf.insert_into(bucket, job);
            } else {
                let _ = fifo.insert_into(bucket, job);
            }
        }

        // SAFETY: each `desc_idx` we pop was set above only when the
        // corresponding `entries[i]` slot was `Some`; no Executor
        // mutation happens between that scan and this dispatch.
        let mut dispatch_one = |meta: &CallbackMeta,
                                desc_idx: usize,
                                arena_ptr: *mut u8,
                                delta_us: u64,
                                result: &mut SpinOnceResult| {
            // Phase 141.B.2 — capture T1 at subscription dispatch
            // entry. Probe pairs it with the most recent T0 from
            // `nros_rmw_runtime_wake_cb` (std + alloc variants)
            // and pushes `T1 - T0` onto the ring buffer 141.C
            // drains. No-op when the probe feature is off or
            // no cycle reader is installed. Other entry kinds
            // (Service / Timer / GuardCondition) skip the probe
            // because the 141 acceptance is specifically
            // wake-to-subscription-dispatch latency.
            #[cfg(feature = "wake-latency-probe")]
            if matches!(meta.kind, EntryKind::Subscription) {
                super::wake_probe::on_dispatch();
            }
            let data_ptr = unsafe { arena_ptr.add(meta.offset) };
            // phase-8 — `desc_idx` is the entry slot index, threaded through so
            // the leaf hooks in `arena.rs` can name the callback they bracket.
            // `MAX_CALLBACK_SLOTS` is 64 (enforced by the `u64` ready-set
            // bitmask), so the `as u8` cannot truncate a live slot.
            // phase-463 W7 — time the dispatch and attribute its publishes
            // (host `profile-mode` only). ONE call site for both builds, so no
            // second `unsafe` block; the binding is the only change an RTOS
            // image sees, and its loadable bytes measured identical (phase-463
            // W5 I3c, Zephyr cpp/talker).
            #[cfg(feature = "profile-mode")]
            super::profile::dispatch_begin(arena_ptr as usize, desc_idx);
            let processed = unsafe { (meta.try_process)(data_ptr, delta_us, desc_idx as u8) };
            #[cfg(feature = "profile-mode")]
            super::profile::dispatch_end(matches!(processed, Ok(true)));
            match processed {
                Ok(true) => match meta.kind {
                    EntryKind::Subscription => result.subscriptions_processed += 1,
                    EntryKind::Service
                    | EntryKind::ServiceClient
                    | EntryKind::ActionServer
                    | EntryKind::ActionClient => result.services_handled += 1,
                    EntryKind::Timer => result.timers_fired += 1,
                    EntryKind::GuardCondition => {}
                },
                Ok(false) => {}
                Err(e) => {
                    // phase-427 — the first one is kept, the rest are counted.
                    // `stop_on_first_error` is what reads it; when nobody
                    // asked, the `Option` is a local the optimiser drops.
                    if first_error.is_none() {
                        *first_error = Some(e);
                    }
                    match meta.kind {
                        EntryKind::Subscription => result.subscription_errors += 1,
                        EntryKind::Service
                        | EntryKind::ServiceClient
                        | EntryKind::ActionServer
                        | EntryKind::ActionClient => result.service_errors += 1,
                        EntryKind::Timer | EntryKind::GuardCondition => {}
                    }
                }
            }
        };

        // Phase 110.E.b follow-up — per-callback runtime accounting
        // for Sporadic SCs. Wall-clock-measure each dispatch and
        // consume the elapsed microseconds from the bound SC's
        // atomic budget. This replaces the cycle-level over-
        // attribution that previously charged the FULL `delta_us`
        // against every Sporadic SC regardless of which entries
        // actually fired — accurate per-callback measurement is the
        // shape the design doc's per-callback runtime acceptance
        // calls out.
        //
        // phase-359 W10 — this was `feature = "std"`-gated, because it "needs a
        // `core::time::Instant`-equivalent monotonic clock ... until a
        // board-side monotonic-microsecond accessor lands". That accessor
        // landed: `now_us()` reads the platform monotonic counter on every
        // flavour. So per-callback sporadic accounting is no longer something
        // only a hosted build gets, and the no_std fallback to polled
        // `SporadicState` cycle deltas is no longer the only option on target.
        let consume_dispatch_runtime_us =
            |desc_idx: usize,
             elapsed_us: u32,
             sched_context_bindings: &[super::sched_context::SchedContextId],
             sched_contexts: &[Option<super::sched_context::SchedContext>],
             sporadic_states: &mut [Option<super::sched_context::SporadicState>],
             alive_slots: &mut [super::monitor::AliveSlot],
             #[cfg(feature = "alloc")] sporadic_atomic_states: &[Option<(
                portable_atomic_util::Arc<super::sched_context::AtomicSporadicState>,
                OpaqueTimerHandle,
            )>]| {
                let sc_idx = sched_context_bindings[desc_idx].0 as usize;
                // Alive supervision counts EVERY dispatch, before the class
                // gate below: a Fifo or time-triggered context can fall
                // silent exactly as a sporadic one can, and the rule that
                // notices must not be scoped to the class that happens to
                // carry a budget.
                if let Some(slot) = alive_slots.get_mut(sc_idx) {
                    slot.dispatches = slot.dispatches.wrapping_add(1);
                }
                let sc_class = sched_contexts
                    .get(sc_idx)
                    .and_then(|s| s.as_ref())
                    .map(|sc| sc.class)
                    .unwrap_or(super::sched_context::SchedClass::Fifo);
                if !matches!(sc_class, super::sched_context::SchedClass::Sporadic) {
                    return;
                }
                #[cfg(feature = "alloc")]
                if let Some((state, _)) =
                    sporadic_atomic_states.get(sc_idx).and_then(|s| s.as_ref())
                {
                    state.consume(elapsed_us);
                    // Unconditional, unlike the overrun record below: the
                    // budget is sized FROM this number, so it has to exist
                    // before the budget is right rather than only after it
                    // is wrong.
                    state.record_exec(elapsed_us);
                    // Phase 110.E.b — overrun detection. Cooperative
                    // single-thread can't preempt a runaway callback,
                    // so post-dispatch wall-clock comparison delivers
                    // the same observable signal as the design's
                    // oneshot-IRQ-and-cancel pattern, without needing
                    // a separate timer per SC. `budget_capacity_us` is
                    // the per-period budget the SC was sized against;
                    // any callback exceeding that has run past its
                    // bandwidth allotment.
                    if elapsed_us > state.budget_capacity_us {
                        state.record_overrun(elapsed_us - state.budget_capacity_us);
                    }
                }
                // issue 0736 — the POLLED state is charged unconditionally,
                // and it is the one that matters: `has_budget` prefers the
                // atomic state only when a refill timer was registered, which
                // no board or entry does. Before this, the alloc arm charged a
                // state nothing populated and the no_std arm discarded the
                // measurement outright (`let _ = (sc_idx, elapsed_us)`), so no
                // shipped image recorded per-callback runtime anywhere — while
                // the comment above claimed it did.
                if let Some(state) = sporadic_states.get_mut(sc_idx).and_then(|s| s.as_mut()) {
                    state.consume(elapsed_us);
                }
            };

        // W3b.5 — post-dispatch contract checks. `lat_active` gates the
        // per-dispatch publish-count snapshot (attribution of dispatch
        // elapsed time to monitored publishers whose counter advanced);
        // `dl_active` gates elapsed measurement for deadline actions. The third
        // term used to be `cfg!(feature = "std")` — "std measures anyway for
        // the sporadic path" — which made a COMPILE-TIME flavour stand in for
        // "is there a clock". It is now the runtime question it always was.
        let mon_table = self.monitor_table;
        let lat_active = mon_table.iter().any(|m| m.max_latency_ms > 0);
        let dl_active = self.sched_contexts.iter().flatten().any(|sc| {
            sc.deadline_us.is_some()
                && !matches!(
                    sc.deadline_action,
                    super::sched_context::DeadlineAction::Ignore
                )
        });
        let mon_clock = self.clock_us_fn;
        // phase10-B3 -- the route rule needs the clock and the publish-count
        // snapshot, and nothing else; without a clock it judges nothing.
        let route_on = mon_clock.is_some() && super::monitor::route_active(mon_table);
        // phase-503 -- a late supervised route reacts at completion too; not
        // before the monitors are armed (phase-474 I2), as after the park.
        let route_hook = self.reaction_hook.filter(|_| self.violations.counts.armed);
        let counts_on = lat_active || route_on;
        // phase-359 W4 — one predicate, no cfg block. `cfg!` is an expression,
        // so the flavour difference stays a value instead of a branch: std
        // measures unconditionally because the sporadic runtime accounting
        // below (itself std-only) consumes the result, which is exactly what
        // the comment above described and what the four-arm sites encoded.
        let measure_us = counts_on || dl_active || mon_clock.is_some();
        // phase-359 W4 — ONE hoisted µs reader for the per-dispatch latency
        // measurement below. Hoisted because `now_us()` takes `&mut self` and
        // the dispatch loop already holds borrows; the std arm copies the epoch
        // (a `Copy` `Instant`) so reading inside the loop touches no `self`.
        // This is the last cfg pair in the timing path: the two call sites it
        // serves each had FOUR arms (start + elapsed, per flavour).
        let read_us = move || mon_clock.map(|c| c()).unwrap_or(0);
        // Deferred deadline-miss violations (the loop body holds an
        // immutable borrow of `self.entries`, so the ring is fed after).
        let mut deadline_misses: heapless::Vec<
            super::monitor::Violation,
            { super::monitor::MAX_VIOLATIONS },
        > = heapless::Vec::new();
        // SCs whose remaining callbacks this cycle are skipped
        // (`DeadlineAction::Skip`) — bitmask over SC slots.
        let mut skipped_scs: u64 = 0;

        // For each priority bucket (Critical → Normal → BestEffort),
        // drain EDF first then FIFO so an EDF callback in this bucket
        // beats a FIFO peer at the same priority, but no lower-priority
        // entry runs while a higher-priority bucket has work pending.
        // Strict static priority across buckets; non-preemptive within
        // an in-flight callback (see Phase 110.D).
        for bucket in 0..NB {
            while let Some(job) = edf.pop_from(bucket) {
                let i = job.desc_idx as usize;
                let sc_idx = self.sched_context_bindings[i].0 as usize;
                if sc_idx < 64 && skipped_scs & (1u64 << sc_idx) != 0 {
                    continue; // W3b.5 DeadlineAction::Skip containment
                }
                if let Some(meta) = self.entries[i].as_ref()
                    && !Self::slot_held(self.slot_tags, i)
                {
                    let counts_before = snapshot_pub_counts(mon_table, counts_on);
                    // Measured only when a consumer wants it, matching the
                    // no_std arm this replaces — the std arm used to measure
                    // unconditionally.
                    let start_us = measure_us.then(read_us);
                    let took_before = result.subscriptions_processed;
                    Self::begin_dispatch(self.slot_tags, i);
                    dispatch_one(meta, i, arena_ptr, delta_us, &mut result);
                    let end_us = start_us.map(|_| read_us());
                    let elapsed_us: Option<u32> = start_us
                        .zip(end_us)
                        .map(|(t0, t1)| t1.saturating_sub(t0))
                        .map(|d| d.min(u32::MAX as u64) as u32);
                    // phase10-B3 -- a subscription dispatch takes its sample
                    // first, so the dispatch start is the take.
                    if route_on && let (Some(t0), Some(t1)) = (start_us, end_us) {
                        if result.subscriptions_processed != took_before {
                            super::monitor::route_take(mon_table, i, t0);
                        }
                        super::monitor::route_judge(
                            mon_table,
                            &counts_before,
                            t1,
                            |row, v, record, react| {
                                if react {
                                    call_route_reaction(route_hook, mon_table, row, &v);
                                }
                                if record {
                                    let _ = deadline_misses.push(v);
                                }
                            },
                        );
                    }
                    if let Some(elapsed_us) = elapsed_us {
                        consume_dispatch_runtime_us(
                            i,
                            elapsed_us,
                            &self.sched_context_bindings[..],
                            &self.sched_contexts[..],
                            &mut self.sporadic_states[..],
                            &mut self.alive_slots[..],
                            #[cfg(feature = "alloc")]
                            &self.sporadic_atomic_states[..],
                        );
                    }
                    if let Some(elapsed_us) = elapsed_us {
                        attribute_latency(mon_table, lat_active, &counts_before, elapsed_us);
                        check_deadline_miss(
                            self.sched_contexts.get(sc_idx).and_then(|s| s.as_ref()),
                            sc_idx,
                            elapsed_us,
                            &mut deadline_misses,
                            &mut skipped_scs,
                            self.fault_fn,
                            self.reaction_hook,
                        );
                    }
                    self.finish_dispatch(i);
                }
            }
            while let Some(job) = fifo.pop_from(bucket) {
                let i = job.desc_idx as usize;
                let sc_idx = self.sched_context_bindings[i].0 as usize;
                if sc_idx < 64 && skipped_scs & (1u64 << sc_idx) != 0 {
                    continue; // W3b.5 DeadlineAction::Skip containment
                }
                if let Some(meta) = self.entries[i].as_ref()
                    && !Self::slot_held(self.slot_tags, i)
                {
                    let counts_before = snapshot_pub_counts(mon_table, counts_on);
                    // Measured only when a consumer wants it, matching the
                    // no_std arm this replaces — the std arm used to measure
                    // unconditionally.
                    let start_us = measure_us.then(read_us);
                    let took_before = result.subscriptions_processed;
                    Self::begin_dispatch(self.slot_tags, i);
                    dispatch_one(meta, i, arena_ptr, delta_us, &mut result);
                    let end_us = start_us.map(|_| read_us());
                    let elapsed_us: Option<u32> = start_us
                        .zip(end_us)
                        .map(|(t0, t1)| t1.saturating_sub(t0))
                        .map(|d| d.min(u32::MAX as u64) as u32);
                    // phase10-B3 -- a subscription dispatch takes its sample
                    // first, so the dispatch start is the take.
                    if route_on && let (Some(t0), Some(t1)) = (start_us, end_us) {
                        if result.subscriptions_processed != took_before {
                            super::monitor::route_take(mon_table, i, t0);
                        }
                        super::monitor::route_judge(
                            mon_table,
                            &counts_before,
                            t1,
                            |row, v, record, react| {
                                if react {
                                    call_route_reaction(route_hook, mon_table, row, &v);
                                }
                                if record {
                                    let _ = deadline_misses.push(v);
                                }
                            },
                        );
                    }
                    if let Some(elapsed_us) = elapsed_us {
                        consume_dispatch_runtime_us(
                            i,
                            elapsed_us,
                            &self.sched_context_bindings[..],
                            &self.sched_contexts[..],
                            &mut self.sporadic_states[..],
                            &mut self.alive_slots[..],
                            #[cfg(feature = "alloc")]
                            &self.sporadic_atomic_states[..],
                        );
                    }
                    if let Some(elapsed_us) = elapsed_us {
                        attribute_latency(mon_table, lat_active, &counts_before, elapsed_us);
                        check_deadline_miss(
                            self.sched_contexts.get(sc_idx).and_then(|s| s.as_ref()),
                            sc_idx,
                            elapsed_us,
                            &mut deadline_misses,
                            &mut skipped_scs,
                            self.fault_fn,
                            self.reaction_hook,
                        );
                    }
                    self.finish_dispatch(i);
                }
            }
        }

        // W3b.5 — feed deferred deadline misses into the violation ring.
        for v in deadline_misses {
            self.violations.record(v);
        }

        // Issue #505 — same ring, same cycle. This runs AFTER dispatch,
        // unlike the windowed rate/age/latency rules at the top of the
        // spin: the activations it reports were dropped by the dispatch
        // that just happened, and a tier that is stalling should not have
        // to wait for the next spin to say so.
        self.check_timer_overruns();
        self.check_release_jitter_rule();
        self.check_stack_headroom_rule();
        self.check_alive_supervision();
        // phase-474 I7 -- the queued /diagnostics reports, after this spin's
        // dispatches and rules, when the next timer leaves room for them.
        self.flush_violation_reports();
        // phase-474 I1 -- the opt-in drain-and-report hook, after every rule of
        // this spin has had its say.
        self.violations.drain_and_report();

        // Process parameter services (outside the arena)
        #[cfg(feature = "param-store")]
        #[allow(unused_mut)] // only the services add to it
        let mut handled = 0usize;
        #[cfg(feature = "param-services")]
        if let Some(params) = &mut self.params {
            {
                let crate::param_store::ParamState {
                    server,
                    services,
                    buffers,
                    staged,
                    ..
                } = &mut **params;
                // phase-426 W3 -- one set per node; see the sibling site above,
                // including why nothing here can discard an error (1270/1271).
                if let Some(buffers) = buffers {
                    for set in services.iter_mut() {
                        let n = set.process(server, staged, buffers);
                        result.services_handled += n;
                        handled += n;
                    }
                }
            }
        }
        #[cfg(feature = "param-store")]
        self.note_param_services_ran(handled);

        // Process lifecycle services (outside the arena).
        //
        // SAFETY: `change_state` dispatches a user-supplied C callback through a
        // raw function pointer stored in `LifecyclePollingNodeCtx`. The caller
        // of `register_lifecycle_services` guarantees the callback/context pair
        // stays live for as long as the executor (see that method's docs).
        #[cfg(feature = "lifecycle-services")]
        if let Some(lc) = &mut self.lifecycle {
            if let Ok(n) = unsafe { lc.process() } {
                result.services_handled += n;
            }
        }

        // Phase 258 (Track 2, 2a) — executor-owned component tick pass.
        // Mirrors `ExecutorNodeRuntime::run_ticks`: after the transport +
        // callbacks have been pumped, drive each enrolled component's `tick`
        // (service-client/action poll, etc.). `exec_ctx` hands the component
        // the whole executor as a raw `*mut Executor` so its tick can
        // reborrow it (the same disjoint-field raw-ptr pattern run_ticks
        // uses). Index-iterate over `Copy` slots so no borrow of
        // `self.component_slots` is held while `tick` runs (which aliases
        // `self` through `exec_ctx`).
        let exec_ctx = self as *mut Executor as *mut core::ffi::c_void;
        let slot_count = self.component_slots.len();
        for i in 0..slot_count {
            let slot = self.component_slots[i];
            // SAFETY: `slot.state` is the leaked cell the matching `tick`
            // expects (enrolled via `enroll_component`); `exec_ctx` is a live
            // `*mut Executor` for `self`. The slot was copied out, so no
            // borrow of `component_slots` is outstanding during the call.
            unsafe {
                (slot.tick)(slot.state, exec_ctx);
            }
        }

        result
    }

    /// Drive I/O and dispatch callbacks forever — the body of an RTOS task.
    ///
    /// EXTENSION (RFC-0089). Not a rename of upstream's `spin`: the `!` is the
    /// point. A bare-metal entry has no shutdown source to return TO, and
    /// declaring that lets the compiler drop the epilogue and lets the caller
    /// write it as the last expression of a `-> !` task body with no
    /// `unreachable!()`. [`spin`](Self::spin) is the verb that can end, and it
    /// is upstream's.
    ///
    /// phase-427 — was `spin(Duration) -> !`, which squatted on rclrs's name
    /// with a different contract (a ported `executor.spin(SpinOptions)` line
    /// had to be renamed by hand, the one edit on the tutorial's happy path
    /// that no real difference forced). `spin_default()` went with it: it named
    /// a 50 ms poll interval and had zero call sites, and the interval is now
    /// [`SpinOptions::poll_interval`], defaulting to
    /// [`DEFAULT_SPIN_POLL_INTERVAL`](super::types::DEFAULT_SPIN_POLL_INTERVAL).
    ///
    /// **Envelope.** Only `poll_interval` and `stop_on_first_error` can mean
    /// anything here; `timeout`, `only_next` and `max_callbacks` are ENDING
    /// conditions and this verb does not end. Passing one is a caller error and
    /// says so at `LOG_ERR` on entry rather than being quietly dropped — a
    /// discarded ending condition is precisely the "compiles and differs" case
    /// RFC-0089 exists to make loud, and a `-> !` signature has no other
    /// channel. `stop_on_first_error` likewise cannot RETURN the error; it
    /// logs it and keeps spinning, because a task body has nowhere to put it.
    ///
    /// ```ignore
    /// let mut executor = Executor::open(&config)?;
    /// executor.register_subscription::<Int32, _>("/topic", |msg| { /* ... */ })?;
    /// executor.spin_forever(SpinOptions::default()); // never returns
    /// ```
    pub fn spin_forever(&mut self, opts: SpinOptions) -> ! {
        if opts.timeout.is_some() || opts.only_next || opts.max_callbacks.is_some() {
            nros_log::log_error!(
                nros_log::get_logger("nros"),
                "spin_forever: an ending condition (timeout / only_next / max_callbacks) \
                 was supplied to a verb that never returns and is being IGNORED \
                 -- use `Executor::spin` for a loop that can end"
            );
        }
        let poll = opts.poll_interval;
        let report_errors = opts.stop_on_first_error;
        loop {
            let mut first_error = None;
            self.spin_once_capturing(poll, &mut first_error);
            if report_errors && let Some(e) = first_error {
                nros_log::log_error!(
                    nros_log::get_logger("nros"),
                    "spin_forever: a callback failed ({:?}); `stop_on_first_error` cannot \
                     end a `-> !` loop, so this is a report, not a stop",
                    e
                );
            }
        }
    }

    /// Drive I/O and dispatch callbacks asynchronously.
    ///
    /// Runs forever, yielding between poll cycles so that other async tasks
    /// (e.g., [`Promise`](super::handles::Promise)) can make progress.
    ///
    /// Uses only `core::future` — no external async runtime dependency.
    ///
    /// ADOPT-BOUNDED against rclrs's
    /// `spin_async(SpinOptions) -> impl Future<Output = Vec<RclrsError>>`:
    ///
    /// * **It never returns and reports no errors** — the output is `!`, and it
    ///   takes no `SpinOptions`. To stop, `select` it against the thing you are
    ///   waiting for (pattern 1 below).
    /// * **It does not sleep on RMW I/O.** Each cycle is `spin_once(1 ms)` and then
    ///   a yield that wakes itself before returning `Pending`, so any runtime that
    ///   honours wakes polls it again at once. It is CPU-bound by construction;
    ///   the 1 ms `spin_once` budget is its only wait. Do not read `async` as idle.
    ///
    /// # Usage patterns
    ///
    /// ```ignore
    /// // Pattern 1: select with a promise (embassy-futures)
    /// use embassy_futures::select::{select, Either};
    /// let promise = client.call(&req)?;
    /// let Either::Second(reply) = select(executor.spin_async(), promise).await
    ///     else { unreachable!() };
    ///
    /// // Pattern 2: manual polling (no async runtime)
    /// let mut promise = client.call(&req)?;
    /// loop {
    ///     executor.spin_once(core::time::Duration::from_millis(10));
    ///     if let Ok(Some(r)) = promise.take() { break r; }
    /// }
    /// ```
    pub async fn spin_async(&mut self) -> ! {
        loop {
            self.spin_once(core::time::Duration::from_millis(1));
            core::future::poll_fn::<(), _>(|cx| {
                cx.waker().wake_by_ref();
                core::task::Poll::Pending
            })
            .await;
        }
    }

    /// Execute the work that is ready NOW and return — rclcpp's
    /// `Executor::spin_some(max_duration)`.
    ///
    /// ADOPT-BOUNDED (RFC-0089). Upstream's drain verb: collect what is ready,
    /// execute it, come back. It never waits for new work — that is
    /// [`spin_once`](Self::spin_once), which takes a budget and blocks on the
    /// transport until it expires.
    ///
    /// **Envelope, two ways it is weaker than rclcpp's:**
    ///
    /// * rclcpp collects the ready set ONCE and executes it. One
    ///   `spin_once(0)` here is already that whole set (RFC-0002 §3), so this
    ///   would be a single call — except a callback may enqueue work for
    ///   another entity, which rclcpp's `spin_all` re-collects and its
    ///   `spin_some` leaves for the next call. Ours re-drains until a pass does
    ///   NO work, which is `spin_all`'s answer, because the alternative is
    ///   work sitting in the arena until someone spins again. Bounded by
    ///   `max`, so a callback that feeds itself cannot wedge the caller.
    /// * `max` is checked BETWEEN passes, never inside one, so it is a floor on
    ///   when this returns and not a ceiling: a single long callback overruns
    ///   it. There is no preemption here to make it a ceiling.
    ///
    /// `max` of [`Duration::ZERO`](core::time::Duration::ZERO) means no limit —
    /// rclcpp's own default — and is the spelling a build with no clock must
    /// use. A non-zero `max` on a clockless build is an ERROR rather than an
    /// unbounded drain (issue 0709, the same rule as `spin`'s `timeout`).
    ///
    /// The `Result` is about that PRECONDITION and nothing else. A failed
    /// callback is counted in each pass's `SpinOnceResult` and does not end the
    /// drain, matching `spin`'s default (`SpinOptions::stop_on_first_error` is
    /// `false`); rclcpp's `spin_some` returns `void` and reports callback
    /// failures nowhere at all.
    ///
    /// # Example
    ///
    /// ```ignore
    /// // Drain the ready set, then get on with the caller's own work.
    /// executor.spin_some(core::time::Duration::ZERO)?;
    /// ```
    pub fn spin_some(&mut self, max: core::time::Duration) -> Result<(), NodeError> {
        let bounded = !max.is_zero();
        let start_us = self.now_us();
        if bounded && start_us.is_none() {
            nros_log::log_error!(
                nros_log::get_logger("nros"),
                "spin_some: a max duration was requested but this build has no clock \
                 - install one with `ExecutorConfig::clock_us`, or pass \
                 `Duration::ZERO` for rclcpp's unbounded default (issue 0709)"
            );
            return Err(NodeError::NotInitialized);
        }
        let max_us = max.as_micros().min(u64::MAX as u128) as u64;

        // No `enter_spin_loop` here, deliberately: `is_spinning` answers "a
        // blocking loop is running that a peer's `cancel()` has to reach", and
        // this verb returns on its own. Raising the flag for the length of a
        // drain would make a `cancel()` from another task look acted-upon when
        // nothing was waiting for it.
        loop {
            let result = self.spin_once(core::time::Duration::ZERO);
            if !result.any_work() {
                break;
            }
            if bounded
                && let (Some(start), Some(now)) = (start_us, self.now_us())
                && now.saturating_sub(start) >= max_us
            {
                break;
            }
        }
        Ok(())
    }

    // ========================================================================
    // spin_one_period (no_std)
    // ========================================================================

    /// Process one iteration and return remaining sleep time.
    ///
    /// This is `no_std` compatible — the caller is responsible for the actual
    /// delay using platform-specific sleep.
    ///
    /// # Arguments
    /// * `period_ms` - Target period in milliseconds
    /// * `elapsed_ms` - Time elapsed since last call (used for timer ticking)
    ///
    /// # Example
    ///
    /// ```ignore
    /// loop {
    ///     let r = executor.spin_one_period(10, elapsed_ms);
    ///     platform_sleep_ms(r.remaining_ms);
    /// }
    /// ```
    pub fn spin_one_period(&mut self, period_ms: u64, elapsed_ms: u64) -> SpinPeriodPollingResult {
        let result = self.spin_once(core::time::Duration::from_millis(elapsed_ms));
        SpinPeriodPollingResult {
            work: result,
            remaining_ms: period_ms.saturating_sub(elapsed_ms),
        }
    }
}

// ============================================================================
// Parameter services (cfg param-services)
// ============================================================================

#[cfg(feature = "param-services")]
impl<'s> Executor<'s> {
    /// Register the 6 ROS 2 parameter services for this node.
    ///
    /// Creates service servers for `get_parameters`, `set_parameters`,
    /// `set_parameters_atomically`, `list_parameters`, `describe_parameters`,
    /// and `get_parameter_types`.
    ///
    /// The service names follow the ROS 2 convention: `/{namespace}/{node_name}/{suffix}`.
    /// For the default namespace `/`, this becomes `/{node_name}/{suffix}` (e.g.
    /// `/sentinel/list_parameters`).
    ///
    /// Parameter services are stored outside the arena and don't consume
    /// callback slots.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let config = ExecutorConfig::from_env().node_name("talker");
    /// let mut executor = Executor::open(&config)?;
    /// executor.register_parameter_services()?;
    /// executor.declare_parameter("start_value", ParameterValue::Integer(0));
    /// ```
    pub fn register_parameter_services(&mut self) -> Result<(), NodeError> {
        // Issue 1706 -- six services over a store that does not exist would
        // answer every request with "not declared"; say what went wrong
        // instead (`report_parameter_store_refused` has named the size).
        if !self.ensure_parameter_store() {
            return Err(NodeError::Transport(TransportError::BadAlloc));
        }
        if let Some(params) = &mut self.params {
            params.requested = true;
        }
        // phase-426 W3 — with no node yet, RECORD the request and stop. The
        // reconcile's no-node fallback publishes under the executor's own
        // identity, and taking it here would pin node 0 to that name before the
        // node that IS node 0 has been built — which is the pre-W3 behaviour
        // this work item exists to remove. Every generated entry arrives in
        // exactly this state (`apply_param_services` runs ahead of the per-node
        // `register` calls, by design), so the fallback belongs on the spin
        // path, where "no node" has stopped being merely "not yet".
        if self.nodes.is_empty() {
            return Ok(());
        }
        self.reconcile_parameter_services()
    }

    /// phase-426 W3 — is there a node whose six services are not up yet?
    ///
    /// The cheap half of the reconcile, kept separate so `spin_once` can test
    /// it without carrying the reconcile's frame (see below).
    #[inline]
    pub(crate) fn parameter_services_pending(&self) -> bool {
        self.params.as_deref().is_some_and(|p| {
            p.requested
                && p.services.len() < self.nodes.len().max(1)
                // Issue 1268 — a failure that cannot change is not pending
                // work. This used to retry six `create_service` calls on EVERY
                // spin, for the life of an image that would never serve them,
                // and the result was discarded; 1271 made it say so once, which
                // left the retrying. An explicit
                // `register_parameter_services()` still tries, because that is
                // a caller asking rather than the spin guessing.
                && p.reconcile_failure.as_ref().is_none_or(|f| !f.permanent)
        })
    }

    /// Issue 1271 -- say, once, that the parameter services could not be
    /// created, instead of discarding the result on every spin.
    ///
    /// The spin keeps retrying (a node registered later, or a transport that
    /// comes up late, may still succeed); this only decides whether anyone is
    /// told. Cold and out of line: it formats, and `spin_once`'s frame must
    /// not carry that.
    #[cold]
    #[inline(never)]
    fn report_parameter_service_reconcile_failure(&mut self, e: NodeError) {
        let Some(params) = self.params.as_deref_mut() else {
            return;
        };
        if params.reconcile_failure_reported {
            return;
        }
        params.reconcile_failure_reported = true;
        // Issue 1268 — name the node and the service. "could not be created
        // ({:?})" named neither, so a reader could not tell a name too long for
        // one node from a backend that will serve none of the six.
        let (node_fqn, service, permanent) = match params.reconcile_failure.as_ref() {
            Some(f) => (f.node_fqn.as_str(), f.service, f.permanent),
            None => ("<unknown node>", "<unknown service>", false),
        };
        nros_log::log_error!(
            nros_log::get_logger("nros"),
            "parameter services could not be created for node {} at service {}: {:?}. \
             `ros2 param` cannot reach {} of this image's {} node(s). {} (issues 1271, 1268).",
            node_fqn,
            service,
            e,
            self.nodes.len().max(1) - params.services.len(),
            self.nodes.len().max(1),
            if permanent {
                "Not retrying: this failure cannot change without a rebuild."
            } else {
                "Retrying on every spin; logged once."
            }
        );
    }

    /// phase-426 W3 — publish one set of six under every node that does not
    /// have one yet.
    ///
    /// **Why a reconcile and not a registration.** `nros::main!` emits
    /// `apply_param_services` BEFORE its per-node `register` calls, by design:
    /// the store has to exist when each component cell captures it. So at the
    /// moment the request is made the node table is EMPTY and there is no FQN
    /// to publish under — registering there is how the six ended up pinned to
    /// the executor's own identity in the first place. The request is recorded
    /// and satisfied here, at the head of every spin, exactly as
    /// `reconcile_ros_time_source` does for `use_sim_time` and for the same
    /// reason.
    ///
    /// **An executor with no registered node still gets one set**, under its
    /// own `node_name`/`namespace` and keyed `NodeId::PRIMARY` — the identity
    /// [`declare_parameter`](Self::declare_parameter) writes to. That is the
    /// pre-W3 behaviour, preserved for the direct-API images that never call
    /// `node_builder` (`param-chatter-talker` is one), and it is keyed the same
    /// as the first node record, so a node registered later inherits the set
    /// rather than getting a second one under a different name.
    ///
    /// Cheap in the settled case: one length comparison — but the FRAME is not
    /// cheap, so it is `inline(never)` and the spin site tests
    /// [`parameter_services_pending`](Self::parameter_services_pending) first.
    /// Building one set used to materialise six `EmbeddedServiceServer`s by
    /// value (2 x `PARAM_SERVICE_BUFFER_SIZE` each, ~48 KiB at the 4096
    /// default) before they were boxed; inlined into `spin_once` that landed
    /// on every spin frame whether or not the branch was taken. Issue 1270
    /// took the buffers out of the set -- one pair per executor, allocated on
    /// the heap directly -- but the set still carries six backend handles and
    /// a name, so the frame stays out of `spin_once`. Issue 0756's rule one
    /// call up — a parameter-service frame does not fit an embedded thread
    /// stack, and `test_open_threaded_spawn_and_halt` died with a bare SIGSEGV
    /// the first time this was reachable from the spin path.
    #[inline(never)]
    pub(crate) fn reconcile_parameter_services(&mut self) -> Result<(), NodeError> {
        let Some(params) = self.params.as_deref() else {
            return Ok(());
        };
        if !params.requested {
            return Ok(());
        }
        // The nodes wanted, minus the ones already served. Collected first
        // because building a set borrows `self.session` mutably while
        // `self.nodes` / `self.params` are still borrowed by the scan.
        let want = self.nodes.len().max(1);
        if params.services.len() >= want {
            return Ok(());
        }
        let mut todo: heapless::Vec<
            (u8, heapless::String<64>, heapless::String<64>),
            { crate::param_sizing::MAX_SERVICE_SETS },
        > = heapless::Vec::new();
        for index in 0..want {
            let key = nros_params::NodeKey::new(index as u8);
            if params.services.iter().any(|set| set.param_node() == key) {
                continue;
            }
            let (name, namespace) = match self.nodes.get(index) {
                Some(record) => (record.name.clone(), record.namespace.clone()),
                // No node table entry: the executor's own implicit primary
                // identity, which is what `NodeId::PRIMARY` means.
                None => (self.node_name.clone(), self.namespace.clone()),
            };
            if todo.push((index as u8, name, namespace)).is_err() {
                return Err(NodeError::NodeTableFull);
            }
        }
        // Issue 1270 -- the ONE buffer pair every set is answered through,
        // allocated with the first set so an image that declares parameters
        // and serves none pays nothing for it. `params` is `Some` here: the
        // scan above returned early otherwise.
        // Issue 1812 -- a carved home hands its pair over with the state, so
        // this is reached only on the heap fallback.
        if let Some(params) = self.params.as_deref_mut()
            && params.buffers.is_none()
        {
            // Issue 1551 — an exhausted heap is an error this fn returns, not
            // an abort through libstd's OOM hook.
            #[cfg(feature = "alloc")]
            {
                params.buffers = Some(
                    crate::parameter_services::ParamServiceBuffers::try_with_capacity(
                        crate::parameter_services::param_service_buffer_bytes(),
                    )
                    .ok_or(NodeError::Transport(TransportError::BadAlloc))?,
                );
            }
            #[cfg(not(feature = "alloc"))]
            return Err(NodeError::Transport(TransportError::BadAlloc));
        }
        for (index, name, namespace) in todo {
            let servers = match self.build_parameter_service_set(
                nros_params::NodeKey::new(index),
                &name,
                &namespace,
            ) {
                Ok(servers) => servers,
                Err((e, service)) => {
                    // Issue 1268 — keep WHAT failed and WHERE, for the one log
                    // line, and decide once whether retrying could ever help.
                    // `Unsupported` from the transport is a property of the
                    // build (the backend has no descriptor for the
                    // `rcl_interfaces` types), so a later spin asks the same
                    // question and gets the same answer.
                    let permanent = matches!(e, NodeError::Transport(TransportError::Unsupported));
                    if let Some(params) = self.params.as_deref_mut() {
                        let mut node_fqn = heapless::String::<256>::new();
                        if let Ok(fqn) = crate::names::fully_qualified_name(&name, &namespace) {
                            let _ = node_fqn.push_str(fqn.as_str());
                        }
                        params.reconcile_failure =
                            Some(crate::parameter_services::ParamServiceReconcileFailure {
                                node_fqn,
                                service,
                                permanent,
                            });
                    }
                    return Err(e);
                }
            };
            // Issue 1812 -- the set lives INLINE in the (carved) state now, not
            // in a box of its own.
            // Issue 0745 — PRESERVE an already-initialized store: launch-param
            // seeding may have run before any node existed (services can't be
            // registered that early). Overwriting here would wipe the seeds.
            match &mut self.params {
                Some(params) => params
                    .services
                    .push(servers)
                    .map_err(|_| NodeError::NodeTableFull)?,
                None => {
                    // Issue 0756 — see new_param_state: never build a ParamState
                    // by value, it does not fit an embedded thread stack.
                    // Issue 1706 -- the store is fallible; the refusal is
                    // reported once by `ensure_parameter_store`'s spelling.
                    if self.param_store_refused {
                        return Err(NodeError::Transport(TransportError::BadAlloc));
                    }
                    let Some(mut state) = Self::new_param_state(
                        core::mem::take(&mut self.param_slots),
                        core::mem::take(&mut self.param_home),
                    ) else {
                        self.param_store_refused = true;
                        report_parameter_store_refused();
                        return Err(NodeError::Transport(TransportError::BadAlloc));
                    };
                    state.requested = true;
                    let _ = state.services.push(servers);
                    self.params = Some(state);
                }
            }
            // phase-430 W2 — "declare `use_sim_time` on EVERY node, as rclcpp
            // does", said where the nodes finally exist. This is the only place
            // that knows the full set: `ensure_parameter_store` runs before any
            // node record does, so it can only seed the implicit PRIMARY, and
            // the further nodes an image composes onto one executor arrive
            // later. Seeding as each set of six goes up keeps the two in step —
            // the parameter is declared on exactly the nodes a
            // `ros2 param set <node> use_sim_time true` can reach.
            //
            // Idempotent by construction: `declare` refuses a name the node
            // already holds and the placeholder flag is only raised on
            // acceptance, so re-seeding PRIMARY here neither duplicates the
            // entry nor re-marks an application's own declaration as ours.
            self.seed_use_sim_time_default(super::node_record::NodeId::from_raw(index));
        }
        // Issue 1271 -- every node is served now, so a later failure (a node
        // registered after this one) is news again and earns its own line.
        if let Some(params) = self.params.as_deref_mut() {
            params.reconcile_failure_reported = false;
            // Issue 1268 -- and drop the record with it, so a later failure is
            // reported against the node it actually happened on.
            params.reconcile_failure = None;
        }
        Ok(())
    }

    /// phase-426 W3 — create the six service servers for ONE node.
    ///
    /// Split out of [`register_parameter_services`](Self::register_parameter_services)
    /// because there are now N of these per image rather than one, and because
    /// the six `create_param_srv` call sites are what
    /// `check-infra-queryable-counts` reads to hold `PARAM_SERVICE_QUERYABLES`
    /// to the number of queryables a set actually claims.
    #[inline(never)]
    fn build_parameter_service_set(
        &mut self,
        node: nros_params::NodeKey,
        node_name: &str,
        namespace: &str,
    ) -> Result<crate::parameter_services::ParameterServiceServers, (NodeError, &'static str)> {
        use crate::parameter_services::{
            DescribeParameters, GetParameterTypes, GetParameters, ListParameters,
            ParamServiceHandle as PSrv, ParameterServiceServers, SetParameters,
            SetParametersAtomically,
        };
        use nros_core::RosService;

        // The node FQN, from the one implementation. This was the third
        // hand-rolled copy of the same join (`crate::names::fully_qualified_name`
        // is the first, `Node::fully_qualified_name` was the second) — and the
        // three did not agree: this one absolutised a bare namespace, that one
        // did not. A join with three spellings has no answer to "what does the
        // tree do with `my_ns`".
        let node_fqn = crate::names::fully_qualified_name(node_name, namespace)
            .map_err(|()| (NodeError::NameTooLong, "get_parameters"))?;
        // The service names below still take the two halves separately.
        let ns: &str = namespace;
        let nn: &str = node_name;

        /// Build a service name like `{node_fqn}/{suffix}` and create the server handle.
        ///
        /// Issue 1268 — the error carries the SUFFIX, so a failure can name the
        /// service a tool would have called instead of "one of six".
        fn create_param_srv<Svc>(
            session: &mut session::ConcreteSession,
            domain_id: u32,
            node_fqn: &str,
            namespace: &str,
            node_name: &str,
            suffix: &'static str,
        ) -> Result<session::RmwServiceServer, (NodeError, &'static str)>
        where
            Svc: RosService,
            Svc::Request: crate::rmw_type_registry::MessageForRmw,
            Svc::Reply: crate::rmw_type_registry::MessageForRmw,
        {
            // Issue 1268 — REGISTER THE TYPES FIRST, exactly as a typed user
            // service does (`register_service_sized`). A backend that keys
            // topics on a registered type descriptor — Cyclone does — fails
            // `create_service` with `Unsupported` for a type it has never been
            // told about, and nothing else in the image registers the
            // `rcl_interfaces` service types: the generated typesupport of a
            // downstream covers ITS OWN message packages, and the backend bakes
            // in only `ParticipantEntitiesInfo` for the graph. So the six
            // parameter services failed on every spin while the image's own
            // services worked, which is what made the cause look like "no
            // service support" for two phases (the issue-0745 comment).
            //
            // A no-op on backends that need no descriptors (zenoh, xrce), which
            // is why zenoh served this same image all along.
            let register = |e: NodeError| (e, suffix);
            crate::rmw_type_registry::register_type::<Svc::Request>().map_err(register)?;
            crate::rmw_type_registry::register_type::<Svc::Reply>().map_err(register)?;
            let mut name = heapless::String::<256>::new();
            name.push_str(node_fqn)
                .map_err(|_| (NodeError::NameTooLong, suffix))?;
            name.push_str("/")
                .map_err(|_| (NodeError::NameTooLong, suffix))?;
            name.push_str(suffix)
                .map_err(|_| (NodeError::NameTooLong, suffix))?;
            let mut info = ServiceInfo::new(&name, Svc::SERVICE_NAME, Svc::SERVICE_HASH)
                // issue 0824 follow-up — `domain_id` is a PARAMETER, not `self.domain_id`:
                // this is a nested `fn`, not a method, so `self` is not in scope and
                // the original spelling was E0434. It only fails under feature sets
                // that compile this arm, which is why `--all-features` caught it and
                // the narrower lanes did not.
                .with_domain(domain_id)
                .with_namespace(namespace);
            if !node_name.is_empty() {
                info = info.with_node_name(node_name);
            }
            // issue 0793 — the parameter services get the PARAMETER profile
            // (`rmw_qos_profile_parameters`: KEEP_LAST(1000), reliable,
            // volatile), not the generic services one. `QOS_PROFILE_PARAMETERS`
            // existed with the right depth and had no caller, so every parameter
            // server ran on a depth-10 queue while ROS 2 gives them 1000 — which
            // matters exactly when a tool sets many parameters at once, the case
            // the deep queue is for.
            session
                .create_service(&info, QoSProfile::parameter_services_default())
                .map_err(|e| (NodeError::Transport(e), suffix))
        }

        let get_handle = create_param_srv::<GetParameters>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "get_parameters",
        )?;
        let set_handle = create_param_srv::<SetParameters>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "set_parameters",
        )?;
        let set_atomic_handle = create_param_srv::<SetParametersAtomically>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "set_parameters_atomically",
        )?;
        let list_handle = create_param_srv::<ListParameters>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "list_parameters",
        )?;
        let desc_handle = create_param_srv::<DescribeParameters>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "describe_parameters",
        )?;
        let types_handle = create_param_srv::<GetParameterTypes>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "get_parameter_types",
        )?;

        Ok(ParameterServiceServers::new(
            // phase-426 W3 — the set carries the node whose parameters it
            // serves, so a handler can never read the store without saying
            // whose parameters it means.
            node,
            // Issue 1271 -- carried so a dropped request is reported against
            // the service a tool actually called.
            node_fqn,
            // Issue 1270 -- handles only. The buffers are the executor's one
            // shared pair (`ParamState::buffers`), not six per node.
            PSrv::<GetParameters>::new(get_handle),
            PSrv::<SetParameters>::new(set_handle),
            PSrv::<SetParametersAtomically>::new(set_atomic_handle),
            PSrv::<ListParameters>::new(list_handle),
            PSrv::<DescribeParameters>::new(desc_handle),
            PSrv::<GetParameterTypes>::new(types_handle),
        ))
    }

    /// phase-426 W3 — the node FQNs this executor publishes parameter services
    /// under, in registration order.
    ///
    /// The acceptance question for W3 ("does a two-node image expose both
    /// FQNs?") answered without a wire: the six services are created from
    /// exactly this list, so asserting it asserts what `ros2 param list` will
    /// enumerate. The wire assertion is W6.
    pub fn parameter_service_node_names(
        &self,
    ) -> heapless::Vec<crate::names::ResolvedName, { crate::param_sizing::MAX_SERVICE_SETS }> {
        let mut out = heapless::Vec::new();
        let Some(params) = self.params.as_deref() else {
            return out;
        };
        for set in params.services.iter() {
            let index = set.param_node().raw() as usize;
            let (name, namespace) = match self.nodes.get(index) {
                Some(record) => (record.name.as_str(), record.namespace.as_str()),
                None => (self.node_name.as_str(), self.namespace.as_str()),
            };
            if let Ok(fqn) = crate::names::fully_qualified_name(name, namespace) {
                let _ = out.push(fqn);
            }
        }
        out
    }

    // phase-359 W10 / issue 0080 — `enable_parameter_persistence{,_with}` are
    // GONE with the seam they attached. Issue 0080 ruled on-device parameter
    // persistence a non-goal in July and listed both by name; nothing in the
    // tree ever called them, and the only backend that could be passed
    // (`FileParamStore`) is deleted. Runtime get/set/describe stay — it is the
    // PERSISTENCE half that was dropped.
}

// ============================================================================
// Lifecycle services (cfg lifecycle-services)
// ============================================================================

#[cfg(feature = "lifecycle-services")]
impl<'s> Executor<'s> {
    /// Register the five REP-2002 lifecycle services on this executor.
    ///
    /// After this call, `ros2 lifecycle set|get|list|nodes` can drive the
    /// stored [`LifecyclePollingNodeCtx`](crate::lifecycle::LifecyclePollingNodeCtx)
    /// through the node's lifecycle. The state machine is created fresh
    /// (starting in `Unconfigured`); callers register their transition
    /// callbacks via [`Executor::lifecycle_state_machine_mut`].
    ///
    /// # Safety
    /// Registered callbacks on the state machine are C FFI function pointers.
    /// The caller must keep the callback code and any context it captures
    /// valid for as long as the executor processes services.
    pub fn register_lifecycle_services(&mut self) -> Result<(), NodeError> {
        use crate::{
            lifecycle::LifecyclePollingNodeCtx,
            lifecycle_services::{
                ChangeState, GetAvailableStates, GetAvailableTransitions, GetState,
                LIFECYCLE_SERVICE_BUFFER_SIZE, LifecycleRuntimeState, LifecycleServiceServers,
            },
        };
        use nros_core::RosService;

        type LcSrv<Svc> = super::handles::EmbeddedServiceServer<
            Svc,
            LIFECYCLE_SERVICE_BUFFER_SIZE,
            LIFECYCLE_SERVICE_BUFFER_SIZE,
        >;

        // Build the node FQN from namespace + node_name (same convention as
        // register_parameter_services).
        let mut node_fqn = heapless::String::<256>::new();
        let ns: &str = &self.namespace;
        let nn: &str = &self.node_name;
        if ns.is_empty() || ns == "/" {
            node_fqn.push_str("/").map_err(|_| NodeError::NameTooLong)?;
            node_fqn.push_str(nn).map_err(|_| NodeError::NameTooLong)?;
        } else {
            node_fqn.push_str("/").map_err(|_| NodeError::NameTooLong)?;
            node_fqn
                .push_str(ns.trim_matches('/'))
                .map_err(|_| NodeError::NameTooLong)?;
            node_fqn.push_str("/").map_err(|_| NodeError::NameTooLong)?;
            node_fqn.push_str(nn).map_err(|_| NodeError::NameTooLong)?;
        }

        fn create_lc_srv<Svc>(
            session: &mut session::ConcreteSession,
            domain_id: u32,
            node_fqn: &str,
            namespace: &str,
            node_name: &str,
            suffix: &str,
        ) -> Result<session::RmwServiceServer, NodeError>
        where
            Svc: RosService,
            Svc::Request: crate::rmw_type_registry::MessageForRmw,
            Svc::Reply: crate::rmw_type_registry::MessageForRmw,
        {
            // Issue 1293 — register both halves first, as `create_param_srv`
            // does since issue 1268: Cyclone creates a topic only for a type it
            // holds a descriptor for. Three of the five request types are
            // EMPTY, and an empty schema had no descriptor until codegen gave
            // it rosidl's `structure_needs_at_least_one_member` byte. A no-op
            // on backends that need no descriptors (zenoh, xrce).
            crate::rmw_type_registry::register_type::<Svc::Request>()?;
            crate::rmw_type_registry::register_type::<Svc::Reply>()?;
            let mut name = heapless::String::<256>::new();
            name.push_str(node_fqn)
                .map_err(|_| NodeError::NameTooLong)?;
            name.push_str("/").map_err(|_| NodeError::NameTooLong)?;
            name.push_str(suffix).map_err(|_| NodeError::NameTooLong)?;
            let mut info = ServiceInfo::new(&name, Svc::SERVICE_NAME, Svc::SERVICE_HASH)
                .with_domain(domain_id)
                .with_namespace(namespace);
            if !node_name.is_empty() {
                info = info.with_node_name(node_name);
            }
            session
                .create_service(&info, QoSProfile::services_default())
                .map_err(NodeError::Transport)
        }

        /// Issue 1587 — the ONE publisher the REP-2002 family claims,
        /// `~/transition_event`. Shaped like `create_lc_srv` beside it both
        /// because the naming rule is the same (node FQN + suffix) and
        /// because `check-infra-queryable-counts` counts the creation sites
        /// to hold `LIFECYCLE_SERVICE_PUBLISHERS` to them, exactly as it
        /// already holds `LIFECYCLE_SERVICE_QUERYABLES` to the five above.
        fn create_lc_pub<Msg: crate::rmw_type_registry::MessageForRmw>(
            session: &mut session::ConcreteSession,
            domain_id: u32,
            node_fqn: &str,
            namespace: &str,
            node_name: &str,
            suffix: &str,
            qos: QoSProfile,
        ) -> Result<session::RmwPublisher, NodeError> {
            // Issue 1293 — same rule as `create_lc_srv`: Cyclone needs the
            // `TransitionEvent` descriptor before it can create the topic.
            crate::rmw_type_registry::register_type::<Msg>()?;
            let mut name = heapless::String::<256>::new();
            name.push_str(node_fqn)
                .map_err(|_| NodeError::NameTooLong)?;
            name.push_str("/").map_err(|_| NodeError::NameTooLong)?;
            name.push_str(suffix).map_err(|_| NodeError::NameTooLong)?;
            let mut info = TopicInfo::new(
                &name,
                <Msg as nros_core::RosMessage>::TYPE_NAME,
                Msg::TYPE_HASH,
            )
            .with_domain(domain_id)
            .with_namespace(namespace);
            if !node_name.is_empty() {
                info = info.with_node_name(node_name);
            }
            session
                .create_publisher(&info, qos)
                .map_err(NodeError::Transport)
        }

        let cs_handle = create_lc_srv::<ChangeState>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "change_state",
        )?;
        let gs_handle = create_lc_srv::<GetState>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "get_state",
        )?;
        let gas_handle = create_lc_srv::<GetAvailableStates>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "get_available_states",
        )?;
        let gat_handle = create_lc_srv::<GetAvailableTransitions>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "get_available_transitions",
        )?;
        let gtg_handle = create_lc_srv::<GetAvailableTransitions>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            "get_transition_graph",
        )?;

        // Issue 1587 — REP-2002's communication interface is the five
        // services PLUS this. VOLATILE, so it costs a publisher slot and a
        // liveliness token and NO queryable; see
        // `LIFECYCLE_SERVICE_PUBLISHERS` for the measurement that settled it.
        let te_handle = create_lc_pub::<nros_lifecycle_msgs::msg::TransitionEvent>(
            &mut self.session,
            self.domain_id,
            &node_fqn,
            ns,
            nn,
            crate::lifecycle_services::TRANSITION_EVENT_SUFFIX,
            crate::lifecycle_services::transition_event_qos(),
        )?;

        let servers = LifecycleServiceServers::new(
            LcSrv::<ChangeState> {
                handle: cs_handle,
                req_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                reply_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                _phantom: core::marker::PhantomData,
            },
            LcSrv::<GetState> {
                handle: gs_handle,
                req_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                reply_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                _phantom: core::marker::PhantomData,
            },
            LcSrv::<GetAvailableStates> {
                handle: gas_handle,
                req_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                reply_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                _phantom: core::marker::PhantomData,
            },
            LcSrv::<GetAvailableTransitions> {
                handle: gat_handle,
                req_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                reply_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                _phantom: core::marker::PhantomData,
            },
            LcSrv::<GetAvailableTransitions> {
                handle: gtg_handle,
                req_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                reply_buffer: [0u8; LIFECYCLE_SERVICE_BUFFER_SIZE],
                _phantom: core::marker::PhantomData,
            },
        );

        self.lifecycle = Some(alloc::boxed::Box::new(LifecycleRuntimeState {
            state_machine: LifecyclePollingNodeCtx::new(),
            services: alloc::boxed::Box::new(servers),
            transition_event: te_handle,
        }));

        Ok(())
    }

    /// The `~/transition_event` publisher, for the tests that assert what
    /// reached the wire. Not a public capability: the executor announces, and
    /// a second publisher on the same topic would be a second source of truth.
    /// Its only callers are the mock-session tests, which a `rmw-cffi` build
    /// does not compile.
    #[cfg(all(test, not(feature = "rmw-cffi")))]
    pub(crate) fn lifecycle_transition_event_publisher(&self) -> Option<&session::RmwPublisher> {
        self.lifecycle.as_ref().map(|lc| &lc.transition_event)
    }

    /// Mutable access to the lifecycle state machine, if registered.
    ///
    /// Used to register transition callbacks before spinning and to read the
    /// current state from application code.
    pub fn lifecycle_state_machine_mut(
        &mut self,
    ) -> Option<&mut crate::lifecycle::LifecyclePollingNodeCtx> {
        self.lifecycle.as_mut().map(|lc| &mut lc.state_machine)
    }

    /// Immutable access to the lifecycle state machine, if registered.
    pub fn lifecycle_state_machine(&self) -> Option<&crate::lifecycle::LifecyclePollingNodeCtx> {
        self.lifecycle.as_ref().map(|lc| &lc.state_machine)
    }

    /// Register a safe lifecycle node (issue 0335 / phase-317).
    ///
    /// Binds the five REP-2002 lifecycle services and wires each transition to
    /// the [`LifecycleCallbacks`](crate::lifecycle::LifecycleCallbacks) trait
    /// impl — the safe Rust counterpart to the C++ `nros::LifecycleNode`. No
    /// `unsafe` in user code; alloc-free (monomorphized trampolines).
    ///
    /// `node` must outlive this executor's lifecycle registration: the context
    /// pointer stored here is dereferenced on every transition until the
    /// executor is finalized. The executor spins single-threaded, so the
    /// `&mut node` reconstituted inside a callback is never aliased.
    pub fn register_lifecycle_node<T: crate::lifecycle::LifecycleCallbacks>(
        &mut self,
        node: &mut T,
    ) -> Result<(), NodeError> {
        use crate::lifecycle::{LifecycleCallbackSlot as Slot, trampolines};

        self.register_lifecycle_services()?;
        let sm = self
            .lifecycle_state_machine_mut()
            .ok_or(NodeError::NotInitialized)?;
        sm.set_context(node as *mut T as *mut core::ffi::c_void);
        sm.register(Slot::Configure, Some(trampolines::on_configure::<T>));
        sm.register(Slot::Activate, Some(trampolines::on_activate::<T>));
        sm.register(Slot::Deactivate, Some(trampolines::on_deactivate::<T>));
        sm.register(Slot::Cleanup, Some(trampolines::on_cleanup::<T>));
        sm.register(Slot::Shutdown, Some(trampolines::on_shutdown::<T>));
        sm.register(Slot::Error, Some(trampolines::on_error::<T>));
        Ok(())
    }
}

// ============================================================================
// phase-446 W6 -- the contract's declared parameters (cfg param-services)
// ============================================================================

#[cfg(feature = "param-store")]
impl<'s> Executor<'s> {
    /// Hand the executor the parameters each node's contract declares.
    ///
    /// The entry calls this before any node registers. It only RECORDS the
    /// table: the check runs where an application declares a parameter (the
    /// `nros` node runtime), not in [`Self::declare_parameter_on`], because
    /// that funnel also carries the launch seed, whose value type is still
    /// inferred from text and was already held to the contract by the
    /// resolver.
    pub fn set_declared_params(&mut self, declared: nros_params::DeclaredParams) {
        self.declared_params = declared;
    }

    /// The table [`Self::set_declared_params`] recorded (empty by default).
    pub fn declared_params(&self) -> nros_params::DeclaredParams {
        self.declared_params
    }
}

// ============================================================================
// Parameter declaration API (cfg param-services)
// ============================================================================

#[cfg(feature = "param-store")]
impl<'s> Executor<'s> {
    /// phase-461 W6 — build the parameter STORE and register no service.
    ///
    /// What an image declaring the `params` axis (and not `param_services`)
    /// calls ahead of its nodes: launch seeds and `declare_parameter` land in
    /// the store, and `ros2 param` reaches none of it, because no queryable
    /// was created. The primary node's `use_sim_time` placeholder is seeded
    /// as it is for a served store; nothing can SET it here, which is the
    /// axis' stated limit.
    ///
    /// Idempotent, and a later [`Self::register_parameter_services`] keeps
    /// this store and adds the six services on top of it.
    pub fn register_parameter_store(&mut self) -> Result<(), NodeError> {
        if self.ensure_parameter_store() {
            Ok(())
        } else {
            Err(NodeError::Transport(TransportError::BadAlloc))
        }
    }

    /// Issue 0745 — lazily create the parameter STORE (no services yet).
    /// Launch-param seeding runs before any node is constructed; the six
    /// service servers attach later in `register_parameter_services`,
    /// which preserves this store.
    /// `true` when the store exists afterwards. `false` only when the platform
    /// heap refused its allocation (issue 1706), which is reported once, here,
    /// with the size it asked for.
    fn ensure_parameter_store(&mut self) -> bool {
        if self.params.is_none() {
            if self.param_store_refused {
                return false;
            }
            let Some(state) = Self::new_param_state(
                core::mem::take(&mut self.param_slots),
                core::mem::take(&mut self.param_home),
            ) else {
                self.param_store_refused = true;
                report_parameter_store_refused();
                return false;
            };
            self.params = Some(state);
            // phase-430 W2 — the executor's implicit PRIMARY node exists the
            // moment the store does, whether or not a node record has been
            // built yet, so it is seeded here. The other node keys are seeded
            // in `reconcile_parameter_services`, as each one's set of six goes
            // up.
            self.seed_use_sim_time_default(super::node_record::NodeId::PRIMARY);
        }
        true
    }

    /// phase-430 W2 — declare `use_sim_time = false`, as rclcpp does on EVERY
    /// node.
    ///
    /// Upstream auto-declares the parameter in `rclcpp::Node`'s constructor, so
    /// `ros2 param list` shows it and `ros2 param set <node> use_sim_time true`
    /// reaches a node whose author never wrote a line about simulated time.
    /// Ours honoured the parameter only if the APP had declared it: the store
    /// refuses an undeclared set (`allow_undeclared` is false), so the runtime
    /// switch worked on exactly the nodes that least needed it.
    ///
    /// The seed is a PLACEHOLDER, tracked by `ParamState::sim_time_seeded`,
    /// because the store refuses a duplicate name: without that flag, seeding
    /// here would turn an application's own `declare_parameter("use_sim_time",
    /// Bool(true))` into a refusal and the auto-declared default would silently
    /// beat the app. `yield_seeded_use_sim_time` steps the placeholder aside
    /// for the first real declaration, whatever value or descriptor it carries.
    ///
    /// PER NODE, both here and in the flag. phase-426 keyed the store and the
    /// six services by node, so "every node" is now literally expressible and
    /// this is where it is said: `ensure_parameter_store` seeds the executor's
    /// implicit PRIMARY, and `reconcile_parameter_services` seeds each further
    /// node key as its set of six goes up — which is exactly the set of nodes a
    /// `ros2 param set <node> use_sim_time true` can reach.
    ///
    /// It deliberately does NOT go through `note_reserved_parameter`, so
    /// `sim_time_stated` stays false: an auto-declared default is not a
    /// STATEMENT by anyone. Recording it as one would make every executor with
    /// parameter services write `set_active(false)` onto a PROCESS-GLOBAL gate
    /// on its first spin — switching off a simulated clock another executor in
    /// the same image installed, which is exactly the collision
    /// `sim_time_stated` was added for (issue 1104). That property is per node
    /// too: seeding N nodes must still be N statements by nobody.
    ///
    /// Gated on `sim-time` as well as `param-services`: an image that cannot
    /// act on the parameter should not advertise it, because a settable knob
    /// that does nothing is worse than an absent one.
    fn seed_use_sim_time_default(&mut self, node: super::node_record::NodeId) {
        #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
        if let Some(params) = self.params.as_deref_mut()
            && let Some(seeded) = params.sim_time_seeded.get_mut(node.index())
            && params.server.declare(
                node.into(),
                crate::time_source::USE_SIM_TIME_PARAM,
                nros_params::ParameterValue::Bool(false),
            )
        {
            *seeded = true;
        }
        let _ = node;
    }

    /// phase-430 W2 — step the seeded `use_sim_time` aside for an application
    /// that declares it itself on `node`. Returns whether it did.
    ///
    /// The app's declaration must WIN — its own default, its own descriptor —
    /// and a declaration is refused when the name is already taken, so the
    /// placeholder has to leave before the real one arrives. Only ever the
    /// placeholder: once a real declaration has landed the flag is false and a
    /// second declaration is refused exactly as it was before W2.
    ///
    /// Only ever THIS node's placeholder, too: an app that names
    /// `use_sim_time` on one node of an image has said nothing about the
    /// others, and their seeds stay placeholders for whoever declares next.
    fn yield_seeded_use_sim_time(&mut self, node: super::node_record::NodeId, name: &str) -> bool {
        #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
        if name == crate::time_source::USE_SIM_TIME_PARAM
            && let Some(params) = self.params.as_deref_mut()
            && let Some(seeded) = params.sim_time_seeded.get_mut(node.index())
            && core::mem::replace(seeded, false)
        {
            return params.server.remove(node.into(), name);
        }
        let _ = (node, name);
        false
    }

    /// The HEAP home for the parameter slot table, used only when the
    /// executor's backing carved none.
    ///
    /// phase-382 W2' — `ParameterServer` no longer OWNS its slots; it borrows
    /// a caller-placed [`nros_params::ParameterTable`]. phase-382 W3' carves
    /// that table out of the caller's executor backing whenever the build
    /// KNOWS the image builds a store ([`ExecutorSizing::params`](super::storage::ExecutorSizing::params), from
    /// `nros_params::IMPLIED_STORE_SLOTS`); this function is what remains for a
    /// store the build could not see — one reached only from application
    /// code — and for an executor opened with a sizing that carves none. It
    /// makes a single heap allocation, leaked, one per such executor that
    /// touches parameters. The leak is what buys the `'static`
    /// the borrow needs without making `ParamState` self-referential (a
    /// `ParamState` that owned the storage AND a server borrowing it is not
    /// expressible), and it is bounded — `ensure_parameter_store` runs this
    /// at most once per executor.
    ///
    /// Issue 0756 — the placement dance is still here because the SIZE is
    /// still here; it only moved off `ParameterServer` and onto
    /// `ParameterStorage`. That storage is 285,184 bytes at the default
    /// `MAX_PARAMETERS=32` and 2,281,472 at 256 (`ParameterValue` is sized by
    /// its `StringArray` variant, so every slot costs ~8.5 KiB regardless of
    /// what it holds). `Box::new(ParameterStorage::new())` materialises all of
    /// that on the caller's stack before copying it into the allocation,
    /// because Rust has no placement-new. On the Zephyr lane that silently
    /// overran the thread stack: an image built with 256 slots boots to
    /// `dds_create_participant` and hangs with no fault and no output, while
    /// 32 — which fits the 512 KiB main stack the cyclonedds snippet asks for
    /// — runs clean. Initialising through the allocation bounds the largest
    /// stack temporary at one slot, so the knob no longer decides whether boot
    /// survives.
    ///
    /// Issue 1706 -- FALLIBLE. This is the one allocation every parameter
    /// declaration reaches, in every language and on every RTOS, and it is the
    /// largest single request most images make. `Box::new_uninit` sent a
    /// failure to the OOM handler: Zephyr printed `HEAP EXHAUSTED` and died in
    /// issue 0589's recursion, FreeRTOS heap_4 hung in `MALLOC FAILED`. Every
    /// caller already has a refusal to return (`declare_parameter` is a
    /// `bool`), so the failure is now one, named by
    /// [`report_parameter_store_refused`] with the size it asked for.
    ///
    /// Issue 1812 -- `alloc` only. Without a heap there is no fallback, and
    /// the store is the carved one or none (see `new_param_state`).
    #[cfg(feature = "alloc")]
    fn leak_parameter_storage() -> Option<nros_params::ParameterTable<'static>> {
        #[cfg(all(test, feature = "std"))]
        if RefuseParameterStore::armed() {
            return None;
        }
        let mut uninit = nros_rmw::fallible::try_box_uninit::<nros_params::ParameterStorage>()?;
        // Safety: `try_box_uninit` gives a correctly-sized, correctly-aligned
        // allocation for exactly this type, and `init_in_place` writes every
        // slot exactly once before `assume_init` observes it.
        unsafe {
            nros_params::ParameterStorage::init_in_place(uninit.as_mut_ptr());
            Some(alloc::boxed::Box::leak(uninit.assume_init()).as_table())
        }
    }

    /// Build the executor's `ParamState`.
    ///
    /// phase-382 W3' — `carved` are the backing's store slots: non-empty, they
    /// ARE the store and the heap is not asked; empty, the store falls back to
    /// [`leak_parameter_storage`](Self::leak_parameter_storage).
    ///
    /// Issue 1812 — and `home` is the services' carved region, which the
    /// backing places on the same condition: non-empty, the state, its service
    /// sets, the buffer pair and the staging slot are built IN it and nothing
    /// here allocates. Otherwise the state is one heap allocation, initialised
    /// in place (`ParamState::try_boxed` — it is several KiB now, so never a
    /// by-value `Box::new`). Without `alloc` that fallback does not exist and
    /// an executor whose backing carved nothing gets `None`, which every caller
    /// reports as the named refusal (`report_parameter_store_refused`).
    fn new_param_state(
        carved: &'s mut [MaybeUninit<nros_params::ParameterSlot>],
        home: &'s mut [MaybeUninit<super::storage::ParamHome>],
    ) -> Option<crate::param_store::Placed<'s, crate::param_store::ParamState<'s>>> {
        let table = if carved.is_empty() {
            #[cfg(feature = "alloc")]
            {
                Self::leak_parameter_storage()?
            }
            #[cfg(not(feature = "alloc"))]
            {
                return None;
            }
        } else {
            // Said once per store, so a boot log answers "where did the store
            // come from" without a debugger: issue 1706's measurements were
            // all heap-peak arithmetic, and this line is the direct answer.
            nros_log::log_info!(
                nros_log::get_logger("nros"),
                "parameter store: {} slots ({} B) + {} ({} B) carved from the executor backing",
                carved.len(),
                core::mem::size_of_val(carved),
                // Issue 1897 -- the home is the store's state, plus the
                // services' sets and buffers only where they are compiled.
                if cfg!(feature = "param-services") {
                    "state and services"
                } else {
                    "state"
                },
                core::mem::size_of_val(home)
            );
            nros_params::ParameterTable::init_in(carved)
        };
        let server = nros_params::ParameterServer::new_in(table);
        match home.first_mut() {
            Some(home) => Some(crate::param_store::ParamHome::init_in(home, server)),
            #[cfg(feature = "alloc")]
            None => crate::param_store::ParamState::try_boxed(server),
            #[cfg(not(feature = "alloc"))]
            None => None,
        }
    }

    /// Install `-p` / `--params-file` parameter overrides — phase-482 W5.
    ///
    /// They are applied when a parameter is DECLARED: the declaration's value
    /// is replaced by the override's, typed by it (`apply_argv_param_override`).
    /// So an override reaches a parameter on every road that declares through
    /// this executor — C, C++ and Rust — including the launch file's baked
    /// values, which the generated entry declares through the same seam.
    ///
    /// That makes argv WIN over a launch-baked parameter, the opposite of the
    /// remap tiers, deliberately: overriding a baked value at run time without
    /// a rebuild is what RFC-0015 §9 asks for ("a runtime override has
    /// identical effect to a `set_parameter` request after boot"), and upstream
    /// agrees — a launch file's parameters reach the node as command-line
    /// arguments themselves, where the later one wins.
    ///
    /// Overrides accumulate in argv order and the LAST one that matches a
    /// declaration wins, as rcl's do. A `node:` override matches the node of
    /// that NAME; one without matches every node.
    ///
    /// Fails only when the parameter store could not be allocated (issue 1706),
    /// in which case nothing is installed.
    #[cfg(feature = "alloc")]
    pub fn install_argv_params<'p, I>(&mut self, params: I) -> Result<usize, NodeError>
    where
        I: IntoIterator<Item = crate::ros_args::ParamArg<'p>>,
    {
        if !self.ensure_parameter_store() {
            return Err(NodeError::Transport(TransportError::BadAlloc));
        }
        let Some(state) = self.params.as_deref_mut() else {
            return Err(NodeError::Transport(TransportError::BadAlloc));
        };
        let mut n = 0;
        for p in params {
            state
                .argv_overrides
                .push(crate::param_store::ArgvParamOverride {
                    node: p.node.map(alloc::string::String::from),
                    name: alloc::string::String::from(p.name),
                    value: alloc::string::String::from(p.value),
                });
            n += 1;
        }
        Ok(n)
    }

    /// The value a declaration of `name` on `node` should take — the last
    /// matching argv override, typed by `declared`, or `declared` itself — and
    /// whether an override was applied.
    ///
    /// An override whose text does not parse as the declared type is NOT
    /// applied: it is logged at error severity, naming the parameter, the text
    /// and the type, and the declared default stands (RFC-0015 §9.6 — "log +
    /// ignore, never panic"). An array-typed declaration takes no override yet.
    #[cfg(not(feature = "alloc"))]
    fn apply_argv_param_override(
        &self,
        _node: super::node_record::NodeId,
        _name: &str,
        declared: nros_params::ParameterValue,
    ) -> (nros_params::ParameterValue, bool) {
        // Issue 1812 -- argv overrides are a hosted-edge input installed
        // through `install_argv_params`, which is `alloc`-only.
        (declared, false)
    }

    #[cfg(feature = "alloc")]
    fn apply_argv_param_override(
        &self,
        node: super::node_record::NodeId,
        name: &str,
        declared: nros_params::ParameterValue,
    ) -> (nros_params::ParameterValue, bool) {
        let Some(state) = self.params.as_deref() else {
            return (declared, false);
        };
        if state.argv_overrides.is_empty() {
            return (declared, false);
        }
        let node_name = self.node(node).map(|r| r.name.as_str()).unwrap_or("");
        let Some(o) = state
            .argv_overrides
            .iter()
            .rev()
            .find(|o| o.name == name && o.node.as_deref().is_none_or(|n| n == node_name))
        else {
            return (declared, false);
        };
        match typed_param_override(&o.value, &declared) {
            Some(v) => (v, true),
            None => {
                nros_log::log_error!(
                    nros_log::get_logger("nros"),
                    "parameter override `{}:={}` is not a {:?}; the declared default stands",
                    name,
                    o.value,
                    declared.param_type()
                );
                (declared, false)
            }
        }
    }

    /// Declare a parameter with a value on the executor's PRIMARY node.
    ///
    /// phase-426 W1 — the store is keyed by node, and this is the spelling for
    /// the executor's implicit primary node (`NodeId::PRIMARY`), which is the
    /// identity `register_parameter_services` publishes and the one every
    /// single-node entry means. Name a different node with
    /// [`declare_parameter_on`](Self::declare_parameter_on).
    ///
    /// phase-428 W6 — `#[must_use]`, for the reason `[[nodiscard]]` went on
    /// C++'s `Result`: the `else { false }` arm is silently discarded at a
    /// call site that drops the value, and `Node::logger` two files over
    /// already carries the attribute — so this was inconsistency, not house
    /// style. A declare that failed and was ignored is a parameter the program
    /// believes it has.
    #[must_use]
    pub fn declare_parameter(&mut self, name: &str, value: nros_params::ParameterValue) -> bool {
        self.declare_parameter_on(super::node_record::NodeId::PRIMARY, name, value)
    }

    /// Declare a parameter with a value on a named node.
    ///
    /// `#[must_use]` for the reason [`declare_parameter`](Self::declare_parameter)
    /// carries it: issue 1257's two dropped results moved to THIS method when
    /// they were fixed, so the attribute on the wrapper alone guarded nothing
    /// a launch-seed site could still drop.
    #[must_use]
    pub fn declare_parameter_on(
        &mut self,
        node: super::node_record::NodeId,
        name: &str,
        value: nros_params::ParameterValue,
    ) -> bool {
        self.ensure_parameter_store();
        let (value, _) = self.apply_argv_param_override(node, name, value);
        // phase-430 W2 — an application declaring `use_sim_time` itself wins
        // over the auto-declared default, so the placeholder leaves first.
        let yielded = self.yield_seeded_use_sim_time(node, name);
        let accepted = match &mut self.params {
            Some(params) => params.server.declare(node.into(), name, value),
            None => false,
        };
        if yielded && !accepted {
            // The app's own declaration was refused on its own terms (a full
            // store, an ill-formed range). Put the rclcpp default back rather
            // than leaving the name undeclared — that is a state neither the
            // app nor upstream asked for, and it would silently un-do W2 for
            // this node.
            self.seed_use_sim_time_default(node);
        }
        // phase-425 W3b — `use_sim_time` is RESERVED, exactly as in ROS 2: its
        // value is not a value the app reads, it is the switch that attaches the
        // time source. This is the one seam every language funnels through
        // (`nros::main!`'s launch bakes via `apply_param_services`, nros-c's
        // the rclc parameter server's `declare`, nros-cpp's `params_shim`), so hooking it
        // here covers all of them instead of once per entry path.
        //
        // phase-430 W3 / issue 1202 — the hook runs AFTER the store's verdict
        // and only on acceptance. It used to run first and unconditionally, so
        // a re-declaration the store REFUSES (the name is already there) still
        // flipped the switch: the store kept `use_sim_time = true` while the
        // `/clock` source detached, leaving an executor with sim time recorded
        // as on and no source attached, which is neither of the two states the
        // parameter can name.
        if accepted {
            self.note_reserved_parameter(name);
        }
        accepted
    }

    /// phase-425 W3b — record a reserved parameter's effect. Today that is
    /// `use_sim_time` and nothing else: it is the tree's only reserved name,
    /// and [`time_source::USE_SIM_TIME_PARAM`](crate::time_source::USE_SIM_TIME_PARAM)
    /// is the only such constant.
    ///
    /// Called only after the store ACCEPTED a declaration, and it reads the
    /// value back OUT of the store instead of taking the caller's: what the
    /// switch must follow is what the store holds, and the two are the same
    /// thing only while every write succeeds (issue 1202). The read is
    /// [`refresh_use_sim_time_from_store`](Self::refresh_use_sim_time_from_store),
    /// the same one the runtime `ros2 param set` path uses, so the declare path
    /// and the wire path cannot disagree about the value.
    ///
    /// A non-bool `use_sim_time` is IGNORED rather than rejected: parameter
    /// declaration has no channel to report a complaint on (it returns "did the
    /// store take it"), and refusing the declaration outright would fail a node
    /// for a parameter ROS 2 lets it declare. The time source simply does not
    /// attach, which is the same outcome as `false`.
    ///
    /// Not covered: [`Executor::parameter`](Self::parameter)'s
    /// [`ParameterBuilder`](nros_params::ParameterBuilder) borrows the server
    /// and declares through it, so the executor never sees the write and
    /// `use_sim_time` named that way attaches nothing — issue 1203.
    fn note_reserved_parameter(&mut self, name: &str) {
        #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
        if name == crate::time_source::USE_SIM_TIME_PARAM {
            self.refresh_use_sim_time_from_store();
        }
        let _ = name;
    }

    /// phase-425 W3b — a parameter service handled `n` requests this spin.
    ///
    /// The hook exists so `use_sim_time` can be re-read after a runtime
    /// `ros2 param set`, WITHOUT a per-spin scan of the store. It takes the
    /// count unconditionally and ignores it when `sim-time` is off, rather than
    /// the call sites carrying the feature test: `handled` was then assigned and
    /// never read in the `param-services`-without-`sim-time` combo, which is a
    /// `-D warnings` error `check-build` catches and the narrower per-crate
    /// clippy runs do not.
    #[inline]
    fn note_param_services_ran(&mut self, handled: usize) {
        #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
        if handled > 0 {
            self.refresh_use_sim_time_from_store();
        }
        let _ = handled;
        self.report_truncated_descriptions();
        #[cfg(feature = "param-services")]
        self.flush_parameter_events();
    }

    /// phase-446 F2 -- log each parameter whose description did not fit
    /// `NROS_MAX_PARAM_DESCRIPTION_LEN`, once, naming the knob.
    ///
    /// `nros-params` has no logger, so it truncates, records the truncation on
    /// the stored descriptor, and hands it over here. Asked on every spin
    /// because a declaration can arrive through builders this executor never
    /// sees the end of (`parameter::<T>()` returns the store's own builder);
    /// while nothing is pending the store answers from one flag, without
    /// walking its table.
    #[cold]
    fn report_truncated_descriptions(&mut self) {
        let Some(params) = self.params.as_deref_mut() else {
            return;
        };
        let nodes = &self.nodes;
        params.server.take_truncated_descriptions(|key, name| {
            let (ns, node) = nodes
                .get(key.index())
                .map_or(("", "?"), |r| (r.namespace.as_str(), r.name.as_str()));
            nros_log::log_warn!(
                nros_log::get_logger("nros"),
                "parameter `{}` on node {}/{}: its description is longer than \
                 NROS_MAX_PARAM_DESCRIPTION_LEN ({} bytes), so `ros2 param describe` \
                 answers it truncated at a character boundary. Raise \
                 NROS_MAX_PARAM_DESCRIPTION_LEN to keep it whole; 0 stores no \
                 descriptions. Logged once for this parameter (phase-446 F2).",
                name,
                ns.trim_end_matches('/'),
                node,
                nros_params::MAX_PARAM_DESCRIPTION_LEN
            );
        });
    }

    /// Declare a parameter with a value and descriptor on the PRIMARY node.
    /// Returns `true` if successful.
    ///
    /// phase-428 W6 remainder — the sibling of [`Self::declare_parameter`],
    /// with the identical `else { false }` arm and no attribute. W6 marked the
    /// one method its audit named; this is the site three lines below it, which
    /// is the shape CLAUDE.md's "fix the CLASS, not the reported site" rule
    /// exists for.
    #[must_use]
    pub fn declare_parameter_with_descriptor(
        &mut self,
        name: &str,
        value: nros_params::ParameterValue,
        descriptor: nros_params::ParameterDescriptor,
    ) -> bool {
        self.declare_parameter_with_descriptor_on(
            super::node_record::NodeId::PRIMARY,
            name,
            value,
            descriptor,
        )
    }

    /// Declare a parameter with a value and descriptor on a named node.
    pub fn declare_parameter_with_descriptor_on(
        &mut self,
        node: super::node_record::NodeId,
        name: &str,
        value: nros_params::ParameterValue,
        descriptor: nros_params::ParameterDescriptor,
    ) -> bool {
        self.ensure_parameter_store();
        // phase-430 W2 — same rule as the sibling above: the app's own
        // declaration, descriptor and all, replaces the auto-declared default.
        let yielded = self.yield_seeded_use_sim_time(node, name);
        // phase-482 W5 — an argv override that the DESCRIPTOR refuses (out of
        // range, or read-only with a different value) must not cost the
        // parameter its existence: log it, then declare the code's default.
        let (overridden, differs) = self.apply_argv_param_override(node, name, value.clone());
        let mut accepted = match &mut self.params {
            Some(params) => params.server.declare_with_descriptor(
                node.into(),
                name,
                overridden,
                Some(descriptor.clone()),
            ),
            None => false,
        };
        if !accepted && differs {
            nros_log::log_error!(
                nros_log::get_logger("nros"),
                "parameter override for `{}` was refused by its descriptor; the declared \
                 default stands",
                name
            );
            accepted = match &mut self.params {
                Some(params) => params.server.declare_with_descriptor(
                    node.into(),
                    name,
                    value,
                    Some(descriptor),
                ),
                None => false,
            };
        }
        if yielded && !accepted {
            self.seed_use_sim_time_default(node);
        }
        // phase-430 W3 / issue 1202 — the sibling declare path, which had NO
        // reserved hook at all: `declare_parameter_with_descriptor` stored
        // `use_sim_time` and attached nothing, so the same declaration meant
        // two different things depending on whether the app passed a
        // descriptor. Same seam, same verdict ordering, one shared hook.
        if accepted {
            self.note_reserved_parameter(name);
        }
        accepted
    }

    /// THE writer — phase-426 W2.
    ///
    /// Set an ALREADY-DECLARED parameter on the executor's primary node, with
    /// the same rules a remote `ros2 param set` gets: read-only, type, range
    /// (min/max/step), and issue 1151's refusal of a name the node never
    /// declared unless that node opted in through
    /// [`allow_undeclared_parameters_on`](Self::allow_undeclared_parameters_on).
    ///
    /// It routes through [`ParameterServer::apply`](nros_params::ParameterServer::apply),
    /// which is what makes the C and C++ facades, the by-value oracle, the
    /// streaming service path and the atomic pre-check agree — a facade that
    /// wrote the slot directly would be a second answer to "may this set
    /// happen", which is the class RFC-0019/0020 forbids. An in-image caller
    /// that genuinely wants declare-on-write names
    /// `params_mut()`/`set_or_declare` and has opted in by naming it.
    ///
    /// Returns [`SetParameterResult::NotFound`] when the store does not exist
    /// yet (no parameter has been declared and no services registered).
    pub fn set_parameter(
        &mut self,
        name: &str,
        value: nros_params::ParameterValue,
    ) -> nros_params::SetParameterResult {
        self.set_parameter_on(super::node_record::NodeId::PRIMARY, name, value)
    }

    /// [`set_parameter`](Self::set_parameter) on a named node.
    pub fn set_parameter_on(
        &mut self,
        node: super::node_record::NodeId,
        name: &str,
        value: nros_params::ParameterValue,
    ) -> nros_params::SetParameterResult {
        // Reserved parameters (`use_sim_time`) take effect on a set exactly as
        // they do on a declare — this is the seam every language funnels
        // through, so hooking it once here covers all of them.
        //
        // AFTER the store's verdict and only on `Success`, for the reason issue
        // 1202 gives one function up: the hook used to run first and off the
        // caller's value, so a write the store REFUSED still moved the switch
        // and left sim time recorded as on with no source attached. `apply` has
        // more ways to refuse than `declare` does — read-only, type, range,
        // undeclared-without-the-node-option — so a writer that hooked first
        // would reach that state from four directions instead of one.
        let result = match &mut self.params {
            Some(params) => params.server.apply(node.into(), name, value),
            None => nros_params::SetParameterResult::NotFound,
        };
        if result == nros_params::SetParameterResult::Success {
            self.note_reserved_parameter(name);
        }
        result
    }

    /// phase-491 W2 (RFC-0105 D7) — rclc's LOCAL typed set on `node`:
    /// type, the on-set hooks with `(old, new)`, the write. Read-only and
    /// range are NOT checked, because rclc's owner of a parameter is not bound
    /// by them; remote writes keep [`set_parameter_on`](Self::set_parameter_on)'s
    /// rules. The reserved-parameter hook runs on success, as on every writer.
    pub fn set_parameter_local_on(
        &mut self,
        node: super::node_record::NodeId,
        name: &str,
        value: nros_params::ParameterValue,
    ) -> nros_params::SetParameterResult {
        let result = match &mut self.params {
            Some(params) => params.server.set_local(node.into(), name, value),
            None => nros_params::SetParameterResult::NotFound,
        };
        if result == nros_params::SetParameterResult::Success {
            self.note_reserved_parameter(name);
        }
        result
    }

    #[cfg(feature = "param-services")]
    /// phase-491 W3 (RFC-0105 D8) — publish `node`'s parameter changes on
    /// `/parameter_events` (rclc's `notify_changed_over_dds`).
    ///
    /// Creates the executor's one `/parameter_events` publisher on the first
    /// call (see `ParamState::event_publisher`), typed
    /// `rcl_interfaces/msg/ParameterEvent`, RELIABLE + VOLATILE as upstream's
    /// `parameter_events` profile. Its depth is upstream's 1000 on a hosted
    /// build and `NROS_PARAM_EVENTS_DEPTH` (default 1) otherwise, because a
    /// reliable DDS writer's history is memory the RMW reserves; depth is not
    /// a matching criterion, so an upstream subscriber still matches.
    /// Idempotent.
    pub fn enable_parameter_events_on(
        &mut self,
        node: super::node_record::NodeId,
    ) -> Result<(), NodeError> {
        use nros_core::RosMessage;
        type Event = nros_rcl_interfaces::msg::ParameterEvent;
        if !self.ensure_parameter_store() {
            return Err(NodeError::Transport(TransportError::BadAlloc));
        }
        let idx = node.index();
        if idx >= crate::param_sizing::MAX_SERVICE_SETS {
            return Err(NodeError::NodeTableFull);
        }
        if self
            .params
            .as_ref()
            .is_some_and(|p| p.event_publisher.is_some())
        {
            if let Some(params) = self.params.as_mut() {
                params.server.set_parameter_events(node.into(), true);
            }
            return Ok(());
        }
        // The event is encoded into the services' reply buffer; on the heap
        // road that pair is allocated with the first service set, which may
        // not exist yet.
        #[cfg(feature = "alloc")]
        if let Some(params) = self.params.as_mut()
            && params.buffers.is_none()
        {
            params.buffers = Some(
                crate::parameter_services::ParamServiceBuffers::try_with_capacity(
                    crate::parameter_services::param_service_buffer_bytes(),
                )
                .ok_or(NodeError::Transport(TransportError::BadAlloc))?,
            );
        }
        crate::rmw_type_registry::register_type::<Event>()?;
        let qos = QoSProfile::parameter_events_default().depth(nros_params::PARAM_EVENTS_DEPTH);
        let handle = self.create_raw_publisher_handle_on(
            node,
            "/parameter_events",
            <Event as RosMessage>::TYPE_NAME,
            <Event as RosMessage>::TYPE_HASH,
            qos,
        )?;
        if let Some(params) = self.params.as_mut() {
            params.event_publisher = Some(handle);
            params.server.set_parameter_events(node.into(), true);
        }
        Ok(())
    }

    #[cfg(feature = "param-services")]
    /// phase-491 W3 — publish every pending parameter change, one
    /// `ParameterEvent` each, oldest first. Runs after each spin's parameter
    /// services and after every C parameter call; nothing allocates.
    pub fn flush_parameter_events(&mut self) {
        let stamp_ns = self
            .epoch_us_fn
            .or(self.clock_us_fn)
            .map_or(0, |clock| clock().saturating_mul(1000));
        let mut lost: u32 = 0;
        loop {
            let Some(params) = self.params.as_mut() else {
                return;
            };
            let Some(event) = params.server.pop_parameter_event() else {
                break;
            };
            let idx = event.node.index();
            let mut fqn = heapless::String::<256>::new();
            match self.nodes.get(idx) {
                Some(r) => {
                    if let Ok(f) = crate::names::fully_qualified_name(&r.name, &r.namespace) {
                        let _ = fqn.push_str(f.as_str());
                    }
                }
                None => {
                    if let Ok(f) =
                        crate::names::fully_qualified_name(&self.node_name, &self.namespace)
                    {
                        let _ = fqn.push_str(f.as_str());
                    }
                }
            }
            let Some(params) = self.params.as_mut() else {
                return;
            };
            let crate::param_store::ParamState {
                server,
                buffers,
                event_publisher,
                ..
            } = &mut **params;
            let (Some(publisher), Some(buffers)) = (event_publisher.as_ref(), buffers.as_mut())
            else {
                continue;
            };
            let value = match event.kind {
                nros_params::ParameterEventKind::Deleted => None,
                _ => server.get(event.node, event.name.as_str()),
            };
            let encoded = crate::parameter_services::encode_parameter_event(
                buffers.reply_mut(),
                stamp_ns,
                fqn.as_str(),
                event.kind,
                event.name.as_str(),
                value,
            );
            match encoded {
                Some(n) => {
                    use nros_rmw::Publisher as _;
                    if publisher.publish_raw(&buffers.reply_mut()[..n]).is_err() {
                        lost = lost.saturating_add(1);
                    }
                }
                None => {
                    lost = lost.saturating_add(1);
                }
            }
        }
        let dropped = self
            .params
            .as_mut()
            .map_or(0, |p| p.server.take_parameter_events_dropped());
        let lost = lost.saturating_add(dropped);
        if lost > 0 {
            Self::report_parameter_events_lost(lost);
        }
    }

    #[cfg(feature = "param-services")]
    #[cold]
    fn report_parameter_events_lost(lost: u32) {
        nros_log::log_warn!(
            nros_log::get_logger("nros"),
            "{} /parameter_events message(s) were not published: the change log \
             (PARAMETER_EVENT_LOG_LEN) filled between two flushes, a value did not fit the \
             parameter-service reply buffer (NROS_PARAM_SERVICE_BUFFER_SIZE), or the \
             publish failed. The parameters themselves changed (phase-491 W3).",
            lost
        );
    }

    /// phase-491 W2 — a remote `NOT_SET` on `node` deletes the parameter
    /// (rclc) instead of being refused (rclcpp). See
    /// [`ParameterServer::set_delete_on_not_set`](nros_params::ParameterServer::set_delete_on_not_set).
    pub fn delete_parameters_on_not_set_on(&mut self, node: super::node_record::NodeId, on: bool) {
        self.ensure_parameter_store();
        if let Some(params) = &mut self.params {
            params.server.set_delete_on_not_set(node.into(), on);
        }
    }

    /// May a remote set DECLARE a name this node never declared? Upstream's
    /// `allow_undeclared_parameters` node option (issue 1151), per node since
    /// phase-426 W1: switching it on for one node leaves its siblings
    /// refusing.
    pub fn allow_undeclared_parameters_on(
        &mut self,
        node: super::node_record::NodeId,
        allow: bool,
    ) {
        self.ensure_parameter_store();
        if let Some(params) = &mut self.params {
            params.server.set_allow_undeclared(node.into(), allow);
        }
    }

    /// [`allow_undeclared_parameters_on`](Self::allow_undeclared_parameters_on)
    /// for the primary node.
    pub fn allow_undeclared_parameters(&mut self, allow: bool) {
        self.allow_undeclared_parameters_on(super::node_record::NodeId::PRIMARY, allow);
    }

    /// Get a parameter value by name from the primary node.
    pub fn get_parameter(&self, name: &str) -> Option<&nros_params::ParameterValue> {
        self.get_parameter_on(super::node_record::NodeId::PRIMARY, name)
    }

    /// Get a parameter value by name from a named node.
    pub fn get_parameter_on(
        &self,
        node: super::node_record::NodeId,
        name: &str,
    ) -> Option<&nros_params::ParameterValue> {
        self.params.as_deref()?.server.get(node.into(), name)
    }

    /// Get an integer parameter value by name from the primary node (convenience).
    pub fn get_parameter_integer(&self, name: &str) -> Option<i64> {
        self.params
            .as_ref()?
            .server
            .get_integer(super::node_record::NodeId::PRIMARY.into(), name)
    }

    /// Get a reference to the parameter server (if registered).
    pub fn params(&self) -> Option<&nros_params::ParameterServer<'s>> {
        self.params.as_deref().map(|p| &p.server)
    }

    /// Get a mutable reference to the parameter server (if registered).
    pub fn params_mut(&mut self) -> Option<&mut nros_params::ParameterServer<'s>> {
        self.params.as_deref_mut().map(|p| &mut p.server)
    }

    /// Create a typed parameter builder (rclrs-compatible API).
    ///
    /// Returns a [`ParameterBuilder`] for fluent parameter declaration with
    /// `.default()`, `.description()`, `.range()`, and terminal methods
    /// `.mandatory()`, `.optional()`, or `.read_only()`.
    ///
    /// Returns [`NodeError::NotInitialized`] if parameter services have
    /// not been registered yet — call [`register_parameter_services`]
    /// first.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let max_speed = executor.parameter::<f64>("max_speed")?
    ///     .default(25.0)
    ///     .description("Maximum velocity (m/s)")
    ///     .read_only()?;
    /// ```
    ///
    /// [`ParameterBuilder`]: nros_params::ParameterBuilder
    /// [`register_parameter_services`]: Self::register_parameter_services
    pub fn parameter<'a, T: nros_params::ParameterVariant>(
        &'a mut self,
        name: &'a str,
    ) -> Result<nros_params::ParameterBuilder<'a, 's, T>, NodeError> {
        self.parameter_on(super::node_record::NodeId::PRIMARY, name)
    }

    /// [`parameter`](Self::parameter) on a named node.
    pub fn parameter_on<'a, T: nros_params::ParameterVariant>(
        &'a mut self,
        node: super::node_record::NodeId,
        name: &'a str,
    ) -> Result<nros_params::ParameterBuilder<'a, 's, T>, NodeError> {
        let server = self
            .params
            .as_mut()
            .map(|p| &mut p.server)
            .ok_or(NodeError::NotInitialized)?;
        Ok(nros_params::ParameterBuilder::new(
            server,
            node.into(),
            name,
        ))
    }

    // ========================================================================
    // phase-417 W4.a — the surface C and C++ forward to
    //
    // Every one of these is a forwarder onto `nros_params::ParameterServer`,
    // the ONE store. They exist on the executor because that is the object the
    // FFI holds: a C caller has an `rclc_executor_t*` and an `rcl_node_t*`,
    // and a C++ node has its `node_id`. Nothing here keeps state — a wrapper
    // that did would be the second store phase-426 removed.
    // ========================================================================

    /// Attach a description and free-text constraints to a declared parameter
    /// on `node` — rclc's `rclc_add_parameter_description`.
    pub fn set_parameter_description_on(
        &mut self,
        node: super::node_record::NodeId,
        name: &str,
        description: &str,
        additional_constraints: &str,
    ) -> bool {
        match &mut self.params {
            Some(params) => params.server.set_parameter_description(
                node.into(),
                name,
                description,
                additional_constraints,
            ),
            None => false,
        }
    }

    /// [`set_parameter_description_on`](Self::set_parameter_description_on) for
    /// the primary node.
    pub fn set_parameter_description(
        &mut self,
        name: &str,
        description: &str,
        additional_constraints: &str,
    ) -> bool {
        self.set_parameter_description_on(
            super::node_record::NodeId::PRIMARY,
            name,
            description,
            additional_constraints,
        )
    }

    /// Mark a declared parameter read-only — rclc's
    /// `rclc_set_parameter_read_only`. Every later write, local or remote, is
    /// refused.
    pub fn set_parameter_read_only_on(
        &mut self,
        node: super::node_record::NodeId,
        name: &str,
        read_only: bool,
    ) -> bool {
        match &mut self.params {
            Some(params) => params
                .server
                .set_parameter_read_only(node.into(), name, read_only),
            None => false,
        }
    }

    /// [`set_parameter_read_only_on`](Self::set_parameter_read_only_on) for the
    /// primary node.
    pub fn set_parameter_read_only(&mut self, name: &str, read_only: bool) -> bool {
        self.set_parameter_read_only_on(super::node_record::NodeId::PRIMARY, name, read_only)
    }

    /// Attach an integer range — rclc's
    /// `rclc_add_parameter_constraint_integer`. Refuses an ill-formed range or
    /// one the current value does not satisfy.
    pub fn set_parameter_integer_range_on(
        &mut self,
        node: super::node_record::NodeId,
        name: &str,
        min: i64,
        max: i64,
        step: i64,
    ) -> bool {
        match &mut self.params {
            Some(params) => {
                params
                    .server
                    .set_parameter_integer_range(node.into(), name, min, max, step)
            }
            None => false,
        }
    }

    /// [`set_parameter_integer_range_on`](Self::set_parameter_integer_range_on)
    /// for the primary node.
    pub fn set_parameter_integer_range(
        &mut self,
        name: &str,
        min: i64,
        max: i64,
        step: i64,
    ) -> bool {
        self.set_parameter_integer_range_on(
            super::node_record::NodeId::PRIMARY,
            name,
            min,
            max,
            step,
        )
    }

    /// Attach a floating-point range — rclc's
    /// `rclc_add_parameter_constraint_double`.
    pub fn set_parameter_float_range_on(
        &mut self,
        node: super::node_record::NodeId,
        name: &str,
        min: f64,
        max: f64,
        step: f64,
    ) -> bool {
        match &mut self.params {
            Some(params) => {
                params
                    .server
                    .set_parameter_float_range(node.into(), name, min, max, step)
            }
            None => false,
        }
    }

    /// [`set_parameter_float_range_on`](Self::set_parameter_float_range_on) for
    /// the primary node.
    pub fn set_parameter_float_range(&mut self, name: &str, min: f64, max: f64, step: f64) -> bool {
        self.set_parameter_float_range_on(super::node_record::NodeId::PRIMARY, name, min, max, step)
    }

    /// The descriptor of a declared parameter — rclcpp's
    /// `describe_parameter`, rclrs's `ParameterBuilder` readback. `None` when
    /// the parameter is not declared on `node`, or was declared without one.
    pub fn describe_parameter_on(
        &self,
        node: super::node_record::NodeId,
        name: &str,
    ) -> Option<&nros_params::ParameterDescriptor> {
        self.params
            .as_ref()?
            .server
            .get_descriptor(node.into(), name)
    }

    /// [`describe_parameter_on`](Self::describe_parameter_on) for the primary
    /// node.
    pub fn describe_parameter(&self, name: &str) -> Option<&nros_params::ParameterDescriptor> {
        self.describe_parameter_on(super::node_record::NodeId::PRIMARY, name)
    }

    /// The declared TYPE of a parameter — rclcpp's `get_parameter_types`, and
    /// the local answer to the `~/get_parameter_types` service.
    pub fn get_parameter_type_on(
        &self,
        node: super::node_record::NodeId,
        name: &str,
    ) -> Option<nros_params::ParameterType> {
        self.params.as_deref()?.server.get_type(node.into(), name)
    }

    /// [`get_parameter_type_on`](Self::get_parameter_type_on) for the primary
    /// node.
    pub fn get_parameter_type(&self, name: &str) -> Option<nros_params::ParameterType> {
        self.get_parameter_type_on(super::node_record::NodeId::PRIMARY, name)
    }

    /// The names a node has declared, filtered by prefix — rclcpp's
    /// `list_parameters`, and the local answer to `~/list_parameters`. An
    /// empty prefix lists them all.
    pub fn list_parameters_on<'p>(
        &'p self,
        node: super::node_record::NodeId,
        prefix: &'p str,
    ) -> impl Iterator<Item = &'p str> {
        self.params
            .as_ref()
            .into_iter()
            .flat_map(move |p| p.server.list_with_prefix(node.into(), prefix))
    }

    /// [`list_parameters_on`](Self::list_parameters_on) for the primary node.
    pub fn list_parameters<'p>(&'p self, prefix: &'p str) -> impl Iterator<Item = &'p str> {
        self.list_parameters_on(super::node_record::NodeId::PRIMARY, prefix)
    }

    /// All-or-nothing multi-set on `node` — rclcpp's
    /// `set_parameters_atomically`.
    ///
    /// We SERVED `~/set_parameters_atomically` and offered it in no language,
    /// so the only way to reach our own atomic set was over the wire. This is
    /// the same call the service handler makes.
    ///
    /// `items` yields `None` for an element that could not be turned into a
    /// value at all; that refuses the batch like any failing check.
    pub fn set_parameters_atomically_on<'x, I>(
        &mut self,
        node: super::node_record::NodeId,
        items: I,
    ) -> nros_params::SetParameterResult
    where
        I: Iterator<Item = Option<(&'x str, nros_params::ParameterValue)>> + Clone,
    {
        match &mut self.params {
            Some(params) => params.server.apply_atomically(node.into(), items),
            None => nros_params::SetParameterResult::NotFound,
        }
    }

    /// [`set_parameters_atomically_on`](Self::set_parameters_atomically_on) for
    /// the primary node.
    pub fn set_parameters_atomically<'x, I>(&mut self, items: I) -> nros_params::SetParameterResult
    where
        I: Iterator<Item = Option<(&'x str, nros_params::ParameterValue)>> + Clone,
    {
        self.set_parameters_atomically_on(super::node_record::NodeId::PRIMARY, items)
    }

    /// Undeclare a parameter — rclcpp's `undeclare_parameter`, rclc's
    /// `rclc_delete_parameter`. The slot is freed for a later declaration.
    pub fn undeclare_parameter_on(&mut self, node: super::node_record::NodeId, name: &str) -> bool {
        match &mut self.params {
            Some(params) => params.server.remove(node.into(), name),
            None => false,
        }
    }

    /// [`undeclare_parameter_on`](Self::undeclare_parameter_on) for the primary
    /// node.
    pub fn undeclare_parameter(&mut self, name: &str) -> bool {
        self.undeclare_parameter_on(super::node_record::NodeId::PRIMARY, name)
    }

    /// Register an accept/reject hook for writes to `node` — rclcpp's
    /// `add_on_set_parameters_callback`.
    ///
    /// It runs on every write that reaches the store through
    /// [`set_parameter_on`](Self::set_parameter_on), which is the seam the six
    /// `rcl_interfaces/srv/*` servers and both wrapper languages share, so ONE
    /// registration covers a remote `ros2 param set` and a local one alike.
    ///
    /// `None` when all [`nros_params::MAX_ON_SET_CALLBACKS`] slots are taken.
    pub fn add_on_set_parameters_callback_on(
        &mut self,
        node: super::node_record::NodeId,
        callback: nros_params::OnSetParameterFn,
        ctx: nros_params::OnSetContext,
    ) -> Option<nros_params::OnSetParameterHandle> {
        self.ensure_parameter_store();
        self.params
            .as_mut()?
            .server
            .add_on_set_parameters_callback(node.into(), callback, ctx)
    }

    /// [`add_on_set_parameters_callback_on`](Self::add_on_set_parameters_callback_on)
    /// for the primary node.
    pub fn add_on_set_parameters_callback(
        &mut self,
        callback: nros_params::OnSetParameterFn,
        ctx: nros_params::OnSetContext,
    ) -> Option<nros_params::OnSetParameterHandle> {
        self.add_on_set_parameters_callback_on(super::node_record::NodeId::PRIMARY, callback, ctx)
    }

    /// Unregister a hook — rclcpp's `remove_on_set_parameters_callback`.
    pub fn remove_on_set_parameters_callback(
        &mut self,
        handle: nros_params::OnSetParameterHandle,
    ) -> bool {
        match &mut self.params {
            Some(params) => params.server.remove_on_set_parameters_callback(handle),
            None => false,
        }
    }

    /// rclrs's `Node::use_undeclared_parameters` — a handle that reads and
    /// writes parameters this node never declared.
    ///
    /// The handle writes through `set_or_declare`, not through the wire-facing
    /// `apply`: `allow_undeclared_parameters` governs what a REMOTE set may
    /// create, and a caller who reached for this type has opted in by naming
    /// it. That is rclrs's split too.
    pub fn use_undeclared_parameters_on(
        &mut self,
        node: super::node_record::NodeId,
    ) -> Result<nros_params::UndeclaredParameters<'_, 's>, NodeError> {
        let server = self
            .params
            .as_mut()
            .map(|p| &mut p.server)
            .ok_or(NodeError::NotInitialized)?;
        Ok(nros_params::UndeclaredParameters::new(server, node.into()))
    }

    /// [`use_undeclared_parameters_on`](Self::use_undeclared_parameters_on) for
    /// the primary node.
    pub fn use_undeclared_parameters(
        &mut self,
    ) -> Result<nros_params::UndeclaredParameters<'_, 's>, NodeError> {
        self.use_undeclared_parameters_on(super::node_record::NodeId::PRIMARY)
    }
}

// ============================================================================
// Executor lifecycle — cancel / is_spinning (phase-417 W4.c)
// ============================================================================

// Issue 1177 -- UN-GATED. This block was `#[cfg(feature = "alloc")]` because
// `halt_flag` and `spinning` were `alloc` fields, and neither needed to be: the
// allocator is required to SHARE the halt flag (`halt_flag()` hands out a
// refcounted handle), never to hold it.
//
// Gating it meant a no_std executor could not be stopped, and worse, that
// `nros-c`'s spin loop -- which calls `cancel`, `is_halted`, `is_spinning`,
// `enter_spin_loop` and `exit_spin_loop` with no cfg of its own -- did not
// COMPILE for an embedded image. The safety island found that; no
// merge-gating lane builds this crate without `alloc`.
impl<'s> Executor<'s> {
    /// Request the executor to stop spinning — `rclcpp::Executor::cancel`.
    ///
    /// # ADOPT-BOUNDED (RFC-0089)
    ///
    /// `cancel` sets a flag the spin loop observes at the NEXT POLL BOUNDARY,
    /// so it returns BEFORE spinning has actually stopped;
    /// [`is_spinning()`](Self::is_spinning) is the observable that tells you
    /// when it has. rclcpp makes the same promise in the same shape, but the
    /// boundary here is one `spin_once` timeout wide (a backend's `drive_io`
    /// blocks up to the poll interval), so "next boundary" is a duration a
    /// caller can measure rather than an implementation detail. The wake flag
    /// below shortens it; it does not remove it.
    ///
    /// Nothing here tears down the session: an executor that has been cancelled
    /// is still initialised, still owns its entities, and can be spun again.
    /// Teardown is a different verb (`fini` / `shutdown`), and collapsing the
    /// two costs a full discovery round on every mode change.
    ///
    /// Safe to call from another thread or a signal handler.
    ///
    /// Also raises the Phase 104.C.6 wake flag so a `spin_once` already blocked
    /// inside a backend's `drive_io` falls through to the cancel check on its
    /// next loop iteration instead of waiting out its full `timeout_ms` first.
    pub fn cancel(&self) {
        self.halt_flag
            .store(true, core::sync::atomic::Ordering::SeqCst);
        // The wake flag is the `Arc` half and still needs an allocator. A
        // core-only image simply waits out the poll interval, which is the
        // bounded behaviour the envelope above already promises.
        #[cfg(feature = "alloc")]
        self.wake_flag
            .store(true, core::sync::atomic::Ordering::SeqCst);
    }

    /// Has a [`cancel()`](Self::cancel) been REQUESTED?
    ///
    /// Not the same question as [`is_spinning()`](Self::is_spinning), and both
    /// are kept because both have callers:
    ///
    /// * `is_halted()` — "someone asked this executor to stop." True the instant
    ///   `cancel()` returns, and it stays true until the next spin loop clears
    ///   it on entry. This is the flag a hand-rolled `while !exec.is_halted()`
    ///   loop polls, which is what a BSP that drives `spin_once` itself writes.
    /// * `is_spinning()` — "a spin loop is running right now." Answers the other
    ///   half of the envelope: whether the cancel has been ACTED on yet.
    ///
    /// The two are true together for as long as one poll takes, which is exactly
    /// the window the ADOPT-BOUNDED envelope on `cancel()` describes. Neither is
    /// derivable from the other: an executor that was never spun is neither
    /// halted nor spinning, and one cancelled mid-poll is both.
    ///
    /// The name is the pre-rename spelling and is deliberately NOT deprecated —
    /// `cancel`'s rclcpp pair is a `spinning` observable, not an
    /// `is_cancel_requested` one, so there is no ROS 2 name to adopt here and a
    /// third spelling would buy nothing.
    pub fn is_halted(&self) -> bool {
        self.halt_flag.load(core::sync::atomic::Ordering::SeqCst)
    }

    /// Is a spin loop running on this executor right now?
    ///
    /// rclcpp spells this `Executor::is_spinning()`. True between the entry and
    /// the exit of [`spin`](Self::spin),
    /// [`spin_period`](Self::spin_period), the `open_threaded` worker loop, and
    /// the C / C++ API loops — every construct that owns its own iteration.
    ///
    /// A bare `spin_once` does NOT set it: one poll is not a spin, and a caller
    /// running its own `while` around `spin_once` is the one who knows it is
    /// looping. Such a caller can say so with
    /// [`enter_spin_loop`](Self::enter_spin_loop).
    ///
    /// See [`is_halted()`](Self::is_halted) for why this is a different question
    /// from "was cancel requested".
    pub fn is_spinning(&self) -> bool {
        self.spinning.load(core::sync::atomic::Ordering::SeqCst)
    }

    /// Declare that the caller is entering a spin loop it drives itself.
    ///
    /// The seam the C and C++ APIs use so their loops answer
    /// [`is_spinning()`](Self::is_spinning) without keeping a flag of their own
    /// (RFC-0019: ergonomics may live in the wrapper, state may not). Also
    /// CLEARS any pending cancel, matching what `spin` does on entry:
    /// a cancel requested before a spin started is not a cancel of THIS spin.
    ///
    /// Pair it with [`exit_spin_loop`](Self::exit_spin_loop) on EVERY exit path,
    /// `break` and early `return` alike — a loop that leaves without it reports
    /// `is_spinning() == true` forever. It is a method pair rather than an RAII
    /// guard on purpose: a guard would have to borrow the executor for the whole
    /// loop, and every caller needs `&mut` inside the body to poll.
    ///
    /// Takes `&self` (the flags are atomics), so the borrow ends at the call.
    pub fn enter_spin_loop(&self) {
        self.halt_flag
            .store(false, core::sync::atomic::Ordering::SeqCst);
        self.spinning
            .store(true, core::sync::atomic::Ordering::SeqCst);
    }

    /// End the scope opened by [`enter_spin_loop`](Self::enter_spin_loop).
    ///
    /// Idempotent. Leaves the cancel flag alone: "someone asked me to stop" is
    /// the caller's answer to keep or clear, and clearing it here would lose the
    /// reason the loop exited.
    pub fn exit_spin_loop(&self) {
        self.spinning
            .store(false, core::sync::atomic::Ordering::SeqCst);
    }
}

// ============================================================================
// std-gated spin and halt methods
// ============================================================================

// phase-359 W10 — this impl used to be ONE `#[cfg(feature = "std")]` block.
// Only the wall-clock spin loops in it need `std` (`Instant`, `thread::sleep`,
// `thread::spawn`); `halt` / `is_halted` / `wake` are plain atomic stores on
// flags the struct already owns, and `halt_flag` / `wake_handle` only need
// `Arc`. Gating the BLOCK rather than the items made a no_std image unable to
// stop its own executor — `ExecutorNodeRuntime::spin` carried a matching `std`
// gate for no reason but this one.
// phase-359 W10 — `alloc`, not `std`. The wall-clock spin loops were the
// reason this block was std-gated: `Instant` for the deadline and
// `thread::sleep` for the pacing. Both now go through the platform — the
// executor's own `now_us()` and `nros_platform_sleep_us` — so a no_std
// image can run the same blocking loops a hosted one does instead of
// hand-rolling them in its BSP.
#[cfg(feature = "alloc")]
impl<'s> Executor<'s> {
    /// Blocking spin loop with configurable exit conditions — rclrs's
    /// `Executor::spin(SpinOptions)`.
    ///
    /// ADOPT-BOUNDED (RFC-0089). Same name, same argument, same meaning: run
    /// until an exit condition in `opts` says stop. Two bounds, both visible in
    /// the signature:
    ///
    /// * **The error channel is one error, not all of them.** rclrs returns
    ///   `Vec<RclrsError>` and the caller writes `.first_error()?`; there is no
    ///   allocator here, so ours returns `Result<(), NodeError>` carrying the
    ///   FIRST failing callback's error and drops the rest (they are still
    ///   counted in each pass's [`SpinOnceResult`]). Ported line for line, the
    ///   edit is `.first_error()?` -> `?`, which the compiler points at.
    /// * **The loop is a poll loop**, so `opts.poll_interval` is the quantum at
    ///   which every exit condition is observed — a `cancel()` from another
    ///   task, the `timeout` expiring, `max_callbacks` being reached. Requesting
    ///   a `timeout` on a build with no clock is an ERROR, not a silent
    ///   never-ending loop (issue 0709).
    ///
    /// phase-427 — this method was `spin_blocking`. `spin` was taken by the
    /// `-> !` task body, which is now [`spin_forever`](Self::spin_forever).
    ///
    /// Runs until one of:
    /// - [`cancel()`](Self::cancel) is called (from
    ///   another thread or signal handler)
    /// - `opts.timeout` expires (if set)
    /// - `opts.max_callbacks` is reached (if set)
    /// - `opts.only_next` is true (single iteration)
    /// - a callback failed and `opts.stop_on_first_error` is set
    ///
    /// # Example
    ///
    /// ```ignore
    /// // Spin until cancelled
    /// executor.spin(SpinOptions::default())?;
    ///
    /// // Spin with 5-second timeout
    /// executor.spin(SpinOptions::new().timeout(core::time::Duration::from_secs(5)))?;
    ///
    /// // Single iteration
    /// executor.spin(SpinOptions::spin_once())?;
    /// ```
    pub fn spin(&mut self, opts: SpinOptions) -> Result<(), NodeError> {
        // phase-427 — was a private `POLL_INTERVAL` const; it is
        // `SpinOptions::poll_interval` now, defaulting to the same 10 ms, so
        // `spin` and `spin_forever` read one value instead of two literals.
        let poll_interval = opts.poll_interval;

        // phase-359 W10 — the executor's own clock. `now_us()` reads the
        // PLATFORM's monotonic counter, and nothing else: the platform API is
        // the clock, so a build with a port has one and a build without has
        // none. There is no `std::time::Instant` third answer any more, which
        // is what used to make "what time is it" depend on whether some crate
        // in the graph happened to name `std`.
        //
        // `None` means this build has NO clock at all — and issue 0709 is what
        // the previous answer here cost. It read: "a timeout cannot be honoured
        // then, and pretending otherwise would exit immediately or never; the
        // honest reading is no deadline". It then picked NEVER. A caller that
        // asked for 50 ms got an infinite loop, silently, in the one API whose
        // whole contract is "returns after N ms" — ten hours of a CI lane
        // before anyone read it as stuck rather than slow.
        //
        // Neither of the two silent readings is honest. An unmet precondition
        // is an ERROR (repo rule, fail-loud): the caller supplied a time
        // quantity this build cannot measure, and only they can decide what to
        // do about it. An UNTIMED `spin` still runs until halt, which
        // is a promise this build can keep.
        let start_us = self.now_us();
        if opts.timeout.is_some() && start_us.is_none() {
            nros_log::log_error!(
                nros_log::get_logger("nros"),
                "spin: a timeout was requested but this build has no clock \
                 — install one with `ExecutorConfig::clock_us` (issue 0709)"
            );
            return Err(NodeError::NotInitialized);
        }
        // `as_micros()` rather than a hand-rolled `ms * 1_000`: the multiply
        // was unchecked, and the unit conversion is `Duration`'s job.
        let timeout_us = opts.timeout.map(|d| d.as_micros() as u64);
        let mut total_callbacks = 0usize;

        // phase-417 W4.c — clears the cancel flag AND raises `is_spinning`. The
        // clear is the pre-existing behaviour (a cancel requested before this
        // spin is not a cancel of this spin); the raise is what lets a peer
        // thread see that its `cancel()` has not been acted on yet. Every exit
        // below is a `break` to the single tail, which is where the scope ends.
        self.enter_spin_loop();

        loop {
            if self.halt_flag.load(core::sync::atomic::Ordering::SeqCst) {
                break;
            }

            if let (Some(start), Some(limit)) = (start_us, timeout_us)
                && self
                    .now_us()
                    .is_some_and(|now| now.saturating_sub(start) >= limit)
            {
                break;
            }

            let mut callback_error = None;
            let result = self.spin_once_capturing(poll_interval, &mut callback_error);
            total_callbacks += result.total();

            // phase-427 — the first error, and only the first: rclrs's
            // `Vec<RclrsError>` needs an allocator we do not have. The scope is
            // closed before returning so a caller that reads `is_spinning()`
            // after an error sees `false`, exactly as after a clean exit.
            if opts.stop_on_first_error
                && let Some(e) = callback_error
            {
                self.exit_spin_loop();
                return Err(NodeError::Transport(e));
            }

            if opts.max_callbacks.is_some_and(|max| total_callbacks >= max) {
                break;
            }

            if opts.only_next {
                break;
            }
        }

        self.exit_spin_loop();
        Ok(())
    }

    /// Execute one period with wall-clock overrun detection.
    ///
    /// Calls [`spin_once()`](Self::spin_once), measures wall-clock time, sleeps
    /// for the remainder if under budget.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let period = core::time::Duration::from_millis(10);
    /// let result = executor.spin_one_period_timed(period);
    /// if result.overrun {
    ///     log::warn!("Period overrun: {:?}", result.elapsed);
    /// }
    /// ```
    pub fn spin_one_period_timed(
        &mut self,
        period: core::time::Duration,
    ) -> super::types::SpinPeriodResult {
        let start_us = self.now_us();
        let result = self.spin_once(period);
        // With no clock there is nothing to measure and nothing to sleep off;
        // report zero elapsed and no overrun, which is what an unmeasured
        // period is.
        let elapsed = start_us
            .zip(self.now_us())
            .map(|(s, e)| core::time::Duration::from_micros(e.saturating_sub(s)))
            .unwrap_or_default();
        let overrun = elapsed > period;
        if !overrun && start_us.is_some() {
            platform_sleep(period - elapsed);
        }
        super::types::SpinPeriodResult {
            work: result,
            overrun,
            elapsed,
        }
    }

    /// Spin at a fixed rate with drift compensation. Blocks until halted.
    ///
    /// Uses wall-clock time to maintain the target rate. The next invocation
    /// time is accumulated (not reset to `now + period`) to prevent cumulative
    /// drift.
    ///
    /// # Example
    ///
    /// ```ignore
    /// // 100Hz control loop — blocks until halt() is called
    /// executor.spin_period(core::time::Duration::from_millis(10))?;
    /// ```
    pub fn spin_period(&mut self, period: core::time::Duration) -> Result<(), NodeError> {
        let period_us = period.as_micros().min(u64::MAX as u128) as u64;
        // Absolute next-deadline in the executor's own clock. issue 0709 — the
        // sibling of `spin`'s guard above: with no clock there is no
        // pacing, and the loop would run as fast as `spin_once` returns while
        // the caller believes it is running at `period`. A requested period
        // this build cannot honour is a configuration error, not a silent
        // busy-loop.
        let Some(start_us) = self.now_us() else {
            nros_log::log_error!(
                nros_log::get_logger("nros"),
                "spin_period: a period was requested but this build has no clock \
                 — install one with `ExecutorConfig::clock_us` (issue 0709)"
            );
            return Err(NodeError::NotInitialized);
        };
        // phase-417 W4.c — after the clock guard, not before it: a call that
        // returns an error never spun, and must not report that it did. (This
        // also moved the cancel-flag clear past the guard, which is the same
        // correction.)
        self.enter_spin_loop();
        let mut next_us = Some(start_us + period_us);

        loop {
            if self.halt_flag.load(core::sync::atomic::Ordering::SeqCst) {
                break;
            }

            self.spin_once(period);

            if let Some(next) = next_us {
                // Jitter is recorded in `spin_once` above, which this loop
                // calls every iteration -- counting it here as well would
                // double every wake on this one driver.
                if let Some(now) = self.now_us()
                    && now < next
                {
                    platform_sleep(core::time::Duration::from_micros(next - now));
                }
                // Accumulate to prevent drift (not = now + period)
                next_us = Some(next + period_us);
            }
        }
        self.exit_spin_loop();
        Ok(())
    }
}

#[cfg(feature = "alloc")]
impl<'s> Executor<'s> {
    /// Phase 110.D.b — move this Executor onto a fresh OS thread,
    /// apply a per-thread scheduling policy via the caller-supplied
    /// `apply_policy` function, and run the spin loop until
    /// `ThreadHandle::halt` fires.
    ///
    /// The function-pointer indirection on `apply_policy` lets the
    /// caller pass any platform's `PlatformScheduler::set_current_thread_policy`
    /// without forcing `Executor` to be generic over the platform —
    /// keeps the existing `Executor` type stable.
    ///
    /// Multi-executor preemption (the actual hard-RT win) comes from
    /// the OS scheduler — call `open_threaded` once per criticality
    /// tier, each with its own policy / priority. The kernel handles
    /// preemption across executors; within a single executor,
    /// dispatch remains non-preemptive (110.A–C bucketed sets).
    ///
    /// # Safety
    ///
    /// Moves `self` across thread boundaries. `Executor` contains a
    /// raw `*mut session::ConcreteSession` when constructed via
    /// `from_session_ptr`; the caller must ensure that pointer's
    /// referent stays valid across the lifetime of the spawned thread
    /// and that no other thread mutates the session concurrently.
    /// `from_session` (Owned) is safer — `ConcreteSession` ownership
    /// transfers cleanly into the thread.
    #[cfg(feature = "alloc")]
    pub unsafe fn open_threaded(
        self,
        policy: nros_platform_api::SchedPolicy,
        apply_policy: fn(
            nros_platform_api::SchedPolicy,
        ) -> Result<(), nros_platform_api::SchedError>,
        spin_period: core::time::Duration,
    ) -> ThreadHandle
    where
        // phase-271 — the spawned thread owns `self` for an unbounded lifetime,
        // so its borrowed storage must be `'static` (a leaked/`static` backing —
        // the `alloc` convenience constructors or a program-lifetime region).
        's: 'static,
    {
        let halt = self.halt_flag.clone();
        // phase-359 W10 — a platform task, not `std::thread`. The two other
        // executor-owned workers moved earlier; this is the third and last, and
        // it is the one the ABI fits best: `open_threaded` exists to give a
        // spin loop an OS SCHEDULING POLICY, which is not something a build
        // without an OS was ever going to get from `std`.
        //
        // The closure becomes a heap context because the entry point crosses C
        // as `*mut c_void`. It is reclaimed by the trampoline on exit rather
        // than leaked: unlike a tier task, this loop RETURNS — that is what
        // `halt` is for.
        let ctx = alloc::boxed::Box::into_raw(alloc::boxed::Box::new(ThreadedCtx {
            executor: self,
            policy,
            apply_policy,
            spin_period,
        }));
        // SAFETY: `ctx` stays live until the trampoline reclaims it, which
        // happens on the spawned task and only after the loop exits.
        let task = unsafe {
            nros_platform_api::task::PlatformTask::spawn(
                threaded_spin_trampoline,
                ctx as *mut core::ffi::c_void,
                OPEN_THREADED_STACK_BYTES,
                c"nros-exec".as_ptr(),
            )
        };
        let Some(task) = task else {
            // The platform refused (or cannot size) a task. Reclaim the
            // context and hand back a handle that owns nothing — `halt` and
            // `join` stay callable, which keeps the caller's shape identical to
            // the success path.
            //
            // SAFETY: nothing was spawned, so this pointer has no other owner.
            drop(unsafe { alloc::boxed::Box::from_raw(ctx) });
            return ThreadHandle { task: None, halt };
        };
        ThreadHandle {
            task: Some(task),
            halt,
        }
    }

    /// Phase 104.C.6 — wake the executor from another thread / ISR /
    /// signal handler.
    ///
    /// Sets the shared `wake_flag`. The next `spin_once` swap-clears the
    /// flag, skips the blocking wait on the primary session, and polls
    /// every session non-blockingly so whatever queued the wake is
    /// observed in a single iteration. Idempotent — multiple `wake()`
    /// calls collapse into one observed wake per `spin_once`.
    pub fn wake(&self) {
        self.wake_flag
            .store(true, core::sync::atomic::Ordering::SeqCst);
    }
}

#[cfg(feature = "alloc")]
impl<'s> Executor<'s> {
    /// Get a clone of the halt flag for use in signal handlers or other threads.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let halt = executor.halt_flag();
    /// std::thread::spawn(move || {
    ///     std::thread::sleep(Duration::from_secs(5));
    ///     halt.store(true, Ordering::SeqCst);
    /// });
    /// executor.spin(SpinOptions::default())?;
    /// ```
    pub fn halt_flag(&self) -> portable_atomic_util::Arc<portable_atomic::AtomicBool> {
        self.halt_flag.clone()
    }

    /// Phase 104.C.6 — clone of the shared wake flag for cross-thread
    /// use (signal handlers, foreign threads, future per-backend vtable
    /// wake hooks).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let wake = executor.wake_handle();
    /// std::thread::spawn(move || {
    ///     // ... compute something ...
    ///     // hand off to executor by setting the flag.
    ///     wake.store(true, Ordering::SeqCst);
    /// });
    /// loop { executor.spin_once(Duration::from_millis(100)); }
    /// ```
    pub fn wake_handle(&self) -> portable_atomic_util::Arc<portable_atomic::AtomicBool> {
        self.wake_flag.clone()
    }
}

/// Phase 110.E.b — opaque per-platform timer handle. Stores the
/// raw platform handle (POSIX `timer_t` boxed via `PosixTimerHandle`,
/// FreeRTOS `TimerHandle_t`, etc.) plus a destroy thunk so the
/// Executor can clean up without being generic over the platform.
///
/// Caller of `register_sporadic_timer` builds this via
/// `OpaqueTimerHandle::new(handle, destroy_fn)` after their
/// `PlatformTimer::create_periodic` call returns.
#[cfg(feature = "alloc")]
pub struct OpaqueTimerHandle {
    handle: *mut core::ffi::c_void,
    destroy_fn: extern "C" fn(*mut core::ffi::c_void),
}

#[cfg(feature = "alloc")]
unsafe impl Send for OpaqueTimerHandle {}
#[cfg(feature = "alloc")]
unsafe impl Sync for OpaqueTimerHandle {}

#[cfg(feature = "alloc")]
impl OpaqueTimerHandle {
    /// # Safety
    /// `handle` must be a live platform-specific timer handle that
    /// `destroy_fn` knows how to drop. Caller surrenders ownership
    /// of the underlying handle to the Executor.
    pub unsafe fn new(
        handle: *mut core::ffi::c_void,
        destroy_fn: extern "C" fn(*mut core::ffi::c_void),
    ) -> Self {
        Self { handle, destroy_fn }
    }
}

#[cfg(feature = "alloc")]
impl Drop for OpaqueTimerHandle {
    fn drop(&mut self) {
        if !self.handle.is_null() {
            (self.destroy_fn)(self.handle);
            self.handle = core::ptr::null_mut();
        }
    }
}

/// Handle returned from [`Executor::open_threaded`]. Holds the
/// spawned thread's join handle and a clone of the executor's halt
/// flag. Drop runs `halt() + join()` so the thread can't outlive the
/// handle.
#[cfg(feature = "alloc")]
pub struct ThreadHandle {
    task: Option<nros_platform_api::task::PlatformTask>,
    halt: portable_atomic_util::Arc<portable_atomic::AtomicBool>,
}

/// Default stack for an `open_threaded` spin loop. `std::thread`'s default was
/// 2 MiB; the executor's own storage is caller-carved and lives elsewhere, so
/// this carries call frames only — the same reasoning (and size) as the NuttX
/// tier spawn, which measured this against a real RTOS default.
#[cfg(feature = "alloc")]
const OPEN_THREADED_STACK_BYTES: usize = 65536;

/// What [`Executor::open_threaded`] hands its task, in place of a closure's
/// captures. Owned by the trampoline, which reclaims it when the loop exits.
#[cfg(feature = "alloc")]
struct ThreadedCtx {
    executor: Executor<'static>,
    policy: nros_platform_api::SchedPolicy,
    apply_policy: fn(nros_platform_api::SchedPolicy) -> Result<(), nros_platform_api::SchedError>,
    spin_period: core::time::Duration,
}

/// The spawned spin loop.
///
/// # Safety
/// `arg` must be the `Box<ThreadedCtx>` raw pointer `open_threaded` created,
/// passed exactly once.
#[cfg(feature = "alloc")]
unsafe extern "C" fn threaded_spin_trampoline(
    arg: *mut core::ffi::c_void,
) -> *mut core::ffi::c_void {
    // SAFETY: the caller's contract — this is the pointer `open_threaded`
    // leaked, and the task is the only consumer of it.
    let mut ctx = unsafe { alloc::boxed::Box::from_raw(arg as *mut ThreadedCtx) };
    // Apply the requested OS scheduling policy to this fresh task. Failure is
    // reported but not propagated — a runtime that fails to lift to SCHED_FIFO
    // still spins correctly at SCHED_OTHER (just without RT guarantees).
    let _ = (ctx.apply_policy)(ctx.policy);
    // phase-417 W4.c — this loop owns its own iteration, so it is a spin and
    // must say so. NOT `enter_spin_loop()`: that clears the cancel flag, and
    // `open_threaded` hands the caller a `ThreadHandle` whose `halt()` may
    // already have fired before this task was scheduled. Raising `is_spinning`
    // without touching the cancel bit is the honest report here.
    ctx.executor
        .spinning
        .store(true, core::sync::atomic::Ordering::SeqCst);
    while !ctx.executor.is_halted() {
        ctx.executor.spin_once(ctx.spin_period);
    }
    ctx.executor.exit_spin_loop();
    core::ptr::null_mut()
}

#[cfg(feature = "alloc")]
impl ThreadHandle {
    /// Signal the spawned executor thread to stop. The thread exits
    /// on its next `spin_once` iteration.
    pub fn halt(&self) {
        self.halt.store(true, core::sync::atomic::Ordering::SeqCst);
    }

    /// Wait for the spawned task to exit. After `join`, calling it again is a
    /// no-op.
    ///
    /// phase-359 W10 — was `std::thread::Result<()>`, which carried a panic
    /// payload this can no longer produce: a platform task has no unwinding
    /// join. Same two outcomes, an error type that does not require `std` —
    /// the trade `signal_fd` already made in this campaign. `NotInitialized`
    /// means the platform refused to host the task at spawn time — nothing was
    /// started, so there is nothing to wait for. (An existing variant rather
    /// than a new one: `NodeError` is mapped across the C and C++ FFI, so a new
    /// variant is a gate-checked ABI change and this needs no new meaning.)
    pub fn join(mut self) -> Result<(), NodeError> {
        self.halt();
        match self.task.take() {
            Some(t) => {
                t.join();
                Ok(())
            }
            None => Err(NodeError::NotInitialized),
        }
    }
}

#[cfg(feature = "alloc")]
impl Drop for ThreadHandle {
    fn drop(&mut self) {
        self.halt.store(true, core::sync::atomic::Ordering::SeqCst);
        if let Some(t) = self.task.take() {
            t.join();
        }
    }
}

// SAFETY: Phase 110.D.b — `Executor` contains a raw `*mut
// session::ConcreteSession` only on the `from_session_ptr` (Borrowed)
// path; the `from_session` (Owned) path is plain Send-able. The
// `unsafe fn open_threaded` entry point documents the safety
// contract for Borrowed sessions; for Owned sessions the Send claim
// is unconditional.
// phase-359 W10 — `alloc`, not `std`: this assertion exists for
// `open_threaded`, which now hands the executor to a PLATFORM task. The
// crossing is the same one; only the thing doing the crossing changed.
#[cfg(feature = "alloc")]
unsafe impl<'s> Send for Executor<'s> {}

// =============================================================================
// Phase 110.F — `OsPriorityWorker` + `WorkItem`
// =============================================================================

// phase-359 W10 — `OsPriorityWorker` / `WorkItem` moved to
// `super::os_priority` and were rewritten off `std::thread` + `std::sync::mpsc`
// + `HashMap` onto the platform task ABI, a bounded `heapless` mailbox and a
// `NodeWake` doorbell. The capability is no longer std-only; see that module
// for what changed semantically (bounded mailbox, capacity-limited pool, and
// no pool on a platform without a wake primitive).

impl<'s> Drop for Executor<'s> {
    fn drop(&mut self) {
        // Issue 0790 — a teardown that never went through `close()` still gets
        // its ordered shutdown hooks, and gets them in the SAME order. The C
        // API's `nros_executor_fini` is exactly that path: it drops the
        // executor in place and leaves the session to `nros_support_fini`, so
        // without this the whole facility would be silently inert for every C
        // entry. Entities are still live at the top of `drop` — the component
        // cells and the arena entries below are what tears them down — so this
        // is the last moment a pre-shutdown hook can do what it exists to do.
        //
        // After a normal `close()` both tables are already empty and these two
        // calls are a pair of `None` scans.
        self.run_shutdown_hooks(super::types::ShutdownPhase::Pre);
        // Phase 258 (Track 2, 2a) — release executor-owned component cells
        // first (before the arena entries), so a component's `drop`
        // trampoline can still touch its own (cell-owned) state. Each slot
        // owns a leaked `Arc<ComponentCell>`; its `drop` reconstitutes +
        // drops that Arc exactly once.
        for slot in self.component_slots.iter() {
            // SAFETY: `slot.state` is the leaked cell enrolled via
            // `enroll_component`; `slot.drop` is its matching trampoline, run
            // exactly once here (slots are not removed before Drop).
            unsafe {
                (slot.drop)(slot.state);
            }
        }
        let arena_ptr = self.arena.as_mut_ptr() as *mut u8;
        for meta in self.entries.iter().flatten() {
            // SAFETY: each entry was written by `ptr::write` in `add_*` and
            // has not been dropped yet. `drop_fn` matches the concrete type.
            unsafe {
                let data_ptr = arena_ptr.add(meta.offset);
                (meta.drop_fn)(data_ptr);
            }
        }
        // Issue 0790 — the post-teardown half, after the entities are gone.
        // Same "already empty after `close()`" note as the pre pass above.
        self.run_shutdown_hooks(super::types::ShutdownPhase::Post);
        // Issue 1385 — LAST in the body, and that is the whole point: the
        // context the backend holds is `wake_ctx`, a field, so it is still
        // alive for every line above and is freed only after `drop` returns.
        // Clearing here is therefore the SHORTEST window in which a callback
        // can fire into live state, not the longest — entity teardown above
        // may still be talking to the backend.
        //
        // A no-op after `close()` (the latch), and a no-op for an executor
        // that never installed. For the C path this is the only clear there
        // is: `rclc_executor_fini` runs this `drop_in_place` and THEN
        // zero-fills the storage the callback pointed into.
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        self.clear_wake_signal();
        // phase-467 Row 8 — and the graph-change target, before the box it
        // names is freed with this executor.
        #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
        self.clear_graph_change_signal();
    }
}

#[cfg(all(test, feature = "std", not(feature = "rmw-cffi")))]
mod dispatch_registry_tests {
    //! Phase 216 follow-up — `Executor::register_dispatch_slot` +
    //! `Executor::dispatch_callback` round-trip.
    //!
    //! Uses `MockSession` (same pattern as
    //! `lifecycle_services::tests::mock_integration`) so the test
    //! doesn't need a live RMW backend. Gated `not(feature =
    //! "rmw-cffi")` because under `rmw-cffi` the `ConcreteSession`
    //! type alias resolves to the cffi session, which `MockSession`
    //! can't impersonate.

    extern crate alloc;

    use super::Executor;
    use crate::mock::MockSession;
    use std::sync::Mutex;

    static CAPTURED: Mutex<alloc::vec::Vec<(usize, alloc::vec::Vec<u8>, usize)>> =
        Mutex::new(alloc::vec::Vec::new());

    /// Test trampoline matching the per-Node
    /// `__nros_node_<pkg>_on_callback` ABI shape (Phase 216.A.5).
    unsafe extern "C" fn recording_on_callback(
        state: *mut core::ffi::c_void,
        cb_id_ptr: *const u8,
        cb_id_len: usize,
        ctx: *mut core::ffi::c_void,
    ) {
        // SAFETY: caller (test body below) holds storage live;
        // `cb_id_ptr..len` points into a `&str` literal.
        let cb_id_bytes = unsafe { core::slice::from_raw_parts(cb_id_ptr, cb_id_len).to_vec() };
        let mut guard = CAPTURED.lock().expect("CAPTURED poisoned");
        guard.push((state as usize, cb_id_bytes, ctx as usize));
    }

    #[test]
    fn register_dispatch_slot_round_trip() {
        let session = MockSession::new();
        let mut executor: Executor = Executor::from_session(session);

        // Pre-condition: empty registry.
        assert_eq!(executor.dispatch_slot_count(), 0);

        // Two distinct "states" so we prove every slot gets called
        // with its OWN state.
        let mut state_blob_a: u32 = 0xABCD_0001;
        let mut state_blob_b: u32 = 0xABCD_0002;
        let state_a_ptr = &mut state_blob_a as *mut u32 as *mut core::ffi::c_void;
        let state_b_ptr = &mut state_blob_b as *mut u32 as *mut core::ffi::c_void;

        executor
            .register_dispatch_slot(state_a_ptr, recording_on_callback)
            .expect("register slot A");
        executor
            .register_dispatch_slot(state_b_ptr, recording_on_callback)
            .expect("register slot B");
        assert_eq!(executor.dispatch_slot_count(), 2);

        let mut ctx_blob: u32 = 0xFEED_BEEF;
        let ctx_ptr = &mut ctx_blob as *mut u32 as *mut core::ffi::c_void;
        let cb_id = "/talker/timer/publish";

        CAPTURED.lock().expect("CAPTURED poisoned").clear();
        executor.dispatch_callback(cb_id, ctx_ptr);

        let captured = CAPTURED.lock().expect("CAPTURED poisoned").clone();
        assert_eq!(
            captured.len(),
            2,
            "every registered slot must be invoked — linear scan, \
             no self-filter at the registry layer"
        );
        // The carved dispatch table iterates in insertion order.
        assert_eq!(captured[0].0, state_a_ptr as usize, "slot A's state");
        assert_eq!(captured[1].0, state_b_ptr as usize, "slot B's state");
        for (idx, capture) in captured.iter().enumerate() {
            assert_eq!(
                capture.1.as_slice(),
                cb_id.as_bytes(),
                "slot {idx} cb_id bytes round-trip"
            );
            assert_eq!(
                capture.2, ctx_ptr as usize,
                "slot {idx} ctx pointer round-trip"
            );
        }
    }

    #[test]
    fn register_dispatch_slot_capacity_full() {
        let session = MockSession::new();
        let mut executor: Executor = Executor::from_session(session);

        let mut state_blob: u32 = 0;
        let state_ptr = &mut state_blob as *mut u32 as *mut core::ffi::c_void;

        // `MAX_NODES` slots fit; the next one must error.
        for _ in 0..crate::config::MAX_NODES {
            executor
                .register_dispatch_slot(state_ptr, recording_on_callback)
                .expect("under-capacity push must succeed");
        }
        assert_eq!(executor.dispatch_slot_count(), crate::config::MAX_NODES);
        let overflow = executor.register_dispatch_slot(state_ptr, recording_on_callback);
        assert!(
            overflow.is_err(),
            "over-capacity push must return Err(()) — raise \
             NROS_EXECUTOR_MAX_NODES at build time to grow the registry"
        );
    }
}

/// Phase 274.W1 — borrowed-executor session sharing + active-groups gating.
///
/// Validates three primitives introduced for RFC-0015 Model 1:
/// - `session_handle` / `open_with_session_handle` (Borrowed session store —
///   the borrowed executor does not own or close the session on drop).
/// - `set_active_groups` + `group_active` (callback-group filter gating).
///
/// Uses `MockSession` (same pattern as `dispatch_registry_tests`); gated
/// `not(feature = "rmw-cffi")` for the same reason.
#[cfg(all(test, feature = "std", not(feature = "rmw-cffi")))]
mod p274_w1_tier_executor_tests {
    use super::Executor;
    use crate::mock::MockSession;

    #[test]
    fn session_handle_borrowed_executor_shares_session_ptr() {
        // Open the primary executor (session owner).
        let session = MockSession::new();
        let mut primary = Executor::from_session(session);

        // Record the primary's session pointer for later comparison.
        let primary_session_ptr = primary.session_ptr();

        // Get the opaque session handle (into_raw for C FFI; here we keep it raw).
        let handle = primary.session_handle();

        // Open a second executor over the SAME session (Borrowed — does not own it).
        // SAFETY: `primary` (the session owner) outlives `borrowed` in this scope.
        let mut borrowed = unsafe { Executor::open_with_session_handle(handle) };

        // Both executors must expose the same session pointer.
        assert_eq!(
            primary.session_ptr(),
            borrowed.session_ptr(),
            "borrowed executor must share the primary's session pointer"
        );
        assert_eq!(
            borrowed.session_ptr(),
            primary_session_ptr,
            "session pointer must be stable across session_handle / open_with_session_handle"
        );

        // Drop the borrowed executor — the primary's session must remain valid.
        drop(borrowed);

        // Primary still exposes the same session pointer (session was NOT closed by drop).
        assert_eq!(
            primary.session_ptr(),
            primary_session_ptr,
            "primary session pointer must be unchanged after dropping the borrowed executor"
        );
    }

    /// An oversized group name is REFUSED and fails CLOSED.
    ///
    /// issue 1172 — this used to be `if s.push_str(g).is_ok()`, which dropped
    /// the name and left the tier filtering on a set that silently lacked it.
    /// Two things are asserted because either alone would let the bug back:
    /// the call must REPORT the failure, and the resulting filter must accept
    /// NOTHING rather than fall back to the wildcard, which would be
    /// fail-open.
    #[test]
    fn an_oversized_group_name_is_refused_and_fails_closed() {
        let session = MockSession::new();
        let mut primary = Executor::from_session(session);
        let handle = primary.session_handle();
        // SAFETY: primary outlives borrowed.
        let mut borrowed = unsafe { Executor::open_with_session_handle(handle) };

        // `GroupName` is `heapless::String<32>`.
        let too_long = "g".repeat(33);
        assert!(
            borrowed
                .set_active_groups(&[("n", "/", too_long.as_str())])
                .is_err(),
            "an oversized group name must be reported, not dropped"
        );
        assert!(
            !borrowed.group_active("n", "/", &too_long),
            "the name that did not fit must not be active"
        );
        assert!(
            !borrowed.group_active("n", "/", "anything-else"),
            "a refused filter must accept NOTHING — falling back to the \
             wildcard would run every callback on this tier"
        );
    }

    #[test]
    fn set_active_groups_gates_group_active() {
        let session = MockSession::new();
        let mut primary = Executor::from_session(session);
        let handle = primary.session_handle();

        // SAFETY: primary outlives borrowed.
        let mut borrowed = unsafe { Executor::open_with_session_handle(handle) };

        // Before gating: wildcard — every group is accepted.
        assert!(
            borrowed.group_active("n", "/", "ctrl"),
            "default (wildcard) must accept every group"
        );
        assert!(
            borrowed.group_active("n", "/", "telem"),
            "default (wildcard) must accept every group"
        );

        // Gate borrowed to only the "ctrl" group (one-tier filter).
        borrowed
            .set_active_groups(&[("n", "/", "ctrl")])
            .expect("fits");

        assert!(
            borrowed.group_active("n", "/", "ctrl"),
            "\"ctrl\" must be active after set_active_groups([\"ctrl\"])"
        );
        assert!(
            !borrowed.group_active("n", "/", "telem"),
            "\"telem\" must NOT be active when only \"ctrl\" is gated"
        );
        assert!(
            !borrowed.group_active("n", "/", "planning"),
            "\"planning\" must NOT be active when only \"ctrl\" is gated"
        );

        // Primary is unaffected (it still uses the wildcard).
        assert!(
            primary.group_active("n", "/", "telem"),
            "primary executor must remain unaffected (still wildcard)"
        );

        // Clear the filter on borrowed — back to wildcard.
        borrowed
            .set_active_groups(&[])
            .expect("the wildcard always fits");
        assert!(
            borrowed.group_active("n", "/", "telem"),
            "after clearing, borrowed must accept all groups again"
        );
    }

    #[test]
    fn session_handle_into_raw_from_raw_round_trip() {
        let session = MockSession::new();
        let mut primary = Executor::from_session(session);
        let session_ptr = primary.session_ptr();

        let handle = primary.session_handle();
        let raw = handle.into_raw();

        // into_raw must return a non-null pointer matching the session address.
        assert!(!raw.is_null());
        assert_eq!(raw as *mut _, session_ptr);

        // from_raw must reconstruct a handle that opens the same borrowed executor.
        // SAFETY: primary still owns the session, raw is its address.
        let handle2 = unsafe { crate::executor::SessionHandle::from_raw(raw) };
        let mut borrowed = unsafe { Executor::open_with_session_handle(handle2) };
        assert_eq!(
            borrowed.session_ptr(),
            session_ptr,
            "from_raw reconstructed handle must open executor on the same session"
        );
    }
}

/// W3b.5 — snapshot the monitored publishers' counters before a dispatch
/// (only when a latency contract exists; otherwise a zeroed array that
/// `attribute_latency` never reads).
fn snapshot_pub_counts(
    table: &'static [super::monitor::MonitorSpec],
    active: bool,
) -> [u32; super::monitor::MAX_MONITORS] {
    let mut counts = [0u32; super::monitor::MAX_MONITORS];
    if active {
        for (k, spec) in table.iter().take(super::monitor::MAX_MONITORS).enumerate() {
            counts[k] = spec.cell.count.load(core::sync::atomic::Ordering::Relaxed);
        }
    }
    counts
}

/// W3b.5 — attribute one dispatch's elapsed time to every monitored
/// publisher whose counter advanced during it (an upper bound on the
/// node-path take → publish latency: the callback deserialized, ran, and
/// published within `elapsed_us`).
fn attribute_latency(
    table: &'static [super::monitor::MonitorSpec],
    active: bool,
    counts_before: &[u32; super::monitor::MAX_MONITORS],
    elapsed_us: u32,
) {
    if !active {
        return;
    }
    for (k, spec) in table.iter().take(super::monitor::MAX_MONITORS).enumerate() {
        if spec.max_latency_ms == 0 {
            continue;
        }
        let now = spec.cell.count.load(core::sync::atomic::Ordering::Relaxed);
        if now != counts_before[k] {
            spec.cell
                .max_latency_us
                .fetch_max(elapsed_us, core::sync::atomic::Ordering::Relaxed);
        }
    }
}

/// W3b.5 — enforce the bound SC's deadline after a dispatch. A miss maps
/// through [`DeadlineAction`](super::sched_context::DeadlineAction):
/// `Warn`/`Skip`/`Fault` all report; `Skip` additionally masks the SC's
/// remaining callbacks for this cycle; `Fault` invokes the fault hook
/// (panic when none is registered).
/// phase-503 -- hand a route deadline verdict of `table[row]` to the reaction
/// hook, if one is installed (and the monitors are armed: the caller passes
/// `None` otherwise). Shared by the overdue check after the park and the
/// completion verdict of a late supervised route (`route_judge`).
fn call_route_reaction(
    hook: Option<(super::monitor::ReactionHookFn, *mut core::ffi::c_void)>,
    table: &[super::monitor::MonitorSpec],
    row: usize,
    v: &super::monitor::Violation,
) {
    let Some((f, ctx)) = hook else { return };
    let spec = &table[row];
    let ev = super::monitor::ReactionEvent {
        reaction_id: spec.reaction_id as u32,
        row: row as u32,
        rule_code: super::monitor::rule_code(v.rule),
        measured_ms: v.measured,
        declared_ms: v.declared,
        mechanism: spec.mechanism,
    };
    // SAFETY: `f` and `ctx` were registered together through
    // `set_reaction_hook`, whose caller keeps `ctx` valid for the executor's
    // life; the event lives across the call.
    unsafe { f(&ev, ctx) };
}

fn check_deadline_miss(
    sc: Option<&super::sched_context::SchedContext>,
    sc_idx: usize,
    elapsed_us: u32,
    misses: &mut heapless::Vec<super::monitor::Violation, { super::monitor::MAX_VIOLATIONS }>,
    skipped_scs: &mut u64,
    fault_fn: Option<fn(&super::monitor::Violation)>,
    reaction_hook: Option<(super::monitor::ReactionHookFn, *mut core::ffi::c_void)>,
) {
    use super::sched_context::DeadlineAction;
    let Some(sc) = sc else { return };
    let Some(deadline_us) = sc.deadline_us.get().map(|nz| nz.get()) else {
        return;
    };
    if matches!(sc.deadline_action, DeadlineAction::Ignore) || elapsed_us <= deadline_us {
        return;
    }
    let v = super::monitor::Violation {
        rule: "deadline-miss-runtime",
        // Entries carry no name at this altitude; the SC slot stands in.
        fqn: "sched-context",
        measured: elapsed_us,
        declared: deadline_us,
    };
    match sc.deadline_action {
        DeadlineAction::Ignore => {}
        DeadlineAction::Warn => {
            let _ = misses.push(v);
        }
        DeadlineAction::Skip => {
            if sc_idx < 64 {
                *skipped_scs |= 1u64 << sc_idx;
            }
            let _ = misses.push(v);
        }
        DeadlineAction::Fault => {
            if let Some(f) = fault_fn {
                f(&v);
                let _ = misses.push(v);
            } else if let Some((f, ctx)) = reaction_hook {
                // phase-503 — the reaction hook is the fault path a C or C++
                // image can install; reaction id 0, the SC slot as the row.
                let ev = super::monitor::ReactionEvent {
                    reaction_id: super::monitor::REACTION_NONE as u32,
                    row: sc_idx as u32,
                    rule_code: super::monitor::rule_code(v.rule),
                    measured_ms: elapsed_us / 1_000,
                    declared_ms: deadline_us / 1_000,
                    mechanism: super::monitor::MECHANISM_EXECUTOR,
                };
                // SAFETY: as in `check_route_deadlines`.
                unsafe { f(&ev, ctx) };
                let _ = misses.push(v);
            } else {
                panic!(
                    "nros: deadline fault — dispatch ran {elapsed_us} us past a {deadline_us} us deadline"
                );
            }
        }
    }
}

// Timer-accounting clock default (issue: no_std tiers with no `clock_us`
// credited each spin the REQUESTED timeout — spin.rs `delta_us` fallback —
// so shared-session wakes made low-rate timers fire early (a 100 ms timer
// at ~67 ms on Zephyr native_sim) and tick rounding made fast tiers fire
// late. Measured on that native_sim image; mechanism documented at the
// fallback site.)
//
// Every platform port exports `nros_platform_clock_ns` through the same
// linkage contract the wake primitives rely on (`nros_platform_export_clock!`
// in nros-platform-cffi), so an rmw-cffi no_std build can safely default the
// executor clock to it; `ExecutorConfig::clock_us` stays as an override.
#[cfg(feature = "rmw-cffi")]
unsafe extern "C" {
    fn nros_platform_clock_ns() -> u64;
}

#[cfg(feature = "rmw-cffi")]
fn default_platform_clock_us() -> u64 {
    // SAFETY: bare query of the platform's monotonic ns counter; the symbol
    // is guaranteed by whichever platform port linked the binary (the same
    // contract `nros_platform_wake_*` already depends on).
    //
    // RFC-0073 made the ABI nanoseconds; the executor's own accounting is
    // still microseconds (`clock_us_fn`, `delta_us`), so the division lives
    // here rather than being pushed into every port.
    unsafe { nros_platform_clock_ns() / 1_000 }
}

/// Sleep, through the platform ABI.
///
/// phase-359 W10 — the spin loops used `std::thread::sleep`. Every port already
/// exports `nros_platform_sleep_us` (the ABI's own pacing primitive, the one an
/// RTOS build has always used), so a hosted loop and an embedded one now pace
/// the same way. The µs entry point is used rather than `_ms` because
/// `spin_one_period_timed` sleeps off a remainder, which rounds badly at
/// millisecond granularity on short periods.
#[cfg(feature = "alloc")]
pub(crate) fn platform_sleep(d: core::time::Duration) {
    unsafe extern "C" {
        fn nros_platform_sleep_us(us: usize);
    }
    let us = d.as_micros().min(usize::MAX as u128) as usize;
    if us == 0 {
        return;
    }
    // SAFETY: a bare pacing call with no pointer arguments, guaranteed by
    // whichever port linked the binary — the same contract the clock and wake
    // symbols in this file already rely on.
    unsafe { nros_platform_sleep_us(us) }
}

/// A monotonic µs reader, or `None` when this build has no clock at all.
///
/// phase-359 W10 — one provider, chosen by what is LINKED rather than by which
/// flavour the crate was built in. W4 unified the executor's clock ACCESSOR and
/// said the provider was the last piece; this is it.
///
/// `rmw-cffi` means a platform port is linked, and every port exports
/// `nros_platform_clock_ns` under the same contract the wake primitives use —
/// so a hosted build reads the same counter an embedded one does, instead of
/// `Instant` on one and the platform on the other. `Instant` survives only
/// where there is no port to ask: `std` without `rmw-cffi`.
///
/// phase-359 W10 follow-up — this comment claimed the metadata PROBE was that
/// configuration, and **it is not**. The probe's generated manifest deps
/// `nros-platform-cffi` with `posix-c-port` (issue 0288 layer 5, so it links),
/// and its `nros` resolves with `rmw-cffi` ON — feature-unified from the
/// component's board crate. Measured on a real probe tree: `alloc default
/// macros rmw-cffi ros-humble std`. It takes the PORT arm.
///
/// What is real: `nros-rmw-metadata` and `nros-tests` do resolve `nros` with
/// `std` and no `rmw-cffi`, and have no port crate in their graphs. But nothing
/// in either uses this arm — deleting it and building the workspace
/// `--all-targets` is clean, and there is no in-tree caller of
/// `nros::time::now` at all. So the arm serves an OUT-OF-TREE contract only: a
/// consumer with `std`, no `rmw-cffi`, and its own `Session`.
pub(crate) fn default_clock_us_fn() -> Option<fn() -> u64> {
    #[cfg(feature = "rmw-cffi")]
    {
        Some(default_platform_clock_us)
    }
    #[cfg(not(feature = "rmw-cffi"))]
    {
        None
    }
}

// =============================================================================
// phase-425 W3b — the `/clock` time source's executor half.
//
// Its OWN impl block, gated on `sim-time`, because the methods were first
// written next to `declare_parameter` — which lives in a
// `#[cfg(feature = "param-store")]` block, so `reconcile_ros_time_source`
// silently disappeared in every combo without parameter services, including the
// one `spin_once` calls it from.
// =============================================================================
#[cfg(all(feature = "sim-time", any(has_rmw, test)))]
impl<'s> Executor<'s> {
    /// phase-425 W3b — bring the `/clock` subscription in line with the last
    /// requested `use_sim_time`.
    ///
    /// Called at the head of every spin, and cheap when there is nothing to do:
    /// the common case is one bool comparison. It is a RECONCILE rather than an
    /// action at the request site because the request routinely arrives before
    /// there is a node to hang the subscription on — `nros::main!` emits
    /// `apply_param_services` before its per-node `register` calls, by design,
    /// so the store exists when each cell is created.
    ///
    /// Turning it off stops SAMPLES from being installed; the subscription
    /// itself stays, because the executor has no entity removal and inventing
    /// one for this would be a much larger change than the switch is worth. The
    /// gate is `time_source::set_active`, which the subscription callback reads.
    ///
    /// Turning it off also does NOT clear the override: a node that stops
    /// listening keeps the last simulated time rather than jumping back to the
    /// wall clock, which every ROS-time timer would otherwise absorb as a
    /// backwards jump.
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    pub(crate) fn reconcile_ros_time_source(&mut self) {
        // An executor nobody told about `use_sim_time` has NO opinion, and the
        // gate is process-global, so writing its default here is not a no-op --
        // it is one executor overruling another. Say nothing until asked.
        if !self.sim_time_stated {
            return;
        }
        if self.sim_time_requested == crate::time_source::is_active()
            && (!self.sim_time_requested || self.sim_time_source.is_some())
        {
            return;
        }
        crate::time_source::set_active(self.sim_time_requested);
        if !self.sim_time_requested {
            // phase-430 W1 — the source is no longer wanted, so its silence is
            // no longer a symptom. Disarming here (rather than only re-arming
            // on attach) is what makes a later re-attach start a FRESH
            // interval: the watch that was counting is put down, not paused.
            self.sim_time_silence.disarm();
            return;
        }
        if self.sim_time_source.is_none() {
            // No node yet — stay pending and try again next spin. Not an error:
            // it is the ordinary order of a generated entry, which declares
            // parameters before it registers components.
            if self.nodes.is_empty() {
                return;
            }
            if let Ok(handle) = self.install_ros_time_source(
                super::node_record::NodeId::PRIMARY,
                crate::time_source::CLOCK_TOPIC,
            ) {
                self.sim_time_source = Some(handle);
                // phase-430 W1 — the interval starts HERE, at attach, and not
                // at construction: before the subscription exists there is
                // nothing to be silent about, so counting from boot would
                // accuse an image that spent the interval bringing a transport
                // up.
                self.sim_time_silence.arm();
            }
        } else {
            // Re-attached: `use_sim_time` went false and back to true while the
            // subscription (which the executor cannot remove) stayed. W1 asks
            // for the one-shot to reset in exactly this case.
            self.sim_time_silence.arm();
        }
    }

    /// phase-430 W1 — credit one spin's elapsed time to the silence watch and
    /// emit the diagnostic if this is the spin that crosses the threshold.
    ///
    /// `delta_us` is the executor's OWN per-spin elapsed measure — the same one
    /// every wall timer on this executor accumulates, including its "no clock,
    /// credit the requested timeout" fallback. See
    /// [`SILENCE_WARN_US`](crate::time_source::SILENCE_WARN_US) for why that is
    /// the unit and not a spin count or an independent wall clock.
    ///
    /// Scope: the source the EXECUTOR installed for `use_sim_time`. An
    /// application that calls
    /// [`Node::install_ros_time_source`](super::node::Node::install_ros_time_source)
    /// directly is not watched, because the line this would print names
    /// `use_sim_time`, and that application never set it — the honest
    /// diagnostic for the explicit path would be a different sentence, and
    /// inventing one nobody asked for is how a warning becomes noise.
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    fn note_sim_time_silence(&mut self, delta_us: u64) {
        if self.sim_time_silence.tick(
            delta_us,
            nros_core::clock::Clock::is_ros_time_override_active(),
        ) {
            crate::time_source::report_silence(crate::time_source::CLOCK_TOPIC);
        }
    }

    /// phase-430 W1 — how many times this executor has reported that
    /// `use_sim_time` is on with no `/clock` sample.
    ///
    /// The count rather than a bool, and an accessor rather than a log grep: a
    /// diagnostic whose contract is "exactly once" needs an assertion that can
    /// tell one from two, and a log sink is not present on every target that
    /// runs the test. It is also the question an application supervising its
    /// own configuration would ask.
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    pub fn sim_time_silence_warnings(&self) -> u32 {
        self.sim_time_silence.reports()
    }

    /// phase-425 W3b — re-read `use_sim_time` from the parameter store.
    ///
    /// Called after a parameter service actually handled something, which is
    /// what makes a runtime `ros2 param set <node> use_sim_time true` work
    /// without a per-spin scan of the store.
    ///
    /// phase-430 W3 / issue 1202 — the declaration path calls it too, through
    /// `note_reserved_parameter`, once the store has accepted the write. It
    /// used to record the value directly from the caller's argument, which is
    /// the same thing only while the store never refuses. One read for both
    /// paths; a second spelling is the drift this function exists to prevent.
    /// `pub(crate)` for the same reason: a test that changes the store directly
    /// needs the entry point a parameter service uses, not a copy of it.
    #[cfg(all(feature = "sim-time", feature = "param-store", any(has_rmw, test)))]
    pub(crate) fn refresh_use_sim_time_from_store(&mut self) {
        // phase-426 W1 — the store is keyed by NODE, and the simulated clock is
        // not. This function is where those two facts meet, so the rule is
        // stated here rather than left to whichever call site got there first.
        //
        // `use_sim_time` is a per-node parameter in ROS 2, and rclcpp means it:
        // every `Node` builds its own `TimeSource` over its own `Clock`, so two
        // nodes composed into one process CAN be configured differently and
        // stamp messages from different clocks at the same instant. This tree
        // deliberately does not follow that (phase-425): "the override is
        // process-global — one simulated clock per image, the model
        // `nros_core::Clock` already documents — so there is nothing to attach
        // to and nothing to fan out." That is the right trade for an image with
        // a fixed RAM budget, and it makes "whose `use_sim_time`?" a question
        // rclcpp never has to answer and this executor now does.
        //
        // ANY node asking arms the one source. Two reasons, and the second is
        // the binding one:
        //
        //   * it is the only rule the CALLERS can implement. `note_param_
        //     services_ran` fires after a runtime `ros2 param set` and knows
        //     only that N requests were handled — not which node was written.
        //     A last-writer-wins rule would need a writer identity that does
        //     not reach here, so it would silently degrade to "whatever node 0
        //     says", which is the default-to-primary bug phase-426 W1 exists to
        //     remove.
        //   * one node still wanting simulated time is a reason to keep the
        //     source attached, and detaching is the destructive direction:
        //     phase-425 already records that turning it off "stops SAMPLES, not
        //     the subscription", precisely so a mid-run change does not read as
        //     a clock jump.
        //
        // The scan is over the executor's own node table, which is the same
        // `u8` index space `NodeKey` wraps, so there is one node identity here
        // and not two.
        let Some(params) = self.params.as_deref() else {
            return;
        };
        let mut stated = false;
        let mut enable = false;
        // A `NodeId` IS the index into this table (`NodeId::index`), so the
        // enumeration is the key space — no second derivation of the number.
        //
        // `.max(1)` because `NodeId::PRIMARY` is IMPLICIT: the executor's node
        // table starts empty and a parameter can be declared on the primary
        // node before any `create_node` puts a record in it. Scanning only the
        // table would then find nothing and leave `sim_time_stated` false, so a
        // `use_sim_time` declared before the first node would never arm the
        // source — which `use_sim_time_attaches_and_detaches_the_clock_source`
        // catches, since its whole first half runs while "there is still no
        // node". Slot 0 is always a legitimate key; at worst the lookup misses.
        for idx in 0..self.nodes.len().max(1) {
            let key = nros_params::NodeKey::new(idx as u8);
            if let Some(v) = params
                .server
                .get_bool(key, crate::time_source::USE_SIM_TIME_PARAM)
            {
                stated = true;
                enable |= v;
            }
        }
        if stated {
            self.sim_time_requested = enable;
            self.sim_time_stated = true;
        }
    }

    /// phase-425 W3b — the installed `/clock` subscription, if any.
    ///
    /// The HANDLE rather than a bool, because "did we subscribe twice" is the
    /// question a reconciliation loop has to be able to answer: a second
    /// registration takes a new slot, so a stable handle across spins is the
    /// evidence that the loop is idempotent.
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    pub fn ros_time_source_handle(&self) -> Option<HandleId> {
        self.sim_time_source
    }

    /// phase-425 W3b — whether a `/clock` subscription is currently installed.
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    pub fn ros_time_source_installed(&self) -> bool {
        self.sim_time_source.is_some()
    }

    /// phase-425 W3 — subscribe `topic` and install every sample as this
    /// image's ROS time. The registration behind
    /// [`Node::install_ros_time_source`](super::node::Node::install_ros_time_source)
    /// and behind the `use_sim_time` reconciliation, so both spell the QoS and
    /// the conversion exactly once.
    #[cfg(all(feature = "sim-time", any(has_rmw, test)))]
    pub(crate) fn install_ros_time_source(
        &mut self,
        node_id: super::node_record::NodeId,
        topic: &str,
    ) -> Result<HandleId, NodeError> {
        self.register_subscription_buffered_on::<
            nros_rosgraph_msgs::msg::Clock,
            _,
            { crate::config::DEFAULT_RX_BUF_SIZE },
        >(
            node_id,
            topic,
            QoSProfile::clock_default(),
            |msg: &nros_rosgraph_msgs::msg::Clock| {
                // The `use_sim_time` gate is read HERE rather than by removing
                // the subscription, because there is no entity removal. An
                // image that never touches `use_sim_time` and installs the
                // source explicitly is active by default.
                if !crate::time_source::is_active() {
                    return;
                }
                if let Some(nanos) =
                    crate::time_source::override_nanos(msg.clock.sec, msg.clock.nanosec)
                {
                    nros_core::clock::Clock::set_ros_time_override(nanos);
                }
            },
            None, // no group — node default
            None, // the configured default RX buffer, unchanged
        )
    }
}

// ============================================================================
// phase-417 W4.c — cancel / is_spinning
// ============================================================================
//
// Same gate as `executor::tests`, exactly: `ConcreteSession` is `MockSession`
// only while no rmw-* feature is unified in (see `executor/mod.rs`), and
// `from_session_with` / `halt_flag` are `alloc`. No `std` gate — `cfg(test)`
// already means a hosted harness, which is why `lib.rs` brings `std` in under
// `test` as well. (It said "exactly" while missing `alloc`, and `std` was not in
// scope: 20 errors, hidden by feature unification under `--workspace`.)
#[cfg(all(test, feature = "alloc", not(feature = "rmw-cffi")))]
mod cancel_tests {
    use super::Executor;
    use crate::{executor::types::ExecutorConfig, mock::MockSession};

    /// The core has no default clock and says so (issue 0709), so a test that
    /// measures elapsed time brings its own — the same seam a board uses.
    fn test_clock_us() -> u64 {
        use std::{sync::OnceLock, time::Instant};
        static EPOCH: OnceLock<Instant> = OnceLock::new();
        EPOCH.get_or_init(Instant::now).elapsed().as_micros() as u64
    }

    fn executor() -> Executor<'static> {
        let cfg = ExecutorConfig::default().clock_us(test_clock_us);
        Executor::from_session_with(MockSession::new(), &cfg)
    }

    /// A fresh executor is neither cancelled nor spinning — the two questions
    /// are independent, and this is the state where both answers are `false`.
    #[test]
    fn a_fresh_executor_is_neither_cancelled_nor_spinning() {
        let exec = executor();
        assert!(!exec.is_halted(), "nothing has asked it to stop");
        assert!(!exec.is_spinning(), "no spin loop is running");
    }

    /// `cancel()` raises the request bit without starting or stopping anything.
    #[test]
    fn cancel_requests_without_spinning() {
        let exec = executor();
        exec.cancel();
        assert!(exec.is_halted(), "cancel() must be observable immediately");
        assert!(
            !exec.is_spinning(),
            "cancel() must not make a non-spinning executor claim to spin"
        );
    }

    /// The load-bearing one: `cancel()` from a peer thread TERMINATES a running
    /// `spin`, `is_spinning()` is true while the loop runs, and false
    /// once it has returned.
    ///
    /// The peer asserts `is_spinning()` from OUTSIDE the spinning thread, which
    /// is the whole point of the observable — it is what a signal handler or a
    /// supervisor sees.
    #[test]
    fn cancel_terminates_a_spin_and_is_spinning_tracks_it() {
        use std::{
            sync::{
                Arc,
                atomic::{AtomicBool, Ordering},
            },
            thread,
            time::{Duration, Instant},
        };

        let mut exec = executor();
        assert!(!exec.is_spinning());

        // `Executor` is not `Sync`, so the peer thread cannot hold a reference
        // to it. It observes and drives through the two flag handles instead —
        // which is the supported cross-thread surface (`halt_flag()`), and
        // keeps this test on the same seam a signal handler uses.
        let cancel_bit = exec.halt_flag();
        let saw_spinning = Arc::new(AtomicBool::new(false));
        let saw_spinning_peer = Arc::clone(&saw_spinning);

        let peer = thread::spawn(move || {
            // Give the loop time to enter. Bounded, and the assertion below is
            // on what was OBSERVED, so a slow host cannot turn this green by
            // accident — it fails instead.
            thread::sleep(Duration::from_millis(50));
            saw_spinning_peer.store(true, Ordering::SeqCst);
            cancel_bit.store(true, Ordering::SeqCst);
        });

        let started = Instant::now();
        exec.spin(crate::executor::types::SpinOptions::default())
            .expect("an untimed spin runs until cancelled");
        let elapsed = started.elapsed();

        peer.join().expect("peer thread must not panic");

        assert!(
            saw_spinning.load(Ordering::SeqCst),
            "the peer must have run before spin returned"
        );
        assert!(
            !exec.is_spinning(),
            "is_spinning() must be false once the loop has returned"
        );
        assert!(
            exec.is_halted(),
            "the cancel request survives the loop it ended"
        );
        // LOWER bound too: a spin that never waited would prove nothing about
        // termination. The peer sleeps 50 ms before cancelling.
        assert!(
            elapsed >= Duration::from_millis(40),
            "spin returned in {elapsed:?} — it cannot have spun"
        );
        // ...and an UPPER bound, because "terminated" is the claim: without the
        // cancel check this loop never returns and the test would hang rather
        // than fail. 10 s is far past any scheduling noise.
        assert!(
            elapsed < Duration::from_secs(10),
            "spin took {elapsed:?} to observe the cancel"
        );
    }

    /// `is_spinning()` is true from INSIDE the loop. Read from a timer callback,
    /// which is the only place the executor is genuinely mid-spin, and asserted
    /// after the loop so a callback that never fired cannot pass silently.
    #[test]
    fn is_spinning_is_true_inside_the_loop() {
        use std::time::Duration;

        let mut exec = executor();
        // `only_next` runs exactly one iteration, so this is a single poll
        // inside a spin scope — bounded, no thread, no clock dependency beyond
        // the one the fixture installs.
        assert!(!exec.is_spinning());
        exec.spin(crate::executor::types::SpinOptions::spin_once())
            .expect("a single-iteration spin must succeed");
        assert!(
            !exec.is_spinning(),
            "the scope must close when the loop returns"
        );

        // The inside-the-loop reading needs a second thread to do it, because
        // the spinning thread is blocked in the loop and `Executor` is `!Sync`
        // so no `&Executor` may cross. What crosses is a pointer to the one
        // atomic, which is the same thing the C and C++ APIs hold: they observe
        // `is_spinning` through a raw executor handle, and that is the case this
        // flag exists to serve.
        struct FlagPtr(*const portable_atomic::AtomicBool);
        // SAFETY: the pointee is an `AtomicBool`, which is `Sync`; the only
        // operation performed through it is a relaxed-or-stronger load. The
        // executor outlives the thread — `peer.join()` below happens before
        // `exec` is dropped at the end of the test.
        unsafe impl Send for FlagPtr {}

        let cancel_bit = exec.halt_flag();
        let observed = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
        let spinning_bit_seen = std::sync::Arc::clone(&observed);
        let flag = FlagPtr(&exec.spinning as *const portable_atomic::AtomicBool);
        let peer = std::thread::spawn(move || {
            let flag = flag;
            for _ in 0..500 {
                // SAFETY: see the `unsafe impl Send` above.
                if unsafe { &*flag.0 }.load(core::sync::atomic::Ordering::SeqCst) {
                    spinning_bit_seen.store(true, std::sync::atomic::Ordering::SeqCst);
                    break;
                }
                std::thread::sleep(Duration::from_millis(2));
            }
            cancel_bit.store(true, std::sync::atomic::Ordering::SeqCst);
        });

        exec.spin(crate::executor::types::SpinOptions::default())
            .expect("an untimed spin runs until cancelled");
        peer.join().expect("peer thread must not panic");

        assert!(
            observed.load(std::sync::atomic::Ordering::SeqCst),
            "is_spinning() must read true while spin is running"
        );
    }

    /// `spin_period` maintains the same scope, and a period this build cannot
    /// pace is an error that must NOT leave the executor claiming to spin.
    #[test]
    fn spin_period_with_no_clock_leaves_is_spinning_false() {
        let mut exec = executor();
        exec.clock_us_fn = None;
        let err = exec
            .spin_period(core::time::Duration::from_millis(10))
            .expect_err("a period with no clock must fail (issue 0709)");
        assert_eq!(err, crate::NodeError::NotInitialized);
        assert!(
            !exec.is_spinning(),
            "a spin that never started must not report that it did"
        );
    }

    /// Entering a spin CLEARS a stale cancel: a cancel requested before this
    /// spin is not a cancel of this spin. Documents the ADOPT-BOUNDED envelope's
    /// one sharp edge.
    #[test]
    fn entering_a_spin_clears_a_stale_cancel() {
        let exec = executor();
        exec.cancel();
        assert!(exec.is_halted());
        exec.enter_spin_loop();
        assert!(
            !exec.is_halted(),
            "a cancel raised before the loop started must not end it instantly"
        );
        assert!(exec.is_spinning());
        exec.exit_spin_loop();
        assert!(!exec.is_spinning());
    }
}