phoxal_api/

lib.rs

//! The single API layer (D60/D61/D1).
//!
//! This crate is the versioned API contract tree. It depends only on the
//! [`phoxal-bus`](phoxal_bus) ABI floor (the contract primitive traits and the
//! typed-topic builders) and the [`phoxal-macros`](phoxal_macros) proc-macros; it
//! does **not** depend on the `phoxal` engine. A participant depends on both crates
//! and imports the API tree directly with `use phoxal_api::v1 as api;`, so
//! `phoxal_api::v1`, `phoxal_api::ApiVersion`, and `phoxal_api::ContractBody`
//! are the canonical paths.
//!
//! # Stable and preview API versions
//!
//! An API version is a conventional `vN` module generated by
//! [`phoxal_api_tree!`]. Each version module carries:
//!
//! - a zero-variant marker `enum Api {}` implementing [`ApiVersion`], whose
//!   [`ApiVersion::ID`] is the module name (`"v1"` or `"v2"`);
//! - the version-local wire bodies, one `pub mod` per contract node holding plain
//!   serde structs/enums and their [`ContractBody`] impls;
//! - an api-local `topic` builder rooted at `topic::new()`.
//!
//! `v1` is frozen. `v2` is the single evolving preview surface: new and changed
//! contracts are edited in that module until the complete API is ready to
//! freeze. Preview work does not mint a new public version for each change.
//! `v2` is authored as `preview version v2 { … }` and is available when the
//! `preview-v2` Cargo feature is enabled. [`ApiVersion::IS_PREVIEW`] records the
//! lifecycle without changing topics or wire bytes. Once `v2` is promoted it
//! becomes immutable; later breaking work starts in a new preview `v3`.
//!
//! [`Api`]: v1::Api
//!
//! # Per-field versions and per-contract identity
//!
//! A participant declares its bus surface with a companion
//! `#[derive(phoxal::Api)]` handle struct.
//! Each handle field names its own version-qualified contract type, so one
//! participant may freely mix fields from modules such as `v1` and
//! `v2`.
//! The derive records each field's resolved [`ContractBody::VERSION`] and
//! [`ContractBody::CONTRACT`] in the participant's embedded metadata and does
//! not declare a participant-wide API version.
//! Across the graph, compatibility is **name identity** (D1) - two participants
//! interoperate on a contract iff they use the exact same version-qualified name
//! (`v1::drive::Target`), which is real on the wire because the version
//! is folded into the key ([`ContractBody::TOPIC`]). There is no `schema_id`: a
//! stable contract type is immutable, so the name alone is the whole identity.
//!
//! # Plain serde wire bodies, provenance in metadata
//!
//! A wire body is just its serde encoding - there is no `{"v":…}` envelope or any
//! other version tag inside the payload (D62). Identity lives entirely in the
//! Zenoh key (the version-qualified [`ContractBody::TOPIC`]); the bus metadata
//! alongside the encoded body carries only provenance (source + logical time) and
//! the codec that produced the bytes - never schema/family/version. Keeping
//! identity out of both the payload and the metadata means the body bytes for an
//! unchanged contract are identical across codecs, and a receiver's per-key
//! subscription is the whole fast-reject.
//!
//! # Topic
//!
//! [`ContractBody::TOPIC`] is derived from the contract node's path in the tree,
//! never written by hand: the version, then the `/`-joined node path plus the
//! topic leaf, with each dynamic node contributing a `{var}` placeholder, e.g.
//! `v1/component/{instance}/motor/{capability}/command`. A fully static path
//! has a literal key (`v1/drive/state`). Folding the version into the key
//! (D1) is what makes two differently-versioned contracts physically distinct
//! Zenoh keys - they cannot collide, so there is no `SCHEMA_ID`/`FAMILY` needed to
//! disambiguate them.
//!
//! # The api-local topic builder
//!
//! Each version module exposes a `topic` builder that mirrors the node tree:
//! `api::topic::new()` returns a root, one method per top-level node walks down the
//! tree, a dynamic node's method takes its variable as `impl Display`, and a leaf
//! method binds the topic's side-branded kind to its version-local body. For
//! example `api::topic::new().drive().state()` yields a
//! `Topic<Subscribe<drive::State>>` (the CLIENT observes the owner's `state`) over
//! the version-qualified key `v1/drive/state`, and
//! `api::topic::new().component("base").motor("left").command()` fills the dynamic
//! segments to produce `v1/component/base/motor/left/command`. Because the
//! builder is generated from the same tree as `TOPIC`, the built key and the
//! documented key stay in lockstep.
//!
//! ## Owner side: `topic::internal`
//!
//! The PUBLIC `topic::new()...` chain above is the **client** side. The matching
//! **owner** side lives at `api::topic::internal::new(cap)...` (L1 + L2, plan #00):
//! the same node tree and keys, but the leaf brands flip so the owner gets the side
//! it must take - `api::topic::internal::new(cap).drive().state()` is
//! `Topic<Publish<drive::State>>` (the owner publishes its telemetry), and
//! `api::topic::internal::new(cap).drive().target()` is `Topic<Subscribe<drive::Target>>`
//! (the owner reads its command input). A query owner reaches its `ServeQuery`
//! brand the same way. The `internal` chain is the deliberate, greppable owner
//! opt-in; a participant acquires the topics of its OWN node through it and everything
//! it consumes through the public chain.
//!
//! The `internal::new` entry requires the runner-minted owner capability
//! ([`OwnerCap`](phoxal_bus::OwnerCap), Layer 2): a participant obtains it from
//! `phoxal::SetupContext::owner_capability()` and passes it in. On the documented
//! surface, owning a topic therefore cannot happen by accident - only with a
//! capability the runner mints.

use phoxal_macros::phoxal_api_tree;

/// The contract primitive traits, re-exported from the `phoxal-bus` crate (the
/// ABI floor) so they stay addressable at `phoxal_api::ApiVersion` /
/// `phoxal_api::ContractBody`.
///
/// - [`ApiVersion`] is the marker trait identifying one API version (D60),
///   implemented only by the zero-variant `enum Api {}` that [`phoxal_api_tree!`]
///   generates inside each version module; its `ID` is the module name (`"v1"`).
///   Its `IS_PREVIEW` const is lifecycle metadata only.
/// - [`ContractBody`] is a version-local wire body (D61): a plain serde type
///   bound to exactly one [`ApiVersion`] and one contract topic. Every body
///   declared inside a [`phoxal_api_tree!`] node gets a generated impl; handles,
///   `SetupContext` builders, and the `Service`/`Driver` derive assertions key
///   off its `Api`/`TOPIC`. `TOPIC` is version-qualified (D1) and *is* the
///   compatibility key - there is no `SCHEMA_ID`/`FAMILY`; its serde encoding
///   *is* the wire payload, with no version envelope (D62).
pub use phoxal_bus::{ApiVersion, ContractBody};

phoxal_api_tree! {
    version v1 {
        drive {
            /// Why actuation authority is in its current state.
            enum StopReason {
                NoTarget,
                EmergencyStop,
                Fault,
            }

            /// Whether the drive is actively commanding the actuators.
            enum ActuatorAuthority {
                Active,
                Stopped,
            }

            /// A requested or limited planar velocity.
            struct Target {
                linear_x_mps: f32,
                angular_z_radps: f32,
                curvature_limit_radpm: Option<f32>,
            }

            /// The drive participant's published control state.
            struct State {
                target: Target,
                limited_target: Target,
                actuator_authority: ActuatorAuthority,
                stop_reason: Option<StopReason>,
            }

            topic target: command Target;
            topic state: state State;
        }

        safety {
            /// Safety participant decision for a candidate motion command.
            #[derive(Copy, Eq)]
            enum SafetyDecision {
                Allow,
                Slow,
                Stop,
                EmergencyStop,
                UnknownConservative,
            }

            /// An inclusive `[min, max]` bound on a scalar control axis.
            struct Constraint {
                min: f64,
                max: f64,
            }

            /// Per-axis velocity bounds the safety participant will allow.
            struct MotionConstraint {
                linear_x_mps: Constraint,
                angular_z_radps: Constraint,
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum SafetyReasonCode {
                ObstacleDetected,
                BatteryLow,
                BatteryCritical,
                DriveFault,
                LocalizationLost,
                SourceStale,
                EmergencyStopEngaged,
                Unknown,
            }

            /// A coded reason behind a safety decision, with optional detail text.
            struct SafetyReason {
                code: SafetyReasonCode,
                detail: Option<String>,
            }

            /// Revisions of the inputs a safety decision was computed against.
            struct SafetySourceRevision {
                localization: Option<u64>,
                map: Option<u64>,
            }

            /// The safety participant's authorization for downstream motion: the
            /// decision, the motion it approves, why, and when it expires.
            struct SafetyAuthorization {
                decision: SafetyDecision,
                approved_motion: MotionConstraint,
                reasons: Vec<SafetyReason>,
                source_revision: SafetySourceRevision,
                expires_at_ns: Option<u64>,
            }

            /// The safety participant's published status: current decision + reasons.
            struct Status {
                decision: SafetyDecision,
                active_reasons: Vec<SafetyReason>,
            }

            /// A request to engage or release the emergency stop.
            #[derive(Eq)]
            struct EmergencyStopRequest {
                engaged: bool,
            }

            topic authorization: state SafetyAuthorization;
            topic state: state Status;
            topic estop: command EmergencyStopRequest;
        }

        mission {
            /// A target pose in the map frame (yaw optional).
            struct Goal {
                x_m: f64,
                y_m: f64,
                yaw_rad: Option<f64>,
            }

            /// A command driving the mission lifecycle.
            enum Command {
                Start(Goal),
                Pause,
                Resume,
                Cancel,
            }

            /// Where the mission is in its lifecycle.
            #[derive(Copy, Eq)]
            enum Phase {
                Idle,
                Active,
                Paused,
                Succeeded,
                Failed,
            }

            /// The mission participant's published state.
            struct State {
                phase: Phase,
                goal: Option<Goal>,
                detail: Option<String>,
            }

            topic command: command Command;
            topic goal: state Goal;
            topic state: state State;
        }

        joint(joint) {
            /// Per-joint position/velocity (and optional effort) on a dynamic
            /// per-joint key.
            struct JointState {
                position_rad: f64,
                velocity_radps: f64,
                effort_nm: Option<f64>,
            }

            topic state: state JointState;
        }

        frame {
            /// A parent → child rigid transform (translation + xyzw quaternion).
            struct FrameTransform {
                parent_frame_id: String,
                child_frame_id: String,
                translation_m: [f64; 3],
                rotation_quat_xyzw: [f64; 4],
                stamp_ns: Option<u64>,
            }

            /// Transforms that do not change over time.
            struct StaticTransforms {
                transforms: Vec<FrameTransform>,
            }

            /// The current transform tree.
            struct Tree {
                transforms: Vec<FrameTransform>,
            }

            /// Ask for the transform between two frames, optionally at a time.
            struct LookupRequest {
                target_frame_id: String,
                source_frame_id: String,
                at_ns: Option<u64>,
            }

            /// The resolved transform, or `None` if it is not available.
            struct LookupResponse {
                transform: Option<FrameTransform>,
            }

            topic tree: state Tree;
            topic static_transforms: state StaticTransforms;
            topic lookup: query LookupRequest => LookupResponse;
        }

        power {
            /// A platform power command.
            #[derive(Copy, Eq)]
            enum Command {
                Reboot,
                Shutdown,
            }

            /// Where the power participant is in handling a command.
            #[derive(Copy, Eq)]
            enum Status {
                Idle,
                Rebooting,
                ShuttingDown,
                Failed,
            }

            /// Why a power command was rejected outright.
            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum RejectedReason {
                SupervisorUnavailable,
                SupervisorReturnedHttp,
            }

            /// Why an accepted power command later failed.
            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum FailedReason {
                SupervisorTransport,
            }

            /// The power participant's published state.
            struct State {
                status: Status,
                detail: Option<String>,
            }

            topic command: command Command;
            topic state: state State;
        }

        motion {
            /// A planar velocity the motion arbiter may select.
            struct Target {
                linear_x_mps: f32,
                angular_z_radps: f32,
                curvature_limit_radpm: Option<f32>,
            }

            /// The motion arbiter's local view of the active safety decision.
            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum SafetyDecision {
                Allow,
                Slow,
                Stop,
                EmergencyStop,
                UnknownConservative,
            }

            /// Which input the motion arbiter is currently following.
            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum MotionSource {
                Manual,
                Follow,
                MissionStop,
                Recovery,
                EmergencyStop,
            }

            /// Why the motion arbiter chose its current source/target.
            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum MotionReason {
                SafetyEmergencyStop,
                ManualEscapeUnderStop,
                SafetyConstrained(SafetyDecision),
                NoFollowTarget,
                FollowTargetStale,
                SafetyAuthorizationUnavailable,
            }

            /// A direct teleop velocity command.
            struct ManualCommand {
                linear_x_mps: f64,
                angular_z_radps: f64,
            }

            /// The motion arbiter's published state.
            struct State {
                active_source: Option<MotionSource>,
                selected: Option<Target>,
                reason: Option<MotionReason>,
            }

            topic manual: command ManualCommand;
            topic state: state State;
        }

        logs(participant_id) {
            /// Wall-clock timestamp carried by a structured bus log event.
            struct Timestamp {
                unix_seconds: i64,
                nanos: u32,
            }

            /// The severity level of a structured bus log event.
            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum Level {
                Error,
                Warn,
                Info,
                Debug,
                Trace,
            }

            /// A scalar tracing field value captured from a log event.
            #[serde(untagged)]
            enum LogValue {
                Bool(bool),
                I64(i64),
                U64(u64),
                F64(f64),
                String(String),
            }

            /// One structured runner log event published out-of-band.
            struct Event {
                seq: u64,
                time: Timestamp,
                level: Level,
                target: String,
                message: String,
                fields: ::std::collections::BTreeMap<String, LogValue>,
                dropped: u32,
            }

            topic self: state Event;
        }

        bus {
            uplink {
                /// Observable state of the router's optional upstream connection.
                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum UplinkPhase {
                    Disabled,
                    Connecting,
                    Connected,
                    Retrying,
                }

                /// Router-owned out-of-band state for the optional site uplink.
                struct State {
                    phase: UplinkPhase,
                    connect: Option<String>,
                    retry_attempt: u32,
                    detail: Option<String>,
                }

                topic state: state State;
            }
        }

        plan {
            /// One pose along a planned path.
            struct PathPose {
                x_m: f64,
                y_m: f64,
                yaw_rad: Option<f64>,
            }

            /// A planned path, tagged with the map revision it was built on.
            struct Path {
                poses: Vec<PathPose>,
                map_revision: Option<u64>,
            }

            /// Why the planner declined to produce a path.
            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum Refusal {
                MissionInactive,
                NoGoal,
                NoMap,
                NoLocalization,
                Unreachable,
                NonPlanarGoalUnsupported,
                LocalizationInitializing,
                LocalizationLost,
                LocalizationRelocalizing,
                UnsupportedLocalizationMode,
                NoLocalizationPose,
                NoLocalizationRevision,
                GoalMapRevisionMismatch,
                MapLocalizeRevisionMismatch,
            }

            /// The planner's published state.
            struct State {
                has_path: bool,
                refusal: Option<Refusal>,
            }

            topic path: state Path;
            topic state: state State;
        }

        follow {
            /// The velocity the path follower wants next, with provenance.
            struct Target {
                map_revision: Option<u64>,
                built_from_localize_revision: Option<u64>,
                frame_id: String,
                linear_x_mps: f64,
                angular_z_radps: f64,
            }

            /// The path follower's published state.
            struct State {
                active: bool,
                target_index: Option<u32>,
                finished: bool,
            }

            topic target: state Target;
            topic state: state State;
        }

        explore {
            /// A candidate frontier to explore, with a size and a ranking score.
            struct Frontier {
                x_m: f64,
                y_m: f64,
                size: u32,
                score: f32,
            }

            /// The current frontier set, tagged with its map revision.
            struct Frontiers {
                frontiers: Vec<Frontier>,
                map_revision: Option<u64>,
            }

            /// The exploration participant's published state.
            struct State {
                exploring: bool,
                selected: Option<Frontier>,
            }

            topic frontiers: state Frontiers;
            topic state: state State;
        }

        perception {
            /// A single detected object: class, confidence, and pose in a frame.
            struct Detection {
                class_id: String,
                confidence: f32,
                position_m: [f64; 3],
                frame_id: String,
                track_id: Option<u64>,
            }

            /// A batch of detections from one perception cycle.
            struct Detections {
                detections: Vec<Detection>,
                stamp_ns: Option<u64>,
            }

            /// The perception participant's published health.
            struct State {
                healthy: bool,
                detector: String,
            }

            topic detections: state Detections;
            topic state: state State;
        }

        video {
            /// Ask to open a video stream for a capability at an optional size.
            struct OpenRequest {
                capability: String,
                width_px: Option<u32>,
                height_px: Option<u32>,
            }

            /// The id of the stream that was opened.
            struct OpenResponse {
                stream_id: String,
            }

            topic open: query OpenRequest => OpenResponse;

            stream(stream) {
                /// Where one open video stream is in its lifecycle.
                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum StreamPhase {
                    Starting,
                    Active,
                    Stopped,
                }

                /// The published state of one video stream: its lifecycle phase
                /// and the number of source frames seen so far. The video participant
                /// publishes it per stream; clients subscribe, hence `state`.
                struct StreamState {
                    phase: StreamPhase,
                    frames_seen: u64,
                }

                topic state: state StreamState;
            }
        }

        simulation {
            /// The simulator clock: current time and whether it is advancing.
            struct Clock {
                now_ns: u64,
                running: bool,
            }

            /// A command to the simulator's run loop.
            #[derive(Copy, Eq)]
            enum Control {
                Pause,
                Resume,
                Reset,
            }

            /// The simulated robot's ground-truth planar pose.
            struct RobotPose {
                x_m: f64,
                y_m: f64,
                yaw_rad: f64,
            }

            /// Whether the simulated robot is in contact, with optional detail.
            struct Contact {
                in_contact: bool,
                detail: Option<String>,
            }

            topic clock: state Clock;
            topic control: command Control;
            topic robot_pose: state RobotPose;
            topic contact: state Contact;
        }

        // Per-instance component capabilities (D17/D38: framework participant / driver
        // territory). `component(instance)` selects a manifest-declared component;
        // each child `kind(capability)` is a self-contained node whose key is
        // `component/{instance}/<kind>/{capability}/<leaf>`. Nodes duplicate any
        // types they share by design - the node path disambiguates, so the names
        // are path-local.
        component(instance) {
            motor(capability) {
                /// A per-actuator command.
                enum Command {
                    Velocity(f32),
                    Torque(f32),
                    Stop,
                }

                topic command: command Command;
            }

            encoder(capability) {
                /// Per-encoder sample on a dynamic per-instance key.
                struct Sample {
                    position_rad: f64,
                    velocity_radps: f32,
                }

                topic sample: state Sample;
            }

            accelerometer(capability) {
                /// Raw accelerometer sample in the sensor-local frame in m/s^2.
                struct Sample {
                    linear_acceleration: [f32; 3],
                }

                topic sample: state Sample;
            }

            gyroscope(capability) {
                /// Raw angular velocity sample in the sensor-local frame in rad/s.
                struct Sample {
                    angular_velocity: [f32; 3],
                }

                topic sample: state Sample;
            }

            magnetometer(capability) {
                /// Raw magnetic-field sample in the sensor-local frame.
                struct Sample {
                    magnetic_field: [f32; 3],
                }

                topic sample: state Sample;
            }

            imu(capability) {
                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum SensorHealth {
                    Nominal,
                    Degraded,
                    Fault,
                }

                #[derive(Copy)]
                struct Bias {
                    angular_velocity_radps: [f32; 3],
                    linear_acceleration_mps2: [f32; 3],
                }

                struct Sample {
                    orientation: Option<[f32; 4]>,
                    angular_velocity_radps: [f32; 3],
                    linear_acceleration_mps2: [f32; 3],
                    covariance: Option<[f32; 9]>,
                    noise_density: Option<[f32; 3]>,
                    sensor_frame_id: Option<String>,
                    measured_at_ns: Option<u64>,
                    health: SensorHealth,
                    bias: Option<Bias>,
                }

                topic sample: state Sample;
            }

            range(capability) {
                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum SensorHealth {
                    Nominal,
                    Degraded,
                    Fault,
                }

                #[derive(Copy)]
                struct Limits {
                    min_m: f32,
                    max_m: f32,
                }

                #[derive(Copy)]
                struct SampleQuality {
                    valid: bool,
                    confidence: Option<f32>,
                }

                struct Sample {
                    distance_m: f32,
                    limits: Option<Limits>,
                    measured_at_ns: Option<u64>,
                    quality: Option<SampleQuality>,
                    health: SensorHealth,
                }

                topic sample: state Sample;
            }

            gnss(capability) {
                /// A GNSS fix: geodetic position plus a 3x3 position covariance.
                struct Sample {
                    latitude: f64,
                    longitude: f64,
                    altitude: f64,
                    position_covariance: [f64; 9],
                }

                topic sample: state Sample;
            }

            camera(capability) {
                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum Encoding {
                    Jpeg,
                    Png,
                    L8,
                    Rgb8,
                    Rgba8,
                }

                #[derive(Copy)]
                struct Intrinsics {
                    fx: f32,
                    fy: f32,
                    cx: f32,
                    cy: f32,
                }

                struct Distortion {
                    model: String,
                    coefficients: Vec<f32>,
                }

                #[derive(Copy)]
                struct ExposureTiming {
                    exposure_start_ns: Option<u64>,
                    exposure_duration_ns: Option<u64>,
                }

                struct CalibrationIdentity {
                    id: String,
                    version: String,
                }

                /// One camera frame: encoded pixel bytes plus optional calibration
                /// and timing metadata.
                struct Frame {
                    width: u32,
                    height: u32,
                    encoding: Encoding,
                    intrinsics: Option<Intrinsics>,
                    distortion: Option<Distortion>,
                    exposure: Option<ExposureTiming>,
                    measured_at_ns: Option<u64>,
                    calibration: Option<CalibrationIdentity>,
                    #[serde(with = "serde_bytes")]
                    data: Vec<u8>,
                }

                topic frame: state Frame;
            }

            depth(capability) {
                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum Encoding {
                    U16Millimeters,
                }

                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum InvalidSamplePolicy {
                    ZeroIsInvalid,
                    NonFiniteIsInvalid,
                }

                #[derive(Copy)]
                struct Intrinsics {
                    fx: f32,
                    fy: f32,
                    cx: f32,
                    cy: f32,
                }

                struct Distortion {
                    model: String,
                    coefficients: Vec<f32>,
                }

                #[derive(Copy)]
                struct ExposureTiming {
                    exposure_start_ns: Option<u64>,
                    exposure_duration_ns: Option<u64>,
                }

                struct CalibrationIdentity {
                    id: String,
                    version: String,
                }

                /// One depth frame: per-pixel millimetre samples plus optional
                /// calibration and timing metadata.
                struct Frame {
                    samples_mm: Vec<u16>,
                    encoding: Encoding,
                    invalid_sample_policy: InvalidSamplePolicy,
                    width: Option<u32>,
                    height: Option<u32>,
                    intrinsics: Option<Intrinsics>,
                    distortion: Option<Distortion>,
                    exposure: Option<ExposureTiming>,
                    measured_at_ns: Option<u64>,
                    calibration: Option<CalibrationIdentity>,
                }

                topic frame: state Frame;
            }

            lidar(capability) {
                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum SensorHealth {
                    Nominal,
                    Degraded,
                    Fault,
                }

                #[derive(Copy)]
                struct ScanGeometry {
                    angle_min_rad: f32,
                    angle_increment_rad: f32,
                }

                #[derive(Copy)]
                struct RangeLimits {
                    min_m: f32,
                    max_m: f32,
                }

                #[derive(Copy)]
                struct ScanQuality {
                    valid_points: u32,
                }

                struct Ranges {
                    ranges: Vec<f32>,
                    geometry: Option<ScanGeometry>,
                    limits: Option<RangeLimits>,
                    measured_at_ns: Option<u64>,
                    quality: Option<ScanQuality>,
                    health: SensorHealth,
                }

                struct Points {
                    points: Vec<[f32; 3]>,
                    limits: Option<RangeLimits>,
                    measured_at_ns: Option<u64>,
                    quality: Option<ScanQuality>,
                    health: SensorHealth,
                }

                /// One lidar scan, either as polar ranges or as cartesian points.
                #[serde(tag = "kind", rename_all = "snake_case")]
                enum Scan {
                    Ranges(Ranges),
                    Points(Points),
                }

                topic scan: state Scan;
            }

            mmwave(capability) {
                /// One mmWave radar detection: position, velocity, and SNR.
                #[derive(Copy)]
                struct Detection {
                    position: [f32; 3],
                    velocity: [f32; 3],
                    snr: f32,
                }

                /// One mmWave radar scan as a set of detections.
                struct Scan {
                    detections: Vec<Detection>,
                }

                topic scan: state Scan;
            }

            microphone(capability) {
                /// One audio frame as raw encoded bytes.
                struct Frame {
                    data: Vec<u8>,
                }

                topic frame: state Frame;
            }

            led(capability) {
                /// A per-LED on/off command.
                #[derive(Copy, Eq)]
                enum Command {
                    On,
                    Off,
                }

                topic command: command Command;
            }

            emergency_stop(capability) {
                /// Per-instance emergency-stop state.
                #[derive(Eq)]
                struct State {
                    engaged: bool,
                }

                topic state: state State;
            }
        }

        odometry {
            /// A planar pose + twist estimate in the odometry frame.
            struct State {
                x_m: f64,
                y_m: f64,
                yaw_rad: f64,
                linear_x_mps: f32,
                angular_z_radps: f32,
            }

            topic state: state State;
        }

        localize {
            /// A planar localization estimate in the map frame.
            struct LocalizationState {
                x_m: f64,
                y_m: f64,
                yaw_rad: f64,
                confidence: f32,
            }

            topic state: state LocalizationState;
        }

        presence {
            /// Per-participant liveness + readiness beacon.
            enum Readiness {
                NotStarted,
                Initializing,
                Ready,
                Degraded,
                Failed,
            }

            /// A single participant's liveness beacon. Participants publish their
            /// own heartbeat; the presence participant subscribes them as its control
            /// input, hence the `command` role.
            struct Heartbeat {
                participant: String,
                readiness: Readiness,
            }

            /// The presence participant's aggregate readiness across all participants.
            /// Presence publishes it; clients subscribe, hence the `state` role.
            struct State {
                readiness: Readiness,
            }

            topic heartbeat: command Heartbeat;
            topic state: state State;
        }

        map {
            /// A published map revision marker.
            struct Revision {
                revision: u64,
                resolution_m: f32,
            }

            /// Request a rectangular submap window (map-frame metres).
            struct SubmapRequest {
                min_x_m: f64,
                min_y_m: f64,
                max_x_m: f64,
                max_y_m: f64,
            }

            /// An occupancy-grid window: row-major cells, 0..=100 + 255 = unknown.
            struct SubmapResponse {
                width: u32,
                height: u32,
                resolution_m: f32,
                cells: Vec<u8>,
            }

            topic revision: state Revision;
            topic submap: query SubmapRequest => SubmapResponse;
        }

        asset {
            /// Fetch a stored asset by path.
            struct GetRequest {
                path: String,
            }

            /// The asset bytes, a not-found marker, or a rejected path.
            enum GetResponse {
                Found { bytes: Vec<u8> },
                Missing,
                InvalidPath,
            }

            topic get: query GetRequest => GetResponse;
        }
    }

    // v2 is the one evolving preview surface. New and changed contracts are
    // edited here until the complete version is ready to freeze; preview work
    // does not mint another public API namespace for each implementation batch.
    preview version v2 {
        battery {
            /// Battery state introduced after the v1 surface was frozen.
            struct State {
                voltage_v: f32,
                current_a: f32,
                charge_ratio: f32,
            }

            topic state: state State;
        }

        simulation {
            /// One robot node that the simulator spawn authority should import.
            struct RobotSpawn {
                robot_id: String,
                node_string: String,
            }

            /// Requests the current complete robot spawn set.
            ///
            /// `known_revision` lets a future responder distinguish initial
            /// bootstrap from refreshes after a runtime join. Responders may
            /// still return the current set when the revision is unchanged.
            struct SpawnRequest {
                known_revision: Option<u64>,
            }

            /// The complete robot spawn set for one simulation world.
            struct SpawnSet {
                revision: u64,
                robots: Vec<RobotSpawn>,
            }

            /// The authoritative advancing simulation clock. Publication means
            /// the world advanced; silence means it did not.
            struct Clock {
                now_ns: u64,
                step: u64,
            }

            topic spawn: query SpawnRequest => SpawnSet;
            topic clock: state Clock;
        }

        router {
            /// One topic's measured ingress over the sample window.
            struct TopicMetric {
                topic: String,
                from_participant: String,
                ingress_rate_hz: f32,
                count: u64,
            }

            /// The router's measured message-flow snapshot. `window_ns` is the
            /// measurement interval LENGTH (not a timestamp; production time is
            /// the envelope `publish_at`, per the guide's logical-time
            /// discipline).
            struct Metrics {
                topics: Vec<TopicMetric>,
                throughput_msg_s: f32,
                window_ns: u64,
            }

            topic metrics: state Metrics;
        }

        telemetry {
            /// Host OS resource sample (published by the new tool-telemetry).
            struct Host {
                cpu_pct: f32,
                ram_used_bytes: u64,
                ram_total_bytes: u64,
                load_1m: f32,
                window_ns: u64,
            }

            /// One participant's OWN process resource sample (published by the
            /// runner off the heartbeat loop). Subscriber demuxes by envelope
            /// source, like `presence::Heartbeat`.
            struct Process {
                cpu_pct: f32,
                rss_bytes: u64,
                window_ns: u64,
            }

            topic host: state Host;
            topic process: state Process;
        }

        joypad {
            /// One gamepad the tool can see. `id` is a STABLE wire id the tool
            /// assigns (name/guid-derived) - NOT a process-local gilrs id.
            struct Device {
                id: String,
                name: String,
                connected: bool,
            }

            /// The joypad tool's published device state.
            struct Devices {
                available: Vec<Device>,
                selected: Option<String>,
                last_error: Option<String>,
            }

            /// Client asks the tool to select/connect a device by its stable id.
            struct Connect {
                id: String,
            }

            /// Client asks the tool to re-enumerate devices.
            struct Rescan {}

            topic devices: state Devices;
            topic connect: command Connect;
            topic rescan: command Rescan;
        }
    }
}

#[cfg(test)]
mod tests;