nros_node/executor/

storage.rs

//! phase-271 / phase-409 — per-entry [`Executor`](super::spin::Executor)
//! storage (issues 0110, 0563, 0936).
//!
//! The executor's sized tables (callback table + arena + scheduling-context
//! tables + the node/session/dispatch tables) used to be inline fields sized by
//! build-time consts baked into `nros-node` — one size for every entry sharing a
//! compiled `nros-node`, and, worse, a size that every function MOVING an
//! `Executor` had to make room for on its stack. Here the ENTRY supplies its own
//! storage, sized to its topology, so a fat native entry and a lean embedded
//! entry in one workspace each get the right size with no workspace-global env,
//! and the `Executor` VALUE stays a small fixed header.
//!
//! Per the "C/C++ is a thin wrapper of Rust" principle the PUBLIC API stays
//! generic-free: the entry hands a raw, 8-aligned `&mut [MaybeUninit<u64>]` backing
//! (sized via [`executor_storage_u64_len`]); `nros-node` carves it privately into
//! the typed sub-slices ([`carve`]). The only `unsafe` is that carve, validated
//! against the `#[repr(C)]` reference [`ExecutorStorage`] layout by unit test.

use core::{
    alloc::Layout,
    mem::{MaybeUninit, align_of, needs_drop, size_of},
    ops::{Deref, DerefMut},
};

use super::{
    arena::CallbackMeta,
    monitor::{AliveSlot, MAX_VIOLATIONS, Violation},
    node_record::NodeRecord,
    sched_context::{SchedContext, SchedContextId, SporadicState},
    spin::{ComponentSlot, DispatchSlot, MAX_REMAPS, RemapRule},
    types::SlotTag,
};
use crate::session::ConcreteSession;

/// Issue 1812 — the parameter services' carved home. A zero-sized stand-in
/// where the services are not compiled, so the region costs nothing there and
/// `carve` still has one type to place.
#[cfg(feature = "param-store")]
pub(crate) type ParamHome = crate::param_store::ParamHome;
#[cfg(not(feature = "param-store"))]
pub(crate) type ParamHome = ();

#[cfg(feature = "alloc")]
type SporadicAtomic = (
    portable_atomic_util::Arc<super::sched_context::AtomicSporadicState>,
    super::spin::OpaqueTimerHandle,
);

/// phase-272 — `(node name, namespace, sched context)`, keyed by the node's
/// fully-qualified identity.
pub(crate) type NodeSchedEntry = (heapless::String<64>, heapless::String<64>, SchedContextId);
/// phase-273 — [`NodeSchedEntry`] plus the callback-group name that narrows it.
pub(crate) type GroupSchedEntry = (
    heapless::String<64>,
    heapless::String<64>,
    heapless::String<32>,
    SchedContextId,
);
/// Issue 0436 — `(rmw name, locator)` for one extra session.
pub(crate) type ExtraSessionId = (heapless::String<32>, heapless::String<128>);
/// Phase 228.C — one callback-group name in a tier executor's filter.
pub(crate) type GroupName = heapless::String<32>;

/// The node half of an [`ActiveGroup`] key: a hash of `(name, namespace)`.
///
/// FNV-1a, 64-bit, over `name` then `\0` then the normalised namespace. The
/// separator matters: without it `("ab", "c")` and `("a", "bc")` hash alike,
/// and a node name may legally contain any of the namespace's characters.
///
/// FNV because the tree already depends on it (heapless's `FnvIndexMap`), it
/// is `const`-friendly and allocation-free, and this runs on the registration
/// path of every entity on an MCU. A 64-bit collision across the handful of
/// nodes in one image is not a risk worth a bigger key: at 32 entries the
/// probability is around 3e-17.
///
/// ONE home, deliberately. Both ends of the comparison call this —
/// `set_active_groups` hashing what the tier declared, and `create_entity`
/// hashing the node an entity belongs to. Two hashers that agree by
/// inspection is exactly the defect class issue 1172 is filed under.
pub(crate) fn node_identity_hash(name: &str, namespace: &str) -> u64 {
    const OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
    const PRIME: u64 = 0x0000_0100_0000_01b3;
    let norm_ns = if namespace.is_empty() { "/" } else { namespace };
    let mut h = OFFSET;
    for b in name
        .as_bytes()
        .iter()
        .chain(core::iter::once(&0u8))
        .chain(norm_ns.as_bytes())
    {
        h ^= *b as u64;
        h = h.wrapping_mul(PRIME);
    }
    h
}

/// One entry of a tier's active-group filter: `(node identity hash, group)`.
///
/// issue 1172 — the filter used to be the GROUP NAME ALONE, which cannot tell
/// node A's `ctrl` from node B's `ctrl`. Two nodes may legitimately declare the
/// same group id on different tiers and nothing rejects it, so a tier filter
/// was admitting entities it did not own. The sibling table for the
/// sched-context path (`group_sched_table`, `bind_group_sched`) has been
/// node-qualified all along; only this one was not.
///
/// The node half is a HASH of `(name, namespace)` rather than the strings.
/// Storing them would cost 184 B per entry against this table's 48 B, and the
/// table is CARVED one entry per node slot — +144 B per slot, which is 4.6 KB
/// of static executor arena at 32 slots. The group name stays readable because
/// a refused filter should be able to say WHICH group it refused.
///
/// The hash has exactly one home, [`node_identity_hash`], and both ends of the
/// comparison call it — codegen never hashes anything, it emits plain strings.
/// A second hasher would be this phase's own defect in a new place.
pub(crate) type ActiveGroup = (u64, GroupName);

// ============================================================================
// CarvedVec — a `heapless::Vec` whose capacity lives in the caller's backing
// ============================================================================

/// A push-only vector over CARVED storage: the elements live in the caller's
/// backing, the `Executor` holds only a fat pointer and a fill cursor.
///
/// phase-409 (issue 0961) — this is the shape phase-271 gave the six sized
/// tables, generalised so the other nine can use it too. It exists because
/// `heapless::Vec<T, N>` puts `N * size_of::<T>()` bytes INSIDE the struct, so
/// every knob that sets an `N` also sets the stack frame of every function that
/// moves an `Executor`: `MAX_CBS` 14 -> 36 (a handle-count fix) added ~3.7 KiB
/// to `Executor::open_in`'s prologue on a part whose main thread has 32 KiB in
/// total.
///
/// Deliberately `MaybeUninit<T>` rather than `Option<T>`, for three reasons:
/// [`as_slice`](Self::as_slice) can hand back the `&[T]` the public
/// `Executor::nodes()` accessor already returns; `carve` writes NOTHING at open
/// (the `memclr` in issue 0961's fault was the executor's tables being zeroed);
/// and the layout matches `heapless::Vec`'s, so the storage cost is the same
/// bytes in a different place.
///
/// Occupied slots are `[0, len)` and IN PUSH ORDER — several callers index by
/// insertion position (`NodeId` IS an index into `nodes`; `session_idx` is an
/// index into `extra_sessions`), so this must never gain a `swap_remove`.
pub(crate) struct CarvedVec<'s, T> {
    slots: &'s mut [MaybeUninit<T>],
    len: usize,
}

impl<'s, T> CarvedVec<'s, T> {
    /// Wrap carved, UNINITIALISED storage as an empty vector.
    fn new(slots: &'s mut [MaybeUninit<T>]) -> Self {
        Self { slots, len: 0 }
    }

    /// Slots this vector can hold — the entry's sizing, not a build-time const.
    pub(crate) fn capacity(&self) -> usize {
        self.slots.len()
    }

    /// Append `value`, returning it in `Err` when full (`heapless::Vec::push`).
    pub(crate) fn push(&mut self, value: T) -> Result<(), T> {
        if self.len == self.capacity() {
            return Err(value);
        }
        self.slots[self.len].write(value);
        self.len += 1;
        Ok(())
    }

    /// Remove and return the OLDEST element (index 0), shifting the rest down
    /// one so push order is kept. O(len); phase-474 I1's violation ring is its
    /// one caller, at `MAX_VIOLATIONS` (default 8) slots.
    pub(crate) fn pop_front(&mut self) -> Option<T> {
        if self.len == 0 {
            return None;
        }
        // SAFETY: `[0, len)` is initialised; slot 0 is read out exactly once
        // and then overwritten by the shift (or left outside `[0, len - 1)`).
        let first = unsafe { self.slots[0].assume_init_read() };
        let base = self.slots.as_mut_ptr();
        // SAFETY: both ranges lie inside `slots`; `copy` handles the overlap.
        unsafe { core::ptr::copy(base.add(1), base, self.len - 1) };
        self.len -= 1;
        Some(first)
    }

    /// Drop every element and reset the cursor.
    pub(crate) fn clear(&mut self) {
        let len = core::mem::replace(&mut self.len, 0);
        if needs_drop::<T>() {
            for slot in &mut self.slots[..len] {
                // SAFETY: `[0, len)` was initialised by `push` and is dropped
                // exactly once — `len` is reset above before this loop runs, so
                // a panicking `T::drop` cannot make a second pass see it.
                unsafe { slot.assume_init_drop() };
            }
        }
    }

    /// The initialised prefix.
    pub(crate) fn as_slice(&self) -> &[T] {
        // SAFETY: `push` initialises `[0, len)` and nothing shortens `len`
        // without dropping (see `clear`).
        unsafe { &*(&self.slots[..self.len] as *const [MaybeUninit<T>] as *const [T]) }
    }

    /// The initialised prefix, mutably.
    pub(crate) fn as_mut_slice(&mut self) -> &mut [T] {
        // SAFETY: as [`as_slice`](Self::as_slice).
        unsafe { &mut *(&mut self.slots[..self.len] as *mut [MaybeUninit<T>] as *mut [T]) }
    }
}

impl<T> Deref for CarvedVec<'_, T> {
    type Target = [T];
    fn deref(&self) -> &[T] {
        self.as_slice()
    }
}

impl<T> DerefMut for CarvedVec<'_, T> {
    fn deref_mut(&mut self) -> &mut [T] {
        self.as_mut_slice()
    }
}

impl<T> Drop for CarvedVec<'_, T> {
    fn drop(&mut self) {
        // The backing is the CALLER's memory, so nothing drops these elements
        // for us — and one of these tables is `extra_sessions`, whose elements
        // close RMW sessions. A `Drop` impl on the vector (rather than a pass in
        // `Executor::drop`) keeps the ORDER the inline `heapless::Vec`s had:
        // `Executor`'s fields drop in declaration order, so the primary
        // `session` still closes before the extras.
        self.clear();
    }
}

// ============================================================================
// Layout
// ============================================================================

/// The typed reference layout the [`carve`] mirrors. `#[repr(C)]` so its field
/// offsets are the deterministic declaration-order layout the const-fn below
/// reproduces; a unit test asserts they agree. Only referenced by tests.
#[cfg(test)]
#[repr(C)]
pub(crate) struct ExecutorStorage<
    const CBS: usize,
    const SC: usize,
    const ARENA: usize,
    const NODES: usize,
    const PARAMS: usize,
    const HOMES: usize,
> {
    arena: [MaybeUninit<u8>; ARENA],
    entries: [Option<CallbackMeta>; CBS],
    sched_contexts: [Option<SchedContext>; SC],
    sched_context_bindings: [SchedContextId; CBS],
    sporadic_states: [Option<SporadicState>; SC],
    #[cfg(feature = "alloc")]
    sporadic_atomic_states: [Option<SporadicAtomic>; SC],
    remaps: [Option<RemapRule>; MAX_REMAPS],
    // phase-409 — the nine that phase-271 left inline.
    nodes: [MaybeUninit<NodeRecord>; NODES],
    extra_sessions: [MaybeUninit<ConcreteSession>; NODES],
    extra_session_ids: [MaybeUninit<ExtraSessionId>; NODES],
    node_sched_table: [MaybeUninit<NodeSchedEntry>; NODES],
    dispatch_slots: [MaybeUninit<DispatchSlot>; NODES],
    component_slots: [MaybeUninit<ComponentSlot>; NODES],
    active_groups: [MaybeUninit<ActiveGroup>; NODES],
    group_sched_table: [MaybeUninit<GroupSchedEntry>; CBS],
    monitor_violations: [MaybeUninit<Violation>; MAX_VIOLATIONS],
    alive_slots: [AliveSlot; SC],
    slot_tags: [SlotTag; CBS],
    // phase-382 W3' — the parameter store, LAST.
    params: [MaybeUninit<nros_params::ParameterSlot>; PARAMS],
    // issue 1812 — the parameter services' home, after the store.
    param_home: [MaybeUninit<ParamHome>; HOMES],
}

/// The typed, mutable sub-slices an [`Executor`](super::spin::Executor) borrows
/// from a carved backing. Element memory is initialised by [`carve`] for the
/// `Option`/`SchedContextId` tables; the [`CarvedVec`] tables are handed over
/// UNINITIALISED and fill on push.
pub(crate) struct ExecutorSlices<'s> {
    pub(crate) arena: &'s mut [MaybeUninit<u8>],
    pub(crate) entries: &'s mut [Option<CallbackMeta>],
    pub(crate) sched_contexts: &'s mut [Option<SchedContext>],
    pub(crate) sched_context_bindings: &'s mut [SchedContextId],
    pub(crate) sporadic_states: &'s mut [Option<SporadicState>],
    #[cfg(feature = "alloc")]
    pub(crate) sporadic_atomic_states: &'s mut [Option<SporadicAtomic>],
    /// Issue 0563 — the SEVENTH sized table. phase-271 moved six of these out
    /// of `Executor` and into caller-owned storage; the remap table was left
    /// inline and grew to 6664 bytes of an 11632-byte struct (57%), which is
    /// what made constructing an executor a ~9.3 KB STACK temporary and
    /// overflowed the Zephyr Cortex-M main stack in issue 0552.
    ///
    /// Fixed count (`MAX_REMAPS`) rather than a new `ExecutorSizing` knob:
    /// the capability is unchanged, so this needs no public API change and no
    /// regeneration of every entry's sizing. The required backing grows by the
    /// same bytes, but that lands in the caller's STATIC buffer instead of on
    /// the stack, which is the entire point.
    pub(crate) remaps: &'s mut [Option<RemapRule>],
    // phase-409 (issue 0961) — the remaining nine, same reasoning one campaign
    // later. `MAX_CBS` 14 -> 36 put ~3.7 KiB of `group_sched_table` on the stack
    // of every function that moves an `Executor`.
    pub(crate) nodes: CarvedVec<'s, NodeRecord>,
    pub(crate) extra_sessions: CarvedVec<'s, ConcreteSession>,
    pub(crate) extra_session_ids: CarvedVec<'s, ExtraSessionId>,
    pub(crate) node_sched_table: CarvedVec<'s, NodeSchedEntry>,
    pub(crate) dispatch_slots: CarvedVec<'s, DispatchSlot>,
    pub(crate) component_slots: CarvedVec<'s, ComponentSlot>,
    pub(crate) active_groups: CarvedVec<'s, ActiveGroup>,
    pub(crate) group_sched_table: CarvedVec<'s, GroupSchedEntry>,
    pub(crate) monitor_violations: CarvedVec<'s, Violation>,
    /// Alive supervision, one record per SC. Initialised by [`carve`] like the
    /// SC tables above it: a zeroed record is the correct starting state.
    pub(crate) alive_slots: &'s mut [AliveSlot],
    /// phase-476 W0 — one lifetime tag per callback slot, parallel to
    /// `entries`. Initialised by [`carve`] to the default (generation 0, no
    /// owner), which is what a never-used slot is.
    pub(crate) slot_tags: &'s mut [SlotTag],
    /// phase-382 W3' — the EIGHTH sized table phase-382 planned and the region
    /// issue 1706 asked for: the parameter store's slots, handed over
    /// UNINITIALISED. The executor initialises them the first time something
    /// declares a parameter (`nros_params::ParameterTable::init_in`), so an
    /// image that carves a store and never declares pays the `.bss` and no
    /// boot time. Empty when the sizing carves no store, which is every image
    /// the build does not know to build one ([`ExecutorSizing::params`]).
    pub(crate) params: &'s mut [MaybeUninit<nros_params::ParameterSlot>],
    /// Issue 1812 — the parameter SERVICES' home ([`ParamHome`]): one when the
    /// sizing carves a store, none otherwise. Handed over UNINITIALISED, like
    /// `params`; `ParamHome::init_in` builds the state in it the first time
    /// something asks for the store.
    pub(crate) param_home: &'s mut [MaybeUninit<ParamHome>],
}

/// Byte offsets of each field within the backing + total size/align. Computed
/// identically by [`executor_storage_layout`] and [`carve`] (single source of
/// truth), reproducing `#[repr(C)]` declaration-order layout.
struct FieldOffsets {
    arena: usize,
    entries: usize,
    sched_contexts: usize,
    sched_context_bindings: usize,
    sporadic_states: usize,
    #[cfg(feature = "alloc")]
    sporadic_atomic_states: usize,
    remaps: usize,
    nodes: usize,
    extra_sessions: usize,
    extra_session_ids: usize,
    node_sched_table: usize,
    dispatch_slots: usize,
    component_slots: usize,
    active_groups: usize,
    group_sched_table: usize,
    monitor_violations: usize,
    alive_slots: usize,
    slot_tags: usize,
    params: usize,
    param_home: usize,
    size: usize,
    align: usize,
}

/// The placement arithmetic and its data types live in `nros-executor-layout`
/// (issue 1197) so a HOST build script can evaluate them for a target it is not
/// compiling. Re-exported here because this is where every consumer already
/// looks, and because `NATIVE` — the only part that names the types — has to
/// live in the crate that owns them.
pub use nros_executor_layout::{Counts as RegionCounts, RegionUnit, RegionUnits};

/// What THIS compiler says, for the target it is compiling.
///
/// The one thing the shared crate cannot provide: it would have to name the
/// types, and they live here.
pub const NATIVE_UNITS: RegionUnits = RegionUnits {
    callback_meta: unit_of::<Option<CallbackMeta>>(),
    sched_context: unit_of::<Option<SchedContext>>(),
    sched_context_id: unit_of::<SchedContextId>(),
    sporadic_state: unit_of::<Option<SporadicState>>(),
    #[cfg(feature = "alloc")]
    sporadic_atomic: unit_of::<Option<SporadicAtomic>>(),
    #[cfg(not(feature = "alloc"))]
    sporadic_atomic: RegionUnit { size: 0, align: 1 },
    remap_rule: unit_of::<Option<RemapRule>>(),
    node_record: unit_of::<NodeRecord>(),
    concrete_session: unit_of::<ConcreteSession>(),
    extra_session_id: unit_of::<ExtraSessionId>(),
    node_sched_entry: unit_of::<NodeSchedEntry>(),
    dispatch_slot: unit_of::<DispatchSlot>(),
    component_slot: unit_of::<ComponentSlot>(),
    group_name: unit_of::<ActiveGroup>(),
    group_sched_entry: unit_of::<GroupSchedEntry>(),
    violation: unit_of::<Violation>(),
    alive_slot: unit_of::<AliveSlot>(),
    slot_tag: unit_of::<SlotTag>(),
    parameter_slot: unit_of::<nros_params::ParameterSlot>(),
    param_home: unit_of::<ParamHome>(),
};

/// issue 1197 — publish the backing's TOTAL size as a symbol whose storage size
/// IS the number, so a build script can recover it from the rlib without running
/// anything. `nros-sizes-build::extract_sizes` reads exactly this shape, the way
/// `nros-c` recovers `EXECUTOR_OPAQUE_U64S`.
///
/// **The total rather than the per-region units, and that is a decision.** The
/// units alone would be more robust — they do not vary with the executor knobs,
/// so a probe cache keyed by (target, features) is correct for them, and the
/// caller supplies `alloc` and the counts explicitly. But the backing is
/// `arena + tables`, and `ARENA_SIZE` is DERIVED in this crate's build script
/// from `MAX_CBS`, `RX_BUF_SIZE` and `ACTION_CLIENTS`. A consumer computing from
/// units would have to re-implement that derivation — a second implementation,
/// which is the whole thing this design refuses. So the consumer probes the one
/// number, and keys its probe directory by the executor env, because unlike the
/// units this DOES vary with it.
///
/// Behind a feature and OFF by default: it is `#[used]`, and a shipped image
/// should not carry a static that exists only to be measured. The probe enables
/// it for its own nested build, which is a separate compilation from the linked
/// one.
#[cfg(feature = "layout-size-markers")]
#[used]
#[unsafe(no_mangle)]
#[doc(hidden)]
pub static __NROS_LU_SZ_executor_backing: [u8;
    crate::executor::backing::EXECUTOR_BACKING_DEFAULT_U64S * 8] =
    [0u8; crate::executor::backing::EXECUTOR_BACKING_DEFAULT_U64S * 8];

const fn unit_of<T>() -> RegionUnit {
    RegionUnit {
        size: size_of::<T>(),
        align: align_of::<T>(),
    }
}

/// The counts this build was configured with, for `sizing`.
const fn counts_for(sizing: ExecutorSizing) -> RegionCounts {
    RegionCounts {
        cbs: sizing.cbs,
        sc: sizing.sc,
        nodes: sizing.nodes,
        arena: sizing.arena,
        remaps: MAX_REMAPS,
        violations: MAX_VIOLATIONS,
        alloc: cfg!(feature = "alloc"),
        params: sizing.params,
        param_home: param_homes(sizing),
    }
}

/// Issue 1812 — how many parameter-service homes a `sizing` carves: one exactly
/// when it carves a store. The services are what the store is FOR on an image
/// that declares parameters, so the two travel together, and an image whose
/// build knows of no store pays for neither (issue 1702's rule).
pub(crate) const fn param_homes(sizing: ExecutorSizing) -> usize {
    if sizing.params > 0 { 1 } else { 0 }
}

const fn compute_offsets(sizing: ExecutorSizing) -> FieldOffsets {
    compute_offsets_with(sizing, &NATIVE_UNITS)
}

/// Adapter over the shared arithmetic: same numbers, named the way `carve`
/// wants them. The placement itself is `nros_executor_layout::offsets` — one
/// implementation, so an external evaluation cannot drift from this one.
///
/// By reference: the unit table crossed clippy's 256-byte pass-by-value line
/// when phase-476 W0 added `slot_tag`.
const fn compute_offsets_with(sizing: ExecutorSizing, units: &RegionUnits) -> FieldOffsets {
    let o = nros_executor_layout::offsets(counts_for(sizing), *units);
    FieldOffsets {
        arena: o.arena,
        entries: o.entries,
        sched_contexts: o.sched_contexts,
        sched_context_bindings: o.sched_context_bindings,
        sporadic_states: o.sporadic_states,
        #[cfg(feature = "alloc")]
        sporadic_atomic_states: o.sporadic_atomic_states,
        remaps: o.remaps,
        nodes: o.nodes,
        extra_sessions: o.extra_sessions,
        extra_session_ids: o.extra_session_ids,
        node_sched_table: o.node_sched_table,
        dispatch_slots: o.dispatch_slots,
        component_slots: o.component_slots,
        active_groups: o.active_groups,
        group_sched_table: o.group_sched_table,
        monitor_violations: o.monitor_violations,
        alive_slots: o.alive_slots,
        slot_tags: o.slot_tags,
        params: o.params,
        param_home: o.param_home,
        size: o.size,
        align: o.align,
    }
}

/// Byte [`Layout`] of the backing, evaluated against a SUPPLIED unit table.
///
/// issue 1197 — the public half of the split. `executor_storage_layout` is this
/// with `NATIVE_UNITS`; an external consumer that has recovered the
/// units for another target (a build script probing an rlib, the way `nros-c`
/// recovers `EXECUTOR_OPAQUE_U64S`) gets the same arithmetic rather than a
/// second implementation of it.
///
/// The OFFSETS stay private: only `carve` needs them, and it runs in the crate
/// that owns the types. A consumer sizing a reservation needs the total.
pub const fn executor_storage_layout_with(sizing: ExecutorSizing, units: RegionUnits) -> Layout {
    let o = compute_offsets_with(sizing, &units);
    // SAFETY: as `executor_storage_layout` — `align` is a max of alignments and
    // `size` is rounded up to it.
    unsafe { Layout::from_size_align_unchecked(o.size, o.align) }
}

/// Byte [`Layout`] of the backing a `sizing`-sized executor needs.
/// Public + non-generic so the macro / FFI can size a raw backing.
pub const fn executor_storage_layout(sizing: ExecutorSizing) -> Layout {
    let o = compute_offsets(sizing);
    // SAFETY: `align` is a power of two (a `max` of `align_of` results) and `size`
    // is rounded up to it; both are non-zero.
    unsafe { Layout::from_size_align_unchecked(o.size, o.align) }
}

/// Number of `u64` words a backing must hold for a `sizing`-sized executor.
/// `u64` backing is 8-aligned, which covers every field (all `align_of ≤ 8`;
/// asserted in tests), so the entry never hand-aligns. The macro emits
/// `[MaybeUninit<u64>; executor_storage_u64_len(sizing)]`.
pub const fn executor_storage_u64_len(sizing: ExecutorSizing) -> usize {
    executor_storage_layout(sizing).size().div_ceil(8)
}

/// Per-entry executor sizing — the entity counts an [`Executor`](super::spin::Executor)
/// is built to hold. **Public + non-generic** (the "C/C++ is a thin wrapper"
/// principle): the entry / macro / FFI supplies these as plain `usize`s rather
/// than as type/const generics C can't name. Used to size + carve the backing.
///
/// `cbs` is capped at 64 by the executor's `u64` ready-set bitmask (asserted in
/// `carve`-time / `open_in`).
#[derive(Clone, Copy)]
pub struct ExecutorSizing {
    /// Callback-table slots (`entries`, the per-entry SC bindings, and the
    /// per-callback-group sched table). ≤ 64.
    pub cbs: usize,
    /// Scheduling-context slots (`sched_contexts`, the sporadic state tables
    /// and alive supervision's per-SC records).
    pub sc: usize,
    /// Bump-allocator arena size in bytes.
    pub arena: usize,
    /// phase-409 — Node slots. One worst-case extra session, extra-session id,
    /// node-sched binding, dispatch slot, component slot and callback-group
    /// filter entry per Node, so ONE count covers all seven tables (that is the
    /// upper bound each of them already assumed under `MAX_NODES`).
    pub nodes: usize,
    /// phase-382 W3' — parameter-store slots carved from the backing.
    ///
    /// The default is [`nros_params::IMPLIED_STORE_SLOTS`]: the store's full
    /// `MAX_PARAMETERS` when the build KNOWS the image builds one (the
    /// contract declares a parameter, the bringup declares `param_services`,
    /// or the launch seeds a `<param>`), and ZERO otherwise. Zero is not a
    /// degraded mode: an executor that carved no store and is asked for one
    /// allocates it from the heap exactly as before, with issue 1706's named
    /// refusal if the heap cannot hold it.
    ///
    /// Conditional rather than fixed, and that is a decision measured in
    /// phase-382's W3' notes: a fixed `MAX_PARAMETERS` region adds the whole
    /// store (280,832 B on armv7m at the default 32 slots) to every image's
    /// backing — Rust `EXECUTOR_BACKING`, every C/C++ `rclc_executor_t`, every
    /// tier slot — which is issue 1702's rejected `.bss` static, everywhere.
    pub params: usize,
}

impl ExecutorSizing {
    /// The build-time default (`MAX_CBS`/`MAX_SC`/`ARENA_SIZE`/`MAX_NODES`
    /// consts) — the backward-compatible size the `alloc` convenience
    /// constructors leak.
    pub const DEFAULT: Self = Self {
        cbs: crate::config::MAX_CBS,
        sc: crate::config::MAX_SC,
        arena: crate::config::ARENA_SIZE,
        nodes: crate::config::MAX_NODES,
        params: nros_params::IMPLIED_STORE_SLOTS,
    };

    /// `u64` words a backing must hold for this sizing (see
    /// [`executor_storage_u64_len`]).
    pub const fn u64_len(&self) -> usize {
        executor_storage_u64_len(*self)
    }

    /// phase-412 #4 — refuse, at COMPILE time, a sizing whose arena is below
    /// what this image's declared entities are modelled to need.
    ///
    /// For a caller that supplies its own `const` sizing for the image's ONE
    /// executor (`open_in` over a `static` sized with [`u64_len`](Self::u64_len)),
    /// so its arena is held to the same model the build-time default is:
    ///
    /// ```ignore
    /// const SIZING: nros::ExecutorSizing = nros::ExecutorSizing { .. };
    /// const _: () = SIZING.assert_covers_model("SIZING.arena");
    /// ```
    ///
    /// Opt-in, deliberately: an executor that holds a SUBSET of the image (one
    /// tier of a tiered boot) legitimately carries less than the whole model,
    /// and only its author knows which kind it is. See
    /// [`arena_oracle`](super::arena_oracle) for the arms and why each is or is
    /// not checked here.
    pub const fn assert_covers_model(&self, source: &'static str) {
        super::arena_oracle::assert_covers_model(self.arena, source)
    }
}

/// The exact `#[repr(C)]` byte layout the C/C++ FFI's inline executor buffer must
/// hold: an [`Executor`](super::spin::Executor)`<'static>` header immediately
/// followed by a default-sized ([`ExecutorSizing::DEFAULT`]) storage backing.
///
/// The FFI keeps the executor inline (heap-free — matching the Rust no-alloc
/// requirement) and carves its per-entry tables from the SAME buffer's
/// [`backing`](Self::backing) tail. Because that buffer is **pinned** — the C
/// caller allocates it, it is initialised in place, and it is only ever reached
/// through a stable `rclc_executor_t*` (never moved after init) — the resulting
/// self-borrow (the header's slices pointing into the same struct's tail) is
/// sound. The FFI probes `size_of` of THIS type (not bare `Executor`) to size
/// its `_opaque` array, and reinterprets `_opaque` as `*mut ExecutorInlineStorage`
/// (the executor stays at offset 0, so existing offset-0 accessors are unchanged).
///
/// phase-409 — moving the last nine tables into the backing moves bytes from
/// `exec` to `backing` and leaves this total roughly where it was; what changes
/// is the STACK, because the header is what `open_in` builds and returns by
/// value.
#[repr(C)]
pub struct ExecutorInlineStorage {
    /// The executor, written in place (offset 0) by `from_session_ptr_in`.
    pub exec: MaybeUninit<super::spin::Executor<'static>>,
    /// The carved backing the executor's slices borrow (the buffer's tail).
    pub backing: [MaybeUninit<u64>; ExecutorSizing::DEFAULT.u64_len()],
}

/// Carve an 8-aligned `u64` backing into the typed executor slices.
///
/// # Safety
/// - `backing.len() * 8` must be ≥ `executor_storage_layout(sizing).size()`.
/// - The returned slices alias `backing`; it must outlive them (the `'s` bound)
///   and not be otherwise accessed while they live.
///
/// The `Option`/binding tables are initialised here (`entries`/SC tables →
/// `None`, bindings → `SchedContextId(0)`), so the returned `&mut [T]` reference
/// validly-init memory. The [`CarvedVec`] tables are handed over empty and
/// UNINITIALISED — nothing reads past their fill cursor.
pub(crate) unsafe fn carve<'s>(
    backing: &'s mut [MaybeUninit<u64>],
    sizing: ExecutorSizing,
) -> ExecutorSlices<'s> {
    let ExecutorSizing {
        cbs,
        sc,
        arena,
        nodes: node_slots,
        params: param_slots,
    } = sizing;
    let o = compute_offsets(sizing);
    // Fail-loud on EVERY profile (not `debug_assert!`): embedded release builds
    // strip debug-assertions, and a backing that is too small is silent memory
    // corruption — the carved `entries`/`sched_contexts` tables run past the end
    // of `backing` into whatever .bss follows (e.g. a C carrier's `__nros_c_inst`),
    // leaving a NULL `drop_fn` that faults in `Executor::drop`. This is exactly
    // how a STALE config-header mirror (C buffer sized from an out-of-date
    // `NROS_*_STORAGE_SIZE`) manifested as a `jalr -> 0` on threadx-riscv64 (#131).
    // Panic here instead, at open, with the two sizes named.
    assert!(
        backing.len() * 8 >= o.size,
        "executor backing too small: {} bytes < {} required — the storage buffer \
         (NROS_*_STORAGE_SIZE) disagrees with the executor layout; rebuild clean so \
         the generated config header matches",
        backing.len() * 8,
        o.size
    );
    let base = backing.as_mut_ptr() as *mut u8;

    // One `CarvedVec` over `$n` slots at byte offset `$at`. No element writes —
    // the vector starts empty. Expanded inside the `unsafe` block below;
    // SAFETY there: `compute_offsets` placed `$n` `$ty`s at `$at`, aligned and
    // inside the asserted `o.size`, and each region is placed exactly once, so
    // the slices do not alias.
    macro_rules! carved {
        ($at:expr, $n:expr, $ty:ty) => {{
            let p = base.add($at) as *mut MaybeUninit<$ty>;
            CarvedVec::new(region_slice(p, $n))
        }};
    }

    unsafe {
        // arena — no init needed (MaybeUninit).
        let arena_s = region_slice(base.add(o.arena) as *mut MaybeUninit<u8>, arena);

        let entries_p = base.add(o.entries) as *mut Option<CallbackMeta>;
        let mut i = 0;
        while i < cbs {
            entries_p.add(i).write(None);
            i += 1;
        }
        let entries_s = region_slice(entries_p, cbs);

        let sc_p = base.add(o.sched_contexts) as *mut Option<SchedContext>;
        let mut i = 0;
        while i < sc {
            sc_p.add(i).write(None);
            i += 1;
        }
        let sched_contexts_s = region_slice(sc_p, sc);

        let bind_p = base.add(o.sched_context_bindings) as *mut SchedContextId;
        let mut i = 0;
        while i < cbs {
            bind_p.add(i).write(SchedContextId(0));
            i += 1;
        }
        let bindings_s = region_slice(bind_p, cbs);

        let sp_p = base.add(o.sporadic_states) as *mut Option<SporadicState>;
        let mut i = 0;
        while i < sc {
            sp_p.add(i).write(None);
            i += 1;
        }
        let sporadic_s = region_slice(sp_p, sc);

        #[cfg(feature = "alloc")]
        let atomic_s = {
            let ap = base.add(o.sporadic_atomic_states) as *mut Option<SporadicAtomic>;
            let mut i = 0;
            while i < sc {
                ap.add(i).write(None);
                i += 1;
            }
            region_slice(ap, sc)
        };

        let remaps_p = base.add(o.remaps) as *mut Option<RemapRule>;
        let mut i = 0;
        while i < MAX_REMAPS {
            remaps_p.add(i).write(None);
            i += 1;
        }
        let remaps_s = region_slice(remaps_p, MAX_REMAPS);

        let alive_p = base.add(o.alive_slots) as *mut AliveSlot;
        let mut i = 0;
        while i < sc {
            alive_p.add(i).write(AliveSlot::default());
            i += 1;
        }
        let alive_s = region_slice(alive_p, sc);

        let tags_p = base.add(o.slot_tags) as *mut SlotTag;
        let mut i = 0;
        while i < cbs {
            tags_p.add(i).write(SlotTag::default());
            i += 1;
        }
        let tags_s = region_slice(tags_p, cbs);

        // phase-382 W3' — no init: the slots are `MaybeUninit` until the
        // first declaration initialises them through `ParameterTable::init_in`.
        let params_s = region_slice(
            base.add(o.params) as *mut MaybeUninit<nros_params::ParameterSlot>,
            param_slots,
        );
        // issue 1812 — no init either: `ParamHome::init_in` builds it in place.
        let home_s = region_slice(
            base.add(o.param_home) as *mut MaybeUninit<ParamHome>,
            param_homes(sizing),
        );

        ExecutorSlices {
            arena: arena_s,
            entries: entries_s,
            sched_contexts: sched_contexts_s,
            sched_context_bindings: bindings_s,
            sporadic_states: sporadic_s,
            #[cfg(feature = "alloc")]
            sporadic_atomic_states: atomic_s,
            remaps: remaps_s,
            nodes: carved!(o.nodes, node_slots, NodeRecord),
            extra_sessions: carved!(o.extra_sessions, node_slots, ConcreteSession),
            extra_session_ids: carved!(o.extra_session_ids, node_slots, ExtraSessionId),
            node_sched_table: carved!(o.node_sched_table, node_slots, NodeSchedEntry),
            dispatch_slots: carved!(o.dispatch_slots, node_slots, DispatchSlot),
            component_slots: carved!(o.component_slots, node_slots, ComponentSlot),
            active_groups: carved!(o.active_groups, node_slots, ActiveGroup),
            group_sched_table: carved!(o.group_sched_table, cbs, GroupSchedEntry),
            monitor_violations: carved!(o.monitor_violations, MAX_VIOLATIONS, Violation),
            alive_slots: alive_s,
            slot_tags: tags_s,
            params: params_s,
            param_home: home_s,
        }
    }
}

/// One carved region as a slice — the ONLY way `carve` builds one (issue 1771).
///
/// `slice::from_raw_parts_mut` requires an ALIGNED, non-null pointer even for
/// a zero-length slice, and an empty region's offset is not always aligned:
/// `nros_executor_layout::offsets` deliberately leaves `off` where it is for a
/// region with no slots (the parameter store in an image without one, the
/// atomic sporadic states without `alloc`), so the total does not grow by
/// padding nothing uses. On thumbv7m that offset is misaligned for
/// `ParameterSlot`, and the debug precondition check panicked at boot. An
/// empty region needs no address at all, so it gets a dangling one.
///
/// # Safety
/// For `n > 0`, `p` points at `n` properly aligned `T`s inside the backing
/// that no other live slice covers.
unsafe fn region_slice<'s, T>(p: *mut T, n: usize) -> &'s mut [T] {
    if n == 0 {
        return &mut [];
    }
    // SAFETY: the caller's contract, for a non-empty region.
    unsafe { core::slice::from_raw_parts_mut(p, n) }
}

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

    /// issue 1197 — the arithmetic must actually READ `units`, not quietly keep
    /// calling `size_of::<T>()` behind a parameter it ignores.
    ///
    /// A parameter that is accepted and unused is exactly how a "data-driven"
    /// refactor passes its own tests while delivering nothing: `NATIVE` would
    /// still be right, every existing assertion would still hold, and the
    /// external consumer this exists for would get the HOST's layout back.
    /// So this feeds a table that could not have come from this compiler and
    /// checks the answer moves by the amount that table implies.
    #[test]
    fn the_placement_reads_the_unit_table_it_is_given() {
        let sizing = ExecutorSizing {
            cbs: 1,
            sc: 0,
            arena: 0,
            nodes: 0,
            params: 0,
        };
        let native = executor_storage_layout_with(sizing, NATIVE_UNITS);

        // One region is scaled by `cbs`: `callback_meta`. Grow ONLY it, by a
        // multiple of its own alignment so no padding shifts, and the total must
        // grow by exactly one element's worth.
        let mut fatter = NATIVE_UNITS;
        let grown_by = fatter.callback_meta.align * 4;
        fatter.callback_meta.size += grown_by;
        let widened = executor_storage_layout_with(sizing, fatter);

        assert_eq!(
            widened.size(),
            native.size() + grown_by,
            "growing one cbs-scaled unit by {grown_by} must grow the backing by \
             the same, or the table is being ignored"
        );

        // And a table of ZEROES must collapse the tables entirely, leaving only
        // the arena. This is the direction that catches a `size_of` still being
        // read for some region the parameter was threaded past.
        let zeroed = RegionUnits {
            callback_meta: RegionUnit { size: 0, align: 1 },
            sched_context: RegionUnit { size: 0, align: 1 },
            sched_context_id: RegionUnit { size: 0, align: 1 },
            sporadic_state: RegionUnit { size: 0, align: 1 },
            sporadic_atomic: RegionUnit { size: 0, align: 1 },
            remap_rule: RegionUnit { size: 0, align: 1 },
            node_record: RegionUnit { size: 0, align: 1 },
            concrete_session: RegionUnit { size: 0, align: 1 },
            extra_session_id: RegionUnit { size: 0, align: 1 },
            node_sched_entry: RegionUnit { size: 0, align: 1 },
            dispatch_slot: RegionUnit { size: 0, align: 1 },
            component_slot: RegionUnit { size: 0, align: 1 },
            group_name: RegionUnit { size: 0, align: 1 },
            group_sched_entry: RegionUnit { size: 0, align: 1 },
            violation: RegionUnit { size: 0, align: 1 },
            alive_slot: RegionUnit { size: 0, align: 1 },
            slot_tag: RegionUnit { size: 0, align: 1 },
            parameter_slot: RegionUnit { size: 0, align: 1 },
            param_home: RegionUnit { size: 0, align: 1 },
        };
        let arena_only = executor_storage_layout_with(
            ExecutorSizing {
                cbs: CBS,
                sc: SC,
                arena: 4096,
                nodes: 4,
                params: 3,
            },
            zeroed,
        );
        assert_eq!(
            arena_only.size(),
            4096,
            "with every unit zero-sized the backing is the arena and nothing else"
        );
    }

    const CBS: usize = crate::config::MAX_CBS;
    const SC: usize = crate::config::MAX_SC;
    const ARENA: usize = crate::config::ARENA_SIZE;
    const NODES: usize = crate::config::MAX_NODES;
    const DEFAULT: ExecutorSizing = ExecutorSizing::DEFAULT;
    /// phase-382 W3' — a store carved in the layout tests whatever this build
    /// implies (`DEFAULT.params` is 0 in a unit-test build: nothing declares a
    /// parameter), so the region is placed and checked on every run.
    const PARAMS: usize = 3;
    const WITH_STORE: ExecutorSizing = ExecutorSizing {
        params: PARAMS,
        ..DEFAULT
    };
    /// The build's own default. Its `params` is `nros_params::IMPLIED_STORE_SLOTS`.
    const DEFAULT_PARAMS: usize = DEFAULT.params;

    #[test]
    fn layout_matches_typed_repr_c() {
        // The manual const-fn layout must equal the compiler's `#[repr(C)]` layout
        // of the typed storage — proof the carve offsets are the real field offsets.
        let got = executor_storage_layout(DEFAULT);
        let want = Layout::new::<
            ExecutorStorage<CBS, SC, ARENA, NODES, DEFAULT_PARAMS, { param_homes(DEFAULT) }>,
        >();
        assert_eq!(got.size(), want.size(), "size");
        assert_eq!(got.align(), want.align(), "align");
        // phase-382 W3' — and with a store carved, which is the layout every
        // image that declares a parameter links.
        let got = executor_storage_layout(WITH_STORE);
        let want = Layout::new::<ExecutorStorage<CBS, SC, ARENA, NODES, PARAMS, 1>>();
        assert_eq!(got.size(), want.size(), "size with a carved store");
        assert_eq!(got.align(), want.align(), "align with a carved store");
    }

    /// phase-382 W3' — the negative control for the CONDITIONAL region: zero
    /// store slots must leave the backing byte-for-byte what it was before the
    /// region existed. `nros_executor_layout::offsets` skips the placement
    /// entirely at zero (an aligned-up `off` would be padding an image with no
    /// store paid for nothing), so the total is the one the seventeen older
    /// regions produce on their own — computed here by zeroing the unit, which
    /// is the layout the region cannot reach.
    #[test]
    fn a_backing_that_carves_no_store_does_not_grow() {
        let none = ExecutorSizing {
            params: 0,
            ..DEFAULT
        };
        let mut no_unit = NATIVE_UNITS;
        no_unit.parameter_slot = RegionUnit { size: 0, align: 1 };
        no_unit.param_home = RegionUnit { size: 0, align: 1 };
        assert_eq!(
            executor_storage_layout(none).size(),
            executor_storage_layout_with(WITH_STORE, no_unit).size(),
            "a backing with no store slots must cost exactly the backing without the region"
        );
        assert_eq!(
            executor_storage_layout(none).align(),
            executor_storage_layout_with(WITH_STORE, no_unit).align(),
        );
        // And a store costs at least its slots, charged to the backing.
        let grown =
            executor_storage_layout(WITH_STORE).size() - executor_storage_layout(none).size();
        assert!(
            grown >= PARAMS * size_of::<nros_params::ParameterSlot>(),
            "{PARAMS} store slots cost {grown} B, less than {PARAMS} x {} B",
            size_of::<nros_params::ParameterSlot>()
        );
        // The layout's slot IS the store's slot, so a carved table is exactly
        // a `ParameterStorage<PARAMS>`'s worth of slots.
        assert_eq!(
            PARAMS * size_of::<nros_params::ParameterSlot>(),
            size_of::<nros_params::ParameterStorage<PARAMS>>()
        );
    }

    /// phase-409 — and the FIELD offsets, one by one. The size/align check above
    /// is the one phase-271 shipped, and it does not distinguish a REORDER that
    /// happens to pad the same: with sixteen regions instead of seven, "the
    /// totals agree" stopped being adequate evidence that `carve` hands out the
    /// region it names. A mismatch here is `nodes` being handed
    /// `extra_sessions`' memory, which is not a size bug and no total would show.
    #[test]
    fn every_carved_region_starts_where_repr_c_puts_it() {
        type Ref = ExecutorStorage<CBS, SC, ARENA, NODES, PARAMS, 1>;
        let o = compute_offsets(WITH_STORE);
        macro_rules! same {
            ($f:ident) => {
                assert_eq!(
                    o.$f,
                    core::mem::offset_of!(Ref, $f),
                    concat!("offset of `", stringify!($f), "`")
                );
            };
        }
        same!(arena);
        same!(entries);
        same!(sched_contexts);
        same!(sched_context_bindings);
        same!(sporadic_states);
        #[cfg(feature = "alloc")]
        same!(sporadic_atomic_states);
        same!(remaps);
        same!(nodes);
        same!(extra_sessions);
        same!(extra_session_ids);
        same!(node_sched_table);
        same!(dispatch_slots);
        same!(component_slots);
        same!(active_groups);
        same!(group_sched_table);
        same!(monitor_violations);
        same!(alive_slots);
        same!(slot_tags);
        // phase-382 W3' — the store, last.
        same!(params);
        // issue 1812 — and the services' home after it.
        same!(param_home);
    }

    #[test]
    fn u64_backing_covers_all_field_aligns() {
        assert!(align_of::<Option<CallbackMeta>>() <= 8);
        assert!(align_of::<Option<SchedContext>>() <= 8);
        assert!(align_of::<SchedContextId>() <= 8);
        assert!(align_of::<Option<SporadicState>>() <= 8);
        // phase-409 — the nine that moved. A type whose alignment exceeds 8
        // would make the `u64` backing insufficient for the whole carve, not
        // just for its own table.
        assert!(align_of::<NodeRecord>() <= 8);
        assert!(align_of::<ConcreteSession>() <= 8);
        assert!(align_of::<ExtraSessionId>() <= 8);
        assert!(align_of::<NodeSchedEntry>() <= 8);
        assert!(align_of::<DispatchSlot>() <= 8);
        assert!(align_of::<ComponentSlot>() <= 8);
        assert!(align_of::<ActiveGroup>() <= 8);
        assert!(align_of::<AliveSlot>() <= 8);
        assert!(align_of::<GroupSchedEntry>() <= 8);
        assert!(align_of::<Violation>() <= 8);
        // phase-382 W3' — the store's slot.
        assert!(align_of::<nros_params::ParameterSlot>() <= 8);
        assert!(executor_storage_layout(DEFAULT).align() <= 8);
        assert!(executor_storage_layout(WITH_STORE).align() <= 8);
    }

    /// phase-409 (issue 0961) — every knob-scaled table's per-slot cost is
    /// charged to the BACKING, which is where the caller put it, and not to the
    /// `Executor` value, which is what `open_in` builds on the stack and
    /// returns by value.
    ///
    /// Deltas rather than absolute sizes, the shape
    /// `the_default_subscription_buffer_is_unchanged` uses: a total says
    /// nothing about which knob moved it, while the difference between two
    /// sizings isolates exactly one knob's per-slot width.
    #[test]
    fn every_knob_scaled_table_is_charged_to_the_backing() {
        let base = executor_storage_layout(DEFAULT).size();

        let one_more_node = executor_storage_layout(ExecutorSizing {
            nodes: DEFAULT.nodes + 1,
            ..DEFAULT
        })
        .size();
        let per_node = size_of::<NodeRecord>()
            + size_of::<ConcreteSession>()
            + size_of::<ExtraSessionId>()
            + size_of::<NodeSchedEntry>()
            + size_of::<DispatchSlot>()
            + size_of::<ComponentSlot>()
            + size_of::<ActiveGroup>();
        assert!(
            one_more_node - base >= per_node,
            "one more Node slot must cost its seven tables ({per_node} B) in the \
             backing; it cost {}",
            one_more_node - base
        );

        // `arena` is its own field, so `..DEFAULT` holds it while `cbs` moves —
        // which isolates the callback-indexed tables. `group_sched_table` is the
        // one that coupled `NROS_EXECUTOR_MAX_CBS` to the main thread's stack.
        let one_more_cb = executor_storage_layout(ExecutorSizing {
            cbs: DEFAULT.cbs + 1,
            ..DEFAULT
        })
        .size();
        assert!(
            one_more_cb - base >= size_of::<GroupSchedEntry>(),
            "one more callback slot must cost a `group_sched_table` entry \
             ({} B) in the backing; it cost {}",
            size_of::<GroupSchedEntry>(),
            one_more_cb - base
        );
    }

    /// The other half of the same claim, and the one issue 0961 is about: the
    /// VALUE does not move.
    ///
    /// A CEILING rather than an equality, because the header's exact size is a
    /// target + feature detail — measured 1016 B on the `std` lane and 2048 B
    /// under `--all-features`, and the difference is almost entirely the primary
    /// session (`SessionStore` is 16 B over `MockSession`, 536 B over
    /// `CffiSession`) plus `scheduler-os-priority`'s worker pool. Both of those
    /// are allowed for BY NAME below, so what is left is a tight budget on the
    /// header proper.
    ///
    /// It is a ceiling on the same number at every knob value, which is the
    /// property under test: 1016 B at BOTH the shipped defaults and the island's
    /// `MAX_CBS=36` / `MAX_NODES=6`. Before this phase it was 5072 B and
    /// 12768 B respectively.
    ///
    /// If this fires for a field you MEANT to add, the fix is almost always to
    /// carve it rather than to raise the ceiling: `Executor::open_in` builds
    /// this value on the stack and returns it by value, and `nros_cpp_init`
    /// holds the returned value, so every byte is charged to two frames of every
    /// image's boot path.
    #[test]
    fn the_executor_value_does_not_scale_with_the_knobs() {
        let value = size_of::<super::super::spin::Executor<'static>>();
        // Two things in the header are legitimately large and are NOT scaled by
        // `MAX_CBS` / `MAX_NODES`, so they get named allowances rather than a
        // looser ceiling for every build:
        //   * the primary session, held by value (that is what owning a session
        //     means), whose size is the backend's, not a knob's;
        //   * `scheduler-os-priority`'s worker pool, a pair of `FnvIndexMap`s
        //     sized by `MAX_PRIORITY_LEVELS` — an opt-in capability.
        //   * phase-436 W6's wake-source table, a fixed `MAX_WAKE_SOURCES`
        //     array of two-pointer slots. It is exempted for the same reason
        //     the two above are — it does not scale with `MAX_CBS` or
        //     `MAX_NODES` — and it is named rather than folded into the base
        //     so that raising `MAX_WAKE_SOURCES` shows up as a cost here
        //     instead of eating another feature's headroom. The rest of
        //     phase-436's header fields (the park bookkeeping scalars) are
        //     NOT exempted and fit inside the 1280 as they should.
        //   * phase-462 W2's age-monitor state table, an inline
        //     `MAX_AGE_MONITORS` array, named for the same reason as the
        //     wake-source table: `AgeState` grew from one byte to eight when
        //     the silence rule gained its lease, and that 56 B belongs on this
        //     line where the next field added to it is visible, not silently
        //     inside the 1280. Its sibling `[MonitorState; MAX_MONITORS]`
        //     predates the allowance idiom and its first 8 rows stay folded
        //     into the base; naming it whole would mean re-tuning the base
        //     literal against a size that is target-dependent.
        //   * phase-496 W1 made both tables KNOBS (`NROS_EXECUTOR_MAX_MONITORS`
        //     / `..._AGE_MONITORS`, derived from the contract's row counts).
        //     They stay inline on purpose -- the spin loop indexes them in
        //     parallel with a `&'static` spec table -- so they are exempt the
        //     same way, by NAMED allowance: the age table whole (above), the
        //     rate table by its rows past the 8 the base already absorbed. A
        //     contract with 14 rate rows grows this value by exactly those six
        //     rows and nothing else can hide inside that allowance.
        //   * issue 1496's released-region table was a FIXED 8-entry
        //     `heapless::Vec` named here; issue 1667 replaced it with an
        //     intrusive free list whose nodes live in the freed arena bytes, so
        //     what remains in this value is one `usize` head, named below.
        //   * phase-474 I1/I2's `ViolationCounts`: the violation ring's total,
        //     dropped and pre-arm counters and the monitors' arming state, nine
        //     scalars that scale with no knob. Named so the next field added to
        //     them shows up here rather than eating another feature's headroom.
        //   * phase-474 I7's `ReportQueue`: the verdicts waiting for the
        //     `/diagnostics` sink (a fixed `REPORT_QUEUE` of four) and what the
        //     hand-over cost. Scales with no knob; named for the same reason.
        //   * phase-476 W0's `slot_tags`: the TABLE is carved (it scales with
        //     `MAX_CBS` and lives in the backing); what sits in this value is
        //     one slice reference, which scales with nothing.
        //   * phase-483 W3's `component_frame`: one optional pointer to the
        //     component-registration frame `nros::NodeContext` installs while a
        //     component's `register` runs. Scales with nothing.
        //   * phase-474 I11's `ReleaseGrid`: the spin loop's release grid (its
        //     period, next release and skipped count). Scales with nothing.
        //   * phase-436 A2b/A2c: whether a declared cadence is wait-paced (a
        //     `bool`) and the count of late wakes beyond the granule (a `u32`).
        //     Two scalars that scale with nothing, named so the next field added
        //     beside them shows up here.
        //   * phase-462 W3b's `hazard_table`: one `&'static` slice reference to
        //     the baked hazard table, whose per-hazard state lives in the
        //     table's own `static` cells. Scales with nothing.
        #[allow(unused_mut)]
        let mut ceiling =
            1280 + size_of::<super::super::spin::SessionStore>()
                + size_of::<super::super::monitor::ViolationCounts>()
                + size_of::<super::super::monitor::ReportQueue>()
                + size_of::<&mut [super::super::types::SlotTag]>()
                + size_of::<usize>()
                + size_of::<Option<core::ptr::NonNull<()>>>()
                + size_of::<super::super::spin::ReleaseGrid>()
                + size_of::<bool>()
                + size_of::<u32>()
                + size_of::<&'static [super::super::monitor::HazardSpec]>()
                + size_of::<
                    [Option<super::super::spin::WakeSourceSlot>;
                        super::super::spin::MAX_WAKE_SOURCES],
                >()
                + size_of::<
                    [super::super::monitor::AgeState; super::super::monitor::MAX_AGE_MONITORS],
                >()
                + size_of::<
                    [super::super::monitor::MonitorState; super::super::monitor::MAX_MONITORS],
                >()
                .saturating_sub(size_of::<[super::super::monitor::MonitorState; 8]>());
        #[cfg(all(
            feature = "alloc",
            feature = "rmw-cffi",
            feature = "scheduler-os-priority"
        ))]
        {
            ceiling += size_of::<super::super::os_priority::OsPriorityPool>();
        }
        // phase-382 W3' -- the parameter store's TABLE is carved (it scales
        // with `MAX_PARAMETERS` and lives in the backing); this value holds one
        // slice reference to it, which scales with nothing.
        #[cfg(feature = "param-store")]
        {
            ceiling += size_of::<&mut [MaybeUninit<nros_params::ParameterSlot>]>();
            // issue 1812 -- and one slice reference to the services' home,
            // which is carved for the same reason, plus the word that says
            // whether the state is carved or (with `alloc`) boxed. Neither
            // scales with a knob.
            ceiling += size_of::<&mut [MaybeUninit<ParamHome>]>();
            ceiling += size_of::<
                Option<
                    crate::param_store::Placed<'static, crate::param_store::ParamState<'static>>,
                >,
            >()
            .saturating_sub(size_of::<usize>());
        }
        // phase-425 W3b / phase-430 W1 -- `use_sim_time`'s state: the `/clock`
        // handle, the requested and stated flags, and the silence watch. None
        // scales with a knob. They sat unnamed inside the 1280 until a build
        // that also carried `param-services` and `lifecycle-services` went
        // 4 B over it, so they are named here like the rest.
        #[cfg(feature = "sim-time")]
        {
            ceiling += size_of::<Option<super::super::types::HandleId>>()
                + 2 * size_of::<bool>()
                + size_of::<crate::time_source::SilenceWatch>();
        }
        // `lifecycle-services`' runtime state is BOXED; this value holds one
        // optional pointer to it, which scales with nothing.
        #[cfg(feature = "lifecycle-services")]
        {
            ceiling += size_of::<
                Option<alloc::boxed::Box<crate::lifecycle_services::LifecycleRuntimeState>>,
            >();
        }
        assert!(
            value <= ceiling,
            "`Executor` is {value} B at MAX_CBS={CBS} / MAX_NODES={NODES}, over \
             the {ceiling} B this value is budgeted; a table that scales with a \
             knob has come back inline (issue 0961)."
        );
    }

    /// issue 1771 — an empty region at a MISALIGNED offset is legal.
    ///
    /// The layout leaves an empty region's offset unaligned (no padding for
    /// nothing), and `carve` used to hand that pointer to
    /// `slice::from_raw_parts_mut`, whose debug precondition check aborts the
    /// image — on thumbv7m, where the offset is not a multiple of
    /// `ParameterSlot`'s alignment. x86_64 happened to align, so carve's own
    /// tests could not see it; this asks the helper at an offset that is
    /// misaligned on every target. Passing `p` straight to
    /// `from_raw_parts_mut` here aborts the test process (not catchable).
    #[test]
    fn an_empty_region_at_a_misaligned_offset_carves_to_an_empty_slice() {
        assert!(align_of::<nros_params::ParameterSlot>() > 1, "the premise");
        let mut backing = [0u64; 4];
        let p = (backing.as_mut_ptr() as *mut u8).wrapping_add(1)
            as *mut MaybeUninit<nros_params::ParameterSlot>;
        assert!(!p.is_aligned(), "the premise: the offset is misaligned");
        let s = unsafe { region_slice(p, 0) };
        assert!(s.is_empty());
        assert!(s.as_ptr().is_aligned());
    }

    /// issue 1771 — `carve` itself, over layouts whose empty parameter region
    /// lands misaligned.
    ///
    /// Which knob values misalign `o.params` depends on every region before it,
    /// so a fixed config proves nothing on the next knob move: the mps2 talker
    /// panicked in one build and booted in another of the same leaf. Sweep the
    /// callback count and require that the sweep REACHES a misaligned offset
    /// (else this test has stopped asking the question), then carve each one.
    /// With the slice built straight from the pointer, the first misaligned
    /// case aborts the test process at the precondition check.
    #[cfg(feature = "alloc")]
    #[test]
    fn carve_survives_an_empty_parameter_region_at_any_alignment() {
        let align = align_of::<nros_params::ParameterSlot>();
        let mut misaligned = 0;
        for cbs in 1..=16 {
            let sizing = ExecutorSizing {
                cbs,
                sc: 1,
                arena: 1,
                nodes: 1,
                params: 0,
            };
            if !compute_offsets(sizing).params.is_multiple_of(align) {
                misaligned += 1;
            }
            let mut backing = alloc::vec![
                const { MaybeUninit::<u64>::uninit() };
                executor_storage_u64_len(sizing)
            ]
            .into_boxed_slice();
            let s = unsafe { carve(&mut backing, sizing) };
            assert!(s.params.is_empty());
            assert_eq!(s.entries.len(), cbs);
        }
        assert!(
            misaligned > 0,
            "no swept layout leaves the empty parameter region misaligned for \
             ParameterSlot (align {align}) — widen the sweep, or this test no \
             longer covers issue 1771"
        );
    }

    // phase-361 W8.e / issue 0594 — this test heap-allocates its backing array,
    // so it needs `alloc`. It compiled under `--no-default-features` only
    // because feature unification from another workspace member happened to
    // turn `nros-node/alloc` on; nothing does that now.
    #[cfg(feature = "alloc")]
    #[test]
    fn carve_yields_right_lengths_and_inits() {
        // Heap-allocate: the default test config (MAX_CBS/MAX_SC/ARENA_SIZE from
        // build.rs) makes this backing array tens of KB, well past
        // `clippy::large_stack_arrays`'s threshold — and the size here is
        // incidental (mirrors production config), not the point under test, so
        // boxing is the right fix rather than an allow.
        let mut backing =
            alloc::vec![const { MaybeUninit::<u64>::uninit() }; executor_storage_u64_len(DEFAULT)]
                .into_boxed_slice();
        let s = unsafe { carve(&mut backing, DEFAULT) };
        assert_eq!(s.arena.len(), ARENA);
        assert_eq!(s.entries.len(), CBS);
        assert_eq!(s.sched_contexts.len(), SC);
        assert_eq!(s.sched_context_bindings.len(), CBS);
        assert_eq!(s.sporadic_states.len(), SC);
        assert!(s.entries.iter().all(|e| e.is_none()));
        assert!(s.sched_context_bindings.iter().all(|b| b.0 == 0));
        // phase-409 — the CarvedVecs come back empty at their carved capacity.
        assert_eq!(s.nodes.capacity(), NODES);
        assert_eq!(s.extra_sessions.capacity(), NODES);
        assert_eq!(s.extra_session_ids.capacity(), NODES);
        assert_eq!(s.node_sched_table.capacity(), NODES);
        assert_eq!(s.dispatch_slots.capacity(), NODES);
        assert_eq!(s.component_slots.capacity(), NODES);
        assert_eq!(s.active_groups.capacity(), NODES);
        assert_eq!(s.group_sched_table.capacity(), CBS);
        assert_eq!(s.monitor_violations.capacity(), MAX_VIOLATIONS);
        // Alive supervision: one zeroed record per SC, carved rather than inline.
        assert_eq!(s.alive_slots.len(), SC);
        assert!(
            s.alive_slots
                .iter()
                .all(|a| a.dispatches == 0 && !a.state.opened)
        );
        assert_eq!(s.nodes.len(), 0);
        assert_eq!(s.group_sched_table.len(), 0);
        // phase-382 W3' — the store region, at this build's implied count.
        assert_eq!(s.params.len(), DEFAULT.params);
        // issue 1812 — and the services' home, present exactly with a store.
        assert_eq!(s.param_home.len(), param_homes(DEFAULT));
    }

    /// phase-382 W3' — carve a store and USE it, with no allocator anywhere.
    ///
    /// Outside the `alloc` gate on purpose (phase-382's trap): the point of
    /// carving is a store an image without a heap can hold, and
    /// `carve_yields_right_lengths_and_inits` above needs `alloc` only for
    /// its own default-sized backing. The backing here is a STATIC sized for a
    /// minimal executor plus the store, so nothing in this test allocates.
    #[test]
    fn a_carved_store_is_usable_without_an_allocator() {
        const TINY: ExecutorSizing = ExecutorSizing {
            cbs: 1,
            sc: 1,
            arena: 64,
            nodes: 1,
            params: PARAMS,
        };
        const WORDS: usize = executor_storage_u64_len(TINY);
        static mut BACKING: [MaybeUninit<u64>; WORDS] = [MaybeUninit::uninit(); WORDS];
        // SAFETY: this test is the only reader of `BACKING`, and it takes the
        // one reference once.
        // The raw pointer is bound first, as in `backing::take`: clippy reads
        // `&mut *(&raw mut X)` as `deref_addrof`, and its rewrite is the
        // `static_mut_refs` hazard.
        let ptr = &raw mut BACKING;
        let backing: &'static mut [MaybeUninit<u64>; WORDS] = unsafe { &mut *ptr };
        // SAFETY: `backing` is exactly `executor_storage_u64_len(TINY)` words.
        let s = unsafe { carve(backing, TINY) };
        assert_eq!(s.params.len(), PARAMS, "the store's slots are carved");
        assert_eq!(s.param_home.len(), 1, "and the services' home with them");
        let table = nros_params::ParameterTable::init_in(s.params);
        assert_eq!(table.capacity(), PARAMS);
        assert_eq!(table.occupied(), 0, "carved slots start empty");
        let mut server = nros_params::ParameterServer::new_in(table);
        let key = nros_params::NodeKey::PRIMARY;
        for i in 0..PARAMS {
            let mut name = heapless::String::<8>::new();
            let _ = core::fmt::write(&mut name, format_args!("p{i}"));
            assert!(server.declare(key, &name, nros_params::ParameterValue::Integer(i as i64)));
        }
        assert!(
            !server.declare(key, "over", nros_params::ParameterValue::Bool(true)),
            "capacity is the carved length"
        );
        assert_eq!(server.get(key, "p1").and_then(|v| v.as_integer()), Some(1));
    }

    #[test]
    fn carved_vec_pushes_in_order_and_refuses_when_full() {
        let mut slots = [const { MaybeUninit::<u32>::uninit() }; 3];
        let mut v = CarvedVec::new(&mut slots);
        assert_eq!(v.capacity(), 3);
        assert!(v.push(10).is_ok());
        assert!(v.push(20).is_ok());
        assert!(v.push(30).is_ok());
        // Order is load-bearing: `NodeId` IS an index into `nodes`.
        assert_eq!(v.as_slice(), &[10, 20, 30]);
        // Full is a REFUSAL that hands the value back, like `heapless::Vec`.
        assert_eq!(v.push(40), Err(40));
        v.clear();
        assert!(v.is_empty());
        assert!(v.push(50).is_ok());
        assert_eq!(v.as_slice(), &[50]);
    }

    /// phase-474 I1 -- `pop_front` takes the OLDEST and keeps push order, which
    /// is what lets the violation ring evict its oldest entry when full.
    #[test]
    fn carved_vec_pop_front_keeps_order() {
        let mut slots = [const { MaybeUninit::<u32>::uninit() }; 3];
        let mut v = CarvedVec::new(&mut slots);
        assert_eq!(v.pop_front(), None);
        for x in [1, 2, 3] {
            assert!(v.push(x).is_ok());
        }
        assert_eq!(v.pop_front(), Some(1));
        assert!(v.push(4).is_ok());
        assert_eq!(v.as_slice(), &[2, 3, 4]);
        assert_eq!(v.pop_front(), Some(2));
        assert_eq!(v.pop_front(), Some(3));
        assert_eq!(v.pop_front(), Some(4));
        assert!(v.is_empty());
    }

    /// The elements live in the CALLER's backing, so nothing drops them unless
    /// the vector does — and `extra_sessions` holds RMW sessions. Without this
    /// a bridge executor would leak every extra session it opened.
    #[test]
    fn carved_vec_drops_its_elements() {
        use core::sync::atomic::{AtomicUsize, Ordering};
        static DROPS: AtomicUsize = AtomicUsize::new(0);
        struct Counted;
        impl Drop for Counted {
            fn drop(&mut self) {
                DROPS.fetch_add(1, Ordering::SeqCst);
            }
        }

        let mut slots = [const { MaybeUninit::<Counted>::uninit() }; 4];
        {
            let mut v = CarvedVec::new(&mut slots);
            assert!(v.push(Counted).is_ok());
            assert!(v.push(Counted).is_ok());
        }
        assert_eq!(
            DROPS.load(Ordering::SeqCst),
            2,
            "both pushed elements dropped — and only the pushed ones, not the \
             uninitialised tail"
        );
    }
}