cu29_runtime/

config.rs

//! This module defines the configuration of the copper runtime.
//! The configuration is a directed graph where nodes are tasks and edges are connections between tasks.
//! The configuration is serialized in the RON format.
//! The configuration is used to generate the runtime code at compile time.
#[cfg(not(feature = "std"))]
extern crate alloc;

use ConfigGraphs::{Missions, Simple};
use core::any::type_name;
use core::fmt;
use core::fmt::Display;
use cu29_traits::{CuError, CuResult};
use cu29_value::Value as CuValue;
use hashbrown::HashMap;
pub use petgraph::Direction::Incoming;
pub use petgraph::Direction::Outgoing;
use petgraph::stable_graph::{EdgeIndex, NodeIndex, StableDiGraph};
#[cfg(feature = "std")]
use petgraph::visit::IntoEdgeReferences;
use petgraph::visit::{Bfs, EdgeRef};
use ron::extensions::Extensions;
use ron::value::Value as RonValue;
use ron::{Number, Options};
use serde::de::DeserializeOwned;
use serde::{Deserialize, Deserializer, Serialize, Serializer};

#[cfg(not(feature = "std"))]
use alloc::boxed::Box;
#[cfg(not(feature = "std"))]
use alloc::collections::BTreeMap;
#[cfg(not(feature = "std"))]
use alloc::vec;
#[cfg(feature = "std")]
use std::collections::BTreeMap;

#[cfg(not(feature = "std"))]
mod imp {
    pub use alloc::borrow::ToOwned;
    pub use alloc::format;
    pub use alloc::string::String;
    pub use alloc::string::ToString;
    pub use alloc::vec::Vec;
}

#[cfg(feature = "std")]
mod imp {
    pub use html_escape::encode_text;
    pub use std::fs::read_to_string;
}

use imp::*;

/// NodeId is the unique identifier of a node in the configuration graph for petgraph
/// and the code generation.
pub type NodeId = u32;
pub const DEFAULT_MISSION_ID: &str = "default";

/// This is the configuration of a component (like a task config or a monitoring config):w
/// It is a map of key-value pairs.
/// It is given to the new method of the task implementation.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct ComponentConfig(pub HashMap<String, Value>);

/// Mapping between resource binding names and bundle-scoped resource ids.
#[allow(dead_code)]
impl Display for ComponentConfig {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut first = true;
        let ComponentConfig(config) = self;
        write!(f, "{{")?;
        for (key, value) in config.iter() {
            if !first {
                write!(f, ", ")?;
            }
            write!(f, "{key}: {value}")?;
            first = false;
        }
        write!(f, "}}")
    }
}

// forward map interface
impl ComponentConfig {
    #[allow(dead_code)]
    pub fn new() -> Self {
        ComponentConfig(HashMap::new())
    }

    #[allow(dead_code)]
    pub fn get<T>(&self, key: &str) -> Result<Option<T>, ConfigError>
    where
        T: for<'a> TryFrom<&'a Value, Error = ConfigError>,
    {
        let ComponentConfig(config) = self;
        match config.get(key) {
            Some(value) => T::try_from(value).map(Some),
            None => Ok(None),
        }
    }

    #[allow(dead_code)]
    /// Retrieve a structured config value by deserializing it with cu29-value.
    ///
    /// Example RON:
    /// `{ "calibration": { "matrix": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]], "enabled": true } }`
    ///
    /// ```rust,ignore
    /// #[derive(serde::Deserialize)]
    /// struct CalibrationCfg {
    ///     matrix: [[f32; 3]; 3],
    ///     enabled: bool,
    /// }
    /// let cfg: CalibrationCfg = config.get_value("calibration")?.unwrap();
    /// ```
    pub fn get_value<T>(&self, key: &str) -> Result<Option<T>, ConfigError>
    where
        T: DeserializeOwned,
    {
        let ComponentConfig(config) = self;
        let Some(value) = config.get(key) else {
            return Ok(None);
        };
        let cu_value = ron_value_to_cu_value(&value.0).map_err(|err| err.with_key(key))?;
        cu_value
            .deserialize_into::<T>()
            .map(Some)
            .map_err(|err| ConfigError {
                message: format!(
                    "Config key '{key}' failed to deserialize as {}: {err}",
                    type_name::<T>()
                ),
            })
    }

    #[allow(dead_code)]
    pub fn deserialize_into<T>(&self) -> Result<T, ConfigError>
    where
        T: DeserializeOwned,
    {
        let mut map = BTreeMap::new();
        for (key, value) in &self.0 {
            let mapped_value = ron_value_to_cu_value(&value.0).map_err(|err| err.with_key(key))?;
            map.insert(CuValue::String(key.clone()), mapped_value);
        }

        CuValue::Map(map)
            .deserialize_into::<T>()
            .map_err(|err| ConfigError {
                message: format!(
                    "Config failed to deserialize as {}: {err}",
                    type_name::<T>()
                ),
            })
    }

    #[allow(dead_code)]
    pub fn set<T: Into<Value>>(&mut self, key: &str, value: T) {
        let ComponentConfig(config) = self;
        config.insert(key.to_string(), value.into());
    }

    #[allow(dead_code)]
    pub fn merge_from(&mut self, other: &ComponentConfig) {
        let ComponentConfig(config) = self;
        for (key, value) in &other.0 {
            config.insert(key.clone(), value.clone());
        }
    }
}

fn ron_value_to_cu_value(value: &RonValue) -> Result<CuValue, ConfigError> {
    match value {
        RonValue::Bool(v) => Ok(CuValue::Bool(*v)),
        RonValue::Char(v) => Ok(CuValue::Char(*v)),
        RonValue::String(v) => Ok(CuValue::String(v.clone())),
        RonValue::Bytes(v) => Ok(CuValue::Bytes(v.clone())),
        RonValue::Unit => Ok(CuValue::Unit),
        RonValue::Option(v) => {
            let mapped = match v {
                Some(inner) => Some(Box::new(ron_value_to_cu_value(inner)?)),
                None => None,
            };
            Ok(CuValue::Option(mapped))
        }
        RonValue::Seq(seq) => {
            let mut mapped = Vec::with_capacity(seq.len());
            for item in seq {
                mapped.push(ron_value_to_cu_value(item)?);
            }
            Ok(CuValue::Seq(mapped))
        }
        RonValue::Map(map) => {
            let mut mapped = BTreeMap::new();
            for (key, value) in map.iter() {
                let mapped_key = ron_value_to_cu_value(key)?;
                let mapped_value = ron_value_to_cu_value(value)?;
                mapped.insert(mapped_key, mapped_value);
            }
            Ok(CuValue::Map(mapped))
        }
        RonValue::Number(num) => match num {
            Number::I8(v) => Ok(CuValue::I8(*v)),
            Number::I16(v) => Ok(CuValue::I16(*v)),
            Number::I32(v) => Ok(CuValue::I32(*v)),
            Number::I64(v) => Ok(CuValue::I64(*v)),
            Number::U8(v) => Ok(CuValue::U8(*v)),
            Number::U16(v) => Ok(CuValue::U16(*v)),
            Number::U32(v) => Ok(CuValue::U32(*v)),
            Number::U64(v) => Ok(CuValue::U64(*v)),
            Number::F32(v) => Ok(CuValue::F32(v.0)),
            Number::F64(v) => Ok(CuValue::F64(v.0)),
            _ => Err(ConfigError {
                message: "Unsupported RON number variant".to_string(),
            }),
        },
    }
}

// The configuration Serialization format is as follows:
// (
//   tasks : [ (id: "toto", type: "zorglub::MyType", config: {...}),
//             (id: "titi", type: "zorglub::MyType2", config: {...})]
//   cnx : [ (src: "toto", dst: "titi", msg: "zorglub::MyMsgType"),...]
// )

/// Wrapper around the ron::Value to allow for custom serialization.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Value(RonValue);

/// Scalar representation used by compile-time constants after RON parsing.
#[doc(hidden)]
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ConstantNumber {
    Signed(i64),
    Unsigned(u64),
    Float(f64),
}

impl ConstantNumber {
    pub fn as_f64(self) -> f64 {
        match self {
            Self::Signed(value) => value as f64,
            Self::Unsigned(value) => value as f64,
            Self::Float(value) => value,
        }
    }
}

/// Rust scalar storage selected for a compile-time constant.
#[doc(hidden)]
#[derive(Serialize, Deserialize, Debug, Clone, Copy, Default, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum ConstantStorage {
    I8,
    I16,
    I32,
    I64,
    Isize,
    U8,
    U16,
    U32,
    U64,
    Usize,
    #[default]
    F32,
    F64,
}

impl ConstantStorage {
    pub const fn rust_type(self) -> &'static str {
        match self {
            Self::I8 => "i8",
            Self::I16 => "i16",
            Self::I32 => "i32",
            Self::I64 => "i64",
            Self::Isize => "isize",
            Self::U8 => "u8",
            Self::U16 => "u16",
            Self::U32 => "u32",
            Self::U64 => "u64",
            Self::Usize => "usize",
            Self::F32 => "f32",
            Self::F64 => "f64",
        }
    }

    pub const fn supports_quantity(self) -> bool {
        matches!(self, Self::F32 | Self::F64)
    }
}

/// One top-level `constants:` declaration.
#[doc(hidden)]
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ConstantConfig {
    id: String,
    #[serde(default, deserialize_with = "deserialize_constant_module")]
    module: Option<String>,
    #[serde(default)]
    storage: Option<ConstantStorage>,
    quantity: Option<cu29_units::constant::Quantity>,
    unit: Option<cu29_units::constant::Unit>,
    value: Option<Value>,
    #[serde(rename = "type")]
    rust_type: Option<String>,
    expression: Option<String>,
}

fn deserialize_constant_module<'de, D>(deserializer: D) -> Result<Option<String>, D::Error>
where
    D: Deserializer<'de>,
{
    Option::<String>::deserialize(deserializer).map(|module| {
        module.map(|module| {
            module
                .chars()
                .filter(|character| !character.is_whitespace())
                .collect()
        })
    })
}

impl ConstantConfig {
    pub const DEFAULT_MODULE: &'static str = "constants";

    pub fn id(&self) -> &str {
        &self.id
    }

    pub fn module_path(&self) -> &str {
        self.module.as_deref().unwrap_or(Self::DEFAULT_MODULE)
    }

    pub fn qualified_id(&self) -> String {
        format!("{}::{}", self.module_path(), self.id)
    }

    pub const fn storage(&self) -> ConstantStorage {
        match self.storage {
            Some(storage) => storage,
            None => ConstantStorage::F32,
        }
    }

    pub const fn quantity(&self) -> Option<cu29_units::constant::Quantity> {
        self.quantity
    }

    pub const fn explicit_unit(&self) -> Option<cu29_units::constant::Unit> {
        self.unit
    }

    pub fn expression_definition(&self) -> Option<(&str, &str)> {
        self.rust_type.as_deref().zip(self.expression.as_deref())
    }

    pub fn resolved_unit(&self) -> Result<Option<cu29_units::constant::Unit>, String> {
        let Some(quantity) = self.quantity else {
            return Ok(None);
        };
        if let Some(unit) = self.unit {
            return Ok(Some(unit));
        }
        let definition = cu29_units::constant::definition(quantity).ok_or_else(|| {
            format!(
                "Constant '{}' uses quantity '{}' which is missing from the unit catalogue",
                self.id,
                quantity.name()
            )
        })?;
        cu29_units::constant::Unit::from_name(definition.coherent_unit)
            .map(Some)
            .ok_or_else(|| {
                format!(
                    "Constant '{}' quantity '{}' has invalid coherent unit metadata '{}'",
                    self.id,
                    quantity.name(),
                    definition.coherent_unit
                )
            })
    }

    pub fn numbers(&self) -> Result<(bool, Vec<ConstantNumber>), String> {
        fn number(value: &RonValue) -> Result<ConstantNumber, String> {
            match value {
                RonValue::Number(number) => match number {
                    Number::I8(value) => Ok(ConstantNumber::Signed(i64::from(*value))),
                    Number::I16(value) => Ok(ConstantNumber::Signed(i64::from(*value))),
                    Number::I32(value) => Ok(ConstantNumber::Signed(i64::from(*value))),
                    Number::I64(value) => Ok(ConstantNumber::Signed(*value)),
                    Number::U8(value) => Ok(ConstantNumber::Unsigned(u64::from(*value))),
                    Number::U16(value) => Ok(ConstantNumber::Unsigned(u64::from(*value))),
                    Number::U32(value) => Ok(ConstantNumber::Unsigned(u64::from(*value))),
                    Number::U64(value) => Ok(ConstantNumber::Unsigned(*value)),
                    Number::F32(value) => Ok(ConstantNumber::Float(f64::from(value.0))),
                    Number::F64(value) => Ok(ConstantNumber::Float(value.0)),
                    _ => Err("unsupported numeric representation".to_string()),
                },
                _ => Err("expected a number".to_string()),
            }
        }

        let value = self
            .value
            .as_ref()
            .ok_or_else(|| format!("Constant '{}' does not declare a numeric value", self.id))?;
        match &value.0 {
            RonValue::Seq(values) => values
                .iter()
                .map(number)
                .collect::<Result<Vec<_>, _>>()
                .map(|values| (true, values)),
            value => number(value).map(|value| (false, vec![value])),
        }
        .map_err(|error| format!("Constant '{}': {error}", self.id))
    }

    pub fn normalized_f32(&self) -> Result<(bool, Vec<f32>), String> {
        let quantity = self.quantity.ok_or_else(|| {
            format!(
                "Constant '{}' does not declare a physical quantity",
                self.id
            )
        })?;
        let unit = self
            .resolved_unit()?
            .ok_or_else(|| format!("Constant '{}' has no resolved unit", self.id))?;
        let (is_array, numbers) = self.numbers()?;
        numbers
            .into_iter()
            .map(|number| {
                let value = number.as_f64() as f32;
                if !value.is_finite() {
                    return Err(format!("Constant '{}' values must be finite", self.id));
                }
                cu29_units::constant::normalize_f32(quantity, unit, value).ok_or_else(|| {
                    format!(
                        "Constant '{}' unit '{}' is not compatible with quantity '{}'",
                        self.id,
                        unit.name(),
                        quantity.name()
                    )
                })
            })
            .collect::<Result<Vec<_>, _>>()
            .map(|values| (is_array, values))
    }

    pub fn normalized_f64(&self) -> Result<(bool, Vec<f64>), String> {
        let quantity = self.quantity.ok_or_else(|| {
            format!(
                "Constant '{}' does not declare a physical quantity",
                self.id
            )
        })?;
        let unit = self
            .resolved_unit()?
            .ok_or_else(|| format!("Constant '{}' has no resolved unit", self.id))?;
        let (is_array, numbers) = self.numbers()?;
        numbers
            .into_iter()
            .map(|number| {
                let value = number.as_f64();
                if !value.is_finite() {
                    return Err(format!("Constant '{}' values must be finite", self.id));
                }
                cu29_units::constant::normalize_f64(quantity, unit, value).ok_or_else(|| {
                    format!(
                        "Constant '{}' unit '{}' is not compatible with quantity '{}'",
                        self.id,
                        unit.name(),
                        quantity.name()
                    )
                })
            })
            .collect::<Result<Vec<_>, _>>()
            .map(|values| (is_array, values))
    }

    /// Stable comparison key for detecting runtime attempts to change a baked constant.
    #[allow(dead_code)]
    pub fn semantic_fingerprint(&self) -> Result<u64, String> {
        const OFFSET: u64 = 0xcbf2_9ce4_8422_2325;
        const PRIME: u64 = 0x0000_0100_0000_01b3;

        fn hash_bytes(hash: &mut u64, bytes: &[u8]) {
            for byte in bytes {
                *hash ^= u64::from(*byte);
                *hash = hash.wrapping_mul(PRIME);
            }
        }

        let mut hash = OFFSET;
        if let Some((rust_type, expression)) = self.expression_definition() {
            hash_bytes(&mut hash, b"expression");
            hash_bytes(&mut hash, rust_type.as_bytes());
            hash_bytes(&mut hash, &[0]);
            hash_bytes(&mut hash, expression.as_bytes());
            return Ok(hash);
        }

        let storage = self.storage();
        hash_bytes(&mut hash, b"numeric");
        hash_bytes(&mut hash, storage.rust_type().as_bytes());
        hash_bytes(
            &mut hash,
            self.quantity
                .map_or("primitive", |quantity| quantity.name())
                .as_bytes(),
        );

        if self.quantity.is_some() {
            match storage {
                ConstantStorage::F32 => {
                    let (is_array, values) = self.normalized_f32()?;
                    hash_bytes(&mut hash, &[u8::from(is_array)]);
                    for value in values {
                        hash_bytes(&mut hash, &value.to_bits().to_le_bytes());
                    }
                }
                ConstantStorage::F64 => {
                    let (is_array, values) = self.normalized_f64()?;
                    hash_bytes(&mut hash, &[u8::from(is_array)]);
                    for value in values {
                        hash_bytes(&mut hash, &value.to_bits().to_le_bytes());
                    }
                }
                _ => {
                    return Err(format!(
                        "Constant '{}' quantity storage must be f32 or f64",
                        self.id
                    ));
                }
            }
            return Ok(hash);
        }

        let (is_array, numbers) = self.numbers()?;
        hash_bytes(&mut hash, &[u8::from(is_array)]);
        for number in numbers {
            match (storage, number) {
                (ConstantStorage::F32, number) => {
                    hash_bytes(&mut hash, &(number.as_f64() as f32).to_bits().to_le_bytes())
                }
                (ConstantStorage::F64, number) => {
                    hash_bytes(&mut hash, &number.as_f64().to_bits().to_le_bytes())
                }
                (_, ConstantNumber::Signed(value)) => hash_bytes(&mut hash, &value.to_le_bytes()),
                (_, ConstantNumber::Unsigned(value)) => hash_bytes(&mut hash, &value.to_le_bytes()),
                (_, ConstantNumber::Float(value)) => {
                    hash_bytes(&mut hash, &value.to_bits().to_le_bytes())
                }
            }
        }
        Ok(hash)
    }
}

#[derive(Debug, Clone, PartialEq)]
pub struct ConfigError {
    message: String,
}

impl ConfigError {
    fn type_mismatch(expected: &'static str, value: &Value) -> Self {
        ConfigError {
            message: format!("Expected {expected} but got {value:?}"),
        }
    }

    fn with_key(self, key: &str) -> Self {
        ConfigError {
            message: format!("Config key '{key}': {}", self.message),
        }
    }
}

impl Display for ConfigError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.message)
    }
}

#[cfg(feature = "std")]
impl std::error::Error for ConfigError {}

#[cfg(not(feature = "std"))]
impl core::error::Error for ConfigError {}

impl From<ConfigError> for CuError {
    fn from(err: ConfigError) -> Self {
        CuError::from(err.to_string())
    }
}

// Macro for implementing From<T> for Value where T is a numeric type
macro_rules! impl_from_numeric_for_value {
    ($($source:ty),* $(,)?) => {
        $(impl From<$source> for Value {
            fn from(value: $source) -> Self {
                Value(RonValue::Number(value.into()))
            }
        })*
    };
}

// Implement From for common numeric types
impl_from_numeric_for_value!(i8, i16, i32, i64, u8, u16, u32, u64, f32, f64);

impl TryFrom<&Value> for bool {
    type Error = ConfigError;

    fn try_from(value: &Value) -> Result<Self, Self::Error> {
        if let Value(RonValue::Bool(v)) = value {
            Ok(*v)
        } else {
            Err(ConfigError::type_mismatch("bool", value))
        }
    }
}

impl From<Value> for bool {
    fn from(value: Value) -> Self {
        if let Value(RonValue::Bool(v)) = value {
            v
        } else {
            panic!("Expected a Boolean variant but got {value:?}")
        }
    }
}
macro_rules! impl_from_value_for_int {
    ($($target:ty),* $(,)?) => {
        $(
            impl From<Value> for $target {
                fn from(value: Value) -> Self {
                    if let Value(RonValue::Number(num)) = value {
                        match num {
                            Number::I8(n) => n as $target,
                            Number::I16(n) => n as $target,
                            Number::I32(n) => n as $target,
                            Number::I64(n) => n as $target,
                            Number::U8(n) => n as $target,
                            Number::U16(n) => n as $target,
                            Number::U32(n) => n as $target,
                            Number::U64(n) => n as $target,
                            Number::F32(_) | Number::F64(_) => {
                                panic!("Expected an integer Number variant but got {num:?}")
                            }
                            _ => {
                                panic!("Expected an integer Number variant but got {num:?}")
                            }
                        }
                    } else {
                        panic!("Expected a Number variant but got {value:?}")
                    }
                }
            }
        )*
    };
}

impl_from_value_for_int!(u8, i8, u16, i16, u32, i32, u64, i64);

macro_rules! impl_try_from_value_for_int {
    ($($target:ty),* $(,)?) => {
        $(
            impl TryFrom<&Value> for $target {
                type Error = ConfigError;

                fn try_from(value: &Value) -> Result<Self, Self::Error> {
                    if let Value(RonValue::Number(num)) = value {
                        match num {
                            Number::I8(n) => Ok(*n as $target),
                            Number::I16(n) => Ok(*n as $target),
                            Number::I32(n) => Ok(*n as $target),
                            Number::I64(n) => Ok(*n as $target),
                            Number::U8(n) => Ok(*n as $target),
                            Number::U16(n) => Ok(*n as $target),
                            Number::U32(n) => Ok(*n as $target),
                            Number::U64(n) => Ok(*n as $target),
                            Number::F32(_) | Number::F64(_) => {
                                Err(ConfigError::type_mismatch("integer", value))
                            }
                            _ => {
                                Err(ConfigError::type_mismatch("integer", value))
                            }
                        }
                    } else {
                        Err(ConfigError::type_mismatch("integer", value))
                    }
                }
            }
        )*
    };
}

impl_try_from_value_for_int!(u8, i8, u16, i16, u32, i32, u64, i64);

impl TryFrom<&Value> for f64 {
    type Error = ConfigError;

    fn try_from(value: &Value) -> Result<Self, Self::Error> {
        if let Value(RonValue::Number(num)) = value {
            let number = match num {
                Number::I8(n) => *n as f64,
                Number::I16(n) => *n as f64,
                Number::I32(n) => *n as f64,
                Number::I64(n) => *n as f64,
                Number::U8(n) => *n as f64,
                Number::U16(n) => *n as f64,
                Number::U32(n) => *n as f64,
                Number::U64(n) => *n as f64,
                Number::F32(n) => n.0 as f64,
                Number::F64(n) => n.0,
                _ => {
                    return Err(ConfigError::type_mismatch("number", value));
                }
            };
            Ok(number)
        } else {
            Err(ConfigError::type_mismatch("number", value))
        }
    }
}

impl From<Value> for f64 {
    fn from(value: Value) -> Self {
        if let Value(RonValue::Number(num)) = value {
            num.into_f64()
        } else {
            panic!("Expected a Number variant but got {value:?}")
        }
    }
}

//Basically just a copy of the From<Value> for f64.
impl TryFrom<&Value> for f32 {
    type Error = ConfigError;

    fn try_from(value: &Value) -> Result<Self, Self::Error> {
        if let Value(RonValue::Number(num)) = value {
            let number = match num {
                Number::I8(n) => *n as f32,
                Number::I16(n) => *n as f32,
                Number::I32(n) => *n as f32,
                Number::I64(n) => *n as f32,
                Number::U8(n) => *n as f32,
                Number::U16(n) => *n as f32,
                Number::U32(n) => *n as f32,
                Number::U64(n) => *n as f32,
                Number::F32(n) => n.0,
                Number::F64(n) => n.0 as f32,
                _ => {
                    return Err(ConfigError::type_mismatch("number", value));
                }
            };
            Ok(number)
        } else {
            Err(ConfigError::type_mismatch("number", value))
        }
    }
}

impl From<Value> for f32 {
    fn from(value: Value) -> Self {
        if let Value(RonValue::Number(num)) = value {
            num.into_f64() as f32
        } else {
            panic!("Expected a Number variant but got {value:?}")
        }
    }
}

impl From<String> for Value {
    fn from(value: String) -> Self {
        Value(RonValue::String(value))
    }
}

impl TryFrom<&Value> for String {
    type Error = ConfigError;

    fn try_from(value: &Value) -> Result<Self, Self::Error> {
        if let Value(RonValue::String(s)) = value {
            Ok(s.clone())
        } else {
            Err(ConfigError::type_mismatch("string", value))
        }
    }
}

impl From<Value> for String {
    fn from(value: Value) -> Self {
        if let Value(RonValue::String(s)) = value {
            s
        } else {
            panic!("Expected a String variant")
        }
    }
}

impl Display for Value {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let Value(value) = self;
        match value {
            RonValue::Number(n) => {
                let s = match n {
                    Number::I8(n) => n.to_string(),
                    Number::I16(n) => n.to_string(),
                    Number::I32(n) => n.to_string(),
                    Number::I64(n) => n.to_string(),
                    Number::U8(n) => n.to_string(),
                    Number::U16(n) => n.to_string(),
                    Number::U32(n) => n.to_string(),
                    Number::U64(n) => n.to_string(),
                    Number::F32(n) => n.0.to_string(),
                    Number::F64(n) => n.0.to_string(),
                    _ => panic!("Expected a Number variant but got {value:?}"),
                };
                write!(f, "{s}")
            }
            RonValue::String(s) => write!(f, "{s}"),
            RonValue::Bool(b) => write!(f, "{b}"),
            RonValue::Map(m) => write!(f, "{m:?}"),
            RonValue::Char(c) => write!(f, "{c:?}"),
            RonValue::Unit => write!(f, "unit"),
            RonValue::Option(o) => write!(f, "{o:?}"),
            RonValue::Seq(s) => write!(f, "{s:?}"),
            RonValue::Bytes(bytes) => write!(f, "{bytes:?}"),
        }
    }
}

/// Logging policy for a `CuHandle`'s payload content.
///
/// Set by the source that produces the handle (typically via this enum's slot under
/// `NodeLogging`) and propagated through clones. The unified-log encoder reads this to
/// decide whether to write the payload bytes or just a metadata-only record for the
/// frame. See `cu29_runtime::pool::CuHandle` for the runtime side.
///
/// Defined here (instead of in `pool.rs`) so the type is reachable from both the
/// library and the `cu29-rendercfg` binary, which compiles `config.rs` standalone.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default)]
#[repr(u8)]
pub enum HandleContent {
    /// Always log the full payload (current default).
    #[serde(rename = "all", alias = "All")]
    #[default]
    All = 0,
    /// Log the payload only if a downstream consumer called `CuHandle::mark_touched`.
    #[serde(rename = "touched_only", alias = "TouchedOnly")]
    TouchedOnly = 1,
    /// Never log the payload; keep only the surrounding metadata (timestamps, status).
    #[serde(rename = "none", alias = "None")]
    None = 2,
}

impl HandleContent {
    /// Reconstruct a [`HandleContent`] from its `AtomicU8` representation. Unknown
    /// values fall back to `All` so corrupt state never silently drops payload bytes.
    #[allow(dead_code)] // Only the lib's pool module calls this; the rendercfg bin doesn't.
    pub fn from_u8(v: u8) -> Self {
        match v {
            1 => HandleContent::TouchedOnly,
            2 => HandleContent::None,
            _ => HandleContent::All,
        }
    }
}

/// Configuration for logging in the node.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct NodeLogging {
    #[serde(default = "default_as_true")]
    enabled: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    codec: Option<String>,
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    codecs: HashMap<String, String>,
    /// Logging policy applied to the source's pool-acquired `CuHandle`s. Surfaced
    /// in user RON config as e.g. `logging: ( handle_content: "touched_only" )`.
    #[serde(default, skip_serializing_if = "is_default_handle_content")]
    handle_content: HandleContent,
}

fn is_default_handle_content(c: &HandleContent) -> bool {
    *c == HandleContent::default()
}

impl NodeLogging {
    #[allow(dead_code)]
    pub fn enabled(&self) -> bool {
        self.enabled
    }

    #[allow(dead_code)]
    pub fn codec(&self) -> Option<&str> {
        self.codec.as_deref()
    }

    #[allow(dead_code)]
    pub fn codecs(&self) -> &HashMap<String, String> {
        &self.codecs
    }

    #[allow(dead_code)]
    pub fn codec_for_msg_type(&self, msg_type: &str) -> Option<&str> {
        self.codecs
            .get(msg_type)
            .map(String::as_str)
            .or(self.codec.as_deref())
    }

    /// Logging policy applied to handles minted by this node's pool. Defaults to
    /// `HandleContent::All` — i.e. existing behavior.
    pub fn handle_content(&self) -> HandleContent {
        self.handle_content
    }
}

impl Default for NodeLogging {
    fn default() -> Self {
        Self {
            enabled: true,
            codec: None,
            codecs: HashMap::new(),
            handle_content: HandleContent::default(),
        }
    }
}

/// Distinguishes regular tasks from bridge nodes so downstream stages can apply
/// bridge-specific instantiation rules.
#[derive(Default, Debug, Copy, Clone, PartialEq, Eq)]
pub enum Flavor {
    #[default]
    Task,
    Bridge,
}

/// Declares which Copper task trait a task node implements.
///
/// This lets config express the runtime role explicitly instead of forcing the
/// proc-macro to guess from graph shape alone.
#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq)]
pub enum TaskKind {
    #[serde(rename = "source", alias = "src")]
    Source,
    #[serde(rename = "task", alias = "regular", alias = "cutask")]
    Regular,
    #[serde(rename = "sink", alias = "snk")]
    Sink,
}

impl TaskKind {
    #[allow(dead_code)]
    pub fn as_str(&self) -> &'static str {
        match self {
            TaskKind::Source => "source",
            TaskKind::Regular => "task",
            TaskKind::Sink => "sink",
        }
    }
}

/// Default thread pool name used by `background: true` tasks.
pub const DEFAULT_BACKGROUND_POOL: &str = "background";

/// Reserved thread pool name driving the `parallel-rt` execution engine. Applied
/// to each stage worker at startup; never task-bound nor built as a rayon pool.
#[allow(dead_code)] // consumed by cu29_derive; unused in some binary targets
pub const RT_POOL: &str = "rt";

/// How a task is backgrounded.
///
/// Either a simple on/off flag (`background: true`), which runs the task on the
/// default [`DEFAULT_BACKGROUND_POOL`] pool, or an explicit pool selection
/// (`background: (pool: "vision")`).
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(untagged)]
pub enum BackgroundConfig {
    /// `background: true` / `background: false`.
    Flag(bool),
    /// `background: (pool: "vision")`.
    Pool { pool: String },
}

/// Refinement policy for an anytime node (`anytime:` on a task).
///
/// Every field is optional, but validation requires at least one - `time_budget_ms`,
/// `max_age_ms` and `max_refines`; see [`CuConfig::validate_anytime_configs`].
///
/// Two orthogonal axes organize the fields:
///
/// - **Budget** — how much to *spend* per result: `time_budget_ms` and
///   `max_refines` are hard bounds, `quality_target` and `max_stall` stop
///   spending early when more is provably not worth it.
/// - **Utility** — whether the result is *worth having* at all: `max_age_ms`
///   (worthless because too old) and `quality_floor` (worthless because too
///   crude).
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)]
pub struct AnytimeConfig {
    /// Wall-clock window for one job in milliseconds, measured from the start of
    /// the base computation and checked *between* refinement quanta.
    /// In background placement it is measured on the worker thread and may exceed the
    /// copperlist period.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub time_budget_ms: Option<f64>,

    /// Validity deadline in milliseconds, measured from the input's earliest time
    /// of validity (Tov): past this data age a result is no longer worth starting
    /// or waiting for.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_age_ms: Option<f64>,

    /// Stop refining early once the reported quality reaches this target, in
    /// `(0.0, 1.0]` on the normalized quality scale. Only valid for tasks that
    /// report a comparable quality.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub quality_target: Option<f32>,

    /// Publish only if the final reported quality is at least this floor, in
    /// `(0.0, 1.0)` on the normalized quality scale; below it the payload is
    /// cleared. Only valid for tasks that report a comparable quality.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub quality_floor: Option<f32>,

    /// Hard bound on refinement quanta per job.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_refines: Option<u32>,

    /// Stop after this many quanta without the published quality improving.
    /// Only valid for tasks that report a comparable quality.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_stall: Option<u32>,
}

impl AnytimeConfig {
    /// Validates the node-local invariants of this policy.
    ///
    /// Ranges are written as positive containment checks so a NaN coming from
    /// the RON fails the check and is rejected, and at least one hard bound is
    /// mandatory: `quality_target`, `max_stall` and `quality_floor` alone leave
    /// refinement unbounded.
    fn validate(&self, task_id: &str) -> CuResult<()> {
        if let Some(budget) = self.time_budget_ms {
            let valid = budget.is_finite() && budget > 0.0;
            if !valid {
                return Err(CuError::from(format!(
                    "Task '{task_id}': anytime.time_budget_ms must be a positive number of milliseconds (got {budget})."
                )));
            }
        }
        if let Some(age) = self.max_age_ms {
            let valid = age.is_finite() && age > 0.0;
            if !valid {
                return Err(CuError::from(format!(
                    "Task '{task_id}': anytime.max_age_ms must be a positive number of milliseconds (got {age})."
                )));
            }
        }
        if let Some(target) = self.quality_target {
            let valid = target > 0.0 && target <= 1.0;
            if !valid {
                return Err(CuError::from(format!(
                    "Task '{task_id}': anytime.quality_target must be within (0.0, 1.0] (got {target})."
                )));
            }
        }
        if let Some(floor) = self.quality_floor {
            let valid = floor > 0.0 && floor < 1.0;
            if !valid {
                return Err(CuError::from(format!(
                    "Task '{task_id}': anytime.quality_floor must be within (0.0, 1.0) (got {floor})."
                )));
            }
        }
        if let Some(refines) = self.max_refines
            && refines == 0
        {
            return Err(CuError::from(format!(
                "Task '{task_id}': anytime.max_refines must be at least 1."
            )));
        }
        if let Some(stall) = self.max_stall
            && stall == 0
        {
            return Err(CuError::from(format!(
                "Task '{task_id}': anytime.max_stall must be at least 1."
            )));
        }
        if let (Some(floor), Some(target)) = (self.quality_floor, self.quality_target)
            && floor > target
        {
            return Err(CuError::from(format!(
                "Task '{task_id}': anytime.quality_floor ({floor}) must not exceed anytime.quality_target ({target}): refinement could stop at the target and then always discard the result."
            )));
        }
        if self.time_budget_ms.is_none() && self.max_age_ms.is_none() && self.max_refines.is_none()
        {
            return Err(CuError::from(format!(
                "Task '{task_id}': anytime needs at least one hard bound: set time_budget_ms, max_age_ms or max_refines. quality_target, max_stall and quality_floor alone leave refinement unbounded."
            )));
        }
        Ok(())
    }
}

/// Whether a task output is transmitted or deterministically recomputed on the ground.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, Default, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum StreamReplay {
    #[default]
    Capture,
    Reconstruct,
}

/// Static streaming contract for an ordinary deterministic task.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, Default)]
#[serde(deny_unknown_fields)]
pub struct NodeStreaming {
    #[serde(default)]
    pub replay: StreamReplay,
}

/// A node in the configuration graph.
/// A node represents a Task in the system Graph.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct Node {
    /// Unique node identifier.
    id: String,

    /// Task rust struct underlying type, e.g. "mymodule::Sensor", etc.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    type_: Option<String>,

    /// Declared Copper task role. When omitted, legacy configs still infer it
    /// from graph shape when that is unambiguous.
    #[serde(skip_serializing_if = "Option::is_none")]
    kind: Option<TaskKind>,

    /// Config passed to the task.
    #[serde(skip_serializing_if = "Option::is_none")]
    config: Option<ComponentConfig>,

    /// Resources requested by the task.
    #[serde(skip_serializing_if = "Option::is_none")]
    resources: Option<HashMap<String, String>>,

    /// Missions for which this task is run.
    missions: Option<Vec<String>>,

    /// Run this task in the background:
    /// ie. Will be set to run on a background thread and until it is finished `CuTask::process` will return None.
    ///
    /// Accepts either a simple flag (`background: true`, which uses the default
    /// [`DEFAULT_BACKGROUND_POOL`] pool) or an explicit pool selection
    /// (`background: (pool: "vision")`).
    #[serde(skip_serializing_if = "Option::is_none")]
    background: Option<BackgroundConfig>,

    /// Anytime refinement policy for this task (base + bounded refinements).
    ///
    /// Only supported on regular tasks. Orthogonal to `background:`, which adds
    /// the async placement layer on top of the refinement loop.
    #[serde(skip_serializing_if = "Option::is_none")]
    anytime: Option<AnytimeConfig>,

    /// Option to include/exclude stubbing for simulation.
    /// By default, sources and sinks are replaces (stubbed) by the runtime to avoid trying to compile hardware specific code for sensing or actuation.
    /// In some cases, for example a sink or source used as a middleware bridge, you might want to run the real code even in simulation.
    /// This option allows to control this behavior.
    /// Note: Normal tasks will be run in sim and this parameter ignored.
    #[serde(skip_serializing_if = "Option::is_none")]
    run_in_sim: Option<bool>,

    /// Config passed to the task.
    #[serde(skip_serializing_if = "Option::is_none")]
    logging: Option<NodeLogging>,

    #[serde(skip_serializing_if = "Option::is_none")]
    streaming: Option<NodeStreaming>,

    /// Node role in the runtime graph (normal task or bridge endpoint).
    #[serde(skip, default)]
    flavor: Flavor,
    /// Message types that are intentionally not connected (NC) in configuration.
    #[serde(skip, default)]
    nc_outputs: Vec<String>,
    /// Original config connection order for each NC output message type.
    #[serde(skip, default)]
    nc_output_orders: Vec<usize>,
}

impl Node {
    #[allow(dead_code)]
    pub fn new(id: &str, ptype: &str) -> Self {
        Node {
            id: id.to_string(),
            type_: Some(ptype.to_string()),
            kind: None,
            config: None,
            resources: None,
            missions: None,
            background: None,
            anytime: None,
            run_in_sim: None,
            logging: None,
            streaming: None,
            flavor: Flavor::Task,
            nc_outputs: Vec::new(),
            nc_output_orders: Vec::new(),
        }
    }

    #[allow(dead_code)]
    pub fn new_with_flavor(id: &str, ptype: &str, flavor: Flavor) -> Self {
        let mut node = Self::new(id, ptype);
        node.flavor = flavor;
        node
    }

    #[allow(dead_code)]
    pub fn get_id(&self) -> String {
        self.id.clone()
    }

    #[allow(dead_code)]
    pub fn get_type(&self) -> &str {
        self.type_.as_ref().unwrap()
    }

    #[allow(dead_code)]
    pub fn set_type(mut self, name: Option<String>) -> Self {
        self.type_ = name;
        self
    }

    #[allow(dead_code)]
    pub fn get_declared_task_kind(&self) -> Option<TaskKind> {
        self.kind
    }

    #[allow(dead_code)]
    pub fn set_task_kind(&mut self, kind: Option<TaskKind>) {
        self.kind = kind;
    }

    #[allow(dead_code)]
    pub fn set_resources<I>(&mut self, resources: Option<I>)
    where
        I: IntoIterator<Item = (String, String)>,
    {
        self.resources = resources.map(|iter| iter.into_iter().collect());
    }

    #[allow(dead_code)]
    pub fn is_background(&self) -> bool {
        match &self.background {
            Some(BackgroundConfig::Flag(flag)) => *flag,
            Some(BackgroundConfig::Pool { .. }) => true,
            None => false,
        }
    }

    /// Name of the thread pool this task should run on when backgrounded.
    /// Defaults to [`DEFAULT_BACKGROUND_POOL`] when no explicit pool is set.
    #[allow(dead_code)]
    pub fn background_pool(&self) -> &str {
        match &self.background {
            Some(BackgroundConfig::Pool { pool }) => pool.as_str(),
            _ => DEFAULT_BACKGROUND_POOL,
        }
    }

    #[allow(dead_code)]
    pub fn is_anytime(&self) -> bool {
        self.anytime.is_some()
    }

    /// Anytime refinement policy configured on this node, if any.
    #[allow(dead_code)]
    pub fn anytime(&self) -> Option<&AnytimeConfig> {
        self.anytime.as_ref()
    }

    /// Sets the anytime refinement policy for this node.
    #[allow(dead_code)]
    pub fn set_anytime(&mut self, anytime: Option<AnytimeConfig>) {
        self.anytime = anytime;
    }

    #[allow(dead_code)]
    pub fn get_instance_config(&self) -> Option<&ComponentConfig> {
        self.config.as_ref()
    }

    #[allow(dead_code)]
    pub fn get_resources(&self) -> Option<&HashMap<String, String>> {
        self.resources.as_ref()
    }

    /// By default, assume a source or a sink is not run in sim.
    /// Normal tasks will be run in sim and this parameter ignored.
    #[allow(dead_code)]
    pub fn is_run_in_sim(&self) -> bool {
        self.run_in_sim.unwrap_or(false)
    }

    #[allow(dead_code)]
    pub fn is_logging_enabled(&self) -> bool {
        if let Some(logging) = &self.logging {
            logging.enabled()
        } else {
            true
        }
    }

    /// Convenience wrapper around [`NodeLogging::handle_content`]: returns the per-handle
    /// logging policy for this node, defaulting to [`HandleContent::All`] when no
    /// `logging` block is configured.
    #[allow(dead_code)]
    pub fn handle_content_policy(&self) -> HandleContent {
        self.logging
            .as_ref()
            .map(NodeLogging::handle_content)
            .unwrap_or_default()
    }

    #[allow(dead_code)]
    pub fn streaming(&self) -> NodeStreaming {
        self.streaming.unwrap_or_default()
    }

    #[allow(dead_code)]
    pub fn get_logging(&self) -> Option<&NodeLogging> {
        self.logging.as_ref()
    }

    #[allow(dead_code)]
    pub fn get_param<T>(&self, key: &str) -> Result<Option<T>, ConfigError>
    where
        T: for<'a> TryFrom<&'a Value, Error = ConfigError>,
    {
        let pc = match self.config.as_ref() {
            Some(pc) => pc,
            None => return Ok(None),
        };
        let ComponentConfig(pc) = pc;
        match pc.get(key) {
            Some(v) => T::try_from(v).map(Some),
            None => Ok(None),
        }
    }

    #[allow(dead_code)]
    pub fn set_param<T: Into<Value>>(&mut self, key: &str, value: T) {
        if self.config.is_none() {
            self.config = Some(ComponentConfig(HashMap::new()));
        }
        let ComponentConfig(config) = self.config.as_mut().unwrap();
        config.insert(key.to_string(), value.into());
    }

    /// Returns whether this node is treated as a normal task or as a bridge.
    #[allow(dead_code)]
    pub fn get_flavor(&self) -> Flavor {
        self.flavor
    }

    /// Overrides the node flavor; primarily used when injecting bridge nodes.
    #[allow(dead_code)]
    pub fn set_flavor(&mut self, flavor: Flavor) {
        self.flavor = flavor;
    }

    /// Registers an intentionally unconnected output message type for this node.
    #[allow(dead_code)]
    pub fn add_nc_output(&mut self, msg_type: &str, order: usize) {
        if let Some(pos) = self
            .nc_outputs
            .iter()
            .position(|existing| existing == msg_type)
        {
            if order < self.nc_output_orders[pos] {
                self.nc_output_orders[pos] = order;
            }
            return;
        }
        self.nc_outputs.push(msg_type.to_string());
        self.nc_output_orders.push(order);
    }

    /// Returns message types intentionally marked as not connected.
    #[allow(dead_code)]
    pub fn nc_outputs(&self) -> &[String] {
        &self.nc_outputs
    }

    /// Returns NC outputs paired with original config order.
    #[allow(dead_code)]
    pub fn nc_outputs_with_order(&self) -> impl Iterator<Item = (&String, usize)> {
        self.nc_outputs
            .iter()
            .zip(self.nc_output_orders.iter().copied())
    }
}

/// Directional mapping for bridge channels.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub enum BridgeChannelConfigRepresentation {
    /// Channel that receives data from the bridge into the graph.
    Rx {
        id: String,
        /// Optional transport/topic identifier specific to the bridge backend.
        #[serde(skip_serializing_if = "Option::is_none")]
        route: Option<String>,
        /// Optional per-channel configuration forwarded to the bridge implementation.
        #[serde(skip_serializing_if = "Option::is_none")]
        config: Option<ComponentConfig>,
    },
    /// Channel that transmits data from the graph into the bridge.
    Tx {
        id: String,
        /// Optional transport/topic identifier specific to the bridge backend.
        #[serde(skip_serializing_if = "Option::is_none")]
        route: Option<String>,
        /// Optional per-channel configuration forwarded to the bridge implementation.
        #[serde(skip_serializing_if = "Option::is_none")]
        config: Option<ComponentConfig>,
    },
}

impl BridgeChannelConfigRepresentation {
    /// Stable logical identifier to reference this channel in connections.
    #[allow(dead_code)]
    pub fn id(&self) -> &str {
        match self {
            BridgeChannelConfigRepresentation::Rx { id, .. }
            | BridgeChannelConfigRepresentation::Tx { id, .. } => id,
        }
    }

    /// Bridge-specific transport path (topic, route, path...) describing this channel.
    #[allow(dead_code)]
    pub fn route(&self) -> Option<&str> {
        match self {
            BridgeChannelConfigRepresentation::Rx { route, .. }
            | BridgeChannelConfigRepresentation::Tx { route, .. } => route.as_deref(),
        }
    }
}

enum EndpointRole {
    Source,
    Destination,
}

fn validate_bridge_channel(
    bridge: &BridgeConfig,
    channel_id: &str,
    role: EndpointRole,
) -> Result<(), String> {
    let channel = bridge
        .channels
        .iter()
        .find(|ch| ch.id() == channel_id)
        .ok_or_else(|| {
            format!(
                "Bridge '{}' does not declare a channel named '{}'",
                bridge.id, channel_id
            )
        })?;

    match (role, channel) {
        (EndpointRole::Source, BridgeChannelConfigRepresentation::Rx { .. }) => Ok(()),
        (EndpointRole::Destination, BridgeChannelConfigRepresentation::Tx { .. }) => Ok(()),
        (EndpointRole::Source, BridgeChannelConfigRepresentation::Tx { .. }) => Err(format!(
            "Bridge '{}' channel '{}' is Tx and cannot act as a source",
            bridge.id, channel_id
        )),
        (EndpointRole::Destination, BridgeChannelConfigRepresentation::Rx { .. }) => Err(format!(
            "Bridge '{}' channel '{}' is Rx and cannot act as a destination",
            bridge.id, channel_id
        )),
    }
}

/// Declarative definition of a resource bundle.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ResourceBundleConfig {
    /// Resource inputs consumed by this provider at startup.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub resources: Option<HashMap<String, String>>,
    pub id: String,
    #[serde(rename = "provider")]
    pub provider: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub config: Option<ComponentConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub missions: Option<Vec<String>>,
}

/// Static log-streaming policy compiled into a Copper application.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LogStreamingConfig {
    pub destinations: Vec<LogStreamDestinationConfig>,
}

/// One statically generated log-stream destination.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LogStreamDestinationConfig {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub feedback: Option<LogStreamFeedbackConfig>,
    pub id: String,
    pub transport: LogStreamTransportConfig,
    pub link: LogStreamLinkConfig,
    pub fec: LogStreamFecConfig,
    /// Recovery interval in CopperLists; a nonzero multiple of logging.keyframe_interval.
    pub recovery_interval: u32,
    pub max_record_bytes: u64,
}

/// Explicit reverse resource and advisory feedback policy for one destination.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LogStreamFeedbackConfig {
    pub transport: LogStreamTransportConfig,
    pub report_interval_ms: u32,
    pub timeout_ms: u32,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub adaptation: Option<LogStreamAdaptationConfig>,
}

/// Bounds on the number of future source symbols between continuous repairs.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LogStreamAdaptationConfig {
    pub min_repair_every_source_symbols: u16,
    pub max_repair_every_source_symbols: u16,
}

/// Concrete Copper resource used as the destination's packet transmitter.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LogStreamTransportConfig {
    #[serde(rename = "type")]
    pub type_: String,
    pub resource: String,
}

/// Physical-link assumptions and sender bounds.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LogStreamLinkConfig {
    pub mtu_bytes: u16,
    pub bitrate_bps: u64,
    pub memory_budget_kib: u32,
    pub max_latency_ms: u32,
    pub burst_packets: u32,
}

/// Explicit FEC policy. Lane identity fixes the algorithms: continuous is RLC
/// and objects is RaptorQ, so there is deliberately no configurable scheme.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LogStreamFecConfig {
    pub continuous: LogStreamContinuousFecConfig,
    pub objects: LogStreamObjectFecConfig,
}

#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LogStreamContinuousFecConfig {
    pub field: LogStreamRlcField,
    pub window_symbols: u16,
    pub repair_every_source_symbols: u16,
    pub repair_density: LogStreamRepairDensity,
}

#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
pub enum LogStreamRlcField {
    Gf2,
    Gf256,
}

#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
pub enum LogStreamRepairDensity {
    Full,
    Threshold(u8),
}

impl LogStreamRepairDensity {
    pub const fn threshold(self) -> u8 {
        match self {
            Self::Full => 15,
            Self::Threshold(value) => value,
        }
    }
}

#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LogStreamObjectFecConfig {
    pub max_object_bytes: u64,
    pub repair_symbols_per_block: u32,
}

/// Declarative definition of a bridge component with a list of channels.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct BridgeConfig {
    pub id: String,
    #[serde(rename = "type")]
    pub type_: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub config: Option<ComponentConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub resources: Option<HashMap<String, String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub missions: Option<Vec<String>>,
    /// Whether this bridge should run as the real implementation in simulation mode.
    ///
    /// Default is `true` to preserve historical behavior where bridges were always
    /// instantiated in sim mode.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub run_in_sim: Option<bool>,
    /// List of logical endpoints exposed by this bridge.
    pub channels: Vec<BridgeChannelConfigRepresentation>,
}

impl BridgeConfig {
    /// By default, bridges run as real implementations in sim mode for backward compatibility.
    #[allow(dead_code)]
    pub fn is_run_in_sim(&self) -> bool {
        self.run_in_sim.unwrap_or(true)
    }

    fn to_node(&self) -> Node {
        let mut node = Node::new_with_flavor(&self.id, &self.type_, Flavor::Bridge);
        node.config = self.config.clone();
        node.resources = self.resources.clone();
        node.missions = self.missions.clone();
        node
    }
}

fn insert_bridge_node(graph: &mut CuGraph, bridge: &BridgeConfig) -> Result<(), String> {
    if graph.get_node_id_by_name(bridge.id.as_str()).is_some() {
        return Err(format!(
            "Bridge '{}' reuses an existing node id. Bridge ids must be unique.",
            bridge.id
        ));
    }
    graph
        .add_node(bridge.to_node())
        .map(|_| ())
        .map_err(|e| e.to_string())
}

/// Serialized representation of a connection used for the RON config.
#[derive(Serialize, Deserialize, Debug, Clone)]
struct SerializedCnx {
    src: String,
    dst: String,
    msg: String,
    missions: Option<Vec<String>>,
}

/// Special destination endpoint used to mark an output as intentionally not connected.
pub const NC_ENDPOINT: &str = "__nc__";

/// This represents a connection between 2 tasks (nodes) in the configuration graph.
#[derive(Debug, Clone)]
pub struct Cnx {
    /// Source node id.
    pub src: String,
    /// Destination node id.
    pub dst: String,
    /// Message type exchanged between src and dst.
    pub msg: String,
    /// Restrict this connection for this list of missions.
    pub missions: Option<Vec<String>>,
    /// Optional channel id when the source endpoint is a bridge.
    pub src_channel: Option<String>,
    /// Optional channel id when the destination endpoint is a bridge.
    pub dst_channel: Option<String>,
    /// Original serialized connection index used to preserve output ordering.
    pub order: usize,
}

impl From<&Cnx> for SerializedCnx {
    fn from(cnx: &Cnx) -> Self {
        SerializedCnx {
            src: format_endpoint(&cnx.src, cnx.src_channel.as_deref()),
            dst: format_endpoint(&cnx.dst, cnx.dst_channel.as_deref()),
            msg: cnx.msg.clone(),
            missions: cnx.missions.clone(),
        }
    }
}

fn format_endpoint(node: &str, channel: Option<&str>) -> String {
    match channel {
        Some(ch) => format!("{node}/{ch}"),
        None => node.to_string(),
    }
}

fn parse_endpoint(
    endpoint: &str,
    role: EndpointRole,
    bridges: &HashMap<&str, &BridgeConfig>,
) -> Result<(String, Option<String>), String> {
    if let Some((node, channel)) = endpoint.split_once('/') {
        if let Some(bridge) = bridges.get(node) {
            validate_bridge_channel(bridge, channel, role)?;
            return Ok((node.to_string(), Some(channel.to_string())));
        } else {
            return Err(format!(
                "Endpoint '{endpoint}' references an unknown bridge '{node}'"
            ));
        }
    }

    if let Some(bridge) = bridges.get(endpoint) {
        return Err(format!(
            "Bridge '{}' connections must reference a channel using '{}/<channel>'",
            bridge.id, bridge.id
        ));
    }

    Ok((endpoint.to_string(), None))
}

fn build_bridge_lookup(bridges: Option<&Vec<BridgeConfig>>) -> HashMap<&str, &BridgeConfig> {
    let mut map = HashMap::new();
    if let Some(bridges) = bridges {
        for bridge in bridges {
            map.insert(bridge.id.as_str(), bridge);
        }
    }
    map
}

fn mission_applies(missions: &Option<Vec<String>>, mission_id: &str) -> bool {
    missions
        .as_ref()
        .map(|mission_list| mission_list.iter().any(|m| m == mission_id))
        .unwrap_or(true)
}

fn merge_connection_missions(existing: &mut Option<Vec<String>>, incoming: &Option<Vec<String>>) {
    if incoming.is_none() {
        *existing = None;
        return;
    }
    if existing.is_none() {
        return;
    }

    if let (Some(existing_missions), Some(incoming_missions)) =
        (existing.as_mut(), incoming.as_ref())
    {
        for mission in incoming_missions {
            if !existing_missions
                .iter()
                .any(|existing_mission| existing_mission == mission)
            {
                existing_missions.push(mission.clone());
            }
        }
        existing_missions.sort();
        existing_missions.dedup();
    }
}

fn register_nc_output<E>(
    graph: &mut CuGraph,
    src_endpoint: &str,
    msg_type: &str,
    order: usize,
    bridge_lookup: &HashMap<&str, &BridgeConfig>,
) -> Result<(), E>
where
    E: From<String>,
{
    let (src_name, src_channel) =
        parse_endpoint(src_endpoint, EndpointRole::Source, bridge_lookup).map_err(E::from)?;
    if src_channel.is_some() {
        return Err(E::from(format!(
            "NC destination '{}' does not support bridge channels in source endpoint '{}'",
            NC_ENDPOINT, src_endpoint
        )));
    }

    let src = graph
        .get_node_id_by_name(src_name.as_str())
        .ok_or_else(|| E::from(format!("Source node not found: {src_endpoint}")))?;
    let src_node = graph
        .get_node_mut(src)
        .ok_or_else(|| E::from(format!("Source node id {src} not found for NC output")))?;
    if src_node.get_flavor() != Flavor::Task {
        return Err(E::from(format!(
            "NC destination '{}' is only supported for task outputs (source '{}')",
            NC_ENDPOINT, src_endpoint
        )));
    }
    src_node.add_nc_output(msg_type, order);
    Ok(())
}

/// A simple wrapper enum for `petgraph::Direction`,
/// designed to be converted *into* it via the `From` trait.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CuDirection {
    Outgoing,
    Incoming,
}

impl From<CuDirection> for petgraph::Direction {
    fn from(dir: CuDirection) -> Self {
        match dir {
            CuDirection::Outgoing => petgraph::Direction::Outgoing,
            CuDirection::Incoming => petgraph::Direction::Incoming,
        }
    }
}

#[derive(Default, Debug, Clone)]
pub struct CuGraph(pub StableDiGraph<Node, Cnx, NodeId>);

impl CuGraph {
    #[allow(dead_code)]
    pub fn get_all_nodes(&self) -> Vec<(NodeId, &Node)> {
        self.0
            .node_indices()
            .map(|index| (index.index() as u32, &self.0[index]))
            .collect()
    }

    #[allow(dead_code)]
    pub fn get_neighbor_ids(&self, node_id: NodeId, dir: CuDirection) -> Vec<NodeId> {
        self.0
            .neighbors_directed(node_id.into(), dir.into())
            .map(|petgraph_index| petgraph_index.index() as NodeId)
            .collect()
    }

    #[allow(dead_code)]
    pub fn node_ids(&self) -> Vec<NodeId> {
        self.0
            .node_indices()
            .map(|index| index.index() as NodeId)
            .collect()
    }

    #[allow(dead_code)]
    pub fn edge_id_between(&self, source: NodeId, target: NodeId) -> Option<usize> {
        self.0
            .find_edge(source.into(), target.into())
            .map(|edge| edge.index())
    }

    #[allow(dead_code)]
    pub fn edge(&self, edge_id: usize) -> Option<&Cnx> {
        self.0.edge_weight(EdgeIndex::new(edge_id))
    }

    #[allow(dead_code)]
    pub fn edges(&self) -> impl Iterator<Item = &Cnx> {
        self.0
            .edge_indices()
            .filter_map(|edge| self.0.edge_weight(edge))
    }

    #[allow(dead_code)]
    pub fn bfs_nodes(&self, start: NodeId) -> Vec<NodeId> {
        let mut visitor = Bfs::new(&self.0, start.into());
        let mut nodes = Vec::new();
        while let Some(node) = visitor.next(&self.0) {
            nodes.push(node.index() as NodeId);
        }
        nodes
    }

    #[allow(dead_code)]
    pub fn incoming_neighbor_count(&self, node_id: NodeId) -> usize {
        self.0.neighbors_directed(node_id.into(), Incoming).count()
    }

    #[allow(dead_code)]
    pub fn outgoing_neighbor_count(&self, node_id: NodeId) -> usize {
        self.0.neighbors_directed(node_id.into(), Outgoing).count()
    }

    pub fn node_indices(&self) -> Vec<petgraph::stable_graph::NodeIndex> {
        self.0.node_indices().collect()
    }

    pub fn add_node(&mut self, node: Node) -> CuResult<NodeId> {
        Ok(self.0.add_node(node).index() as NodeId)
    }

    #[allow(dead_code)]
    pub fn connection_exists(&self, source: NodeId, target: NodeId) -> bool {
        self.0.find_edge(source.into(), target.into()).is_some()
    }

    pub fn connect_ext(
        &mut self,
        source: NodeId,
        target: NodeId,
        msg_type: &str,
        missions: Option<Vec<String>>,
        src_channel: Option<String>,
        dst_channel: Option<String>,
    ) -> CuResult<()> {
        self.connect_ext_with_order(
            source,
            target,
            msg_type,
            missions,
            src_channel,
            dst_channel,
            usize::MAX,
        )
    }

    #[allow(clippy::too_many_arguments)]
    pub fn connect_ext_with_order(
        &mut self,
        source: NodeId,
        target: NodeId,
        msg_type: &str,
        missions: Option<Vec<String>>,
        src_channel: Option<String>,
        dst_channel: Option<String>,
        order: usize,
    ) -> CuResult<()> {
        let (src_id, dst_id) = (
            self.0
                .node_weight(source.into())
                .ok_or("Source node not found")?
                .id
                .clone(),
            self.0
                .node_weight(target.into())
                .ok_or("Target node not found")?
                .id
                .clone(),
        );

        let _ = self.0.add_edge(
            petgraph::stable_graph::NodeIndex::from(source),
            petgraph::stable_graph::NodeIndex::from(target),
            Cnx {
                src: src_id,
                dst: dst_id,
                msg: msg_type.to_string(),
                missions,
                src_channel,
                dst_channel,
                order,
            },
        );
        Ok(())
    }
    /// Get the node with the given id.
    /// If mission_id is provided, get the node from that mission's graph.
    /// Otherwise get the node from the simple graph.
    #[allow(dead_code)]
    pub fn get_node(&self, node_id: NodeId) -> Option<&Node> {
        self.0.node_weight(node_id.into())
    }

    #[allow(dead_code)]
    pub fn get_node_weight(&self, index: NodeId) -> Option<&Node> {
        self.0.node_weight(index.into())
    }

    #[allow(dead_code)]
    pub fn get_node_mut(&mut self, node_id: NodeId) -> Option<&mut Node> {
        self.0.node_weight_mut(node_id.into())
    }

    pub fn get_node_id_by_name(&self, name: &str) -> Option<NodeId> {
        self.0
            .node_indices()
            .into_iter()
            .find(|idx| self.0[*idx].get_id() == name)
            .map(|i| i.index() as NodeId)
    }

    #[allow(dead_code)]
    pub fn get_edge_weight(&self, index: usize) -> Option<Cnx> {
        self.0.edge_weight(EdgeIndex::new(index)).cloned()
    }

    #[allow(dead_code)]
    pub fn get_node_output_msg_type(&self, node_id: &str) -> Option<String> {
        self.get_node_output_msg_types(node_id)
            .and_then(|mut msgs| msgs.drain(..1).next())
    }

    #[allow(dead_code)]
    pub fn get_node_output_msg_types(&self, node_id: &str) -> Option<Vec<String>> {
        let node_id = self.get_node_id_by_name(node_id)?;
        let msgs = self.get_node_output_msg_types_by_id(node_id).ok()?;
        (!msgs.is_empty()).then_some(msgs)
    }

    #[allow(dead_code)]
    pub fn get_node_output_msg_types_by_id(&self, node_id: NodeId) -> CuResult<Vec<String>> {
        let mut edge_ids = self.get_src_edges(node_id)?;
        edge_ids.sort();

        let node = self
            .get_node(node_id)
            .ok_or_else(|| CuError::from(format!("Node id {node_id} not found")))?;

        let mut msg_order: Vec<(usize, String)> = Vec::new();
        let mut record_msg = |msg: String, order: usize| {
            if let Some((existing_order, _)) = msg_order
                .iter_mut()
                .find(|(_, existing_msg)| *existing_msg == msg)
            {
                if order < *existing_order {
                    *existing_order = order;
                }
                return;
            }
            msg_order.push((order, msg));
        };

        for edge_id in edge_ids {
            let Some(edge) = self.edge(edge_id) else {
                continue;
            };
            let order = if edge.order == usize::MAX {
                edge_id
            } else {
                edge.order
            };
            record_msg(edge.msg.clone(), order);
        }

        for (msg, order) in node.nc_outputs_with_order() {
            record_msg(msg.clone(), order);
        }

        msg_order.sort_by(|(order_a, msg_a), (order_b, msg_b)| {
            order_a.cmp(order_b).then_with(|| msg_a.cmp(msg_b))
        });
        Ok(msg_order.into_iter().map(|(_, msg)| msg).collect())
    }

    /// Channel-aware variant of [`CuGraph::get_node_output_msg_types_by_id`].
    ///
    /// Returns each distinct output port as `(msg_type, src_channel)`, where
    /// `src_channel` is `None` for ordinary task ports and `Some(id)` for
    /// bridge-channel ports. Unlike the msg-only variant, two ports sharing the
    /// same message type but living on different bridge channels are kept as
    /// separate entries, preserving their relative ordering (see #791).
    #[allow(dead_code)]
    pub fn get_node_output_ports_by_id(
        &self,
        node_id: NodeId,
    ) -> CuResult<Vec<(String, Option<String>)>> {
        let mut edge_ids = self.get_src_edges(node_id)?;
        edge_ids.sort();

        let node = self
            .get_node(node_id)
            .ok_or_else(|| CuError::from(format!("Node id {node_id} not found")))?;

        let mut port_order: Vec<(usize, String, Option<String>)> = Vec::new();
        let mut record_port = |msg: String, channel: Option<String>, order: usize| {
            if let Some((existing_order, _, _)) = port_order
                .iter_mut()
                .find(|(_, m, c)| *m == msg && *c == channel)
            {
                if order < *existing_order {
                    *existing_order = order;
                }
                return;
            }
            port_order.push((order, msg, channel));
        };

        for edge_id in edge_ids {
            let Some(edge) = self.edge(edge_id) else {
                continue;
            };
            let order = if edge.order == usize::MAX {
                edge_id
            } else {
                edge.order
            };
            record_port(edge.msg.clone(), edge.src_channel.clone(), order);
        }

        for (msg, order) in node.nc_outputs_with_order() {
            record_port(msg.clone(), None, order);
        }

        port_order.sort_by(|(order_a, msg_a, ch_a), (order_b, msg_b, ch_b)| {
            order_a
                .cmp(order_b)
                .then_with(|| msg_a.cmp(msg_b))
                .then_with(|| ch_a.cmp(ch_b))
        });
        Ok(port_order
            .into_iter()
            .map(|(_, msg, ch)| (msg, ch))
            .collect())
    }

    #[allow(dead_code)]
    pub fn get_node_input_msg_type(&self, node_id: &str) -> Option<String> {
        self.get_node_input_msg_types(node_id)
            .and_then(|mut v| v.pop())
    }

    pub fn get_node_input_msg_types(&self, node_id: &str) -> Option<Vec<String>> {
        self.0.node_indices().find_map(|node_index| {
            if let Some(node) = self.0.node_weight(node_index) {
                if node.id != node_id {
                    return None;
                }
                let edges: Vec<_> = self
                    .0
                    .edges_directed(node_index, Incoming)
                    .map(|edge| edge.id().index())
                    .collect();
                if edges.is_empty() {
                    return None;
                }
                let mut edges = edges;
                edges.sort();
                let msgs = edges
                    .into_iter()
                    .map(|edge_id| {
                        let cnx = self
                            .0
                            .edge_weight(EdgeIndex::new(edge_id))
                            .expect("Found an cnx id but could not retrieve it back");
                        cnx.msg.clone()
                    })
                    .collect();
                return Some(msgs);
            }
            None
        })
    }

    #[allow(dead_code)]
    pub fn get_connection_msg_type(&self, source: NodeId, target: NodeId) -> Option<&str> {
        self.0
            .find_edge(source.into(), target.into())
            .map(|edge_index| self.0[edge_index].msg.as_str())
    }

    /// Get the list of edges that are connected to the given node as a source.
    fn get_edges_by_direction(
        &self,
        node_id: NodeId,
        direction: petgraph::Direction,
    ) -> CuResult<Vec<usize>> {
        Ok(self
            .0
            .edges_directed(node_id.into(), direction)
            .map(|edge| edge.id().index())
            .collect())
    }

    pub fn get_src_edges(&self, node_id: NodeId) -> CuResult<Vec<usize>> {
        self.get_edges_by_direction(node_id, Outgoing)
    }

    /// Get the list of edges that are connected to the given node as a destination.
    pub fn get_dst_edges(&self, node_id: NodeId) -> CuResult<Vec<usize>> {
        self.get_edges_by_direction(node_id, Incoming)
    }

    #[allow(dead_code)]
    pub fn node_count(&self) -> usize {
        self.0.node_count()
    }

    #[allow(dead_code)]
    pub fn edge_count(&self) -> usize {
        self.0.edge_count()
    }

    /// Adds an edge between two nodes/tasks in the configuration graph.
    /// msg_type is the type of message exchanged between the two nodes/tasks.
    #[allow(dead_code)]
    pub fn connect(&mut self, source: NodeId, target: NodeId, msg_type: &str) -> CuResult<()> {
        self.connect_ext(source, target, msg_type, None, None, None)
    }
}

fn validate_task_kind(
    node_id: &str,
    kind: TaskKind,
    has_inputs: bool,
    has_outputs: bool,
) -> CuResult<()> {
    match kind {
        TaskKind::Source if has_inputs => Err(CuError::from(format!(
            "Task '{node_id}' is declared as kind 'source' but has incoming connections. Sources map to CuSrcTask and cannot consume inputs. Use kind: task instead."
        ))),
        TaskKind::Regular if !has_inputs => Err(CuError::from(format!(
            "Task '{node_id}' is declared as kind 'task' but has no incoming connections. Regular tasks map to CuTask and need at least one input connection. Use kind: source if it is input-free."
        ))),
        TaskKind::Sink if has_outputs => Err(CuError::from(format!(
            "Task '{node_id}' is declared as kind 'sink' but has outgoing or NC outputs. Sinks map to CuSinkTask and cannot produce outputs. Use kind: task instead."
        ))),
        TaskKind::Sink if !has_inputs => Err(CuError::from(format!(
            "Task '{node_id}' is declared as kind 'sink' but has no incoming connections. Sinks need at least one input connection so Copper can determine their input message type."
        ))),
        _ => Ok(()),
    }
}

#[allow(dead_code)]
pub fn infer_task_kind_for_id(graph: &CuGraph, node_id: NodeId) -> Option<TaskKind> {
    let node = graph.get_node(node_id)?;
    if node.get_flavor() != Flavor::Task {
        return None;
    }

    let has_inputs = !graph.get_dst_edges(node_id).ok()?.is_empty();
    let has_outputs = !graph
        .get_node_output_msg_types_by_id(node_id)
        .ok()?
        .is_empty();

    match (has_inputs, has_outputs) {
        (false, true) => Some(TaskKind::Source),
        (true, true) => Some(TaskKind::Regular),
        (true, false) => Some(TaskKind::Sink),
        (false, false) => None,
    }
}

#[allow(dead_code)]
pub fn resolve_task_kind_for_id(graph: &CuGraph, node_id: NodeId) -> CuResult<TaskKind> {
    let node = graph
        .get_node(node_id)
        .ok_or_else(|| CuError::from(format!("Task node id {node_id} not found")))?;
    if node.get_flavor() != Flavor::Task {
        return Err(CuError::from(format!(
            "Node '{}' is not a task and does not have a task kind.",
            node.id
        )));
    }

    let has_inputs = !graph.get_dst_edges(node_id)?.is_empty();
    let has_outputs = !graph.get_node_output_msg_types_by_id(node_id)?.is_empty();

    if let Some(kind) = node.get_declared_task_kind() {
        validate_task_kind(node.id.as_str(), kind, has_inputs, has_outputs)?;
        return Ok(kind);
    }

    let inferred = match (has_inputs, has_outputs) {
        (false, true) => TaskKind::Source,
        (true, true) => TaskKind::Regular,
        (true, false) => TaskKind::Sink,
        (false, false) => {
            return Err(CuError::from(format!(
                "Task '{}' has no declared inputs or outputs, so Copper cannot infer whether it is a source, task, or sink. Add `kind: source|task|sink`; source/task nodes also need an output declaration via a connection or `dst: \"{NC_ENDPOINT}\"`.",
                node.id
            )));
        }
    };

    validate_task_kind(node.id.as_str(), inferred, has_inputs, has_outputs)?;
    Ok(inferred)
}

impl core::ops::Index<NodeIndex> for CuGraph {
    type Output = Node;

    fn index(&self, index: NodeIndex) -> &Self::Output {
        &self.0[index]
    }
}

#[derive(Debug, Clone)]
pub enum ConfigGraphs {
    Simple(CuGraph),
    Missions(HashMap<String, CuGraph>),
}

impl ConfigGraphs {
    /// Returns a consistent hashmap of mission names to Graphs whatever the shape of the config is.
    /// Note: if there is only one anonymous mission it will be called "default"
    #[allow(dead_code)]
    pub fn get_all_missions_graphs(&self) -> HashMap<String, CuGraph> {
        match self {
            Simple(graph) => HashMap::from([(DEFAULT_MISSION_ID.to_string(), graph.clone())]),
            Missions(graphs) => graphs.clone(),
        }
    }

    #[allow(dead_code)]
    pub fn get_default_mission_graph(&self) -> CuResult<&CuGraph> {
        match self {
            Simple(graph) => Ok(graph),
            Missions(graphs) => {
                if graphs.len() == 1 {
                    Ok(graphs.values().next().unwrap())
                } else {
                    Err("Cannot get default mission graph from mission config".into())
                }
            }
        }
    }

    #[allow(dead_code)]
    pub fn get_graph(&self, mission_id: Option<&str>) -> CuResult<&CuGraph> {
        match self {
            Simple(graph) => match mission_id {
                None | Some(DEFAULT_MISSION_ID) => Ok(graph),
                Some(_) => Err("Cannot get mission graph from simple config".into()),
            },
            Missions(graphs) => {
                let id = mission_id
                    .ok_or_else(|| "Mission ID required for mission configs".to_string())?;
                graphs
                    .get(id)
                    .ok_or_else(|| format!("Mission {id} not found").into())
            }
        }
    }

    #[allow(dead_code)]
    pub fn get_graph_mut(&mut self, mission_id: Option<&str>) -> CuResult<&mut CuGraph> {
        match self {
            Simple(graph) => match mission_id {
                None => Ok(graph),
                Some(_) => Err("Cannot get mission graph from simple config".into()),
            },
            Missions(graphs) => {
                let id = mission_id
                    .ok_or_else(|| "Mission ID required for mission configs".to_string())?;
                graphs
                    .get_mut(id)
                    .ok_or_else(|| format!("Mission {id} not found").into())
            }
        }
    }

    pub fn add_mission(&mut self, mission_id: &str) -> CuResult<&mut CuGraph> {
        match self {
            Simple(_) => Err("Cannot add mission to simple config".into()),
            Missions(graphs) => match graphs.entry(mission_id.to_string()) {
                hashbrown::hash_map::Entry::Occupied(_) => {
                    Err(format!("Mission {mission_id} already exists").into())
                }
                hashbrown::hash_map::Entry::Vacant(entry) => Ok(entry.insert(CuGraph::default())),
            },
        }
    }
}

/// CuConfig is the programmatic representation of the configuration graph.
/// It is a directed graph where nodes are tasks and edges are connections between tasks.
///
/// The core of CuConfig is its `graphs` field which can be either a simple graph
/// or a collection of mission-specific graphs. The graph structure is based on petgraph.
#[derive(Debug, Clone)]
pub struct CuConfig {
    /// Values baked into the application by `#[copper_runtime]`.
    #[doc(hidden)]
    pub constants: Vec<ConstantConfig>,
    /// Monitoring configuration list.
    pub monitors: Vec<MonitorConfig>,
    /// Optional logging configuration
    pub logging: Option<LoggingConfig>,
    /// Optional runtime configuration
    pub runtime: Option<RuntimeConfig>,
    /// Declarative resource bundle definitions
    pub resources: Vec<ResourceBundleConfig>,
    /// Optional statically generated semantic log-stream destinations.
    pub log_streaming: Option<LogStreamingConfig>,
    /// Declarative bridge definitions that are yet to be expanded into the graph
    pub bridges: Vec<BridgeConfig>,
    /// Graph structure - either a single graph or multiple mission-specific graphs
    pub graphs: ConfigGraphs,
}

/// Every reconstructed node needs recorded or reconstructed inputs. Checking
/// direct edges at every reconstructed node also covers chains and fan-in.
fn validate_reconstruction_inputs(graph: &CuGraph) -> CuResult<()> {
    for index in graph.0.node_indices() {
        let node = &graph.0[index];
        if node.streaming().replay != StreamReplay::Reconstruct {
            continue;
        }
        for edge in graph.0.edges_directed(index, Incoming) {
            let source = &graph.0[edge.source()];
            if !source.is_logging_enabled() {
                return Err(CuError::from(format!(
                    "Task '{}' uses streaming.replay: reconstruct but input '{}' from '{}' has logging.enabled: false. Enable logging on '{}' or use streaming.replay: capture on '{}'.",
                    node.id,
                    edge.weight().msg,
                    source.id,
                    source.id,
                    node.id
                )));
            }
        }
    }
    Ok(())
}

impl CuConfig {
    /// Validates reconstruction inputs, static log-stream topology and bounds before code generation.
    pub fn validate_log_streaming_config(&self) -> CuResult<()> {
        match &self.graphs {
            Simple(graph) => validate_reconstruction_inputs(graph)?,
            Missions(graphs) => {
                for (mission, graph) in graphs {
                    validate_reconstruction_inputs(graph)
                        .map_err(|error| CuError::from(format!("Mission '{mission}': {error}")))?;
                }
            }
        }

        let Some(streaming) = &self.log_streaming else {
            return Ok(());
        };
        if streaming.destinations.is_empty() {
            return Err(CuError::from(
                "log_streaming.destinations must contain at least one destination",
            ));
        }

        let keyframe_interval = self
            .logging
            .as_ref()
            .and_then(|logging| logging.keyframe_interval)
            .unwrap_or(DEFAULT_KEYFRAME_INTERVAL);
        for (index, destination) in streaming.destinations.iter().enumerate() {
            if destination.id.trim().is_empty() {
                return Err(CuError::from(format!(
                    "log_streaming destination at index {index} has an empty id"
                )));
            }
            if streaming.destinations[..index]
                .iter()
                .any(|other| other.id == destination.id)
            {
                return Err(CuError::from(format!(
                    "Duplicate log_streaming destination id '{}'",
                    destination.id
                )));
            }
            if destination.transport.type_.trim().is_empty() {
                return Err(CuError::from(format!(
                    "log_streaming destination '{}' has an empty transport type",
                    destination.id
                )));
            }
            let Some((bundle_id, resource_name)) = destination.transport.resource.split_once('.')
            else {
                return Err(CuError::from(format!(
                    "log_streaming destination '{}' resource '{}' must use 'bundle.resource' syntax",
                    destination.id, destination.transport.resource
                )));
            };
            if bundle_id.is_empty()
                || resource_name.is_empty()
                || resource_name.contains('.')
                || !self.resources.iter().any(|bundle| bundle.id == bundle_id)
            {
                return Err(CuError::from(format!(
                    "log_streaming destination '{}' references invalid resource '{}'",
                    destination.id, destination.transport.resource
                )));
            }
            if streaming.destinations[..index]
                .iter()
                .any(|other| other.transport.resource == destination.transport.resource)
            {
                return Err(CuError::from(format!(
                    "log_streaming resource '{}' is bound by more than one destination",
                    destination.transport.resource
                )));
            }
            if let Some(feedback) = &destination.feedback {
                let baseline = destination.fec.continuous.repair_every_source_symbols;
                if feedback.report_interval_ms == 0
                    || feedback.timeout_ms <= feedback.report_interval_ms
                    || feedback.adaptation.is_some_and(|bounds| {
                        bounds.min_repair_every_source_symbols == 0
                            || bounds.min_repair_every_source_symbols > baseline
                            || baseline > bounds.max_repair_every_source_symbols
                    })
                {
                    return Err(CuError::from(
                        "Invalid log_streaming feedback cadence or FEC bounds",
                    ));
                }
                let resource = &feedback.transport.resource;
                let valid_resource = resource.split_once('.').is_some_and(|(bundle, slot)| {
                    !slot.is_empty()
                        && !slot.contains('.')
                        && self.resources.iter().any(|r| r.id == bundle)
                });
                if feedback.transport.type_.trim().is_empty() || !valid_resource {
                    return Err(CuError::from("Invalid log_streaming feedback resource"));
                }
            }
            // All logical receivers have one owner, including shared-carrier handles.
            let resources = core::iter::once(&destination.transport.resource)
                .chain(destination.feedback.iter().map(|f| &f.transport.resource));
            for resource in resources {
                let uses = streaming
                    .destinations
                    .iter()
                    .map(|d| {
                        usize::from(&d.transport.resource == resource)
                            + usize::from(
                                d.feedback
                                    .as_ref()
                                    .is_some_and(|f| &f.transport.resource == resource),
                            )
                    })
                    .sum::<usize>();
                if uses > 1 {
                    return Err(CuError::from(format!(
                        "Log-stream resource '{resource}' has multiple owners"
                    )));
                }
            }
            if destination.link.mtu_bytes <= 72 {
                return Err(CuError::from(format!(
                    "log_streaming destination '{}' mtu_bytes must exceed the 72-byte packet header",
                    destination.id
                )));
            }
            if destination.link.bitrate_bps == 0
                || destination.link.memory_budget_kib == 0
                || destination.link.max_latency_ms == 0
                || destination.link.burst_packets == 0
            {
                return Err(CuError::from(format!(
                    "log_streaming destination '{}' link values must be nonzero",
                    destination.id
                )));
            }
            if destination.fec.continuous.window_symbols == 0
                || destination.fec.continuous.repair_every_source_symbols == 0
            {
                return Err(CuError::from(format!(
                    "log_streaming destination '{}' continuous FEC values must be nonzero",
                    destination.id
                )));
            }
            if destination.fec.continuous.repair_density.threshold() > 15 {
                return Err(CuError::from(format!(
                    "log_streaming destination '{}' repair density threshold must be in 0..=15",
                    destination.id
                )));
            }
            if destination.fec.objects.max_object_bytes == 0
                || destination.fec.objects.repair_symbols_per_block == 0
                || destination.max_record_bytes == 0
            {
                return Err(CuError::from(format!(
                    "log_streaming destination '{}' object and record bounds must be nonzero",
                    destination.id
                )));
            }
            if destination.recovery_interval == 0
                || !destination
                    .recovery_interval
                    .is_multiple_of(keyframe_interval)
            {
                return Err(CuError::from(format!(
                    "log_streaming destination '{}' recovery_interval must be a nonzero multiple of logging.keyframe_interval ({keyframe_interval})",
                    destination.id
                )));
            }
        }
        Ok(())
    }

    /// Guarantees that a default `"background"` thread pool entry exists in
    /// `runtime.thread_pools` whenever the graph has any `background: true`
    /// task that didn't explicitly select a pool. Thread pools are otherwise
    /// constructed straight from `runtime.thread_pools` by the runtime — they
    /// are not stored in `ResourceManager`.
    #[cfg(feature = "std")]
    fn ensure_default_background_pool(&mut self) {
        if !self.has_background_tasks() {
            return;
        }

        const DEFAULT_BACKGROUND_THREADS: usize = 2;

        let runtime = self.runtime.get_or_insert_with(RuntimeConfig::default);
        if !runtime
            .thread_pools
            .iter()
            .any(|pool| pool.id == DEFAULT_BACKGROUND_POOL)
        {
            runtime.thread_pools.push(ThreadPoolConfig {
                id: DEFAULT_BACKGROUND_POOL.to_string(),
                threads: DEFAULT_BACKGROUND_THREADS,
                affinity: None,
                policy: SchedulingPolicy::Fair,
                on_error: OnError::Warn,
            });
        }
    }

    /// The configured planner selection, if any (absent means `Linearity`).
    // rendercfg.rs recompiles this file via `mod config;`, so pub helpers it
    // does not call are dead code in that bin under `clippy --deny warnings`.
    #[allow(dead_code)]
    pub fn planner_config(&self) -> Option<&PlannerConfig> {
        self.runtime.as_ref()?.planner.as_ref()
    }

    /// The step order baked at build time for `mission`, if the config carries one.
    #[doc(hidden)]
    #[allow(dead_code)]
    pub fn planner_resolved_order(&self, mission: &str) -> Option<&[String]> {
        self.planner_config()?
            .resolved
            .as_ref()?
            .get(mission)
            .map(Vec::as_slice)
    }

    /// Bake per-mission resolved step orders into the planner section,
    /// creating the section (with `type_`) if the loaded config lacks one.
    /// Codegen contract: generated apps call this before logging the
    /// effective config.
    #[doc(hidden)]
    #[allow(dead_code)]
    pub fn set_planner_resolved_orders(
        &mut self,
        type_: &str,
        orders: impl IntoIterator<Item = (String, Vec<String>)>,
    ) {
        let runtime = self.runtime.get_or_insert_with(RuntimeConfig::default);
        let planner = runtime.planner.get_or_insert_with(|| PlannerConfig {
            type_: type_.to_string(),
            config: None,
            resolved: None,
        });
        planner.resolved = Some(orders.into_iter().collect());
    }

    #[cfg(feature = "std")]
    fn has_background_tasks(&self) -> bool {
        match &self.graphs {
            ConfigGraphs::Simple(graph) => graph
                .get_all_nodes()
                .iter()
                .any(|(_, node)| node.is_background()),
            ConfigGraphs::Missions(graphs) => graphs.values().any(|graph| {
                graph
                    .get_all_nodes()
                    .iter()
                    .any(|(_, node)| node.is_background())
            }),
        }
    }
}

#[derive(Serialize, Deserialize, Default, Debug, Clone)]
pub struct MonitorConfig {
    #[serde(rename = "type")]
    type_: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    config: Option<ComponentConfig>,
}

impl MonitorConfig {
    #[allow(dead_code)]
    pub fn get_type(&self) -> &str {
        &self.type_
    }

    #[allow(dead_code)]
    pub fn get_config(&self) -> Option<&ComponentConfig> {
        self.config.as_ref()
    }
}

fn default_as_true() -> bool {
    true
}

pub const DEFAULT_KEYFRAME_INTERVAL: u32 = 100;

fn default_keyframe_interval() -> Option<u32> {
    Some(DEFAULT_KEYFRAME_INTERVAL)
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct LoggingConfig {
    /// Enable task logging to the log file.
    #[serde(default = "default_as_true", skip_serializing_if = "Clone::clone")]
    pub enable_task_logging: bool,

    /// Generate and record task-state keyframes.
    ///
    /// Without another generated keyframe consumer, this is a compile-time application
    /// property and `#[copper_runtime]` emits no capture calls when it is `false`.
    /// A log-stream destination independently requests keyframe capture for recovery points.
    #[serde(default = "default_as_true", skip_serializing_if = "Clone::clone")]
    pub enable_keyframe_logging: bool,

    /// Number of preallocated CopperLists available to the runtime.
    ///
    /// This is consumed by proc-macro codegen and must match the value compiled into the
    /// application binary.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub copperlist_count: Option<usize>,

    /// Size of each slab in the log file. (it is the size of the memory mapped file at a time)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub slab_size_mib: Option<u64>,

    /// Pre-allocated size for each section in the log file.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub section_size_mib: Option<u64>,

    /// Interval in copperlists between two "keyframes" in the log file i.e. freezing tasks.
    #[serde(
        default = "default_keyframe_interval",
        skip_serializing_if = "Option::is_none"
    )]
    pub keyframe_interval: Option<u32>,

    /// Named log codec specs reusable across task output bindings.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub codecs: Vec<LoggingCodecSpec>,
}

impl Default for LoggingConfig {
    fn default() -> Self {
        Self {
            enable_task_logging: true,
            enable_keyframe_logging: true,
            copperlist_count: None,
            slab_size_mib: None,
            section_size_mib: None,
            keyframe_interval: default_keyframe_interval(),
            codecs: Vec::new(),
        }
    }
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct LoggingCodecSpec {
    pub id: String,
    #[serde(rename = "type")]
    pub type_: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub config: Option<ComponentConfig>,
}

#[derive(Serialize, Deserialize, Default, Debug, Clone)]
pub struct RuntimeConfig {
    /// Set a CopperList execution rate target in Hz
    /// It will act as a rate limiter: if the execution is slower than this rate,
    /// it will continue to execute at "best effort".
    ///
    /// The main usecase is to not waste cycles when the system doesn't need an unbounded execution rate.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub rate_target_hz: Option<u64>,

    /// Declarative thread pool definitions used by the background-task pools and
    /// the `parallel-rt` execution engine. Each pool carries an optional CPU
    /// affinity and a scheduling policy/priority.
    ///
    /// This is a `std`-only concept; on `no_std`/embedded targets there are no
    /// threads and this section is ignored.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub thread_pools: Vec<ThreadPoolConfig>,

    /// Execution planner selection, one for the whole config.
    ///
    /// This is a codegen input: `#[copper_runtime]` bakes the resulting plan
    /// into the binary. Editing it in a deployed app's RON at startup does not
    /// change the compiled plan (same class as `logging.copperlist_count`); the
    /// RON must match the binary that wrote the log.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub planner: Option<PlannerConfig>,
}

/// Selects the planner that orders the steps of every mission graph, plus its
/// config. Mirrors [`MonitorConfig`]: `type` names a `CuPlanner` implementation.
/// Copper ships `cu29::planner::Linearity` (the default when this section is
/// absent) and `cu29::planner::Pinned`; any other type is an out-of-tree
/// planner resolved at build time by `cu29::planner::emit_plan` in the
/// application's `build.rs`.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct PlannerConfig {
    #[serde(rename = "type")]
    pub(crate) type_: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub(crate) config: Option<ComponentConfig>,
    /// Step order per mission (stable step keys), baked at build time when an
    /// out-of-tree planner resolved the plan. Takes precedence over `type`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) resolved: Option<BTreeMap<String, Vec<String>>>,
}

impl PlannerConfig {
    #[allow(dead_code)]
    pub fn get_type(&self) -> &str {
        &self.type_
    }

    #[allow(dead_code)]
    pub fn get_config(&self) -> Option<&ComponentConfig> {
        self.config.as_ref()
    }

    /// The per-mission step orders baked at build time, if any.
    #[doc(hidden)]
    #[allow(dead_code)]
    pub fn resolved_orders(&self) -> Option<&BTreeMap<String, Vec<String>>> {
        self.resolved.as_ref()
    }
}

/// Smallest valid real-time priority for [`SchedulingPolicy::Fifo`]/[`SchedulingPolicy::RoundRobin`].
pub const MIN_RT_PRIORITY: u8 = 1;
/// Largest valid real-time priority for [`SchedulingPolicy::Fifo`]/[`SchedulingPolicy::RoundRobin`].
pub const MAX_RT_PRIORITY: u8 = 99;
/// Lowest valid niceness for [`SchedulingPolicy::Nice`] (most favorable).
pub const MIN_NICE: i8 = -20;
/// Highest valid niceness for [`SchedulingPolicy::Nice`] (least favorable).
pub const MAX_NICE: i8 = 19;

/// Scheduling policy applied to every worker thread of a [`ThreadPoolConfig`].
///
/// On Linux these map directly onto the POSIX scheduling policies. On other
/// platforms they are applied best-effort (see the per-pool
/// [`ThreadPoolConfig::on_error`] behavior).
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SchedulingPolicy {
    /// Normal fair time-sharing scheduler (`SCHED_OTHER`/CFS on Linux) with default
    /// niceness. The OS shares the CPU fairly across threads and no thread starves.
    ///
    /// Use for everything that isn't latency-critical. This is the default.
    #[default]
    Fair,
    /// Fair scheduler with an explicit niceness (`-20..=19`, lower is more favorable).
    ///
    /// A soft priority hint, not a guarantee: a higher (nicer) value yields the CPU
    /// more readily. Use to bias a pool below or above normal work without leaving
    /// the fair scheduler — e.g. `Nice(10)` for heavy background work that should
    /// step aside for the control loop.
    Nice(i8),
    /// `SCHED_FIFO` real-time policy, priority `1..=99` (higher wins).
    ///
    /// Hard real-time: a FIFO thread runs ahead of every fair thread and is not
    /// time-sliced — it runs until it blocks or a higher-priority RT thread preempts
    /// it. Use for the latency-critical pipeline, and pin it with `affinity` so a
    /// busy worker cannot starve other work on the same core. Linux-only; typically
    /// needs `CAP_SYS_NICE`.
    Fifo { priority: u8 },
    /// `SCHED_RR` real-time policy, priority `1..=99` (higher wins).
    ///
    /// Same real-time semantics as [`Fifo`](Self::Fifo), except threads at the same
    /// priority are round-robin time-sliced rather than run-to-block. Use when
    /// several RT workers share a priority and should interleave fairly. Linux-only;
    /// typically needs `CAP_SYS_NICE`.
    RoundRobin { priority: u8 },
}

/// What to do when a pool's affinity or scheduling request cannot be applied
/// (for example, setting a real-time priority without `CAP_SYS_NICE`).
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum OnError {
    /// Log a warning and fall back to default scheduling. This keeps unprivileged
    /// dev/laptop runs working out of the box.
    #[default]
    Warn,
    /// Hard-fail at startup if the requested affinity/scheduler cannot be applied.
    /// Use this for deployed real-time robots that must fail loudly.
    Strict,
}

/// Declarative definition of a single thread pool.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
pub struct ThreadPoolConfig {
    /// Unique pool id. Reserved ids: [`RT_POOL`] (the `parallel-rt` execution
    /// engine) and [`DEFAULT_BACKGROUND_POOL`] (the default background pool).
    pub id: String,
    /// Number of worker threads in the pool.
    pub threads: usize,
    /// Optional set of logical CPU cores the pool may use. When set, worker `i`
    /// is pinned to `affinity[i % affinity.len()]` (Spread): `threads ==
    /// affinity.len()` yields one worker pinned per dedicated core.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub affinity: Option<Vec<usize>>,
    /// Scheduling policy/priority applied to each worker thread.
    #[serde(default)]
    pub policy: SchedulingPolicy,
    /// What to do if affinity/scheduling cannot be applied.
    #[serde(default)]
    pub on_error: OnError,
}

/// Validates the declarative thread pool definitions of a runtime config.
///
/// Checks ids are non-empty and unique, thread counts are non-zero, real-time
/// priorities and niceness values are in range, and affinity lists are non-empty
/// when present. This is purely a config-level check; pools are built later.
fn validate_thread_pools<E>(runtime: &Option<RuntimeConfig>) -> Result<(), E>
where
    E: From<String>,
{
    let Some(runtime) = runtime else {
        return Ok(());
    };

    let mut seen: Vec<&str> = Vec::new();
    for pool in &runtime.thread_pools {
        if pool.id.is_empty() {
            return Err(E::from("Thread pool id cannot be empty".to_string()));
        }
        if seen.contains(&pool.id.as_str()) {
            return Err(E::from(format!("Duplicate thread pool id '{}'", pool.id)));
        }
        seen.push(pool.id.as_str());

        if pool.threads == 0 {
            return Err(E::from(format!(
                "Thread pool '{}' must have at least 1 thread",
                pool.id
            )));
        }

        match pool.policy {
            SchedulingPolicy::Fifo { priority } | SchedulingPolicy::RoundRobin { priority } => {
                if !(MIN_RT_PRIORITY..=MAX_RT_PRIORITY).contains(&priority) {
                    return Err(E::from(format!(
                        "Thread pool '{}' real-time priority {priority} is out of range ({MIN_RT_PRIORITY}..={MAX_RT_PRIORITY})",
                        pool.id
                    )));
                }
            }
            SchedulingPolicy::Nice(nice) => {
                if !(MIN_NICE..=MAX_NICE).contains(&nice) {
                    return Err(E::from(format!(
                        "Thread pool '{}' niceness {nice} is out of range ({MIN_NICE}..={MAX_NICE})",
                        pool.id
                    )));
                }
            }
            SchedulingPolicy::Fair => {}
        }

        if let Some(affinity) = &pool.affinity
            && affinity.is_empty()
        {
            return Err(E::from(format!(
                "Thread pool '{}' has an empty affinity list; omit `affinity` for no pinning",
                pool.id
            )));
        }
    }

    Ok(())
}

/// Maximum representable Copper runtime rate target in whole Hertz.
///
/// Copper stores runtime periods in integer nanoseconds, so anything above 1 GHz
/// would round down to a zero-duration period.
pub const MAX_RATE_TARGET_HZ: u64 = 1_000_000_000;

/// Missions are used to generate alternative DAGs within the same configuration.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct MissionsConfig {
    pub id: String,
}

/// A compile-time predicate controlling whether a configuration fragment is included.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
pub enum ConfigPredicate {
    Feature(String),
    Not(Box<ConfigPredicate>),
    All(Vec<ConfigPredicate>),
    Any(Vec<ConfigPredicate>),
}

#[cfg(feature = "std")]
impl ConfigPredicate {
    fn evaluate(&self, active_features: &[&str]) -> bool {
        match self {
            Self::Feature(feature) => active_features.contains(&feature.as_str()),
            Self::Not(predicate) => !predicate.evaluate(active_features),
            Self::All(predicates) => predicates
                .iter()
                .all(|predicate| predicate.evaluate(active_features)),
            Self::Any(predicates) => predicates
                .iter()
                .any(|predicate| predicate.evaluate(active_features)),
        }
    }
}

/// Includes are used to include other configuration files.
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct IncludesConfig {
    pub path: String,
    #[serde(default)]
    pub params: HashMap<String, Value>,
    #[serde(default)]
    pub missions: Option<Vec<String>>,
    #[serde(default)]
    pub when: Option<ConfigPredicate>,
}

/// One subsystem participating in a multi-Copper deployment.
#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
pub struct MultiCopperSubsystemConfig {
    pub id: String,
    pub config: String,
}

/// One explicit interconnect between two subsystem bridge channels.
#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
pub struct MultiCopperInterconnectConfig {
    pub from: String,
    pub to: String,
    pub msg: String,
    #[serde(default)]
    pub when: Option<ConfigPredicate>,
}

/// One path-based config overlay applied to a parsed local Copper config.
#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct InstanceConfigSetOperation {
    pub path: String,
    pub value: ComponentConfig,
}

/// Typed endpoint reference used by validated multi-Copper interconnects.
#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct MultiCopperEndpoint {
    pub subsystem_id: String,
    pub bridge_id: String,
    pub channel_id: String,
}

#[cfg(feature = "std")]
impl Display for MultiCopperEndpoint {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{}/{}/{}",
            self.subsystem_id, self.bridge_id, self.channel_id
        )
    }
}

/// Validated subsystem entry with its compiler-assigned numeric subsystem code and parsed local Copper config.
#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Debug, Clone)]
pub struct MultiCopperSubsystem {
    pub id: String,
    pub subsystem_code: u16,
    pub config_path: String,
    pub config: CuConfig,
}

/// Validated explicit interconnect between two subsystem endpoints.
#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MultiCopperInterconnect {
    pub from: MultiCopperEndpoint,
    pub to: MultiCopperEndpoint,
    pub msg: String,
    pub bridge_type: String,
}

/// Strict umbrella configuration describing multiple Copper subsystems and their explicit links.
#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Debug, Clone)]
pub struct MultiCopperConfig {
    pub subsystems: Vec<MultiCopperSubsystem>,
    pub interconnects: Vec<MultiCopperInterconnect>,
    pub instance_overrides_root: Option<String>,
}

#[cfg(feature = "std")]
impl MultiCopperConfig {
    #[allow(dead_code)]
    pub fn subsystem(&self, id: &str) -> Option<&MultiCopperSubsystem> {
        self.subsystems.iter().find(|subsystem| subsystem.id == id)
    }

    #[allow(dead_code)]
    pub fn resolve_subsystem_config_for_instance(
        &self,
        subsystem_id: &str,
        instance_id: u32,
    ) -> CuResult<CuConfig> {
        let subsystem = self.subsystem(subsystem_id).ok_or_else(|| {
            CuError::from(format!(
                "Multi-Copper config does not define subsystem '{}'.",
                subsystem_id
            ))
        })?;
        let mut config = subsystem.config.clone();

        let Some(root) = &self.instance_overrides_root else {
            return Ok(config);
        };

        let override_path = std::path::Path::new(root)
            .join(instance_id.to_string())
            .join(format!("{subsystem_id}.ron"));
        if !override_path.exists() {
            return Ok(config);
        }

        apply_instance_overrides_from_file(&mut config, &override_path)?;
        Ok(config)
    }
}

#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
struct MultiCopperConfigRepresentation {
    subsystems: Vec<MultiCopperSubsystemConfig>,
    interconnects: Vec<MultiCopperInterconnectConfig>,
    instance_overrides_root: Option<String>,
}

#[cfg(feature = "std")]
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
struct InstanceConfigOverridesRepresentation {
    #[serde(default)]
    set: Vec<InstanceConfigSetOperation>,
}

#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum MultiCopperChannelDirection {
    Rx,
    Tx,
}

#[cfg(feature = "std")]
#[allow(dead_code)]
#[derive(Debug, Clone)]
struct MultiCopperChannelContract {
    bridge_type: String,
    direction: MultiCopperChannelDirection,
    msg: Option<String>,
}

#[cfg(feature = "std")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum InstanceConfigTargetKind {
    Task,
    Resource,
    Bridge,
}

/// This is the main Copper configuration representation.
#[derive(Serialize, Deserialize, Default)]
struct CuConfigRepresentation {
    constants: Option<Vec<ConstantConfig>>,
    tasks: Option<Vec<Node>>,
    resources: Option<Vec<ResourceBundleConfig>>,
    log_streaming: Option<LogStreamingConfig>,
    bridges: Option<Vec<BridgeConfig>>,
    cnx: Option<Vec<SerializedCnx>>,
    #[serde(
        default,
        alias = "monitor",
        deserialize_with = "deserialize_monitor_configs"
    )]
    monitors: Option<Vec<MonitorConfig>>,
    logging: Option<LoggingConfig>,
    runtime: Option<RuntimeConfig>,
    missions: Option<Vec<MissionsConfig>>,
    includes: Option<Vec<IncludesConfig>>,
}

#[derive(Deserialize)]
#[serde(untagged)]
enum OneOrManyMonitorConfig {
    One(MonitorConfig),
    Many(Vec<MonitorConfig>),
}

fn deserialize_monitor_configs<'de, D>(
    deserializer: D,
) -> Result<Option<Vec<MonitorConfig>>, D::Error>
where
    D: Deserializer<'de>,
{
    let parsed = Option::<OneOrManyMonitorConfig>::deserialize(deserializer)?;
    Ok(parsed.map(|value| match value {
        OneOrManyMonitorConfig::One(single) => vec![single],
        OneOrManyMonitorConfig::Many(many) => many,
    }))
}

/// Shared implementation for deserializing a CuConfigRepresentation into a CuConfig
fn deserialize_config_representation<E>(
    representation: &CuConfigRepresentation,
) -> Result<CuConfig, E>
where
    E: From<String>,
{
    let mut cuconfig = CuConfig::default();
    let bridge_lookup = build_bridge_lookup(representation.bridges.as_ref());

    if let Some(mission_configs) = &representation.missions {
        // This is the multi-mission case
        let mut missions = Missions(HashMap::new());

        for mission_config in mission_configs {
            let mission_id = mission_config.id.as_str();
            let graph = missions
                .add_mission(mission_id)
                .map_err(|e| E::from(e.to_string()))?;

            if let Some(tasks) = &representation.tasks {
                for task in tasks {
                    if let Some(task_missions) = &task.missions {
                        // if there is a filter by mission on the task, only add the task to the mission if it matches the filter.
                        if task_missions.contains(&mission_id.to_owned()) {
                            graph
                                .add_node(task.clone())
                                .map_err(|e| E::from(e.to_string()))?;
                        }
                    } else {
                        // if there is no filter by mission on the task, add the task to the mission.
                        graph
                            .add_node(task.clone())
                            .map_err(|e| E::from(e.to_string()))?;
                    }
                }
            }

            if let Some(bridges) = &representation.bridges {
                for bridge in bridges {
                    if mission_applies(&bridge.missions, mission_id) {
                        insert_bridge_node(graph, bridge).map_err(E::from)?;
                    }
                }
            }

            if let Some(cnx) = &representation.cnx {
                for (connection_order, c) in cnx.iter().enumerate() {
                    if let Some(cnx_missions) = &c.missions {
                        // if there is a filter by mission on the connection, only add the connection to the mission if it matches the filter.
                        if cnx_missions.contains(&mission_id.to_owned()) {
                            if c.dst == NC_ENDPOINT {
                                register_nc_output::<E>(
                                    graph,
                                    &c.src,
                                    &c.msg,
                                    connection_order,
                                    &bridge_lookup,
                                )?;
                                continue;
                            }
                            let (src_name, src_channel) =
                                parse_endpoint(&c.src, EndpointRole::Source, &bridge_lookup)
                                    .map_err(E::from)?;
                            let (dst_name, dst_channel) =
                                parse_endpoint(&c.dst, EndpointRole::Destination, &bridge_lookup)
                                    .map_err(E::from)?;
                            let src =
                                graph
                                    .get_node_id_by_name(src_name.as_str())
                                    .ok_or_else(|| {
                                        E::from(format!("Source node not found: {}", c.src))
                                    })?;
                            let dst =
                                graph
                                    .get_node_id_by_name(dst_name.as_str())
                                    .ok_or_else(|| {
                                        E::from(format!("Destination node not found: {}", c.dst))
                                    })?;
                            graph
                                .connect_ext_with_order(
                                    src,
                                    dst,
                                    &c.msg,
                                    Some(cnx_missions.clone()),
                                    src_channel,
                                    dst_channel,
                                    connection_order,
                                )
                                .map_err(|e| E::from(e.to_string()))?;
                        }
                    } else {
                        // if there is no filter by mission on the connection, add the connection to the mission.
                        if c.dst == NC_ENDPOINT {
                            register_nc_output::<E>(
                                graph,
                                &c.src,
                                &c.msg,
                                connection_order,
                                &bridge_lookup,
                            )?;
                            continue;
                        }
                        let (src_name, src_channel) =
                            parse_endpoint(&c.src, EndpointRole::Source, &bridge_lookup)
                                .map_err(E::from)?;
                        let (dst_name, dst_channel) =
                            parse_endpoint(&c.dst, EndpointRole::Destination, &bridge_lookup)
                                .map_err(E::from)?;
                        let src = graph
                            .get_node_id_by_name(src_name.as_str())
                            .ok_or_else(|| E::from(format!("Source node not found: {}", c.src)))?;
                        let dst =
                            graph
                                .get_node_id_by_name(dst_name.as_str())
                                .ok_or_else(|| {
                                    E::from(format!("Destination node not found: {}", c.dst))
                                })?;
                        graph
                            .connect_ext_with_order(
                                src,
                                dst,
                                &c.msg,
                                None,
                                src_channel,
                                dst_channel,
                                connection_order,
                            )
                            .map_err(|e| E::from(e.to_string()))?;
                    }
                }
            }
        }
        cuconfig.graphs = missions;
    } else {
        // this is the simple case
        let mut graph = CuGraph::default();

        if let Some(tasks) = &representation.tasks {
            for task in tasks {
                graph
                    .add_node(task.clone())
                    .map_err(|e| E::from(e.to_string()))?;
            }
        }

        if let Some(bridges) = &representation.bridges {
            for bridge in bridges {
                insert_bridge_node(&mut graph, bridge).map_err(E::from)?;
            }
        }

        if let Some(cnx) = &representation.cnx {
            for (connection_order, c) in cnx.iter().enumerate() {
                if c.dst == NC_ENDPOINT {
                    register_nc_output::<E>(
                        &mut graph,
                        &c.src,
                        &c.msg,
                        connection_order,
                        &bridge_lookup,
                    )?;
                    continue;
                }
                let (src_name, src_channel) =
                    parse_endpoint(&c.src, EndpointRole::Source, &bridge_lookup)
                        .map_err(E::from)?;
                let (dst_name, dst_channel) =
                    parse_endpoint(&c.dst, EndpointRole::Destination, &bridge_lookup)
                        .map_err(E::from)?;
                let src = graph
                    .get_node_id_by_name(src_name.as_str())
                    .ok_or_else(|| E::from(format!("Source node not found: {}", c.src)))?;
                let dst = graph
                    .get_node_id_by_name(dst_name.as_str())
                    .ok_or_else(|| E::from(format!("Destination node not found: {}", c.dst)))?;
                graph
                    .connect_ext_with_order(
                        src,
                        dst,
                        &c.msg,
                        None,
                        src_channel,
                        dst_channel,
                        connection_order,
                    )
                    .map_err(|e| E::from(e.to_string()))?;
            }
        }
        cuconfig.graphs = Simple(graph);
    }

    cuconfig.monitors = representation.monitors.clone().unwrap_or_default();
    cuconfig.constants = representation.constants.clone().unwrap_or_default();
    cuconfig.logging = representation.logging.clone();
    cuconfig.runtime = representation.runtime.clone();
    cuconfig.resources = representation.resources.clone().unwrap_or_default();
    cuconfig.log_streaming = representation.log_streaming.clone();
    cuconfig.bridges = representation.bridges.clone().unwrap_or_default();

    validate_thread_pools::<E>(&cuconfig.runtime)?;

    Ok(cuconfig)
}

impl<'de> Deserialize<'de> for CuConfig {
    /// This is a custom serialization to make this implementation independent of petgraph.
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let representation =
            CuConfigRepresentation::deserialize(deserializer).map_err(serde::de::Error::custom)?;

        // Convert String errors to D::Error using serde::de::Error::custom
        match deserialize_config_representation::<String>(&representation) {
            Ok(config) => Ok(config),
            Err(e) => Err(serde::de::Error::custom(e)),
        }
    }
}

impl Serialize for CuConfig {
    /// This is a custom serialization to make this implementation independent of petgraph.
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let bridges = if self.bridges.is_empty() {
            None
        } else {
            Some(self.bridges.clone())
        };
        let resources = if self.resources.is_empty() {
            None
        } else {
            Some(self.resources.clone())
        };
        let monitors = (!self.monitors.is_empty()).then_some(self.monitors.clone());
        match &self.graphs {
            Simple(graph) => {
                let tasks: Vec<Node> = graph
                    .0
                    .node_indices()
                    .map(|idx| graph.0[idx].clone())
                    .filter(|node| node.get_flavor() == Flavor::Task)
                    .collect();

                let mut ordered_cnx: Vec<(usize, SerializedCnx)> = graph
                    .0
                    .edge_indices()
                    .map(|edge_idx| {
                        let edge = &graph.0[edge_idx];
                        let order = if edge.order == usize::MAX {
                            edge_idx.index()
                        } else {
                            edge.order
                        };
                        (order, SerializedCnx::from(edge))
                    })
                    .collect();
                for node_idx in graph.0.node_indices() {
                    let node = &graph.0[node_idx];
                    if node.get_flavor() != Flavor::Task {
                        continue;
                    }
                    for (msg, order) in node.nc_outputs_with_order() {
                        ordered_cnx.push((
                            order,
                            SerializedCnx {
                                src: node.get_id(),
                                dst: NC_ENDPOINT.to_string(),
                                msg: msg.clone(),
                                missions: None,
                            },
                        ));
                    }
                }
                ordered_cnx.sort_by(|(order_a, cnx_a), (order_b, cnx_b)| {
                    order_a
                        .cmp(order_b)
                        .then_with(|| cnx_a.src.cmp(&cnx_b.src))
                        .then_with(|| cnx_a.dst.cmp(&cnx_b.dst))
                        .then_with(|| cnx_a.msg.cmp(&cnx_b.msg))
                });
                let cnx: Vec<SerializedCnx> = ordered_cnx
                    .into_iter()
                    .map(|(_, serialized)| serialized)
                    .collect();

                CuConfigRepresentation {
                    constants: (!self.constants.is_empty()).then_some(self.constants.clone()),
                    tasks: Some(tasks),
                    bridges: bridges.clone(),
                    cnx: Some(cnx),
                    monitors: monitors.clone(),
                    logging: self.logging.clone(),
                    runtime: self.runtime.clone(),
                    resources: resources.clone(),
                    log_streaming: self.log_streaming.clone(),
                    missions: None,
                    includes: None,
                }
                .serialize(serializer)
            }
            Missions(graphs) => {
                let missions = graphs
                    .keys()
                    .map(|id| MissionsConfig { id: id.clone() })
                    .collect();

                // Collect all unique tasks across missions
                let mut tasks = Vec::new();
                let mut ordered_cnx: Vec<(usize, SerializedCnx)> = Vec::new();

                for (mission_id, graph) in graphs {
                    // Add all nodes from this mission
                    for node_idx in graph.node_indices() {
                        let node = &graph[node_idx];
                        if node.get_flavor() == Flavor::Task
                            && !tasks.iter().any(|n: &Node| n.id == node.id)
                        {
                            tasks.push(node.clone());
                        }
                    }

                    // Add all edges from this mission
                    for edge_idx in graph.0.edge_indices() {
                        let edge = &graph.0[edge_idx];
                        let order = if edge.order == usize::MAX {
                            edge_idx.index()
                        } else {
                            edge.order
                        };
                        let serialized = SerializedCnx::from(edge);
                        if let Some((existing_order, existing_serialized)) =
                            ordered_cnx.iter_mut().find(|(_, c)| {
                                c.src == serialized.src
                                    && c.dst == serialized.dst
                                    && c.msg == serialized.msg
                            })
                        {
                            if order < *existing_order {
                                *existing_order = order;
                            }
                            merge_connection_missions(
                                &mut existing_serialized.missions,
                                &serialized.missions,
                            );
                        } else {
                            ordered_cnx.push((order, serialized));
                        }
                    }
                    for node_idx in graph.0.node_indices() {
                        let node = &graph.0[node_idx];
                        if node.get_flavor() != Flavor::Task {
                            continue;
                        }
                        for (msg, order) in node.nc_outputs_with_order() {
                            let serialized = SerializedCnx {
                                src: node.get_id(),
                                dst: NC_ENDPOINT.to_string(),
                                msg: msg.clone(),
                                missions: Some(vec![mission_id.clone()]),
                            };
                            if let Some((existing_order, existing_serialized)) =
                                ordered_cnx.iter_mut().find(|(_, c)| {
                                    c.src == serialized.src
                                        && c.dst == serialized.dst
                                        && c.msg == serialized.msg
                                })
                            {
                                if order < *existing_order {
                                    *existing_order = order;
                                }
                                merge_connection_missions(
                                    &mut existing_serialized.missions,
                                    &serialized.missions,
                                );
                            } else {
                                ordered_cnx.push((order, serialized));
                            }
                        }
                    }
                }
                ordered_cnx.sort_by(|(order_a, cnx_a), (order_b, cnx_b)| {
                    order_a
                        .cmp(order_b)
                        .then_with(|| cnx_a.src.cmp(&cnx_b.src))
                        .then_with(|| cnx_a.dst.cmp(&cnx_b.dst))
                        .then_with(|| cnx_a.msg.cmp(&cnx_b.msg))
                });
                let cnx: Vec<SerializedCnx> = ordered_cnx
                    .into_iter()
                    .map(|(_, serialized)| serialized)
                    .collect();

                CuConfigRepresentation {
                    constants: (!self.constants.is_empty()).then_some(self.constants.clone()),
                    tasks: Some(tasks),
                    resources: resources.clone(),
                    log_streaming: self.log_streaming.clone(),
                    bridges,
                    cnx: Some(cnx),
                    monitors,
                    logging: self.logging.clone(),
                    runtime: self.runtime.clone(),
                    missions: Some(missions),
                    includes: None,
                }
                .serialize(serializer)
            }
        }
    }
}

impl Default for CuConfig {
    fn default() -> Self {
        CuConfig {
            constants: Vec::new(),
            graphs: Simple(CuGraph(StableDiGraph::new())),
            monitors: Vec::new(),
            logging: None,
            runtime: None,
            resources: Vec::new(),
            log_streaming: None,
            bridges: Vec::new(),
        }
    }
}

/// The implementation has a lot of convenience methods to manipulate
/// the configuration to give some flexibility into programmatically creating the configuration.
impl CuConfig {
    #[allow(dead_code)]
    pub fn new_simple_type() -> Self {
        Self::default()
    }

    #[allow(dead_code)]
    pub fn new_mission_type() -> Self {
        CuConfig {
            constants: Vec::new(),
            graphs: Missions(HashMap::new()),
            monitors: Vec::new(),
            logging: None,
            runtime: None,
            resources: Vec::new(),
            log_streaming: None,
            bridges: Vec::new(),
        }
    }

    pub(crate) fn get_options() -> Options {
        Options::default()
            .with_default_extension(Extensions::IMPLICIT_SOME)
            .with_default_extension(Extensions::UNWRAP_NEWTYPES)
            .with_default_extension(Extensions::UNWRAP_VARIANT_NEWTYPES)
    }

    #[allow(dead_code)]
    pub fn serialize_ron(&self) -> CuResult<String> {
        let ron = Self::get_options();
        let pretty = ron::ser::PrettyConfig::default();
        ron.to_string_pretty(&self, pretty)
            .map_err(|e| CuError::from(format!("Error serializing configuration: {e}")))
    }

    #[allow(dead_code)]
    pub fn deserialize_ron(ron: &str) -> CuResult<Self> {
        let representation = Self::get_options().from_str(ron).map_err(|e| {
            CuError::from(format!(
                "Syntax Error in config: {} at position {}",
                e.code, e.span
            ))
        })?;
        Self::deserialize_impl(representation)
            .map_err(|e| CuError::from(format!("Error deserializing configuration: {e}")))
    }

    fn deserialize_impl(representation: CuConfigRepresentation) -> Result<Self, String> {
        deserialize_config_representation(&representation)
    }

    /// Render the configuration graph in the dot format.
    #[cfg(feature = "std")]
    #[allow(dead_code)]
    pub fn render(
        &self,
        output: &mut dyn std::io::Write,
        mission_id: Option<&str>,
    ) -> CuResult<()> {
        writeln!(output, "digraph G {{")
            .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;
        writeln!(output, "    graph [rankdir=LR, nodesep=0.8, ranksep=1.2];")
            .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;
        writeln!(output, "    node [shape=plain, fontname=\"Noto Sans\"];")
            .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;
        writeln!(output, "    edge [fontname=\"Noto Sans\"];")
            .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;

        let sections = match (&self.graphs, mission_id) {
            (Simple(graph), _) => vec![RenderSection { label: None, graph }],
            (Missions(graphs), Some(id)) => {
                let graph = graphs
                    .get(id)
                    .ok_or_else(|| CuError::from(format!("Mission {id} not found")))?;
                vec![RenderSection {
                    label: Some(id.to_string()),
                    graph,
                }]
            }
            (Missions(graphs), None) => {
                let mut missions: Vec<_> = graphs.iter().collect();
                missions.sort_by(|a, b| a.0.cmp(b.0));
                missions
                    .into_iter()
                    .map(|(label, graph)| RenderSection {
                        label: Some(label.clone()),
                        graph,
                    })
                    .collect()
            }
        };

        for section in sections {
            self.render_section(output, section.graph, section.label.as_deref())?;
        }

        writeln!(output, "}}")
            .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;
        Ok(())
    }

    #[allow(dead_code)]
    pub fn get_all_instances_configs(
        &self,
        mission_id: Option<&str>,
    ) -> Vec<Option<&ComponentConfig>> {
        let graph = self.graphs.get_graph(mission_id).unwrap();
        graph
            .get_all_nodes()
            .iter()
            .map(|(_, node)| node.get_instance_config())
            .collect()
    }

    #[allow(dead_code)]
    pub fn get_graph(&self, mission_id: Option<&str>) -> CuResult<&CuGraph> {
        self.graphs.get_graph(mission_id)
    }

    #[allow(dead_code)]
    pub fn get_graph_mut(&mut self, mission_id: Option<&str>) -> CuResult<&mut CuGraph> {
        self.graphs.get_graph_mut(mission_id)
    }

    #[allow(dead_code)]
    pub fn get_monitor_config(&self) -> Option<&MonitorConfig> {
        self.monitors.first()
    }

    #[allow(dead_code)]
    pub fn get_monitor_configs(&self) -> &[MonitorConfig] {
        &self.monitors
    }

    #[allow(dead_code)]
    pub fn get_runtime_config(&self) -> Option<&RuntimeConfig> {
        self.runtime.as_ref()
    }

    #[allow(dead_code)]
    pub fn find_task_node(&self, mission_id: Option<&str>, task_id: &str) -> Option<&Node> {
        self.get_graph(mission_id)
            .ok()?
            .get_all_nodes()
            .into_iter()
            .find_map(|(_, node)| {
                (node.get_flavor() == Flavor::Task && node.id == task_id).then_some(node)
            })
    }

    #[allow(dead_code)]
    pub fn find_logging_codec_spec(&self, codec_id: &str) -> Option<&LoggingCodecSpec> {
        self.logging
            .as_ref()?
            .codecs
            .iter()
            .find(|spec| spec.id == codec_id)
    }

    /// Validate compile-time constant names, shapes, scalar ranges, and unit compatibility.
    pub fn validate_constants(&self) -> CuResult<()> {
        fn validate_integer(
            id: &str,
            storage: ConstantStorage,
            number: ConstantNumber,
        ) -> CuResult<()> {
            let valid = match (storage, number) {
                (ConstantStorage::I8, ConstantNumber::Signed(value)) => i8::try_from(value).is_ok(),
                (ConstantStorage::I16, ConstantNumber::Signed(value)) => {
                    i16::try_from(value).is_ok()
                }
                (ConstantStorage::I32, ConstantNumber::Signed(value)) => {
                    i32::try_from(value).is_ok()
                }
                (ConstantStorage::I64, ConstantNumber::Signed(_)) => true,
                (ConstantStorage::Isize, ConstantNumber::Signed(value)) => {
                    isize::try_from(value).is_ok()
                }
                (ConstantStorage::U8, ConstantNumber::Unsigned(value)) => {
                    u8::try_from(value).is_ok()
                }
                (ConstantStorage::U16, ConstantNumber::Unsigned(value)) => {
                    u16::try_from(value).is_ok()
                }
                (ConstantStorage::U32, ConstantNumber::Unsigned(value)) => {
                    u32::try_from(value).is_ok()
                }
                (ConstantStorage::U64, ConstantNumber::Unsigned(_)) => true,
                (ConstantStorage::Usize, ConstantNumber::Unsigned(value)) => {
                    usize::try_from(value).is_ok()
                }
                _ => false,
            };
            if valid {
                Ok(())
            } else {
                Err(CuError::from(format!(
                    "Constant '{id}' value {number:?} cannot be represented as {}",
                    storage.rust_type()
                )))
            }
        }

        let mut ids = HashMap::new();
        for constant in &self.constants {
            if constant.id().is_empty() {
                return Err(CuError::from("Constant ids cannot be empty"));
            }
            if ids
                .insert((constant.module_path(), constant.id()), ())
                .is_some()
            {
                return Err(CuError::from(format!(
                    "Duplicate constant '{}'. Constant ids must be unique within a module.",
                    constant.qualified_id()
                )));
            }

            match (
                constant.value.is_some(),
                constant.rust_type.as_deref(),
                constant.expression.as_deref(),
            ) {
                (true, None, None) => {}
                (true, _, _) => {
                    return Err(CuError::from(format!(
                        "Constant '{}' cannot combine numeric 'value' with 'type' or 'expression'",
                        constant.id()
                    )));
                }
                (false, Some(rust_type), Some(expression)) => {
                    if constant.storage.is_some()
                        || constant.quantity.is_some()
                        || constant.unit.is_some()
                    {
                        return Err(CuError::from(format!(
                            "Constant '{}' cannot combine 'type' and 'expression' with numeric 'storage', 'quantity', or 'unit'",
                            constant.id()
                        )));
                    }
                    if rust_type.trim().is_empty() {
                        return Err(CuError::from(format!(
                            "Constant '{}' type cannot be empty",
                            constant.id()
                        )));
                    }
                    if expression.trim().is_empty() {
                        return Err(CuError::from(format!(
                            "Constant '{}' expression cannot be empty",
                            constant.id()
                        )));
                    }
                    continue;
                }
                (false, Some(_), None) => {
                    return Err(CuError::from(format!(
                        "Constant '{}' declares 'type' without 'expression'",
                        constant.id()
                    )));
                }
                (false, None, Some(_)) => {
                    return Err(CuError::from(format!(
                        "Constant '{}' declares 'expression' without 'type'",
                        constant.id()
                    )));
                }
                (false, None, None) => {
                    return Err(CuError::from(format!(
                        "Constant '{}' must declare either numeric 'value' or both 'type' and 'expression'",
                        constant.id()
                    )));
                }
            }

            if constant.quantity().is_none() && constant.explicit_unit().is_some() {
                return Err(CuError::from(format!(
                    "Constant '{}' declares a unit without a quantity",
                    constant.id()
                )));
            }

            if constant.quantity().is_some() {
                if !constant.storage().supports_quantity() {
                    return Err(CuError::from(format!(
                        "Constant '{}' quantity '{}' requires storage f32 or f64, not {}",
                        constant.id(),
                        constant.quantity().map_or("", |quantity| quantity.name()),
                        constant.storage().rust_type()
                    )));
                }
                let normalized = match constant.storage() {
                    ConstantStorage::F32 => constant.normalized_f32().map(|_| ()),
                    ConstantStorage::F64 => constant.normalized_f64().map(|_| ()),
                    _ => unreachable!("quantity storage was checked above"),
                };
                normalized.map_err(CuError::from)?;
                continue;
            }

            let (_, numbers) = constant.numbers().map_err(CuError::from)?;
            for number in numbers {
                match constant.storage() {
                    ConstantStorage::F32 => {
                        if !(number.as_f64() as f32).is_finite() {
                            return Err(CuError::from(format!(
                                "Constant '{}' values must be finite",
                                constant.id()
                            )));
                        }
                    }
                    ConstantStorage::F64 => {
                        if !number.as_f64().is_finite() {
                            return Err(CuError::from(format!(
                                "Constant '{}' values must be finite",
                                constant.id()
                            )));
                        }
                    }
                    storage => validate_integer(constant.id(), storage, number)?,
                }
            }
        }
        Ok(())
    }

    /// Validate the logging configuration to ensure section pre-allocation sizes do not exceed slab sizes.
    /// This method is wrapper around [LoggingConfig::validate]
    pub fn validate_logging_config(&self) -> CuResult<()> {
        if let Some(logging) = &self.logging {
            return logging.validate();
        }
        Ok(())
    }

    /// Validate the runtime configuration.
    pub fn validate_runtime_config(&self) -> CuResult<()> {
        if let Some(runtime) = &self.runtime {
            return runtime.validate();
        }
        Ok(())
    }

    /// Validates every `anytime:` policy in the resolved graphs.
    ///
    /// Runs at configuration-resolution time, the first point where both the
    /// resolved graphs and `runtime.rate_target_hz` are known:
    ///
    /// 1. node-local bounds and ranges (see [`AnytimeConfig`]);
    /// 2. `anytime:` is only supported on regular tasks — refinement needs both
    ///    an input and an output;
    /// 3. an anytime task has exactly one input connection (the runner anchors
    ///    the job on the input's Tov) and at most one output message type
    ///    (`base()` and every `refine()` write the same output slot);
    /// 4. a *foreground* anytime task needs `max_refines`: the execution plan
    ///    is static (the node compiles to a base step plus `max_refines` refine
    ///    steps, see `curuntime::expand_anytime_steps`), so the refine count
    ///    must be known at compile time;
    /// 5. fit the period: a *foreground* anytime task in a rate-limited config
    ///    must set a time bound (`time_budget_ms` or `max_age_ms`), and the
    ///    worst-case window — `min` of the ones set — must be smaller than the
    ///    loop period. Background nodes and configs without a rate target skip
    ///    this check.
    pub fn validate_anytime_configs(&self) -> CuResult<()> {
        let rate_target_hz = self.runtime.as_ref().and_then(|r| r.rate_target_hz);
        match &self.graphs {
            Simple(graph) => validate_anytime_graph(graph, rate_target_hz),
            Missions(graphs) => {
                for graph in graphs.values() {
                    validate_anytime_graph(graph, rate_target_hz)?;
                }
                Ok(())
            }
        }
    }
}

/// Checks every `anytime:` node of one graph: local bounds, regular-task kind,
/// single-input/single-output arity, and the foreground fit-the-period rule
/// (see [`CuConfig::validate_anytime_configs`]).
fn validate_anytime_graph(graph: &CuGraph, rate_target_hz: Option<u64>) -> CuResult<()> {
    for (node_id, node) in graph.get_all_nodes() {
        let Some(anytime) = node.anytime() else {
            continue;
        };
        anytime.validate(&node.id)?;

        let kind = resolve_task_kind_for_id(graph, node_id)?;
        if kind != TaskKind::Regular {
            return Err(CuError::from(format!(
                "Task '{}' is declared with an anytime: policy but resolves to kind '{}'. Anytime refinement needs both an input and an output, so it is only supported on regular tasks.",
                node.id,
                kind.as_str()
            )));
        }

        // Foreground and background alike: the runner reads the job anchor
        // from the single input's Tov, and base()/refine() write one stable
        // output slot. Zero declared outputs is fine when the kind is
        // declared — the macro synthesizes exactly one nc output.
        let input_count = graph.get_dst_edges(node_id)?.len();
        if input_count != 1 {
            return Err(CuError::from(format!(
                "Task '{}' is an anytime task and must have exactly one input connection (found {input_count}): the runner anchors the job on the input's Tov.",
                node.id
            )));
        }
        let output_count = graph.get_node_output_msg_types_by_id(node_id)?.len();
        if output_count > 1 {
            return Err(CuError::from(format!(
                "Task '{}' is an anytime task and must have exactly one output message type (found {output_count}): base() and every refine() write the same output slot.",
                node.id
            )));
        }

        // Background placement: the refinement window runs on a worker thread
        // and may exceed the copperlist period — that is the point of it.
        if node.is_background() {
            continue;
        }

        // Foreground placement compiles to a static plan: the node's step is
        // followed by exactly max_refines refine steps, so the count must be
        // known here — a time-only hard bound cannot produce a static plan.
        if anytime.max_refines.is_none() {
            return Err(CuError::from(format!(
                "Task '{}' is a foreground anytime task and needs anytime.max_refines: the execution plan is static, so the refine step count must be known at compile time. time_budget_ms/max_age_ms remain early-stop conditions within those quanta.",
                node.id
            )));
        }

        let Some(rate_target_hz) = rate_target_hz else {
            continue;
        };
        let window_ms = match (anytime.time_budget_ms, anytime.max_age_ms) {
            (Some(budget), Some(age)) => budget.min(age),
            (Some(budget), None) => budget,
            (None, Some(age)) => age,
            (None, None) => {
                return Err(CuError::from(format!(
                    "Task '{}' is a foreground anytime task in a rate-limited config and needs a time bound: set anytime.time_budget_ms or anytime.max_age_ms. max_refines alone gives the runtime no time quantity to check against the {rate_target_hz} Hz loop period, and one slow quantum would silently overrun it.",
                    node.id
                )));
            }
        };
        let period_ms = 1_000.0 / rate_target_hz as f64;
        if window_ms >= period_ms {
            return Err(CuError::from(format!(
                "Task '{}': the worst-case anytime window ({window_ms} ms) does not fit within the {rate_target_hz} Hz loop period ({period_ms} ms) with headroom for the rest of the copperlist. Tighten the time bound, lower runtime.rate_target_hz, or run the task with background: true.",
                node.id
            )));
        }
    }
    Ok(())
}

#[cfg(feature = "std")]
#[derive(Default)]
pub(crate) struct PortLookup {
    pub inputs: HashMap<String, String>,
    pub outputs: HashMap<String, String>,
    pub default_input: Option<String>,
    pub default_output: Option<String>,
}

#[cfg(feature = "std")]
#[derive(Clone)]
pub(crate) struct RenderNode {
    pub id: String,
    pub type_name: String,
    pub flavor: Flavor,
    pub inputs: Vec<String>,
    pub outputs: Vec<String>,
}

#[cfg(feature = "std")]
#[derive(Clone)]
pub(crate) struct RenderConnection {
    pub src: String,
    pub src_port: Option<String>,
    #[allow(dead_code)]
    pub src_channel: Option<String>,
    pub dst: String,
    pub dst_port: Option<String>,
    #[allow(dead_code)]
    pub dst_channel: Option<String>,
    pub msg: String,
}

#[cfg(feature = "std")]
pub(crate) struct RenderTopology {
    pub nodes: Vec<RenderNode>,
    pub connections: Vec<RenderConnection>,
}

#[cfg(feature = "std")]
impl RenderTopology {
    pub fn sort_connections(&mut self) {
        self.connections.sort_by(|a, b| {
            a.src
                .cmp(&b.src)
                .then(a.dst.cmp(&b.dst))
                .then(a.msg.cmp(&b.msg))
        });
    }
}

#[cfg(feature = "std")]
#[allow(dead_code)]
struct RenderSection<'a> {
    label: Option<String>,
    graph: &'a CuGraph,
}

#[cfg(feature = "std")]
impl CuConfig {
    #[allow(dead_code)]
    fn render_section(
        &self,
        output: &mut dyn std::io::Write,
        graph: &CuGraph,
        label: Option<&str>,
    ) -> CuResult<()> {
        use std::fmt::Write as FmtWrite;

        let mut topology = build_render_topology(graph, &self.bridges);
        topology.nodes.sort_by(|a, b| a.id.cmp(&b.id));
        topology.sort_connections();

        let cluster_id = label.map(|lbl| format!("cluster_{}", sanitize_identifier(lbl)));
        if let Some(ref cluster_id) = cluster_id {
            writeln!(output, "    subgraph \"{cluster_id}\" {{")
                .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;
            writeln!(
                output,
                "        label=<<B>Mission: {}</B>>;",
                encode_text(label.unwrap())
            )
            .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;
            writeln!(
                output,
                "        labelloc=t; labeljust=l; color=\"#bbbbbb\"; style=\"rounded\"; margin=20;"
            )
            .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;
        }
        let indent = if cluster_id.is_some() {
            "        "
        } else {
            "    "
        };
        let node_prefix = label
            .map(|lbl| format!("{}__", sanitize_identifier(lbl)))
            .unwrap_or_default();

        let mut port_lookup: HashMap<String, PortLookup> = HashMap::new();
        let mut id_lookup: HashMap<String, String> = HashMap::new();

        for node in &topology.nodes {
            let node_idx = graph
                .get_node_id_by_name(node.id.as_str())
                .ok_or_else(|| CuError::from(format!("Node '{}' missing from graph", node.id)))?;
            let node_weight = graph
                .get_node(node_idx)
                .ok_or_else(|| CuError::from(format!("Node '{}' missing weight", node.id)))?;

            let fillcolor = match node.flavor {
                Flavor::Bridge => "#faedcd",
                Flavor::Task => match resolve_task_kind_for_id(graph, node_idx)? {
                    TaskKind::Source => "#ddefc7",
                    TaskKind::Sink => "#cce0ff",
                    TaskKind::Regular => "#f2f2f2",
                },
            };

            let port_base = format!("{}{}", node_prefix, sanitize_identifier(&node.id));
            let (inputs_table, input_map, default_input) =
                build_port_table("Inputs", &node.inputs, &port_base, "in");
            let (outputs_table, output_map, default_output) =
                build_port_table("Outputs", &node.outputs, &port_base, "out");
            let config_html = node_weight.config.as_ref().and_then(build_config_table);

            let mut label_html = String::new();
            write!(
                label_html,
                "<TABLE BORDER=\"0\" CELLBORDER=\"1\" CELLSPACING=\"0\" CELLPADDING=\"6\" COLOR=\"gray\" BGCOLOR=\"white\">"
            )
            .unwrap();
            write!(
                label_html,
                "<TR><TD COLSPAN=\"2\" ALIGN=\"LEFT\" BGCOLOR=\"{fillcolor}\"><FONT POINT-SIZE=\"12\"><B>{}</B></FONT><BR/><FONT COLOR=\"dimgray\">[{}]</FONT></TD></TR>",
                encode_text(&node.id),
                encode_text(&node.type_name)
            )
            .unwrap();
            write!(
                label_html,
                "<TR><TD ALIGN=\"LEFT\" VALIGN=\"TOP\">{inputs_table}</TD><TD ALIGN=\"LEFT\" VALIGN=\"TOP\">{outputs_table}</TD></TR>"
            )
            .unwrap();

            if let Some(config_html) = config_html {
                write!(
                    label_html,
                    "<TR><TD COLSPAN=\"2\" ALIGN=\"LEFT\">{config_html}</TD></TR>"
                )
                .unwrap();
            }

            label_html.push_str("</TABLE>");

            let identifier_raw = if node_prefix.is_empty() {
                node.id.clone()
            } else {
                format!("{node_prefix}{}", node.id)
            };
            let identifier = escape_dot_id(&identifier_raw);
            writeln!(output, "{indent}\"{identifier}\" [label=<{label_html}>];")
                .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;

            id_lookup.insert(node.id.clone(), identifier);
            port_lookup.insert(
                node.id.clone(),
                PortLookup {
                    inputs: input_map,
                    outputs: output_map,
                    default_input,
                    default_output,
                },
            );
        }

        for cnx in &topology.connections {
            let src_id = id_lookup
                .get(&cnx.src)
                .ok_or_else(|| CuError::from(format!("Unknown node '{}'", cnx.src)))?;
            let dst_id = id_lookup
                .get(&cnx.dst)
                .ok_or_else(|| CuError::from(format!("Unknown node '{}'", cnx.dst)))?;
            let src_suffix = port_lookup
                .get(&cnx.src)
                .and_then(|lookup| lookup.resolve_output(cnx.src_port.as_deref()))
                .map(|port| format!(":\"{port}\":e"))
                .unwrap_or_default();
            let dst_suffix = port_lookup
                .get(&cnx.dst)
                .and_then(|lookup| lookup.resolve_input(cnx.dst_port.as_deref()))
                .map(|port| format!(":\"{port}\":w"))
                .unwrap_or_default();
            let msg = encode_text(&cnx.msg);
            writeln!(
                output,
                "{indent}\"{src_id}\"{src_suffix} -> \"{dst_id}\"{dst_suffix} [label=< <B><FONT COLOR=\"gray\">{msg}</FONT></B> >];"
            )
            .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;
        }

        if cluster_id.is_some() {
            writeln!(output, "    }}")
                .map_err(|e| CuError::new_with_cause("Failed to write render output", e))?;
        }

        Ok(())
    }
}

#[cfg(feature = "std")]
pub(crate) fn build_render_topology(graph: &CuGraph, bridges: &[BridgeConfig]) -> RenderTopology {
    let mut bridge_lookup = HashMap::new();
    for bridge in bridges {
        bridge_lookup.insert(bridge.id.as_str(), bridge);
    }

    let mut nodes: Vec<RenderNode> = Vec::new();
    let mut node_lookup: HashMap<String, usize> = HashMap::new();
    for (node_idx, node) in graph.get_all_nodes() {
        let node_id = node.get_id();
        let mut inputs = Vec::new();
        let mut outputs = Vec::new();
        if node.get_flavor() == Flavor::Bridge
            && let Some(bridge) = bridge_lookup.get(node_id.as_str())
        {
            for channel in &bridge.channels {
                match channel {
                    // Rx brings data from the bridge into the graph, so treat it as an output.
                    BridgeChannelConfigRepresentation::Rx { id, .. } => outputs.push(id.clone()),
                    // Tx consumes data from the graph heading into the bridge, so show it on the input side.
                    BridgeChannelConfigRepresentation::Tx { id, .. } => inputs.push(id.clone()),
                }
            }
        } else if node.get_flavor() == Flavor::Task {
            for (idx, msg) in graph
                .get_node_output_msg_types_by_id(node_idx)
                .unwrap_or_default()
                .into_iter()
                .enumerate()
            {
                outputs.push(format!("out{idx}: {msg}"));
            }
        }

        node_lookup.insert(node_id.clone(), nodes.len());
        nodes.push(RenderNode {
            id: node_id,
            type_name: node.get_type().to_string(),
            flavor: node.get_flavor(),
            inputs,
            outputs,
        });
    }

    let mut output_port_lookup: Vec<HashMap<String, String>> = vec![HashMap::new(); nodes.len()];
    for (node_idx, node) in graph.get_all_nodes() {
        let Some(&idx) = node_lookup.get(&node.get_id()) else {
            continue;
        };
        if node.get_flavor() != Flavor::Task {
            continue;
        }
        for (port_idx, msg) in graph
            .get_node_output_msg_types_by_id(node_idx)
            .unwrap_or_default()
            .into_iter()
            .enumerate()
        {
            output_port_lookup[idx].insert(msg.clone(), format!("out{port_idx}: {msg}"));
        }
    }

    let mut auto_input_counts = vec![0usize; nodes.len()];
    for edge in graph.0.edge_references() {
        let cnx = edge.weight();
        if let Some(&idx) = node_lookup.get(&cnx.dst)
            && nodes[idx].flavor == Flavor::Task
            && cnx.dst_channel.is_none()
        {
            auto_input_counts[idx] += 1;
        }
    }

    let mut next_auto_input = vec![0usize; nodes.len()];
    let mut connections = Vec::new();
    for edge in graph.0.edge_references() {
        let cnx = edge.weight();
        let mut src_port = cnx.src_channel.clone();
        let mut dst_port = cnx.dst_channel.clone();

        if let Some(&idx) = node_lookup.get(&cnx.src) {
            let node = &mut nodes[idx];
            if node.flavor == Flavor::Task && src_port.is_none() {
                src_port = output_port_lookup[idx].get(&cnx.msg).cloned();
            }
        }
        if let Some(&idx) = node_lookup.get(&cnx.dst) {
            let node = &mut nodes[idx];
            if node.flavor == Flavor::Task && dst_port.is_none() {
                let count = auto_input_counts[idx];
                let next = if count <= 1 {
                    "in".to_string()
                } else {
                    let next = format!("in.{}", next_auto_input[idx]);
                    next_auto_input[idx] += 1;
                    next
                };
                node.inputs.push(next.clone());
                dst_port = Some(next);
            }
        }

        connections.push(RenderConnection {
            src: cnx.src.clone(),
            src_port,
            src_channel: cnx.src_channel.clone(),
            dst: cnx.dst.clone(),
            dst_port,
            dst_channel: cnx.dst_channel.clone(),
            msg: cnx.msg.clone(),
        });
    }

    RenderTopology { nodes, connections }
}

#[cfg(feature = "std")]
impl PortLookup {
    pub fn resolve_input(&self, name: Option<&str>) -> Option<&str> {
        if let Some(name) = name
            && let Some(port) = self.inputs.get(name)
        {
            return Some(port.as_str());
        }
        self.default_input.as_deref()
    }

    pub fn resolve_output(&self, name: Option<&str>) -> Option<&str> {
        if let Some(name) = name
            && let Some(port) = self.outputs.get(name)
        {
            return Some(port.as_str());
        }
        self.default_output.as_deref()
    }
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn build_port_table(
    title: &str,
    names: &[String],
    base_id: &str,
    prefix: &str,
) -> (String, HashMap<String, String>, Option<String>) {
    use std::fmt::Write as FmtWrite;

    let mut html = String::new();
    write!(
        html,
        "<TABLE BORDER=\"0\" CELLBORDER=\"0\" CELLSPACING=\"0\" CELLPADDING=\"1\">"
    )
    .unwrap();
    write!(
        html,
        "<TR><TD ALIGN=\"LEFT\"><FONT COLOR=\"dimgray\">{}</FONT></TD></TR>",
        encode_text(title)
    )
    .unwrap();

    let mut lookup = HashMap::new();
    let mut default_port = None;

    if names.is_empty() {
        html.push_str("<TR><TD ALIGN=\"LEFT\"><FONT COLOR=\"lightgray\">&mdash;</FONT></TD></TR>");
    } else {
        for (idx, name) in names.iter().enumerate() {
            let port_id = format!("{base_id}_{prefix}_{idx}");
            write!(
                html,
                "<TR><TD PORT=\"{port_id}\" ALIGN=\"LEFT\">{}</TD></TR>",
                encode_text(name)
            )
            .unwrap();
            lookup.insert(name.clone(), port_id.clone());
            if idx == 0 {
                default_port = Some(port_id);
            }
        }
    }

    html.push_str("</TABLE>");
    (html, lookup, default_port)
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn build_config_table(config: &ComponentConfig) -> Option<String> {
    use std::fmt::Write as FmtWrite;

    if config.0.is_empty() {
        return None;
    }

    let mut entries: Vec<_> = config.0.iter().collect();
    entries.sort_by(|a, b| a.0.cmp(b.0));

    let mut html = String::new();
    html.push_str("<TABLE BORDER=\"0\" CELLBORDER=\"0\" CELLSPACING=\"0\" CELLPADDING=\"1\">");
    for (key, value) in entries {
        let value_txt = format!("{value}");
        write!(
            html,
            "<TR><TD ALIGN=\"LEFT\"><FONT COLOR=\"dimgray\">{}</FONT> = {}</TD></TR>",
            encode_text(key),
            encode_text(&value_txt)
        )
        .unwrap();
    }
    html.push_str("</TABLE>");
    Some(html)
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn sanitize_identifier(value: &str) -> String {
    value
        .chars()
        .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
        .collect()
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn escape_dot_id(value: &str) -> String {
    let mut escaped = String::with_capacity(value.len());
    for ch in value.chars() {
        match ch {
            '"' => escaped.push_str("\\\""),
            '\\' => escaped.push_str("\\\\"),
            _ => escaped.push(ch),
        }
    }
    escaped
}

impl LoggingConfig {
    /// Validate the logging configuration to ensure section pre-allocation sizes do not exceed slab sizes.
    pub fn validate(&self) -> CuResult<()> {
        if let Some(copperlist_count) = self.copperlist_count
            && copperlist_count == 0
        {
            return Err(CuError::from(
                "CopperList count cannot be zero. Set logging.copperlist_count to at least 1.",
            ));
        }

        if let Some(section_size_mib) = self.section_size_mib
            && let Some(slab_size_mib) = self.slab_size_mib
            && section_size_mib > slab_size_mib
        {
            return Err(CuError::from(format!(
                "Section size ({section_size_mib} MiB) cannot be larger than slab size ({slab_size_mib} MiB). Adjust the parameters accordingly."
            )));
        }

        let mut codec_ids = HashMap::new();
        for codec in &self.codecs {
            if codec_ids.insert(codec.id.as_str(), ()).is_some() {
                return Err(CuError::from(format!(
                    "Duplicate logging codec id '{}'. Codec ids must be unique.",
                    codec.id
                )));
            }
        }

        Ok(())
    }
}

impl RuntimeConfig {
    /// Validate runtime loop-rate settings.
    pub fn validate(&self) -> CuResult<()> {
        if let Some(rate_target_hz) = self.rate_target_hz {
            if rate_target_hz == 0 {
                return Err(CuError::from(
                    "Runtime rate target cannot be zero. Set runtime.rate_target_hz to at least 1.",
                ));
            }

            if rate_target_hz > MAX_RATE_TARGET_HZ {
                return Err(CuError::from(format!(
                    "Runtime rate target ({rate_target_hz} Hz) exceeds the supported maximum of {MAX_RATE_TARGET_HZ} Hz."
                )));
            }
        }

        Ok(())
    }
}

#[allow(dead_code)] // dead in no-std
fn substitute_parameters(content: &str, params: &HashMap<String, Value>) -> String {
    let mut result = content.to_string();

    for (key, value) in params {
        let pattern = format!("{{{{{key}}}}}");
        result = result.replace(&pattern, &value.to_string());
    }

    result
}

/// Returns a merged CuConfigRepresentation.
#[cfg(feature = "std")]
fn process_includes(
    file_path: &str,
    base_representation: CuConfigRepresentation,
    processed_files: &mut Vec<String>,
    active_features: &[&str],
) -> CuResult<CuConfigRepresentation> {
    // Note: Circular dependency detection removed
    processed_files.push(file_path.to_string());

    let mut result = base_representation;

    if let Some(includes) = result.includes.take() {
        for include in includes {
            if include
                .when
                .as_ref()
                .is_some_and(|predicate| !predicate.evaluate(active_features))
            {
                continue;
            }

            let include_path = if include.path.starts_with('/') {
                include.path.clone()
            } else {
                let current_dir = std::path::Path::new(file_path).parent();

                match current_dir.map(|path| path.to_string_lossy().to_string()) {
                    Some(current_dir) if !current_dir.is_empty() => {
                        format!("{}/{}", current_dir, include.path)
                    }
                    _ => include.path,
                }
            };

            let include_content = read_to_string(&include_path).map_err(|e| {
                CuError::from(format!("Failed to read include file: {include_path}"))
                    .add_cause(e.to_string().as_str())
            })?;

            let processed_content = substitute_parameters(&include_content, &include.params);

            let mut included_representation: CuConfigRepresentation = match Options::default()
                .with_default_extension(Extensions::IMPLICIT_SOME)
                .with_default_extension(Extensions::UNWRAP_NEWTYPES)
                .with_default_extension(Extensions::UNWRAP_VARIANT_NEWTYPES)
                .from_str(&processed_content)
            {
                Ok(rep) => rep,
                Err(e) => {
                    return Err(CuError::from(format!(
                        "Failed to parse include file: {} - Error: {} at position {}",
                        include_path, e.code, e.span
                    )));
                }
            };

            included_representation = process_includes(
                &include_path,
                included_representation,
                processed_files,
                active_features,
            )?;

            if let Some(included_constants) = included_representation.constants {
                if result.constants.is_none() {
                    result.constants = Some(included_constants);
                } else {
                    let mut constants = result.constants.take().unwrap();
                    for included_constant in included_constants {
                        if !constants.iter().any(|constant| {
                            constant.id == included_constant.id
                                && constant.module_path() == included_constant.module_path()
                        }) {
                            constants.push(included_constant);
                        }
                    }
                    result.constants = Some(constants);
                }
            }

            if let Some(included_tasks) = included_representation.tasks {
                if result.tasks.is_none() {
                    result.tasks = Some(included_tasks);
                } else {
                    let mut tasks = result.tasks.take().unwrap();
                    for included_task in included_tasks {
                        if !tasks.iter().any(|t| t.id == included_task.id) {
                            tasks.push(included_task);
                        }
                    }
                    result.tasks = Some(tasks);
                }
            }

            if let Some(included_bridges) = included_representation.bridges {
                if result.bridges.is_none() {
                    result.bridges = Some(included_bridges);
                } else {
                    let mut bridges = result.bridges.take().unwrap();
                    for included_bridge in included_bridges {
                        if !bridges.iter().any(|b| b.id == included_bridge.id) {
                            bridges.push(included_bridge);
                        }
                    }
                    result.bridges = Some(bridges);
                }
            }

            if let Some(included_resources) = included_representation.resources {
                if result.resources.is_none() {
                    result.resources = Some(included_resources);
                } else {
                    let mut resources = result.resources.take().unwrap();
                    for included_resource in included_resources {
                        if !resources.iter().any(|r| r.id == included_resource.id) {
                            resources.push(included_resource);
                        }
                    }
                    result.resources = Some(resources);
                }
            }

            if let Some(included_cnx) = included_representation.cnx {
                if result.cnx.is_none() {
                    result.cnx = Some(included_cnx);
                } else {
                    let mut cnx = result.cnx.take().unwrap();
                    for included_c in included_cnx {
                        if let Some(existing_cnx) = cnx.iter_mut().find(|c| {
                            c.src == included_c.src
                                && c.dst == included_c.dst
                                && c.msg == included_c.msg
                        }) {
                            merge_connection_missions(
                                &mut existing_cnx.missions,
                                &included_c.missions,
                            );
                        } else {
                            cnx.push(included_c);
                        }
                    }
                    result.cnx = Some(cnx);
                }
            }

            if let Some(included_monitors) = included_representation.monitors {
                if result.monitors.is_none() {
                    result.monitors = Some(included_monitors);
                } else {
                    let mut monitors = result.monitors.take().unwrap();
                    for included_monitor in included_monitors {
                        if !monitors.iter().any(|m| m.type_ == included_monitor.type_) {
                            monitors.push(included_monitor);
                        }
                    }
                    result.monitors = Some(monitors);
                }
            }

            if result.logging.is_none() {
                result.logging = included_representation.logging;
            }

            if result.runtime.is_none() {
                result.runtime = included_representation.runtime;
            }

            if result.log_streaming.is_none() {
                result.log_streaming = included_representation.log_streaming;
            }

            if let Some(included_missions) = included_representation.missions {
                if result.missions.is_none() {
                    result.missions = Some(included_missions);
                } else {
                    let mut missions = result.missions.take().unwrap();
                    for included_mission in included_missions {
                        if !missions.iter().any(|m| m.id == included_mission.id) {
                            missions.push(included_mission);
                        }
                    }
                    result.missions = Some(missions);
                }
            }
        }
    }

    Ok(result)
}

#[cfg(feature = "std")]
fn parse_instance_config_overrides_string(
    content: &str,
) -> CuResult<InstanceConfigOverridesRepresentation> {
    Options::default()
        .with_default_extension(Extensions::IMPLICIT_SOME)
        .with_default_extension(Extensions::UNWRAP_NEWTYPES)
        .with_default_extension(Extensions::UNWRAP_VARIANT_NEWTYPES)
        .from_str(content)
        .map_err(|e| {
            CuError::from(format!(
                "Failed to parse instance override file: Error: {} at position {}",
                e.code, e.span
            ))
        })
}

#[cfg(feature = "std")]
fn merge_component_config(target: &mut Option<ComponentConfig>, value: &ComponentConfig) {
    if let Some(existing) = target {
        existing.merge_from(value);
    } else {
        *target = Some(value.clone());
    }
}

#[cfg(feature = "std")]
fn apply_task_config_override_to_graph(
    graph: &mut CuGraph,
    task_id: &str,
    value: &ComponentConfig,
) -> usize {
    let mut matches = 0usize;
    let node_indices: Vec<_> = graph.0.node_indices().collect();
    for node_index in node_indices {
        let node = &mut graph.0[node_index];
        if node.get_flavor() == Flavor::Task && node.id == task_id {
            merge_component_config(&mut node.config, value);
            matches += 1;
        }
    }
    matches
}

#[cfg(feature = "std")]
fn apply_bridge_node_config_override_to_graph(
    graph: &mut CuGraph,
    bridge_id: &str,
    value: &ComponentConfig,
) {
    let node_indices: Vec<_> = graph.0.node_indices().collect();
    for node_index in node_indices {
        let node = &mut graph.0[node_index];
        if node.get_flavor() == Flavor::Bridge && node.id == bridge_id {
            merge_component_config(&mut node.config, value);
        }
    }
}

#[cfg(feature = "std")]
fn parse_instance_override_target(path: &str) -> CuResult<(InstanceConfigTargetKind, String)> {
    let mut parts = path.split('/');
    let scope = parts.next().unwrap_or_default();
    let id = parts.next().unwrap_or_default();
    let leaf = parts.next().unwrap_or_default();

    if scope.is_empty() || id.is_empty() || leaf.is_empty() || parts.next().is_some() {
        return Err(CuError::from(format!(
            "Invalid instance override path '{}'. Expected 'tasks/<id>/config', 'resources/<id>/config', or 'bridges/<id>/config'.",
            path
        )));
    }

    if leaf != "config" {
        return Err(CuError::from(format!(
            "Invalid instance override path '{}'. Only the '/config' leaf is supported.",
            path
        )));
    }

    let kind = match scope {
        "tasks" => InstanceConfigTargetKind::Task,
        "resources" => InstanceConfigTargetKind::Resource,
        "bridges" => InstanceConfigTargetKind::Bridge,
        _ => {
            return Err(CuError::from(format!(
                "Invalid instance override path '{}'. Supported roots are 'tasks', 'resources', and 'bridges'.",
                path
            )));
        }
    };

    Ok((kind, id.to_string()))
}

#[cfg(feature = "std")]
fn apply_instance_config_set_operation(
    config: &mut CuConfig,
    operation: &InstanceConfigSetOperation,
) -> CuResult<()> {
    let (target_kind, target_id) = parse_instance_override_target(&operation.path)?;

    match target_kind {
        InstanceConfigTargetKind::Task => {
            let matches = match &mut config.graphs {
                ConfigGraphs::Simple(graph) => {
                    apply_task_config_override_to_graph(graph, &target_id, &operation.value)
                }
                ConfigGraphs::Missions(graphs) => graphs
                    .values_mut()
                    .map(|graph| {
                        apply_task_config_override_to_graph(graph, &target_id, &operation.value)
                    })
                    .sum(),
            };

            if matches == 0 {
                return Err(CuError::from(format!(
                    "Instance override path '{}' targets unknown task '{}'.",
                    operation.path, target_id
                )));
            }
        }
        InstanceConfigTargetKind::Resource => {
            let mut matches = 0usize;
            for resource in &mut config.resources {
                if resource.id == target_id {
                    merge_component_config(&mut resource.config, &operation.value);
                    matches += 1;
                }
            }
            if matches == 0 {
                return Err(CuError::from(format!(
                    "Instance override path '{}' targets unknown resource '{}'.",
                    operation.path, target_id
                )));
            }
        }
        InstanceConfigTargetKind::Bridge => {
            let mut matches = 0usize;
            for bridge in &mut config.bridges {
                if bridge.id == target_id {
                    merge_component_config(&mut bridge.config, &operation.value);
                    matches += 1;
                }
            }
            if matches == 0 {
                return Err(CuError::from(format!(
                    "Instance override path '{}' targets unknown bridge '{}'.",
                    operation.path, target_id
                )));
            }

            match &mut config.graphs {
                ConfigGraphs::Simple(graph) => {
                    apply_bridge_node_config_override_to_graph(graph, &target_id, &operation.value);
                }
                ConfigGraphs::Missions(graphs) => {
                    for graph in graphs.values_mut() {
                        apply_bridge_node_config_override_to_graph(
                            graph,
                            &target_id,
                            &operation.value,
                        );
                    }
                }
            }
        }
    }

    Ok(())
}

#[cfg(feature = "std")]
fn apply_instance_overrides(
    config: &mut CuConfig,
    overrides: &InstanceConfigOverridesRepresentation,
) -> CuResult<()> {
    for operation in &overrides.set {
        apply_instance_config_set_operation(config, operation)?;
    }
    Ok(())
}

#[cfg(feature = "std")]
fn apply_instance_overrides_from_file(
    config: &mut CuConfig,
    override_path: &std::path::Path,
) -> CuResult<()> {
    let override_content = read_to_string(override_path).map_err(|e| {
        CuError::from(format!(
            "Failed to read instance override file '{}'",
            override_path.display()
        ))
        .add_cause(e.to_string().as_str())
    })?;
    let overrides = parse_instance_config_overrides_string(&override_content).map_err(|e| {
        CuError::from(format!(
            "Failed to parse instance override file '{}': {e}",
            override_path.display()
        ))
    })?;
    apply_instance_overrides(config, &overrides)
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn parse_multi_config_string(content: &str) -> CuResult<MultiCopperConfigRepresentation> {
    Options::default()
        .with_default_extension(Extensions::IMPLICIT_SOME)
        .with_default_extension(Extensions::UNWRAP_NEWTYPES)
        .with_default_extension(Extensions::UNWRAP_VARIANT_NEWTYPES)
        .from_str(content)
        .map_err(|e| {
            CuError::from(format!(
                "Failed to parse multi-Copper configuration: Error: {} at position {}",
                e.code, e.span
            ))
        })
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn resolve_relative_config_path(base_path: Option<&str>, referenced_path: &str) -> String {
    if referenced_path.starts_with('/') || base_path.is_none() {
        return referenced_path.to_string();
    }

    let current_dir = std::path::Path::new(base_path.expect("checked above"))
        .parent()
        .unwrap_or_else(|| std::path::Path::new(""))
        .to_path_buf();
    current_dir
        .join(referenced_path)
        .to_string_lossy()
        .to_string()
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn parse_multi_endpoint(endpoint: &str) -> CuResult<MultiCopperEndpoint> {
    let mut parts = endpoint.split('/');
    let subsystem_id = parts.next().unwrap_or_default();
    let bridge_id = parts.next().unwrap_or_default();
    let channel_id = parts.next().unwrap_or_default();

    if subsystem_id.is_empty()
        || bridge_id.is_empty()
        || channel_id.is_empty()
        || parts.next().is_some()
    {
        return Err(CuError::from(format!(
            "Invalid multi-Copper endpoint '{endpoint}'. Expected 'subsystem/bridge/channel'."
        )));
    }

    Ok(MultiCopperEndpoint {
        subsystem_id: subsystem_id.to_string(),
        bridge_id: bridge_id.to_string(),
        channel_id: channel_id.to_string(),
    })
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn multi_channel_key(bridge_id: &str, channel_id: &str) -> String {
    format!("{bridge_id}/{channel_id}")
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn register_multi_channel_msg(
    contracts: &mut HashMap<String, MultiCopperChannelContract>,
    bridge_id: &str,
    channel_id: &str,
    expected_direction: MultiCopperChannelDirection,
    msg: &str,
) -> CuResult<()> {
    let key = multi_channel_key(bridge_id, channel_id);
    let contract = contracts.get_mut(&key).ok_or_else(|| {
        CuError::from(format!(
            "Bridge channel '{bridge_id}/{channel_id}' is referenced by the graph but not declared in the bridge config."
        ))
    })?;

    if contract.direction != expected_direction {
        let expected = match expected_direction {
            MultiCopperChannelDirection::Rx => "Rx",
            MultiCopperChannelDirection::Tx => "Tx",
        };
        return Err(CuError::from(format!(
            "Bridge channel '{bridge_id}/{channel_id}' is used as {expected} in the graph but declared with the opposite direction."
        )));
    }

    match &contract.msg {
        Some(existing) if existing != msg => Err(CuError::from(format!(
            "Bridge channel '{bridge_id}/{channel_id}' carries inconsistent message types '{existing}' and '{msg}'."
        ))),
        Some(_) => Ok(()),
        None => {
            contract.msg = Some(msg.to_string());
            Ok(())
        }
    }
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn build_multi_bridge_channel_contracts(
    config: &CuConfig,
) -> CuResult<HashMap<String, MultiCopperChannelContract>> {
    let graph = config
        .graphs
        .get_graph(Some(DEFAULT_MISSION_ID))
        .map_err(|e| {
            CuError::from(format!(
                "Multi-Copper subsystem configs with missions must define a '{DEFAULT_MISSION_ID}' mission: {e}"
            ))
        })?;

    let mut contracts = HashMap::new();
    for bridge in &config.bridges {
        for channel in &bridge.channels {
            let (channel_id, direction) = match channel {
                BridgeChannelConfigRepresentation::Rx { id, .. } => {
                    (id.as_str(), MultiCopperChannelDirection::Rx)
                }
                BridgeChannelConfigRepresentation::Tx { id, .. } => {
                    (id.as_str(), MultiCopperChannelDirection::Tx)
                }
            };

            let key = multi_channel_key(&bridge.id, channel_id);
            if contracts.contains_key(&key) {
                return Err(CuError::from(format!(
                    "Duplicate bridge channel declaration for '{key}'."
                )));
            }

            contracts.insert(
                key,
                MultiCopperChannelContract {
                    bridge_type: bridge.type_.clone(),
                    direction,
                    msg: None,
                },
            );
        }
    }

    for edge in graph.edges() {
        if let Some(channel_id) = &edge.src_channel {
            register_multi_channel_msg(
                &mut contracts,
                &edge.src,
                channel_id,
                MultiCopperChannelDirection::Rx,
                &edge.msg,
            )?;
        }
        if let Some(channel_id) = &edge.dst_channel {
            register_multi_channel_msg(
                &mut contracts,
                &edge.dst,
                channel_id,
                MultiCopperChannelDirection::Tx,
                &edge.msg,
            )?;
        }
    }

    Ok(contracts)
}

#[cfg(feature = "std")]
#[allow(dead_code)]
fn validate_multi_config_representation(
    representation: MultiCopperConfigRepresentation,
    file_path: Option<&str>,
    active_features: &[&str],
) -> CuResult<MultiCopperConfig> {
    if representation
        .instance_overrides_root
        .as_ref()
        .is_some_and(|root| root.trim().is_empty())
    {
        return Err(CuError::from(
            "Multi-Copper instance_overrides_root must not be empty.",
        ));
    }

    if representation.subsystems.is_empty() {
        return Err(CuError::from(
            "Multi-Copper config must declare at least one subsystem.",
        ));
    }
    if representation.subsystems.len() > usize::from(u16::MAX) + 1 {
        return Err(CuError::from(
            "Multi-Copper config supports at most 65536 distinct subsystem ids.",
        ));
    }

    let mut seen_subsystems = std::collections::HashSet::new();
    for subsystem in &representation.subsystems {
        if subsystem.id.trim().is_empty() {
            return Err(CuError::from(
                "Multi-Copper subsystem ids must not be empty.",
            ));
        }
        if !seen_subsystems.insert(subsystem.id.clone()) {
            return Err(CuError::from(format!(
                "Duplicate multi-Copper subsystem id '{}'.",
                subsystem.id
            )));
        }
    }

    let mut sorted_ids: Vec<_> = representation
        .subsystems
        .iter()
        .map(|subsystem| subsystem.id.clone())
        .collect();
    sorted_ids.sort();
    let subsystem_code_map: HashMap<_, _> = sorted_ids
        .into_iter()
        .enumerate()
        .map(|(idx, id)| {
            (
                id,
                u16::try_from(idx).expect("subsystem count was validated against u16 range"),
            )
        })
        .collect();

    let mut subsystem_contracts: HashMap<String, HashMap<String, MultiCopperChannelContract>> =
        HashMap::new();
    let mut subsystems = Vec::with_capacity(representation.subsystems.len());

    for subsystem in representation.subsystems {
        let resolved_config_path = resolve_relative_config_path(file_path, &subsystem.config);
        let config = read_configuration_with_features(&resolved_config_path, active_features)
            .map_err(|e| {
                CuError::from(format!(
                    "Failed to read subsystem '{}' from '{}': {e}",
                    subsystem.id, resolved_config_path
                ))
            })?;
        let contracts = build_multi_bridge_channel_contracts(&config).map_err(|e| {
            CuError::from(format!(
                "Invalid subsystem '{}' for multi-Copper validation: {e}",
                subsystem.id
            ))
        })?;
        subsystem_contracts.insert(subsystem.id.clone(), contracts);
        subsystems.push(MultiCopperSubsystem {
            subsystem_code: *subsystem_code_map
                .get(&subsystem.id)
                .expect("subsystem code map must contain every subsystem"),
            id: subsystem.id,
            config_path: resolved_config_path,
            config,
        });
    }

    let mut interconnects = Vec::with_capacity(representation.interconnects.len());
    for interconnect in representation.interconnects {
        if interconnect
            .when
            .as_ref()
            .is_some_and(|predicate| !predicate.evaluate(active_features))
        {
            continue;
        }

        let from = parse_multi_endpoint(&interconnect.from).map_err(|e| {
            CuError::from(format!(
                "Invalid multi-Copper interconnect source '{}': {e}",
                interconnect.from
            ))
        })?;
        let to = parse_multi_endpoint(&interconnect.to).map_err(|e| {
            CuError::from(format!(
                "Invalid multi-Copper interconnect destination '{}': {e}",
                interconnect.to
            ))
        })?;

        let from_contracts = subsystem_contracts.get(&from.subsystem_id).ok_or_else(|| {
            CuError::from(format!(
                "Interconnect source '{}' references unknown subsystem '{}'.",
                from, from.subsystem_id
            ))
        })?;
        let to_contracts = subsystem_contracts.get(&to.subsystem_id).ok_or_else(|| {
            CuError::from(format!(
                "Interconnect destination '{}' references unknown subsystem '{}'.",
                to, to.subsystem_id
            ))
        })?;

        let from_contract = from_contracts
            .get(&multi_channel_key(&from.bridge_id, &from.channel_id))
            .ok_or_else(|| {
                CuError::from(format!(
                    "Interconnect source '{}' references unknown bridge channel.",
                    from
                ))
            })?;
        let to_contract = to_contracts
            .get(&multi_channel_key(&to.bridge_id, &to.channel_id))
            .ok_or_else(|| {
                CuError::from(format!(
                    "Interconnect destination '{}' references unknown bridge channel.",
                    to
                ))
            })?;

        if from_contract.direction != MultiCopperChannelDirection::Tx {
            return Err(CuError::from(format!(
                "Interconnect source '{}' must reference a Tx bridge channel.",
                from
            )));
        }
        if to_contract.direction != MultiCopperChannelDirection::Rx {
            return Err(CuError::from(format!(
                "Interconnect destination '{}' must reference an Rx bridge channel.",
                to
            )));
        }

        if from_contract.bridge_type != to_contract.bridge_type {
            return Err(CuError::from(format!(
                "Interconnect '{}' -> '{}' mixes incompatible bridge types '{}' and '{}'.",
                from, to, from_contract.bridge_type, to_contract.bridge_type
            )));
        }

        let from_msg = from_contract.msg.as_ref().ok_or_else(|| {
            CuError::from(format!(
                "Interconnect source '{}' is not wired inside subsystem '{}', so its message type cannot be inferred.",
                from, from.subsystem_id
            ))
        })?;
        let to_msg = to_contract.msg.as_ref().ok_or_else(|| {
            CuError::from(format!(
                "Interconnect destination '{}' is not wired inside subsystem '{}', so its message type cannot be inferred.",
                to, to.subsystem_id
            ))
        })?;

        if from_msg != to_msg {
            return Err(CuError::from(format!(
                "Interconnect '{}' -> '{}' connects incompatible message types '{}' and '{}'.",
                from, to, from_msg, to_msg
            )));
        }
        if interconnect.msg != *from_msg {
            return Err(CuError::from(format!(
                "Interconnect '{}' -> '{}' declares message type '{}' but subsystem graphs require '{}'.",
                from, to, interconnect.msg, from_msg
            )));
        }

        interconnects.push(MultiCopperInterconnect {
            from,
            to,
            msg: interconnect.msg,
            bridge_type: from_contract.bridge_type.clone(),
        });
    }

    let instance_overrides_root = representation
        .instance_overrides_root
        .as_ref()
        .map(|root| resolve_relative_config_path(file_path, root));

    Ok(MultiCopperConfig {
        subsystems,
        interconnects,
        instance_overrides_root,
    })
}

/// Read a copper configuration from a file.
#[cfg(feature = "std")]
pub fn read_configuration(config_filename: &str) -> CuResult<CuConfig> {
    read_configuration_with_features(config_filename, &[])
}

/// Read a Copper configuration using the supplied compile-time Cargo features.
#[cfg(feature = "std")]
pub fn read_configuration_with_features(
    config_filename: &str,
    active_features: &[&str],
) -> CuResult<CuConfig> {
    let config_content = read_configuration_content(config_filename)?;
    read_configuration_str_with_features(config_content, Some(config_filename), active_features)
}

#[cfg(feature = "std")]
fn read_configuration_content(config_filename: &str) -> CuResult<String> {
    read_to_string(config_filename).map_err(|e| {
        CuError::from(format!(
            "Failed to read configuration file: {:?}",
            config_filename
        ))
        .add_cause(e.to_string().as_str())
    })
}

/// Read a copper configuration from a String.
/// Parse a RON string into a CuConfigRepresentation, using the standard options.
/// Returns an error if the parsing fails.
fn parse_config_string(content: &str) -> CuResult<CuConfigRepresentation> {
    Options::default()
        .with_default_extension(Extensions::IMPLICIT_SOME)
        .with_default_extension(Extensions::UNWRAP_NEWTYPES)
        .with_default_extension(Extensions::UNWRAP_VARIANT_NEWTYPES)
        .from_str(content)
        .map_err(|e| {
            CuError::from(format!(
                "Failed to parse configuration: Error: {} at position {}",
                e.code, e.span
            ))
        })
}

/// Convert a CuConfigRepresentation to a CuConfig.
/// Uses the deserialize_impl method and validates the logging configuration.
fn config_representation_to_config(representation: CuConfigRepresentation) -> CuResult<CuConfig> {
    #[allow(unused_mut)]
    let mut cuconfig = CuConfig::deserialize_impl(representation)
        .map_err(|e| CuError::from(format!("Error deserializing configuration: {e}")))?;

    #[cfg(feature = "std")]
    cuconfig.ensure_default_background_pool();

    cuconfig.validate_logging_config()?;
    cuconfig.validate_runtime_config()?;
    cuconfig.validate_anytime_configs()?;
    cuconfig.validate_constants()?;
    cuconfig.validate_log_streaming_config()?;

    Ok(cuconfig)
}

#[allow(unused_variables)]
fn resolve_configuration_representation(
    config_content: &str,
    file_path: Option<&str>,
    active_features: &[&str],
) -> CuResult<CuConfigRepresentation> {
    // Parse the configuration string
    let representation = parse_config_string(config_content)?;

    // Process includes and generate a merged configuration if a file path is provided
    // includes are only available with std.
    #[cfg(feature = "std")]
    let representation = if let Some(path) = file_path {
        process_includes(path, representation, &mut Vec::new(), active_features)?
    } else {
        representation
    };

    Ok(representation)
}

/// Read a Copper configuration and return the include-expanded RON used by proc-macro bundling.
///
/// The RON is serialized from the ordered source representation before it is lowered into
/// mission graph hash maps. This keeps task ordering aligned with generated runtime code.
#[cfg(feature = "std")]
#[doc(hidden)]
#[allow(dead_code)]
pub fn read_configuration_with_resolved_ron(config_filename: &str) -> CuResult<(CuConfig, String)> {
    read_configuration_with_resolved_ron_and_features(config_filename, &[])
}

/// Read and expand a Copper configuration using the supplied compile-time Cargo features.
#[cfg(feature = "std")]
#[doc(hidden)]
pub fn read_configuration_with_resolved_ron_and_features(
    config_filename: &str,
    active_features: &[&str],
) -> CuResult<(CuConfig, String)> {
    let config_content = read_configuration_content(config_filename)?;
    let representation = resolve_configuration_representation(
        &config_content,
        Some(config_filename),
        active_features,
    )?;
    let resolved_ron = CuConfig::get_options()
        .to_string_pretty(&representation, ron::ser::PrettyConfig::default())
        .map_err(|e| CuError::from(format!("Error serializing configuration: {e}")))?;
    let config = config_representation_to_config(representation)?;
    Ok((config, resolved_ron))
}

#[allow(dead_code)]
pub fn read_configuration_str(
    config_content: String,
    file_path: Option<&str>,
) -> CuResult<CuConfig> {
    read_configuration_str_with_features(config_content, file_path, &[])
}

/// Read a Copper configuration string using the supplied compile-time Cargo features.
pub fn read_configuration_str_with_features(
    config_content: String,
    file_path: Option<&str>,
    active_features: &[&str],
) -> CuResult<CuConfig> {
    let representation =
        resolve_configuration_representation(&config_content, file_path, active_features)?;

    // Convert the representation to a CuConfig and validate
    config_representation_to_config(representation)
}

/// Read a strict multi-Copper umbrella configuration from a file.
#[cfg(feature = "std")]
#[allow(dead_code)]
pub fn read_multi_configuration(config_filename: &str) -> CuResult<MultiCopperConfig> {
    read_multi_configuration_with_features(config_filename, &[])
}

/// Read a multi-Copper configuration using the supplied compile-time Cargo features.
#[cfg(feature = "std")]
#[allow(dead_code)]
pub fn read_multi_configuration_with_features(
    config_filename: &str,
    active_features: &[&str],
) -> CuResult<MultiCopperConfig> {
    let config_content = read_to_string(config_filename).map_err(|e| {
        CuError::from(format!(
            "Failed to read multi-Copper configuration file: {:?}",
            config_filename
        ))
        .add_cause(e.to_string().as_str())
    })?;
    read_multi_configuration_str_with_features(
        config_content,
        Some(config_filename),
        active_features,
    )
}

/// Read a strict multi-Copper umbrella configuration from a string.
#[cfg(feature = "std")]
#[allow(dead_code)]
pub fn read_multi_configuration_str(
    config_content: String,
    file_path: Option<&str>,
) -> CuResult<MultiCopperConfig> {
    read_multi_configuration_str_with_features(config_content, file_path, &[])
}

/// Read a multi-Copper configuration string using the supplied compile-time Cargo features.
#[cfg(feature = "std")]
#[allow(dead_code)]
pub fn read_multi_configuration_str_with_features(
    config_content: String,
    file_path: Option<&str>,
    active_features: &[&str],
) -> CuResult<MultiCopperConfig> {
    let representation = parse_multi_config_string(&config_content)?;
    validate_multi_config_representation(representation, file_path, active_features)
}

// tests
#[cfg(test)]
mod tests {
    use super::*;
    #[cfg(not(feature = "std"))]
    use alloc::vec;
    use serde::Deserialize;
    #[cfg(feature = "std")]
    use std::path::{Path, PathBuf};

    #[test]
    fn test_plain_serialize() {
        let mut config = CuConfig::default();
        let graph = config.get_graph_mut(None).unwrap();
        let n1 = graph
            .add_node(Node::new("test1", "package::Plugin1"))
            .unwrap();
        let n2 = graph
            .add_node(Node::new("test2", "package::Plugin2"))
            .unwrap();
        graph.connect(n1, n2, "msgpkg::MsgType").unwrap();
        let serialized = config.serialize_ron().unwrap();
        let deserialized = CuConfig::deserialize_ron(&serialized).unwrap();
        let graph = config.graphs.get_graph(None).unwrap();
        let deserialized_graph = deserialized.graphs.get_graph(None).unwrap();
        assert_eq!(graph.node_count(), deserialized_graph.node_count());
        assert_eq!(graph.edge_count(), deserialized_graph.edge_count());
    }

    #[test]
    fn test_planner_config_defaults_and_round_trips() {
        // The default has no planner section and none is serialized.
        let mut config = CuConfig::default();
        config
            .get_graph_mut(None)
            .unwrap()
            .add_node(Node::new("a", "demo::A"))
            .unwrap();
        assert!(!config.serialize_ron().unwrap().contains("planner"));
        assert!(config.planner_config().is_none());

        // A planner selection round-trips, including baked resolved orders.
        let txt = r#"( tasks: [], cnx: [],
            runtime: ( planner: ( type: "cu29::planner::Pinned", config: { "order": ["a", "b"] } ) ) )"#;
        let mut config = CuConfig::deserialize_ron(txt).unwrap();
        let planner = config.planner_config().unwrap();
        assert_eq!(planner.get_type(), "cu29::planner::Pinned");
        let order: Vec<String> = planner
            .get_config()
            .unwrap()
            .get_value("order")
            .unwrap()
            .unwrap();
        assert_eq!(order, ["a", "b"]);

        config.set_planner_resolved_orders(
            "cu29::planner::Pinned",
            [("default".to_string(), vec!["task:a".to_string()])],
        );
        let reparsed = CuConfig::deserialize_ron(&config.serialize_ron().unwrap()).unwrap();
        assert_eq!(
            reparsed.planner_resolved_order("default").unwrap(),
            ["task:a".to_string()]
        );

        // The stamp creates the planner section when the loaded RON lacks one.
        let mut bare = CuConfig::default();
        bare.set_planner_resolved_orders(
            "acme::Planner",
            [("default".to_string(), vec!["task:a".to_string()])],
        );
        assert_eq!(bare.planner_config().unwrap().get_type(), "acme::Planner");
        assert_eq!(
            bare.planner_resolved_order("default").unwrap(),
            ["task:a".to_string()]
        );
    }

    #[test]
    fn test_serialize_with_params() {
        let mut config = CuConfig::default();
        let graph = config.get_graph_mut(None).unwrap();
        let mut camera = Node::new("copper-camera", "camerapkg::Camera");
        camera.set_param::<Value>("resolution-height", 1080.into());
        graph.add_node(camera).unwrap();
        let serialized = config.serialize_ron().unwrap();
        let config = CuConfig::deserialize_ron(&serialized).unwrap();
        let deserialized = config.get_graph(None).unwrap();
        let resolution = deserialized
            .get_node(0)
            .unwrap()
            .get_param::<i32>("resolution-height")
            .expect("resolution-height lookup failed");
        assert_eq!(resolution, Some(1080));
    }

    #[derive(Debug, Deserialize, PartialEq)]
    struct InnerSettings {
        threshold: u32,
        flags: Option<bool>,
    }

    #[derive(Debug, Deserialize, PartialEq)]
    struct SettingsConfig {
        gain: f32,
        matrix: [[f32; 3]; 3],
        inner: InnerSettings,
        tags: Vec<String>,
    }

    #[test]
    fn test_component_config_get_value_structured() {
        let txt = r#"
            (
                tasks: [
                    (
                        id: "task",
                        type: "pkg::Task",
                        config: {
                            "settings": {
                                "gain": 1.5,
                                "matrix": [
                                    [1.0, 0.0, 0.0],
                                    [0.0, 1.0, 0.0],
                                    [0.0, 0.0, 1.0],
                                ],
                                "inner": { "threshold": 42, "flags": Some(true) },
                                "tags": ["alpha", "beta"],
                            },
                        },
                    ),
                ],
                cnx: [],
            )
        "#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.graphs.get_graph(None).unwrap();
        let node = graph.get_node(0).unwrap();
        let component = node.get_instance_config().expect("missing config");
        let settings = component
            .get_value::<SettingsConfig>("settings")
            .expect("settings lookup failed")
            .expect("missing settings");
        let expected = SettingsConfig {
            gain: 1.5,
            matrix: [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
            inner: InnerSettings {
                threshold: 42,
                flags: Some(true),
            },
            tags: vec!["alpha".to_string(), "beta".to_string()],
        };
        assert_eq!(settings, expected);
    }

    #[test]
    fn test_component_config_get_value_scalar_compatibility() {
        let txt = r#"
            (
                tasks: [
                    (id: "task", type: "pkg::Task", config: { "scalar": 7 }),
                ],
                cnx: [],
            )
        "#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.graphs.get_graph(None).unwrap();
        let node = graph.get_node(0).unwrap();
        let component = node.get_instance_config().expect("missing config");
        let scalar = component
            .get::<u32>("scalar")
            .expect("scalar lookup failed");
        assert_eq!(scalar, Some(7));
    }

    #[test]
    fn test_component_config_get_value_mixed_usage() {
        let txt = r#"
            (
                tasks: [
                    (
                        id: "task",
                        type: "pkg::Task",
                        config: {
                            "scalar": 12,
                            "settings": {
                                "gain": 2.5,
                                "matrix": [
                                    [1.0, 2.0, 3.0],
                                    [4.0, 5.0, 6.0],
                                    [7.0, 8.0, 9.0],
                                ],
                                "inner": { "threshold": 7, "flags": None },
                                "tags": ["gamma"],
                            },
                        },
                    ),
                ],
                cnx: [],
            )
        "#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.graphs.get_graph(None).unwrap();
        let node = graph.get_node(0).unwrap();
        let component = node.get_instance_config().expect("missing config");
        let scalar = component
            .get::<u32>("scalar")
            .expect("scalar lookup failed");
        let settings = component
            .get_value::<SettingsConfig>("settings")
            .expect("settings lookup failed");
        assert_eq!(scalar, Some(12));
        assert!(settings.is_some());
    }

    #[test]
    fn test_component_config_get_value_error_includes_key() {
        let txt = r#"
            (
                tasks: [
                    (
                        id: "task",
                        type: "pkg::Task",
                        config: { "settings": { "gain": 1.0 } },
                    ),
                ],
                cnx: [],
            )
        "#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.graphs.get_graph(None).unwrap();
        let node = graph.get_node(0).unwrap();
        let component = node.get_instance_config().expect("missing config");
        let err = component
            .get_value::<u32>("settings")
            .expect_err("expected type mismatch");
        assert!(err.to_string().contains("settings"));
    }

    #[test]
    fn test_deserialization_error() {
        // Task needs to be an array, but provided tuple wrongfully
        let txt = r#"( tasks: (), cnx: [], monitors: [(type: "ExampleMonitor", )] ) "#;
        let err = CuConfig::deserialize_ron(txt).expect_err("expected deserialization error");
        assert!(
            err.to_string()
                .contains("Syntax Error in config: Expected opening `[` at position 1:9-1:10")
        );
    }

    #[test]
    fn test_compile_time_constant_defaults_and_normalization() {
        let config = read_configuration_str(
            r#"(
                constants: [
                    (id: "COUNT", storage: usize, value: 12),
                    (id: "COUNT", module: "diagnostics", storage: usize, value: 24),
                    (id: "LENGTH_DEFAULT", quantity: length, value: [0.18, 0.0, 0.31]),
                    (id: "LENGTH_EXPLICIT", quantity: length, unit: meter, storage: f32,
                        value: [0.18, 0.0, 0.31]),
                    (id: "LENGTH_MM", quantity: length, unit: millimeter,
                        value: [180.0, 0.0, 310.0]),
                    (id: "ANGLE_DEG", quantity: angle, unit: degree, value: 180.0),
                    (id: "MASS_DEFAULT", quantity: mass, value: 1.0),
                    (id: "TEMPERATURE_C", quantity: thermodynamic_temperature,
                        unit: degree_celsius, storage: f64, value: 20.0),
                    (id: "CONSTRUCTED", module: "geometry", type: "crate::ConstPair",
                        expression: "crate::ConstPair::new(crate::constants::COUNT)"),
                    (id: "CONSTRUCTED_COPY", module: "geometry", type: "crate::ConstPair",
                        expression: "crate::ConstPair::new(crate::constants::COUNT)"),
                    (id: "CONSTRUCTED_REWRITTEN", module: "geometry", type: "crate::ConstPair",
                        expression: "crate::ConstPair::new( crate::constants::COUNT )"),
                ],
                tasks: [],
                cnx: [],
            )"#
            .to_string(),
            None,
        )
        .unwrap();

        assert_eq!(config.constants[0].module_path(), "constants");
        assert_eq!(config.constants[0].qualified_id(), "constants::COUNT");
        assert_eq!(config.constants[0].storage(), ConstantStorage::Usize);
        assert_eq!(config.constants[1].module_path(), "diagnostics");
        assert_eq!(config.constants[1].qualified_id(), "diagnostics::COUNT");
        let (_, default_length) = config.constants[2].normalized_f32().unwrap();
        let (_, explicit_length) = config.constants[3].normalized_f32().unwrap();
        let (_, millimeters) = config.constants[4].normalized_f32().unwrap();
        assert_eq!(default_length[0].to_bits(), explicit_length[0].to_bits());
        assert_eq!(default_length[2].to_bits(), explicit_length[2].to_bits());
        assert_eq!(default_length, millimeters);
        assert_eq!(
            config.constants[2].semantic_fingerprint().unwrap(),
            config.constants[3].semantic_fingerprint().unwrap()
        );
        assert_eq!(
            config.constants[2].semantic_fingerprint().unwrap(),
            config.constants[4].semantic_fingerprint().unwrap()
        );

        let (_, angle) = config.constants[5].normalized_f32().unwrap();
        assert_eq!(angle[0].to_bits(), core::f32::consts::PI.to_bits());

        let mass = &config.constants[6];
        assert_eq!(mass.resolved_unit().unwrap().unwrap().name(), "kilogram");
        assert_eq!(mass.normalized_f32().unwrap().1, vec![1.0]);

        let temperature = config.constants[7].normalized_f64().unwrap().1[0];
        assert!((temperature - 293.15).abs() < f64::EPSILON * 4.0);

        assert_eq!(
            config.constants[8].expression_definition(),
            Some((
                "crate::ConstPair",
                "crate::ConstPair::new(crate::constants::COUNT)"
            ))
        );
        assert_eq!(
            config.constants[8].semantic_fingerprint().unwrap(),
            config.constants[9].semantic_fingerprint().unwrap()
        );
        assert_ne!(
            config.constants[8].semantic_fingerprint().unwrap(),
            config.constants[10].semantic_fingerprint().unwrap()
        );

        let serialized = config.serialize_ron().unwrap();
        let reparsed = CuConfig::deserialize_ron(&serialized).unwrap();
        assert_eq!(
            reparsed.constants[8].expression_definition(),
            config.constants[8].expression_definition()
        );
        assert_eq!(
            reparsed.constants[8].semantic_fingerprint().unwrap(),
            config.constants[8].semantic_fingerprint().unwrap()
        );
    }

    #[test]
    fn test_compile_time_constant_rejects_invalid_definition_shapes() {
        let cases = [
            (
                r#"(id: "BAD", type: "crate::Pair")"#,
                "declares 'type' without 'expression'",
            ),
            (
                r#"(id: "BAD", expression: "crate::Pair::new()")"#,
                "declares 'expression' without 'type'",
            ),
            (
                r#"(id: "BAD", value: 1, type: "u32", expression: "1")"#,
                "cannot combine numeric 'value' with 'type' or 'expression'",
            ),
            (
                r#"(id: "BAD", storage: f32, type: "u32", expression: "1")"#,
                "cannot combine 'type' and 'expression' with numeric 'storage', 'quantity', or 'unit'",
            ),
            (
                r#"(id: "BAD")"#,
                "must declare either numeric 'value' or both 'type' and 'expression'",
            ),
        ];

        for (constant, expected) in cases {
            let source = format!("(constants: [{constant}], tasks: [], cnx: [])");
            let error = read_configuration_str(source, None)
                .expect_err("invalid constant definition shape must fail");
            assert!(
                error.to_string().contains(expected),
                "unexpected error: {error}"
            );
        }
    }

    #[test]
    fn test_compile_time_constant_rejects_duplicate_qualified_id() {
        let error = read_configuration_str(
            r#"(
                constants: [
                    (id: "COUNT", module: "diagnostics", value: 1),
                    (id: "COUNT", module: "diagnostics", value: 2),
                ],
                tasks: [],
                cnx: [],
            )"#
            .to_string(),
            None,
        )
        .expect_err("duplicate qualified constant id must fail");
        assert!(
            error
                .to_string()
                .contains("Duplicate constant 'diagnostics::COUNT'")
        );
    }

    #[test]
    fn test_compile_time_constant_rejects_incompatible_unit() {
        let error = read_configuration_str(
            r#"(
                constants: [(id: "BAD", quantity: length, unit: degree, value: 1.0)],
                tasks: [],
                cnx: [],
            )"#
            .to_string(),
            None,
        )
        .expect_err("length in degrees must fail");
        assert!(
            error
                .to_string()
                .contains("unit 'degree' is not compatible with quantity 'length'")
        );
    }

    #[test]
    fn test_missions() {
        let txt = r#"( missions: [ (id: "data_collection"), (id: "autonomous")])"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.graphs.get_graph(Some("data_collection")).unwrap();
        assert!(graph.node_count() == 0);
        let graph = config.graphs.get_graph(Some("autonomous")).unwrap();
        assert!(graph.node_count() == 0);
    }

    #[test]
    fn test_monitor_plural_syntax() {
        let txt = r#"( tasks: [], cnx: [], monitors: [(type: "ExampleMonitor", )] ) "#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert_eq!(config.get_monitor_config().unwrap().type_, "ExampleMonitor");

        let txt = r#"( tasks: [], cnx: [], monitors: [(type: "ExampleMonitor", config: { "toto": 4, } )] ) "#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert_eq!(
            config
                .get_monitor_config()
                .unwrap()
                .config
                .as_ref()
                .unwrap()
                .0["toto"]
                .0,
            4u8.into()
        );
    }

    #[test]
    fn test_monitor_singular_syntax() {
        let txt = r#"( tasks: [], cnx: [], monitor: (type: "ExampleMonitor", config: { "toto": 4, } ) ) "#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert_eq!(config.get_monitor_configs().len(), 1);
        assert_eq!(config.get_monitor_config().unwrap().type_, "ExampleMonitor");
        assert_eq!(
            config
                .get_monitor_config()
                .unwrap()
                .config
                .as_ref()
                .unwrap()
                .0["toto"]
                .0,
            4u8.into()
        );
    }

    #[test]
    #[cfg(feature = "std")]
    fn test_render_topology_multi_input_ports() {
        let mut config = CuConfig::default();
        let graph = config.get_graph_mut(None).unwrap();
        let src1 = graph.add_node(Node::new("src1", "tasks::Source1")).unwrap();
        let src2 = graph.add_node(Node::new("src2", "tasks::Source2")).unwrap();
        let dst = graph.add_node(Node::new("dst", "tasks::Dst")).unwrap();
        graph.connect(src1, dst, "msg::A").unwrap();
        graph.connect(src2, dst, "msg::B").unwrap();

        let topology = build_render_topology(graph, &[]);
        let dst_node = topology
            .nodes
            .iter()
            .find(|node| node.id == "dst")
            .expect("missing dst node");
        assert_eq!(dst_node.inputs.len(), 2);

        let mut dst_ports: Vec<_> = topology
            .connections
            .iter()
            .filter(|cnx| cnx.dst == "dst")
            .map(|cnx| cnx.dst_port.as_deref().expect("missing dst port"))
            .collect();
        dst_ports.sort();
        assert_eq!(dst_ports, vec!["in.0", "in.1"]);
    }

    #[test]
    fn test_logging_parameters() {
        // Test with `enable_task_logging: false`
        let txt = r#"( tasks: [], cnx: [], logging: ( slab_size_mib: 1024, section_size_mib: 100, enable_task_logging: false ),) "#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert!(config.logging.is_some());
        let logging_config = config.logging.unwrap();
        assert_eq!(logging_config.slab_size_mib.unwrap(), 1024);
        assert_eq!(logging_config.section_size_mib.unwrap(), 100);
        assert!(!logging_config.enable_task_logging);

        // Test with `enable_task_logging` not provided
        let txt =
            r#"( tasks: [], cnx: [], logging: ( slab_size_mib: 1024, section_size_mib: 100, ),) "#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert!(config.logging.is_some());
        let logging_config = config.logging.unwrap();
        assert_eq!(logging_config.slab_size_mib.unwrap(), 1024);
        assert_eq!(logging_config.section_size_mib.unwrap(), 100);
        assert!(logging_config.enable_task_logging);
    }

    #[test]
    fn test_node_logging_handle_content_round_trips() {
        // RON enum variants use bare identifiers — same convention as `kind: source`.
        let txt = r#"(
            tasks: [
                (id: "cam", type: "pkg::Cam", kind: source, logging: (handle_content: touched_only)),
                (id: "noop", type: "pkg::Noop", kind: sink),
            ],
            cnx: [
                (src: "cam", dst: "noop", msg: "pkg::Frame"),
            ],
        )"#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let cam = config.find_task_node(None, "cam").unwrap();
        assert_eq!(cam.handle_content_policy(), HandleContent::TouchedOnly);

        // A node without an explicit `logging` block falls back to `All`.
        let noop = config.find_task_node(None, "noop").unwrap();
        assert_eq!(noop.handle_content_policy(), HandleContent::All);

        // Round-trip preserves the policy.
        let reserialized = config.serialize_ron().unwrap();
        let reparsed = CuConfig::deserialize_ron(&reserialized).unwrap();
        let cam2 = reparsed.find_task_node(None, "cam").unwrap();
        assert_eq!(cam2.handle_content_policy(), HandleContent::TouchedOnly);
    }

    #[test]
    fn test_node_logging_handle_content_all_variants_parse() {
        for (value, expected) in [
            ("all", HandleContent::All),
            ("touched_only", HandleContent::TouchedOnly),
            ("none", HandleContent::None),
        ] {
            let txt = format!(
                r#"(
                    tasks: [(id: "s", type: "pkg::T", kind: source, logging: (handle_content: {value}))],
                    cnx: [(src: "s", dst: "__nc__", msg: "pkg::M")],
                )"#
            );
            let config = CuConfig::deserialize_ron(&txt).unwrap();
            assert_eq!(
                config
                    .find_task_node(None, "s")
                    .unwrap()
                    .handle_content_policy(),
                expected,
                "policy mismatch for `{value}`"
            );
        }
    }

    #[test]
    fn test_bridge_parsing() {
        let txt = r#"
        (
            tasks: [
                (id: "dst", type: "tasks::Destination"),
                (id: "src", type: "tasks::Source"),
            ],
            bridges: [
                (
                    id: "radio",
                    type: "tasks::SerialBridge",
                    config: { "path": "/dev/ttyACM0", "baud": 921600 },
                    channels: [
                        Rx ( id: "status", route: "sys/status" ),
                        Tx ( id: "motor", route: "motor/cmd" ),
                    ],
                ),
            ],
            cnx: [
                (src: "radio/status", dst: "dst", msg: "mymsgs::Status"),
                (src: "src", dst: "radio/motor", msg: "mymsgs::MotorCmd"),
            ],
        )
        "#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert_eq!(config.bridges.len(), 1);
        let bridge = &config.bridges[0];
        assert_eq!(bridge.id, "radio");
        assert_eq!(bridge.channels.len(), 2);
        match &bridge.channels[0] {
            BridgeChannelConfigRepresentation::Rx { id, route, .. } => {
                assert_eq!(id, "status");
                assert_eq!(route.as_deref(), Some("sys/status"));
            }
            _ => panic!("expected Rx channel"),
        }
        match &bridge.channels[1] {
            BridgeChannelConfigRepresentation::Tx { id, route, .. } => {
                assert_eq!(id, "motor");
                assert_eq!(route.as_deref(), Some("motor/cmd"));
            }
            _ => panic!("expected Tx channel"),
        }
        let graph = config.graphs.get_graph(None).unwrap();
        let bridge_id = graph
            .get_node_id_by_name("radio")
            .expect("bridge node missing");
        let bridge_node = graph.get_node(bridge_id).unwrap();
        assert_eq!(bridge_node.get_flavor(), Flavor::Bridge);

        // Edges should retain channel metadata.
        let mut edges = Vec::new();
        for edge_idx in graph.0.edge_indices() {
            edges.push(graph.0[edge_idx].clone());
        }
        assert_eq!(edges.len(), 2);
        let status_edge = edges
            .iter()
            .find(|e| e.dst == "dst")
            .expect("status edge missing");
        assert_eq!(status_edge.src_channel.as_deref(), Some("status"));
        assert!(status_edge.dst_channel.is_none());
        let motor_edge = edges
            .iter()
            .find(|e| e.dst_channel.is_some())
            .expect("motor edge missing");
        assert_eq!(motor_edge.dst_channel.as_deref(), Some("motor"));
    }

    #[test]
    fn test_bridge_roundtrip() {
        let mut config = CuConfig::default();
        let mut bridge_config = ComponentConfig::default();
        bridge_config.set("port", "/dev/ttyACM0".to_string());
        config.bridges.push(BridgeConfig {
            id: "radio".to_string(),
            type_: "tasks::SerialBridge".to_string(),
            config: Some(bridge_config),
            resources: None,
            missions: None,
            run_in_sim: None,
            channels: vec![
                BridgeChannelConfigRepresentation::Rx {
                    id: "status".to_string(),
                    route: Some("sys/status".to_string()),
                    config: None,
                },
                BridgeChannelConfigRepresentation::Tx {
                    id: "motor".to_string(),
                    route: Some("motor/cmd".to_string()),
                    config: None,
                },
            ],
        });

        let serialized = config.serialize_ron().unwrap();
        assert!(
            serialized.contains("bridges"),
            "bridges section missing from serialized config"
        );
        let deserialized = CuConfig::deserialize_ron(&serialized).unwrap();
        assert_eq!(deserialized.bridges.len(), 1);
        let bridge = &deserialized.bridges[0];
        assert!(bridge.is_run_in_sim());
        assert_eq!(bridge.channels.len(), 2);
        assert!(matches!(
            bridge.channels[0],
            BridgeChannelConfigRepresentation::Rx { .. }
        ));
        assert!(matches!(
            bridge.channels[1],
            BridgeChannelConfigRepresentation::Tx { .. }
        ));
    }

    #[test]
    fn test_resource_parsing() {
        let txt = r#"
        (
            resources: [
                (
                    id: "fc",
                    provider: "copper_board_px4::Px4Bundle",
                    config: { "baud": 921600 },
                    missions: ["m1"],
                ),
                (
                    id: "misc",
                    provider: "cu29_runtime::StdClockBundle",
                ),
            ],
        )
        "#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert_eq!(config.resources.len(), 2);
        let fc = &config.resources[0];
        assert_eq!(fc.id, "fc");
        assert_eq!(fc.provider, "copper_board_px4::Px4Bundle");
        assert_eq!(fc.missions.as_deref(), Some(&["m1".to_string()][..]));
        let baud: u32 = fc
            .config
            .as_ref()
            .expect("missing config")
            .get::<u32>("baud")
            .expect("baud lookup failed")
            .expect("missing baud");
        assert_eq!(baud, 921_600);
        let misc = &config.resources[1];
        assert_eq!(misc.id, "misc");
        assert_eq!(misc.provider, "cu29_runtime::StdClockBundle");
        assert!(misc.config.is_none());
    }

    #[test]
    fn test_resource_roundtrip() {
        let mut config = CuConfig::default();
        let mut bundle_cfg = ComponentConfig::default();
        bundle_cfg.set("path", "/dev/ttyACM0".to_string());
        config.resources.push(ResourceBundleConfig {
            resources: None,
            id: "fc".to_string(),
            provider: "copper_board_px4::Px4Bundle".to_string(),
            config: Some(bundle_cfg),
            missions: Some(vec!["m1".to_string()]),
        });

        let serialized = config.serialize_ron().unwrap();
        let deserialized = CuConfig::deserialize_ron(&serialized).unwrap();
        assert_eq!(deserialized.resources.len(), 1);
        let res = &deserialized.resources[0];
        assert_eq!(res.id, "fc");
        assert_eq!(res.provider, "copper_board_px4::Px4Bundle");
        assert_eq!(res.missions.as_deref(), Some(&["m1".to_string()][..]));
        let path: String = res
            .config
            .as_ref()
            .expect("missing config")
            .get::<String>("path")
            .expect("path lookup failed")
            .expect("missing path");
        assert_eq!(path, "/dev/ttyACM0");
    }

    #[test]
    fn test_bridge_channel_config() {
        let txt = r#"
        (
            tasks: [],
            bridges: [
                (
                    id: "radio",
                    type: "tasks::SerialBridge",
                    channels: [
                        Rx ( id: "status", route: "sys/status", config: { "filter": "fast" } ),
                        Tx ( id: "imu", route: "telemetry/imu", config: { "rate": 100 } ),
                    ],
                ),
            ],
            cnx: [],
        )
        "#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let bridge = &config.bridges[0];
        match &bridge.channels[0] {
            BridgeChannelConfigRepresentation::Rx {
                config: Some(cfg), ..
            } => {
                let val = cfg
                    .get::<String>("filter")
                    .expect("filter lookup failed")
                    .expect("filter missing");
                assert_eq!(val, "fast");
            }
            _ => panic!("expected Rx channel with config"),
        }
        match &bridge.channels[1] {
            BridgeChannelConfigRepresentation::Tx {
                config: Some(cfg), ..
            } => {
                let rate = cfg
                    .get::<i32>("rate")
                    .expect("rate lookup failed")
                    .expect("rate missing");
                assert_eq!(rate, 100);
            }
            _ => panic!("expected Tx channel with config"),
        }
    }

    #[test]
    fn test_task_resources_roundtrip() {
        let txt = r#"
        (
            tasks: [
                (
                    id: "imu",
                    type: "tasks::ImuDriver",
                    resources: { "bus": "fc.spi_1", "irq": "fc.gpio_imu" },
                ),
            ],
            cnx: [],
        )
        "#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.graphs.get_graph(None).unwrap();
        let node = graph.get_node(0).expect("missing task node");
        let resources = node.get_resources().expect("missing resources map");
        assert_eq!(resources.get("bus").map(String::as_str), Some("fc.spi_1"));
        assert_eq!(
            resources.get("irq").map(String::as_str),
            Some("fc.gpio_imu")
        );

        let serialized = config.serialize_ron().unwrap();
        let deserialized = CuConfig::deserialize_ron(&serialized).unwrap();
        let graph = deserialized.graphs.get_graph(None).unwrap();
        let node = graph.get_node(0).expect("missing task node");
        let resources = node
            .get_resources()
            .expect("missing resources map after roundtrip");
        assert_eq!(resources.get("bus").map(String::as_str), Some("fc.spi_1"));
        assert_eq!(
            resources.get("irq").map(String::as_str),
            Some("fc.gpio_imu")
        );
    }

    #[test]
    fn test_bridge_resources_preserved() {
        let mut config = CuConfig::default();
        config.resources.push(ResourceBundleConfig {
            resources: None,
            id: "fc".to_string(),
            provider: "board::Bundle".to_string(),
            config: None,
            missions: None,
        });
        let bridge_resources = HashMap::from([("serial".to_string(), "fc.serial0".to_string())]);
        config.bridges.push(BridgeConfig {
            id: "radio".to_string(),
            type_: "tasks::SerialBridge".to_string(),
            config: None,
            resources: Some(bridge_resources),
            missions: None,
            run_in_sim: None,
            channels: vec![BridgeChannelConfigRepresentation::Tx {
                id: "uplink".to_string(),
                route: None,
                config: None,
            }],
        });

        let serialized = config.serialize_ron().unwrap();
        let deserialized = CuConfig::deserialize_ron(&serialized).unwrap();
        let graph = deserialized.graphs.get_graph(None).expect("missing graph");
        let bridge_id = graph
            .get_node_id_by_name("radio")
            .expect("bridge node missing");
        let node = graph.get_node(bridge_id).expect("missing bridge node");
        let resources = node
            .get_resources()
            .expect("bridge resources were not preserved");
        assert_eq!(
            resources.get("serial").map(String::as_str),
            Some("fc.serial0")
        );
    }

    #[test]
    fn test_demo_config_parses() {
        let txt = r#"(
    resources: [
        (
            id: "fc",
            provider: "crate::resources::RadioBundle",
        ),
    ],
    tasks: [
        (id: "thr", type: "tasks::ThrottleControl"),
        (id: "tele0", type: "tasks::TelemetrySink0"),
        (id: "tele1", type: "tasks::TelemetrySink1"),
        (id: "tele2", type: "tasks::TelemetrySink2"),
        (id: "tele3", type: "tasks::TelemetrySink3"),
    ],
    bridges: [
        (  id: "crsf",
           type: "cu_crsf::CrsfBridge<SerialResource, SerialPortError>",
           resources: { "serial": "fc.serial" },
           channels: [
                Rx ( id: "rc_rx" ),  // receiving RC Channels
                Tx ( id: "lq_tx" ),  // Sending LineQuality back
            ],
        ),
        (
            id: "bdshot",
            type: "cu_bdshot::RpBdshotBridge",
            channels: [
                Tx ( id: "esc0_tx" ),
                Tx ( id: "esc1_tx" ),
                Tx ( id: "esc2_tx" ),
                Tx ( id: "esc3_tx" ),
                Rx ( id: "esc0_rx" ),
                Rx ( id: "esc1_rx" ),
                Rx ( id: "esc2_rx" ),
                Rx ( id: "esc3_rx" ),
            ],
        ),
    ],
    cnx: [
        (src: "crsf/rc_rx", dst: "thr", msg: "cu_crsf::messages::RcChannelsPayload"),
        (src: "thr", dst: "bdshot/esc0_tx", msg: "cu_bdshot::EscCommand"),
        (src: "thr", dst: "bdshot/esc1_tx", msg: "cu_bdshot::EscCommand"),
        (src: "thr", dst: "bdshot/esc2_tx", msg: "cu_bdshot::EscCommand"),
        (src: "thr", dst: "bdshot/esc3_tx", msg: "cu_bdshot::EscCommand"),
        (src: "bdshot/esc0_rx", dst: "tele0", msg: "cu_bdshot::EscTelemetry"),
        (src: "bdshot/esc1_rx", dst: "tele1", msg: "cu_bdshot::EscTelemetry"),
        (src: "bdshot/esc2_rx", dst: "tele2", msg: "cu_bdshot::EscTelemetry"),
        (src: "bdshot/esc3_rx", dst: "tele3", msg: "cu_bdshot::EscTelemetry"),
    ],
)"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert_eq!(config.resources.len(), 1);
        assert_eq!(config.bridges.len(), 2);
    }

    #[test]
    fn test_bridge_tx_cannot_be_source() {
        let txt = r#"
        (
            tasks: [
                (id: "dst", type: "tasks::Destination"),
            ],
            bridges: [
                (
                    id: "radio",
                    type: "tasks::SerialBridge",
                    channels: [
                        Tx ( id: "motor", route: "motor/cmd" ),
                    ],
                ),
            ],
            cnx: [
                (src: "radio/motor", dst: "dst", msg: "mymsgs::MotorCmd"),
            ],
        )
        "#;

        let err = CuConfig::deserialize_ron(txt).expect_err("expected bridge source error");
        assert!(
            err.to_string()
                .contains("channel 'motor' is Tx and cannot act as a source")
        );
    }

    #[test]
    fn test_bridge_rx_cannot_be_destination() {
        let txt = r#"
        (
            tasks: [
                (id: "src", type: "tasks::Source"),
            ],
            bridges: [
                (
                    id: "radio",
                    type: "tasks::SerialBridge",
                    channels: [
                        Rx ( id: "status", route: "sys/status" ),
                    ],
                ),
            ],
            cnx: [
                (src: "src", dst: "radio/status", msg: "mymsgs::Status"),
            ],
        )
        "#;

        let err = CuConfig::deserialize_ron(txt).expect_err("expected bridge destination error");
        assert!(
            err.to_string()
                .contains("channel 'status' is Rx and cannot act as a destination")
        );
    }

    #[test]
    fn test_validate_logging_config() {
        // Test with valid logging configuration
        let txt =
            r#"( tasks: [], cnx: [], logging: ( slab_size_mib: 1024, section_size_mib: 100 ) )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert!(config.validate_logging_config().is_ok());

        // Test with invalid logging configuration
        let txt =
            r#"( tasks: [], cnx: [], logging: ( slab_size_mib: 100, section_size_mib: 1024 ) )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        assert!(config.validate_logging_config().is_err());
    }

    #[test]
    fn log_streaming_config_parses_and_round_trips_without_scheme_fields() {
        let txt = r#"
        (
            resources: [
                (
                    id: "telemetry_udp",
                    provider: "cu29_logstream_udp::CuUdpLogStreamResources",
                    config: {
                        "bind_addr": "0.0.0.0:0",
                        "remote_addr": "192.168.10.20:7447",
                        "send_buffer_bytes": 262144,
                        "ttl": 1,
                        "dscp": 46,
                    },
                ),
            ],
            log_streaming: (
                destinations: [
                    (
                        id: "ground",
                        transport: (
                            type: "cu29_logstream_udp::CuUdpLogStreamTx",
                            resource: "telemetry_udp.tx",
                        ),
                        link: (
                            mtu_bytes: 1200,
                            bitrate_bps: 1000000,
                            memory_budget_kib: 512,
                            max_latency_ms: 250,
                            burst_packets: 8,
                        ),
                        fec: (
                            continuous: (
                                field: Gf256,
                                window_symbols: 64,
                                repair_every_source_symbols: 4,
                                repair_density: Full,
                            ),
                            objects: (
                                max_object_bytes: 4194304,
                                repair_symbols_per_block: 8,
                            ),
                        ),
                        recovery_interval: 100,
                        max_record_bytes: 65536,
                    ),
                ],
            ),
        )
        "#;

        let config = read_configuration_str(txt.to_string(), None).unwrap();
        let destination = &config.log_streaming.as_ref().unwrap().destinations[0];
        assert_eq!(destination.id, "ground");
        assert_eq!(destination.transport.resource, "telemetry_udp.tx");
        assert_eq!(destination.fec.continuous.field, LogStreamRlcField::Gf256);
        assert_eq!(
            destination.fec.continuous.repair_density,
            LogStreamRepairDensity::Full
        );

        let serialized = config.serialize_ron().unwrap();
        let reparsed = read_configuration_str(serialized, None).unwrap();
        assert_eq!(reparsed.log_streaming, config.log_streaming);

        let feedback = r#"feedback: (
            transport: (type: "app::FeedbackRx", resource: "telemetry_udp.rx"),
            report_interval_ms: 500, timeout_ms: 2000,
            adaptation: (min_repair_every_source_symbols: 1, max_repair_every_source_symbols: 16),
        ), link:"#;
        let adaptive = txt.replace("link:", feedback);
        let parsed = read_configuration_str(adaptive.clone(), None).unwrap();
        assert!(
            parsed.log_streaming.as_ref().unwrap().destinations[0]
                .feedback
                .is_some()
        );
        let roundtrip = read_configuration_str(parsed.serialize_ron().unwrap(), None).unwrap();
        assert_eq!(roundtrip.log_streaming, parsed.log_streaming);
        for invalid in [
            adaptive.replace("report_interval_ms: 500", "report_interval_ms: 0"),
            adaptive.replace("timeout_ms: 2000", "timeout_ms: 500"),
            adaptive.replace(
                "min_repair_every_source_symbols: 1",
                "min_repair_every_source_symbols: 5",
            ),
            adaptive.replace(
                "max_repair_every_source_symbols: 16",
                "max_repair_every_source_symbols: 3",
            ),
            adaptive.replace("telemetry_udp.rx", "telemetry_udp.tx"),
            adaptive.replace("telemetry_udp.rx", "missing.rx"),
        ] {
            assert!(read_configuration_str(invalid, None).is_err());
        }
    }

    #[test]
    fn log_streaming_rejects_a_pluggable_fec_scheme() {
        let txt = r#"
        (
            resources: [(id: "network", provider: "app::Network")],
            log_streaming: (
                destinations: [(
                    id: "ground",
                    transport: (type: "app::Tx", resource: "network.tx"),
                    link: (
                        mtu_bytes: 1200,
                        bitrate_bps: 1000000,
                        memory_budget_kib: 512,
                        max_latency_ms: 250,
                        burst_packets: 8,
                    ),
                    fec: (
                        continuous: (
                            scheme: Rlc,
                            field: Gf256,
                            window_symbols: 64,
                            repair_every_source_symbols: 4,
                            repair_density: Full,
                        ),
                        objects: (
                            max_object_bytes: 4194304,
                            repair_symbols_per_block: 8,
                        ),
                    ),
                    recovery_interval: 100,
                    max_record_bytes: 65536,
                )],
            ),
        )
        "#;

        let error = read_configuration_str(txt.to_string(), None).unwrap_err();
        assert!(error.to_string().contains("scheme"), "{error}");
    }

    // this test makes sure the edge id is suitable to be used to sort the inputs of a task
    #[test]
    fn test_deserialization_edge_id_assignment() {
        // note here that the src1 task is added before src2 in the tasks array,
        // however, src1 connection is added AFTER src2 in the cnx array
        let txt = r#"(
            tasks: [(id: "src1", type: "a"), (id: "src2", type: "b"), (id: "sink", type: "c")],
            cnx: [(src: "src2", dst: "sink", msg: "msg1"), (src: "src1", dst: "sink", msg: "msg2")]
        )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.graphs.get_graph(None).unwrap();
        assert!(config.validate_logging_config().is_ok());

        // the node id depends on the order in which the tasks are added
        let src1_id = 0;
        assert_eq!(graph.get_node(src1_id).unwrap().id, "src1");
        let src2_id = 1;
        assert_eq!(graph.get_node(src2_id).unwrap().id, "src2");

        // the edge id depends on the order the connection is created
        // the src2 was added second in the tasks, but the connection was added first
        let src1_edge_id = *graph.get_src_edges(src1_id).unwrap().first().unwrap();
        assert_eq!(src1_edge_id, 1);
        let src2_edge_id = *graph.get_src_edges(src2_id).unwrap().first().unwrap();
        assert_eq!(src2_edge_id, 0);
    }

    #[test]
    fn test_simple_missions() {
        // A simple config that selection a source depending on the mission it is in.
        let txt = r#"(
                    missions: [ (id: "m1"),
                                (id: "m2"),
                                ],
                    tasks: [(id: "src1", type: "a", missions: ["m1"]),
                            (id: "src2", type: "b", missions: ["m2"]),
                            (id: "sink", type: "c")],

                    cnx: [
                            (src: "src1", dst: "sink", msg: "u32", missions: ["m1"]),
                            (src: "src2", dst: "sink", msg: "u32", missions: ["m2"]),
                         ],
              )
              "#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let m1_graph = config.graphs.get_graph(Some("m1")).unwrap();
        assert_eq!(m1_graph.edge_count(), 1);
        assert_eq!(m1_graph.node_count(), 2);
        let index = 0;
        let cnx = m1_graph.get_edge_weight(index).unwrap();

        assert_eq!(cnx.src, "src1");
        assert_eq!(cnx.dst, "sink");
        assert_eq!(cnx.msg, "u32");
        assert_eq!(cnx.missions, Some(vec!["m1".to_string()]));

        let m2_graph = config.graphs.get_graph(Some("m2")).unwrap();
        assert_eq!(m2_graph.edge_count(), 1);
        assert_eq!(m2_graph.node_count(), 2);
        let index = 0;
        let cnx = m2_graph.get_edge_weight(index).unwrap();
        assert_eq!(cnx.src, "src2");
        assert_eq!(cnx.dst, "sink");
        assert_eq!(cnx.msg, "u32");
        assert_eq!(cnx.missions, Some(vec!["m2".to_string()]));
    }
    #[test]
    fn test_mission_serde() {
        // A simple config that selection a source depending on the mission it is in.
        let txt = r#"(
                    missions: [ (id: "m1"),
                                (id: "m2"),
                                ],
                    tasks: [(id: "src1", type: "a", missions: ["m1"]),
                            (id: "src2", type: "b", missions: ["m2"]),
                            (id: "sink", type: "c")],

                    cnx: [
                            (src: "src1", dst: "sink", msg: "u32", missions: ["m1"]),
                            (src: "src2", dst: "sink", msg: "u32", missions: ["m2"]),
                         ],
              )
              "#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let serialized = config.serialize_ron().unwrap();
        let deserialized = CuConfig::deserialize_ron(&serialized).unwrap();
        let m1_graph = deserialized.graphs.get_graph(Some("m1")).unwrap();
        assert_eq!(m1_graph.edge_count(), 1);
        assert_eq!(m1_graph.node_count(), 2);
        let index = 0;
        let cnx = m1_graph.get_edge_weight(index).unwrap();
        assert_eq!(cnx.src, "src1");
        assert_eq!(cnx.dst, "sink");
        assert_eq!(cnx.msg, "u32");
        assert_eq!(cnx.missions, Some(vec!["m1".to_string()]));
    }

    #[test]
    fn test_mission_scoped_nc_connection_survives_serialize_roundtrip() {
        let txt = r#"(
            missions: [(id: "m1"), (id: "m2")],
            tasks: [
                (id: "src_m1", type: "a", missions: ["m1"]),
                (id: "src_m2", type: "b", missions: ["m2"]),
            ],
            cnx: [
                (src: "src_m1", dst: "__nc__", msg: "msg::A", missions: ["m1"]),
                (src: "src_m2", dst: "__nc__", msg: "msg::B", missions: ["m2"]),
            ]
        )"#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let serialized = config.serialize_ron().unwrap();
        let deserialized = CuConfig::deserialize_ron(&serialized).unwrap();

        let m1_graph = deserialized.graphs.get_graph(Some("m1")).unwrap();
        let src_m1_id = m1_graph.get_node_id_by_name("src_m1").unwrap();
        let src_m1 = m1_graph.get_node(src_m1_id).unwrap();
        assert_eq!(src_m1.nc_outputs(), &["msg::A".to_string()]);

        let m2_graph = deserialized.graphs.get_graph(Some("m2")).unwrap();
        let src_m2_id = m2_graph.get_node_id_by_name("src_m2").unwrap();
        let src_m2 = m2_graph.get_node(src_m2_id).unwrap();
        assert_eq!(src_m2.nc_outputs(), &["msg::B".to_string()]);
    }

    #[test]
    fn test_keyframe_interval() {
        // note here that the src1 task is added before src2 in the tasks array,
        // however, src1 connection is added AFTER src2 in the cnx array
        let txt = r#"(
            tasks: [(id: "src1", type: "a"), (id: "src2", type: "b"), (id: "sink", type: "c")],
            cnx: [(src: "src2", dst: "sink", msg: "msg1"), (src: "src1", dst: "sink", msg: "msg2")],
            logging: ( keyframe_interval: 314 )
        )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let logging_config = config.logging.unwrap();
        assert_eq!(logging_config.keyframe_interval.unwrap(), 314);
        assert!(logging_config.enable_keyframe_logging);
    }

    #[test]
    fn test_keyframe_logging_can_be_disabled_independently() {
        let txt = r#"(
            tasks: [],
            cnx: [],
            logging: (enable_task_logging: true, enable_keyframe_logging: false),
        )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let logging = config.logging.unwrap();
        assert!(logging.enable_task_logging);
        assert!(!logging.enable_keyframe_logging);
    }

    #[test]
    fn test_default_keyframe_interval() {
        // note here that the src1 task is added before src2 in the tasks array,
        // however, src1 connection is added AFTER src2 in the cnx array
        let txt = r#"(
            tasks: [(id: "src1", type: "a"), (id: "src2", type: "b"), (id: "sink", type: "c")],
            cnx: [(src: "src2", dst: "sink", msg: "msg1"), (src: "src1", dst: "sink", msg: "msg2")],
            logging: ( slab_size_mib: 200, section_size_mib: 1024, )
        )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let logging_config = config.logging.unwrap();
        assert_eq!(logging_config.keyframe_interval.unwrap(), 100);
    }

    #[test]
    fn test_task_kind_roundtrip_and_alias() {
        let txt = r#"(
            tasks: [
                (id: "src", type: "a", kind: source),
                (id: "regular", type: "b", kind: regular),
                (id: "sink", type: "c", kind: sink),
            ],
            cnx: [
                (src: "src", dst: "regular", msg: "msg::A"),
                (src: "regular", dst: "sink", msg: "msg::B"),
            ]
        )"#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.get_graph(None).unwrap();

        assert_eq!(
            graph
                .get_node(graph.get_node_id_by_name("src").unwrap())
                .unwrap()
                .get_declared_task_kind(),
            Some(TaskKind::Source)
        );
        assert_eq!(
            graph
                .get_node(graph.get_node_id_by_name("regular").unwrap())
                .unwrap()
                .get_declared_task_kind(),
            Some(TaskKind::Regular)
        );
        assert_eq!(
            graph
                .get_node(graph.get_node_id_by_name("sink").unwrap())
                .unwrap()
                .get_declared_task_kind(),
            Some(TaskKind::Sink)
        );

        let serialized = config.serialize_ron().unwrap();
        assert!(serialized.contains("kind: source"));
        assert!(serialized.contains("kind: task"));
        assert!(serialized.contains("kind: sink"));
    }

    #[test]
    fn test_resolve_task_kind_uses_nc_outputs_for_regular_tasks() {
        let txt = r#"(
            tasks: [
                (id: "src", type: "a"),
                (id: "regular", type: "b"),
            ],
            cnx: [
                (src: "src", dst: "regular", msg: "msg::A"),
                (src: "regular", dst: "__nc__", msg: "msg::B"),
            ]
        )"#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.get_graph(None).unwrap();
        let regular_id = graph.get_node_id_by_name("regular").unwrap();

        assert_eq!(
            resolve_task_kind_for_id(graph, regular_id).unwrap(),
            TaskKind::Regular
        );
    }

    #[test]
    fn test_resolve_task_kind_rejects_isolated_task_without_kind() {
        let txt = r#"(
            tasks: [
                (id: "lonely", type: "a"),
            ],
            cnx: []
        )"#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.get_graph(None).unwrap();
        let lonely_id = graph.get_node_id_by_name("lonely").unwrap();

        let err = resolve_task_kind_for_id(graph, lonely_id).expect_err("expected task kind error");
        assert!(
            err.to_string()
                .contains("cannot infer whether it is a source, task, or sink"),
            "unexpected error: {err}"
        );
    }

    #[test]
    fn test_resolve_explicit_source_kind_allows_missing_declared_outputs() {
        let txt = r#"(
            tasks: [
                (id: "src", type: "a", kind: source),
            ],
            cnx: []
        )"#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.get_graph(None).unwrap();
        let src_id = graph.get_node_id_by_name("src").unwrap();

        assert_eq!(
            resolve_task_kind_for_id(graph, src_id).unwrap(),
            TaskKind::Source
        );
    }

    #[test]
    fn test_resolve_explicit_regular_kind_allows_missing_declared_outputs() {
        let txt = r#"(
            tasks: [
                (id: "src", type: "a"),
                (id: "regular", type: "b", kind: task),
            ],
            cnx: [
                (src: "src", dst: "regular", msg: "msg::A"),
            ]
        )"#;

        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.get_graph(None).unwrap();
        let regular_id = graph.get_node_id_by_name("regular").unwrap();

        assert_eq!(
            resolve_task_kind_for_id(graph, regular_id).unwrap(),
            TaskKind::Regular
        );
    }

    #[test]
    fn test_runtime_rate_target_rejects_zero() {
        let txt = r#"(
            tasks: [(id: "src", type: "a"), (id: "sink", type: "b")],
            cnx: [(src: "src", dst: "sink", msg: "msg::A")],
            runtime: (rate_target_hz: 0)
        )"#;

        let err =
            read_configuration_str(txt.to_string(), None).expect_err("runtime config should fail");
        assert!(
            err.to_string()
                .contains("Runtime rate target cannot be zero"),
            "unexpected error: {err}"
        );
    }

    #[test]
    fn test_runtime_rate_target_rejects_above_nanosecond_resolution() {
        let txt = format!(
            r#"(
                tasks: [(id: "src", type: "a"), (id: "sink", type: "b")],
                cnx: [(src: "src", dst: "sink", msg: "msg::A")],
                runtime: (rate_target_hz: {})
            )"#,
            MAX_RATE_TARGET_HZ + 1
        );

        let err = read_configuration_str(txt, None).expect_err("runtime config should fail");
        assert!(
            err.to_string().contains("exceeds the supported maximum"),
            "unexpected error: {err}"
        );
    }

    /// Builds a src -> any -> sink config with the given `anytime:` policy body,
    /// extra node attributes (e.g. `, background: true`) and top-level extras
    /// (e.g. `runtime: (rate_target_hz: 100),`).
    fn anytime_config_txt(policy: &str, node_attrs: &str, top_level: &str) -> String {
        format!(
            r#"(
            tasks: [
                (id: "src", type: "a"),
                (id: "any", type: "b", anytime: ({policy}){node_attrs}),
                (id: "sink", type: "c"),
            ],
            cnx: [
                (src: "src", dst: "any", msg: "msg::A"),
                (src: "any", dst: "sink", msg: "msg::B"),
            ],
            {top_level}
        )"#
        )
    }

    fn expect_anytime_error(txt: String, expected: &str) {
        let err = read_configuration_str(txt, None).expect_err("anytime config should fail");
        assert!(
            err.to_string().contains(expected),
            "unexpected error: {err}"
        );
    }

    #[test]
    fn test_anytime_node_parses_and_exposes_policy() {
        let txt = anytime_config_txt(
            r#"
                time_budget_ms: 8.0,
                max_age_ms: 100.0,
                quality_target: 0.95,
                quality_floor: 0.30,
                max_refines: 64,
                max_stall: 4,
            "#,
            ", background: true",
            "",
        );
        let config = read_configuration_str(txt, None).unwrap();
        let graph = config.get_graph(None).unwrap();
        let node = graph
            .get_node(graph.get_node_id_by_name("any").unwrap())
            .unwrap();
        assert!(node.is_anytime());
        assert!(node.is_background());
        assert_eq!(
            node.anytime().unwrap(),
            &AnytimeConfig {
                time_budget_ms: Some(8.0),
                max_age_ms: Some(100.0),
                quality_target: Some(0.95),
                quality_floor: Some(0.30),
                max_refines: Some(64),
                max_stall: Some(4),
            }
        );
        let src = graph
            .get_node(graph.get_node_id_by_name("src").unwrap())
            .unwrap();
        assert!(!src.is_anytime());
        assert!(src.anytime().is_none());
    }

    #[test]
    fn test_anytime_typical_perception_config_is_accepted() {
        // The doc's typical perception config; foreground placement compiles to
        // a static plan, so max_refines is part of the minimum foreground set.
        let txt = anytime_config_txt(
            "max_age_ms: 100.0, quality_target: 0.9, max_refines: 22",
            "",
            "",
        );
        let config = read_configuration_str(txt, None).unwrap();
        let graph = config.get_graph(None).unwrap();
        let node = graph
            .get_node(graph.get_node_id_by_name("any").unwrap())
            .unwrap();
        let anytime = node.anytime().unwrap();
        assert_eq!(anytime.max_age_ms, Some(100.0));
        assert_eq!(anytime.quality_target, Some(0.9));
        assert_eq!(anytime.max_refines, Some(22));
        assert_eq!(anytime.time_budget_ms, None);
    }

    #[test]
    fn test_anytime_arity_is_one_input_one_output() {
        // Two inputs: the runner cannot pick a Tov anchor.
        let two_inputs = r#"(
            tasks: [
                (id: "src_a", type: "a"),
                (id: "src_b", type: "a"),
                (id: "any", type: "b", anytime: (max_refines: 2)),
                (id: "sink", type: "c"),
            ],
            cnx: [
                (src: "src_a", dst: "any", msg: "msg::A"),
                (src: "src_b", dst: "any", msg: "msg::A"),
                (src: "any", dst: "sink", msg: "msg::B"),
            ],
        )"#;
        expect_anytime_error(
            two_inputs.to_string(),
            "exactly one input connection (found 2)",
        );

        // Two output message types: refine() has no single slot to rewrite.
        let two_outputs = r#"(
            tasks: [
                (id: "src", type: "a"),
                (id: "any", type: "b", anytime: (max_refines: 2)),
                (id: "sink_a", type: "c"),
                (id: "sink_b", type: "c"),
            ],
            cnx: [
                (src: "src", dst: "any", msg: "msg::A"),
                (src: "any", dst: "sink_a", msg: "msg::B"),
                (src: "any", dst: "sink_b", msg: "msg::C"),
            ],
        )"#;
        expect_anytime_error(
            two_outputs.to_string(),
            "exactly one output message type (found 2)",
        );

        // Fan-out of ONE output type to two consumers stays legal.
        let fan_out = r#"(
            tasks: [
                (id: "src", type: "a"),
                (id: "any", type: "b", anytime: (max_refines: 2)),
                (id: "sink_a", type: "c"),
                (id: "sink_b", type: "c"),
            ],
            cnx: [
                (src: "src", dst: "any", msg: "msg::A"),
                (src: "any", dst: "sink_a", msg: "msg::B"),
                (src: "any", dst: "sink_b", msg: "msg::B"),
            ],
        )"#;
        read_configuration_str(fan_out.to_string(), None).unwrap();
    }

    #[test]
    fn test_anytime_foreground_needs_max_refines() {
        // A time-only hard bound cannot produce a static plan in the foreground.
        expect_anytime_error(
            anytime_config_txt("max_age_ms: 100.0, quality_target: 0.9", "", ""),
            "needs anytime.max_refines",
        );
        // Background placement has no static refine schedule to emit.
        let background = anytime_config_txt("max_age_ms: 100.0", ", background: true", "");
        read_configuration_str(background, None).unwrap();
    }

    #[test]
    fn test_anytime_survives_serialize_roundtrip() {
        let txt = anytime_config_txt("time_budget_ms: 8.0, max_refines: 64", "", "");
        let config = CuConfig::deserialize_ron(&txt).unwrap();
        let serialized = config.serialize_ron().unwrap();
        let deserialized = CuConfig::deserialize_ron(&serialized).unwrap();
        let graph = deserialized.get_graph(None).unwrap();
        let node = graph
            .get_node(graph.get_node_id_by_name("any").unwrap())
            .unwrap();
        assert_eq!(
            node.anytime().unwrap(),
            &AnytimeConfig {
                time_budget_ms: Some(8.0),
                max_age_ms: None,
                quality_target: None,
                quality_floor: None,
                max_refines: Some(64),
                max_stall: None,
            }
        );
    }

    #[test]
    fn test_anytime_rejects_missing_hard_bound() {
        expect_anytime_error(
            anytime_config_txt("quality_target: 0.9, max_stall: 4", "", ""),
            "needs at least one hard bound",
        );
    }

    #[test]
    fn test_anytime_rejects_nan_quality_target() {
        expect_anytime_error(
            anytime_config_txt("time_budget_ms: 8.0, quality_target: NaN", "", ""),
            "anytime.quality_target must be within (0.0, 1.0]",
        );
    }

    #[test]
    fn test_anytime_rejects_non_positive_times() {
        expect_anytime_error(
            anytime_config_txt("time_budget_ms: 0.0", "", ""),
            "anytime.time_budget_ms must be a positive",
        );
        expect_anytime_error(
            anytime_config_txt("max_age_ms: -5.0", "", ""),
            "anytime.max_age_ms must be a positive",
        );
        expect_anytime_error(
            anytime_config_txt("time_budget_ms: inf", "", ""),
            "anytime.time_budget_ms must be a positive",
        );
    }

    #[test]
    fn test_anytime_rejects_zero_counts() {
        expect_anytime_error(
            anytime_config_txt("max_refines: 0", "", ""),
            "anytime.max_refines must be at least 1",
        );
        expect_anytime_error(
            anytime_config_txt("max_refines: 4, max_stall: 0", "", ""),
            "anytime.max_stall must be at least 1",
        );
    }

    #[test]
    fn test_anytime_quality_ranges() {
        // target is (0.0, 1.0]: exactly 1.0 is fine, 0.0 is not.
        let ok = anytime_config_txt(
            "time_budget_ms: 8.0, quality_target: 1.0, max_refines: 4",
            "",
            "",
        );
        read_configuration_str(ok, None).unwrap();
        expect_anytime_error(
            anytime_config_txt("time_budget_ms: 8.0, quality_target: 0.0", "", ""),
            "anytime.quality_target must be within (0.0, 1.0]",
        );
        // floor is (0.0, 1.0): exactly 1.0 is rejected.
        expect_anytime_error(
            anytime_config_txt("time_budget_ms: 8.0, quality_floor: 1.0", "", ""),
            "anytime.quality_floor must be within (0.0, 1.0)",
        );
    }

    #[test]
    fn test_anytime_rejects_floor_above_target() {
        expect_anytime_error(
            anytime_config_txt(
                "time_budget_ms: 8.0, quality_target: 0.5, quality_floor: 0.8",
                "",
                "",
            ),
            "must not exceed anytime.quality_target",
        );
    }

    #[test]
    fn test_anytime_rejects_sources_and_sinks() {
        let on_source = r#"(
            tasks: [
                (id: "src", type: "a", anytime: (max_refines: 4)),
                (id: "sink", type: "b"),
            ],
            cnx: [(src: "src", dst: "sink", msg: "msg::A")],
        )"#;
        expect_anytime_error(on_source.to_string(), "only supported on regular tasks");

        let on_sink = r#"(
            tasks: [
                (id: "src", type: "a"),
                (id: "sink", type: "b", anytime: (max_refines: 4)),
            ],
            cnx: [(src: "src", dst: "sink", msg: "msg::A")],
        )"#;
        expect_anytime_error(on_sink.to_string(), "only supported on regular tasks");
    }

    #[test]
    fn test_anytime_foreground_rate_limited_needs_time_bound() {
        expect_anytime_error(
            anytime_config_txt("max_refines: 64", "", "runtime: (rate_target_hz: 100),"),
            "needs a time bound",
        );
    }

    #[test]
    fn test_anytime_foreground_window_must_fit_period() {
        expect_anytime_error(
            anytime_config_txt(
                "time_budget_ms: 12.0, max_refines: 8",
                "",
                "runtime: (rate_target_hz: 100),",
            ),
            "does not fit within",
        );
        // The worst-case window is min(time_budget_ms, max_age_ms).
        let ok = anytime_config_txt(
            "time_budget_ms: 20.0, max_age_ms: 5.0, max_refines: 8",
            "",
            "runtime: (rate_target_hz: 100),",
        );
        read_configuration_str(ok, None).unwrap();
    }

    #[test]
    fn test_anytime_background_exempt_from_fit_check() {
        let txt = anytime_config_txt(
            "max_refines: 64",
            ", background: true",
            "runtime: (rate_target_hz: 100),",
        );
        read_configuration_str(txt, None).unwrap();
    }

    #[test]
    fn test_anytime_no_rate_target_accepts_refines_only_foreground() {
        let txt = anytime_config_txt("max_refines: 64", "", "");
        read_configuration_str(txt, None).unwrap();
    }

    #[test]
    fn test_anytime_validated_per_mission_graph() {
        let txt = r#"(
            missions: [(id: "A"), (id: "B")],
            tasks: [
                (id: "src", type: "a"),
                (id: "any", type: "b", missions: ["B"], anytime: (quality_target: 0.9)),
                (id: "sink", type: "c"),
            ],
            cnx: [
                (src: "src", dst: "any", msg: "msg::A", missions: ["B"]),
                (src: "any", dst: "sink", msg: "msg::B", missions: ["B"]),
                (src: "src", dst: "sink", msg: "msg::A", missions: ["A"]),
            ],
        )"#;
        expect_anytime_error(txt.to_string(), "needs at least one hard bound");
    }

    #[test]
    fn test_nc_connection_marks_source_output_without_creating_edge() {
        let txt = r#"(
            tasks: [(id: "src", type: "a"), (id: "sink", type: "b")],
            cnx: [
                (src: "src", dst: "sink", msg: "msg::A"),
                (src: "src", dst: "__nc__", msg: "msg::B"),
            ]
        )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.get_graph(None).unwrap();
        let src_id = graph.get_node_id_by_name("src").unwrap();
        let src_node = graph.get_node(src_id).unwrap();

        assert_eq!(graph.edge_count(), 1);
        assert_eq!(src_node.nc_outputs(), &["msg::B".to_string()]);
    }

    #[test]
    fn test_nc_connection_survives_serialize_roundtrip() {
        let txt = r#"(
            tasks: [(id: "src", type: "a"), (id: "sink", type: "b")],
            cnx: [
                (src: "src", dst: "sink", msg: "msg::A"),
                (src: "src", dst: "__nc__", msg: "msg::B"),
            ]
        )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let serialized = config.serialize_ron().unwrap();
        let deserialized = CuConfig::deserialize_ron(&serialized).unwrap();
        let graph = deserialized.get_graph(None).unwrap();
        let src_id = graph.get_node_id_by_name("src").unwrap();
        let src_node = graph.get_node(src_id).unwrap();

        assert_eq!(graph.edge_count(), 1);
        assert_eq!(src_node.nc_outputs(), &["msg::B".to_string()]);
    }

    #[test]
    fn test_nc_connection_preserves_original_connection_order() {
        let txt = r#"(
            tasks: [(id: "src", type: "a"), (id: "sink", type: "b")],
            cnx: [
                (src: "src", dst: "__nc__", msg: "msg::A"),
                (src: "src", dst: "sink", msg: "msg::B"),
            ]
        )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.get_graph(None).unwrap();
        let src_id = graph.get_node_id_by_name("src").unwrap();
        let src_node = graph.get_node(src_id).unwrap();
        let edge_id = graph.get_src_edges(src_id).unwrap()[0];
        let edge = graph.edge(edge_id).unwrap();

        assert_eq!(edge.msg, "msg::B");
        assert_eq!(edge.order, 1);
        assert_eq!(
            src_node
                .nc_outputs_with_order()
                .map(|(msg, order)| (msg.as_str(), order))
                .collect::<Vec<_>>(),
            vec![("msg::A", 0)]
        );
    }

    #[cfg(feature = "std")]
    fn multi_config_test_dir(name: &str) -> PathBuf {
        let unique = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .expect("system time before unix epoch")
            .as_nanos();
        let dir = std::env::temp_dir().join(format!("cu29_multi_config_{name}_{unique}"));
        std::fs::create_dir_all(&dir).expect("create temp test dir");
        dir
    }

    #[cfg(feature = "std")]
    fn write_multi_config_file(dir: &Path, name: &str, contents: &str) -> PathBuf {
        let path = dir.join(name);
        std::fs::write(&path, contents).expect("write temp config file");
        path
    }

    #[cfg(feature = "std")]
    fn alpha_subsystem_config() -> &'static str {
        r#"(
            tasks: [
                (id: "src", type: "demo::Src"),
                (id: "sink", type: "demo::Sink"),
            ],
            bridges: [
                (
                    id: "zenoh",
                    type: "demo::ZenohBridge",
                    channels: [
                        Tx(id: "ping"),
                        Rx(id: "pong"),
                    ],
                ),
            ],
            cnx: [
                (src: "src", dst: "zenoh/ping", msg: "demo::Ping"),
                (src: "zenoh/pong", dst: "sink", msg: "demo::Pong"),
            ],
        )"#
    }

    #[cfg(feature = "std")]
    fn beta_subsystem_config() -> &'static str {
        r#"(
            tasks: [
                (id: "responder", type: "demo::Responder"),
            ],
            bridges: [
                (
                    id: "zenoh",
                    type: "demo::ZenohBridge",
                    channels: [
                        Rx(id: "ping"),
                        Tx(id: "pong"),
                    ],
                ),
            ],
            cnx: [
                (src: "zenoh/ping", dst: "responder", msg: "demo::Ping"),
                (src: "responder", dst: "zenoh/pong", msg: "demo::Pong"),
            ],
        )"#
    }

    #[cfg(feature = "std")]
    fn instance_override_subsystem_config() -> &'static str {
        r#"(
            tasks: [
                (
                    id: "imu",
                    type: "demo::ImuTask",
                    config: {
                        "sample_hz": 200,
                    },
                ),
            ],
            resources: [
                (
                    id: "board",
                    provider: "demo::BoardBundle",
                    config: {
                        "bus": "i2c-1",
                    },
                ),
            ],
            bridges: [
                (
                    id: "radio",
                    type: "demo::RadioBridge",
                    config: {
                        "mtu": 32,
                    },
                    channels: [
                        Tx(id: "tx"),
                        Rx(id: "rx"),
                    ],
                ),
            ],
            cnx: [
                (src: "imu", dst: "radio/tx", msg: "demo::Packet"),
                (src: "radio/rx", dst: "imu", msg: "demo::Packet"),
            ],
        )"#
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_read_multi_configuration_assigns_stable_subsystem_codes() {
        let dir = multi_config_test_dir("stable_ids");
        write_multi_config_file(&dir, "alpha.ron", alpha_subsystem_config());
        write_multi_config_file(&dir, "beta.ron", beta_subsystem_config());
        let network_path = write_multi_config_file(
            &dir,
            "network.ron",
            r#"(
                subsystems: [
                    (id: "beta", config: "beta.ron"),
                    (id: "alpha", config: "alpha.ron"),
                ],
                interconnects: [
                    (from: "alpha/zenoh/ping", to: "beta/zenoh/ping", msg: "demo::Ping"),
                    (from: "beta/zenoh/pong", to: "alpha/zenoh/pong", msg: "demo::Pong"),
                ],
            )"#,
        );

        let config =
            read_multi_configuration(network_path.to_str().expect("network path utf8")).unwrap();

        let alpha = config.subsystem("alpha").expect("alpha subsystem missing");
        let beta = config.subsystem("beta").expect("beta subsystem missing");
        assert_eq!(alpha.subsystem_code, 0);
        assert_eq!(beta.subsystem_code, 1);
        assert_eq!(config.interconnects.len(), 2);
        assert_eq!(config.interconnects[0].bridge_type, "demo::ZenohBridge");
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_multi_configuration_filters_interconnects_by_feature() {
        let dir = multi_config_test_dir("feature_interconnects");
        write_multi_config_file(&dir, "alpha.ron", alpha_subsystem_config());
        write_multi_config_file(&dir, "beta.ron", beta_subsystem_config());
        let network_path = write_multi_config_file(
            &dir,
            "network.ron",
            r#"(
                subsystems: [
                    (id: "alpha", config: "alpha.ron"),
                    (id: "beta", config: "beta.ron"),
                ],
                interconnects: [
                    (
                        from: "alpha/zenoh/ping",
                        to: "beta/zenoh/ping",
                        msg: "demo::Ping",
                        when: Feature("networked"),
                    ),
                    (
                        from: "beta/zenoh/pong",
                        to: "alpha/zenoh/pong",
                        msg: "demo::Pong",
                        when: Feature("networked"),
                    ),
                ],
            )"#,
        );

        let disconnected = read_multi_configuration_with_features(
            network_path.to_str().expect("network path utf8"),
            &[],
        )
        .unwrap();
        assert!(disconnected.interconnects.is_empty());

        let networked = read_multi_configuration_with_features(
            network_path.to_str().expect("network path utf8"),
            &["networked"],
        )
        .unwrap();
        assert_eq!(networked.interconnects.len(), 2);
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_multi_configuration_uses_default_mission_contracts() {
        let dir = multi_config_test_dir("default_mission");
        write_multi_config_file(
            &dir,
            "alpha.ron",
            r#"(
                missions: [(id: "default"), (id: "diagnostics")],
                tasks: [
                    (id: "src", type: "demo::Src"),
                    (
                        id: "diagnostic",
                        type: "demo::Diagnostic",
                        missions: ["diagnostics"],
                    ),
                ],
                bridges: [
                    (
                        id: "zenoh",
                        type: "demo::ZenohBridge",
                        channels: [Tx(id: "ping")],
                    ),
                ],
                cnx: [
                    (src: "src", dst: "zenoh/ping", msg: "demo::Ping"),
                    (
                        src: "diagnostic",
                        dst: "__nc__",
                        msg: "demo::DiagnosticMessage",
                        missions: ["diagnostics"],
                    ),
                ],
            )"#,
        );
        write_multi_config_file(&dir, "beta.ron", beta_subsystem_config());
        let network_path = write_multi_config_file(
            &dir,
            "network.ron",
            r#"(
                subsystems: [
                    (id: "alpha", config: "alpha.ron"),
                    (id: "beta", config: "beta.ron"),
                ],
                interconnects: [
                    (from: "alpha/zenoh/ping", to: "beta/zenoh/ping", msg: "demo::Ping"),
                ],
            )"#,
        );

        let config =
            read_multi_configuration(network_path.to_str().expect("network path utf8")).unwrap();
        assert_eq!(config.interconnects.len(), 1);
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_read_multi_configuration_rejects_wrong_direction() {
        let dir = multi_config_test_dir("wrong_direction");
        write_multi_config_file(&dir, "alpha.ron", alpha_subsystem_config());
        write_multi_config_file(&dir, "beta.ron", beta_subsystem_config());
        let network_path = write_multi_config_file(
            &dir,
            "network.ron",
            r#"(
                subsystems: [
                    (id: "alpha", config: "alpha.ron"),
                    (id: "beta", config: "beta.ron"),
                ],
                interconnects: [
                    (from: "alpha/zenoh/pong", to: "beta/zenoh/ping", msg: "demo::Pong"),
                ],
            )"#,
        );

        let err = read_multi_configuration(network_path.to_str().expect("network path utf8"))
            .expect_err("direction mismatch should fail");

        assert!(
            err.to_string()
                .contains("must reference a Tx bridge channel"),
            "unexpected error: {err}"
        );
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_read_multi_configuration_rejects_declared_message_mismatch() {
        let dir = multi_config_test_dir("msg_mismatch");
        write_multi_config_file(&dir, "alpha.ron", alpha_subsystem_config());
        write_multi_config_file(&dir, "beta.ron", beta_subsystem_config());
        let network_path = write_multi_config_file(
            &dir,
            "network.ron",
            r#"(
                subsystems: [
                    (id: "alpha", config: "alpha.ron"),
                    (id: "beta", config: "beta.ron"),
                ],
                interconnects: [
                    (from: "alpha/zenoh/ping", to: "beta/zenoh/ping", msg: "demo::Wrong"),
                ],
            )"#,
        );

        let err = read_multi_configuration(network_path.to_str().expect("network path utf8"))
            .expect_err("message mismatch should fail");

        assert!(
            err.to_string()
                .contains("declares message type 'demo::Wrong'"),
            "unexpected error: {err}"
        );
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_read_multi_configuration_resolves_instance_override_root() {
        let dir = multi_config_test_dir("instance_root");
        write_multi_config_file(&dir, "robot.ron", instance_override_subsystem_config());
        let network_path = write_multi_config_file(
            &dir,
            "multi_copper.ron",
            r#"(
                subsystems: [
                    (id: "robot", config: "robot.ron"),
                ],
                interconnects: [],
                instance_overrides_root: "instances",
            )"#,
        );

        let config =
            read_multi_configuration(network_path.to_str().expect("network path utf8")).unwrap();

        assert_eq!(
            config.instance_overrides_root.as_deref().map(Path::new),
            Some(dir.join("instances").as_path())
        );
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_resolve_subsystem_config_for_instance_applies_overrides() {
        let dir = multi_config_test_dir("instance_apply");
        write_multi_config_file(&dir, "robot.ron", instance_override_subsystem_config());
        let instances_dir = dir.join("instances").join("17");
        std::fs::create_dir_all(&instances_dir).expect("create instance dir");
        write_multi_config_file(
            &instances_dir,
            "robot.ron",
            r#"(
                set: [
                    (
                        path: "tasks/imu/config",
                        value: {
                            "gyro_bias": [0.1, -0.2, 0.3],
                        },
                    ),
                    (
                        path: "resources/board/config",
                        value: {
                            "bus": "robot17-imu",
                        },
                    ),
                    (
                        path: "bridges/radio/config",
                        value: {
                            "mtu": 64,
                        },
                    ),
                ],
            )"#,
        );
        let network_path = write_multi_config_file(
            &dir,
            "multi_copper.ron",
            r#"(
                subsystems: [
                    (id: "robot", config: "robot.ron"),
                ],
                interconnects: [],
                instance_overrides_root: "instances",
            )"#,
        );

        let multi =
            read_multi_configuration(network_path.to_str().expect("network path utf8")).unwrap();
        let effective = multi
            .resolve_subsystem_config_for_instance("robot", 17)
            .expect("effective config");

        let graph = effective.get_graph(None).expect("graph");
        let imu_id = graph.get_node_id_by_name("imu").expect("imu node");
        let imu = graph.get_node(imu_id).expect("imu weight");
        let imu_cfg = imu.get_instance_config().expect("imu config");
        assert_eq!(imu_cfg.get::<u64>("sample_hz").unwrap(), Some(200));
        let gyro_bias: Vec<f64> = imu_cfg
            .get_value("gyro_bias")
            .expect("gyro_bias deserialize")
            .expect("gyro_bias value");
        assert_eq!(gyro_bias, vec![0.1, -0.2, 0.3]);

        let board = effective
            .resources
            .iter()
            .find(|resource| resource.id == "board")
            .expect("board resource");
        assert_eq!(
            board.config.as_ref().unwrap().get::<String>("bus").unwrap(),
            Some("robot17-imu".to_string())
        );

        let radio = effective
            .bridges
            .iter()
            .find(|bridge| bridge.id == "radio")
            .expect("radio bridge");
        assert_eq!(
            radio.config.as_ref().unwrap().get::<u64>("mtu").unwrap(),
            Some(64)
        );

        let radio_id = graph.get_node_id_by_name("radio").expect("radio node");
        let radio_node = graph.get_node(radio_id).expect("radio weight");
        assert_eq!(
            radio_node
                .get_instance_config()
                .unwrap()
                .get::<u64>("mtu")
                .unwrap(),
            Some(64)
        );
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_resolve_subsystem_config_for_instance_rejects_unknown_path() {
        let dir = multi_config_test_dir("instance_unknown");
        write_multi_config_file(&dir, "robot.ron", instance_override_subsystem_config());
        let instances_dir = dir.join("instances").join("17");
        std::fs::create_dir_all(&instances_dir).expect("create instance dir");
        write_multi_config_file(
            &instances_dir,
            "robot.ron",
            r#"(
                set: [
                    (
                        path: "tasks/missing/config",
                        value: {
                            "gyro_bias": [1.0, 2.0, 3.0],
                        },
                    ),
                ],
            )"#,
        );
        let network_path = write_multi_config_file(
            &dir,
            "multi_copper.ron",
            r#"(
                subsystems: [
                    (id: "robot", config: "robot.ron"),
                ],
                interconnects: [],
                instance_overrides_root: "instances",
            )"#,
        );

        let multi =
            read_multi_configuration(network_path.to_str().expect("network path utf8")).unwrap();
        let err = multi
            .resolve_subsystem_config_for_instance("robot", 17)
            .expect_err("unknown task override should fail");

        assert!(
            err.to_string().contains("targets unknown task 'missing'"),
            "unexpected error: {err}"
        );
    }

    #[test]
    fn test_thread_pools_parse_and_round_trip() {
        let txt = r#"(
            runtime: (
                rate_target_hz: 1000,
                thread_pools: [
                    ( id: "rt",         threads: 4, affinity: [2, 3, 4, 5], policy: Fifo(priority: 80) ),
                    ( id: "background", threads: 2, affinity: [0, 1] ),
                    ( id: "vision",     threads: 2, policy: Nice(10), on_error: Strict ),
                ],
            ),
            tasks: [ ( id: "t", type: "tasks::Foo" ) ],
        )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let runtime = config.runtime.as_ref().expect("runtime config");
        assert_eq!(runtime.thread_pools.len(), 3);

        let rt = &runtime.thread_pools[0];
        assert_eq!(rt.id, "rt");
        assert_eq!(rt.threads, 4);
        assert_eq!(rt.affinity.as_deref(), Some([2, 3, 4, 5].as_slice()));
        assert_eq!(rt.policy, SchedulingPolicy::Fifo { priority: 80 });
        assert_eq!(rt.on_error, OnError::Warn);

        let bg = &runtime.thread_pools[1];
        assert_eq!(bg.id, "background");
        assert_eq!(bg.policy, SchedulingPolicy::Fair);

        let vision = &runtime.thread_pools[2];
        assert_eq!(vision.policy, SchedulingPolicy::Nice(10));
        assert_eq!(vision.affinity, None);
        assert_eq!(vision.on_error, OnError::Strict);

        // Round-trips through serialization.
        let serialized = config.serialize_ron().unwrap();
        let reparsed = CuConfig::deserialize_ron(&serialized).unwrap();
        assert_eq!(
            reparsed.runtime.as_ref().unwrap().thread_pools,
            runtime.thread_pools
        );
    }

    #[test]
    fn test_background_flag_and_pool_forms() {
        let txt = r#"(
            tasks: [
                ( id: "a", type: "tasks::Foo", background: true ),
                ( id: "b", type: "tasks::Foo", background: (pool: "vision") ),
                ( id: "c", type: "tasks::Foo" ),
            ],
            cnx: [],
        )"#;
        let config = CuConfig::deserialize_ron(txt).unwrap();
        let graph = config.get_graph(None).unwrap();

        let a = graph.get_node(0).unwrap();
        assert!(a.is_background());
        assert_eq!(a.background_pool(), DEFAULT_BACKGROUND_POOL);

        let b = graph.get_node(1).unwrap();
        assert!(b.is_background());
        assert_eq!(b.background_pool(), "vision");

        let c = graph.get_node(2).unwrap();
        assert!(!c.is_background());
        assert_eq!(c.background_pool(), DEFAULT_BACKGROUND_POOL);
    }

    #[test]
    fn test_thread_pool_validation_rejects_bad_configs() {
        let cases = [
            (
                r#"( runtime: ( thread_pools: [ ( id: "rt", threads: 0 ) ] ), tasks: [] )"#,
                "at least 1 thread",
            ),
            (
                r#"( runtime: ( thread_pools: [ ( id: "a", threads: 1 ), ( id: "a", threads: 1 ) ] ), tasks: [] )"#,
                "Duplicate thread pool id",
            ),
            (
                r#"( runtime: ( thread_pools: [ ( id: "rt", threads: 1, policy: Fifo(priority: 200) ) ] ), tasks: [] )"#,
                "out of range",
            ),
            (
                r#"( runtime: ( thread_pools: [ ( id: "rt", threads: 1, affinity: [] ) ] ), tasks: [] )"#,
                "empty affinity",
            ),
        ];

        for (txt, expected) in cases {
            let err = CuConfig::deserialize_ron(txt)
                .expect_err("expected thread pool validation to fail");
            assert!(
                err.to_string().contains(expected),
                "error '{err}' did not contain '{expected}'"
            );
        }
    }

    #[cfg(feature = "std")]
    #[test]
    fn test_default_background_pool_injected_for_background_tasks() {
        let txt = r#"(
            tasks: [
                ( id: "src", type: "tasks::Src" ),
                ( id: "bg",  type: "tasks::Task", background: true ),
            ],
            cnx: [
                ( src: "src", dst: "bg", msg: "i32" ),
                ( src: "bg", dst: "__nc__", msg: "i32" ),
            ],
        )"#;
        let config = read_configuration_str(txt.to_string(), None).unwrap();
        let pools = &config.runtime.as_ref().unwrap().thread_pools;
        let background: Vec<_> = pools
            .iter()
            .filter(|p| p.id == DEFAULT_BACKGROUND_POOL)
            .collect();
        assert_eq!(background.len(), 1);
        assert_eq!(background[0].threads, 2);
        // Thread pools are owned by the runtime, not the resource manager — no
        // synthetic "threadpool" bundle should be injected.
        assert!(!config.resources.iter().any(|b| b.id == "threadpool"));
    }
}