phytrace_sdk/

ffi.rs

//! C FFI bindings for the PhyTrace SDK.
//!
//! This module exposes the PhyTrace SDK's core functionality through a C-compatible
//! ABI, enabling integration with C++ ROS2 nodes and other non-Rust consumers.
//!
//! # Architecture
//!
//! The FFI layer manages an internal `tokio::Runtime` per agent handle so that
//! C callers never deal with async. All functions are synchronous from the caller's
//! perspective.
//!
//! # Memory Model
//!
//! - Opaque handles (`*mut PhyTraceAgent`, `*mut PhyTraceBuilder`, `*mut PhyTraceEvent`)
//!   are heap-allocated and must be freed by the corresponding `_destroy` function.
//! - Strings returned by the library (e.g., `phytrace_last_error`, `phytrace_event_to_json`)
//!   must be freed with `phytrace_string_free`.
//! - Null pointers are handled gracefully — functions return `PHYTRACE_ERR_NULL_PTR`.
//!
//! # Domains Covered
//!
//! This FFI layer covers the domains required for ROS2 topic integration:
//! - Identity, Location, Motion, Power, Perception (Lidar + IMU), Safety,
//!   Navigation, Actuators (Joints), Operational, Communication, Context
//!
//! # Domains NOT Yet Covered (tracked in issue)
//!
//! AI, Audio, Compliance, Compute, Coordination, EnvironmentInteraction,
//! HRI, Maintenance, Manipulation, Payload, Simulation, Thermal

#![allow(clippy::missing_safety_doc)]

use std::cell::RefCell;
use std::ffi::{CStr, CString};
use std::os::raw::c_char;
use std::ptr;

use crate::core::builder::EventBuilder;
use crate::core::config::PhyTraceConfig;
use crate::models::domains::*;
use crate::models::enums;
use crate::models::event::UdmEvent;
use crate::transport::mock::MockTransport;
use crate::PhyTraceAgent;

// =============================================================================
// Error Codes
// =============================================================================

/// Operation succeeded.
pub const PHYTRACE_OK: i32 = 0;
/// A null pointer was passed where a valid pointer was required.
pub const PHYTRACE_ERR_NULL_PTR: i32 = -1;
/// A string argument contained invalid UTF-8.
pub const PHYTRACE_ERR_INVALID_UTF8: i32 = -2;
/// Configuration error (invalid YAML, missing fields, validation failure).
pub const PHYTRACE_ERR_CONFIG: i32 = -3;
/// Agent lifecycle error (start, stop, flush).
pub const PHYTRACE_ERR_AGENT: i32 = -4;
/// Event builder error (build validation failed).
pub const PHYTRACE_ERR_BUILDER: i32 = -5;
/// Transport error (send failed).
pub const PHYTRACE_ERR_TRANSPORT: i32 = -6;
/// Tokio runtime creation failed.
pub const PHYTRACE_ERR_RUNTIME: i32 = -7;
/// Serialization error (JSON encode/decode).
pub const PHYTRACE_ERR_SERIALIZATION: i32 = -8;
/// Invalid enum value passed.
pub const PHYTRACE_ERR_INVALID_ENUM: i32 = -9;

// =============================================================================
// Enum Integer Constants — EventType
// =============================================================================

/// `EventType::TelemetryPeriodic`
pub const PHYTRACE_EVENT_TYPE_TELEMETRY_PERIODIC: i32 = 0;
/// `EventType::TelemetryOnChange`
pub const PHYTRACE_EVENT_TYPE_TELEMETRY_ON_CHANGE: i32 = 1;
/// `EventType::TelemetrySnapshot`
pub const PHYTRACE_EVENT_TYPE_TELEMETRY_SNAPSHOT: i32 = 2;
/// `EventType::StateTransition`
pub const PHYTRACE_EVENT_TYPE_STATE_TRANSITION: i32 = 3;
/// `EventType::ModeChange`
pub const PHYTRACE_EVENT_TYPE_MODE_CHANGE: i32 = 4;
/// `EventType::TaskStarted`
pub const PHYTRACE_EVENT_TYPE_TASK_STARTED: i32 = 5;
/// `EventType::TaskCompleted`
pub const PHYTRACE_EVENT_TYPE_TASK_COMPLETED: i32 = 6;
/// `EventType::TaskFailed`
pub const PHYTRACE_EVENT_TYPE_TASK_FAILED: i32 = 7;
/// `EventType::TaskCancelled`
pub const PHYTRACE_EVENT_TYPE_TASK_CANCELLED: i32 = 8;
/// `EventType::GoalReached`
pub const PHYTRACE_EVENT_TYPE_GOAL_REACHED: i32 = 9;
/// `EventType::PathBlocked`
pub const PHYTRACE_EVENT_TYPE_PATH_BLOCKED: i32 = 10;
/// `EventType::Rerouting`
pub const PHYTRACE_EVENT_TYPE_REROUTING: i32 = 11;
/// `EventType::SafetyViolation`
pub const PHYTRACE_EVENT_TYPE_SAFETY_VIOLATION: i32 = 12;
/// `EventType::EmergencyStop`
pub const PHYTRACE_EVENT_TYPE_EMERGENCY_STOP: i32 = 13;
/// `EventType::SystemStartup`
pub const PHYTRACE_EVENT_TYPE_SYSTEM_STARTUP: i32 = 14;
/// `EventType::SystemShutdown`
pub const PHYTRACE_EVENT_TYPE_SYSTEM_SHUTDOWN: i32 = 15;
/// `EventType::Error`
pub const PHYTRACE_EVENT_TYPE_ERROR: i32 = 16;
/// `EventType::Custom`
pub const PHYTRACE_EVENT_TYPE_CUSTOM: i32 = 17;

// =============================================================================
// Enum Integer Constants — SourceType
// =============================================================================

/// `SourceType::Amr`
pub const PHYTRACE_SOURCE_TYPE_AMR: i32 = 0;
/// `SourceType::Agv`
pub const PHYTRACE_SOURCE_TYPE_AGV: i32 = 1;
/// `SourceType::AutonomousForklift`
pub const PHYTRACE_SOURCE_TYPE_AUTONOMOUS_FORKLIFT: i32 = 2;
/// `SourceType::DeliveryRobot`
pub const PHYTRACE_SOURCE_TYPE_DELIVERY_ROBOT: i32 = 3;
/// `SourceType::CleaningRobot`
pub const PHYTRACE_SOURCE_TYPE_CLEANING_ROBOT: i32 = 4;
/// `SourceType::InspectionRobot`
pub const PHYTRACE_SOURCE_TYPE_INSPECTION_ROBOT: i32 = 5;
/// `SourceType::SecurityRobot`
pub const PHYTRACE_SOURCE_TYPE_SECURITY_ROBOT: i32 = 6;
/// `SourceType::IndustrialArm`
pub const PHYTRACE_SOURCE_TYPE_INDUSTRIAL_ARM: i32 = 7;
/// `SourceType::Cobot`
pub const PHYTRACE_SOURCE_TYPE_COBOT: i32 = 8;
/// `SourceType::MobileManipulator`
pub const PHYTRACE_SOURCE_TYPE_MOBILE_MANIPULATOR: i32 = 9;
/// `SourceType::AutonomousVehicle`
pub const PHYTRACE_SOURCE_TYPE_AUTONOMOUS_VEHICLE: i32 = 10;
/// `SourceType::ElectricVehicle`
pub const PHYTRACE_SOURCE_TYPE_ELECTRIC_VEHICLE: i32 = 11;
/// `SourceType::Drone`
pub const PHYTRACE_SOURCE_TYPE_DRONE: i32 = 12;
/// `SourceType::Humanoid`
pub const PHYTRACE_SOURCE_TYPE_HUMANOID: i32 = 13;
/// `SourceType::Quadruped`
pub const PHYTRACE_SOURCE_TYPE_QUADRUPED: i32 = 14;
/// `SourceType::Human`
pub const PHYTRACE_SOURCE_TYPE_HUMAN: i32 = 15;
/// `SourceType::Custom`
pub const PHYTRACE_SOURCE_TYPE_CUSTOM: i32 = 16;
/// `SourceType::Simulation`
pub const PHYTRACE_SOURCE_TYPE_SIMULATION: i32 = 17;

// =============================================================================
// Enum Integer Constants — SafetyState
// =============================================================================

/// `SafetyState::Normal`
pub const PHYTRACE_SAFETY_STATE_NORMAL: i32 = 0;
/// `SafetyState::Warning`
pub const PHYTRACE_SAFETY_STATE_WARNING: i32 = 1;
/// `SafetyState::ProtectiveStop`
pub const PHYTRACE_SAFETY_STATE_PROTECTIVE_STOP: i32 = 2;
/// `SafetyState::EmergencyStop`
pub const PHYTRACE_SAFETY_STATE_EMERGENCY_STOP: i32 = 3;
/// `SafetyState::SafetyInterlock`
pub const PHYTRACE_SAFETY_STATE_SAFETY_INTERLOCK: i32 = 4;
/// `SafetyState::ReducedSpeed`
pub const PHYTRACE_SAFETY_STATE_REDUCED_SPEED: i32 = 5;

// =============================================================================
// Enum Integer Constants — OperationalMode
// =============================================================================

/// `OperationalMode::Autonomous`
pub const PHYTRACE_OPERATIONAL_MODE_AUTONOMOUS: i32 = 0;
/// `OperationalMode::Manual`
pub const PHYTRACE_OPERATIONAL_MODE_MANUAL: i32 = 1;
/// `OperationalMode::SemiAutonomous`
pub const PHYTRACE_OPERATIONAL_MODE_SEMI_AUTONOMOUS: i32 = 2;
/// `OperationalMode::Teleoperated`
pub const PHYTRACE_OPERATIONAL_MODE_TELEOPERATED: i32 = 3;
/// `OperationalMode::Learning`
pub const PHYTRACE_OPERATIONAL_MODE_LEARNING: i32 = 4;
/// `OperationalMode::Maintenance`
pub const PHYTRACE_OPERATIONAL_MODE_MAINTENANCE: i32 = 5;
/// `OperationalMode::Emergency`
pub const PHYTRACE_OPERATIONAL_MODE_EMERGENCY: i32 = 6;
/// `OperationalMode::Idle`
pub const PHYTRACE_OPERATIONAL_MODE_IDLE: i32 = 7;

// =============================================================================
// Enum Integer Constants — OperationalState
// =============================================================================

/// `OperationalState::Off`
pub const PHYTRACE_OPERATIONAL_STATE_OFF: i32 = 0;
/// `OperationalState::Booting`
pub const PHYTRACE_OPERATIONAL_STATE_BOOTING: i32 = 1;
/// `OperationalState::Ready`
pub const PHYTRACE_OPERATIONAL_STATE_READY: i32 = 2;
/// `OperationalState::ExecutingTask`
pub const PHYTRACE_OPERATIONAL_STATE_EXECUTING_TASK: i32 = 3;
/// `OperationalState::Navigating`
pub const PHYTRACE_OPERATIONAL_STATE_NAVIGATING: i32 = 4;
/// `OperationalState::Manipulating`
pub const PHYTRACE_OPERATIONAL_STATE_MANIPULATING: i32 = 5;
/// `OperationalState::Charging`
pub const PHYTRACE_OPERATIONAL_STATE_CHARGING: i32 = 6;
/// `OperationalState::Paused`
pub const PHYTRACE_OPERATIONAL_STATE_PAUSED: i32 = 7;
/// `OperationalState::Error`
pub const PHYTRACE_OPERATIONAL_STATE_ERROR: i32 = 8;
/// `OperationalState::EmergencyStopped`
pub const PHYTRACE_OPERATIONAL_STATE_EMERGENCY_STOPPED: i32 = 9;
/// `OperationalState::ShuttingDown`
pub const PHYTRACE_OPERATIONAL_STATE_SHUTTING_DOWN: i32 = 10;
/// `OperationalState::Recovering`
pub const PHYTRACE_OPERATIONAL_STATE_RECOVERING: i32 = 11;

// =============================================================================
// Enum Integer Constants — LocalizationQuality
// =============================================================================

/// `LocalizationQuality::Excellent`
pub const PHYTRACE_LOCALIZATION_QUALITY_EXCELLENT: i32 = 0;
/// `LocalizationQuality::Good`
pub const PHYTRACE_LOCALIZATION_QUALITY_GOOD: i32 = 1;
/// `LocalizationQuality::Fair`
pub const PHYTRACE_LOCALIZATION_QUALITY_FAIR: i32 = 2;
/// `LocalizationQuality::Poor`
pub const PHYTRACE_LOCALIZATION_QUALITY_POOR: i32 = 3;
/// `LocalizationQuality::Lost`
pub const PHYTRACE_LOCALIZATION_QUALITY_LOST: i32 = 4;

// =============================================================================
// Enum Integer Constants — PathState
// =============================================================================

/// `PathState::None`
pub const PHYTRACE_PATH_STATE_NONE: i32 = 0;
/// `PathState::Planning`
pub const PHYTRACE_PATH_STATE_PLANNING: i32 = 1;
/// `PathState::Valid`
pub const PHYTRACE_PATH_STATE_VALID: i32 = 2;
/// `PathState::Executing`
pub const PHYTRACE_PATH_STATE_EXECUTING: i32 = 3;
/// `PathState::Blocked`
pub const PHYTRACE_PATH_STATE_BLOCKED: i32 = 4;
/// `PathState::Completed`
pub const PHYTRACE_PATH_STATE_COMPLETED: i32 = 5;
/// `PathState::Failed`
pub const PHYTRACE_PATH_STATE_FAILED: i32 = 6;

// =============================================================================
// Enum Integer Constants — EStopType
// =============================================================================

/// `EStopType::Software`
pub const PHYTRACE_ESTOP_TYPE_SOFTWARE: i32 = 0;
/// `EStopType::Hardware`
pub const PHYTRACE_ESTOP_TYPE_HARDWARE: i32 = 1;
/// `EStopType::Remote`
pub const PHYTRACE_ESTOP_TYPE_REMOTE: i32 = 2;
/// `EStopType::Automatic`
pub const PHYTRACE_ESTOP_TYPE_AUTOMATIC: i32 = 3;

// =============================================================================
// Enum Conversion Helpers
// =============================================================================

fn event_type_from_i32(val: i32) -> Option<enums::EventType> {
    match val {
        PHYTRACE_EVENT_TYPE_TELEMETRY_PERIODIC => Some(enums::EventType::TelemetryPeriodic),
        PHYTRACE_EVENT_TYPE_TELEMETRY_ON_CHANGE => Some(enums::EventType::TelemetryOnChange),
        PHYTRACE_EVENT_TYPE_TELEMETRY_SNAPSHOT => Some(enums::EventType::TelemetrySnapshot),
        PHYTRACE_EVENT_TYPE_STATE_TRANSITION => Some(enums::EventType::StateTransition),
        PHYTRACE_EVENT_TYPE_MODE_CHANGE => Some(enums::EventType::ModeChange),
        PHYTRACE_EVENT_TYPE_TASK_STARTED => Some(enums::EventType::TaskStarted),
        PHYTRACE_EVENT_TYPE_TASK_COMPLETED => Some(enums::EventType::TaskCompleted),
        PHYTRACE_EVENT_TYPE_TASK_FAILED => Some(enums::EventType::TaskFailed),
        PHYTRACE_EVENT_TYPE_TASK_CANCELLED => Some(enums::EventType::TaskCancelled),
        PHYTRACE_EVENT_TYPE_GOAL_REACHED => Some(enums::EventType::GoalReached),
        PHYTRACE_EVENT_TYPE_PATH_BLOCKED => Some(enums::EventType::PathBlocked),
        PHYTRACE_EVENT_TYPE_REROUTING => Some(enums::EventType::Rerouting),
        PHYTRACE_EVENT_TYPE_SAFETY_VIOLATION => Some(enums::EventType::SafetyViolation),
        PHYTRACE_EVENT_TYPE_EMERGENCY_STOP => Some(enums::EventType::EmergencyStop),
        PHYTRACE_EVENT_TYPE_SYSTEM_STARTUP => Some(enums::EventType::SystemStartup),
        PHYTRACE_EVENT_TYPE_SYSTEM_SHUTDOWN => Some(enums::EventType::SystemShutdown),
        PHYTRACE_EVENT_TYPE_ERROR => Some(enums::EventType::Error),
        PHYTRACE_EVENT_TYPE_CUSTOM => Some(enums::EventType::Custom),
        _ => None,
    }
}

fn source_type_from_i32(val: i32) -> Option<enums::SourceType> {
    match val {
        PHYTRACE_SOURCE_TYPE_AMR => Some(enums::SourceType::Amr),
        PHYTRACE_SOURCE_TYPE_AGV => Some(enums::SourceType::Agv),
        PHYTRACE_SOURCE_TYPE_AUTONOMOUS_FORKLIFT => Some(enums::SourceType::AutonomousForklift),
        PHYTRACE_SOURCE_TYPE_DELIVERY_ROBOT => Some(enums::SourceType::DeliveryRobot),
        PHYTRACE_SOURCE_TYPE_CLEANING_ROBOT => Some(enums::SourceType::CleaningRobot),
        PHYTRACE_SOURCE_TYPE_INSPECTION_ROBOT => Some(enums::SourceType::InspectionRobot),
        PHYTRACE_SOURCE_TYPE_SECURITY_ROBOT => Some(enums::SourceType::SecurityRobot),
        PHYTRACE_SOURCE_TYPE_INDUSTRIAL_ARM => Some(enums::SourceType::IndustrialArm),
        PHYTRACE_SOURCE_TYPE_COBOT => Some(enums::SourceType::Cobot),
        PHYTRACE_SOURCE_TYPE_MOBILE_MANIPULATOR => Some(enums::SourceType::MobileManipulator),
        PHYTRACE_SOURCE_TYPE_AUTONOMOUS_VEHICLE => Some(enums::SourceType::AutonomousVehicle),
        PHYTRACE_SOURCE_TYPE_ELECTRIC_VEHICLE => Some(enums::SourceType::ElectricVehicle),
        PHYTRACE_SOURCE_TYPE_DRONE => Some(enums::SourceType::Drone),
        PHYTRACE_SOURCE_TYPE_HUMANOID => Some(enums::SourceType::Humanoid),
        PHYTRACE_SOURCE_TYPE_QUADRUPED => Some(enums::SourceType::Quadruped),
        PHYTRACE_SOURCE_TYPE_HUMAN => Some(enums::SourceType::Human),
        PHYTRACE_SOURCE_TYPE_CUSTOM => Some(enums::SourceType::Custom),
        PHYTRACE_SOURCE_TYPE_SIMULATION => Some(enums::SourceType::Simulation),
        _ => None,
    }
}

fn safety_state_from_i32(val: i32) -> Option<enums::SafetyState> {
    match val {
        PHYTRACE_SAFETY_STATE_NORMAL => Some(enums::SafetyState::Normal),
        PHYTRACE_SAFETY_STATE_WARNING => Some(enums::SafetyState::Warning),
        PHYTRACE_SAFETY_STATE_PROTECTIVE_STOP => Some(enums::SafetyState::ProtectiveStop),
        PHYTRACE_SAFETY_STATE_EMERGENCY_STOP => Some(enums::SafetyState::EmergencyStop),
        PHYTRACE_SAFETY_STATE_SAFETY_INTERLOCK => Some(enums::SafetyState::SafetyInterlock),
        PHYTRACE_SAFETY_STATE_REDUCED_SPEED => Some(enums::SafetyState::ReducedSpeed),
        _ => None,
    }
}

fn operational_mode_from_i32(val: i32) -> Option<enums::OperationalMode> {
    match val {
        PHYTRACE_OPERATIONAL_MODE_AUTONOMOUS => Some(enums::OperationalMode::Autonomous),
        PHYTRACE_OPERATIONAL_MODE_MANUAL => Some(enums::OperationalMode::Manual),
        PHYTRACE_OPERATIONAL_MODE_SEMI_AUTONOMOUS => Some(enums::OperationalMode::SemiAutonomous),
        PHYTRACE_OPERATIONAL_MODE_TELEOPERATED => Some(enums::OperationalMode::Teleoperated),
        PHYTRACE_OPERATIONAL_MODE_LEARNING => Some(enums::OperationalMode::Learning),
        PHYTRACE_OPERATIONAL_MODE_MAINTENANCE => Some(enums::OperationalMode::Maintenance),
        PHYTRACE_OPERATIONAL_MODE_EMERGENCY => Some(enums::OperationalMode::Emergency),
        PHYTRACE_OPERATIONAL_MODE_IDLE => Some(enums::OperationalMode::Idle),
        _ => None,
    }
}

fn operational_state_from_i32(val: i32) -> Option<enums::OperationalState> {
    match val {
        PHYTRACE_OPERATIONAL_STATE_OFF => Some(enums::OperationalState::Off),
        PHYTRACE_OPERATIONAL_STATE_BOOTING => Some(enums::OperationalState::Booting),
        PHYTRACE_OPERATIONAL_STATE_READY => Some(enums::OperationalState::Ready),
        PHYTRACE_OPERATIONAL_STATE_EXECUTING_TASK => Some(enums::OperationalState::ExecutingTask),
        PHYTRACE_OPERATIONAL_STATE_NAVIGATING => Some(enums::OperationalState::Navigating),
        PHYTRACE_OPERATIONAL_STATE_MANIPULATING => Some(enums::OperationalState::Manipulating),
        PHYTRACE_OPERATIONAL_STATE_CHARGING => Some(enums::OperationalState::Charging),
        PHYTRACE_OPERATIONAL_STATE_PAUSED => Some(enums::OperationalState::Paused),
        PHYTRACE_OPERATIONAL_STATE_ERROR => Some(enums::OperationalState::Error),
        PHYTRACE_OPERATIONAL_STATE_EMERGENCY_STOPPED => {
            Some(enums::OperationalState::EmergencyStopped)
        }
        PHYTRACE_OPERATIONAL_STATE_SHUTTING_DOWN => Some(enums::OperationalState::ShuttingDown),
        PHYTRACE_OPERATIONAL_STATE_RECOVERING => Some(enums::OperationalState::Recovering),
        _ => None,
    }
}

fn localization_quality_from_i32(val: i32) -> Option<enums::LocalizationQuality> {
    match val {
        PHYTRACE_LOCALIZATION_QUALITY_EXCELLENT => Some(enums::LocalizationQuality::Excellent),
        PHYTRACE_LOCALIZATION_QUALITY_GOOD => Some(enums::LocalizationQuality::Good),
        PHYTRACE_LOCALIZATION_QUALITY_FAIR => Some(enums::LocalizationQuality::Fair),
        PHYTRACE_LOCALIZATION_QUALITY_POOR => Some(enums::LocalizationQuality::Poor),
        PHYTRACE_LOCALIZATION_QUALITY_LOST => Some(enums::LocalizationQuality::Lost),
        _ => None,
    }
}

fn path_state_from_i32(val: i32) -> Option<enums::PathState> {
    match val {
        PHYTRACE_PATH_STATE_NONE => Some(enums::PathState::None),
        PHYTRACE_PATH_STATE_PLANNING => Some(enums::PathState::Planning),
        PHYTRACE_PATH_STATE_VALID => Some(enums::PathState::Valid),
        PHYTRACE_PATH_STATE_EXECUTING => Some(enums::PathState::Executing),
        PHYTRACE_PATH_STATE_BLOCKED => Some(enums::PathState::Blocked),
        PHYTRACE_PATH_STATE_COMPLETED => Some(enums::PathState::Completed),
        PHYTRACE_PATH_STATE_FAILED => Some(enums::PathState::Failed),
        _ => None,
    }
}

fn estop_type_from_i32(val: i32) -> Option<enums::EStopType> {
    match val {
        PHYTRACE_ESTOP_TYPE_SOFTWARE => Some(enums::EStopType::Software),
        PHYTRACE_ESTOP_TYPE_HARDWARE => Some(enums::EStopType::Hardware),
        PHYTRACE_ESTOP_TYPE_REMOTE => Some(enums::EStopType::Remote),
        PHYTRACE_ESTOP_TYPE_AUTOMATIC => Some(enums::EStopType::Automatic),
        _ => None,
    }
}

// =============================================================================
// Thread-local Error Storage
// =============================================================================

thread_local! {
    static LAST_ERROR: RefCell<Option<CString>> = const { RefCell::new(None) };
}

fn set_last_error(msg: impl Into<String>) {
    let msg = msg.into();
    tracing::error!(ffi_error = %msg);
    LAST_ERROR.with(|e| {
        *e.borrow_mut() = CString::new(msg).ok();
    });
}

fn clear_last_error() {
    LAST_ERROR.with(|e| {
        *e.borrow_mut() = None;
    });
}

// =============================================================================
// Opaque Handle Types
// =============================================================================

/// Opaque handle to a PhyTrace agent with an embedded tokio runtime.
pub struct PhyTraceAgentHandle {
    agent: PhyTraceAgent,
    runtime: tokio::runtime::Runtime,
}

/// Opaque handle to an event builder.
pub struct PhyTraceBuilderHandle {
    builder: EventBuilder,
}

/// Opaque handle to a built UDM event.
pub struct PhyTraceEventHandle {
    event: UdmEvent,
}

// =============================================================================
// Helper: convert C string to &str
// =============================================================================

unsafe fn cstr_to_str<'a>(ptr: *const c_char) -> Result<&'a str, i32> {
    if ptr.is_null() {
        return Err(PHYTRACE_ERR_NULL_PTR);
    }
    CStr::from_ptr(ptr)
        .to_str()
        .map_err(|_| PHYTRACE_ERR_INVALID_UTF8)
}

/// Helper: convert optional C string to Option<String>
unsafe fn optional_cstr_to_string(ptr: *const c_char) -> Option<String> {
    if ptr.is_null() {
        None
    } else {
        CStr::from_ptr(ptr).to_str().ok().map(|s| s.to_owned())
    }
}

// =============================================================================
// Error Retrieval
// =============================================================================

/// Retrieve the last error message from the FFI layer.
///
/// Returns a pointer to a null-terminated UTF-8 string describing the last error.
/// Returns null if no error has occurred. The returned string is valid until the
/// next FFI call on the same thread. Caller must NOT free this pointer.
#[no_mangle]
pub extern "C" fn phytrace_last_error() -> *const c_char {
    LAST_ERROR.with(|e| {
        let borrow = e.borrow();
        match borrow.as_ref() {
            Some(cstr) => cstr.as_ptr(),
            None => ptr::null(),
        }
    })
}

/// Free a string allocated by the PhyTrace FFI layer.
///
/// Must be called on strings returned by `phytrace_event_to_json`.
/// Passing null is a no-op.
#[no_mangle]
pub unsafe extern "C" fn phytrace_string_free(s: *mut c_char) {
    if !s.is_null() {
        drop(CString::from_raw(s));
    }
}

// =============================================================================
// Version
// =============================================================================

/// Get the PhyTrace SDK version string.
///
/// Returns a pointer to a static null-terminated string. Caller must NOT free this.
#[no_mangle]
pub extern "C" fn phytrace_sdk_version() -> *const c_char {
    // Safety: SDK_VERSION is a &'static str from env!, always valid
    static VERSION_CSTR: std::sync::OnceLock<CString> = std::sync::OnceLock::new();
    VERSION_CSTR
        .get_or_init(|| CString::new(crate::SDK_VERSION).unwrap())
        .as_ptr()
}

/// Get the UDM version string supported by this SDK.
///
/// Returns a pointer to a static null-terminated string. Caller must NOT free this.
#[no_mangle]
pub extern "C" fn phytrace_udm_version() -> *const c_char {
    static UDM_VERSION_CSTR: std::sync::OnceLock<CString> = std::sync::OnceLock::new();
    UDM_VERSION_CSTR
        .get_or_init(|| CString::new(crate::UDM_VERSION).unwrap())
        .as_ptr()
}

// =============================================================================
// Config & Agent Lifecycle
// =============================================================================

/// Create a PhyTrace agent from a YAML configuration string.
///
/// Returns a heap-allocated agent handle on success, or null on failure.
/// On failure, call `phytrace_last_error()` for details.
///
/// The returned handle must be freed with `phytrace_agent_destroy()`.
#[no_mangle]
pub unsafe extern "C" fn phytrace_agent_create_from_yaml(
    yaml_str: *const c_char,
) -> *mut PhyTraceAgentHandle {
    clear_last_error();

    let yaml = match cstr_to_str(yaml_str) {
        Ok(s) => s,
        Err(code) => {
            set_last_error(if code == PHYTRACE_ERR_NULL_PTR {
                "yaml_str is null"
            } else {
                "yaml_str contains invalid UTF-8"
            });
            return ptr::null_mut();
        }
    };

    let config = match PhyTraceConfig::from_yaml(yaml) {
        Ok(c) => c,
        Err(e) => {
            set_last_error(format!("Config parse error: {e}"));
            return ptr::null_mut();
        }
    };

    create_agent_from_config(config)
}

/// Create a PhyTrace agent from a YAML configuration file path.
///
/// Returns a heap-allocated agent handle on success, or null on failure.
/// On failure, call `phytrace_last_error()` for details.
///
/// The returned handle must be freed with `phytrace_agent_destroy()`.
#[no_mangle]
pub unsafe extern "C" fn phytrace_agent_create_from_file(
    path: *const c_char,
) -> *mut PhyTraceAgentHandle {
    clear_last_error();

    let path_str = match cstr_to_str(path) {
        Ok(s) => s,
        Err(code) => {
            set_last_error(if code == PHYTRACE_ERR_NULL_PTR {
                "path is null"
            } else {
                "path contains invalid UTF-8"
            });
            return ptr::null_mut();
        }
    };

    let runtime = match tokio::runtime::Runtime::new() {
        Ok(rt) => rt,
        Err(e) => {
            set_last_error(format!("Failed to create tokio runtime: {e}"));
            return ptr::null_mut();
        }
    };

    let config = match PhyTraceConfig::from_file(path_str) {
        Ok(c) => c,
        Err(e) => {
            set_last_error(format!("Config file error: {e}"));
            return ptr::null_mut();
        }
    };

    // Drop the temporary runtime — create_agent_from_config makes its own
    drop(runtime);
    create_agent_from_config(config)
}

/// Internal helper to create an agent handle from a validated config.
fn create_agent_from_config(config: PhyTraceConfig) -> *mut PhyTraceAgentHandle {
    let runtime = match tokio::runtime::Runtime::new() {
        Ok(rt) => rt,
        Err(e) => {
            set_last_error(format!("Failed to create tokio runtime: {e}"));
            return ptr::null_mut();
        }
    };

    let agent = match runtime.block_on(PhyTraceAgent::from_config(config)) {
        Ok(a) => a,
        Err(e) => {
            set_last_error(format!("Agent creation error: {e}"));
            return ptr::null_mut();
        }
    };

    Box::into_raw(Box::new(PhyTraceAgentHandle { agent, runtime }))
}

/// Create a PhyTrace agent with a mock transport for testing.
///
/// This is a convenience function that creates an agent configured with
/// a `MockTransport` — useful for unit tests and integration tests where
/// no real PhyCloud endpoint is needed.
///
/// `source_id` — Null-terminated source identifier string.
/// `source_type` — Integer source type constant (e.g., `PHYTRACE_SOURCE_TYPE_AMR`).
///
/// Returns a heap-allocated agent handle on success, or null on failure.
#[no_mangle]
pub unsafe extern "C" fn phytrace_agent_create_mock(
    source_id: *const c_char,
    source_type: i32,
) -> *mut PhyTraceAgentHandle {
    clear_last_error();

    let sid = match cstr_to_str(source_id) {
        Ok(s) => s,
        Err(code) => {
            set_last_error(if code == PHYTRACE_ERR_NULL_PTR {
                "source_id is null"
            } else {
                "source_id contains invalid UTF-8"
            });
            return ptr::null_mut();
        }
    };

    let st = match source_type_from_i32(source_type) {
        Some(st) => st,
        None => {
            set_last_error(format!("Invalid source_type: {source_type}"));
            return ptr::null_mut();
        }
    };

    let config = PhyTraceConfig::new(sid).with_source_type(st);
    let transport = Box::new(MockTransport::new());

    let runtime = match tokio::runtime::Runtime::new() {
        Ok(rt) => rt,
        Err(e) => {
            set_last_error(format!("Failed to create tokio runtime: {e}"));
            return ptr::null_mut();
        }
    };

    let agent = match runtime.block_on(PhyTraceAgent::with_transport(config, transport)) {
        Ok(a) => a,
        Err(e) => {
            set_last_error(format!("Agent creation error: {e}"));
            return ptr::null_mut();
        }
    };

    Box::into_raw(Box::new(PhyTraceAgentHandle { agent, runtime }))
}

/// Start the agent (connects transport, begins background workers).
///
/// Returns `PHYTRACE_OK` on success, negative error code on failure.
#[no_mangle]
pub unsafe extern "C" fn phytrace_agent_start(agent: *mut PhyTraceAgentHandle) -> i32 {
    clear_last_error();

    if agent.is_null() {
        set_last_error("agent handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let handle = &*agent;
    match handle.runtime.block_on(handle.agent.start()) {
        Ok(()) => PHYTRACE_OK,
        Err(e) => {
            set_last_error(format!("Agent start error: {e}"));
            PHYTRACE_ERR_AGENT
        }
    }
}

/// Stop the agent gracefully (flushes buffer, disconnects transport).
///
/// Returns `PHYTRACE_OK` on success, negative error code on failure.
#[no_mangle]
pub unsafe extern "C" fn phytrace_agent_stop(agent: *mut PhyTraceAgentHandle) -> i32 {
    clear_last_error();

    if agent.is_null() {
        set_last_error("agent handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let handle = &*agent;
    match handle.runtime.block_on(handle.agent.shutdown()) {
        Ok(()) => PHYTRACE_OK,
        Err(e) => {
            set_last_error(format!("Agent stop error: {e}"));
            PHYTRACE_ERR_AGENT
        }
    }
}

/// Destroy and free an agent handle.
///
/// Calls stop if the agent is still running, then frees all memory.
/// Passing null is a no-op.
#[no_mangle]
pub unsafe extern "C" fn phytrace_agent_destroy(agent: *mut PhyTraceAgentHandle) {
    if !agent.is_null() {
        let handle = Box::from_raw(agent);
        // Attempt graceful shutdown — ignore errors during destroy
        let _ = handle.runtime.block_on(handle.agent.shutdown());
        // handle is dropped here, freeing agent + runtime
    }
}

/// Check if the agent is currently running.
///
/// Returns 1 if running, 0 if not, `PHYTRACE_ERR_NULL_PTR` if agent is null.
#[no_mangle]
pub unsafe extern "C" fn phytrace_agent_is_running(agent: *const PhyTraceAgentHandle) -> i32 {
    if agent.is_null() {
        set_last_error("agent handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    if (*agent).agent.is_running() {
        1
    } else {
        0
    }
}

/// Flush any buffered events to the transport.
///
/// Returns `PHYTRACE_OK` on success, negative error code on failure.
#[no_mangle]
pub unsafe extern "C" fn phytrace_agent_flush(agent: *mut PhyTraceAgentHandle) -> i32 {
    clear_last_error();

    if agent.is_null() {
        set_last_error("agent handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let handle = &*agent;
    match handle.runtime.block_on(handle.agent.flush()) {
        Ok(()) => PHYTRACE_OK,
        Err(e) => {
            set_last_error(format!("Flush error: {e}"));
            PHYTRACE_ERR_TRANSPORT
        }
    }
}

// =============================================================================
// Event Builder
// =============================================================================

/// Create a new event builder from an agent's configuration.
///
/// Returns a heap-allocated builder handle, or null on failure.
/// The builder must be freed with `phytrace_builder_destroy()` or consumed
/// by `phytrace_builder_build()`.
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_new(
    agent: *const PhyTraceAgentHandle,
) -> *mut PhyTraceBuilderHandle {
    clear_last_error();

    if agent.is_null() {
        set_last_error("agent handle is null");
        return ptr::null_mut();
    }

    let config = (*agent).agent.config();
    let builder = EventBuilder::new(config);
    Box::into_raw(Box::new(PhyTraceBuilderHandle { builder }))
}

/// Set the event type on the builder.
///
/// `event_type` is one of the `PHYTRACE_EVENT_TYPE_*` constants.
/// Returns `PHYTRACE_OK` on success, negative error code on failure.
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_event_type(
    builder: *mut PhyTraceBuilderHandle,
    event_type: i32,
) -> i32 {
    clear_last_error();

    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let et = match event_type_from_i32(event_type) {
        Some(et) => et,
        None => {
            set_last_error(format!("Invalid event_type: {event_type}"));
            return PHYTRACE_ERR_INVALID_ENUM;
        }
    };

    let handle = &mut *builder;
    // EventBuilder uses a consuming pattern — we need to swap
    let old_builder = std::mem::replace(
        &mut handle.builder,
        EventBuilder::new(&PhyTraceConfig::new("tmp")),
    );
    handle.builder = old_builder.event_type(et);
    PHYTRACE_OK
}

/// Set the source type on the builder.
///
/// `source_type` is one of the `PHYTRACE_SOURCE_TYPE_*` constants.
/// Returns `PHYTRACE_OK` on success, negative error code on failure.
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_source_type(
    builder: *mut PhyTraceBuilderHandle,
    source_type: i32,
) -> i32 {
    clear_last_error();

    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let st = match source_type_from_i32(source_type) {
        Some(st) => st,
        None => {
            set_last_error(format!("Invalid source_type: {source_type}"));
            return PHYTRACE_ERR_INVALID_ENUM;
        }
    };

    let handle = &mut *builder;
    let old_builder = std::mem::replace(
        &mut handle.builder,
        EventBuilder::new(&PhyTraceConfig::new("tmp")),
    );
    handle.builder = old_builder.source_type(st);
    PHYTRACE_OK
}

/// Build the event, consuming the builder.
///
/// Returns a heap-allocated event handle on success, or null on failure
/// (e.g., validation error). On failure, the builder is still consumed/freed.
///
/// The returned event must be freed with `phytrace_event_destroy()` or
/// consumed by `phytrace_agent_send()`.
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_build(
    builder: *mut PhyTraceBuilderHandle,
) -> *mut PhyTraceEventHandle {
    clear_last_error();

    if builder.is_null() {
        set_last_error("builder handle is null");
        return ptr::null_mut();
    }

    let handle = Box::from_raw(builder);
    match handle.builder.build() {
        Ok(event) => Box::into_raw(Box::new(PhyTraceEventHandle { event })),
        Err(e) => {
            set_last_error(format!("Build error: {e}"));
            ptr::null_mut()
        }
    }
}

/// Build the event without validation, consuming the builder.
///
/// This always succeeds and returns a handle. Useful for testing or when
/// the caller knows the event is well-formed.
///
/// The returned event must be freed with `phytrace_event_destroy()` or
/// consumed by `phytrace_agent_send()`.
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_build_unchecked(
    builder: *mut PhyTraceBuilderHandle,
) -> *mut PhyTraceEventHandle {
    clear_last_error();

    if builder.is_null() {
        set_last_error("builder handle is null");
        return ptr::null_mut();
    }

    let handle = Box::from_raw(builder);
    let event = handle.builder.build_unchecked();
    Box::into_raw(Box::new(PhyTraceEventHandle { event }))
}

/// Destroy a builder without building an event.
///
/// Passing null is a no-op.
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_destroy(builder: *mut PhyTraceBuilderHandle) {
    if !builder.is_null() {
        drop(Box::from_raw(builder));
    }
}

// =============================================================================
// Builder Helper — macro for consuming builder pattern
// =============================================================================

/// Internal macro that handles the mem::replace dance for consuming builder methods.
macro_rules! builder_mutate {
    ($builder:expr, |$b:ident| $body:expr) => {{
        let handle = &mut *$builder;
        let $b = std::mem::replace(
            &mut handle.builder,
            EventBuilder::new(&PhyTraceConfig::new("tmp")),
        );
        handle.builder = $body;
    }};
}

// =============================================================================
// Domain Setters — Location
// =============================================================================

/// Set the location domain on the builder.
///
/// All floating-point parameters use `f64::NAN` to indicate "not set".
/// String parameters use null to indicate "not set".
///
/// # Parameters
/// - `latitude` — GPS latitude in decimal degrees (-90 to 90), or NAN
/// - `longitude` — GPS longitude in decimal degrees (-180 to 180), or NAN
/// - `altitude_m` — Altitude in meters above sea level, or NAN
/// - `heading_deg` — Heading in degrees (0-360), or NAN
/// - `x_m` — Local X coordinate in meters, or NAN
/// - `y_m` — Local Y coordinate in meters, or NAN
/// - `z_m` — Local Z coordinate in meters, or NAN
/// - `yaw_deg` — Local yaw angle in degrees, or NAN
/// - `frame_id` — Reference frame ID (e.g., "map", "odom"), or null
/// - `map_id` — Map identifier, or null
/// - `floor` — Floor number; `i32::MIN` means "not set"
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_location(
    builder: *mut PhyTraceBuilderHandle,
    latitude: f64,
    longitude: f64,
    altitude_m: f64,
    heading_deg: f64,
    x_m: f64,
    y_m: f64,
    z_m: f64,
    yaw_deg: f64,
    frame_id: *const c_char,
    map_id: *const c_char,
    floor: i32,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let has_local = !x_m.is_nan() || !y_m.is_nan() || !z_m.is_nan() || !yaw_deg.is_nan();

    let local = if has_local {
        Some(location::LocalCoordinates {
            x_m: if x_m.is_nan() { None } else { Some(x_m) },
            y_m: if y_m.is_nan() { None } else { Some(y_m) },
            z_m: if z_m.is_nan() { None } else { Some(z_m) },
            yaw_deg: if yaw_deg.is_nan() {
                None
            } else {
                Some(yaw_deg)
            },
            ..Default::default()
        })
    } else {
        None
    };

    let loc = LocationDomain {
        latitude: if latitude.is_nan() {
            None
        } else {
            Some(latitude)
        },
        longitude: if longitude.is_nan() {
            None
        } else {
            Some(longitude)
        },
        altitude_m: if altitude_m.is_nan() {
            None
        } else {
            Some(altitude_m)
        },
        heading_deg: if heading_deg.is_nan() {
            None
        } else {
            Some(heading_deg)
        },
        local,
        frame_id: optional_cstr_to_string(frame_id),
        map_id: optional_cstr_to_string(map_id),
        floor: if floor == i32::MIN { None } else { Some(floor) },
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.location(loc));
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Motion
// =============================================================================

/// Set the motion domain on the builder.
///
/// All floating-point parameters use `f64::NAN` to indicate "not set".
///
/// # Parameters
/// - `speed_mps` — Speed in meters/second, or NAN
/// - `vx`, `vy`, `vz` — Linear velocity components in m/s, or NAN
/// - `roll_dps`, `pitch_dps`, `yaw_dps` — Angular velocity in deg/s, or NAN
/// - `cmd_linear_mps` — Commanded linear velocity m/s, or NAN
/// - `cmd_angular_dps` — Commanded angular velocity deg/s, or NAN
/// - `frame_id` — Reference frame, or null
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_motion(
    builder: *mut PhyTraceBuilderHandle,
    speed_mps: f64,
    vx: f64,
    vy: f64,
    vz: f64,
    roll_dps: f64,
    pitch_dps: f64,
    yaw_dps: f64,
    cmd_linear_mps: f64,
    cmd_angular_dps: f64,
    frame_id: *const c_char,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let has_linear = !vx.is_nan() || !vy.is_nan() || !vz.is_nan();
    let has_angular = !roll_dps.is_nan() || !pitch_dps.is_nan() || !yaw_dps.is_nan();

    let mot = MotionDomain {
        speed_mps: if speed_mps.is_nan() {
            None
        } else {
            Some(speed_mps)
        },
        linear_velocity: if has_linear {
            Some(motion::LinearVelocity {
                x_mps: if vx.is_nan() { None } else { Some(vx) },
                y_mps: if vy.is_nan() { None } else { Some(vy) },
                z_mps: if vz.is_nan() { None } else { Some(vz) },
            })
        } else {
            None
        },
        angular_velocity: if has_angular {
            Some(motion::AngularVelocity {
                roll_dps: if roll_dps.is_nan() {
                    None
                } else {
                    Some(roll_dps)
                },
                pitch_dps: if pitch_dps.is_nan() {
                    None
                } else {
                    Some(pitch_dps)
                },
                yaw_dps: if yaw_dps.is_nan() {
                    None
                } else {
                    Some(yaw_dps)
                },
            })
        } else {
            None
        },
        commanded_linear_mps: if cmd_linear_mps.is_nan() {
            None
        } else {
            Some(cmd_linear_mps)
        },
        commanded_angular_dps: if cmd_angular_dps.is_nan() {
            None
        } else {
            Some(cmd_angular_dps)
        },
        frame_id: optional_cstr_to_string(frame_id),
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.motion(mot));
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Power
// =============================================================================

/// Set the power domain on the builder.
///
/// Floating-point parameters use `f64::NAN` for "not set".
/// `is_charging`: 1 = true, 0 = false, -1 = not set.
///
/// # Parameters
/// - `soc_pct` — State of charge percentage (0-100), or NAN
/// - `voltage_v` — Battery voltage, or NAN
/// - `current_a` — Battery current in amps, or NAN
/// - `temperature_c` — Battery temperature in Celsius, or NAN
/// - `is_charging` — 1/0/-1
/// - `health_pct` — State of health percentage (0-100), or NAN
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_power(
    builder: *mut PhyTraceBuilderHandle,
    soc_pct: f64,
    voltage_v: f64,
    current_a: f64,
    temperature_c: f64,
    is_charging: i32,
    health_pct: f64,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let battery = power::Battery {
        state_of_charge_pct: if soc_pct.is_nan() {
            None
        } else {
            Some(soc_pct)
        },
        voltage_v: if voltage_v.is_nan() {
            None
        } else {
            Some(voltage_v)
        },
        current_a: if current_a.is_nan() {
            None
        } else {
            Some(current_a)
        },
        temperature_c: if temperature_c.is_nan() {
            None
        } else {
            Some(temperature_c)
        },
        state_of_health_pct: if health_pct.is_nan() {
            None
        } else {
            Some(health_pct)
        },
        ..Default::default()
    };

    let charging = if is_charging >= 0 {
        Some(power::Charging {
            is_charging: Some(is_charging != 0),
            state: Some(if is_charging != 0 {
                enums::ChargingState::Charging
            } else {
                enums::ChargingState::NotCharging
            }),
            ..Default::default()
        })
    } else {
        None
    };

    let pwr = PowerDomain {
        battery: Some(battery),
        charging,
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.power(pwr));
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Perception: Lidar
// =============================================================================

/// Set a lidar sensor in the perception domain.
///
/// String parameters use null for "not set". Float parameters use NAN for "not set".
///
/// # Parameters
/// - `sensor_id` — Sensor identifier string, or null
/// - `point_count` — Number of points in scan; 0 means not set
/// - `min_range_m`, `max_range_m` — Sensor range limits, or NAN
/// - `min_angle_deg`, `max_angle_deg` — Scan angle limits, or NAN
/// - `angular_resolution_deg` — Angular resolution, or NAN
/// - `closest_range_m` — Closest detected range, or NAN
/// - `closest_angle_deg` — Angle of closest detection, or NAN
/// - `scan_frequency_hz` — Scan frequency, or NAN
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_perception_lidar(
    builder: *mut PhyTraceBuilderHandle,
    sensor_id: *const c_char,
    point_count: u32,
    min_range_m: f64,
    max_range_m: f64,
    min_angle_deg: f64,
    max_angle_deg: f64,
    angular_resolution_deg: f64,
    closest_range_m: f64,
    closest_angle_deg: f64,
    scan_frequency_hz: f64,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let lidar = perception::LidarSensor {
        sensor_id: optional_cstr_to_string(sensor_id),
        point_count: if point_count == 0 {
            None
        } else {
            Some(point_count)
        },
        min_range_m: if min_range_m.is_nan() {
            None
        } else {
            Some(min_range_m)
        },
        max_range_m: if max_range_m.is_nan() {
            None
        } else {
            Some(max_range_m)
        },
        min_angle_deg: if min_angle_deg.is_nan() {
            None
        } else {
            Some(min_angle_deg)
        },
        max_angle_deg: if max_angle_deg.is_nan() {
            None
        } else {
            Some(max_angle_deg)
        },
        angular_resolution_deg: if angular_resolution_deg.is_nan() {
            None
        } else {
            Some(angular_resolution_deg)
        },
        closest_range_m: if closest_range_m.is_nan() {
            None
        } else {
            Some(closest_range_m)
        },
        closest_angle_deg: if closest_angle_deg.is_nan() {
            None
        } else {
            Some(closest_angle_deg)
        },
        scan_frequency_hz: if scan_frequency_hz.is_nan() {
            None
        } else {
            Some(scan_frequency_hz)
        },
        ..Default::default()
    };

    // Get or create the perception domain, append to lidar vec
    let handle = &mut *builder;
    let old_builder = std::mem::replace(
        &mut handle.builder,
        EventBuilder::new(&PhyTraceConfig::new("tmp")),
    );

    // Peek at existing perception to preserve any IMU data already set
    let existing_perception = old_builder.peek().perception.clone();
    let mut perc = existing_perception.unwrap_or_default();
    let lidars = perc.lidar.get_or_insert_with(Vec::new);
    lidars.push(lidar);

    handle.builder = old_builder.perception(perc);
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Perception: IMU
// =============================================================================

/// Set the IMU sensor in the perception domain.
///
/// Float parameters use NAN for "not set".
///
/// # Parameters
/// - `accel_x_mps2`, `accel_y_mps2`, `accel_z_mps2` — Linear acceleration (m/s²)
/// - `gyro_x_dps`, `gyro_y_dps`, `gyro_z_dps` — Angular velocity (deg/s)
/// - `mag_x_ut`, `mag_y_ut`, `mag_z_ut` — Magnetometer readings (microtesla)
/// - `temperature_c` — Sensor temperature, or NAN
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_perception_imu(
    builder: *mut PhyTraceBuilderHandle,
    accel_x_mps2: f64,
    accel_y_mps2: f64,
    accel_z_mps2: f64,
    gyro_x_dps: f64,
    gyro_y_dps: f64,
    gyro_z_dps: f64,
    mag_x_ut: f64,
    mag_y_ut: f64,
    mag_z_ut: f64,
    temperature_c: f64,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let imu = perception::ImuSensor {
        accel_x_mps2: if accel_x_mps2.is_nan() {
            None
        } else {
            Some(accel_x_mps2)
        },
        accel_y_mps2: if accel_y_mps2.is_nan() {
            None
        } else {
            Some(accel_y_mps2)
        },
        accel_z_mps2: if accel_z_mps2.is_nan() {
            None
        } else {
            Some(accel_z_mps2)
        },
        gyro_x_dps: if gyro_x_dps.is_nan() {
            None
        } else {
            Some(gyro_x_dps)
        },
        gyro_y_dps: if gyro_y_dps.is_nan() {
            None
        } else {
            Some(gyro_y_dps)
        },
        gyro_z_dps: if gyro_z_dps.is_nan() {
            None
        } else {
            Some(gyro_z_dps)
        },
        mag_x_ut: if mag_x_ut.is_nan() {
            None
        } else {
            Some(mag_x_ut)
        },
        mag_y_ut: if mag_y_ut.is_nan() {
            None
        } else {
            Some(mag_y_ut)
        },
        mag_z_ut: if mag_z_ut.is_nan() {
            None
        } else {
            Some(mag_z_ut)
        },
        temperature_c: if temperature_c.is_nan() {
            None
        } else {
            Some(temperature_c)
        },
        ..Default::default()
    };

    // Preserve existing perception data (lidar, etc.)
    let handle = &mut *builder;
    let old_builder = std::mem::replace(
        &mut handle.builder,
        EventBuilder::new(&PhyTraceConfig::new("tmp")),
    );
    let existing_perception = old_builder.peek().perception.clone();
    let mut perc = existing_perception.unwrap_or_default();
    perc.imu = Some(imu);

    handle.builder = old_builder.perception(perc);
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Safety
// =============================================================================

/// Set the safety domain on the builder.
///
/// Enum parameters use -1 for "not set". Boolean parameters use -1 for "not set",
/// 0 for false, 1 for true. Float parameters use NAN for "not set".
///
/// # Parameters
/// - `safety_state` — `PHYTRACE_SAFETY_STATE_*` constant, or -1
/// - `is_safe` — 1/0/-1
/// - `estop_active` — 1/0/-1
/// - `estop_type` — `PHYTRACE_ESTOP_TYPE_*` constant, or -1
/// - `speed_limit_mps` — Speed limit in m/s, or NAN
/// - `closest_distance_m` — Closest obstacle distance, or NAN
/// - `closest_human_m` — Closest human distance, or NAN
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_safety(
    builder: *mut PhyTraceBuilderHandle,
    safety_state: i32,
    is_safe: i32,
    estop_active: i32,
    estop_type: i32,
    speed_limit_mps: f64,
    closest_distance_m: f64,
    closest_human_m: f64,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let ss = if safety_state >= 0 {
        match safety_state_from_i32(safety_state) {
            Some(s) => Some(s),
            None => {
                set_last_error(format!("Invalid safety_state: {safety_state}"));
                return PHYTRACE_ERR_INVALID_ENUM;
            }
        }
    } else {
        None
    };

    let estop = if estop_active >= 0 {
        let et = if estop_type >= 0 {
            match estop_type_from_i32(estop_type) {
                Some(t) => Some(t),
                None => {
                    set_last_error(format!("Invalid estop_type: {estop_type}"));
                    return PHYTRACE_ERR_INVALID_ENUM;
                }
            }
        } else {
            None
        };

        Some(safety::EStopInfo {
            is_active: Some(estop_active != 0),
            e_stop_type: et,
            ..Default::default()
        })
    } else {
        None
    };

    let proximity = if !closest_distance_m.is_nan() || !closest_human_m.is_nan() {
        Some(safety::ProximityInfo {
            closest_distance_m: if closest_distance_m.is_nan() {
                None
            } else {
                Some(closest_distance_m)
            },
            closest_human_m: if closest_human_m.is_nan() {
                None
            } else {
                Some(closest_human_m)
            },
            ..Default::default()
        })
    } else {
        None
    };

    let saf = SafetyDomain {
        safety_state: ss,
        is_safe: if is_safe >= 0 {
            Some(is_safe != 0)
        } else {
            None
        },
        e_stop: estop,
        speed_limit_mps: if speed_limit_mps.is_nan() {
            None
        } else {
            Some(speed_limit_mps)
        },
        proximity,
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.safety(saf));
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Navigation
// =============================================================================

/// Set the navigation domain on the builder.
///
/// Enum parameters use -1 for "not set". Float/bool follow the NAN/-1 conventions.
///
/// # Parameters
/// - `loc_quality` — `PHYTRACE_LOCALIZATION_QUALITY_*` constant, or -1
/// - `loc_confidence` — Localization confidence (0.0-1.0), or NAN
/// - `is_localized` — 1/0/-1
/// - `path_state` — `PHYTRACE_PATH_STATE_*` constant, or -1
/// - `path_length_m` — Total path length in meters, or NAN
/// - `path_remaining_m` — Remaining path length, or NAN
/// - `goal_x`, `goal_y` — Goal position in meters, or NAN
/// - `goal_orientation_deg` — Goal orientation, or NAN
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_navigation(
    builder: *mut PhyTraceBuilderHandle,
    loc_quality: i32,
    loc_confidence: f64,
    is_localized: i32,
    path_state: i32,
    path_length_m: f64,
    path_remaining_m: f64,
    goal_x: f64,
    goal_y: f64,
    goal_orientation_deg: f64,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let localization = if loc_quality >= 0 || !loc_confidence.is_nan() || is_localized >= 0 {
        let quality = if loc_quality >= 0 {
            match localization_quality_from_i32(loc_quality) {
                Some(q) => Some(q),
                None => {
                    set_last_error(format!("Invalid loc_quality: {loc_quality}"));
                    return PHYTRACE_ERR_INVALID_ENUM;
                }
            }
        } else {
            None
        };

        Some(navigation::Localization {
            quality,
            confidence: if loc_confidence.is_nan() {
                None
            } else {
                Some(loc_confidence)
            },
            is_localized: if is_localized >= 0 {
                Some(is_localized != 0)
            } else {
                None
            },
            ..Default::default()
        })
    } else {
        None
    };

    let path = if path_state >= 0 || !path_length_m.is_nan() || !path_remaining_m.is_nan() {
        let ps = if path_state >= 0 {
            match path_state_from_i32(path_state) {
                Some(p) => Some(p),
                None => {
                    set_last_error(format!("Invalid path_state: {path_state}"));
                    return PHYTRACE_ERR_INVALID_ENUM;
                }
            }
        } else {
            None
        };

        Some(navigation::PathInfo {
            state: ps,
            length_m: if path_length_m.is_nan() {
                None
            } else {
                Some(path_length_m)
            },
            remaining_m: if path_remaining_m.is_nan() {
                None
            } else {
                Some(path_remaining_m)
            },
            ..Default::default()
        })
    } else {
        None
    };

    let goal = if !goal_x.is_nan() || !goal_y.is_nan() || !goal_orientation_deg.is_nan() {
        Some(navigation::NavigationGoal {
            position: if !goal_x.is_nan() || !goal_y.is_nan() {
                Some(Position2D {
                    x_m: if goal_x.is_nan() { None } else { Some(goal_x) },
                    y_m: if goal_y.is_nan() { None } else { Some(goal_y) },
                })
            } else {
                None
            },
            orientation_deg: if goal_orientation_deg.is_nan() {
                None
            } else {
                Some(goal_orientation_deg)
            },
            ..Default::default()
        })
    } else {
        None
    };

    let nav = NavigationDomain {
        localization,
        path,
        goal,
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.navigation(nav));
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Actuators (Joints)
// =============================================================================

/// Set the actuators domain with joint state data.
///
/// Joint arrays are passed as JSON-encoded arrays (e.g., `["joint1","joint2"]`
/// for names, `[1.0, 2.0]` for values). This simplifies the C interface for
/// variable-length arrays.
///
/// # Parameters
/// - `names_json` — JSON array of joint name strings, e.g. `["joint1","joint2"]`
/// - `positions_json` — JSON array of position values (radians), or null
/// - `velocities_json` — JSON array of velocity values, or null
/// - `efforts_json` — JSON array of effort/torque values, or null
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_actuators_joints(
    builder: *mut PhyTraceBuilderHandle,
    names_json: *const c_char,
    positions_json: *const c_char,
    velocities_json: *const c_char,
    efforts_json: *const c_char,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    // Parse names (required)
    let names_str = match cstr_to_str(names_json) {
        Ok(s) => s,
        Err(code) => {
            set_last_error(if code == PHYTRACE_ERR_NULL_PTR {
                "names_json is null"
            } else {
                "names_json contains invalid UTF-8"
            });
            return code;
        }
    };
    let names: Vec<String> = match serde_json::from_str(names_str) {
        Ok(n) => n,
        Err(e) => {
            set_last_error(format!("Failed to parse names_json: {e}"));
            return PHYTRACE_ERR_SERIALIZATION;
        }
    };

    // Parse optional float arrays
    let positions: Option<Vec<f64>> = parse_optional_json_array(positions_json);
    let velocities: Option<Vec<f64>> = parse_optional_json_array(velocities_json);
    let efforts: Option<Vec<f64>> = parse_optional_json_array(efforts_json);

    // Build joint structs
    let mut joints = Vec::with_capacity(names.len());
    for (i, name) in names.into_iter().enumerate() {
        joints.push(actuators::Joint {
            name: Some(name),
            position: positions.as_ref().and_then(|p| p.get(i).copied()),
            velocity: velocities.as_ref().and_then(|v| v.get(i).copied()),
            effort: efforts.as_ref().and_then(|e| e.get(i).copied()),
            ..Default::default()
        });
    }

    let act = ActuatorsDomain {
        joints: Some(joints),
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.actuators(act));
    PHYTRACE_OK
}

/// Helper to parse an optional JSON array from a C string.
unsafe fn parse_optional_json_array<T: serde::de::DeserializeOwned>(
    ptr: *const c_char,
) -> Option<T> {
    if ptr.is_null() {
        return None;
    }
    let s = match CStr::from_ptr(ptr).to_str() {
        Ok(s) => s,
        Err(_) => return None,
    };
    serde_json::from_str(s).ok()
}

// =============================================================================
// Domain Setters — Operational
// =============================================================================

/// Set the operational domain on the builder.
///
/// Enum parameters use -1 for "not set". String parameters use null.
/// Float parameters use NAN.
///
/// # Parameters
/// - `mode` — `PHYTRACE_OPERATIONAL_MODE_*` constant, or -1
/// - `state` — `PHYTRACE_OPERATIONAL_STATE_*` constant, or -1
/// - `task_id` — Current task ID string, or null
/// - `task_type` — Current task type string, or null
/// - `uptime_sec` — System uptime in seconds, or NAN
/// - `mission_id` — Mission ID string, or null
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_operational(
    builder: *mut PhyTraceBuilderHandle,
    mode: i32,
    state: i32,
    task_id: *const c_char,
    task_type: *const c_char,
    uptime_sec: f64,
    mission_id: *const c_char,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let op_mode = if mode >= 0 {
        match operational_mode_from_i32(mode) {
            Some(m) => Some(m),
            None => {
                set_last_error(format!("Invalid operational mode: {mode}"));
                return PHYTRACE_ERR_INVALID_ENUM;
            }
        }
    } else {
        None
    };

    let op_state = if state >= 0 {
        match operational_state_from_i32(state) {
            Some(s) => Some(s),
            None => {
                set_last_error(format!("Invalid operational state: {state}"));
                return PHYTRACE_ERR_INVALID_ENUM;
            }
        }
    } else {
        None
    };

    let task = {
        let tid = optional_cstr_to_string(task_id);
        let ttype = optional_cstr_to_string(task_type);
        if tid.is_some() || ttype.is_some() {
            Some(operational::Task {
                task_id: tid,
                task_type: ttype,
                ..Default::default()
            })
        } else {
            None
        }
    };

    let ops = OperationalDomain {
        mode: op_mode,
        state: op_state,
        task,
        uptime_sec: if uptime_sec.is_nan() {
            None
        } else {
            Some(uptime_sec)
        },
        mission_id: optional_cstr_to_string(mission_id),
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.operational(ops));
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Identity
// =============================================================================

/// Set the identity domain on the builder.
///
/// String parameters use null for "not set".
///
/// # Parameters
/// - `source_id` — Robot/system identifier, or null (uses config default)
/// - `platform` — Platform name, or null
/// - `model` — Model name, or null
/// - `firmware_version` — Firmware version string, or null
/// - `serial_number` — Serial number, or null
/// - `fleet_id` — Fleet identifier, or null
/// - `site_id` — Site identifier, or null
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_identity(
    builder: *mut PhyTraceBuilderHandle,
    source_id: *const c_char,
    platform: *const c_char,
    model: *const c_char,
    firmware_version: *const c_char,
    serial_number: *const c_char,
    fleet_id: *const c_char,
    site_id: *const c_char,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let ident = IdentityDomain {
        source_id: optional_cstr_to_string(source_id),
        platform: optional_cstr_to_string(platform),
        model: optional_cstr_to_string(model),
        firmware_version: optional_cstr_to_string(firmware_version),
        serial_number: optional_cstr_to_string(serial_number),
        fleet_id: optional_cstr_to_string(fleet_id),
        site_id: optional_cstr_to_string(site_id),
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.identity(ident));
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Communication
// =============================================================================

/// Set the communication domain on the builder.
///
/// This is a simplified interface for the most common communication fields.
/// String parameters use null for "not set". Integer parameters use -1 for "not set".
///
/// # Parameters
/// - `is_connected` — Network connected: 1/0/-1
/// - `signal_strength_dbm` — WiFi/cellular signal strength, or `i32::MIN`
/// - `latency_ms` — Network latency, or NAN
/// - `packet_loss_pct` — Packet loss percentage, or NAN
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_communication(
    builder: *mut PhyTraceBuilderHandle,
    is_connected: i32,
    signal_strength_dbm: i32,
    latency_ms: f64,
    packet_loss_pct: f64,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let network = communication::NetworkInfo {
        is_connected: if is_connected >= 0 {
            Some(is_connected != 0)
        } else {
            None
        },
        signal_strength_dbm: if signal_strength_dbm == i32::MIN {
            None
        } else {
            Some(signal_strength_dbm)
        },
        latency_ms: if latency_ms.is_nan() {
            None
        } else {
            Some(latency_ms)
        },
        packet_loss_pct: if packet_loss_pct.is_nan() {
            None
        } else {
            Some(packet_loss_pct)
        },
        ..Default::default()
    };

    let comm = CommunicationDomain {
        network: Some(network),
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.communication(comm));
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Context
// =============================================================================

/// Set the context domain on the builder.
///
/// String parameters use null for "not set". Integer parameters use -1 for "not set".
///
/// # Parameters
/// - `timezone` — Timezone string (e.g., "America/New_York"), or null
/// - `facility_id` — Facility identifier, or null
/// - `facility_name` — Facility name, or null
/// - `human_count` — Number of humans in area; -1 means not set
/// - `robot_count` — Number of robots in area; -1 means not set
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_context(
    builder: *mut PhyTraceBuilderHandle,
    timezone: *const c_char,
    facility_id: *const c_char,
    facility_name: *const c_char,
    human_count: i32,
    robot_count: i32,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let time = {
        let tz = optional_cstr_to_string(timezone);
        if tz.is_some() {
            Some(context::TimeContext {
                timezone: tz,
                ..Default::default()
            })
        } else {
            None
        }
    };

    let facility = {
        let fid = optional_cstr_to_string(facility_id);
        let fname = optional_cstr_to_string(facility_name);
        if fid.is_some() || fname.is_some() || human_count >= 0 || robot_count >= 0 {
            Some(context::FacilityContext {
                facility_id: fid,
                name: fname,
                human_count: if human_count >= 0 {
                    Some(human_count as u32)
                } else {
                    None
                },
                robot_count: if robot_count >= 0 {
                    Some(robot_count as u32)
                } else {
                    None
                },
                ..Default::default()
            })
        } else {
            None
        }
    };

    let ctx = ContextDomain {
        time,
        facility,
        ..Default::default()
    };

    builder_mutate!(builder, |b| b.context(ctx));
    PHYTRACE_OK
}

// =============================================================================
// Domain Setters — Extensions (raw JSON)
// =============================================================================

/// Set arbitrary extensions on the builder as a JSON string.
///
/// This is used by the ROS2 generic converter to stash raw message payloads.
///
/// # Parameters
/// - `json_str` — JSON object string, e.g. `{"raw_msg": {...}}`
#[no_mangle]
pub unsafe extern "C" fn phytrace_builder_set_extensions_json(
    builder: *mut PhyTraceBuilderHandle,
    json_str: *const c_char,
) -> i32 {
    clear_last_error();
    if builder.is_null() {
        set_last_error("builder handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let s = match cstr_to_str(json_str) {
        Ok(s) => s,
        Err(code) => {
            set_last_error(if code == PHYTRACE_ERR_NULL_PTR {
                "json_str is null"
            } else {
                "json_str contains invalid UTF-8"
            });
            return code;
        }
    };

    let value: serde_json::Value = match serde_json::from_str(s) {
        Ok(v) => v,
        Err(e) => {
            set_last_error(format!("Failed to parse extensions JSON: {e}"));
            return PHYTRACE_ERR_SERIALIZATION;
        }
    };

    builder_mutate!(builder, |b| b.extensions(value));
    PHYTRACE_OK
}

// =============================================================================
// Event Operations
// =============================================================================

/// Send a built event through the agent's transport.
///
/// This consumes the event handle (frees it). On failure, the event is still freed.
///
/// Returns `PHYTRACE_OK` on success, negative error code on failure.
#[no_mangle]
pub unsafe extern "C" fn phytrace_agent_send(
    agent: *mut PhyTraceAgentHandle,
    event: *mut PhyTraceEventHandle,
) -> i32 {
    clear_last_error();

    if agent.is_null() {
        set_last_error("agent handle is null");
        // Still free the event if non-null
        if !event.is_null() {
            drop(Box::from_raw(event));
        }
        return PHYTRACE_ERR_NULL_PTR;
    }

    if event.is_null() {
        set_last_error("event handle is null");
        return PHYTRACE_ERR_NULL_PTR;
    }

    let event_handle = Box::from_raw(event);
    let handle = &*agent;

    match handle
        .runtime
        .block_on(handle.agent.send(event_handle.event))
    {
        Ok(()) => PHYTRACE_OK,
        Err(e) => {
            set_last_error(format!("Send error: {e}"));
            PHYTRACE_ERR_TRANSPORT
        }
    }
}

/// Serialize a built event to JSON.
///
/// Returns a heap-allocated null-terminated JSON string, or null on failure.
/// The returned string must be freed with `phytrace_string_free()`.
#[no_mangle]
pub unsafe extern "C" fn phytrace_event_to_json(event: *const PhyTraceEventHandle) -> *mut c_char {
    clear_last_error();

    if event.is_null() {
        set_last_error("event handle is null");
        return ptr::null_mut();
    }

    match (*event).event.to_json() {
        Ok(json) => match CString::new(json) {
            Ok(cstr) => cstr.into_raw(),
            Err(e) => {
                set_last_error(format!("JSON contains null byte: {e}"));
                ptr::null_mut()
            }
        },
        Err(e) => {
            set_last_error(format!("Serialization error: {e}"));
            ptr::null_mut()
        }
    }
}

/// Destroy a built event without sending it.
///
/// Passing null is a no-op.
#[no_mangle]
pub unsafe extern "C" fn phytrace_event_destroy(event: *mut PhyTraceEventHandle) {
    if !event.is_null() {
        drop(Box::from_raw(event));
    }
}

// =============================================================================
// Unit Tests
// =============================================================================

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

    // =========================================================================
    // Helper to create a mock agent for tests
    // =========================================================================

    fn create_test_agent() -> *mut PhyTraceAgentHandle {
        // Enable dev mode to bypass license validation in tests
        std::env::set_var("PHYWARE_DEV_MODE", "1");
        let source_id = CString::new("test-robot-001").unwrap();
        unsafe { phytrace_agent_create_mock(source_id.as_ptr(), PHYTRACE_SOURCE_TYPE_AMR) }
    }

    fn create_test_builder(agent: *const PhyTraceAgentHandle) -> *mut PhyTraceBuilderHandle {
        unsafe { phytrace_builder_new(agent) }
    }

    // =========================================================================
    // Version
    // =========================================================================

    #[test]
    fn test_sdk_version() {
        let version = phytrace_sdk_version();
        assert!(!version.is_null());
        let s = unsafe { CStr::from_ptr(version) }.to_str().unwrap();
        assert_eq!(s, env!("CARGO_PKG_VERSION"));
    }

    #[test]
    fn test_udm_version() {
        let version = phytrace_udm_version();
        assert!(!version.is_null());
        let s = unsafe { CStr::from_ptr(version) }.to_str().unwrap();
        assert_eq!(s, "0.0.3");
    }

    // =========================================================================
    // Error handling
    // =========================================================================

    #[test]
    fn test_last_error_initially_null() {
        clear_last_error();
        let err = phytrace_last_error();
        assert!(err.is_null());
    }

    #[test]
    fn test_last_error_after_null_ptr() {
        unsafe {
            let result = phytrace_agent_start(ptr::null_mut());
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
            let err = phytrace_last_error();
            assert!(!err.is_null());
            let msg = CStr::from_ptr(err).to_str().unwrap();
            assert!(msg.contains("null"));
        }
    }

    #[test]
    fn test_string_free_null_is_noop() {
        unsafe {
            phytrace_string_free(ptr::null_mut()); // Should not crash
        }
    }

    // =========================================================================
    // Agent lifecycle
    // =========================================================================

    #[test]
    fn test_agent_create_mock() {
        let agent = create_test_agent();
        assert!(!agent.is_null());
        unsafe { phytrace_agent_destroy(agent) };
    }

    #[test]
    fn test_agent_create_mock_null_source_id() {
        unsafe {
            let agent = phytrace_agent_create_mock(ptr::null(), PHYTRACE_SOURCE_TYPE_AMR);
            assert!(agent.is_null());
            let err = phytrace_last_error();
            assert!(!err.is_null());
        }
    }

    #[test]
    fn test_agent_create_mock_invalid_source_type() {
        let sid = CString::new("test").unwrap();
        unsafe {
            let agent = phytrace_agent_create_mock(sid.as_ptr(), 9999);
            assert!(agent.is_null());
            let err = phytrace_last_error();
            assert!(!err.is_null());
            let msg = CStr::from_ptr(err).to_str().unwrap();
            assert!(msg.contains("Invalid source_type"));
        }
    }

    #[test]
    fn test_agent_start_stop() {
        let agent = create_test_agent();
        assert!(!agent.is_null());
        unsafe {
            let result = phytrace_agent_start(agent);
            assert_eq!(result, PHYTRACE_OK);

            assert_eq!(phytrace_agent_is_running(agent), 1);

            let result = phytrace_agent_stop(agent);
            assert_eq!(result, PHYTRACE_OK);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_agent_is_running_null() {
        unsafe {
            let result = phytrace_agent_is_running(ptr::null());
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    #[test]
    fn test_agent_destroy_null_is_noop() {
        unsafe {
            phytrace_agent_destroy(ptr::null_mut()); // Should not crash
        }
    }

    #[test]
    fn test_agent_flush_null() {
        unsafe {
            let result = phytrace_agent_flush(ptr::null_mut());
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    #[test]
    fn test_agent_flush() {
        let agent = create_test_agent();
        unsafe {
            phytrace_agent_start(agent);
            let result = phytrace_agent_flush(agent);
            assert_eq!(result, PHYTRACE_OK);
            phytrace_agent_destroy(agent);
        }
    }

    // =========================================================================
    // Config errors
    // =========================================================================

    #[test]
    fn test_agent_create_from_yaml_null() {
        unsafe {
            let agent = phytrace_agent_create_from_yaml(ptr::null());
            assert!(agent.is_null());
        }
    }

    #[test]
    fn test_agent_create_from_yaml_invalid() {
        let yaml = CString::new("not: {valid: yaml: :::").unwrap();
        unsafe {
            let agent = phytrace_agent_create_from_yaml(yaml.as_ptr());
            assert!(agent.is_null());
            let err = phytrace_last_error();
            assert!(!err.is_null());
        }
    }

    #[test]
    fn test_agent_create_from_file_null() {
        unsafe {
            let agent = phytrace_agent_create_from_file(ptr::null());
            assert!(agent.is_null());
        }
    }

    #[test]
    fn test_agent_create_from_file_nonexistent() {
        let path = CString::new("/nonexistent/path/config.yaml").unwrap();
        unsafe {
            let agent = phytrace_agent_create_from_file(path.as_ptr());
            assert!(agent.is_null());
            let err = phytrace_last_error();
            assert!(!err.is_null());
        }
    }

    // =========================================================================
    // Builder lifecycle
    // =========================================================================

    #[test]
    fn test_builder_new_and_destroy() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        assert!(!builder.is_null());
        unsafe {
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_builder_new_null_agent() {
        unsafe {
            let builder = phytrace_builder_new(ptr::null());
            assert!(builder.is_null());
        }
    }

    #[test]
    fn test_builder_destroy_null_is_noop() {
        unsafe {
            phytrace_builder_destroy(ptr::null_mut()); // Should not crash
        }
    }

    #[test]
    fn test_builder_set_event_type() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result =
                phytrace_builder_set_event_type(builder, PHYTRACE_EVENT_TYPE_TELEMETRY_PERIODIC);
            assert_eq!(result, PHYTRACE_OK);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_builder_set_event_type_invalid() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_event_type(builder, 999);
            assert_eq!(result, PHYTRACE_ERR_INVALID_ENUM);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_builder_set_event_type_null_builder() {
        unsafe {
            let result = phytrace_builder_set_event_type(
                ptr::null_mut(),
                PHYTRACE_EVENT_TYPE_TELEMETRY_PERIODIC,
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    #[test]
    fn test_builder_set_source_type() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_source_type(builder, PHYTRACE_SOURCE_TYPE_DRONE);
            assert_eq!(result, PHYTRACE_OK);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_builder_set_source_type_invalid() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_source_type(builder, -99);
            assert_eq!(result, PHYTRACE_ERR_INVALID_ENUM);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    // =========================================================================
    // Build and verify JSON output
    // =========================================================================

    /// Build an event and return its JSON representation.
    unsafe fn build_and_get_json(builder: *mut PhyTraceBuilderHandle) -> String {
        let event = phytrace_builder_build(builder);
        assert!(
            !event.is_null(),
            "Builder build failed. Error: {:?}",
            CStr::from_ptr(phytrace_last_error()).to_str().ok()
        );
        let json_ptr = phytrace_event_to_json(event);
        assert!(!json_ptr.is_null());
        let json = CStr::from_ptr(json_ptr).to_str().unwrap().to_owned();
        phytrace_string_free(json_ptr);
        phytrace_event_destroy(event);
        json
    }

    #[test]
    fn test_build_unchecked_empty_builder() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            // build_unchecked should always succeed
            let event = phytrace_builder_build_unchecked(builder);
            assert!(!event.is_null());
            phytrace_event_destroy(event);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_build_unchecked_null_builder() {
        unsafe {
            let event = phytrace_builder_build_unchecked(ptr::null_mut());
            assert!(event.is_null());
        }
    }

    // =========================================================================
    // Location domain
    // =========================================================================

    #[test]
    fn test_location_gps() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_location(
                builder,
                41.8781,
                -87.6298, // lat, lon
                f64::NAN, // altitude
                90.0,     // heading
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN, // local coords
                ptr::null(),
                ptr::null(), // frame_id, map_id
                i32::MIN,    // floor
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["location"]["latitude"], 41.8781);
            assert_eq!(v["location"]["longitude"], -87.6298);
            assert_eq!(v["location"]["heading_deg"], 90.0);
            assert!(v["location"]["altitude_m"].is_null());

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_location_local_coords() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let frame = CString::new("odom").unwrap();
            let map = CString::new("warehouse-1").unwrap();
            let result = phytrace_builder_set_location(
                builder,
                f64::NAN,
                f64::NAN,
                f64::NAN, // no GPS
                f64::NAN, // no heading
                10.5,
                20.3,
                0.0,
                45.0, // local x, y, z, yaw
                frame.as_ptr(),
                map.as_ptr(),
                2, // floor
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["location"]["local"]["x_m"], 10.5);
            assert_eq!(v["location"]["local"]["y_m"], 20.3);
            assert_eq!(v["location"]["local"]["z_m"], 0.0);
            assert_eq!(v["location"]["local"]["yaw_deg"], 45.0);
            assert_eq!(v["location"]["frame_id"], "odom");
            assert_eq!(v["location"]["map_id"], "warehouse-1");
            assert_eq!(v["location"]["floor"], 2);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_location_null_builder() {
        unsafe {
            let result = phytrace_builder_set_location(
                ptr::null_mut(),
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                ptr::null(),
                ptr::null(),
                0,
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Motion domain
    // =========================================================================

    #[test]
    fn test_motion_velocity() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_motion(
                builder,
                1.5, // speed
                1.0,
                0.2,
                0.0, // linear velocity
                0.0,
                0.0,
                15.0, // angular velocity (dps)
                f64::NAN,
                f64::NAN,    // no commanded velocity
                ptr::null(), // no frame_id
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["motion"]["speed_mps"], 1.5);
            assert_eq!(v["motion"]["linear_velocity"]["x_mps"], 1.0);
            assert_eq!(v["motion"]["linear_velocity"]["y_mps"], 0.2);
            assert_eq!(v["motion"]["angular_velocity"]["yaw_dps"], 15.0);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_motion_commanded() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_motion(
                builder,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                0.5,
                10.0, // commanded linear, angular
                ptr::null(),
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["motion"]["commanded_linear_mps"], 0.5);
            assert_eq!(v["motion"]["commanded_angular_dps"], 10.0);
            assert!(v["motion"]["linear_velocity"].is_null());

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_motion_null_builder() {
        unsafe {
            let result = phytrace_builder_set_motion(
                ptr::null_mut(),
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                ptr::null(),
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Power domain
    // =========================================================================

    #[test]
    fn test_power_battery() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_power(
                builder, 85.0, // soc
                48.5, // voltage
                -2.1, // current (discharging)
                35.0, // temperature
                0,    // not charging
                98.0, // health
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["power"]["battery"]["state_of_charge_pct"], 85.0);
            assert_eq!(v["power"]["battery"]["voltage_v"], 48.5);
            assert_eq!(v["power"]["battery"]["current_a"], -2.1);
            assert_eq!(v["power"]["battery"]["temperature_c"], 35.0);
            assert_eq!(v["power"]["battery"]["state_of_health_pct"], 98.0);
            assert_eq!(v["power"]["charging"]["is_charging"], false);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_power_charging_not_set() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_power(
                builder,
                50.0,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                -1, // charging not set
                f64::NAN,
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["power"]["battery"]["state_of_charge_pct"], 50.0);
            assert!(v["power"]["charging"].is_null());

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_power_boundary_values() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            // 0% SOC
            let result = phytrace_builder_set_power(
                builder,
                0.0,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                -1,
                f64::NAN,
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["power"]["battery"]["state_of_charge_pct"], 0.0);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_power_null_builder() {
        unsafe {
            let result = phytrace_builder_set_power(ptr::null_mut(), 0.0, 0.0, 0.0, 0.0, 0, 0.0);
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Perception — Lidar
    // =========================================================================

    #[test]
    fn test_perception_lidar() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let sid = CString::new("lidar_front").unwrap();
            let result = phytrace_builder_set_perception_lidar(
                builder,
                sid.as_ptr(),
                360,    // point_count
                0.1,    // min_range
                30.0,   // max_range
                -180.0, // min_angle
                180.0,  // max_angle
                1.0,    // angular_resolution
                0.5,    // closest_range
                45.0,   // closest_angle
                10.0,   // scan_frequency
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["perception"]["lidar"][0]["sensor_id"], "lidar_front");
            assert_eq!(v["perception"]["lidar"][0]["point_count"], 360);
            assert_eq!(v["perception"]["lidar"][0]["min_range_m"], 0.1);
            assert_eq!(v["perception"]["lidar"][0]["max_range_m"], 30.0);
            assert_eq!(v["perception"]["lidar"][0]["closest_range_m"], 0.5);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_perception_lidar_multiple() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let sid1 = CString::new("lidar_front").unwrap();
            let sid2 = CString::new("lidar_rear").unwrap();

            phytrace_builder_set_perception_lidar(
                builder,
                sid1.as_ptr(),
                360,
                0.1,
                30.0,
                -180.0,
                180.0,
                1.0,
                f64::NAN,
                f64::NAN,
                f64::NAN,
            );
            phytrace_builder_set_perception_lidar(
                builder,
                sid2.as_ptr(),
                180,
                0.2,
                15.0,
                -90.0,
                90.0,
                1.0,
                f64::NAN,
                f64::NAN,
                f64::NAN,
            );

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["perception"]["lidar"].as_array().unwrap().len(), 2);
            assert_eq!(v["perception"]["lidar"][0]["sensor_id"], "lidar_front");
            assert_eq!(v["perception"]["lidar"][1]["sensor_id"], "lidar_rear");

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_perception_lidar_null_builder() {
        unsafe {
            let result = phytrace_builder_set_perception_lidar(
                ptr::null_mut(),
                ptr::null(),
                0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Perception — IMU
    // =========================================================================

    #[test]
    fn test_perception_imu() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_perception_imu(
                builder, 0.1, -0.2, 9.81, // accel
                0.5, -0.3, 1.2, // gyro
                25.0, -10.0, 45.0, // mag
                28.5, // temperature
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["perception"]["imu"]["accel_z_mps2"], 9.81);
            assert_eq!(v["perception"]["imu"]["gyro_z_dps"], 1.2);
            assert_eq!(v["perception"]["imu"]["mag_x_ut"], 25.0);
            assert_eq!(v["perception"]["imu"]["temperature_c"], 28.5);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_perception_lidar_then_imu_preserves_both() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let sid = CString::new("lidar0").unwrap();
            phytrace_builder_set_perception_lidar(
                builder,
                sid.as_ptr(),
                100,
                0.1,
                10.0,
                -90.0,
                90.0,
                1.0,
                f64::NAN,
                f64::NAN,
                f64::NAN,
            );
            phytrace_builder_set_perception_imu(
                builder,
                0.0,
                0.0,
                9.81,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
            );

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            // Both lidar and IMU should be present
            assert!(!v["perception"]["lidar"].is_null());
            assert!(!v["perception"]["imu"].is_null());
            assert_eq!(v["perception"]["lidar"][0]["sensor_id"], "lidar0");
            assert_eq!(v["perception"]["imu"]["accel_z_mps2"], 9.81);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_perception_imu_null_builder() {
        unsafe {
            let result = phytrace_builder_set_perception_imu(
                ptr::null_mut(),
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Safety domain
    // =========================================================================

    #[test]
    fn test_safety() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_safety(
                builder,
                PHYTRACE_SAFETY_STATE_WARNING,
                1, // is_safe = true
                0, // estop not active
                PHYTRACE_ESTOP_TYPE_SOFTWARE,
                1.0, // speed limit
                2.5, // closest distance
                3.0, // closest human
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["safety"]["safety_state"], "warning");
            assert_eq!(v["safety"]["is_safe"], true);
            assert_eq!(v["safety"]["e_stop"]["is_active"], false);
            assert_eq!(v["safety"]["speed_limit_mps"], 1.0);
            assert_eq!(v["safety"]["proximity"]["closest_distance_m"], 2.5);
            assert_eq!(v["safety"]["proximity"]["closest_human_m"], 3.0);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_safety_estop_active() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_safety(
                builder,
                PHYTRACE_SAFETY_STATE_EMERGENCY_STOP,
                0, // not safe
                1, // estop active
                PHYTRACE_ESTOP_TYPE_HARDWARE,
                0.0, // speed limit 0
                f64::NAN,
                f64::NAN,
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["safety"]["safety_state"], "emergency_stop");
            assert_eq!(v["safety"]["e_stop"]["is_active"], true);
            assert_eq!(v["safety"]["e_stop"]["e_stop_type"], "hardware");

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_safety_invalid_enum() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result =
                phytrace_builder_set_safety(builder, 99, -1, -1, -1, f64::NAN, f64::NAN, f64::NAN);
            assert_eq!(result, PHYTRACE_ERR_INVALID_ENUM);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_safety_null_builder() {
        unsafe {
            let result = phytrace_builder_set_safety(ptr::null_mut(), 0, 0, 0, 0, 0.0, 0.0, 0.0);
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Navigation domain
    // =========================================================================

    #[test]
    fn test_navigation() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_navigation(
                builder,
                PHYTRACE_LOCALIZATION_QUALITY_GOOD,
                0.95, // confidence
                1,    // is_localized
                PHYTRACE_PATH_STATE_EXECUTING,
                25.0, // path length
                10.0, // remaining
                50.0,
                30.0, // goal x, y
                90.0, // goal orientation
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["navigation"]["localization"]["quality"], "good");
            assert_eq!(v["navigation"]["localization"]["confidence"], 0.95);
            assert_eq!(v["navigation"]["localization"]["is_localized"], true);
            assert_eq!(v["navigation"]["path"]["state"], "executing");
            assert_eq!(v["navigation"]["path"]["length_m"], 25.0);
            assert_eq!(v["navigation"]["goal"]["position"]["x_m"], 50.0);
            assert_eq!(v["navigation"]["goal"]["orientation_deg"], 90.0);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_navigation_minimal() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_navigation(
                builder,
                -1,       // no quality
                f64::NAN, // no confidence
                -1,       // no localized flag
                PHYTRACE_PATH_STATE_VALID,
                15.0,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert!(v["navigation"]["localization"].is_null());
            assert_eq!(v["navigation"]["path"]["state"], "valid");

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_navigation_invalid_enum() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_navigation(
                builder,
                99,
                f64::NAN,
                -1,
                -1,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                f64::NAN,
            );
            assert_eq!(result, PHYTRACE_ERR_INVALID_ENUM);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_navigation_null_builder() {
        unsafe {
            let result = phytrace_builder_set_navigation(
                ptr::null_mut(),
                0,
                0.0,
                0,
                0,
                0.0,
                0.0,
                0.0,
                0.0,
                0.0,
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Actuators domain (joints)
    // =========================================================================

    #[test]
    fn test_actuators_joints() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let names = CString::new(r#"["wheel_fl","wheel_fr","wheel_rl","wheel_rr"]"#).unwrap();
            let positions = CString::new("[0.0, 1.57, 3.14, 4.71]").unwrap();
            let velocities = CString::new("[10.0, 10.5, 9.8, 10.2]").unwrap();
            let efforts = CString::new("[5.0, 5.1, 4.9, 5.0]").unwrap();

            let result = phytrace_builder_set_actuators_joints(
                builder,
                names.as_ptr(),
                positions.as_ptr(),
                velocities.as_ptr(),
                efforts.as_ptr(),
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            let joints = v["actuators"]["joints"].as_array().unwrap();
            assert_eq!(joints.len(), 4);
            assert_eq!(joints[0]["name"], "wheel_fl");
            assert_eq!(joints[0]["position"], 0.0);
            assert_eq!(joints[1]["velocity"], 10.5);
            assert_eq!(joints[3]["effort"], 5.0);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_actuators_joints_names_only() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let names = CString::new(r#"["j1","j2"]"#).unwrap();

            let result = phytrace_builder_set_actuators_joints(
                builder,
                names.as_ptr(),
                ptr::null(), // no positions
                ptr::null(), // no velocities
                ptr::null(), // no efforts
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            let joints = v["actuators"]["joints"].as_array().unwrap();
            assert_eq!(joints.len(), 2);
            assert_eq!(joints[0]["name"], "j1");
            // Position should not be present
            assert!(joints[0]["position"].is_null());

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_actuators_joints_null_names() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_actuators_joints(
                builder,
                ptr::null(), // null names — error
                ptr::null(),
                ptr::null(),
                ptr::null(),
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_actuators_joints_invalid_json() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let bad_names = CString::new("not valid json").unwrap();
            let result = phytrace_builder_set_actuators_joints(
                builder,
                bad_names.as_ptr(),
                ptr::null(),
                ptr::null(),
                ptr::null(),
            );
            assert_eq!(result, PHYTRACE_ERR_SERIALIZATION);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_actuators_joints_null_builder() {
        unsafe {
            let names = CString::new(r#"["j1"]"#).unwrap();
            let result = phytrace_builder_set_actuators_joints(
                ptr::null_mut(),
                names.as_ptr(),
                ptr::null(),
                ptr::null(),
                ptr::null(),
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Operational domain
    // =========================================================================

    #[test]
    fn test_operational() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let tid = CString::new("task-123").unwrap();
            let ttype = CString::new("delivery").unwrap();
            let mid = CString::new("mission-456").unwrap();

            let result = phytrace_builder_set_operational(
                builder,
                PHYTRACE_OPERATIONAL_MODE_AUTONOMOUS,
                PHYTRACE_OPERATIONAL_STATE_NAVIGATING,
                tid.as_ptr(),
                ttype.as_ptr(),
                3600.0, // uptime
                mid.as_ptr(),
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["operational"]["mode"], "autonomous");
            assert_eq!(v["operational"]["state"], "navigating");
            assert_eq!(v["operational"]["task"]["task_id"], "task-123");
            assert_eq!(v["operational"]["task"]["task_type"], "delivery");
            assert_eq!(v["operational"]["uptime_sec"], 3600.0);
            assert_eq!(v["operational"]["mission_id"], "mission-456");

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_operational_invalid_enum() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_operational(
                builder,
                99,
                -1,
                ptr::null(),
                ptr::null(),
                f64::NAN,
                ptr::null(),
            );
            assert_eq!(result, PHYTRACE_ERR_INVALID_ENUM);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_operational_null_builder() {
        unsafe {
            let result = phytrace_builder_set_operational(
                ptr::null_mut(),
                0,
                0,
                ptr::null(),
                ptr::null(),
                0.0,
                ptr::null(),
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Identity domain
    // =========================================================================

    #[test]
    fn test_identity() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let sid = CString::new("robot-42").unwrap();
            let platform = CString::new("TurtleBot4").unwrap();
            let model = CString::new("TB4-Standard").unwrap();
            let firmware = CString::new("1.2.3").unwrap();
            let serial = CString::new("SN-00042").unwrap();
            let fleet = CString::new("fleet-alpha").unwrap();
            let site = CString::new("warehouse-nyc").unwrap();

            let result = phytrace_builder_set_identity(
                builder,
                sid.as_ptr(),
                platform.as_ptr(),
                model.as_ptr(),
                firmware.as_ptr(),
                serial.as_ptr(),
                fleet.as_ptr(),
                site.as_ptr(),
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["identity"]["source_id"], "robot-42");
            assert_eq!(v["identity"]["platform"], "TurtleBot4");
            assert_eq!(v["identity"]["model"], "TB4-Standard");
            assert_eq!(v["identity"]["firmware_version"], "1.2.3");
            assert_eq!(v["identity"]["serial_number"], "SN-00042");
            assert_eq!(v["identity"]["fleet_id"], "fleet-alpha");
            assert_eq!(v["identity"]["site_id"], "warehouse-nyc");

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_identity_null_builder() {
        unsafe {
            let result = phytrace_builder_set_identity(
                ptr::null_mut(),
                ptr::null(),
                ptr::null(),
                ptr::null(),
                ptr::null(),
                ptr::null(),
                ptr::null(),
                ptr::null(),
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Communication domain
    // =========================================================================

    #[test]
    fn test_communication() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_communication(builder, 1, -65, 12.5, 0.1);
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["communication"]["network"]["is_connected"], true);
            assert_eq!(v["communication"]["network"]["signal_strength_dbm"], -65);
            assert_eq!(v["communication"]["network"]["latency_ms"], 12.5);
            assert_eq!(v["communication"]["network"]["packet_loss_pct"], 0.1);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_communication_null_builder() {
        unsafe {
            let result = phytrace_builder_set_communication(ptr::null_mut(), 0, 0, 0.0, 0.0);
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Context domain
    // =========================================================================

    #[test]
    fn test_context() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let tz = CString::new("America/New_York").unwrap();
            let fid = CString::new("site-001").unwrap();
            let fname = CString::new("NYC Warehouse").unwrap();

            let result = phytrace_builder_set_context(
                builder,
                tz.as_ptr(),
                fid.as_ptr(),
                fname.as_ptr(),
                5,
                3,
            );
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["context"]["time"]["timezone"], "America/New_York");
            assert_eq!(v["context"]["facility"]["facility_id"], "site-001");
            assert_eq!(v["context"]["facility"]["name"], "NYC Warehouse");
            assert_eq!(v["context"]["facility"]["human_count"], 5);
            assert_eq!(v["context"]["facility"]["robot_count"], 3);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_context_null_builder() {
        unsafe {
            let result = phytrace_builder_set_context(
                ptr::null_mut(),
                ptr::null(),
                ptr::null(),
                ptr::null(),
                0,
                0,
            );
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Extensions (raw JSON)
    // =========================================================================

    #[test]
    fn test_extensions_json() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let json_str =
                CString::new(r#"{"raw_msg":{"topic":"/custom","data":[1,2,3]}}"#).unwrap();
            let result = phytrace_builder_set_extensions_json(builder, json_str.as_ptr());
            assert_eq!(result, PHYTRACE_OK);

            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();
            assert_eq!(v["extensions"]["raw_msg"]["topic"], "/custom");
            assert_eq!(v["extensions"]["raw_msg"]["data"][0], 1);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_extensions_json_invalid() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let bad = CString::new("not json").unwrap();
            let result = phytrace_builder_set_extensions_json(builder, bad.as_ptr());
            assert_eq!(result, PHYTRACE_ERR_SERIALIZATION);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_extensions_json_null() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            let result = phytrace_builder_set_extensions_json(builder, ptr::null());
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
            phytrace_builder_destroy(builder);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_extensions_json_null_builder() {
        unsafe {
            let s = CString::new("{}").unwrap();
            let result = phytrace_builder_set_extensions_json(ptr::null_mut(), s.as_ptr());
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
        }
    }

    // =========================================================================
    // Event operations
    // =========================================================================

    #[test]
    fn test_event_to_json() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            phytrace_builder_set_power(builder, 75.0, f64::NAN, f64::NAN, f64::NAN, -1, f64::NAN);
            let event = phytrace_builder_build(builder);
            assert!(!event.is_null());

            let json_ptr = phytrace_event_to_json(event);
            assert!(!json_ptr.is_null());

            let json = CStr::from_ptr(json_ptr).to_str().unwrap();
            assert!(json.contains("state_of_charge_pct"));
            assert!(json.contains("75"));

            phytrace_string_free(json_ptr);
            phytrace_event_destroy(event);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_event_to_json_null() {
        unsafe {
            let json = phytrace_event_to_json(ptr::null());
            assert!(json.is_null());
        }
    }

    #[test]
    fn test_event_destroy_null_is_noop() {
        unsafe {
            phytrace_event_destroy(ptr::null_mut()); // Should not crash
        }
    }

    // =========================================================================
    // Send flow
    // =========================================================================

    #[test]
    fn test_send_event() {
        let agent = create_test_agent();
        unsafe {
            phytrace_agent_start(agent);

            let builder = create_test_builder(agent);
            phytrace_builder_set_power(builder, 80.0, f64::NAN, f64::NAN, f64::NAN, -1, f64::NAN);
            let event = phytrace_builder_build(builder);
            assert!(!event.is_null());

            let result = phytrace_agent_send(agent, event);
            assert_eq!(result, PHYTRACE_OK);

            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_send_null_event() {
        let agent = create_test_agent();
        unsafe {
            let result = phytrace_agent_send(agent, ptr::null_mut());
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);
            phytrace_agent_destroy(agent);
        }
    }

    #[test]
    fn test_send_null_agent() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            phytrace_builder_set_power(builder, 50.0, f64::NAN, f64::NAN, f64::NAN, -1, f64::NAN);
            let event = phytrace_builder_build(builder);
            assert!(!event.is_null());

            // Send with null agent — event should still be freed
            let result = phytrace_agent_send(ptr::null_mut(), event);
            assert_eq!(result, PHYTRACE_ERR_NULL_PTR);

            phytrace_agent_destroy(agent);
        }
    }

    // =========================================================================
    // Full multi-domain event
    // =========================================================================

    #[test]
    fn test_full_multi_domain_event() {
        let agent = create_test_agent();
        let builder = create_test_builder(agent);
        unsafe {
            // Set event type
            phytrace_builder_set_event_type(builder, PHYTRACE_EVENT_TYPE_TELEMETRY_PERIODIC);

            // Location (odom)
            let frame = CString::new("odom").unwrap();
            phytrace_builder_set_location(
                builder,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                45.0,
                10.0,
                20.0,
                0.0,
                45.0,
                frame.as_ptr(),
                ptr::null(),
                i32::MIN,
            );

            // Motion (odom twist)
            phytrace_builder_set_motion(
                builder,
                1.2,
                1.0,
                0.1,
                0.0,
                0.0,
                0.0,
                5.0,
                f64::NAN,
                f64::NAN,
                ptr::null(),
            );

            // Power (battery_state)
            phytrace_builder_set_power(builder, 72.0, 48.0, -1.5, 30.0, 0, 95.0);

            // Lidar (scan)
            let lid = CString::new("rplidar").unwrap();
            phytrace_builder_set_perception_lidar(
                builder,
                lid.as_ptr(),
                720,
                0.15,
                12.0,
                -180.0,
                180.0,
                0.5,
                0.8,
                -30.0,
                10.0,
            );

            // IMU
            phytrace_builder_set_perception_imu(
                builder,
                0.01,
                -0.02,
                9.81,
                0.5,
                -0.1,
                0.2,
                f64::NAN,
                f64::NAN,
                f64::NAN,
                32.0,
            );

            // Safety
            phytrace_builder_set_safety(
                builder,
                PHYTRACE_SAFETY_STATE_NORMAL,
                1,
                0,
                -1,
                f64::NAN,
                3.5,
                f64::NAN,
            );

            // Navigation
            phytrace_builder_set_navigation(
                builder,
                PHYTRACE_LOCALIZATION_QUALITY_EXCELLENT,
                0.99,
                1,
                PHYTRACE_PATH_STATE_EXECUTING,
                50.0,
                35.0,
                100.0,
                50.0,
                0.0,
            );

            // Joints
            let names = CString::new(r#"["wheel_l","wheel_r"]"#).unwrap();
            let pos = CString::new("[0.0, 0.0]").unwrap();
            let vel = CString::new("[15.0, 14.8]").unwrap();
            phytrace_builder_set_actuators_joints(
                builder,
                names.as_ptr(),
                pos.as_ptr(),
                vel.as_ptr(),
                ptr::null(),
            );

            // Operational
            let tid = CString::new("delivery-789").unwrap();
            let ttype = CString::new("delivery").unwrap();
            phytrace_builder_set_operational(
                builder,
                PHYTRACE_OPERATIONAL_MODE_AUTONOMOUS,
                PHYTRACE_OPERATIONAL_STATE_NAVIGATING,
                tid.as_ptr(),
                ttype.as_ptr(),
                7200.0,
                ptr::null(),
            );

            // Build and verify
            let json = build_and_get_json(builder);
            let v: serde_json::Value = serde_json::from_str(&json).unwrap();

            // Verify all domains present
            assert_eq!(v["event_type"], "telemetry_periodic");
            assert!(!v["location"].is_null());
            assert!(!v["motion"].is_null());
            assert!(!v["power"].is_null());
            assert!(!v["perception"].is_null());
            assert!(!v["safety"].is_null());
            assert!(!v["navigation"].is_null());
            assert!(!v["actuators"].is_null());
            assert!(!v["operational"].is_null());

            // Spot-check key values
            assert_eq!(v["location"]["local"]["x_m"], 10.0);
            assert_eq!(v["motion"]["speed_mps"], 1.2);
            assert_eq!(v["power"]["battery"]["state_of_charge_pct"], 72.0);
            assert_eq!(v["perception"]["lidar"][0]["point_count"], 720);
            assert_eq!(v["perception"]["imu"]["accel_z_mps2"], 9.81);
            assert_eq!(v["safety"]["safety_state"], "normal");
            assert_eq!(v["navigation"]["localization"]["quality"], "excellent");
            assert_eq!(v["actuators"]["joints"].as_array().unwrap().len(), 2);
            assert_eq!(v["operational"]["state"], "navigating");

            phytrace_agent_destroy(agent);
        }
    }

    // =========================================================================
    // Enum conversion coverage
    // =========================================================================

    #[test]
    fn test_all_event_types() {
        for i in 0..=17 {
            assert!(
                event_type_from_i32(i).is_some(),
                "EventType {i} should be valid"
            );
        }
        assert!(event_type_from_i32(18).is_none());
        assert!(event_type_from_i32(-1).is_none());
    }

    #[test]
    fn test_all_source_types() {
        for i in 0..=17 {
            assert!(
                source_type_from_i32(i).is_some(),
                "SourceType {i} should be valid"
            );
        }
        assert!(source_type_from_i32(18).is_none());
        assert!(source_type_from_i32(-1).is_none());
    }

    #[test]
    fn test_all_safety_states() {
        for i in 0..=5 {
            assert!(
                safety_state_from_i32(i).is_some(),
                "SafetyState {i} should be valid"
            );
        }
        assert!(safety_state_from_i32(6).is_none());
    }

    #[test]
    fn test_all_operational_modes() {
        for i in 0..=7 {
            assert!(
                operational_mode_from_i32(i).is_some(),
                "OpMode {i} should be valid"
            );
        }
        assert!(operational_mode_from_i32(8).is_none());
    }

    #[test]
    fn test_all_operational_states() {
        for i in 0..=11 {
            assert!(
                operational_state_from_i32(i).is_some(),
                "OpState {i} should be valid"
            );
        }
        assert!(operational_state_from_i32(12).is_none());
    }

    #[test]
    fn test_all_localization_qualities() {
        for i in 0..=4 {
            assert!(
                localization_quality_from_i32(i).is_some(),
                "LocQuality {i} should be valid"
            );
        }
        assert!(localization_quality_from_i32(5).is_none());
    }

    #[test]
    fn test_all_path_states() {
        for i in 0..=6 {
            assert!(
                path_state_from_i32(i).is_some(),
                "PathState {i} should be valid"
            );
        }
        assert!(path_state_from_i32(7).is_none());
    }

    #[test]
    fn test_all_estop_types() {
        for i in 0..=3 {
            assert!(
                estop_type_from_i32(i).is_some(),
                "EStopType {i} should be valid"
            );
        }
        assert!(estop_type_from_i32(4).is_none());
    }
}