node.hpp

Go to the documentation of this file.

// nros-cpp: Node class
// Freestanding C++ — no exceptions, no STL required
 
#ifndef NROS_RCLCPP_NODE_HPP
#define NROS_RCLCPP_NODE_HPP
 
#include <cstdint>
#include <cstddef>
#include <type_traits> // Phase 189.M3.3.e — SFINAE on the callback-style create_service
#if defined(NROS_CPP_STD) || (__STDC_HOSTED__ + 0) // hosted-family: hosted-console
#include <cstdlib>                                 // getenv — Phase 123.B.3 env-aware init
#if defined(NROS_CPP_STD) || (__STDC_HOSTED__ + 0) // hosted-family: hosted-console
// <stdio.h> + unqualified `::fprintf` (issue 0942 / phase-472 W5): `<cstdio>` need not put
// the C names in `std` on a freestanding libstdc++, and `std::fprintf` then fails.
#include <stdio.h>
#endif
#endif
 
// `<map>` is `NROS_CPP_STD` ONLY, and the `|| __STDC_HOSTED__` arm above is
// exactly what it must not have (issue 1431).
//
// phase-417 W4.a put it in that block beside `<cstdlib>`/`<cstdio>`, which is
// safe for THOSE: Zephyr's minimal libcpp ships `cstdlib` and `cstdio`, so the
// hosted arm can be satisfied. It ships no `map`. And `__STDC_HOSTED__` is 1 on
// Zephyr — the compiler is hosted, the include path is not — so the arm fired
// and the header failed to open. MEASURED, `g++ -nostdinc++ -I zephyr/cxx-compat`:
//
//     node.hpp:18:10: fatal error: map: No such file or directory
//
// That is issue 0112's half of the both-probes rule, which CLAUDE.md records:
// `__STDC_HOSTED__` alone is a claim about the COMPILER and the question is
// about the INCLUDE PATH.
//
// The fix is not `__has_include(<map>)`. It is to guard the include with the
// same condition as the only code that needs it. Both consumers —
// `Node::declare_parameters` below and `lifecycle.hpp`'s twin, which includes
// no `<map>` of its own and relies on this one — sit inside
// `NROS_CPP_HAS_STD_STRING` (phase-476 W3), which implies `NROS_CPP_STD`
// because every capability probe is `#if defined(NROS_CPP_STD)`. So this is the
// narrowest guard that still covers every use, and it restores the property
// the block below states as the rule: a hosted STL include lives inside an
// `NROS_CPP_STD` region, never one an `||` arm can reach from a freestanding
// board (issue 0332).
#if defined(NROS_CPP_STD) // hosted-family: container-interop
#include <map>            // phase-417 W4.a — rclcpp::Node::declare_parameters<T>'s argument
#endif
 
// Phase 118.D: ffi.h MUST come before qos.hpp so qos.hpp's
// `#ifndef NROS_CPP_FFI_H` guard sees the canonical types and skips
// its local redefinitions.
#include "rclcpp/detail/nros_cpp_ffi.h"
 
#include "rclcpp/detail/traits.hpp"
#include "rclcpp/handle.hpp" // phase-482 W2 — `Node::SharedPtr`
#include "rclcpp/result.hpp"
#include "rclcpp/owned.hpp" // phase-456 W5 — the return type of the poll `create_service`
#include "rclcpp/detail/hosted_block.hpp"
#include "rclcpp/detail/nros_cpp_config_generated.h"
// phase-482 W3 — `rclcpp::init` below reads `NROS_ENTRY_LOCATOR` /
// `NROS_ENTRY_DOMAIN_ID`, so the ladder that derives them from Kconfig must be
// visible in EVERY TU that calls it, not only in one that also includes
// `<rclcpp/detail/main.hpp>`. A ported `main.cpp` includes `<rclcpp/rclcpp.hpp>` and
// nothing else: on a Zephyr guest it compiled with the macro undefined, passed
// a null locator, and the backend's default dialled the GUEST's own loopback
// (`ConnectionFailed`, then `create_publisher`'s abort). Where nothing bakes a
// locator the header yields `""`, which `nros_cpp_init` reads as absent — the
// same answer a null gave.
#include "rclc/detail/entry_config.h"
#include "rclcpp/qos.hpp"
// Phase 189.M3.1 — rclcpp-style named-options structs
// (`SubscriptionOptions` / `PublisherOptions`) used by the 4-arg
// `create_subscription` / `create_publisher` overloads below.
#include "rclcpp/options.hpp"
// Phase 84.G8: heavy entity headers (publisher / subscription / service /
// client / action_server / action_client) are no longer pulled in here.
// Each entity header provides the out-of-line definition of its
// corresponding `Node::create_X<T>()` template and includes `node.hpp`
// itself. Consumers that #include `rclcpp/rclcpp.hpp` (the umbrella) still
// get every entity + every create method via that path; consumers that
// only want lightweight Node access can include this header directly
// and pay for only the light entities (timer, guard_condition,
// executor) below.
#include "rclcpp/timer.hpp"
// Issue 0789 — `Node::get_clock()` / `Node::now()`. `clock.hpp` pulls in
// `time.hpp` and `duration.hpp`, so a node that stamps a header needs no
// further include.
#include "rclcpp/clock.hpp"
// phase-427 W4 — `ComponentNode` is merged into `Node`, so the two things its
// header pulled in for the merged members come here with them:
//   * `log.hpp`  — `NROS_ERROR`, the OVERRIDABLE sink `report_component_failure`
//     routes through so a freestanding image can be given a boot diagnostic
//     (issue 1015).
//   * `declared_qos.hpp` — `rclcpp::declared_depth` + `DECLARED_DEPTH_UNDECLARED`,
//     read by `Node::check_declared_depth` (phase-403 step 2).
// Neither includes a nano-ros header of its own, so neither can close a cycle
// back onto `node.hpp`. `component.hpp` — which DOES include this file — is why
// the member-pointer `create_subscription_in` / `create_subscription_in_group`
// family is DECLARED here and DEFINED there.
#include "rclcpp/detail/declared_qos.hpp"
#include "rclcpp/detail/declared_params.hpp" // phase-446 W6 -- each node's DECLARED parameters
// phase-417 W4.a -- `rclcpp::ParameterType`, `ParameterDescriptor`,
// `ParameterWrite` and the on-set callback types, which the parameter methods
// below name. Freestanding (`<cstdint>`, `const char*`, the FFI header) and it
// includes nothing that includes this file. `nros.hpp` included it already;
// the declarations here are why it moves onto node.hpp's own include list.
#include "rclcpp/node_parameters.hpp"
#include "rclcpp/logging.hpp"
#include "rclcpp/guard_condition.hpp"
#include "rclcpp/executor.hpp"
// phase-417 stage 2b (RFC-0089) — `rclcpp::TopicEndpointInfo` and the visitor
// typedef used by the graph forwarders below.
#include "rclcpp/graph.hpp"
// Phase 273 (RFC-0047) — callback-group token (value type, no heap).
#include "rclcpp/callback_group.hpp"
// phase-427 W1 declared the parameter facade here; phase-426 W4 took away the
// store it read. The hosted block no longer holds a `ParameterServer` — the
// facade forwards to the EXECUTOR's store — so this header needs
// `parameter.hpp` for nothing of its own. It is kept because what that header
// still holds (`rclcpp::Seq<T, N>`) is a public surface a consumer reaches
// through the node header, and `parameter.hpp` depends on `result.hpp` and
// `<nros/parameter.h>` only,
// so there is no cycle.
#include "rclcpp/parameter.hpp"
 
// `<chrono>` is the one capability whose predicate is not the uniform one —
// it needs `<ratio>` as a prerequisite too. The three measured corrections that
// established that live with the predicate, at the one detection site.
#include "rclcpp/detail/std_detect.hpp"
 
// phase-476 W3 — the hosted-node macro (`NROS_CPP_` + `NODE_HOSTED`) IS GONE. It was the
// conjunction of all four capability probes, wrapped around every hosted-shape member at once. Each
// member now names the ONE capability its signature actually uses: the `std::string`-keyed
// forwarders `NROS_CPP_HAS_STD_STRING`, the `std::shared_ptr` spellings `NROS_CPP_HAS_SHARED_PTR`,
// and nothing needs
// `<vector>` or `<functional>` any more. The rule it served is unchanged: a
// probe gates METHODS, never a member.
 
// `NROS_RCLCPP_MAX_PARAMS` IS GONE (phase-426 W4). It sized an inline
// `nros::ParameterServer` on the merged node's hosted block — a SECOND
// parameter store, node-local, which `ros2 param get` could not see and a
// sibling node did not share. The member is deleted and the facade forwards to
// the executor's store (`rclcpp/node_parameters.hpp`), so there is no per-node
// arena left for a number to bound.
//
// The image's one parameter arena is now `NROS_MAX_PARAMETERS` on
// `nros-params` (default 32, a build knob), and it is shared across every node
// on the executor rather than multiplied by the node count. Do not reintroduce
// a per-facade capacity: a second number is how a second store starts.
 
#ifdef NROS_RMW_CYCLONEDDS
extern "C" int32_t nros_rmw_cyclonedds_register(void);
#endif
#if defined(NROS_RMW_XRCE) || defined(NROS_RMW_XRCE_CFFI)
extern "C" int32_t nros_rmw_xrce_register(void);
#endif
#ifdef NROS_RMW_ZENOH_CFFI
extern "C" int32_t nros_rmw_zenoh_register(void);
#endif
#ifdef NROS_RMW_UORB
extern "C" int32_t nros_rmw_uorb_register(void);
#endif
 
// Issue #229 pin (cross-space, C++-FFI half): ErrorCode must stay
// value-identical to the NROS_CPP_RET_* codes (nros_cpp_ffi.h, included
// above) that every shim below feeds into Result().
static_assert(NROS_CPP_RET_NOT_FOUND == -4 && NROS_CPP_RET_ALREADY_EXISTS == -5 &&
                  NROS_CPP_RET_FULL == -6 && NROS_CPP_RET_NOT_INIT == -7 &&
                  NROS_CPP_RET_TRY_AGAIN == -14 && NROS_CPP_RET_REENTRANT == -15 &&
                  NROS_CPP_RET_UNSUPPORTED == -16,
              "nros_cpp_ret_t diverged from the shared numbering (issue #229)");
 
// Phase 84.G8: forward declarations of the heavy entity class
// templates. Full definitions live in the corresponding `*.hpp`,
// which also provide the out-of-line `Node::create_X<>` template
// bodies — consumers only pay for the entities they #include.
//
// phase-428 (RFC-0089): six of them are DECLARED in the upstream namespace,
// because that is where their definition now lives, and this header names them
// that way. (Each also had an `nros::` migration alias, declared beside its
// type in that type's own header, until phase-483 W1 deleted them.)
namespace rclcpp {
// phase-427 W7 — the node itself, defined further down in this header. Forward
// declared up here because the `rclcpp::` free functions BELOW take it by
// reference and are named by `Node`'s own qualified friend declarations, which
// require a prior declaration of the function AND of its parameter type.
class Node;
template <typename M> class Publisher;
template <typename M> class Subscription;
template <typename S> class Service;
template <typename S> class Client;
} // namespace rclcpp
 
namespace rclcpp_action {
template <typename A> class Server;
template <typename A> class Client;
} // namespace rclcpp_action
 
namespace rclcpp {
 
// Phase 122.3.d.b — L1 polling-mode action wrappers.
template <typename A> class PollingActionServer;
template <typename A> class PollingActionClient;
// phase-456 W2b — the two poll-side subscribers (`polling_subscription.hpp`).
template <typename M> class PollSubscription;
template <typename M> class PollingSubscription;
// phase-456 W5 — the poll-side service server (`polling_service.hpp`).
template <typename S> class PollService;
// phase-456 W9 — the poll-side (future-style) service client
// (`polling_client.hpp`), and the dispatch client's handle
// (`client_handle.hpp`).
template <typename S> class PollClient;
template <typename S> class ClientHandle;
 
struct NodeHandle {
    void* executor;
    const char* launch_name;
    const char* launch_namespace;
    const nros_cpp_qos_override_t* qos_overrides;
    size_t qos_override_count;
 
    constexpr NodeHandle()
        : executor(nullptr), launch_name(nullptr), launch_namespace(nullptr),
          qos_overrides(nullptr), qos_override_count(0) {}
    explicit constexpr NodeHandle(void* exec)
        : executor(exec), launch_name(nullptr), launch_namespace(nullptr), qos_overrides(nullptr),
          qos_override_count(0) {}
    constexpr NodeHandle(void* exec, const char* name, const char* ns)
        : executor(exec), launch_name(name), launch_namespace(ns), qos_overrides(nullptr),
          qos_override_count(0) {}
    constexpr NodeHandle(void* exec, const char* name, const char* ns,
                         const nros_cpp_qos_override_t* overrides, size_t override_count)
        : executor(exec), launch_name(name), launch_namespace(ns), qos_overrides(overrides),
          qos_override_count(override_count) {}
    constexpr bool valid() const { return executor != nullptr; }
 
    constexpr const char* resolve_name(const char* fallback) const {
        return (launch_name != nullptr && launch_name[0] != '\0') ? launch_name : fallback;
    }
    constexpr const char* resolve_namespace(const char* fallback) const {
        return (launch_namespace != nullptr && launch_namespace[0] != '\0') ? launch_namespace
                                                                            : fallback;
    }
};
 
// `constexpr` at namespace scope is implicitly const, so it already has internal
// linkage per TU — `inline` bought nothing and cost C++14 compatibility, which
// nano-ros otherwise keeps (see `just check cpp`'s freestanding c++14 syntax
// gate). PX4 builds every module with -std=gnu++14 -Werror, so an inline
// variable here made <rclcpp/rclcpp.hpp> uncompilable in a PX4 module (phase-325 W2).
constexpr uint8_t kDomainIdExplicitZero = 255;
 
namespace detail {
 
inline void report_component_failure(const char* node_name, const char* what, int32_t code) {
    // Route through the OVERRIDABLE sink first, so a freestanding image can
    // see this at all. Issue 1015's bisect ran aground here: on Zephyr both
    // arms below compile to nothing, so a component that failed to register
    // halted SILENTLY -- the board printed only the Zephyr banner, identical
    // to a healthy boot, and "is it broken?" had no answer on the target where
    // it mattered. Issue 0589 fixed exactly this class for the Rust side; the
    // C++ side still had it.
    NROS_ERROR("node \"%s\": FAILED at %s (code=%d)", (node_name != nullptr) ? node_name : "?",
               (what != nullptr) ? what : "?", static_cast<int>(code));
#if defined(NROS_CPP_STD) || (__STDC_HOSTED__ + 0) // hosted-family: hosted-console
    ::fprintf(stderr, "[nros] FATAL: node \"%s\" failed to construct at %s (code=%d)\n",
              (node_name != nullptr) ? node_name : "?", (what != nullptr) ? what : "?",
              static_cast<int>(code));
#endif
}
 
constexpr int32_t DECLARED_DEPTH_MISMATCH = -403;
 
inline void report_declared_depth_mismatch(const char* node_name, const char* topic, int declared,
                                           int passed) {
    NROS_ERROR("node \"%s\": topic \"%s\" DECLARED depth %d but the QoS "
               "passed states %d. Depth multiplies the executor arena, so they must agree.",
               (node_name != nullptr) ? node_name : "?", (topic != nullptr) ? topic : "?", declared,
               passed);
#if defined(NROS_CPP_STD) || (__STDC_HOSTED__ + 0) // hosted-family: hosted-console
    ::fprintf(stderr,
              "[nros] FATAL: node \"%s\": topic \"%s\" was DECLARED depth %d in "
              "the contract sidecar (<stem>.contract.yaml) but the QoS passed to "
              "create_subscription_in states depth %d. Depth multiplies the executor "
              "arena (cost is (depth+1)*bound per subscription), so the two must agree. "
              "Fix the contract row or the call site.\n",
              (node_name != nullptr) ? node_name : "?", (topic != nullptr) ? topic : "?", declared,
              passed);
#else
    (void)node_name;
    (void)topic;
    (void)declared;
    (void)passed;
#endif
}
 
inline void report_callback_group_mismatch(const char* node_name, const char* how, const char* name,
                                           int len, const char* list) {
    const char* node = (node_name != nullptr) ? node_name : "?";
    const char* group = (name != nullptr) ? name : "?";
    const char* declared = (list != nullptr) ? list : "";
    // "created": the code made a group the keyword never declared.
    // "declared": the keyword declared a group the constructor never made.
    const bool created = (how != nullptr && how[0] == 'c');
    if (created) {
        NROS_ERROR("node \"%s\": created callback group \"%.*s\", not in CALLBACK_GROUPS \"%s\"",
                   node, len, group, declared);
    } else {
        NROS_ERROR("node \"%s\": CALLBACK_GROUPS \"%s\" declares \"%.*s\", never created", node,
                   declared, len, group);
    }
#if defined(NROS_CPP_STD) || (__STDC_HOSTED__ + 0) // hosted-family: hosted-console
    ::fprintf(stderr,
              created ? "[nros] FATAL: node \"%s\" created callback group \"%.*s\", which its "
                        "registration's CALLBACK_GROUPS \"%s\" does not declare.\n"
                      : "[nros] FATAL: node \"%s\" never created callback group \"%.*s\", which "
                        "its registration's CALLBACK_GROUPS \"%s\" declares.\n",
              node, len, group, declared);
    ::fprintf(stderr,
              "      The tier derivation ranks the declared list and the executor binds what the "
              "code creates, so the two must name the same groups (ONE declared group and none "
              "created is node-level placement, and is allowed). Fix the "
              "nano_ros_node_register(... CALLBACK_GROUPS ...) line or the create_callback_group "
              "call.\n");
#endif
}
 
constexpr int32_t DECLARED_QOS_MISMATCH = DECLARED_DEPTH_MISMATCH;
 
inline void report_declared_policy_mismatch(const char* node_name, const char* topic,
                                            const char* policy, const char* declared,
                                            const char* passed) {
    NROS_ERROR("node \"%s\": topic \"%s\" DECLARED %s %s but the QoS passed states %s. An "
               "incompatible-QoS match never delivers, so they must agree.",
               (node_name != nullptr) ? node_name : "?", (topic != nullptr) ? topic : "?", policy,
               declared, passed);
#if defined(NROS_CPP_STD) || (__STDC_HOSTED__ + 0) // hosted-family: hosted-console
    ::fprintf(stderr,
              "[nros] FATAL: node \"%s\": topic \"%s\" was DECLARED %s %s in the contract "
              "sidecar (<stem>.contract.yaml) but the QoS passed to create_subscription_in "
              "states %s. Fix the contract row or the call site.\n",
              (node_name != nullptr) ? node_name : "?", (topic != nullptr) ? topic : "?", policy,
              declared, passed);
#else
    (void)node_name;
    (void)topic;
    (void)policy;
    (void)declared;
    (void)passed;
#endif
}
 
inline const char* declared_reliability_spelling(int ordinal) {
    return ordinal == static_cast<int>(::rclcpp::ReliabilityPolicy::Reliable) ? "reliable"
           : ordinal == static_cast<int>(::rclcpp::ReliabilityPolicy::BestEffort)
               ? "best_effort"
               : "system_default";
}
 
inline const char* declared_durability_spelling(int ordinal) {
    return ordinal == static_cast<int>(::rclcpp::DurabilityPolicy::Volatile) ? "volatile"
           : ordinal == static_cast<int>(::rclcpp::DurabilityPolicy::TransientLocal)
               ? "transient_local"
               : "system_default";
}
 
constexpr int32_t DECLARED_PARAM_MISMATCH = -446;
 
inline void report_declared_param_mismatch(const char* fqn, const char* param, const char* contract,
                                           int declared, int passed) {
    const char* f = (fqn != nullptr) ? fqn : "?";
    const char* p = (param != nullptr) ? param : "?";
    const char* c = (contract != nullptr) ? contract : "?";
    if (declared == ::rclcpp::DECLARED_PARAM_UNDECLARED) {
        NROS_ERROR("node \"%s\": parameter \"%s\" is not declared in its contract (%s).", f, p, c);
    } else {
        NROS_ERROR("node \"%s\": parameter \"%s\" is declared %s in its contract (%s) but the "
                   "code declares it as %s.",
                   f, p, ::rclcpp::declared_param_type_name(declared), c,
                   ::rclcpp::declared_param_type_name(passed));
    }
#if defined(NROS_CPP_STD) || (__STDC_HOSTED__ + 0) // hosted-family: hosted-console
    if (declared == ::rclcpp::DECLARED_PARAM_UNDECLARED) {
        ::fprintf(stderr,
                  "[nros] FATAL: node \"%s\": parameter \"%s\" is not declared in its "
                  "contract (%s, `params:`). The parameter store is sized from that "
                  "declaration, so a parameter it does not name has no slot. Declare it "
                  "there with its type, or stop declaring it in the code.\n",
                  f, p, c);
    } else {
        ::fprintf(stderr,
                  "[nros] FATAL: node \"%s\": parameter \"%s\" is declared `%s` in its "
                  "contract (%s) but the code declares it as `%s`. Fix the contract or "
                  "the code so they state one type.\n",
                  f, p, ::rclcpp::declared_param_type_name(declared), c,
                  ::rclcpp::declared_param_type_name(passed));
    }
#endif
}
 
// phase-476 W3 — `detail::NodeHosted` IS GONE. It was the lazily allocated
// block behind `Node::hosted_`, and by W3 it held one member:
// `rclcpp::NodeOptions`, a type with no data members (every accessor is a
// REFUSE-LOUD template, `options.hpp`). Allocating a heap block to store an
// empty object bought nothing, so `get_node_options()` answers a constant and
// the block, the member and the `operator new` go.
 
} // namespace detail
 
inline Result init_in(const char* locator = nullptr, uint8_t domain_id = 0);
 
inline Result init_in(const char* locator, uint8_t domain_id, const char* session_name);
 
inline Result init_in(const char* locator, uint8_t domain_id, const char* session_name,
                      const char* node_namespace);
 
inline Result init_with_rmw(const char* rmw, const char* locator = nullptr, uint8_t domain_id = 0,
                            const char* session_name = "node");
 
inline Result init_in(int argc, char const* const* argv, const char* session_name = nullptr);
 
inline Result shutdown_in();
 
// phase-427 W7 — the remaining `rclcpp::` free functions `Node` befriends. A
// QUALIFIED friend declaration (`friend Result(::rclcpp::ok)();`) names an
// existing entity; it cannot introduce one. These four live in `nros.hpp`,
// which includes this header, so without these declarations the friendship
// would be unresolvable and the private `executor_handle_` unreachable from the
// functions whose whole job is to set it. Default arguments stay on the
// definitions — a default may be added by a later declaration, never repeated.
inline bool ok();
inline Result create_node(::rclcpp::Node& out, const char* name, const char* ns);
inline Result create_node_on(::rclcpp::Node& out, void* executor_handle, const char* name,
                             const char* ns);
inline Result spin_once(int32_t timeout_ms);
inline Result spin_in();
inline Result spin_in(uint32_t duration_ms, int32_t poll_ms);
inline void* global_handle();
 
} // namespace rclcpp
 
// ============================================================================
// rclcpp:: — the HOME of the C++ node type (RFC-0089 §"Settled: `rclcpp::` is
// the HOME, not an alias onto `nros::`"). phase-427 W7 flipped the direction:
// the class was DEFINED here and `nros::Node` became the migration alias, the
// same shape the other nine types already carried (`clock.hpp`, `duration.hpp`,
// `time.hpp`, `publisher.hpp`, `subscription.hpp`, `client.hpp`, `service.hpp`,
// `action_client.hpp`, `action_server.hpp`). phase-483 W1 deleted the aliases;
// `rclcpp::` is now the only namespace.
//
// `Node` was the TENTH and was held back because PRs #797 and #806 were stacked
// on this header. Both merged. The measurement that blocked it before — the
// parity extractor rooting our native surface at `{"nros"}` alone, so a class
// defined here re-bucketed ~60 members to `theirs-only` — is gone too:
// `scripts/api-parity.py` roots every C++ TU at `OUR_CPP_ROOTS`, both halves of
// the vocabulary we ship.
//
// The ours-only names the body below reaches (`ErrorCode`, `detail::*`,
// `NodeHandle`, `SchedContext`, the polling entity templates) are spelled
// `::rclcpp::`-qualified. Until phase-483 W1 that qualifier was `::nros::` and
// told an adopted name from an ours-only one; the namespace no longer carries
// that distinction.
// ============================================================================
namespace rclcpp {
class Node {
  public:
    Node() : handle_(), initialized_(false), executor_handle_(nullptr), clock_(RCL_ROS_TIME) {}
 
    // ==== phase-427 W2 — construction ======================================
    //
    // Upstream constructs a node from a name and THROWS on failure. RFC-0018
    // forbids exceptions here, so the constructor is kept [clause 2] and the
    // failure channel changes [clause 1]: the node records the failure and
    // `ok()` reports it.
 
    explicit Node(const char* name, const char* ns = nullptr)
        : handle_(), initialized_(false), executor_handle_(nullptr), clock_(RCL_ROS_TIME) {
        (void)this->init(name, ns);
    }
 
    Result init(const char* name, const char* ns = nullptr) {
        if (initialized_) return Result(::rclcpp::ErrorCode::AlreadyExists);
        if (!Node::global_initialized()) return Result(::rclcpp::ErrorCode::NotInitialized);
        executor_handle_ = Node::global_storage();
        return Node::create(*this, name, ns);
    }
 
    Result init_on(void* executor_handle, const char* name, const char* ns = nullptr) {
        if (initialized_) return Result(::rclcpp::ErrorCode::AlreadyExists);
        if (executor_handle == nullptr) return Result(::rclcpp::ErrorCode::NotInitialized);
        executor_handle_ = executor_handle;
        return Node::create(*this, name, ns);
    }
 
    explicit Node(::rclcpp::NodeHandle handle, const char* name, const char* ns = nullptr)
        : handle_(), initialized_(false), executor_handle_(nullptr), clock_(RCL_ROS_TIME) {
        if (!handle.valid()) {
            this->set_error("ctor (null executor handle)", -1);
            return;
        }
        Result r =
            this->init_on(handle.executor, handle.resolve_name(name), handle.resolve_namespace(ns));
        if (!r.ok()) {
            this->set_error("node create", r.raw());
            return;
        }
        // Issue 1854 -- the launch's QoS overrides, installed before the
        // derived constructor body creates a single entity (a base is fully
        // constructed before the derived body runs), which is the ordering
        // the `configure` shape gets from the entry's own call.
        if (handle.qos_overrides != nullptr && handle.qos_override_count != 0) {
            nros_cpp_ret_t qrc = ::nros_cpp_node_set_qos_overrides(&handle_, handle.qos_overrides,
                                                                   handle.qos_override_count);
            if (qrc != NROS_CPP_RET_OK) {
                this->set_error("set_qos_overrides", static_cast<int32_t>(qrc));
            }
        }
    }
 
    bool ok() const { return initialized_ && !__atomic_load_n(&has_error_, __ATOMIC_ACQUIRE); }
 
    const char* error_what() const {
        // Acquire-fence on the flag so a standalone call (not preceded by
        // ok()) still sees the released `error_what_` write (issue #230).
        (void)__atomic_load_n(&has_error_, __ATOMIC_ACQUIRE);
        return error_what_;
    }
    int32_t error_code() const {
        (void)__atomic_load_n(&has_error_, __ATOMIC_ACQUIRE);
        return error_code_;
    }
 
    // ==== phase-427 W1/W3 — the HOSTED shape ================================
    //
    // Upstream's own signatures, verbatim, on the same type. Everything below
    // is spelled in `std::shared_ptr` / `std::string` / `std::vector` /
    // `std::function`, so where those are absent the SIGNATURES are absent with
    // them — a gate on METHODS, never on a member.
    //
    // ONE NAME, TWO SIGNATURES (RFC-0089 §"Entity creation"). The out-ref
    // family above and the `shared_ptr` family below are OVERLOADS, and the
    // compiler separates them without ambiguity because the hosted forms put
    // `M` only in the return type — so a call that passes an out-param deduces
    // nothing for them and they drop out, while an explicit
    // `create_publisher<M>("chatter", 10)` cannot bind an out-ref parameter to
    // a string literal. On a FREESTANDING target the hosted overload does not
    // exist at all, so that same ported line fails to compile naming the
    // out-ref overload — mechanical, which is what clause 2 asks for.
    //
    // phase-476 W3 — each member below is gated on the ONE capability its
    // signature uses, not on a conjunction of all four.
 
    Node(const char* name, const ::rclcpp::NodeOptions& options) : Node(name, nullptr) {
        (void)options;
    }
 
    Node(const char* name, const char* ns, const ::rclcpp::NodeOptions& options) : Node(name, ns) {
        (void)options;
    }
 
    const ::rclcpp::NodeOptions& get_node_options() const {
        static constexpr ::rclcpp::NodeOptions kOptions{};
        return kOptions;
    }
 
#ifdef NROS_CPP_HAS_STD_STRING // hosted-family: string-interop
    explicit Node(const ::std::string& name) : Node(name.c_str(), nullptr) {}
 
    Node(const ::std::string& name, const ::rclcpp::NodeOptions& options)
        : Node(name.c_str(), options) {}
 
    Node(const ::std::string& name, const ::std::string& ns,
         const ::rclcpp::NodeOptions& options = ::rclcpp::NodeOptions())
        : Node(name.c_str(), ns.c_str(), options) {}
#endif // NROS_CPP_HAS_STD_STRING
 
    using SharedPtr = ::rclcpp::Handle<Node>;
    using ConstSharedPtr = ::rclcpp::Handle<const Node>;
 
    SharedPtr shared_from_this() { return SharedPtr(this); }
    ConstSharedPtr shared_from_this() const { return ConstSharedPtr(this); }
 
    bool initialized() const { return initialized_; }
 
    Node& nros_node() { return *this; }
    const Node& nros_node() const { return *this; }
 
#ifdef NROS_CPP_HAS_STD_STRING // hosted-family: string-interop
    // -- entity creation, upstream's signatures (bodies in `nros.hpp`) -------
 
    template <typename M>
    typename ::rclcpp::Publisher<M>::SharedPtr create_publisher(const ::std::string& topic,
                                                                const ::rclcpp::QoS& qos);
 
    template <typename M>
    typename ::rclcpp::Publisher<M>::SharedPtr create_publisher(const ::std::string& topic,
                                                                ::size_t depth);
 
    template <typename M, typename Cb>
    typename ::rclcpp::Subscription<M>::SharedPtr
    create_subscription(const ::std::string& topic, const ::rclcpp::QoS& qos, Cb cb);
 
    template <typename M, typename Cb>
    typename ::rclcpp::Subscription<M>::SharedPtr create_subscription(const ::std::string& topic,
                                                                      ::size_t depth, Cb cb);
 
    template <typename S>
    ::rclcpp::Owned<::rclcpp::PollService<S>>
    create_service(const ::std::string& name, const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename S, typename F,
              typename = typename std::enable_if<std::is_convertible<
                  F, void (*)(const typename S::Request&, typename S::Response&)>::value>::type>
    typename ::rclcpp::Service<S>::SharedPtr
    create_service(const ::std::string& name, F callback,
                   const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename S, typename F,
              typename = typename std::enable_if<
                  !::rclcpp::detail::is_qos_arg<F>::value &&
                  !std::is_convertible<F, void (*)(const typename S::Request&,
                                                   typename S::Response&)>::value>::type,
              typename = void>
    typename ::rclcpp::Service<S>::SharedPtr
    create_service(const ::std::string&, F, const ::rclcpp::QoS& = ::rclcpp::QoS::services());
 
    template <typename S>
    ::rclcpp::Owned<::rclcpp::PollClient<S>>
    create_client(const ::std::string& name, const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename S, typename F,
              typename = typename std::enable_if<
                  std::is_convertible<F, void (*)(const typename S::Response&)>::value>::type>
    typename ::rclcpp::Client<S>::SharedPtr
    create_client(const ::std::string& name, F callback,
                  const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename S, typename F,
              typename = typename std::enable_if<
                  !::rclcpp::detail::is_qos_arg<F>::value &&
                  !std::is_convertible<F, void (*)(const typename S::Response&)>::value>::type,
              typename = void>
    typename ::rclcpp::Client<S>::SharedPtr
    create_client(const ::std::string&, F, const ::rclcpp::QoS& = ::rclcpp::QoS::services());
 
#endif // NROS_CPP_HAS_STD_STRING
 
    // -- the ported publisher line, on EVERY target — phase-456 W5 ----------
    //
    // OUTSIDE the hosted gate (phase-476 W3 deleted it), and that is the point
    // rather than a placement detail. `create_publisher<M>("chatter", 10)` is the single most
    // copied line in the porting corpus, and until W5 it was gated: the return
    // type was `std::shared_ptr<Publisher<M>>`, so on a minimal freestanding
    // libcpp the overload did not exist and the line did not compile.
    // `ported_create_publisher_freestanding_probe.cpp` asserted exactly that,
    // and the lane's own error text named the reason — "the hosted overload
    // returns std::shared_ptr and there is no allocator here".
    //
    // The return type is `Publisher<M>::SharedPtr` = `rclcpp::Owned<Publisher<M>>`
    // now, which needs no allocator and exists everywhere, so the reason is
    // gone and the gate goes with it. RFC-0096 D1: ONE API, byte-for-byte the
    // same shape on every target, reached by removing what made it differ.
    //
    // The `const char*` key is what makes it freestanding — a `std::string`
    // parameter would have re-imposed the gate through the argument instead of
    // the return. A string literal binds here exactly (array-to-pointer), so a
    // ported call reaches this overload on a hosted target too; the
    // `std::string` forwarders above stay for a caller that already holds one.
 
    template <typename M>
    typename ::rclcpp::Publisher<M>::SharedPtr
    create_publisher(const char* topic,
                     const ::rclcpp::QoS& qos = ::rclcpp::QoS::default_profile());
 
    template <typename M>
    typename ::rclcpp::Publisher<M>::SharedPtr create_publisher(const char* topic, ::size_t depth);
 
    // phase-476 W1 — the DISPATCH verbs join it, for the same reason. Their
    // results have been freestanding handles since phase-456 (the arena holds
    // the subscription, the server, the client and the callable), so the
    // `std::string` key was the only thing still keeping them hosted. The
    // `std::string` overloads in the hosted block forward here.
 
    template <typename M, typename Cb>
    typename ::rclcpp::Subscription<M>::SharedPtr
    create_subscription(const char* topic, const ::rclcpp::QoS& qos, Cb cb);
 
    template <typename M, typename Cb>
    typename ::rclcpp::Subscription<M>::SharedPtr create_subscription(const char* topic,
                                                                      ::size_t depth, Cb cb);
 
    template <typename S>
    ::rclcpp::Owned<::rclcpp::PollService<S>>
    create_service(const char* name, const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename S, typename F,
              typename = typename ::rclcpp::tr::enable_if<::rclcpp::tr::is_convertible<
                  F, void (*)(const typename S::Request&, typename S::Response&)>::value>::type>
    typename ::rclcpp::Service<S>::SharedPtr
    create_service(const char* name, F callback,
                   const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename S, typename F,
              typename = typename ::rclcpp::tr::enable_if<
                  !::rclcpp::detail::is_qos_arg<F>::value &&
                  !::rclcpp::tr::is_convertible<F, void (*)(const typename S::Request&,
                                                            typename S::Response&)>::value>::type,
              typename = void>
    typename ::rclcpp::Service<S>::SharedPtr
    create_service(const char*, F, const ::rclcpp::QoS& = ::rclcpp::QoS::services());
 
    template <typename S>
    ::rclcpp::Owned<::rclcpp::PollClient<S>>
    create_client(const char* name, const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename S, typename F,
              typename = typename ::rclcpp::tr::enable_if<::rclcpp::tr::is_convertible<
                  F, void (*)(const typename S::Response&)>::value>::type>
    typename ::rclcpp::Client<S>::SharedPtr
    create_client(const char* name, F callback,
                  const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <
        typename S, typename F,
        typename = typename ::rclcpp::tr::enable_if<
            !::rclcpp::detail::is_qos_arg<F>::value &&
            !::rclcpp::tr::is_convertible<F, void (*)(const typename S::Response&)>::value>::type,
        typename = void>
    typename ::rclcpp::Client<S>::SharedPtr
    create_client(const char*, F, const ::rclcpp::QoS& = ::rclcpp::QoS::services());
 
    // -- parameters (bodies in `nros.hpp`) ----------------------------------
    //
    // Forwarders onto THE parameter store - the `nros_params::ParameterServer`
    // the EXECUTOR owns, reached across the FFI by `rclcpp/node_parameters.hpp`.
    // Declared here with the class and DEFINED in `nros.hpp` beside the other
    // out-of-line members, which is where the reasoning lives.
    //
    // Until phase-426 W4 these read an inline `ParameterServer` member on the
    // hosted block instead: a second store, node-local, that the six
    // `rcl_interfaces/srv/*` servers could not read - so a parameter declared
    // through this facade was invisible to `ros2 param get` and a sibling node
    // did not share it.
    //
    // OUTSIDE the hosted gate (phase-476 W3 deleted it), and that is the rest of
    // W4 rather than a tidy-up. The member leaving was "the last thing that made
    // the hosted gate decide whether a node HAS parameters rather than
    // whether it can spell them" - but the declarations stayed inside the gate,
    // so a freestanding node still had no parameter method, and
    // `nros::ParameterServer<Cap>` (deleted with this wave) was the only C++
    // parameter surface it had. Deleting that class while the gate stood would
    // have removed the capability from freestanding C++ instead of moving it,
    // which is what W4's ordering rule exists to prevent. The scalar FFI is
    // `<cstdint>` and a `const char*`; nothing about it needs the STL, and
    // `rclcpp::Seq<T, N>` gives the array form the same reach. Only the
    // `std::string`-KEYED overloads below need it, and they keep the gate - a
    // gate on METHODS, never on a member, which is what
    // `check-cpp-capability-layout` asks.
 
    template <typename T> T declare_parameter(const char* name, T default_value = T());
    template <typename T> bool get_parameter(const char* name, T& out) const;
    template <typename T> T get_parameter(const char* name) const;
    template <typename T> Result set_parameter(const char* name, T value);
    bool has_parameter(const char* name) const;
 
    // ---- phase-417 W4.a: the rest of rclcpp's parameter surface ------------
    //
    // All of it forwards to the executor's ONE store through
    // `rclcpp/node_parameters.hpp`. OUTSIDE any capability gate for the same
    // reason the four above are: the FFI is `<cstdint>` and `const char*`, so
    // a freestanding node can spell every one of them, and a gate here would
    // decide whether a node HAS parameters rather than whether it can name
    // them.
 
    template <typename T>
    T declare_parameter(const char* name, T default_value, const ParameterDescriptor& descriptor);
 
    template <typename T> bool get_parameter_or(const char* name, T& out, T fallback) const;
 
    Result undeclare_parameter(const char* name);
 
    ParameterType get_parameter_type(const char* name) const;
 
    Result get_parameter_types(const char* const* names, ::size_t count, ParameterType* out) const;
 
    Result describe_parameter(const char* name, ParameterDescriptor& out, char* text,
                              ::size_t text_len) const;
 
    Result list_parameters(const char* prefix, char* out_names, ::size_t name_stride,
                           ::size_t max_names, ::size_t& count) const;
 
    Result set_parameters_atomically(const ParameterWrite* writes, ::size_t count);
 
    Result add_on_set_parameters_callback(OnSetParametersCallbackType callback, void* context,
                                          ParameterCallbackHandle& out_handle);
 
    Result remove_on_set_parameters_callback(ParameterCallbackHandle handle);
 
#ifdef NROS_CPP_HAS_STD_STRING // hosted-family: string-interop
    template <typename T> T declare_parameter(const ::std::string& name, T default_value = T()) {
        return this->template declare_parameter<T>(name.c_str(), default_value);
    }
    template <typename T> bool get_parameter(const ::std::string& name, T& out) const {
        return this->template get_parameter<T>(name.c_str(), out);
    }
    template <typename T> T get_parameter(const ::std::string& name) const {
        return this->template get_parameter<T>(name.c_str());
    }
    template <typename T> Result set_parameter(const ::std::string& name, T value) {
        return this->template set_parameter<T>(name.c_str(), value);
    }
    bool has_parameter(const ::std::string& name) const {
        return this->has_parameter(name.c_str());
    }
    Result undeclare_parameter(const ::std::string& name) {
        return this->undeclare_parameter(name.c_str());
    }
    template <typename T>
    T declare_parameter(const ::std::string& name, T default_value,
                        const ParameterDescriptor& descriptor) {
        return this->template declare_parameter<T>(name.c_str(), default_value, descriptor);
    }
    template <typename T>
    bool get_parameter_or(const ::std::string& name, T& out, T fallback) const {
        return this->template get_parameter_or<T>(name.c_str(), out, fallback);
    }
    ParameterType get_parameter_type(const ::std::string& name) const {
        return this->get_parameter_type(name.c_str());
    }
 
    template <typename T>
    Result declare_parameters(const ::std::string& prefix, const ::std::map<::std::string, T>& m) {
        for (typename ::std::map<::std::string, T>::const_iterator it = m.begin(); it != m.end();
             ++it) {
            const ::std::string full = prefix.empty() ? it->first : (prefix + "." + it->first);
            const ::nros_cpp_node_t* h = this->ffi_handle();
            Result r = ::rclcpp::detail::node_param_declare(h, full.c_str(), it->second);
            if (!r.ok() && r.raw() != RCLC_RET_ALREADY_EXISTS) {
                return r;
            }
        }
        return Result(RCL_RET_OK);
    }
#endif // NROS_CPP_HAS_STD_STRING
 
    static Result create(Node& out, const char* name, const char* ns = nullptr) {
        if (!out.executor_handle_) {
            return Result(::rclcpp::ErrorCode::NotInitialized);
        }
 
        nros_cpp_ret_t ret = nros_cpp_node_create(out.executor_handle_, name, ns, &out.handle_);
 
        if (ret == 0) {
            out.initialized_ = true;
        }
        return Result(ret);
    }
 
    const char* get_name() const {
        if (!initialized_) return "";
        return nros_cpp_node_get_name(&handle_);
    }
 
    const char* get_namespace() const {
        if (!initialized_) return "";
        return nros_cpp_node_get_namespace(&handle_);
    }
 
    Result get_fully_qualified_name(char* buf, size_t buf_len, size_t* out_len = nullptr) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_node_get_fully_qualified_name(&handle_, buf, buf_len, out_len));
    }
 
    const char* serialization_format() const {
        if (!initialized_) return nullptr;
        return nros_cpp_node_get_serialization_format(&handle_);
    }
 
    ::rclcpp::Logger get_logger() const {
        if (!initialized_) return ::rclcpp::Logger("", nullptr);
        return ::rclcpp::Logger(nros_cpp_node_get_name(&handle_),
                                nros_cpp_node_get_logger(&handle_));
    }
 
    Clock* get_clock() { return &clock_; }
    const Clock* get_clock() const { return &clock_; }
 
    Time now() const { return clock_.now(); }
 
    bool is_valid() const { return initialized_; }
 
    const nros_cpp_node_t* ffi_handle() const { return initialized_ ? &handle_ : nullptr; }
 
    void set_qos_overrides(const nros_cpp_qos_override_t* overrides, size_t len) {
        if (initialized_) {
            ::nros_cpp_node_set_qos_overrides(&handle_, overrides, len);
        }
    }
 
    void* executor_handle() const { return initialized_ ? executor_handle_ : nullptr; }
 
    Result start_parameter_services() {
        return Result(nros_cpp_register_parameter_services(executor_handle()));
    }
 
    // ---- Graph queries — phase-417 stage 2b (RFC-0089) --------------------
    //
    // rclcpp puts these on the node. `rclcpp::Executor` owns them here because
    // one session per image makes the executor the graph's receiver
    // (RFC-0002), so each method below FORWARDS to the executor this node was
    // opened against and nothing else: no state, no loop, no caching, no name
    // construction. RFC-0019 — the behaviour is Rust's and stays there.
    //
    // The envelope every one of them shares (ADOPT-BOUNDED, RFC-0089): they
    // report what has been DISCOVERED and never block, so an empty result
    // means "nobody seen yet" and never "nobody exists" — poll rather than
    // calling once and concluding. `ErrorCode::Unsupported`, which is what a
    // backend with no graph at all returns, is a DIFFERENT answer from an
    // empty one and must not be collapsed into zero.
 
    Result get_node_names(nros_cpp_node_visit_fn visit, void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_node_names(executor_handle_, visit, ctx));
    }
 
    Result get_topic_names_and_types(nros_cpp_names_and_types_visit_fn visit, void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_topic_names_and_types(executor_handle_, visit, ctx));
    }
 
    Result get_service_names_and_types(nros_cpp_names_and_types_visit_fn visit, void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_service_names_and_types(executor_handle_, visit, ctx));
    }
 
    Result count_publishers(const char* topic_name, size_t* out_count) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_count_publishers(executor_handle_, topic_name, out_count));
    }
 
    Result count_subscribers(const char* topic_name, size_t* out_count) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_count_subscribers(executor_handle_, topic_name, out_count));
    }
 
    Result get_publisher_names_and_types_by_node(const char* node_name, const char* node_namespace,
                                                 nros_cpp_names_and_types_visit_fn visit,
                                                 void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_publisher_names_and_types_by_node(
            executor_handle_, node_name, node_namespace, visit, ctx));
    }
 
    Result get_subscription_names_and_types_by_node(const char* node_name,
                                                    const char* node_namespace,
                                                    nros_cpp_names_and_types_visit_fn visit,
                                                    void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_subscription_names_and_types_by_node(
            executor_handle_, node_name, node_namespace, visit, ctx));
    }
 
    Result get_service_names_and_types_by_node(const char* node_name, const char* node_namespace,
                                               nros_cpp_names_and_types_visit_fn visit,
                                               void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_service_names_and_types_by_node(
            executor_handle_, node_name, node_namespace, visit, ctx));
    }
 
    Result get_client_names_and_types_by_node(const char* node_name, const char* node_namespace,
                                              nros_cpp_names_and_types_visit_fn visit,
                                              void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_client_names_and_types_by_node(
            executor_handle_, node_name, node_namespace, visit, ctx));
    }
 
    Result get_publishers_info_by_topic(const char* topic_name,
                                        nros_cpp_endpoint_info_visit_fn visit, void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_publishers_info_by_topic(executor_handle_, topic_name,
                                                                     visit, ctx));
    }
 
    Result get_publishers_info_by_topic(const char* topic_name,
                                        ::rclcpp::TopicEndpointInfoVisitFn visit, void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        ::rclcpp::detail::EndpointInfoTrampoline tramp{visit, ctx};
        return Result(nros_cpp_executor_get_publishers_info_by_topic(
            executor_handle_, topic_name, &::rclcpp::detail::EndpointInfoTrampoline::thunk,
            &tramp));
    }
 
    Result get_subscriptions_info_by_topic(const char* topic_name,
                                           nros_cpp_endpoint_info_visit_fn visit, void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_subscriptions_info_by_topic(executor_handle_,
                                                                        topic_name, visit, ctx));
    }
 
    Result get_subscriptions_info_by_topic(const char* topic_name,
                                           ::rclcpp::TopicEndpointInfoVisitFn visit,
                                           void* ctx) const {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        ::rclcpp::detail::EndpointInfoTrampoline tramp{visit, ctx};
        return Result(nros_cpp_executor_get_subscriptions_info_by_topic(
            executor_handle_, topic_name, &::rclcpp::detail::EndpointInfoTrampoline::thunk,
            &tramp));
    }
 
    template <typename M>
    Result create_publisher(::rclcpp::Publisher<M>& out, const char* topic,
                            const ::rclcpp::QoS& qos = ::rclcpp::QoS::default_profile());
 
    template <typename M>
    Result create_publisher(::rclcpp::Publisher<M>& out, const char* topic,
                            const ::rclcpp::QoS& qos, const ::rclcpp::PublisherOptions& options);
 
    template <typename M>
    Result create_subscription(::rclcpp::PollSubscription<M>& out, const char* topic,
                               const ::rclcpp::QoS& qos = ::rclcpp::QoS::default_profile());
 
    template <typename M>
    Result create_subscription(::rclcpp::PollSubscription<M>& out, const char* topic,
                               const ::rclcpp::QoS& qos,
                               const ::rclcpp::SubscriptionOptions& options);
 
    template <
        typename M, typename F,
        typename = typename std::enable_if<std::is_convertible<F, void (*)(const M&)>::value>::type>
    Result create_subscription(::rclcpp::Subscription<M>& out, const char* topic,
                               const ::rclcpp::QoS& qos, F callback,
                               const ::rclcpp::SubscriptionOptions& options = {});
 
    template <typename M, typename F,
              typename = typename std::enable_if<
                  std::is_convertible<F, void (*)(const M&, const uint8_t*, size_t)>::value>::type>
    Result create_subscription_with_info(::rclcpp::Subscription<M>& out, const char* topic,
                                         const ::rclcpp::QoS& qos, F callback,
                                         const ::rclcpp::SubscriptionOptions& options = {});
 
#if defined(NROS_SAFETY_E2E)
    template <typename M, typename F,
              typename = typename std::enable_if<std::is_convertible<
                  F, void (*)(const M&, const ::nros_cpp_integrity_status_t&)>::value>::type>
    Result create_subscription_with_safety(::rclcpp::Subscription<M>& out, const char* topic,
                                           const ::rclcpp::QoS& qos, F callback,
                                           const ::rclcpp::SubscriptionOptions& options = {});
#endif // NROS_SAFETY_E2E
 
    template <typename S>
    Result create_service(::rclcpp::PollService<S>& out, const char* service_name,
                          const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename S, typename F,
              typename = typename std::enable_if<std::is_convertible<
                  F, void (*)(const typename S::Request&, typename S::Response&)>::value>::type>
    Result create_service(::rclcpp::Service<S>& out, const char* service_name, F callback,
                          const ::rclcpp::QoS& qos = ::rclcpp::QoS::services(),
                          const ::rclcpp::ServiceOptions& options = {});
 
    template <typename S>
    Result create_client(::rclcpp::PollClient<S>& out, const char* service_name,
                         const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename S, typename F,
              typename = typename std::enable_if<
                  std::is_convertible<F, void (*)(const typename S::Response&)>::value>::type>
    Result create_client(::rclcpp::Client<S>& out, const char* service_name, F callback,
                         const ::rclcpp::QoS& qos = ::rclcpp::QoS::services(),
                         const ::rclcpp::ClientOptions& options = {});
 
    template <typename A>
    Result create_action_server(::rclcpp_action::Server<A>& out, const char* action_name,
                                const ::rclcpp::QoS& qos = ::rclcpp::QoS::services(),
                                const ::rclcpp::ActionServerOptions& options = {});
 
    template <typename A>
    Result create_action_client(::rclcpp_action::Client<A>& out, const char* action_name,
                                const ::rclcpp::QoS& qos = ::rclcpp::QoS::services());
 
    template <typename A>
    Result create_polling_action_server(::rclcpp::PollingActionServer<A>& out,
                                        const char* action_name);
 
    template <typename A>
    Result create_polling_action_client(::rclcpp::PollingActionClient<A>& out,
                                        const char* action_name);
 
    template <typename M>
    Result create_polling_subscription(::rclcpp::PollingSubscription<M>& out, const char* topic,
                                       const ::rclcpp::QoS& qos = ::rclcpp::QoS::default_profile());
 
    Result create_timer(Timer& out, const Clock& clock, uint64_t period_ms,
                        nros_cpp_timer_callback_t callback, void* context = nullptr) {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        size_t handle_id = 0;
        nros_cpp_ret_t ret = nros_cpp_timer_create_on_clock(
            executor_handle_, static_cast<uint8_t>(clock.get_clock_type()), period_ms, callback,
            context, &handle_id);
        if (ret == 0) {
            out.executor_ = executor_handle_;
            out.handle_id_ = handle_id;
            out.initialized_ = true;
        }
        return Result(ret);
    }
 
    template <typename Cb>::rclcpp::TimerHandle create_wall_timer(::rclcpp::Duration period, Cb cb);
 
#ifdef NROS_CPP_HAS_STD_CHRONO // hosted-family: chrono-interop
    template <typename Rep, typename Period, typename Cb>
    ::rclcpp::TimerHandle create_wall_timer(::std::chrono::duration<Rep, Period> period, Cb cb);
#endif
 
    Result create_wall_timer(Timer& out, uint64_t period_ms, nros_cpp_timer_callback_t callback,
                             void* context = nullptr) {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        size_t handle_id = 0;
        nros_cpp_ret_t ret =
            nros_cpp_timer_create(executor_handle_, period_ms, callback, context, &handle_id);
        if (ret == 0) {
            out.executor_ = executor_handle_;
            out.handle_id_ = handle_id;
            out.initialized_ = true;
        }
        return Result(ret);
    }
 
    // ==== phase-427 W3 — member-function binding, on the upstream name ======
    //
    // `nros::bind_timer<C, &C::m>(node, out, ms, self)` was a FREE function
    // with an invented name doing what `create_wall_timer` does. Folding it in
    // removes an invention by reusing an upstream name, which is what clause 2
    // asks for — and it is the shape a component actually writes, so the verb a
    // reader meets first is the one they need.
    //
    // NO ALLOCATION and NO `std::function`: the member pointer is a TEMPLATE
    // PARAMETER, so the trampoline is a capture-less lambda that converts to
    // the executor's raw `void(*)(void*)` and `self` is the context. That is
    // why this overload, unlike the `std::chrono` one, reaches every target.
 
    template <class C, void (C::*Method)()>
    Result create_wall_timer(Timer& out, uint64_t period_ms, C* self) {
        return this->create_wall_timer(
            out, period_ms, [](void* ctx) { (static_cast<C*>(ctx)->*Method)(); }, self);
    }
 
    template <class C, void (C::*Method)()>
    Result create_timer(Timer& out, const Clock& clock, uint64_t period_ms, C* self) {
        return this->create_timer(
            out, clock, period_ms, [](void* ctx) { (static_cast<C*>(ctx)->*Method)(); }, self);
    }
 
    template <class C, void (C::*Method)()>
    Result create_timer_in_group(const ::rclcpp::CallbackGroup& group, Timer& out,
                                 uint64_t period_ms, C* self) {
        return this->create_timer_in_group(
            group, out, period_ms, [](void* ctx) { (static_cast<C*>(ctx)->*Method)(); }, self);
    }
 
    Result create_timer_oneshot(Timer& out, uint64_t delay_ms, nros_cpp_timer_callback_t callback,
                                void* context = nullptr) {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        size_t handle_id = 0;
        nros_cpp_ret_t ret = nros_cpp_timer_create_oneshot(executor_handle_, delay_ms, callback,
                                                           context, &handle_id);
        if (ret == 0) {
            out.executor_ = executor_handle_;
            out.handle_id_ = handle_id;
            out.initialized_ = true;
        }
        return Result(ret);
    }
 
    // -- Phase 273 (RFC-0047) — Callback-group API -------------------------
 
    ::rclcpp::CallbackGroup create_callback_group(const char* name) {
        if (!::rclcpp::detail::admit_callback_group(name)) {
            const ::rclcpp::detail::DeclaredCallbackGroups* g =
                ::rclcpp::detail::declared_callback_groups_scope();
            const char* list = (g != nullptr) ? g->list : nullptr;
            int len = 0;
            while (name[len] != '\0')
                ++len;
            ::rclcpp::detail::report_callback_group_mismatch(this->get_name(), "created", name, len,
                                                             list);
            this->set_error("create_callback_group: the group is not in this registration's "
                            "CALLBACK_GROUPS",
                            ::rclcpp::detail::DECLARED_CALLBACK_GROUP_MISMATCH);
        }
        return ::rclcpp::CallbackGroup{name};
    }
 
    Result create_timer_in_group(const ::rclcpp::CallbackGroup& group, Timer& out,
                                 uint64_t period_ms, nros_cpp_timer_callback_t callback,
                                 void* context = nullptr) {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        size_t handle_id = 0;
        nros_cpp_ret_t ret = nros_cpp_timer_create_in_group(
            executor_handle_, &handle_, period_ms, callback, context, group.get_name(), &handle_id);
        if (ret == 0) {
            out.executor_ = executor_handle_;
            out.handle_id_ = handle_id;
            out.initialized_ = true;
        }
        return Result(ret);
    }
 
    template <
        typename M, typename F,
        typename = typename std::enable_if<std::is_convertible<F, void (*)(const M&)>::value>::type>
    Result create_subscription_in_group(const ::rclcpp::CallbackGroup& group,
                                        ::rclcpp::Subscription<M>& out, const char* topic,
                                        const ::rclcpp::QoS& qos, F callback,
                                        const ::rclcpp::SubscriptionOptions& options = {});
 
    template <typename M>
    Result create_publisher_in_group(const ::rclcpp::CallbackGroup& /* group */,
                                     ::rclcpp::Publisher<M>& out, const char* topic,
                                     const ::rclcpp::QoS& qos = ::rclcpp::QoS::default_profile()) {
        return create_publisher<M>(out, topic, qos);
    }
 
    Result create_guard_condition(::rclcpp::GuardCondition& out, nros_cpp_guard_callback_t callback,
                                  void* context = nullptr) {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        size_t handle_id = 0;
        nros_cpp_ret_t ret = nros_cpp_guard_condition_create(executor_handle_, callback, context,
                                                             out.storage_, &handle_id);
        if (ret == 0) {
            out.initialized_ = true;
            out.executor_ = executor_handle_;
            out.handle_id_ = handle_id;
        }
        return Result(ret);
    }
 
    // ==== phase-427 W4 — the ours-only family, under `_in` names =============
    //
    // These came off `nros::ComponentNode`. Every one of them is spelled with
    // an `_in` SUFFIX rather than upstream's bare verb, and the rename is the
    // whole point of the item.
    //
    // `ComponentNode::create_publisher<M>(const char*, const QoS&)` returned by
    // value and reported failure through the `ok()` latch; upstream's
    // `create_publisher<M>(const std::string&, …)` returns a `shared_ptr` and
    // throws. As OVERLOADS on one type those differ only in SIGNATURE, and C++
    // resolves a signature-only difference SILENTLY. Measured on the merged
    // shape before the rename, with gcc 13:
    //
    //   create_publisher<M>("chatter", 10)                -> UPSTREAM (shared_ptr)
    //   create_publisher<M>("chatter", rclcpp::QoS(10))    -> OURS (by value),
    //                                                         accepted with only
    //                                                         a -Wextra-ish note
    //                                                         that ISO calls it
    //                                                         ambiguous
    //
    // So a ported file compiles either way and gets a different type, lifetime
    // and failure channel depending on which spelling of the depth it used.
    // That is exactly the compile-and-differ RFC-0089 forbids, and the merge is
    // what would have manufactured it. The fix is a different NAME, not a
    // cleverer signature — the third application of that rule in this campaign,
    // after the reordered C node initialiser and the clock-taking C timer verb.
    //
    // `tests/compile/one_node_type_ours_only_names.cpp` pins both halves: that
    // the ported spellings reach upstream's overload on the real type, and
    // (the negative control) that the pre-rename shape bound the wrong one.
 
    template <typename M>
    ::rclcpp::Publisher<M>
    create_publisher_in(const char* topic,
                        const ::rclcpp::QoS& qos = ::rclcpp::QoS::default_profile()) {
        ::rclcpp::Publisher<M> pub;
        Result r = this->create_publisher(pub, topic, qos);
        if (!r.ok()) {
            this->set_error("create_publisher_in", r.raw());
        }
        return pub;
    }
 
    template <typename M, class C, void (C::*Method)(const M& msg)>
    void create_subscription_in(const char* topic,
                                const ::rclcpp::QoS& qos = ::rclcpp::QoS::default_profile());
 
    template <typename M, class C, void (C::*Method)(const M& msg)>
    void create_subscription_in_group(const ::rclcpp::CallbackGroup& group, const char* topic,
                                      const ::rclcpp::QoS& qos = ::rclcpp::QoS::default_profile());
 
    bool check_declared_depth(const char* type_name, const char* topic, const ::rclcpp::QoS& qos) {
        const int declared = ::rclcpp::declared_depth(type_name, topic);
        // Nobody declared this endpoint. Not an error: the image has not opted
        // in, and anything sizing from depth refuses rather than defaulting.
        if (declared == ::rclcpp::DECLARED_DEPTH_UNDECLARED) {
            return true;
        }
        if (declared == qos.depth()) {
            return true;
        }
        // The two NUMBERS and the TOPIC go out first: `set_error` records one
        // `const char*`, which cannot carry them.
        ::rclcpp::detail::report_declared_depth_mismatch(this->get_name(), topic, declared,
                                                         qos.depth());
        this->set_error(
            "create_subscription_in: ::rclcpp::QoS depth disagrees with the depth declared for "
            "this topic in the contract sidecar. Depth multiplies the arena, so the "
            "declaration and the code must state one number, not two.",
            ::rclcpp::detail::DECLARED_DEPTH_MISMATCH);
        return false;
    }
 
    bool check_declared_qos(const char* type_name, const char* topic, const ::rclcpp::QoS& qos) {
        if (!this->check_declared_depth(type_name, topic, qos)) {
            return false;
        }
        const int rel = ::rclcpp::declared_reliability(type_name, topic);
        if (rel != ::rclcpp::DECLARED_POLICY_UNDECLARED &&
            rel != static_cast<int>(qos.reliability())) {
            ::rclcpp::detail::report_declared_policy_mismatch(
                this->get_name(), topic, "reliability",
                ::rclcpp::detail::declared_reliability_spelling(rel),
                ::rclcpp::detail::declared_reliability_spelling(
                    static_cast<int>(qos.reliability())));
            this->set_error("create_subscription_in: ::rclcpp::QoS reliability disagrees with the "
                            "reliability declared for this topic in the contract sidecar.",
                            ::rclcpp::detail::DECLARED_QOS_MISMATCH);
            return false;
        }
        const int dur = ::rclcpp::declared_durability(type_name, topic);
        if (dur != ::rclcpp::DECLARED_POLICY_UNDECLARED &&
            dur != static_cast<int>(qos.durability())) {
            ::rclcpp::detail::report_declared_policy_mismatch(
                this->get_name(), topic, "durability",
                ::rclcpp::detail::declared_durability_spelling(dur),
                ::rclcpp::detail::declared_durability_spelling(static_cast<int>(qos.durability())));
            this->set_error("create_subscription_in: ::rclcpp::QoS durability disagrees with the "
                            "durability declared for this topic in the contract sidecar.",
                            ::rclcpp::detail::DECLARED_QOS_MISMATCH);
            return false;
        }
        return true;
    }
 
    bool check_declared_param(const char* name, int passed_type) {
        const char* ns = this->get_namespace();
        const char* nn = this->get_name();
        if (name == nullptr || nn == nullptr) {
            return true;
        }
        const ::rclcpp::declared_params::Node* declaring =
            ::rclcpp::declared_param_node((ns != nullptr) ? ns : "", nn);
        if (declaring == nullptr || ::rclcpp::declared_param_exempt(name)) {
            return true;
        }
        const int declared = ::rclcpp::declared_param_type(declaring, name);
        if (declared == passed_type) {
            return true;
        }
        ::rclcpp::detail::report_declared_param_mismatch(declaring->fqn, name, declaring->contract,
                                                         declared, passed_type);
        this->set_error("declare_parameter: the code does not declare this parameter the way "
                        "its contract does (see the line above for the node, the parameter and "
                        "the contract). The parameter store is sized from the contract's "
                        "`params:`, so the two must state one name and one type.",
                        ::rclcpp::detail::DECLARED_PARAM_MISMATCH);
        return false;
    }
 
    void set_error(const char* what, int32_t code) {
        // Relaxed read for the first-failure guard: set_error runs during
        // construction, on the constructing thread, never concurrently with a
        // reader (issue #230).
        if (!__atomic_load_n(&has_error_, __ATOMIC_RELAXED)) {
            error_what_ = what;
            error_code_ = code;
            // RELEASE publishes the two plain writes above: a reader that
            // acquire-observes has_error_ == true is guaranteed to see them.
            __atomic_store_n(&has_error_, true, __ATOMIC_RELEASE);
            ::rclcpp::detail::report_component_failure(this->get_name(), what, code);
        }
    }
 
    ~Node() {
        if (initialized_) {
            nros_cpp_node_destroy(&handle_);
            initialized_ = false;
        }
    }
 
    // Move semantics (non-copyable)
    Node(Node&& other)
        : handle_(other.handle_), initialized_(other.initialized_),
          executor_handle_(other.executor_handle_), clock_(other.clock_),
          // The latch travels with the node: a moved-from node's failure is
          // still this node's failure, and the entry checks `ok()` on whichever
          // object it ended up holding.
          has_error_(other.has_error_), error_what_(other.error_what_),
          error_code_(other.error_code_) {
        other.initialized_ = false;
        other.executor_handle_ = nullptr;
    }
 
    Node& operator=(Node&& other) {
        if (this != &other) {
            if (initialized_) {
                nros_cpp_node_destroy(&handle_);
            }
            handle_ = other.handle_;
            initialized_ = other.initialized_;
            executor_handle_ = other.executor_handle_;
            clock_ = other.clock_;
            has_error_ = other.has_error_;
            error_what_ = other.error_what_;
            error_code_ = other.error_code_;
            other.initialized_ = false;
            other.executor_handle_ = nullptr;
        }
        return *this;
    }
 
  private:
    Node(const Node&) = delete;
    Node& operator=(const Node&) = delete;
 
    nros_cpp_node_t handle_;
    bool initialized_;
    void* executor_handle_; // Set by rclcpp::init() via friendship
    // Issue 0789 — the node's own clock, ROS time as in rclcpp. Constructing
    // it touches no platform service (only a steady clock records an epoch),
    // so a Node in static storage stays as cheap to create as it was.
    Clock clock_;
    // phase-476 W3 — `void* hosted_` and its lazy `hosted()` accessor are gone
    // with `detail::NodeHosted` (see there): the block's last member was an
    // empty `NodeOptions`. `sizeof(Node)` loses that pointer on EVERY target,
    // so the layout stays probe-independent.
 
    // phase-427 W4 — the error latch, 24 UNCONDITIONAL bytes on every node.
    //
    // These did NOT go behind the old `hosted_` block, and the decision was deliberate rather
    // than an oversight the layout rule missed. This is the error channel a
    // `-fno-exceptions` target has INSTEAD of a throwing constructor: the
    // boot-halt mechanism (`NanoRosEntityInventory.cmake`, RFC-0044 Q2) is
    // exactly what a freestanding image needs, and a latch reachable only on a
    // hosted target would leave the firmware case — the one that cannot throw —
    // with no channel at all. So every node pays 24 bytes, which is the price
    // of one node type whose failure story works on both.
    //
    // Issue #230 — inverted flag: the HEALTHY value is the zero-init default,
    // so a cross-core reader sees "ok" without waiting for any store. Accessed
    // via __atomic builtins (release in set_error, acquire in ok()/error_*) —
    // NOT `<atomic>`, which the Zephyr `-nostdinc++` minimal libcpp may lack
    // (issue 0112 class). All three fields are zero-init-safe.
    bool has_error_ = false;
    const char* error_what_ = nullptr;
    int32_t error_code_ = 0;
 
    // phase-427 W7 — the class moved to `rclcpp::` while its friends were still
    // `nros::` free functions, so each friend is QUALIFIED. phase-483 W1 moved
    // the friends into `rclcpp::` too; the qualified form still names exactly
    // the declarations at the top of this header.
    //
    // The declarator-id is PARENTHESIZED, and that is not style. A
    // nested-name-specifier is parsed greedily, so `friend Result ::rclcpp::init`
    // reads as `Result::rclcpp::init` and fails with `'rclcpp' in 'using Result ='
    // does not name a type` — a diagnostic that names neither the friend nor
    // the namespace. `(::rclcpp::init)` closes the return type first.
    friend class ::rclcpp::Executor;
    friend class ::rclcpp::NodeBuilder;
    friend Result(::rclcpp::init_in)(const char* locator, uint8_t domain_id);
    friend Result(::rclcpp::init_in)(const char* locator, uint8_t domain_id,
                                     const char* session_name);
    // Issue 1434 — the namespaced overload. A friend declaration names ONE
    // signature, so an overload that reaches `global_storage()` needs its own
    // line; without it the new body compiles everywhere the class is not
    // instantiated and fails only where a TU actually calls it.
    friend Result(::rclcpp::init_in)(const char* locator, uint8_t domain_id,
                                     const char* session_name, const char* node_namespace);
    friend Result(::rclcpp::init_with_rmw)(const char* rmw, const char* locator, uint8_t domain_id,
                                           const char* session_name);
    friend Result(::rclcpp::shutdown_in)();
    friend bool(::rclcpp::ok)();
    friend Result(::rclcpp::create_node)(Node& out, const char* name, const char* ns);
    friend Result(::rclcpp::create_node_on)(Node& out, void* executor_handle, const char* name,
                                            const char* ns);
    friend Result(::rclcpp::spin_once)(int32_t timeout_ms);
    friend Result(::rclcpp::spin_in)();
    friend Result(::rclcpp::spin_in)(uint32_t duration_ms, int32_t poll_ms);
    friend void*(::rclcpp::global_handle)();
 
    // Global executor inline storage for init/shutdown free functions.
    //
    // Use a template-static-member trick instead of a function-local static.
    // Function-local statics need __cxa_guard_acquire/release on first-call
    // initialisation; on NuttX the resulting guard logic returns NULL for
    // the storage pointer (observed empirically with LTO on armv7a-nuttx-eabihf,
    // even with constant-initialisation `= {}`). A template static member is
    // emitted into .bss like a file-scope variable and gets COMDAT-folded by
    // the linker, sidestepping the guarded-init path entirely.
    template <int = 0> struct GlobalStorageHolder {
        alignas(8) static uint8_t storage[NROS_CPP_EXECUTOR_STORAGE_SIZE];
    };
    static uint8_t* global_storage() { return GlobalStorageHolder<>::storage; }
 
    static bool global_initialized() {
        return nros_cpp_context_is_live(GlobalStorageHolder<>::storage);
    }
};
 
// Out-of-class definitions for Node::GlobalStorageHolder<> — the template
// machinery means these get emitted as COMDAT symbols, so multiple TUs
// including this header all collapse to a single .bss allocation.
template <int N>
alignas(8) uint8_t Node::GlobalStorageHolder<N>::storage[NROS_CPP_EXECUTOR_STORAGE_SIZE] = {};
 
} // namespace rclcpp
 
namespace rclcpp {
 
// ==== phase-427 W4 — the timer pool, as a TEMPLATE PARAMETER ================
//
// `ComponentNode` carried `Timer timers_[NROS_COMPONENT_MAX_TIMERS]` — 192
// unconditional bytes at the default depth of 8. Merging that onto `Node` would
// have charged every node in the tree for a pool most of them never touch, on
// targets chosen for having no memory to spare.
//
// So the depth is a template parameter and the DEFAULT IS ZERO: `Node` itself
// carries no pool and is unchanged in size by this half of the merge. A node
// that wants the storage-free timer verbs derives `NodeWithTimers<N>` and names
// the depth it needs.
//
// Why a derived template and not `template <size_t N> class Node` — measured,
// not preferred. `Node` has to stay ONE non-template type
// (`tests/compile/one_node_type.cpp`); 218 in-tree sites spell `Node` with
// no argument list, which a class template with a defaulted parameter does not
// permit; and every `Node&` parameter in the tree — `create_node(Node&)`,
// `Executor`, `spin` — would otherwise accept only ONE depth, so a component
// with a pool would not be a node the executor could take. Deriving keeps the
// IS-A that `ComponentNode` never had (it WRAPPED a node, which is the reason
// this merge exists at all) while keeping the bytes opt-in.
//
// `NodeWithTimers` is NOT a second node type. It adds storage and two verbs;
// it declares no identity, and every one of its instances IS-A `Node`.
 
#ifndef NROS_COMPONENT_MAX_TIMERS
#define NROS_COMPONENT_MAX_TIMERS 8
#endif
#if NROS_COMPONENT_MAX_TIMERS < 1
#error "NROS_COMPONENT_MAX_TIMERS must be >= 1: it sizes a C array (issue 1015)"
#endif
 
template <::size_t MaxTimers = NROS_COMPONENT_MAX_TIMERS>
class NodeWithTimers : public ::rclcpp::Node {
    static_assert(MaxTimers >= 1,
                  "NodeWithTimers<0> has no pool -- derive ::rclcpp::Node directly, or use "
                  "the out-ref create_wall_timer(Timer&, ...) family");
 
  public:
    using ::rclcpp::Node::Node;
 
    template <class C, void (C::*Method)()> void create_wall_timer_in(uint64_t period_ms) {
        Timer* slot = this->next_timer_slot("create_wall_timer_in");
        if (slot == nullptr) return;
        Result r = this->Node::template create_wall_timer<C, Method>(*slot, period_ms,
                                                                     static_cast<C*>(this));
        if (!r.ok()) {
            this->set_error("create_wall_timer_in", r.raw());
            return;
        }
        ++timer_count_;
    }
 
    void create_wall_timer_in(uint64_t period_ms, nros_cpp_timer_callback_t callback,
                              void* context = nullptr) {
        Timer* slot = this->next_timer_slot("create_wall_timer_in");
        if (slot == nullptr) return;
        Result r = this->Node::create_wall_timer(*slot, period_ms, callback, context);
        if (!r.ok()) {
            this->set_error("create_wall_timer_in", r.raw());
            return;
        }
        ++timer_count_;
    }
 
    template <class C, void (C::*Method)()>
    void create_timer_in_group(const CallbackGroup& group, uint64_t period_ms) {
        Timer* slot = this->next_timer_slot("create_timer_in_group");
        if (slot == nullptr) return;
        Result r = this->Node::template create_timer_in_group<C, Method>(group, *slot, period_ms,
                                                                         static_cast<C*>(this));
        if (!r.ok()) {
            this->set_error("create_timer_in_group", r.raw());
            return;
        }
        ++timer_count_;
    }
 
    void create_timer_in_group(const CallbackGroup& group, uint64_t period_ms,
                               nros_cpp_timer_callback_t callback, void* context = nullptr) {
        Timer* slot = this->next_timer_slot("create_timer_in_group");
        if (slot == nullptr) return;
        Result r = this->Node::create_timer_in_group(group, *slot, period_ms, callback, context);
        if (!r.ok()) {
            this->set_error("create_timer_in_group", r.raw());
            return;
        }
        ++timer_count_;
    }
 
    // The out-ref forms on `Node` share these names; bring them in so a derived
    // node can still spell `create_timer_in_group(group, my_timer_, 100, cb, ctx)`
    // without the pool overloads hiding the base by name lookup.
    using ::rclcpp::Node::create_timer_in_group;
    using ::rclcpp::Node::create_wall_timer;
 
  private:
    Timer* next_timer_slot(const char* what) {
        if (timer_count_ >= MaxTimers) {
            this->set_error(what, -1);
            return nullptr;
        }
        return &timers_[timer_count_];
    }
 
    Timer timers_[MaxTimers];
    ::size_t timer_count_ = 0;
};
 
// -- Free function implementations --
 
inline Result init_in(const char* locator, uint8_t domain_id) {
    // Issue 0329 — forward RAW to the 3-arg overload, which resolves the whole
    // ladder (baked `NROS_ENTRY_LOCATOR`/`NROS_ENTRY_DOMAIN_ID` rungs, hosted
    // default, then the env overlay in the Rust resolver behind `nros_cpp_init`).
    // This overload previously re-resolved the locator rung itself — a second,
    // partial copy of the same ladder (it never applied `NROS_ENTRY_DOMAIN_ID`),
    // duplicating what the 3-arg already does. Phase 266: unified default session
    // name "node".
    return init_in(locator, domain_id, "node");
}
 
inline Result init_in(const char* locator, uint8_t domain_id, const char* session_name) {
    // Issue 1434 — forward RAW to the 4-arg overload, exactly as the 2-arg
    // forwards here (issue 0329): one ladder, one body. `nullptr` is "this
    // image declares no namespace", which is what every caller of this
    // overload has always meant.
    return init_in(locator, domain_id, session_name, nullptr);
}
 
inline Result init_in(const char* locator, uint8_t domain_id, const char* session_name,
                      const char* node_namespace) {
    // NROS_CPP_RET_INVALID_ARGUMENT = -3 (defined in nros_cpp_ffi.h
    // which isn't included from this header — duplicate the value
    // inline; generated header is the source of truth).
    if (session_name == nullptr) {
        return Result(-3);
    }
#if defined(NROS_CPP_STD) || (__STDC_HOSTED__ + 0) // hosted-family: hosted-console
    // Issue #39 — apply the same `$NROS_LOCATOR` / `$ROS_DOMAIN_ID` env
    // fallback as the 2-arg `init()` when `locator` is null / `domain_id` is
    // 0. This makes `init_in(argc, argv)` (which delegates here with a
    // null locator) honor the env overlay instead of passing a null locator
    // to the backend → TransportError / degraded session.
    // Issue 0330 — the hard local default is GONE entirely (it was a zenoh
    // fact in an RMW-blind header); the backend now supplies it.
    // RFC-0045 / issue #206 — the env overlay (NROS_LOCATOR / ROS_DOMAIN_ID /
    // NROS_NODE_NAME) moved into the shared Rust resolver behind
    // nros_cpp_init (precedence model A: hosted env > this baked chain >
    // compiled default; malformed or >232 ROS_DOMAIN_ID is an init ERROR,
    // never a silent domain 0). This header only assembles the baked rung.
#endif
    // Phase-287 W6 — compile-time connect defaults, so ONE portable source
    // works native + embedded. `NROS_ENTRY_LOCATOR` / `NROS_ENTRY_DOMAIN_ID`
    // are target compile definitions the embedded board gate bakes
    // (NanoRosEntry.cmake; Kconfig on Zephyr via <rclcpp/detail/main.hpp>); on native
    // they are undefined. Precedence (model A, RFC-0045/#206): env (hosted,
    // applied in the Rust resolver) > explicit arg > baked macro > default.
#ifdef NROS_ENTRY_LOCATOR
    if (locator == nullptr) {
        locator = NROS_ENTRY_LOCATOR;
    }
#endif
#ifdef NROS_ENTRY_DOMAIN_ID
    // Only the UNSET sentinel (0) folds the baked macro in; an explicit
    // argument — including kDomainIdExplicitZero (255) for a literal
    // domain 0 (issue #227) — passes through untouched.
    if (domain_id == 0) {
        domain_id = static_cast<uint8_t>(NROS_ENTRY_DOMAIN_ID);
    }
#endif
    // Issue 0330 — there is deliberately NO hosted "tcp/127.0.0.1:7447"
    // fallback here. That value is a *zenoh* fact and this header is
    // RMW-blind; a cyclonedds or xrce build must not carry it. A null
    // locator flows through `nros_cpp_init` (→ `None` → the RFC-0045
    // resolver's empty bottom rung) to whichever backend is linked, and
    // that backend applies its own default (zenoh:
    // `nros_rmw_zenoh::DEFAULT_LOCATOR`; xrce: its agent default;
    // cyclonedds: ignores the locator). Precedence is otherwise unchanged:
    // hosted env > explicit arg > baked macro > backend default.
 
    // Phase 128.C.1 / phase-241.D3-rev — RMW-blind init. The selected
    // backend registers itself before `main` via its `.init_array` ctor
    // (RFC-0042 §D3.3), and `nros_cpp_init` additionally calls the weak
    // `nros_app_register_backends()` board-override hook for RTOS targets
    // where `.init_array` ctors do not run. No `#ifdef NROS_RMW_*` chain
    // here, no CMake-driven fan-out — the user's
    // `target_link_libraries(... NanoRos::Rmw::<name>)` is the only
    // selector.
    // Issue 1050 defect (3) — the RMW selector's BAKED rung. `NROS_ENTRY_RMW`
    // is a target compile definition the entry gate bakes, exactly like
    // `NROS_ENTRY_LOCATOR` / `NROS_ENTRY_DOMAIN_ID` above; undefined means the
    // image names no backend and the registry must contain exactly one.
    //
    // This is what the paragraph above could not express. "The user's
    // `target_link_libraries(... NanoRos::Rmw::<name>)` is the only selector"
    // is true of the LINK and false of the REGISTRY: a hosted archive
    // registers whatever it carries, from `.init_array`, before `main`.
#ifdef NROS_ENTRY_RMW
    const char* rmw = NROS_ENTRY_RMW;
#else
    const char* rmw = nullptr;
#endif
    // Issue 1434 — the namespace travels as the BAKED rung, like `rmw` above
    // and `session_name` beside it. `nullptr` reaches `nros_cpp_init_rmw`'s
    // own "unset" arm, which is the root; an EMPTY string is normalised here
    // rather than there, because a bake macro that did not resolve expands to
    // `""` and treating that as "the empty namespace" would be a configured
    // value where the image stated nothing (the same reasoning 1050 applied to
    // an empty `rmw` selector).
    if (node_namespace != nullptr && node_namespace[0] == '\0') {
        node_namespace = nullptr;
    }
    // Issue 1568 — the one refusal every executor-storage path takes: the
    // linked library says whether this TU's `NROS_CPP_EXECUTOR_STORAGE_SIZE`
    // (the header it was compiled against — on NuttX the committed snapshot)
    // is enough for the executor it builds. Refused rather than overrun.
    {
        nros_cpp_ret_t chk =
            nros_cpp_executor_storage_check(::rclcpp::Node::global_storage(),
                                            sizeof(::rclcpp::Node::GlobalStorageHolder<>::storage));
        if (chk != 0) {
            return Result(chk);
        }
    }
    nros_cpp_ret_t ret = nros_cpp_init_rmw(rmw, locator, domain_id, session_name, node_namespace,
                                           ::rclcpp::Node::global_storage());
    // No flag to set: `nros_cpp_init_rmw` stamps the context tag, and
    // `global_initialized()` reads it.
    return Result(ret);
}
 
inline Result init_with_rmw(const char* rmw, const char* locator, uint8_t domain_id,
                            const char* session_name) {
    // NROS_CPP_RET_INVALID_ARGUMENT = -3; see the 3-arg overload for why the
    // value is duplicated here rather than included.
    if (session_name == nullptr) {
        return Result(-3);
    }
#ifdef NROS_ENTRY_LOCATOR
    if (locator == nullptr) {
        locator = NROS_ENTRY_LOCATOR;
    }
#endif
#ifdef NROS_ENTRY_DOMAIN_ID
    if (domain_id == 0) {
        domain_id = static_cast<uint8_t>(NROS_ENTRY_DOMAIN_ID);
    }
#endif
    // No `NROS_ENTRY_RMW` fallback here: an explicit argument that resolves to
    // nullptr is the caller saying "no selector", and quietly substituting the
    // bake would make this overload unable to express that.
    // Issue 1568 — the one refusal every executor-storage path takes: the
    // linked library says whether this TU's `NROS_CPP_EXECUTOR_STORAGE_SIZE`
    // (the header it was compiled against — on NuttX the committed snapshot)
    // is enough for the executor it builds. Refused rather than overrun.
    {
        nros_cpp_ret_t chk =
            nros_cpp_executor_storage_check(::rclcpp::Node::global_storage(),
                                            sizeof(::rclcpp::Node::GlobalStorageHolder<>::storage));
        if (chk != 0) {
            return Result(chk);
        }
    }
    nros_cpp_ret_t ret = nros_cpp_init_rmw(rmw, locator, domain_id, session_name, nullptr,
                                           ::rclcpp::Node::global_storage());
    // No flag to set: `nros_cpp_init_rmw` stamps the context tag, and
    // `global_initialized()` reads it.
    return Result(ret);
}
 
inline Result shutdown_in() {
    if (!::rclcpp::Node::global_initialized()) {
        return Result::success();
    }
    // No flag to clear: `nros_cpp_fini` unstamps the tag, which is what
    // `global_initialized()` reads. One owner of the fact.
    return Result(nros_cpp_fini(::rclcpp::Node::global_storage()));
}
 
inline void* global_handle() {
    if (!::rclcpp::Node::global_initialized()) return nullptr;
    return ::rclcpp::Node::global_storage();
}
 
namespace detail {
inline int32_t apply_ros_args(void* executor, int argc, char const* const* argv) {
    // No `--ros-args` scope means nothing for the parser to read; skipping the
    // call keeps a plain `main(argc, argv)` off the FFI entirely.
    bool scoped = false;
    for (int i = 0; argv != nullptr && i < argc && !scoped; ++i) {
        const char* a = argv[i];
        const char* want = "--ros-args";
        while (a != nullptr && *a != '\0' && *a == *want) {
            ++a;
            ++want;
        }
        scoped = a != nullptr && *a == '\0' && *want == '\0';
    }
    if (!scoped) {
        return 0;
    }
    char why[256] = {0};
    const int32_t rc = nros_cpp_install_argv_remaps(executor, argc, argv, why, sizeof(why));
    if (rc != 0) {
        // issue 1303 — two records through `nros_log`, each short enough for
        // its format buffer: the refused token (bounded here), then the fixed
        // text, whose length `say_refused` checks at compile time. As one
        // `NROS_ERROR` record it was over 870 bytes, which a real sink cannot
        // carry: the body is dropped and only an ellipsis is printed.
        RCLC_LOG_ERROR(::rclcpp::detail::log_handle(nullptr), "rclcpp::init: refused: %.120s",
                       why[0] != '\0' ? why : "invalid executor handle or argv");
        NROS_RCLCPP_SAY_REFUSED(NROS_RCLCPP_REFUSE_INIT_ARGV);
    }
    return rc;
}
 
inline Result init_honouring_ros_args(int argc, char const* const* argv, const char* name) {
    const int32_t checked = apply_ros_args(nullptr, argc, argv);
    if (checked != 0) {
        return Result(checked);
    }
    Result r = init_in(nullptr, 0, name);
    if (!r.ok()) {
        return r;
    }
    const int32_t installed = apply_ros_args(::rclcpp::global_handle(), argc, argv);
    if (installed != 0) {
        (void)shutdown_in();
        return Result(installed);
    }
    return r;
}
} // namespace detail
 
// -- init honouring --ros-args --
//
// `init_in(argc, argv)` delegates to the 3-arg `init_in`, which reads the
// environment. The session name falls back to `"nros_cpp"`.
 
inline Result init_in(int argc, char const* const* argv, const char* session_name) {
    const char* name = (session_name != nullptr) ? session_name : "nros_cpp";
    return detail::init_honouring_ros_args(argc, argv, name);
}
 
inline bool ok() {
    return ::rclcpp::Node::global_initialized() && !::nros_cpp_termination_requested();
}
 
inline Result create_node(::rclcpp::Node& out, const char* name, const char* ns = nullptr) {
    if (!::rclcpp::Node::global_initialized()) {
        return Result(ErrorCode::NotInitialized);
    }
    out.executor_handle_ = ::rclcpp::Node::global_storage();
    return ::rclcpp::Node::create(out, name, ns);
}
 
inline Result create_node_on(::rclcpp::Node& out, void* executor_handle, const char* name,
                             const char* ns = nullptr) {
    if (executor_handle == nullptr) {
        return Result(ErrorCode::NotInitialized);
    }
    out.executor_handle_ = executor_handle;
    return ::rclcpp::Node::create(out, name, ns);
}
 
inline ResultOf<::rclcpp::Node> make_node(const char* name, const char* ns = nullptr) {
    ::rclcpp::Node n;
    Result r = create_node(n, name, ns);
    if (!r.ok()) return ResultOf<::rclcpp::Node>::error(r);
    return ResultOf<::rclcpp::Node>::ok(::rclcpp::tr::forward_rvalue(n));
}
 
// -- Executor::create_node implementation (requires full Node definition) --
 
inline Result Executor::create_node(::rclcpp::Node& out, const char* name, const char* ns) {
    if (!initialized_) return Result(ErrorCode::NotInitialized);
    out.executor_handle_ = storage_;
    return ::rclcpp::Node::create(out, name, ns);
}
 
// -- Phase 104.C.9 — NodeBuilder ----------------------------------------
//
// Mirrors Rust's `Executor::node_builder(name).rmw(...).locator(...).
// domain_id(...).namespace(...).sched(...).build()` chain. The C++
// wrapper is value-typed and stack-allocated; it accumulates options
// into an inline `nros_cpp_node_options_t` and ships it to
// `nros_cpp_node_create_ex` on `.build()`.
//
// Usage:
// ```cpp
// rclcpp::Node node;
// RCLCPP_TRY(executor.node_builder("egress")
//              .rmw("cyclonedds")
//              .domain_id(0)
//              .build(node));
// ```
 
class NodeBuilder {
  public:
    NodeBuilder(void* executor_handle, const char* name)
        : executor_handle_(executor_handle), name_(name),
          options_(nros_cpp_node_get_default_options()) {}
 
    NodeBuilder& rmw(const char* name) {
        copy_bounded(name, options_.rmw_name, &options_.rmw_name_len, NROS_CPP_RMW_NAME_LEN);
        return *this;
    }
 
    NodeBuilder& locator(const char* loc) {
        copy_bounded(loc, options_.locator, &options_.locator_len, NROS_CPP_LOCATOR_LEN);
        return *this;
    }
 
    NodeBuilder& domain_id(uint32_t id) {
        options_.domain_id_override = id;
        return *this;
    }
 
    NodeBuilder& namespace_(const char* ns) {
        copy_bounded(ns, options_.namespace_, &options_.namespace_len, NROS_CPP_NAMESPACE_LEN);
        return *this;
    }
 
    NodeBuilder& sched(uint8_t sc_id) {
        options_.sched_context_id = sc_id;
        return *this;
    }
 
    Result build(::rclcpp::Node& out) const {
        if (!executor_handle_) return Result(ErrorCode::NotInitialized);
        out.executor_handle_ = executor_handle_;
        nros_cpp_ret_t ret =
            nros_cpp_node_create_ex(executor_handle_, name_, &options_, &out.handle_);
        if (ret == 0) {
            out.initialized_ = true;
        }
        return Result(ret);
    }
 
  private:
    static void copy_bounded(const char* src, uint8_t* dst, size_t* dst_len, size_t cap) {
        size_t n = 0;
        if (src != nullptr) {
            while (src[n] != '\0' && n < cap) {
                dst[n] = static_cast<uint8_t>(src[n]);
                ++n;
            }
        }
        // Zero out the tail so stale bytes don't leak across reuses.
        for (size_t i = n; i < cap; ++i) {
            dst[i] = 0;
        }
        *dst_len = n;
    }
 
    void* executor_handle_;
    const char* name_;
    nros_cpp_node_options_t options_;
};
 
inline NodeBuilder Executor::node_builder(const char* name) {
    return NodeBuilder(initialized_ ? handle() : nullptr, name);
}
 
namespace detail {
inline void finish_declared_callback_groups(::rclcpp::Node& node,
                                            const DeclaredCallbackGroups& groups) {
    const char* missing = nullptr;
    int len = 0;
    if (first_uncreated_callback_group(groups, &missing, &len)) {
        report_callback_group_mismatch(node.get_name(), "declared", missing, len, groups.list);
        node.set_error("a CALLBACK_GROUPS group was never created",
                       DECLARED_CALLBACK_GROUP_MISMATCH);
    }
}
} // namespace detail
 
} // namespace rclcpp
 
// The process-level verbs — `rclcpp::init()`, `rclcpp::ok()`,
// `rclcpp::shutdown()`, `rclcpp::spin_once()` — are declared in `nros.hpp`,
// which is where the free functions they name live. This header carries only
// what the node itself needs.
 
#endif // NROS_RCLCPP_NODE_HPP