nros_node/executor/

sched_context.rs

//! Phase 110.B — `SchedContext` API + supporting types.
//!
//! A `SchedContext` is a first-class scheduling capability. Multiple
//! callbacks share one SC; one OS priority slot per Executor regardless
//! of callback count. Inspired by seL4 MCS (Mixed-Criticality
//! Scheduling).
//!
//! 110.B.a (this commit) lands the type surface + `EdfReadySet`. The
//! Executor builder methods (`create_sched_context`,
//! `register_subscription_in`, ...) and the cbindgen / C / C++ wrappers
//! land in 110.B.b once the const-generic `Executor<MAX_HANDLES,
//! MAX_SC>` reshape is sorted.

use core::num::NonZeroU32;

/// Optional time field with a sentinel `0` for "absent".
///
/// Phase 110.B keeps a stable `#[repr(transparent)]` u32 layout so
/// cbindgen emits plain `uint32_t` for C consumers — `Option<NonZeroU32>`
/// loses its niche optimization the moment a `#[repr(C)]` struct
/// embeds it. Rust callers see the ergonomic
/// [`get`](OptUs::get)-returning-`Option<NonZeroU32>` getter.
///
/// Sentinel `0` is physically meaningful for every time field on
/// [`SchedContext`]: 0-period would mean infinite frequency, 0-budget
/// means unbounded, 0-deadline means no deadline.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[repr(transparent)]
pub struct OptUs(u32);

impl OptUs {
    pub const NONE: Self = Self(0);

    pub const fn from_us(us: u32) -> Self {
        Self(us)
    }

    pub const fn from_nz(nz: NonZeroU32) -> Self {
        Self(nz.get())
    }

    /// Returns the inner value or `None` when the sentinel is set.
    pub const fn get(self) -> Option<NonZeroU32> {
        NonZeroU32::new(self.0)
    }

    pub const fn is_some(self) -> bool {
        self.0 != 0
    }

    pub const fn raw(self) -> u32 {
        self.0
    }
}

/// Scheduling class — picks the runtime queue + selection policy for
/// the contained callbacks.
///
/// Phase 110.A only exercises `Fifo`; `Edf` lands with the
/// `EdfReadySet` plumb-up in 110.B.b; `Sporadic` is post-v1 (110.E);
/// time-triggered windows are not a class but a per-`SchedContext` gate
/// (`tt_window_offset_us` / `tt_window_duration_us`, 110.G).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum SchedClass {
    #[default]
    Fifo,
    Edf,
    Sporadic,
    BestEffort,
}

/// Criticality bucket for [`SchedContext`]. Phase 110.C uses this to
/// pick which `BucketedFifoSet` / `BucketedEdfSet` slot a callback
/// dispatches through; later phases (110.D) map it to OS priority.
///
/// Default `Normal` keeps existing single-bucket workloads unchanged
/// — every default-Fifo SC sits in `Normal`, so dispatch order is
/// bit-identical to pre-110.C when no callback opts in to `Critical`
/// or `BestEffort`.
///
/// Single-thread non-preemption note: a `BestEffort` callback already
/// running blocks `Critical` work that becomes ready mid-cycle. Hard-
/// RT scenarios need 110.D's multi-executor preemption.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Ord, PartialOrd)]
pub enum Priority {
    /// Highest-priority bucket. Drained first within a single
    /// `spin_once` cycle; non-preemptive against in-flight lower-
    /// priority callbacks (see Phase 110.D for preemption).
    Critical = 0,
    /// Default bucket. Most callbacks (and the auto-default Fifo SC)
    /// live here.
    #[default]
    Normal = 1,
    /// Lowest-priority bucket. Drained last; first to be skipped if a
    /// future cycle-budget overrun forces an early return.
    BestEffort = 2,
}

impl Priority {
    pub const COUNT: usize = 3;

    pub const fn index(self) -> usize {
        self as usize
    }
}

/// How an EDF deadline is interpreted relative to a callback firing.
///
/// - `Released`: deadline is `release_time + period`. Default for
///   timer-triggered callbacks.
/// - `Activated`: deadline is `activation_time + relative_deadline`.
///   Default for event-triggered subscriptions.
/// - `Inherited`: deadline travels in the message header — latency-
///   aware pipelines extract it per-message at dispatch time.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum DeadlinePolicy {
    Released,
    #[default]
    Activated,
    Inherited,
}

/// RFC-0052 / phase-296 W3b.5 — what the executor DOES when a dispatched
/// callback runs past its bound SC's `deadline_us`. Distinct from
/// [`DeadlinePolicy`] (which says where the deadline COMES from); this is
/// the miss REACTION, lowered from the tier table's `deadline_policy`
/// string (`ignore | warn | skip | fault`).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum DeadlineAction {
    /// Measure nothing, report nothing (uncontracted default).
    #[default]
    Ignore,
    /// Push a `deadline-miss-runtime` violation onto the monitor drain.
    Warn,
    /// Warn AND skip the offending SC's remaining callbacks for the rest
    /// of this spin cycle (damage containment: a runaway callback does
    /// not get to also starve unrelated groups with its siblings).
    Skip,
    /// Warn AND invoke the executor's fault hook (panic when none is
    /// registered — on embedded targets that is a watchdog-visible stop).
    Fault,
}

impl DeadlineAction {
    /// Lower the tier-table string (`[tiers.<t>].deadline_policy`).
    /// Unknown strings map to `Ignore` — the bake already validated the
    /// vocabulary; runtime tolerance here avoids a boot-time panic path.
    ///
    /// phase-462 W2 -- that string is no longer authored per tier and nothing
    /// else. The launch contract's `on_violation` is now its SOURCE
    /// (`nros-orchestration-ir::violation_agreement`, applied in
    /// `plan_from_model`), and a tier table that states a different word is a
    /// resolve-time refusal naming both. So these four variants are what the
    /// contract's safety vocabulary reaches the target AS: the word in the
    /// YAML file becomes something the executor does.
    pub fn from_tier_str(s: &str) -> Self {
        match s {
            "warn" => Self::Warn,
            "skip" => Self::Skip,
            "fault" => Self::Fault,
            _ => Self::Ignore,
        }
    }

    /// The tier-table spelling of this action -- the inverse of
    /// [`from_tier_str`](Self::from_tier_str).
    ///
    /// The bake and the runtime share no type (this crate is `no_std` and
    /// knows nothing of the model), so the STRING is the interface between
    /// `ViolationAction::as_tier_str` on the bake side and this. Spelling it
    /// here rather than only on the bake side is what lets both sides pin the
    /// same four words in a test.
    pub const fn as_tier_str(self) -> &'static str {
        match self {
            Self::Ignore => "ignore",
            Self::Warn => "warn",
            Self::Skip => "skip",
            Self::Fault => "fault",
        }
    }
}

/// Identifier for a [`SchedContext`] registered with an Executor.
/// 110.B.b adds storage `[Option<SchedContext>; MAX_SC]`; this index
/// addresses into that array.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SchedContextId(pub u8);

/// First-class scheduling capability — one SC per scheduling concern,
/// shared by every callback that should run under the same budget /
/// period / deadline / class.
///
/// Phase 110.B.a defines the shape; 110.B.b's builder methods on
/// Executor consume it.
#[derive(Debug, Clone, Copy, Default)]
pub struct SchedContext {
    pub class: SchedClass,
    pub priority: Priority,
    pub period_us: OptUs,
    pub budget_us: OptUs,
    pub deadline_us: OptUs,
    pub deadline_policy: DeadlinePolicy,
    /// Phase 110.F — opt-in OS-level priority for per-callback
    /// dispatch. `0` (default) means "no per-callback OS priority"
    /// — the executor's cooperative dispatch path runs every
    /// callback bound to this SC. Non-zero values trigger the
    /// per-priority worker-pool path (registered via
    /// `Executor::register_os_priority_dispatcher`); each callback
    /// then runs on a worker thread the OS scheduler has elevated
    /// to that numeric priority.
    ///
    /// Numeric meaning is platform-defined (POSIX 1..99 for
    /// SCHED_FIFO; FreeRTOS 0..configMAX_PRIORITIES-1; Zephyr
    /// direction-flipped). Chain-priority assignment + chain
    /// grouping happen at the orchestration layer and are out of
    /// executor scope.
    pub os_pri: u8,
    /// Phase 110.G — time-triggered window offset within the
    /// executor's major frame. `None` (sentinel `0`) = always
    /// eligible (no TT gate); `Some(off)` + `tt_window_duration_us`
    /// gates dispatch to the half-open interval
    /// `[off, off + duration) mod major_frame`.
    ///
    /// Independent of `class` — a `Sporadic`-class SC can also be TT-
    /// gated; both gates apply (skip dispatch when EITHER fails).
    /// Pairs with `Executor::register_time_triggered_dispatcher`
    /// which sets the major-frame length.
    /// W3b.5 — reaction on a deadline miss (see [`DeadlineAction`]).
    pub deadline_action: DeadlineAction,
    pub tt_window_offset_us: OptUs,
    /// Phase 110.G — time-triggered window length. See
    /// `tt_window_offset_us`.
    pub tt_window_duration_us: OptUs,
}

/// Phase 110.E.b — atomic sporadic-server state for ISR-driven
/// refill. ISR / timer-thread context calls `refill_thunk` to top up
/// the budget; spin_once reads atomically without any `&mut` access.
///
/// Replaces the polled-clock `SporadicState` shape on platforms with
/// a `PlatformTimer` impl. The Executor still keeps the legacy
/// `SporadicState` path active on `feature = "std"` so the
/// transition is non-breaking.
pub struct AtomicSporadicState {
    pub budget_remaining_us: portable_atomic::AtomicU32,
    /// Wraps every ~50 days at ms resolution; saturates per
    /// `tick`'s monotonic-clock contract. portable-atomic provides
    /// AtomicU32 even on RISC-V `riscv32imc` / Cortex-M0+ that lack
    /// native 32-bit atomics.
    pub last_refill_ms: portable_atomic::AtomicU32,
    pub budget_capacity_us: u32,
    pub period_us: u32,
    /// Phase 110.E.b — cumulative count of dispatched callbacks
    /// whose measured wall-clock runtime exceeded the SC's
    /// `budget_us`. Bumped by the per-callback runtime closure
    /// inside `Executor::spin_once` (std-only — the no_std fallback
    /// continues to use the polled `SporadicState` path without
    /// per-callback overrun accounting). Cooperative single-thread
    /// dispatch can't preempt a runaway callback, so this counter
    /// is the diagnostic signal — the design's oneshot-IRQ-and-
    /// cancel pattern is structurally equivalent for non-preemptive
    /// callbacks, and `last_overrun_us` carries the worst-case
    /// observation for tuning. Both reset by `clear_overrun_stats`.
    pub overrun_count: portable_atomic::AtomicU32,
    /// WORST overrun amount seen (`measured_us - budget_us`) since the
    /// last `clear_overrun_stats`; `0` when none has been observed.
    ///
    /// This used to `store` the most RECENT overrun while its doc claimed
    /// it "carries the worst-case observation for tuning". A large overrun
    /// followed by a small one silently replaced the number anyone would
    /// have sized a budget from, and the only surviving evidence of the bad
    /// dispatch was that `overrun_count` had gone up by one. It is a
    /// `fetch_max` now, which is what the name and the purpose both say.
    pub last_overrun_us: portable_atomic::AtomicU32,
    /// Worst execution time observed on this SC, in microseconds, recorded
    /// on EVERY dispatch rather than only on an overrun.
    ///
    /// `overrun_count` and `last_overrun_us` answer "did it exceed the
    /// budget, and by how much". Neither can answer "how close did it come"
    /// — a system that never overruns produces no evidence at all, and that
    /// is exactly the system whose budget you are trying to choose. Sizing
    /// `budget_us` from a measured maximum is the whole point of the field.
    ///
    /// Only meaningful where the dispatch loop actually measures: elapsed is
    /// `0` unless a latency monitor, a deadline action, or a clock is
    /// present (`measure_us` in `spin_once`). No clock, no number.
    pub max_exec_us: portable_atomic::AtomicU32,
}

impl AtomicSporadicState {
    pub const fn new(budget_us: u32, period_us: u32) -> Self {
        Self {
            budget_remaining_us: portable_atomic::AtomicU32::new(budget_us),
            last_refill_ms: portable_atomic::AtomicU32::new(0),
            budget_capacity_us: budget_us,
            period_us,
            overrun_count: portable_atomic::AtomicU32::new(0),
            last_overrun_us: portable_atomic::AtomicU32::new(0),
            max_exec_us: portable_atomic::AtomicU32::new(0),
        }
    }

    /// Record one overrun: callback measured runtime exceeded the
    /// SC's `budget_us`. Bumps `overrun_count` + stores the absolute
    /// overrun amount in `last_overrun_us`. Called from the
    /// per-callback runtime closure inside `Executor::spin_once`.
    #[inline]
    pub fn record_overrun(&self, overrun_us: u32) {
        self.overrun_count
            .fetch_add(1, portable_atomic::Ordering::Relaxed);
        self.last_overrun_us
            .fetch_max(overrun_us, portable_atomic::Ordering::Relaxed);
    }

    /// Record one dispatch's measured execution time. Called on EVERY
    /// dispatch charged to this SC, overrun or not.
    #[inline]
    pub fn record_exec(&self, elapsed_us: u32) {
        self.max_exec_us
            .fetch_max(elapsed_us, portable_atomic::Ordering::Relaxed);
    }

    /// Worst execution time seen since the last `clear_overrun_stats`.
    #[inline]
    pub fn max_exec_us(&self) -> u32 {
        self.max_exec_us.load(portable_atomic::Ordering::Relaxed)
    }

    /// Reset both overrun statistics. Useful when tuning the budget
    /// across windows (monitoring code logs + clears periodically).
    #[inline]
    pub fn clear_overrun_stats(&self) {
        self.overrun_count
            .store(0, portable_atomic::Ordering::Relaxed);
        self.last_overrun_us
            .store(0, portable_atomic::Ordering::Relaxed);
        self.max_exec_us
            .store(0, portable_atomic::Ordering::Relaxed);
    }

    /// Read the budget atomically; spin_once consults this to decide
    /// whether to skip the SC's entries this cycle.
    pub fn has_budget(&self) -> bool {
        self.budget_remaining_us
            .load(portable_atomic::Ordering::Acquire)
            > 0
    }

    /// Saturating subtract — used by spin_once after dispatching a
    /// callback bound to this SC.
    pub fn consume(&self, us: u32) {
        let mut cur = self
            .budget_remaining_us
            .load(portable_atomic::Ordering::Acquire);
        loop {
            let next = cur.saturating_sub(us);
            match self.budget_remaining_us.compare_exchange_weak(
                cur,
                next,
                portable_atomic::Ordering::Release,
                portable_atomic::Ordering::Acquire,
            ) {
                Ok(_) => return,
                Err(observed) => cur = observed,
            }
        }
    }
}

/// C-callable refill thunk that `PlatformTimer::create_periodic`
/// invokes from the platform's timer context. Single atomic store —
/// safe in any thread / ISR context.
///
/// # Safety
/// `user_data` must point at a live `AtomicSporadicState`; the caller
/// of `PlatformTimer::create_periodic` owns the lifetime contract.
pub extern "C" fn atomic_sporadic_refill_thunk(user_data: *mut core::ffi::c_void) {
    if user_data.is_null() {
        return;
    }
    let state = unsafe { &*(user_data as *const AtomicSporadicState) };
    state
        .budget_remaining_us
        .store(state.budget_capacity_us, portable_atomic::Ordering::Release);
}

/// Phase 110.E — user-space sporadic-server runtime state.
///
/// Tracks remaining `budget_us` for the current period and the wall-
/// clock instant of the last refill. The executor consults this state
/// during dispatch: when `budget_remaining_us` reaches 0 the SC is
/// suppressed until the next period boundary, at which point a refill
/// resets the counter.
///
/// Refill cadence is polled — each `spin_once` checks whether the
/// elapsed time since the last refill exceeds `period_us` and tops
/// the budget back up. Less precise than an ISR-driven refill (Phase
/// 110.E's per-platform timer hook is what gets that) but correct as
/// an upper-bound bandwidth limiter.
#[derive(Debug, Clone, Copy)]
pub struct SporadicState {
    pub budget_remaining_us: u32,
    pub budget_capacity_us: u32,
    pub period_us: u32,
    pub last_refill_ms: u64,
    /// issue 0736 — consecutive spins in which this SC was skipped for want of
    /// budget. A skip is invisible by construction: `spin_once` `continue`s
    /// past the entry, so a starved tier looks exactly like an idle one. This
    /// counter is what lets it say so. Reset on any dispatch.
    pub consecutive_budget_skips: u32,
    /// issue 0736 — skips and dispatches over a rolling window.
    ///
    /// The consecutive counter above catches TOTAL starvation quickly and
    /// misses the commoner shape entirely: a budget that merely THROTTLES.
    /// Measured on nuttx-arm/rust, a 5 ms budget per 10 ms period held the
    /// tier to about a quarter of its declared rate — skip a few, refill,
    /// dispatch, repeat — so no streak ever reached the consecutive threshold
    /// and the tier was silently 4x slow. A declaration that cannot be met has
    /// to be reported whether it starves or merely throttles.
    pub window_skips: u32,
    pub window_dispatches: u32,
    /// Worst execution time observed on this SC, in microseconds, recorded
    /// on EVERY dispatch.
    ///
    /// This is the polled path, and issue 0736 established it is the one
    /// that matters: `has_budget` prefers the atomic state only when a
    /// refill timer was registered, which no board or entry does. So a
    /// number recorded only on the atomic side would be a number no shipped
    /// image ever writes.
    ///
    /// Sizing `budget_us` needs a measured maximum, and the overrun
    /// counters cannot supply one: they say nothing at all until the budget
    /// is already exceeded, which is the wrong end of the question when the
    /// budget is what you are trying to choose.
    ///
    /// Only meaningful where the dispatch loop measures: elapsed is `0`
    /// unless a latency monitor, a deadline action, or a clock is present.
    pub max_exec_us: u32,
}

impl SporadicState {
    pub const fn new(budget_us: u32, period_us: u32) -> Self {
        Self {
            budget_remaining_us: budget_us,
            budget_capacity_us: budget_us,
            period_us,
            last_refill_ms: 0,
            consecutive_budget_skips: 0,
            window_skips: 0,
            window_dispatches: 0,
            max_exec_us: 0,
        }
    }

    /// Replenish the budget at period boundaries. Returns `true` if the SC has
    /// budget remaining afterwards.
    ///
    /// issue 0736 — this used to be `tick(now_ms, delta_us)`, which refilled
    /// AND then charged the whole inter-spin `delta_us` as consumption. A
    /// budget bounds the CPU the SC's callbacks consume; the wall-clock gap
    /// between two spins is not that, and on any target where the gap exceeds
    /// the budget it exhausts the SC on every single spin no matter what the
    /// callbacks did. Measured on nuttx-arm/rust: `delta_us` 10_000..80_000
    /// against a 5_000 us budget, giving 1200 budget skips against 3 dispatches
    /// while the sibling tier — identical but declaring no budget — dispatched
    /// on all 450 of its spins.
    ///
    /// The `delta_us` charge was documented as a "worst-case attribution"
    /// standing in for per-callback measurement. That measurement now exists
    /// and runs on every flavour, so consumption belongs to
    /// [`Self::consume`], called with what the callback actually cost.
    pub fn refill(&mut self, now_ms: u64) -> bool {
        // Refill at period boundaries — coarse but correct.
        if now_ms.saturating_sub(self.last_refill_ms) >= self.period_us as u64 / 1000 {
            self.budget_remaining_us = self.budget_capacity_us;
            self.last_refill_ms = now_ms;
        }
        self.budget_remaining_us > 0
    }

    /// Charge measured callback runtime against the remaining budget.
    ///
    /// The polled-state twin of `AtomicSporadicState::consume`. Both exist
    /// because the atomic one is only present when a caller has registered a
    /// refill timer via `Executor::register_sporadic_timer` — which, outside
    /// this crate's own tests, nothing does. Every shipped image runs THIS
    /// path, so it is the one that has to be right (issue 0736).
    pub fn consume(&mut self, us: u32) {
        self.budget_remaining_us = self.budget_remaining_us.saturating_sub(us);
        self.consecutive_budget_skips = 0;
        self.window_dispatches = self.window_dispatches.saturating_add(1);
        // Every dispatch, not only the overrunning ones. See `max_exec_us`.
        if us > self.max_exec_us {
            self.max_exec_us = us;
        }
    }

    /// How many dispatch opportunities before the throttle ratio is judged.
    /// Long enough that a brief burst of skips is not news; short enough to
    /// close inside a short run. 1000 was the first value and it NEVER closed
    /// on the measured case — that tier misses roughly 240 dispatches over the
    /// whole e2e window, so a 1000-opportunity window is larger than the
    /// evidence and the warning existed without ever being reachable, which is
    /// the same silence it was written to break.
    pub const BUDGET_WINDOW: u32 = 200;
    /// Report when more than this share of the window was skipped. A quarter
    /// is already a tier delivering at 75% of what it declared.
    pub const BUDGET_SKIP_REPORT_PERMILLE: u32 = 250;

    /// Close the window if it is full. Returns `Some((skips, total))` when the
    /// window closed with a skip share worth reporting.
    pub fn take_budget_window(&mut self) -> Option<(u32, u32)> {
        let total = self.window_skips + self.window_dispatches;
        if total < Self::BUDGET_WINDOW {
            return None;
        }
        let skips = self.window_skips;
        self.window_skips = 0;
        self.window_dispatches = 0;
        if skips.saturating_mul(1000) / total.max(1) >= Self::BUDGET_SKIP_REPORT_PERMILLE {
            Some((skips, total))
        } else {
            None
        }
    }

    /// Record one budget-skipped dispatch. Returns `Some(n)` when the streak
    /// has reached a length worth reporting — at 100, then each power of ten —
    /// so a starved SC is loud once and does not then flood the console.
    pub fn note_budget_skip(&mut self) -> Option<u32> {
        self.consecutive_budget_skips = self.consecutive_budget_skips.saturating_add(1);
        self.window_skips = self.window_skips.saturating_add(1);
        let n = self.consecutive_budget_skips;
        // Once when the streak is clearly not noise, then sparsely: a starved
        // SC must be loud, and must not then drown the console it is reporting
        // on. (The measured case ran 1200 consecutive skips.)
        if n == 100 || (n > 100 && n.is_multiple_of(1000)) {
            Some(n)
        } else {
            None
        }
    }
}

impl SchedContext {
    pub const fn new_fifo() -> Self {
        Self {
            class: SchedClass::Fifo,
            priority: Priority::Normal,
            period_us: OptUs::NONE,
            budget_us: OptUs::NONE,
            deadline_us: OptUs::NONE,
            deadline_policy: DeadlinePolicy::Activated,
            os_pri: 0,
            deadline_action: DeadlineAction::Ignore,
            tt_window_offset_us: OptUs::NONE,
            tt_window_duration_us: OptUs::NONE,
        }
    }

    /// RFC-0052 — the **common backend** that lowers an RTOS-agnostic tier
    /// policy (`[tiers.<t>]` class / budget / period / deadline) to a
    /// [`SchedContext`]. ONE implementation shared by every language: the Rust
    /// runtime (`ExecutorNodeRuntime::apply_tier_sched_policy`)
    /// and the C / C++ entries (`nros_{c,cpp}_create_sched_context_from_policy`)
    /// all call this, so the mapping can never drift between codegen paths.
    ///
    /// - `real_time` + `budget_us` + `period_us` → [`SchedClass::Sporadic`]
    ///   (budget + RT replenishment period on the SC);
    /// - `best_effort` → [`SchedClass::BestEffort`];
    /// - `time_triggered` + `period_us` → a TT window (major frame =
    ///   `period_us`, window = `budget_us` or the whole frame). The returned
    ///   `Some(frame_us)` is the major frame the caller must install via
    ///   [`crate::executor::Executor::register_time_triggered_dispatcher`]
    ///   (the SC itself stays `Fifo`-class per the 110.G TT refactor);
    /// - `deadline_us` sets the SC deadline; `deadline_policy` its
    ///   [`DeadlineAction`].
    ///
    /// Returns `None` when the tier declares no class / budget / deadline — the
    /// caller keeps the default `Fifo` SC (byte-identical pre-policy behavior).
    /// `os_pri` is intentionally NOT set here (it is an orthogonal per-callback
    /// OS-priority knob the caller applies); this fn covers only the
    /// RTOS-agnostic real-time policy.
    pub fn from_tier_policy(
        class: Option<&str>,
        period_us: Option<u64>,
        budget_us: Option<u64>,
        deadline_us: Option<u64>,
        deadline_policy: Option<&str>,
    ) -> Option<(Self, Option<u32>)> {
        let sporadic = class == Some("real_time") && budget_us.is_some() && period_us.is_some();
        let best_effort = class == Some("best_effort");
        let time_triggered = class == Some("time_triggered") && period_us.is_some();
        if !sporadic && !best_effort && !time_triggered && deadline_us.is_none() {
            return None;
        }
        let clamp = |v: u64| v.min(u32::MAX as u64) as u32;
        let mut sc = Self::default();
        let mut tt_frame = None;
        if sporadic {
            sc.class = SchedClass::Sporadic;
            sc.budget_us = OptUs::from_us(clamp(budget_us.unwrap_or(0)));
            sc.period_us = OptUs::from_us(clamp(period_us.unwrap_or(0)));
        } else if best_effort {
            sc.class = SchedClass::BestEffort;
        } else if time_triggered {
            tt_frame = Some(clamp(period_us.unwrap_or(0)));
            let window_us = clamp(budget_us.unwrap_or(period_us.unwrap_or(0)));
            sc.tt_window_duration_us = OptUs::from_us(window_us);
        }
        if let Some(d) = deadline_us {
            sc.deadline_us = OptUs::from_us(clamp(d));
        }
        if let Some(action) = deadline_policy {
            sc.deadline_action = DeadlineAction::from_tier_str(action);
        }
        Some((sc, tt_frame))
    }
}

// ----------------------------------------------------------------------
// Phase 110.G — TimeTriggered schedule-table API.
//
// ARINC-653-style cyclic executive: the major frame is partitioned
// into fixed windows; each callback is bound to a window via
// `SchedContext { tt_window_offset_us, tt_window_duration_us }`.
// The runtime gate inside `Executor::spin_once` already enforces
// per-window dispatch suppression (Phase 110.G runtime, landed
// pre-session). This block adds the schedule-table types +
// builder helpers so callers can declare a complete cyclic
// schedule with a single API call instead of stitching
// `create_sched_context` + `bind_handle_to_sched_context` together.
// ----------------------------------------------------------------------

/// One slot in a time-triggered schedule.
///
/// Window `[offset_us, offset_us + duration_us)` within the major
/// frame. `name` is a static-lifetime label for diagnostics
/// (logging, panic messages); the runtime never inspects it.
#[derive(Debug, Clone, Copy)]
pub struct TimeTriggeredWindow {
    pub offset_us: u32,
    pub duration_us: u32,
    pub name: &'static str,
}

impl TimeTriggeredWindow {
    pub const fn new(offset_us: u32, duration_us: u32, name: &'static str) -> Self {
        Self {
            offset_us,
            duration_us,
            name,
        }
    }
}

/// Fixed-size, no_std-friendly cyclic schedule. `N` is the
/// declared maximum window count; `window_count` is the active
/// length (callers can build the array up to `N` and set
/// `window_count` to the actual size used).
#[derive(Debug)]
pub struct TimeTriggeredSchedule<const N: usize> {
    pub major_frame_us: u32,
    pub windows: [TimeTriggeredWindow; N],
    pub window_count: usize,
}

impl<const N: usize> TimeTriggeredSchedule<N> {
    /// Construct a schedule from an exhaustive `[TimeTriggeredWindow; N]`
    /// array; `window_count` is set to `N`.
    pub const fn new_full(major_frame_us: u32, windows: [TimeTriggeredWindow; N]) -> Self {
        Self {
            major_frame_us,
            windows,
            window_count: N,
        }
    }

    /// Validate the schedule: every window must fit inside
    /// `[0, major_frame_us)` and windows must be non-overlapping
    /// in offset-sorted order. Sliding-window check; O(N²) is fine
    /// because TT schedules are small (rarely > 16 slots).
    pub fn validate(&self) -> Result<(), TimeTriggeredScheduleError> {
        if self.major_frame_us == 0 {
            return Err(TimeTriggeredScheduleError::ZeroMajorFrame);
        }
        if self.window_count > N {
            return Err(TimeTriggeredScheduleError::WindowCountOverflow);
        }
        for (i, w) in self.windows[..self.window_count].iter().enumerate() {
            if w.duration_us == 0 {
                return Err(TimeTriggeredScheduleError::ZeroWindowDuration { window: i });
            }
            let end = (w.offset_us as u64) + (w.duration_us as u64);
            if end > self.major_frame_us as u64 {
                return Err(TimeTriggeredScheduleError::WindowExceedsMajorFrame { window: i });
            }
            for (j, other) in self.windows[..self.window_count].iter().enumerate() {
                if i == j {
                    continue;
                }
                let o_end = (other.offset_us as u64) + (other.duration_us as u64);
                let overlaps = (w.offset_us as u64) < o_end && (other.offset_us as u64) < end;
                if overlaps {
                    return Err(TimeTriggeredScheduleError::WindowsOverlap {
                        window_a: i,
                        window_b: j,
                    });
                }
            }
        }
        Ok(())
    }
}

/// Validation errors for a [`TimeTriggeredSchedule`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TimeTriggeredScheduleError {
    ZeroMajorFrame,
    WindowCountOverflow,
    ZeroWindowDuration { window: usize },
    WindowExceedsMajorFrame { window: usize },
    WindowsOverlap { window_a: usize, window_b: usize },
}

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

    #[test]
    fn opt_us_sentinel_round_trip() {
        assert!(!OptUs::NONE.is_some());
        assert_eq!(OptUs::NONE.get(), None);
        let some = OptUs::from_us(42);
        assert!(some.is_some());
        assert_eq!(some.get().map(|nz| nz.get()), Some(42));
        assert_eq!(some.raw(), 42);
    }

    #[test]
    fn opt_us_layout_is_u32() {
        // ABI guard — `OptUs` MUST stay `#[repr(transparent)]` over
        // `u32` so cbindgen emits a plain `uint32_t`.
        assert_eq!(core::mem::size_of::<OptUs>(), core::mem::size_of::<u32>());
        assert_eq!(core::mem::align_of::<OptUs>(), core::mem::align_of::<u32>());
    }

    #[test]
    fn sched_context_default_is_fifo() {
        let sc = SchedContext::default();
        assert_eq!(sc.class, SchedClass::Fifo);
        assert!(!sc.period_us.is_some());
        assert!(!sc.budget_us.is_some());
        assert!(!sc.deadline_us.is_some());
        assert_eq!(sc.deadline_policy, DeadlinePolicy::Activated);
    }

    // RFC-0052 — the common-backend tier→SchedContext lowering, shared by the
    // Rust runtime (`apply_tier_sched_policy`) and the C/C++ FFI
    // (`nros_{c,cpp}_create_sched_context_from_policy`). One place, one test.

    #[test]
    fn from_tier_policy_real_time_lowers_to_sporadic() {
        let (sc, tt) = SchedContext::from_tier_policy(
            Some("real_time"),
            Some(20_000),
            Some(3_000),
            Some(15_000),
            Some("fault"),
        )
        .expect("real_time+budget+period is a policy");
        assert_eq!(sc.class, SchedClass::Sporadic);
        assert_eq!(sc.period_us.raw(), 20_000);
        assert_eq!(sc.budget_us.raw(), 3_000);
        assert_eq!(sc.deadline_us.raw(), 15_000);
        assert_eq!(sc.deadline_action, DeadlineAction::Fault);
        assert_eq!(tt, None);
    }

    #[test]
    fn from_tier_policy_real_time_without_budget_or_period_is_not_sporadic() {
        // `real_time` needs BOTH budget and period to be a sporadic server; a
        // bare `real_time` with neither (and no deadline) declares no policy.
        assert!(
            SchedContext::from_tier_policy(Some("real_time"), None, None, None, None).is_none()
        );
    }

    #[test]
    fn from_tier_policy_best_effort() {
        let (sc, tt) = SchedContext::from_tier_policy(Some("best_effort"), None, None, None, None)
            .expect("best_effort is a policy");
        assert_eq!(sc.class, SchedClass::BestEffort);
        assert_eq!(tt, None);
    }

    #[test]
    fn from_tier_policy_time_triggered_returns_major_frame() {
        // TT stays Fifo-class (110.G) but returns the major frame to register
        // and sets the window duration (budget → window, else whole frame).
        let (sc, tt) = SchedContext::from_tier_policy(
            Some("time_triggered"),
            Some(10_000),
            Some(4_000),
            None,
            None,
        )
        .expect("time_triggered+period is a policy");
        assert_eq!(sc.class, SchedClass::Fifo);
        assert_eq!(tt, Some(10_000));
        assert_eq!(sc.tt_window_duration_us.raw(), 4_000);
    }

    #[test]
    fn from_tier_policy_deadline_only() {
        // A deadline with no RT class still yields a policy (Fifo + deadline).
        let (sc, _tt) = SchedContext::from_tier_policy(None, None, None, Some(8_000), Some("warn"))
            .expect("a deadline is a policy");
        assert_eq!(sc.class, SchedClass::Fifo);
        assert_eq!(sc.deadline_us.raw(), 8_000);
        assert_eq!(sc.deadline_action, DeadlineAction::Warn);
    }

    #[test]
    fn from_tier_policy_none_when_no_policy() {
        // No class, no deadline → None → caller keeps the default Fifo SC.
        assert!(SchedContext::from_tier_policy(None, Some(1_000), None, None, None).is_none());
        assert!(SchedContext::from_tier_policy(Some("default"), None, None, None, None).is_none());
    }

    /// phase-462 W2 -- the four words are the interface between the bake and
    /// this crate. `nros-orchestration-ir`'s `violation_agreement` pins the
    /// same three non-default ones in `the_tier_spelling_round_trips`; if
    /// either side renames one, the contract's `on_violation` silently lowers
    /// to `Ignore` and the image stops reacting.
    #[test]
    fn the_contract_vocabulary_is_the_tier_vocabulary() {
        for a in [
            DeadlineAction::Ignore,
            DeadlineAction::Warn,
            DeadlineAction::Skip,
            DeadlineAction::Fault,
        ] {
            assert_eq!(DeadlineAction::from_tier_str(a.as_tier_str()), a);
        }
        assert_eq!(DeadlineAction::Fault.as_tier_str(), "fault");
        // An unreadable word is the default, not a boot panic.
        assert_eq!(
            DeadlineAction::from_tier_str("abort"),
            DeadlineAction::Ignore
        );
    }
}

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

    /// The number a budget gets sized from has to survive a later, smaller
    /// dispatch. `max_exec_us` is a maximum, not a last-write.
    #[test]
    fn polled_state_keeps_the_worst_execution_not_the_latest() {
        let mut st = SporadicState::new(1000, 10_000);
        st.consume(120);
        st.consume(900);
        st.consume(30);
        assert_eq!(st.max_exec_us, 900);
    }

    /// Recorded on EVERY dispatch, including ones well inside budget. A
    /// system that never overruns still has to say how close it came.
    #[test]
    fn polled_state_records_without_any_overrun() {
        let mut st = SporadicState::new(10_000, 20_000);
        st.consume(700);
        st.consume(450);
        assert_eq!(
            st.max_exec_us, 700,
            "no overrun occurred, yet 700 is the evidence"
        );
    }

    #[test]
    fn atomic_state_keeps_the_worst_execution_not_the_latest() {
        let st = AtomicSporadicState::new(1000, 10_000);
        st.record_exec(120);
        st.record_exec(900);
        st.record_exec(30);
        assert_eq!(st.max_exec_us(), 900);
    }

    /// Regression: `last_overrun_us` used to `store`, so a big overrun
    /// followed by a small one lost the big one entirely -- while its own
    /// doc promised "the worst-case observation for tuning".
    #[test]
    fn last_overrun_keeps_the_worst_not_the_most_recent() {
        let st = AtomicSporadicState::new(1000, 10_000);
        st.record_overrun(500);
        st.record_overrun(20);
        assert_eq!(
            st.last_overrun_us.load(portable_atomic::Ordering::Relaxed),
            500,
            "a later small overrun must not erase the worst one"
        );
        assert_eq!(st.overrun_count.load(portable_atomic::Ordering::Relaxed), 2);
    }

    #[test]
    fn clearing_stats_resets_the_high_water_too() {
        let st = AtomicSporadicState::new(1000, 10_000);
        st.record_exec(4242);
        st.record_overrun(7);
        st.clear_overrun_stats();
        assert_eq!(st.max_exec_us(), 0);
        assert_eq!(
            st.last_overrun_us.load(portable_atomic::Ordering::Relaxed),
            0
        );
        assert_eq!(st.overrun_count.load(portable_atomic::Ordering::Relaxed), 0);
    }
}