nros/

lib.rs

//! # nros
//!
//! A lightweight ROS 2 client library for embedded systems.
//!
//! This crate provides a unified API for building ROS 2 nodes in Rust,
//! with support for `no_std` environments and embedded targets.
//!
//! ## Features
//!
//! - **no_std compatible**: Works on bare-metal and RTOS targets
//! - **Zero-copy where possible**: Minimizes memory allocations
//! - **Type-safe**: Compile-time verification of message types
//! - **ROS 2 compatible**: Interoperates with standard ROS 2 nodes via rmw_zenoh
//!
//! ## Quick Start
//!
//! ```ignore
//! use nros::prelude::*;
//! use std_msgs::msg::Int32;
//!
//! let config = ExecutorConfig::from_env().node_name("my_node");
//! let mut executor = Executor::open(&config)?;
//!
//! let node = executor.node_builder("my_node").build()?;
//! let publisher = executor.node_mut(node).create_publisher::<Int32>("/my_topic")?;
//! publisher.publish(&Int32 { data: 42 })?;
//!
//! executor.node_mut(node).create_subscription::<Int32, _>("/topic", |msg: &Int32| {
//!     println!("Received: {}", msg.data);
//! })?;
//!
//! executor.spin(SpinOptions::default());
//! ```
//!
//! ## Executor Sizing
//!
//! The executor's static memory layout is controlled via environment variables
//! at build time:
//!
//! - **`NROS_EXECUTOR_MAX_CBS`** (default 4) — maximum number of registered
//!   callbacks (subscriptions + timers + services + guard conditions).
//! - **`NROS_EXECUTOR_ARENA_SIZE`** (default 4096) — byte budget for storing
//!   callback closures inline.
//!
//! A subscription's arena receive buffer is sized from the MESSAGE TYPE's own
//! serialized bound (phase-392 W3c), not from that knob, wherever the bound is
//! reachable. `.rx_buffer::<N>()` is the opt-out: it says "give me exactly `N`
//! bytes per slot" and skips the derivation, which is what a peer that pads or
//! a `.msg` bound looser than the traffic needs (e.g.
//! `node_mut(id).subscription(t).typed::<M>().rx_buffer::<4096>().build(cb)`).
//!
//! ## Transport Backends
//!
//! Phase 248 C5c — `nros` is RMW- and platform-AGNOSTIC. It carries only the
//! `rmw-cffi` vtable; the concrete backend (zenoh / xrce / cyclonedds) enters
//! the link graph via the board crate (embedded), the board-less app's own
//! `nros-rmw-*` dep (native), or the `nros-c`/`nros-cpp` staticlib root (D3),
//! and self-registers through the `RMW_INIT_ENTRIES` walker at `Executor::open`.
//! The concrete session type is resolved automatically; advanced users can
//! access it via `nros::internals::RmwSession`.
//!
//! ## Crate Features
//!
//! `nros` exposes only FUNCTIONAL features — `std`/`alloc`, the `rmw-cffi`
//! vtable, `lending`, `bridge`/`config`, `param-services`,
//! `lifecycle-services`, `safety-e2e`, `stream`, `ffi-sync`, and the ROS
//! edition (`ros-humble`/`ros-iron`). There are NO `platform-*` or concrete
//! `rmw-*` selector features (Phase 248 C7). Platform + RMW are selected by the
//! board / staticlib root via dependencies, not `nros` features. The
//! `zephyr_component_main!` entry macro is gated only on `rmw-cffi` (it's
//! framework entry codegen, like `nros::main!`), not a platform feature.
//!
//! **ROS edition** (select one; RFC-0056 — the per-distro interop profile):
//! - `ros-humble` - ROS 2 Humble (default; `TypeHashNotSupported`, XCDR1)
//! - `ros-iron` - ROS 2 Iron (RIHS01 type hash)
//! - `ros-jazzy` - ROS 2 Jazzy (RIHS01; XCDR2/appendable is phase-303)
//!
//! **Other**:
//! - `std` (default) - Enable standard library support
//! - `alloc` - Enable heap allocation without full std
//!
//! ## Further Reading
//!
//! - [`guide`] — tutorials: getting started, services, configuration,
//!   ROS 2 interop, and troubleshooting
//! - [Message Generation](https://github.com/jerry73204/nano-ros/blob/main/docs/guides/message-generation.md)
//!   — codegen reference (all options, output structure, bundled interfaces)
//! - [Environment Variables](https://github.com/jerry73204/nano-ros/blob/main/docs/reference/environment-variables.md)
//!   — complete buffer tuning reference
//! - [ROS 2 Interop](https://github.com/jerry73204/nano-ros/blob/main/docs/reference/rmw_zenoh_interop.md)
//!   — protocol details (key expressions, liveliness, attachments)
//! - [Examples](https://github.com/jerry73204/nano-ros/tree/main/examples)
//!   — working examples by platform (native, QEMU, ESP32, Zephyr)

#![no_std]

// ── Feature validation (mutual exclusivity) ─────────────────────────────
// Phase 248 C5c/C7 — `nros` carries NO `platform-*` selector features, so the
// platform mutual-exclusion `compile_error!` is gone. The platform is selected
// by the board / staticlib root via an `nros-platform` dep, and nros-node picks
// the kernel primitive at runtime (C2 wake-probe).
// Only `rmw-cffi` is exposed at this layer; the cffi shim selects the
// concrete backend at the C ABI level via the `RMW_INIT_ENTRIES` walker.

// At most one ROS edition (RFC-0056 — the axis is compile-time exclusive).
#[cfg(any(
    all(
        feature = "ros-humble",
        any(feature = "ros-iron", feature = "ros-jazzy")
    ),
    all(feature = "ros-iron", feature = "ros-jazzy"),
))]
compile_error!("`ros-{humble,iron,jazzy}` are mutually exclusive — select one ROS edition.");

#[cfg(feature = "std")]
extern crate std;

#[cfg(feature = "alloc")]
extern crate alloc;

// Phase 216.A.5 — the `nros::node!()` proc-macro emits absolute paths
// under `::nros::*` (so downstream Node pkgs only need a single `nros`
// dep). For the in-crate macro-expansion test in `node.rs`, alias the
// `nros` crate name to itself so those absolute paths resolve. Gated on
// `cfg(test)` to keep the alias out of normal builds.
#[cfg(test)]
extern crate self as nros;

// Phase 248 C5c — the umbrella's force-link statics
// (`__FORCE_LINK_{PLATFORM_CFFI,ZENOH,XRCE,CYCLONEDDS_SYS}`) are REMOVED along
// with `nros`'s concrete-backend deps. `nros` no longer references any concrete
// RMW or platform crate, so it has nothing to force-link. Registration + the
// `nros_platform_*` link anchor now live with whoever owns the concrete crate:
//   * embedded   — the BOARD crate force-links its backend + calls
//     `<backend>::register()` in its boot path (C5a);
//   * board-less native — the APP owns `nros-rmw-*` + a `#[used]` force-link in
//     its `main.rs`, and `nros-platform-cffi[posix-c-port]` anchors the C symbols;
//   * C/C++ staticlib — `nros-c`/`nros-cpp` bundle one backend (D3) and anchor
//     `nros-platform` themselves.

// Phase 249 P1 — `__register_linked_rmw()` (a Phase 248 C5c no-op kept only so the
// `nros::main!` framework's call sites compiled) is REMOVED along with those call
// sites. Backend registration never routed through the backend-agnostic `nros` crate:
// hosted auto-registers via the `RMW_INIT_ENTRIES` walk at `Executor::open`; embedded
// boards perform the explicit `<backend>::register()` in their boot path (C5a). One
// Rust trigger = the board/app explicit register (phase-249).

// phase-391 W5 — build-time knobs (`MAX_COMPONENTS`, `COMPONENT_SLOT_BYTES`).
// Ungated: they are plain consts, useful to size caller-supplied storage
// whether or not the runtime module that consumes them is compiled in.
pub mod config;

// phase-391 W5 — caller-supplied component-pool storage sizing. Ungated for the
// same reason `config` is: plain arithmetic, useful to size a `static` whether
// or not `node_runtime` is compiled in.
// Issue 1419 / issue 1556 item 1 — the census hooks every language's node API
// calls (unconditionally; the bodies exist only under `metadata-mode`).
#[doc(hidden)]
pub mod census_hooks;
pub mod dispatch_tag;
pub mod guide;
#[cfg(feature = "metadata-mode")]
pub mod metadata_mode;
/// phase-463 W7 — the host profile (`nros_node::executor::profile`), for the
/// hosted edges that read `$NROS_PROFILE_OUT` (`nros-cpp`, `nros-board-linux`).
#[cfg(all(feature = "profile-mode", feature = "rmw-cffi"))]
pub use nros_node::executor::profile;
pub mod node;
pub mod node_metadata;
/// Phase 212.M.5.a.2 — executor-backed component runtime.
///
/// Binds [`Node`] / [`ExecutableNode`] to a live
/// [`Executor`] so a Node pkg can actually run (versus
/// [`MetadataRecorder`] which
/// is the planner-side metadata sink).
///
/// Gated on `rmw-cffi`; the underlying [`Executor`] is only present
/// when an RMW backend is linked. W5-endgame (issue 0843): the MACRO install
/// path (per-class static storage, placed cells, slabbed ctxs) is alloc-free,
/// so the module no longer demands `alloc` — only the dynamic
/// `ExecutorNodeRuntime` half does, item-gated inside.
#[cfg(feature = "rmw-cffi")]
pub mod node_runtime;
pub mod runtime_storage;

/// Issue 1535 — what a `void*` executor handle crossing the language seam is,
/// and the one check every seam in this crate makes before treating it as an
/// `Executor` (a C/C++ entry's handle is an nros-cpp context, not one).
pub mod executor_handle;

/// Phase 212.L.5 — top-level init API; phase-427 W9 — on every target.
///
/// Re-exported flat at the crate root: `nros::Context` (`alloc`),
/// `nros::ContextSource`, `nros::InitError`, `nros::InitOptions` (every
/// target); `nros::init()`, `nros::init_with_args(args)` (`env`).
/// The `env` feature gates only the process-environment reader and the
/// argv entry; freestanding, `Context::default_from_env()` is the
/// bake (`Context::baked()`).
pub mod init;

/// issue 0687 — the hosted edge of configuration: every env var nano-ros
/// honours is read here, and the core takes values.
#[cfg(feature = "env")]
pub mod env;

/// Issue 1763 — the same env rung for a `#![no_std]` image inside a host
/// process (threadx-linux, freertos-posix), read with the C library's `getenv`.
/// `target_os = "linux"` is "a C library is linked" on this tree. Compiled on
/// every Linux build, not only `not(feature = "env")` ones: feature
/// unification can turn `nros/env` on under a caller whose own `env` is off,
/// and the caller must still find this. Where a caller has `env`, it uses the
/// `std::env` reader instead (`nros-c`/`nros-cpp` `resolve_boot`).
#[cfg(target_os = "linux")]
pub mod host_env;

/// phase-484 W8c — the retired env aliases both hosted readers refuse.
pub mod retired_env;
pub use retired_env::RETIRED_ENV_VARS;

#[cfg(feature = "env")]
pub use env::{ExecutorConfigEnvExt, rmw_selector};

pub use init::{ContextSource, InitError, InitOptions};

#[cfg(feature = "alloc")]
pub use init::Context;

#[cfg(feature = "env")]
pub use init::{init, init_with_args};

/// Compile-time opaque storage sizes for FFI consumers.
///
/// See [`sizes`] for the `export_size!` pattern used to expose these values
/// to `nros-c` / `nros-cpp` at build time.
pub mod sizes;

/// Monotonic time for portable node code (issue #504).
///
/// phase-359 W10 — `rmw-cffi`, not `any(std, rmw-cffi)`: the clock is the
/// platform port's, and a build with no port has none to offer.
#[cfg(feature = "rmw-cffi")]
pub mod time;

/// CDR encapsulation constants and helpers for FFI layers that handle raw
/// CDR bytes (e.g. nros-c, nros-cpp action and service paths).
pub mod cdr {
    pub use nros_serdes::{
        CDR_BE_HEADER, CDR_HEADER_LEN, CDR_LE_HEADER, strip_cdr_header, write_cdr_le_header,
    };
}

// Re-export core types
pub use nros_core::{
    CdrReader, CdrWriter, Clock, ClockType, DeserError, Deserialize, Duration, MessageInfo,
    PUBLISHER_GID_SIZE, RawMessageInfo, RosMessage, RosService, SecNanosecMsg, SerError, Serialize,
    Time,
};

// -----------------------------------------------------------------------------
// Logging (phase-417 W4.d, issue 0589).
//
// `nros_log` was in this crate's dependency graph and reachable from NONE of
// its surface: no `pub use`, nothing in the prelude. So from the façade the
// shortest path to "print something" was `std::println!` — which is FATAL on
// Zephyr `native_sim`: `zvfs_write(1, …)` dispatches to
// `stdinout_write_vmeth`, which calls `zvfs_write(1, …)` again, and because
// `k_mutex` is recursive it exhausts the stack instead of deadlocking. The
// image dies with no message. A logging facade nobody can reach from the
// umbrella is not a facade.
//
// `nros::Logger` IS RE-BOUND, and that is the point rather than a side effect.
// It used to name `nros_core::logger::Logger`, which formats through the `log`
// crate: on a target with no `log` backend installed — every embedded one —
// the record is constructed and dropped, and it NEVER reaches
// `nros_platform_log_write`. The type the C and C++ FFI hands out, the type
// the `nros_*!` macros dispatch through, and the type the platform sink
// receives is `nros_log::Logger`. One name, one meaning.
//
// Migration: the two types share `new` and `name` and NOTHING else — the old
// one has inherent `.info(&str)` / `.warn(&str)` / `*_once` / `*_throttle`
// methods, the new one is driven by the `nros_*!` macros. So every call site
// that used the old surface FAILS TO COMPILE against the new binding rather
// than silently changing where its records go. That is the RFC-0089 rule
// applied to our own rename, and it is why this is a re-binding with a named
// escape hatch instead of a quiet swap. The escape hatch was `LogCrateLogger`,
// deprecated on arrival and deleted by phase-482 W6.
pub use nros_log::{
    DEFAULT_LOGGER, LogSink, Logger, MAX_LOGGERS, Record as LogRecord, Severity, ThrottleState,
    get_logger, get_or_create_logger, register_logger,
};
// The emission macros, at the crate root, because a user who has
// `use nros::prelude::*` should not have to learn a second crate name to log a
// line. `#[macro_export]` puts them at `nros_log`'s root; this puts them at
// ours.
//
// NAMES (phase-417, RFC-0089 "each language follows ITS OWN upstream",
// settled 2026-09-04). The three ROS 2 client libraries disagree about how to
// spell a log line — `rclrs::log_info!`, `RCLCPP_INFO`,
// `RCUTILS_LOG_INFO_NAMED` — so there is no one "ROS 2 spelling" to match.
// Rust follows rclrs, because a node ported from rclrs is read beside rclrs.
// Hence the five severity macros below carry rclrs's names.
//
// Two families keep OUR prefix, and that is a decision rather than an
// oversight: a name takes rclrs's spelling exactly when rclrs HAS that name.
//
//   * `nros_trace!` — rclrs stops at `debug`. TRACE has no upstream twin, so
//     giving it one would claim a correspondence that does not exist.
//   * `nros_*_throttle!` / `nros_*_throttle_at!` — rclrs throttles with a
//     MODIFIER on one macro (`log_info!(logger.throttle(d), "…")` via
//     `LogParams` / `ToLogParams`), not a macro per severity. Adopting that is
//     a shape change, not a rename; see `nros-log/src/macros.rs`'s throttle
//     note for the three ledger rows it would have to reverse.
pub use nros_log::{
    log_debug, log_error, log_fatal, log_info, log_warn, nros_debug_throttle,
    nros_debug_throttle_at, nros_error_throttle, nros_error_throttle_at, nros_fatal_throttle,
    nros_fatal_throttle_at, nros_info_throttle, nros_info_throttle_at, nros_trace,
    nros_trace_throttle, nros_trace_throttle_at, nros_warn_throttle, nros_warn_throttle_at,
};
/// The whole logging facade — sinks, the early-record ring, the throttle
/// primitives, `init`/`flush`/`add_sink`.
///
/// The root re-exports above are the surface a node author needs; this is
/// everything, for a board or a bridge composing its own delivery.
pub mod logging {
    pub use nros_log::*;
}

// Re-export heapless for generated message types and examples
pub use nros_core::heapless;

// Phase 212.M.5.a.2 — executor-backed runtime entry points.
// (`component_register_symbol` retired in the Phase 212.N.7 closing
// sweep — the helper had no live callers after the BSP baker + macro
// extern emit were deleted.)
pub use node::{
    ActionExecutor, Callback, CallbackCtx, ClientDispatch, EntityBounds, NodeActionClient,
    NodeActionServer, NodeDeclError, NodeOptions, NodeParameter, NodePublisher, NodeResult,
    NodeRuntime, NodeServiceClient, NodeServiceServer, NodeSubscription, NodeTimer,
    PublisherResolver, TickCtx,
};
// phase-483 W3 — the component API registers into a live executor, so it
// exists where the executor does.
#[cfg(feature = "rmw-cffi")]
pub use node::{CallbackEffects, Component, DeclarativeNode, ExecutableNode, NodeContext};
// Issue 0784 — the macro and codegen PLUMBING, out of the documented surface.
// `nros::` publishes three audiences under one namespace; these six are for the
// `nros::node!` expansion and the generated metadata probe
// (`nros-cli-core/src/orchestration/metadata_build.rs`), never for a node
// author, and none is named by any hand-written file in `examples/` or
// `packages/`. Hidden, not deleted: the generated code reaches them by path, the
// same treatment as `__private_node_state_into_raw` below.
#[cfg(feature = "rmw-cffi")]
#[doc(hidden)]
pub use node::{__record_with_context, record_node_metadata, register_node};
// Phase 212.M.5.a.4 — internal helper consumed by `nros::node!()`
// for the BSP dispatch path. Public-but-doc-hidden so the macro expand
// resolves it as `::nros::__private_node_state_into_raw`.
#[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
#[doc(hidden)]
pub use node::__private_node_state_into_raw;
// phase-359 W8 — follows `node_metadata`'s re-gate: the type needs `alloc`,
// not `std`.
#[cfg(feature = "alloc")]
pub use node_metadata::SourceMetadataExport;
/// phase-381 follow-up — the node-FQN join, at the crate root because that is
/// where a user looks after `Executor::get_node_names` hands them the two
/// halves. `nros_node::names` also has `expand_name` / `resolve_name`, which
/// stay behind `node_metadata` — they are the entity-name seam, not this.
pub use node_metadata::fully_qualified_name;
pub use node_metadata::{
    CallbackEffectKind, CallbackEffectMetadata, EntityKind, EntityMetadata, MetadataRecorder,
    MetadataString, NodeMetadata, NodeMetadataError, ParameterDefault, SourceLocationMetadata,
    SourceNameKind,
};
#[doc(hidden)]
pub use node_metadata::{CallbackId, EntityId, NodeId};
// Phase 216.A.4 — opaque tag types Node authors hold on `Self::State`
// and match against the `Callback<'_>` delivered to
// `ExecutableNode::on_callback`.
pub use dispatch_tag::{ActionTag, ServiceTag, SubscriptionTag};
// W5-endgame (issue 0843) — the alloc-free half of the seam: per-class static
// storage + the `_in` installs the macro emits. Available on `rmw-cffi` alone.
#[cfg(feature = "rmw-cffi")]
pub use node_runtime::{
    ComponentSlotStorage,
    // Phase 257 (W0-B) — the uniform cross-language component-install seam backing
    // `__nros_component_<pkg>_install` (nros::node!): register an ExecutableNode on the
    // shared executor a foreign typed entry hands in. (`register_node_borrowed` stays
    // crate-internal — it returns the private `ComponentCell`.)
    install_node_typed_in,
    // Phase 305 W3 (issue 0255) — same seam plus launch `<remap>` rules; the variant
    // `nros::node!()` emits.
    install_node_typed_with_launch_in,
};
// The dynamic runtime + the leak-per-call conveniences still need `alloc`.
#[cfg(all(feature = "rmw-cffi", feature = "alloc"))]
pub use node_runtime::{
    ExecutorError,
    ExecutorNodeRuntime,
    RegisteredNode,
    install_node_typed,
    install_node_typed_with_launch,
    // Phase 268 W1 — same seam with both `<param>` initials AND `<node name= namespace=>`
    // identity injection (RFC-0046).
    install_node_typed_with_node_identity,
    // W4a — same seam, seeding the node's NodeContext with launch-baked `<param>` initials.
    install_node_typed_with_params,
};

// phase-483 W3 — the `install_node_typed*` STUBS for builds without
// `rmw-cffi` are gone. They existed so a `nros::node!()` package compiled
// without the executor stayed linkable; a component now registers into a live
// executor (`NodeContext::create_node` returns a `Node`), so a component
// package without `rmw-cffi` has nothing to register into and does not build.
// Phase 212.N.12 — canonical `nros::node!()` macro. Replaces the legacy
// `nros::node!()` macro (retired in the N.12 hard rename — both the
// proc-macro forwarder and the Cargo metadata key are gone).
#[cfg(feature = "macros")]
pub use nros_macros::node;
// Phase 212.N.9 — `nros::main!()` proc-macro family. One-line Entry-pkg
// `main.rs` (replaces the legacy `build.rs + include!()` shape). See
// `docs/design/0024-multi-node-workspace-layout.md` §11.6.
#[cfg(feature = "macros")]
pub use nros_macros::main;

/// Route this image's panics to its platform — phase-366 W5.c / RFC-0077.
///
/// Emits the `#[panic_handler]` for an embedded image, forwarding the message
/// to `nros_platform_panic` so a Rust panic ends the same way a C precondition
/// failure or a C++ terminate does. What that ending IS belongs to the port:
/// `k_panic()` on Zephyr, `esp_system_abort()` on ESP-IDF, UART-then-exit-QEMU
/// on the ThreadX RV64 board.
///
/// # Why this is a macro you INVOKE, not something `nros::main!` emits
///
/// `#[panic_handler]` is a singleton of the final artifact, and the image owns
/// it. Emitting one silently from `nros::main!()` would collide with every image
/// that already declares its own — `examples/esp32-c3-baremetal` writes
/// `use esp_backtrace as _;`, and `logging-smoke-freertos-mps2` uses
/// `panic-semihosting` with `features = ["exit"]` so a panic exits QEMU instead
/// of hanging the test harness. Those images are RIGHT, and an invisible default
/// would fight them.
///
/// So the line is written in the entry, where it can be read, swapped for
/// `use panic_halt as _;`, or replaced by a hand-written handler that logs to
/// NVM and reboots. A default you cannot see is a constraint, not a default.
///
/// # Use — `main!(panic = …)` is the normal way; this is the escape hatch
///
/// phase-366 R3. An entry that goes through `nros::main!()` should say
/// `panic = "platform"` (or nothing — that is the default since M5) and let the
/// macro emit this body. One line, and the build can check it.
///
/// ```ignore
/// #![no_std]
/// nros::main!();            // ends through `nros_platform_panic`
/// ```
///
/// Invoke this macro directly only where no `main!()` expansion can carry the
/// item — a hand-rolled `no_std` binary, or the lib side of a crate whose
/// `crate-type` includes `staticlib` and whose entry macro is
/// `zephyr_component_main!` / a board `app_main!`. It is kept for exactly those:
/// deleting it would strand the images that cannot use the macro replacing it.
///
/// ```ignore
/// // src/app_main.rs — the .a is a final artifact to rustc, and `main!()` in
/// // the bin target never reaches it.
/// nros::panic_to_platform!();
/// ```
///
/// Do NOT invoke it in a `std` image: libstd supplies the lang item there and a
/// second one does not compile. Do not invoke it alongside `use panic_halt as _`
/// or any other provider, for the same reason — that is the duplicate
/// `check-archive-lang-items` exists to catch.
/// Park the core on panic — the `halt` value of `nros::main!(panic = …)`.
///
/// For an image that must not print: no formatting, no allocation, no call out
/// to the platform. Interrupts are masked first so the parked core cannot be
/// woken back into a half-dead system by a timer or a driver ISR still armed
/// from before the panic.
///
/// This is a body rather than a re-export of the `panic-halt` crate so that
/// choosing it costs the entry no new dependency — `main!(panic = "halt")` is a
/// word in a macro the crate already calls, which is the point of the surface.
/// The behaviour is the same: mask, then spin forever.
///
/// Prefer `panic = "platform"`. Halting discards the diagnosis, and every port
/// implements `nros_platform_panic` precisely so a dying image can say why.
/// Phase 392 W3b — the receive-buffer size for a message type, as a constant
/// that cannot drift from the type.
///
/// ```ignore
/// node.subscription::<PointCloud2>("points")
///     .rx_buffer::<{ nros::rx_buffer_for!(PointCloud2) }>()
///     .build(on_cloud)?;
/// ```
///
/// `.rx_buffer::<N>()` has always accepted a number. The problem is where the
/// number comes from: a literal is correct until someone appends a field to the
/// message, and then it is silently too small — the sample is received, ACKed
/// and dropped at the transport, which needs a packet capture to attribute
/// (`report_dropped_take`, and the 13.4 KiB Autoware trajectory case). This
/// expands to the type's own bound, computed from its schema by phase 380, so
/// appending a field moves the buffer with it.
///
/// **phase-392 W3c narrowed what this is FOR.** A plain
/// `.typed::<M>().build()` now derives its arena receive buffer from `M` on its
/// own, and `.rx_buffer::<N>()` is the opt-out, so the macro is no longer how a
/// buffered subscription gets a type-sized buffer. What still needs it is the
/// entry shapes whose buffer is a real inline `[u8; RX]` and therefore a
/// const-generic argument: `.message_info()` and `.safety()`. Those are the
/// call sites this expands for.
///
/// **Why a macro and not a method.** The builder cannot do this for you:
/// inside `impl<M> TypedSubscriptionBuilder<M>` the type is a generic
/// parameter, and on stable Rust a generic parameter may not appear in a const
/// operation — `error: generic parameters may not be used in const operations`.
/// At a call site the type is CONCRETE, which is legal, so the size has to be
/// named where the type is. That constraint is also why phase-392's size
/// classes were "decoupled from codegen" in the first place.
///
/// **Unbounded types are a BUILD ERROR** (phase-403 W0). A type with an
/// unbounded `string`/`wstring`/`sequence` has no bound, and this refuses to
/// invent one. It used to expand to `DEFAULT_RX_BUF_SIZE`; it now fails to
/// compile, naming both remedies.
///
/// Every message type is REQUIRED to carry a derived upper bound, stated in the
/// `.msg` (`string<=64`) or capped in `nros-codegen.toml`. Phase 380 is explicit
/// that `None` means "no bound EXISTS", never "unknown", and that a buffer must
/// not be sized from a fallback. Substituting the configured default was the
/// violation of that rule; refusing is what it licenses. `report_dropped_take`
/// is a backstop for a buffer that is too small, not a licence to pick one.
///
/// ```compile_fail
/// use nros_serdes::schema::{Field, FieldType, Message};
/// struct Unbounded;
/// impl Message for Unbounded {
///     const TYPE_NAME: &'static str = "test/msg/Unbounded";
///     const FIELDS: &'static [Field] = &[Field {
///         name: "s",
///         ty: FieldType::String,
///         offset: 0,
///     }];
/// }
/// let _n: usize = nros::rx_buffer_for!(Unbounded);
/// ```
///
/// The positive control for that `compile_fail`, so it cannot pass because the
/// fixture stopped compiling for an unrelated reason:
///
/// ```
/// use nros_serdes::schema::{Field, FieldType, Message};
/// struct Bounded;
/// impl Message for Bounded {
///     const TYPE_NAME: &'static str = "test/msg/Bounded";
///     const FIELDS: &'static [Field] = &[Field {
///         name: "a",
///         ty: FieldType::Uint64,
///         offset: 0,
///     }];
/// }
/// let n: usize = nros::rx_buffer_for!(Bounded);
/// assert!(n > 0);
/// ```
///
/// **Why the `const` block.** The macro is used in two positions: as a
/// const-generic argument (`.rx_buffer::<{ rx_buffer_for!(M) }>()`) and as a
/// plain expression (`let n = rx_buffer_for!(M);`). A bare `panic!` is a build
/// error in the first and a RUNTIME panic in the second, which would make the
/// rule depend on where the macro appears. Wrapping the whole match in an inline
/// `const` block forces compile-time evaluation in BOTH, so an unbounded type
/// can never reach a running image.
///
/// **What the error names.** rustc points at this macro invocation, where the
/// type is written literally, so the TYPE is named. The MEMBER that costs the
/// bound cannot be in the message: const evaluation does not format, so a
/// `panic!` there takes a literal only. The member is named by the codegen
/// diagnostic for the same type -- `unbounded_reason` in the generated C header
/// (`packs/c/message.h.jinja`), which names EVERY member that costs the bound in
/// one build (phase-403 W0), or `nros_serdes::size::visit_unbounded` over its
/// `FIELDS`.
#[macro_export]
macro_rules! rx_buffer_for {
    ($msg:ty) => {
        // The `const` block is load-bearing; see "Why the `const` block" above.
        const {
            match $crate::__rx_bound::<$msg>() {
                ::core::option::Option::Some(n) => n,
                ::core::option::Option::None => ::core::panic!(
                    "nros: this message type has NO serialized-size bound, so no \
                     receive buffer can be sized from it.\n\
                     Every message type must carry a derived upper bound. Bound the \
                     member that costs it, either:\n\
                     \x20 - in the `.msg`: `string<=64`, `wstring<=64`, \
                     `sequence<T, N>`, `T[<=N]`; or\n\
                     \x20 - as an INLINE `cap` in `nros-codegen.toml`: under \
                     `[fields]`, `\"pkg/Msg.field\" = 64`. A `heap` or `view` cap \
                     is a sizing hint that nothing enforces (RFC-0033), so it \
                     deliberately does NOT bound.\n\
                     WHICH members cost the bound -- all of them, not just the \
                     first -- are named by the codegen diagnostic for this same \
                     type: `unbounded_reason` in the generated C header, or \
                     `nros_serdes::size::visit_unbounded` over its `FIELDS`. The type itself is named by the \
                     `rx_buffer_for!` invocation rustc points at.\n\
                     Phase 380: `None` means no bound EXISTS, never \"unknown\", and \
                     a buffer sized from a fallback is the failure that rule was \
                     written to prevent. Erroring honours it; defaulting to \
                     `DEFAULT_RX_BUF_SIZE` did not."
                ),
            }
        }
    };
}

#[macro_export]
macro_rules! panic_halt {
    () => {
        #[panic_handler]
        fn __nros_panic_halt(_info: &::core::panic::PanicInfo) -> ! {
            // Mask interrupts through the platform's critical section, which is
            // the one IRQ primitive that is portable across the ports (the
            // `cortex_m`/`riscv` intrinsics are not). Entering and never
            // leaving is deliberate.
            unsafe extern "C" {
                fn nros_platform_critical_section_acquire() -> u32;
            }
            // SAFETY: the ABI's acquire takes no argument and returns a restore
            // token we deliberately drop — nothing after this point runs.
            unsafe {
                let _ = nros_platform_critical_section_acquire();
            }
            loop {
                ::core::hint::spin_loop();
            }
        }
    };
}

#[macro_export]
macro_rules! panic_to_platform {
    () => {
        #[panic_handler]
        fn __nros_panic(info: &::core::panic::PanicInfo) -> ! {
            use ::core::fmt::Write as _;

            // Fixed buffer, never the heap: this runs when the allocator may be
            // exactly what failed. Truncation is deliberate — a short panic line
            // still diagnoses; a missing one does not.
            struct Buf {
                bytes: [u8; 192],
                used: usize,
            }
            impl ::core::fmt::Write for Buf {
                fn write_str(&mut self, s: &str) -> ::core::fmt::Result {
                    let room = self.bytes.len() - self.used;
                    let n = s.len().min(room);
                    self.bytes[self.used..self.used + n].copy_from_slice(&s.as_bytes()[..n]);
                    self.used += n;
                    Ok(())
                }
            }

            let mut buf = Buf {
                bytes: [0u8; 192],
                used: 0,
            };
            let _ = write!(buf, "{info}");

            unsafe extern "C" {
                fn nros_platform_panic(msg: *const u8, len: usize) -> !;
            }
            // SAFETY: `buf.bytes[..used]` is initialised and outlives the
            // diverging call; the ABI takes a length-delimited diagnostic, not
            // a C string.
            unsafe { nros_platform_panic(buf.bytes.as_ptr(), buf.used) }
        }
    };
}

/// Define Zephyr's `rust_main` for a self-bringup Rust component package.
///
/// The macro is intended for `rust_cargo_application()` apps whose crate
/// already invokes `nros::node!()`. It opens a Zephyr executor, registers
/// the supplied component through [`ExecutorNodeRuntime`], and spins forever.
/// Issue 0330 — force-link an RMW backend crate into a pure-Rust staticlib.
///
/// On a Rust-only image (Zephyr and friends) the Zephyr module emits a weak
/// `nros_rmw_<name>_register` and calls it only if it resolves. The strong
/// definition is the backend crate's `#[no_mangle]` export — and rustc's
/// staticlib DCE drops it unless something in the crate being compiled into the
/// staticlib references that crate. The symbol is then present in the rlib and
/// absent from the `.a`, the weak call sees NULL, and the image comes up with no
/// backend registered (issues 0155 / 0163).
///
/// This emits the reference, without naming any backend in nano-ros' own
/// RMW-agnostic layers — the app crate names it, because the app crate is what
/// selects an RMW:
///
/// ```ignore
/// #[cfg(feature = "rmw-zenoh")]
/// nros::force_link_backend!(nros_rmw_zenoh);
/// #[cfg(feature = "rmw-xrce")]
/// nros::force_link_backend!(nros_rmw_xrce_cffi);
/// ```
///
/// It is an ANCHOR, not a registration call — the static is never executed
/// (same class as `nros-c`'s `FORCE_LINK` and `nros-rmw-cffi`'s section anchor).
/// Registration happens through `nros_app_register_backends`. Backends whose
/// register entry lives in a C/C++ library the image already links (cyclonedds
/// on Zephyr) need no anchor at all.
///
/// Invoke at module scope. Multiple invocations in one crate are fine — each
/// expands inside its own anonymous const, so the static names cannot collide.
#[macro_export]
macro_rules! force_link_backend {
    // `ident`, not `path`: a `path` fragment may not be followed by `::`, so
    // `$backend::register()` fails to parse at the CALL site with a misleading
    // "expected an operator". Backend crate names are single idents anyway.
    ($backend:ident) => {
        const _: () = {
            #[used]
            static __NROS_FORCE_LINK_BACKEND: fn() = || {
                let _ = $backend::register();
            };
        };
    };
}

// Phase 248 C7 (Method A) — gated on `rmw-cffi` only (needs `Executor`), NOT a
// `platform-*` feature. This is a framework ENTRY macro (same category as
// `nros::main!`'s zephyr `rust_main` codegen) — `#[macro_export]` so it emits
// nothing unless a Zephyr example invokes it; the body's `::zephyr::*` /
// `::nros_platform::zephyr::wait_network` resolve only in that zephyr-build
// context (the example deps the `zephyr` crate + `nros-platform[platform-zephyr]`).
#[cfg(feature = "rmw-cffi")]
#[macro_export]
macro_rules! zephyr_component_main {
    ($node:ty) => {
        #[unsafe(no_mangle)]
        pub extern "C" fn rust_main() {
            // issue 1123 — publish an `nros_log` sink list. The `log` FACADE
            // (what an example body writes) is bridged into it just below
            // (issue 1324 retired `zephyr::set_logger`); the sink list is what
            // `nros_log` needs, which is what the
            // FRAMEWORK writes (nros-node's executor, nros-rmw-zenoh's session
            // and pool diagnostics, nros-rmw-cffi). With no sink list
            // `nros_log::dispatch_to_sinks` holds each record in the bounded
            // `nros_log::early` ring — issue 0710 deliberately removed the
            // implicit platform fallback — so on a pure-Rust Zephyr image every
            // framework record was constructed, dispatched and never seen.
            //
            // This is the funnel: a pure-Rust Zephyr image has no
            // `libnros_c.a` (issue 0163), so `rclc_log_init` / `rclc_log_emit`'s
            // lazy `ensure_default_sinks()` never run, and `nros-board-zephyr`
            // covers only `run_tiers`. Reached through `nros_platform` because
            // the example leaves dep that and not `nros-platform-cffi`.
            //
            // FIRST, before `wait_network`: `init` DRAINS the early ring, and
            // anything raised during bringup is exactly what the ring exists to
            // serve (the esp32 half of this class, issue 1048, got this order
            // backwards and drained into a writer that was still `None`). The
            // Zephyr writer is `nros_platform_log_write`, defined
            // unconditionally by the C port, so there is no such window here.
            ::nros_platform::log::init_default();
            // issue 1324 — the `log` facade into the same sinks. This was
            // `zephyr::set_logger()`, whose full-`CONFIG_LOG` arm exists only
            // under `CONFIG_RUST_ALLOC`, the allocator this image no longer links.
            ::nros_platform::log::install_log_crate_bridge();
            // Phase 248 C7 step 1 — relocated helper (was `$crate::platform::zephyr`).
            let _ = ::nros_platform::zephyr::wait_network(2000);
            // Phase 249 P1 — RMW register is board/platform-owned (Phase 248 C5a);
            // the backend-agnostic `nros` crate cannot register (no backend dep).
            // Issue 0155 — the "board/platform boot path" that was supposed to
            // register never fired for pure-Rust Zephyr images: the zephyr
            // module emits a STRONG `nros_app_register_backends` stub for the
            // Kconfig-selected RMW (zephyr/CMakeLists.txt Phase 160.A), but
            // only the C/C++ `nros_cpp_init` path ever CALLED it — a Rust-only
            // image reached `Executor::open` with no backend registered and
            // died with Transport(ConnectionFailed) (silently, pre-0155).
            // Call the hook explicitly, exactly like the C++ init path.
            unsafe extern "C" {
                fn nros_app_register_backends();
            }
            unsafe { nros_app_register_backends() };
            // Issue 0163 — a pure-Rust image has no `libnros_c.a`, so the
            // backend must ride in THIS staticlib and be referenced from the
            // app crate, or rustc's staticlib DCE drops the whole backend
            // closure (the `#[no_mangle]` C export included), leaving the
            // module's weak `nros_rmw_<x>_register` resolving to NULL and the
            // hook above registering nothing.
            //
            // Issue 0330 — that reference used to be a pair of hardcoded
            // `::nros_rmw_zenoh::register()` / `::nros_rmw_xrce_cffi::register()`
            // calls emitted RIGHT HERE, which named two concrete backends in
            // the RMW-agnostic facade (and left cyclonedds handled asymmetrically
            // through the C hook). It also forced every consumer to carry
            // `rmw-zenoh` / `rmw-xrce` feature rows purely so these `cfg`s would
            // resolve — the cyclonedds-only example carried both as inert
            // placeholders. The anchor now lives in the app crate, which is the
            // layer that legitimately selects an RMW: see
            // [`nros::force_link_backend!`]. Registration itself is unchanged —
            // the `nros_app_register_backends` hook above does it.
            // phase-427 W9 — the baked identity has ONE source. This block
            // used to read `option_env!("NROS_LOCATOR")` / `NROS_DOMAIN_ID`
            // itself and assemble an `ExecutorConfig` by hand (a copy
            // `nros::main!`'s Zephyr arm carried too, minus the domain — issue
            // 0161's class); `Context::baked()` is where that lives now, and
            // `default_from_env()` resolves to it on a freestanding build.
            // `nros`'s own `build.rs` re-exports the Kconfig values into that
            // crate's build (`nros_zephyr_build::bake_nros_config`), the same
            // channel the leaf's `build.rs` uses for itself.
            //
            // #166 / phase-286 W1 — native_sim test parallelism. The test
            // harness launches the image with `-testargs --nros-locator=<loc>`
            // and starts a per-test zenohd on that (ephemeral) port; preferring
            // it over the build-time bake lets every test dial a DISTINCT router,
            // retiring the shared-baked-port serialization of the zenoh e2e
            // lanes. Provided by `nros-platform-zephyr` (argv-backed, process
            // lifetime); returns NULL on real embedded → the bake stands. The
            // hook is an `extern "C"` only a Zephyr image defines, so it is
            // resolved HERE, in the entry, and handed to the context.
            unsafe extern "C" {
                fn nros_runtime_locator_override() -> *const ::core::ffi::c_char;
            }
            let runtime_locator: ::core::option::Option<&str> = {
                let p = unsafe { nros_runtime_locator_override() };
                if p.is_null() {
                    ::core::option::Option::None
                } else {
                    unsafe { ::core::ffi::CStr::from_ptr(p) }.to_str().ok()
                }
            };
            let ctx = match $crate::Context::default_from_env() {
                ::core::result::Result::Ok(ctx) => ctx.with_locator_override(runtime_locator),
                ::core::result::Result::Err(e) => {
                    panic!("nros zephyr entry: baked Context is invalid: {e:?}")
                }
            };
            let config = ctx.config(<$node as $crate::Component>::NAME);
            // Issue 0155 — fail LOUD (repo rule: panic, not silent
            // early-return). A silent `return` here idles the image with zero
            // output; the zephyr-cyclonedds rust lane was undiagnosable until
            // this printed the real error.
            let executor = match $crate::Executor::open(&config) {
                Ok(executor) => executor,
                Err(e) => {
                    panic!("nros zephyr entry: Executor::open failed: {e:?}");
                }
            };
            let mut runtime = $crate::ExecutorNodeRuntime::from_executor(executor);
            // phase-436 — Zephyr's microsecond park, which the tier runners
            // install on every tier and this single-executor entry did not.
            // Zephyr's `platform.c` always defines both symbols, and this macro
            // only expands in a Zephyr image, so they are plain references.
            {
                unsafe extern "C" {
                    fn nros_platform_wake_park_until_us(
                        w: *mut ::core::ffi::c_void,
                        deadline_us: u64,
                    ) -> i8;
                    fn nros_platform_wake_park_granularity_us() -> u64;
                }
                // SAFETY: a pure query of the linked port, no arguments.
                let granularity = unsafe { nros_platform_wake_park_granularity_us() };
                let _ = $crate::port_park::install_port_park(
                    runtime.executor_mut(),
                    nros_platform_wake_park_until_us,
                    granularity,
                );
            }
            if let Err(e) = runtime.register_node::<$node>() {
                panic!("nros zephyr entry: register_node failed: {e:?}");
            }
            // Readiness marker. The C/C++ Zephyr listeners print
            // "Waiting for messages..." from their `main()` before the spin
            // loop; the e2e harness polls for that substring to know the
            // subscriber has declared before starting the talker (Phase 89.12).
            // The Rust path's spin loop lives in this macro (the node only owns
            // callbacks), so emit the same canonical marker here — without it a
            // fully-working Rust listener never signals readiness and the e2e
            // times out at 30 s (issue #35: the zenoh native_sim rust pubsub /
            // service / action failures were this missing marker, not a
            // transport fault — `Executor::open` + `register_node` had already
            // succeeded).
            ::log::info!("Waiting for messages");
            loop {
                let _ = runtime.spin_once(::core::time::Duration::from_millis(10));
            }
        }
    };
}

// phase-483 W4 (issue 0784) — `StandaloneNode` (the transport-less
// pre-component node) and its `NodeConfig` / `PublisherHandle` /
// `SubscriptionHandle` are no longer re-exported. `nros::Node` is THE node,
// and these have no rclrs counterpart; the two bench programs that use them
// import `nros_node` directly.

// Re-export publisher/subscriber options (topic + QoS; always available).
pub use nros_node::{PublisherOptions, SubscriptionOptions};

// Re-export timer types
pub use nros_node::{TimerCallbackFn, TimerDuration, TimerHandle, TimerMode, TimerState};
// phase-425 W4/W5 — which clock advances a timer. Re-exported here for the
// reason `sim-time` is a feature here: an application deps `nros`, not
// `nros-node`, so a capability that stops at the core crate is one no
// application can name. W4 added the type and the registrar and stopped at the
// core, which the `/clock` fixture found the moment it tried to use them.
// UNGATED since phase-430 W4, and the enum moved to `nros_node::timer` to make
// that possible. The `rmw-cffi` gate was right while the only way to name a
// clock was `Executor::register_timer_on_clock`; W4 put the axis on the
// DECLARATIVE surface too (`DeclaredNode::create_timer_on_clock`), which a
// metadata-mode build compiles with no transport linked. A type the metadata
// layer cannot name is a type the metadata layer re-invents.
pub use nros_node::timer::TimerClockSource;

/// phase-467 Q4 / ledger row `c:logging_rosout_enabled` — the `/rosout` log
/// bridge. A module re-export rather than a flat one: the names a caller
/// needs (`enable`, `pump`, `qos`, `qos_bounded`, `TOPIC`) are generic words
/// that only read correctly under the `rosout::` prefix.
/// Gated like the module it comes from: `nros_node::rosout` is
/// `#[cfg(all(feature = "rosout", any(has_rmw, test)))]` there, and `has_rmw`
/// is `nros-node`'s own build-script cfg — this crate spells the same
/// condition as `feature = "rmw-cffi"`, exactly as the `parameter_services`
/// re-export below does.
#[cfg(all(feature = "rosout", feature = "rmw-cffi"))]
pub use nros_node::rosout;

// Re-export transport types (middleware-agnostic)
pub use nros_rmw::{
    ClientTrait, Publisher, QoSDurabilityPolicy, QoSHistoryPolicy, QoSLivelinessPolicy,
    QoSOverride, QoSOverrideRole, QoSOverrideValue, QoSPolicyMask, QoSProfile,
    QoSReliabilityPolicy, Rmw, RmwConfig, ServiceInfo, ServiceRequest, ServiceTrait, Session,
    SessionMode, Subscription as SubscriptionTrait, TopicInfo, Transport, TransportConfig,
};

/// Phase 108.B — standard ROS-2-equivalent QoS profiles. Match
/// upstream `rmw_qos_profile_default` etc. field-by-field. Backends
/// validate against these synchronously at create time; no silent
/// downgrade.
// phase-379 W5 — rclrs exports the eight QoS presets as CRATE-LEVEL consts
// (`rclrs::QOS_PROFILE_DEFAULT`); ours were associated consts on `QoSProfile`
// and nothing re-exported them, so `use rclrs::QOS_PROFILE_DEFAULT` had no
// counterpart to port to. The NAMES already matched exactly — only the path
// did not, which is why the ledger filed these as a re-export and not a
// rename.
//
// These ALIAS the associated consts rather than restating them. `nros::qos`
// below is a second, hand-written copy of the same presets that predates them;
// `qos_presets_agree` in the test module asserts the two never drift, which is
// the hand-mirror class (issues 0088/0160/0245) one layer up.
/// `rmw_qos_profile_default` — reliable, volatile, keep-last(10).
pub const QOS_PROFILE_DEFAULT: QoSProfile = QoSProfile::QOS_PROFILE_DEFAULT;
/// `rmw_qos_profile_system_default` — the RMW implementation's own defaults.
pub const QOS_PROFILE_SYSTEM_DEFAULT: QoSProfile = QoSProfile::QOS_PROFILE_SYSTEM_DEFAULT;
/// `rmw_qos_profile_sensor_data` — best-effort, keep-last(5).
pub const QOS_PROFILE_SENSOR_DATA: QoSProfile = QoSProfile::QOS_PROFILE_SENSOR_DATA;
/// `rmw_qos_profile_services_default`.
pub const QOS_PROFILE_SERVICES_DEFAULT: QoSProfile = QoSProfile::QOS_PROFILE_SERVICES_DEFAULT;
/// `rmw_qos_profile_parameters` — reliable, depth 1000.
pub const QOS_PROFILE_PARAMETERS: QoSProfile = QoSProfile::QOS_PROFILE_PARAMETERS;
/// `rmw_qos_profile_parameter_events`.
pub const QOS_PROFILE_PARAMETER_EVENTS: QoSProfile = QoSProfile::QOS_PROFILE_PARAMETER_EVENTS;
/// The clock preset — sensor-data shaped with depth 1.
pub const QOS_PROFILE_CLOCK: QoSProfile = QoSProfile::QOS_PROFILE_CLOCK;
/// The action-status preset — reliable + transient-local, depth 1.
pub const QOS_PROFILE_ACTION_STATUS_DEFAULT: QoSProfile =
    QoSProfile::QOS_PROFILE_ACTION_STATUS_DEFAULT;

/// The five presets under their older, shorter names.
///
/// **Every one of these is an ALIAS.** phase-428 W10 — this module used to
/// RESTATE four of the five as struct literals: `DEFAULT` spelled all ten fields
/// out, `SENSOR_DATA` and `PARAMETERS` were `..DEFAULT` updates of it, and
/// `SERVICES_DEFAULT` was `= DEFAULT` — a second, independent transcription of
/// upstream's table living 40 lines below the first. Only `SYSTEM_DEFAULT` was a
/// real alias, and the comment that made it one claimed it was joining "the
/// other four", which was not true of any of them.
///
/// That is the mirror this work item removes: upstream's 7 profiles were
/// hand-written in four places across the repo — here, the crate-level
/// `QOS_PROFILE_*` consts above, `nros-rmw/src/traits.rs`, and
/// `nros-rmw-abi/include/nros/rmw_entity.h` — about 26 constants for a 7-row
/// table, with no gate binding them. `QOS_PROFILE_PARAMETER_EVENTS` is the proof
/// that the arrangement does not hold: it is `KeepAll, 0` in `traits.rs` under a
/// comment claiming it matched `rmw_qos_profile_parameter_events`, which is
/// `KEEP_LAST, 1000`.
///
/// So this module now declares no values at all. The SSoT is
/// [`QoSProfile`]'s associated consts, and a correction there — including the
/// `PARAMETER_EVENTS` one — reaches these names without anyone remembering to
/// come here. Note that the alias set is a SUBSET: `CLOCK`,
/// `PARAMETER_EVENTS`, `ACTION_STATUS_DEFAULT` and `PX4` have no short spelling
/// and are reached as `nros::QOS_PROFILE_*` or `QoSProfile::QOS_PROFILE_*`.
pub mod qos {
    use crate::QoSProfile;

    /// `rmw_qos_profile_default` — reliable + volatile + keep-last(10),
    /// automatic liveliness, no deadline / lifespan.
    pub const DEFAULT: QoSProfile = QoSProfile::QOS_PROFILE_DEFAULT;

    /// `rmw_qos_profile_sensor_data` — best-effort + volatile + keep-last(5).
    pub const SENSOR_DATA: QoSProfile = QoSProfile::QOS_PROFILE_SENSOR_DATA;

    /// `rmw_qos_profile_services_default` — reliable + volatile +
    /// keep-last(10).
    ///
    /// It aliases its OWN associated const, not `DEFAULT`. The two profiles
    /// hold the same values upstream and are two upstream constants; writing
    /// this one as `= DEFAULT`, which is what it said before W10, would make a
    /// future divergence between them invisible here.
    pub const SERVICES_DEFAULT: QoSProfile = QoSProfile::QOS_PROFILE_SERVICES_DEFAULT;

    /// `rmw_qos_profile_parameters` — reliable + volatile + keep-last(**1000**).
    pub const PARAMETERS: QoSProfile = QoSProfile::QOS_PROFILE_PARAMETERS;

    /// `rmw_qos_profile_system_default` — **an absence, not a profile**: every
    /// policy is the SYSTEM_DEFAULT sentinel and the depth is the depth
    /// sentinel, resolved by whichever backend is linked.
    ///
    /// issue 0829 — this said `= DEFAULT` (depth 10) while
    /// `QoSProfile::QOS_PROFILE_SYSTEM_DEFAULT` said depth 1, so one name
    /// shipped two queue depths depending on which spelling a caller reached.
    /// It was the first of these to become an alias, and since W10 it is no
    /// longer the only one: see `QoSProfile::QOS_PROFILE_SYSTEM_DEFAULT`.
    pub const SYSTEM_DEFAULT: QoSProfile = QoSProfile::QOS_PROFILE_SYSTEM_DEFAULT;
}

// Re-export safety types when feature is enabled
#[cfg(feature = "safety-e2e")]
pub use nros_rmw::{IntegrityStatus, SafetyValidator, crc32};

// Phase 248 C7 step 1 — the `nros::platform::zephyr` module (the
// `wait_for_network` FFI wrapper) RELOCATED to `nros-platform`
// (`nros_platform::zephyr::wait_network`); callers reference it via
// `::nros_platform::zephyr::wait_network`. nros no longer hosts a platform
// helper module. (The `zephyr_component_main!` macro relocation is C7 step 2.)
//
/// Backend-specific internal types.
///
/// These types are implementation details of the transport backends.
/// Most users should use the high-level APIs (`Executor`, etc.)
/// instead of these types directly.
///
/// The `Rmw*` type aliases resolve to whichever backend is active at compile time,
/// providing a backend-agnostic way to reference concrete transport types.
pub mod internals {
    // ── Backend-agnostic type aliases ────────────────────────────────────
    // These resolve to the concrete types of the active RMW backend.
    // Today the only exposed backend at this layer is the cffi shim.

    #[cfg(feature = "rmw-cffi")]
    pub type RmwSession = nros_rmw_cffi::CffiSession;
    #[cfg(feature = "rmw-cffi")]
    pub type RmwPublisher = nros_rmw_cffi::CffiPublisher;
    #[cfg(feature = "rmw-cffi")]
    pub type RmwSubscriber = nros_rmw_cffi::CffiSubscription;
    #[cfg(feature = "rmw-cffi")]
    pub type RmwServiceServer = nros_rmw_cffi::CffiService;
    #[cfg(feature = "rmw-cffi")]
    pub type RmwServiceClient = nros_rmw_cffi::CffiClient;

    /// Phase 124.A — zero-copy publisher slot type. Lives in the
    /// `internals` module so `nros-c` can construct + transmute the
    /// lifetime when boxing the slot for the C-side `_loan` /
    /// `_commit` / `_discard` token plumbing.
    #[cfg(all(feature = "rmw-cffi", feature = "lending"))]
    pub type RmwSlot<'a> = nros_rmw_cffi::CffiSlot<'a>;

    /// Phase 124.A — zero-copy subscriber view type.
    #[cfg(all(feature = "rmw-cffi", feature = "lending"))]
    pub type RmwView<'a> = nros_rmw_cffi::CffiView<'a>;

    /// Open a new middleware session.
    ///
    /// Wraps the backend-specific session constructor behind a common signature.
    /// Used by the C API (`nros-c`); Rust users should prefer `Executor::open()`.
    ///
    /// Phase 156 — takes an explicit primary backend by name, mirroring what
    /// `Executor::open` does for Rust callers. Without it, C bridges built with
    /// two linked backends (e.g. xrce + dds) get whichever ctor fires first —
    /// non-deterministic across link orderings, and often the wrong backend for
    /// the bridge's intended primary.
    ///
    /// Issue 1050 defect (3) — `rmw` is the RESOLVED selector, not a second
    /// reading of the environment. This function used to consult
    /// `rmw_selector()` itself, which made it the tree's second answer to "which
    /// backend?" and blind to every rung but the environment: a C image with a
    /// BAKED selector had it discarded here. The caller resolves the whole
    /// ladder (`env > baked > none`) through `ExecutorConfig` and passes the
    /// result; `None` means the registry must hold exactly one backend, which
    /// `nros_rmw_cffi::get_vtable` now enforces rather than assumes.
    #[cfg(feature = "rmw-cffi")]
    pub fn open_session(
        locator: &str,
        mode: nros_rmw::SessionMode,
        domain_id: u32,
        node_name: &str,
        rmw: Option<&str>,
    ) -> Result<RmwSession, nros_rmw::TransportError> {
        use nros_rmw::Rmw;

        // Phase 249 P4b.1 — every linked backend self-registered via
        // its `.init_array` ctor before `main` (RFC-0042 §D3.3); no
        // runtime section walk.

        let config = nros_rmw::RmwConfig {
            locator,
            mode,
            domain_id,
            node_name,
            namespace: "",
            properties: &[],
        };
        // Phase 155.B — propagate the real `TransportError` instead of
        // collapsing every backend failure to `ConnectionFailed`. The
        // C-side `rclc_support_init` decodes the variant into a
        // specific `NROS_RET_*` code so "init -> -X" tells the user
        // which precondition the backend rejected.
        // issue 1050 defect (3) — the selector ARRIVES here now. It used to be
        // read from `$NROS_RMW` on the spot, which is why a baked one could not
        // reach this path: the reader knew about one rung and the resolver knew
        // about two. The environment still wins; it wins in `ExecutorConfig`,
        // where every other field's precedence is decided, instead of here.
        if let Some(name) = rmw {
            return nros_rmw_cffi::CffiRmw::open_with_rmw(name, &config);
        }
        nros_rmw_cffi::CffiRmw.open(&config)
    }

    /// Drive middleware I/O for pull-based backends.
    ///
    /// Delegates to [`Session::drive_io()`](nros_rmw::Session::drive_io),
    /// which each backend implements appropriately (no-op for push-based,
    /// poll for pull-based).
    ///
    /// Used by the C API executor before polling handles.
    #[cfg(feature = "rmw-cffi")]
    pub fn drive_session_io(session: &mut RmwSession, timeout_ms: i32) {
        use nros_rmw::Session;
        let _ = session.drive_io(timeout_ms);
    }
}

// Re-export types that don't depend on RMW (always available)
pub use nros_node::{
    BOOT_SET_DOMAIN, BOOT_SET_LOCATOR, BOOT_SET_NAMESPACE, BOOT_SET_NODE_NAME, BakedBootConfig,
    BootConfig, BootConfigError, DOMAIN_ID_EXPLICIT_ZERO_C_ABI, DOMAIN_ID_MAX, ExecutorConfig,
    ExecutorSemantics, GuardCondition, HandleId, HandleSet, InvocationMode, NROS_BOOT_CONFIG_MAGIC,
    NROS_BOOT_CONFIG_VERSION, RawCancelCallback, RawGoalCallback, RawServiceCallback,
    RawSubscriptionCallback, ReadinessSnapshot, ShutdownCallbackFn, ShutdownCallbackHandle,
    ShutdownPhase, SpinOnceResult, SpinOptions, SpinPeriodPollingResult, Trigger,
    baked_domain_from_c_abi,
};

// ---------------------------------------------------------------------------
// The error vocabulary (issue 0783). Both re-exports are unconditional.
//
// Every fallible call in the Rust user API returns `NodeError`, and
// `NodeError::Transport(TransportError)` is its most common variant — so
// handling one means naming both. They used to be exported from two unrelated
// blocks (`NodeError` with the boot/executor types, `TransportError` with the
// transport traits), which is a discoverability nit rather than a capability
// gap: both were always reachable, and `prelude` already listed them together.
// Nothing here changes what `nros::` exports.
//
// There is deliberately NO numeric code type beside them. A Rust caller matches
// a flat enum; the numeric vocabulary is the C ABI's `rcl_ret_t` /
// `NROS_RET_*` (0, -1..-16), which is its own space and not `rcl_ret_t`'s.
// nros-core carried an `rcl_ret_t` mirror (`RclReturnCode`) and an error that
// wrapped it (`NanoRosError`); neither was ever reachable from this facade and
// neither had a producer, so issue 0783 deleted them rather than exporting a
// type a user could name and never receive. RFC-0036's Errors row now describes
// what these two are.
// ---------------------------------------------------------------------------
/// phase-436 W7 — installing a port's park primitive, with the wake-object
/// constraint stated once. Board entries reach it through this facade because
/// that is the dependency they already carry.
///
/// Gated like every other `executor::` re-export here, and it has to be: the
/// module itself is `#[cfg(any(has_rmw, test))]`, and `has_rmw` is emitted by
/// `nros-node`'s build script exactly when `CARGO_FEATURE_RMW_CFFI` is set. An
/// ungated `pub use` therefore names a module that does not exist wherever no
/// RMW seam is compiled in — which is not a hypothetical configuration but the
/// one `nros build --metadata-mode` uses, where it is `error[E0432]:
/// unresolved import` before the harness reaches a single component.
#[cfg(feature = "rmw-cffi")]
pub use nros_node::executor::port_park;

/// phase-436 B2 — the other half of the seam, for the boards that now use it.
///
/// `port_park` above is what a port hands the executor to WAIT with;
/// these are what it hands the executor to be told WHEN. A board registering
/// a deadline source receives a [`WakeSourceId`] and reads it back out of
/// `Executor::last_park()`, so without this re-export it could match on
/// neither.
#[cfg(feature = "rmw-cffi")]
pub use nros_node::executor::{MAX_WAKE_SOURCES, NextDeadlineFn, WakeSourceId};

/// issue 1571 — the spawned tiers' executor backing. `nros::main!` emits one
/// `TierExecutorBacking` static per tiered entry and hands its slots to the
/// board's `run_tiers`, which refuses a short block through
/// `check_tier_executor_backing` and opens each spawned tier with
/// `Executor::open_with_session_slot`. Gated like the module it names
/// (`has_rmw` + `alloc` in nros-node).
#[cfg(all(feature = "rmw-cffi", feature = "alloc"))]
pub use nros_node::executor::{
    EXECUTOR_BACKING_DEFAULT_U64S, TierBackingShort, TierExecutorBacking, TierExecutorBackingSlot,
    TierSetupGate, TierSetupGuard, check_tier_executor_backing,
};
/// issue 1598 — each spawned tier's TASK memory (stack + control block):
/// `nros::main!` emits one `TierTaskMemory` static per spawned tier, sized from
/// its `stack_bytes`, and hands the `TierTaskMemorySet` rows to a board whose
/// tier runner creates the task over them (FreeRTOS `xTaskCreateStatic`).
#[cfg(all(feature = "rmw-cffi", feature = "alloc"))]
pub use nros_node::executor::{
    TIER_TASK_TCB_U64S, TierTaskMemory, TierTaskMemoryRaw, TierTaskMemorySet,
};

pub use nros_node::NodeError;
pub use nros_rmw::TransportError;

// RFC-0052 / phase-296 W3b — on-target contract-monitor types. Baked
// `system_monitors.rs` uses the fully-qualified `::nros_node::executor::
// monitor::*` path; this re-export lets hand-written entries and fixtures
// reach the same types through the `nros` umbrella (they install the
// tables via `Executor::set_monitor_table` / `set_age_table` and drain
// with `drain_violations`). The monitor module is `has_rmw`-gated in
// nros-node (it names entity types), so mirror that with `rmw-cffi`.
#[cfg(feature = "rmw-cffi")]
pub mod monitor {
    pub use nros_node::executor::monitor::{
        AgeMonitorSpec, GuardRef, GuardSpec, HazardCell, HazardSpec, MAX_AGE_MONITORS,
        MAX_MONITORS, MAX_VIOLATIONS, MECHANISM_EXECUTOR, MECHANISM_TIMER, MonitorArming,
        MonitorSpec, MonitorTableFull, NO_SINK, PubMonitorCell, REACTION_NONE, RULE_IDS,
        ReactionEvent, ReactionHookFn, SubMonitorCell, Violation, check_table_capacity, fqn_hash,
        request_monitor_arming, route_next_due_us, rule_code, rule_name,
    };
}

// Issues 1635 / 1676 — the contract-monitor install and the `/diagnostics`
// reporter, ONE implementation: `nros::main!` calls `install_contract_monitors`
// on every executor it builds, and `nros-cpp`'s `nros_cpp_install_monitors`
// arms the same `DiagSink`.
#[cfg(feature = "rmw-cffi")]
pub mod contract;

// Re-export RMW-dependent types (require an active transport backend)
#[cfg(feature = "rmw-cffi")]
pub use nros_node::{
    ActionClient, ActionClientCore, ActionServer, ActionServerCore, ActionServerHandle,
    ActionServerRawHandle, ActiveGoal, CompletedGoal, EmbeddedPublisher, EmbeddedRawPublisher,
    EmbeddedServiceClient, EmbeddedServiceServer, Executor, ExecutorSizing, FeedbackStream,
    GoalFeedbackStream, LoanError, Node, Promise, PublishLoan, RawActionClientSpec,
    RawActionServerSpec, RawActiveGoal, RawSubscription, RecvView, SessionHandle, SessionSpec,
    Subscription, action_channel_type,
};

// phase-271 (issue #110) — per-entry executor sizing helper: the orchestration
// codegen's `build_executor` sizes its backing to the system's callback count
// via `nros::arena_size_for(CALLBACK_COUNT)` + `ExecutorSizing`, replacing the
// workspace-global `NROS_EXECUTOR_MAX_CBS`.
#[cfg(feature = "rmw-cffi")]
pub use nros_node::config::arena_size_for;

/// The configured default receive-buffer size (`NROS_SUBSCRIPTION_BUFFER_SIZE`).
///
/// NOT a fallback for a missing bound any more (phase-403 W0): [`rx_buffer_for!`]
/// used to expand to this for an unbounded type and now refuses to compile
/// instead. It stays public, and stays the default, for the paths that have no
/// `M` to ask rather than a bound they declined to use -- `create_subscription_raw`
/// and the RFC-0043 type-name-string subscriptions, the service / action / TX
/// buffer defaults, the `pubsub_entry` term of the arena derivation in
/// `nros-node/build.rs`, and its weld to the C API's `MESSAGE_BUFFER_SIZE`.
/// Whether the arena derivation should stop leaning on it is a phase-403 W5
/// question.
///
/// Re-exported here (rather than reached through `nros_node`) because a macro
/// expands at the CALLER, where `nros_node` may not be a dependency at all.
pub use nros_node::config::DEFAULT_RX_BUF_SIZE;

/// Phase 392 W3b — the bound behind [`rx_buffer_for!`]. Not part of the stable
/// surface; call the macro.
///
/// Public only because a `macro_rules!` body is expanded in the caller's crate
/// and can reach nothing private. `#[doc(hidden)]` and `__`-prefixed for the
/// same reason every other macro-support item in this crate is.
#[doc(hidden)]
pub const fn __rx_bound<M: nros_serdes::schema::Message>() -> Option<usize> {
    nros_serdes::size::max_serialized_bound::<M>()
}

// Phase 173.5 — board config traits. `BoardConfig` (read locator /
// domain). `BoardTransportConfig` was removed with its dead
// setters (issue 1064); the live path is the deploy overlay.
pub use nros_platform::BoardConfig;

// Phase 216.A.1 — `DispatchStrategy` enum. User-visible at
// `nros::DispatchStrategy`; the canonical home is `nros_platform::
// board::dispatch` so the C ABI symbol the `nros::node!()` macro emits
// (`__nros_node_<pkg>_dispatch_strategy() -> u8`) lives next to the
// other board-side trampolines.
pub use nros_platform::DispatchStrategy;

/// Implementation detail — used by `nros::node!()` macro expansion.
///
/// Re-exports `nros_platform` so the macro's emitted trampoline can
/// reference `RuntimeCtx` / `RuntimeError` / the `Node*Fn`
/// fn-pointer aliases without forcing every consumer Node pkg's
/// `Cargo.toml` to carry an explicit `nros-platform` dep on top of
/// `nros`. Phase 212.M-F.13 path (b).
///
/// Not part of the public API — paths under this module may change at
/// any time. End users should depend on `nros` alone and invoke
/// `nros::node!()`; the macro routes through here automatically.
#[doc(hidden)]
pub mod __macro_support {
    pub use ::nros_platform;

    /// phase-314 — whether THIS `nros` build carries the parameter services.
    ///
    /// The `nros::main!` expansion const-asserts it when the system declares
    /// `[param_services]`. A cfg in the entry crate cannot see this: the
    /// feature belongs to `nros`, and the entry enables it through its
    /// dependency, so only `nros` itself can report the answer.
    ///
    /// Without the assert the mismatch is SILENT — `apply_param_services` is a
    /// no-op, the build succeeds, the image boots, and `ros2 param list`
    /// returns nothing.
    pub const PARAM_SERVICES_ENABLED: bool = cfg!(feature = "param-services");

    /// phase-461 W6 — whether THIS `nros` build carries the parameter STORE
    /// (`param-store`, which `param-services` implies). A system declaring the
    /// `params` axis const-asserts it, for the reason above: without the
    /// feature `apply_param_store` is a no-op and every `declare_parameter`
    /// is refused at boot instead of at compile time.
    pub const PARAM_STORE_ENABLED: bool = cfg!(feature = "param-store");

    /// Issue 1766 — the same answer for the other capability axes a leaf
    /// can declare in `[system] features`. A Form-1 `nros::main!()`
    /// const-asserts the flag of every declared axis
    /// (`nros_orchestration_ir::leaf_capabilities::LeafAxis::compiled_flag`),
    /// because without the feature the axis is compiled out and the
    /// declaration would be dropped in silence.
    pub const LIFECYCLE_SERVICES_ENABLED: bool = cfg!(feature = "lifecycle-services");
    /// See [`LIFECYCLE_SERVICES_ENABLED`].
    pub const SAFETY_E2E_ENABLED: bool = cfg!(feature = "safety-e2e");
    /// See [`LIFECYCLE_SERVICES_ENABLED`].
    pub const ROSOUT_ENABLED: bool = cfg!(feature = "rosout");

    /// Issue 0257 — the build-time executor callback-table size
    /// (`NROS_EXECUTOR_MAX_CBS`, default 4). Re-exported so the `nros::main!`
    /// expansion can `const`-assert the model's entity count against the
    /// capacity that ACTUALLY compiles in, instead of letting the image boot
    /// and die on `create_timer (code=-6 Full)`.
    pub use ::nros_node::config::MAX_CBS as EXECUTOR_MAX_CBS;
}

// Phase 110.B / 110.G — scheduling-context API surface. Consumers
// of the Phase 110 cyclic / TT scheduler need these types to
// describe schedules and bind handles; re-exporting them here
// keeps user code free of `nros_node::executor::sched_context`
// path noise. Gated on `rmw-cffi`: the source module is
// `#[cfg(any(has_rmw, test))]` in nros-node, so it only exists once
// an RMW backend is linked (matches the re-export block above).
#[cfg(feature = "rmw-cffi")]
pub use nros_node::executor::sched_context::{
    DeadlineAction, DeadlinePolicy, OptUs, Priority, SchedClass, SchedContext, SchedContextId,
    TimeTriggeredSchedule, TimeTriggeredScheduleError, TimeTriggeredWindow,
};

#[cfg(all(feature = "std", feature = "rmw-cffi"))]
pub use nros_node::SpinPeriodResult;

// Re-export service types
pub use nros_core::{ServiceClient, ServiceServer};

// Re-export action types.
//
// issue 0796 — `CancelResponse` (the per-goal Reject/Accept decision) and
// `CancelReturnCode` (the `action_msgs/srv/CancelGoal` RPC status) are two
// concepts that shared one name until the split. Both are exported: without
// `CancelReturnCode` here, `ActionClient::cancel_goal`'s `Promise<CancelReturnCode>`
// could not be NAMED from `nros::` alone.
pub use nros_core::{
    CancelResponse, CancelReturnCode, GoalId, GoalInfo, GoalResponse, GoalStatus,
    GoalStatusStamped, RosAction,
};

// Re-export lifecycle types (always available, no_std compatible)
pub use nros_core::{LifecycleState, LifecycleTransition, TransitionResult};
pub use nros_node::{LifecycleCallbackFn, LifecycleError, LifecyclePollingNode};

/// Re-export of the full lifecycle module so examples can reach
/// `LifecycleCallbackSlot`, `LifecyclePollingNodeCtx`, etc.
pub mod lifecycle {
    pub use nros_core::lifecycle::{LifecycleState, LifecycleTransition, TransitionResult};
    pub use nros_node::lifecycle::*;
}

// Phase 128.G — bridge surface re-exports. Gated behind the
// `bridge` / `config` umbrella features so single-backend builds
// don't pull in `nros-bridge` (or, for `config`, the TOML stack).
#[cfg(feature = "bridge")]
pub use nros_bridge as bridge;

#[cfg(feature = "config")]
pub use nros_bridge::run_from_config;

// Re-export parameter types.
//
// phase-382 W2' — `ParameterStorage` / `ParameterTable` are here because the
// store's slots are CALLER-OWNED: anyone constructing a `ParameterServer`
// outside an executor has to place the storage and lend it.
// phase-426 W1 — `NodeKey` is here because every per-parameter call names the
// node it is about; a consumer holding a `ParameterServer` needs it to say so.
// phase-417 W4.a — the rest of the parameter vocabulary. Five ledger rows
// (`rust:ParameterRange`, `rust:ParameterRanges`, `rust:Parameters`,
// `rust:Node::use_undeclared_parameters`, `rust:RmwParameterConversionError`)
// were not missing capabilities: `nros_params` had every one of them and this
// list stopped at ten names, so a user of the facade could build a range
// through the builder's scalar arguments and never NAME the type it produced.
// An unexported type is a capability a user cannot write down.
pub use nros_params::{
    DeclarationError, FloatingPointRange, IntegerRange, MAX_ON_SET_CALLBACKS, MandatoryParameter,
    NodeKey, OnSetContext, OnSetParameterFn, OnSetParameterHandle, OptionalParameter, Parameter,
    ParameterBuilder, ParameterDescriptor, ParameterError, ParameterRange, ParameterServer,
    ParameterStorage, ParameterTable, ParameterType, ParameterValue, ParameterVariant,
    ReadOnlyParameter, SetParameterResult, UndeclaredParameters,
};
// The wire-side half: why an `rcl_interfaces` parameter value could not be
// turned into a native one. The `~/set_parameters` handler already puts
// `reason()` into the `SetParametersResult`; without the type a user could read
// the sentence and not match on the cause.
// Gated like the module it comes from: `parameter_services` is the six
// `rcl_interfaces/srv/*` servers, and an image without them has no wire side
// for this error to describe.
// Gated like the module it comes from: `parameter_services` is
// `#[cfg(all(feature = "param-services", any(has_rmw, test)))]` in nros-node,
// so it exists only once an RMW backend is linked — the same pairing the
// `sched_context` re-export above uses.
#[cfg(all(feature = "param-services", feature = "rmw-cffi"))]
pub use nros_node::parameter_services::ValueConversionError;
/// Prelude module for convenient imports
///
/// Import everything you need with a single statement:
/// ```
/// use nros::prelude::*;
/// ```
/// phase-379 W5 — the RTOS machinery, named explicitly.
///
/// The second tier of the two-tier surface. `nros::prelude` is the API a ported
/// ROS 2 node uses; everything here exists because the target is an RTOS, has no
/// correspondent in rclrs/rclcpp/rclc, and a ROS 2 developer reading a node
/// should not have to step over it.
///
/// Nothing moved out of `nros::` — these are re-exports, and every name is still
/// reachable at its old path. What changed is that they are no longer dragged in
/// by `use nros::prelude::*`.
///
/// The membership rule is mechanical rather than taste: a name belongs in the
/// PRELUDE iff the parity ledger gives it a non-`extension` verdict — i.e. it
/// corresponds to something in rclrs, rclcpp or rclc. Names with no
/// correspondent belong here, unless they are load-bearing for startup
/// (`ExecutorConfig`, `SpinOptions`), which is an argued allow-list rather than
/// an exception anyone may grow.
pub mod embedded {
    // Wire encoding. A node publishes typed messages; these are for code that
    // handles bytes, which upstream hides entirely.
    pub use crate::{CdrReader, CdrWriter};

    // Handle bookkeeping — the static tables that replace an allocator.
    #[cfg(feature = "rmw-cffi")]
    pub use crate::{HandleId, HandleSet, InvocationMode};

    // Component/runtime plumbing, and the source-metadata capture the
    // orchestration layer records. None of it appears in a ported node.
    pub use crate::MetadataRecorder;

    // Entity REGISTRATION vocabulary. A ported node writes
    // `create_publisher(...)`; these are what the declaration macros and the
    // orchestration layer use to describe what was created.
    pub use crate::{
        ActionTag, Callback, CallbackEffectKind, EntityKind, NodeRuntime, ServiceTag,
        SourceLocationMetadata, SourceNameKind, SubscriptionTag,
    };
    #[cfg(feature = "rmw-cffi")]
    pub use crate::{CallbackEffects, record_node_metadata, register_node};
    // Gated where the root gates it — the export follows the capability, not
    // the tier.
    #[cfg(feature = "alloc")]
    pub use crate::SourceMetadataExport;
}

pub mod prelude {
    // phase-379 W5 — the RTOS machinery moved to `nros::embedded`. Removed
    // here rather than re-exported from both: a two-tier surface that still
    // drags tier two in through the glob is one tier with extra words.

    pub use crate::{
        Deserialize, Logger, MessageInfo, QoSDurabilityPolicy, QoSHistoryPolicy, QoSProfile,
        QoSReliabilityPolicy, RosMessage, RosService, Serialize, TopicInfo,
    };

    // phase-417 / issue 0589 — logging, in the glob a node author already
    // writes. `Logger` above now means `nros_log::Logger`; these are what
    // drives it. Without them the shortest path from `use nros::prelude::*` to
    // a printed line was `std::println!`, which kills a Zephyr `native_sim`
    // image outright.
    //
    // The five severity macros now carry rclrs's OWN names (RFC-0089, settled
    // 2026-09-04), so a ROS 2 developer meeting one through the glob meets the
    // exact spelling their client library has, not a near-miss of it. That is
    // the property `check-prelude-tiers` enforces mechanically: a ledger
    // `extension` may not sit in the glob.
    //
    // `Severity`, `get_logger`, `get_or_create_logger`, `register_logger` and
    // `nros_trace` are ledger `extension`s -- rclrs has no correspondent for a
    // free logger lookup, a registry, or a TRACE severity (it stops at debug).
    // They stay behind `nros::logging::` / the crate root, where reaching for
    // one is a decision. phase-379 W5's rule, applied to this phase's own work.
    //
    // The throttle macros ARE here: they are ledger `divergence`s, not
    // extensions -- rclrs has the capability under a different decomposition
    // (`log_info!(logger.throttle(d), "…")`), so the glob is not introducing a
    // name with no upstream counterpart.
    #[cfg(all(feature = "alloc", feature = "rmw-cffi"))]
    pub use crate::{Component, DeclarativeNode, NodeContext};
    #[cfg(feature = "alloc")]
    pub use crate::{
        NodeActionClient, NodeActionServer, NodeDeclError, NodeOptions, NodeParameter,
        NodePublisher, NodeResult, NodeServiceClient, NodeServiceServer, NodeSubscription,
        NodeTimer, ParameterDefault, node,
    };
    pub use crate::{
        log_debug, log_error, log_fatal, log_info, log_warn, nros_debug_throttle,
        nros_debug_throttle_at, nros_error_throttle, nros_error_throttle_at, nros_fatal_throttle,
        nros_fatal_throttle_at, nros_info_throttle, nros_info_throttle_at, nros_warn_throttle,
        nros_warn_throttle_at,
    };

    // Re-export lifecycle types
    pub use crate::{
        LifecycleCallbackFn, LifecycleError, LifecyclePollingNode, LifecycleState,
        LifecycleTransition, TransitionResult,
    };

    // Re-export executor config + handle types (always available)
    pub use crate::{
        ExecutorConfig, GuardCondition, NodeError, SessionMode, SpinOnceResult, SpinOptions,
        SpinPeriodPollingResult, TransportError, Trigger,
    };

    // issue 0687 — `ExecutorConfig::from_env()` is an extension trait now (the
    // environment is read at this crate's edge, not in the core), so the
    // spelling only works where the trait is in scope. It is in the prelude
    // precisely so that the consumers written against the inherent method —
    // the native examples, the benches — keep compiling unchanged.
    #[cfg(feature = "env")]
    pub use crate::ExecutorConfigEnvExt;

    // Re-export RMW-dependent executor + handle types
    #[cfg(feature = "rmw-cffi")]
    pub use crate::{
        EmbeddedPublisher, EmbeddedServiceClient, Executor, FeedbackStream, Node, Promise,
        Subscription,
    };

    // Publisher/Subscriber options (topic + QoS).
    pub use crate::{PublisherOptions, SubscriptionOptions};

    #[cfg(all(feature = "std", feature = "rmw-cffi"))]
    pub use crate::SpinPeriodResult;

    // Re-export parameter types
    pub use crate::{ParameterServer, ParameterStorage, ParameterType, ParameterValue};

    // Re-export typed parameter API (rclrs-compatible builder pattern)
    pub use crate::{
        MandatoryParameter, OptionalParameter, ParameterBuilder, ParameterError, ParameterVariant,
        ReadOnlyParameter,
    };

    // Re-export action types
    pub use crate::{GoalId, GoalInfo, GoalResponse, GoalStatus, GoalStatusStamped, RosAction};

    // Re-export Time, Duration, Clock from core
    pub use nros_core::{Clock, ClockType, Duration, Time};

    // Re-export timer types
    pub use crate::{TimerCallbackFn, TimerDuration, TimerHandle, TimerMode};
}

/// Derive macros for message types
///
/// Use these macros to generate message serialization code.
/// These macros help you create custom message types that are compatible
/// with ROS 2's CDR serialization format.
pub mod derive {
    #[cfg(feature = "macros")]
    pub use nros_macros::RosMessage;
}

#[cfg(test)]
mod tests {
    #[test]
    fn test_prelude_imports() {
        // This test just verifies that the prelude compiles
        use crate::prelude::*;

        let _ = QoSProfile::BEST_EFFORT;
    }

    /// The component trait, its registration context and the result type
    /// resolve under the names phase-483 W2/W3 gave them: `Component` (the
    /// trait, which phase-212 had named `Node`) and a `NodeContext` with no
    /// runtime parameter.
    #[cfg(feature = "rmw-cffi")]
    #[test]
    fn node_context_types_resolve() {
        fn _take_node_ctx<N: crate::Component>(_: &mut crate::NodeContext<'_>) {}
        let _: crate::NodeResult<()> = Ok(());
    }
}

// ---------------------------------------------------------------------------
// phase-361 W8.e / issue 0594 — capabilities REQUIRE the heap / the standard
// library, they do not enable it. Turning `alloc` or `std` on for the user
// silently changes what their firmware image is; naming the feature they must
// add does not.
// ---------------------------------------------------------------------------
// issue 0687 follow-up — `alloc`, not `std`. The reason recorded here ("writes
// a file and exits") was never this crate's: the file write is `nros-cpp`'s
// `metadata_hooks`. What `metadata_mode.rs` actually needed was a `Sync`
// global, and it named `std::sync::Mutex` for it; on the portable mutex the
// capability is `String` + `format!` + a lock, i.e. the heap and nothing more.
#[cfg(all(feature = "metadata-mode", not(feature = "alloc")))]
compile_error!(
    "`metadata-mode` records into a heap-allocated global: add \"alloc\" to this crate's features"
);
// Emitted here as well as in `nros-node`, and NOT for the reason it first
// looks like. `nros = { features = ["env"] }` alone does not reach this line:
// `env` forwards to `nros-node/env`, nros-node is compiled first, and its own
// guard aborts the build there — measured, not assumed. What this covers is
// the case feature unification creates, where some other crate in the graph
// turns `nros-node/std` on so that guard stays quiet while THIS crate's `std`
// is still off. Rare, and exactly the shape that would otherwise compile a
// hosted capability into a build that never named the standard library.
#[cfg(all(feature = "env", not(feature = "std")))]
compile_error!(
    "`env` reads the process environment, which needs the standard library: add \"std\" to this crate's features"
);

// phase-379 W5, revised by phase-428 W10 — the crate-level `QOS_PROFILE_*`
// presets (rclrs parity) and the older `nros::qos::*` module are two spellings
// of the same profiles. BOTH now alias `QoSProfile`'s associated consts; until
// W10 the second restated them as struct literals, and these tests were the only
// thing holding the two copies together.
//
// They are kept, and what they assert has changed meaning. They no longer catch
// a hand-mirror drifting (there is no longer a hand mirror to drift — issues
// 0088 / 0160 / 0245). They catch a REINTRODUCTION: the moment someone writes a
// literal into either surface instead of aliasing, a value can differ and one of
// these fails. That is cheap enough to keep and is the only mechanism standing
// between this crate and the arrangement W10 removed.
//
// What they do NOT check, deliberately, is whether the SSoT matches UPSTREAM.
// Two aliases of a wrong constant agree perfectly — which is exactly the state
// `QOS_PROFILE_PARAMETER_EVENTS` was in (`KeepAll, 0` against upstream's
// `KEEP_LAST, 1000`). That assertion belongs beside the associated consts in
// `nros-rmw/src/traits.rs`, not here.
#[cfg(test)]
mod qos_preset_parity {
    use super::*;

    #[test]
    fn crate_level_presets_alias_the_associated_consts() {
        assert_eq!(QOS_PROFILE_DEFAULT, QoSProfile::QOS_PROFILE_DEFAULT);
        assert_eq!(QOS_PROFILE_SENSOR_DATA, QoSProfile::QOS_PROFILE_SENSOR_DATA);
        assert_eq!(QOS_PROFILE_PARAMETERS, QoSProfile::QOS_PROFILE_PARAMETERS);
        assert_eq!(
            QOS_PROFILE_ACTION_STATUS_DEFAULT,
            QoSProfile::QOS_PROFILE_ACTION_STATUS_DEFAULT
        );
    }

    /// `qos::*` was a SEPARATE hand-written copy until phase-428 W10; all five
    /// names alias the associated consts now, so this passes by construction.
    /// It stays as the tripwire for re-introducing a literal — see the module
    /// comment above.
    #[test]
    fn qos_module_agrees_with_the_presets() {
        // issue 0829 FIXED — SYSTEM_DEFAULT was the first to become an alias.
        // It is here rather than in its own pinned test because the two copies
        // no longer say anything a copy could get wrong: both alias the one
        // associated const, which is all sentinel.
        assert_eq!(
            qos::SYSTEM_DEFAULT,
            QOS_PROFILE_SYSTEM_DEFAULT,
            "qos::SYSTEM_DEFAULT drifted"
        );
        assert_eq!(qos::DEFAULT, QOS_PROFILE_DEFAULT, "qos::DEFAULT drifted");
        assert_eq!(
            qos::SENSOR_DATA,
            QOS_PROFILE_SENSOR_DATA,
            "qos::SENSOR_DATA drifted"
        );
        assert_eq!(
            qos::SERVICES_DEFAULT,
            QOS_PROFILE_SERVICES_DEFAULT,
            "qos::SERVICES_DEFAULT drifted"
        );
        assert_eq!(
            qos::PARAMETERS,
            QOS_PROFILE_PARAMETERS,
            "qos::PARAMETERS drifted"
        );
    }

    /// issue 0829, RESOLVED — this test used to PIN the divergence, asserting
    /// depth 10 on the façade side and depth 1 on the `nros-rmw` side because
    /// neither was obviously the live one. Both numbers are gone, and the
    /// replacement is not "we picked one": no concrete depth can be right,
    /// because the two reference RMWs resolve the same sentinel differently
    /// (`rmw_cyclonedds_cpp` → `KEEP_LAST, 1`; `rmw_zenoh_cpp` →
    /// `RMW_ZENOH_DEFAULT_HISTORY_DEPTH`, 42).
    ///
    /// So what is asserted now is the SHAPE: `SYSTEM_DEFAULT` states nothing,
    /// on every field. That is what makes it different from `DEFAULT` — the
    /// two being byte-identical was the older defect, and asserting they
    /// DIFFER is what keeps anyone from quietly aliasing them again.
    #[test]
    fn system_default_states_nothing_on_every_field() {
        use nros_rmw::{
            DEPTH_SYSTEM_DEFAULT, QoSDurabilityPolicy, QoSHistoryPolicy, QoSLivelinessPolicy,
            QoSReliabilityPolicy,
        };
        let sd = QOS_PROFILE_SYSTEM_DEFAULT;
        assert_eq!(sd.reliability, QoSReliabilityPolicy::SystemDefault);
        assert_eq!(sd.durability, QoSDurabilityPolicy::SystemDefault);
        assert_eq!(sd.history, QoSHistoryPolicy::SystemDefault);
        assert_eq!(sd.depth, DEPTH_SYSTEM_DEFAULT);
        // `None` IS the liveliness sentinel — it lowers to
        // `NROS_RMW_LIVELINESS_SYSTEM_DEFAULT` (0), the two having collapsed
        // onto one value in phase-376 W5/B2.
        assert_eq!(sd.liveliness_kind, QoSLivelinessPolicy::None);
        assert!(sd.has_unresolved_system_default());

        // The whole point of the name: it is NOT a synonym for DEFAULT.
        assert_ne!(
            sd, QOS_PROFILE_DEFAULT,
            "SYSTEM_DEFAULT aliased DEFAULT again — see issue 0829"
        );
        assert!(!QOS_PROFILE_DEFAULT.has_unresolved_system_default());
    }
}