phoxal_api/

lib.rs

//! The single API layer (D60/D61).
//!
//! This crate is the dated 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 runtime depends on both crates
//! and imports the API tree directly with `use phoxal_api::y2026_1 as api;`, so
//! `phoxal_api::y2026_1`, `phoxal_api::ApiVersion`, and `phoxal_api::ContractBody`
//! are the canonical paths.
//!
//! # Dated API versions
//!
//! An API version is a **dated module** (`phoxal_api::y2026_1`, …) generated by
//! [`phoxal_api_tree!`]. Each version module carries:
//!
//! - a zero-variant marker `enum Api {}` implementing [`ApiVersion`], whose
//!   [`ApiVersion::ID`] is the dated module name (`"y2026_1"`) - the canonical
//!   version identity;
//! - 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()`.
//!
//! Versions can build on earlier ones with `version y2026_2 extends y2026_1`:
//! every inherited node and type is re-emitted *fresh* under the new module - same
//! [`ContractBody::FAMILY`] and [`ContractBody::TOPIC`], a different [`Api`] - so an
//! unchanged contract stays wire-identical while the compile-time `Api` bound stays
//! distinct. See [`phoxal_api_tree!`] for the inheritance and shape-identity rules.
//!
//! [`Api`]: y2026_1::Api
//!
//! # One API version per runtime, one per graph
//!
//! A runtime authors against exactly one version module
//! (`use phoxal_api::y2026_1 as api;`) and declares it on the derive
//! (`#[phoxal(api = y2026_1)]`). Every handle body is bound
//! `ContractBody<Api = R::Api>`, so passing a body from another API version is a
//! compile error (D59/D60). At deploy time a single graph runs a single API
//! version: all of its runtimes share one `Api`, so contracts on the bus are
//! mutually consistent by construction (D59).
//!
//! # Plain serde wire bodies, version in metadata
//!
//! A wire body is just its serde encoding - there is no `{"v":…}` envelope or any
//! other version tag inside the payload (D62). The three pieces of routing
//! identity travel as bus metadata alongside the encoded body, not in it:
//!
//! - the **version** ([`ApiVersion::ID`], e.g. `"y2026_1"`),
//! - the **family** ([`ContractBody::FAMILY`], e.g. `"drive::State"`),
//! - the **codec** that produced the bytes.
//!
//! Keeping these out of the payload means the body bytes for an unchanged contract
//! are identical across versions and codecs; the envelope/metadata layer owns
//! version and family.
//!
//! # Family and topic
//!
//! Both identifiers are derived from the contract node's path in the tree, never
//! written by hand:
//!
//! - [`ContractBody::FAMILY`] is the `::`-joined node path plus the body type name,
//!   e.g. `component::motor::Command`. It excludes dynamic variables, so every
//!   instance of a per-instance node shares one family.
//! - [`ContractBody::TOPIC`] is the versionless `/`-joined key with each dynamic
//!   node contributing a `{var}` placeholder, e.g.
//!   `component/{instance}/motor/{capability}/command`. A fully static path has a
//!   literal key (`drive/state`).
//!
//! # 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 static key `drive/state`, and
//! `api::topic::new().component("base").motor("left").command()` fills the dynamic
//! segments to produce `component/base/motor/left/command`. Because the builder is
//! generated from the same tree as `FAMILY`/`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 runtime 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 runtime 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 dated API version (D60),
///   implemented only by the zero-variant `enum Api {}` that [`phoxal_api_tree!`]
///   generates inside each version module; its `ID` is the dated module name
///   (`"y2026_1"`) and the canonical version identity, carried in bus metadata.
/// - [`ContractBody`] is a version-local wire body (D61): a plain serde type
///   bound to exactly one [`ApiVersion`] and one contract family/topic. Every
///   body declared inside a [`phoxal_api_tree!`] node gets a generated impl;
///   handles, `SetupContext` builders, and the `#[derive(Runtime)]` assertions
///   key off its `Api`/`FAMILY`/`TOPIC` to reject a body from the wrong API
///   version at compile time. Its serde encoding *is* the wire payload; there is
///   no version envelope (D62).
pub use phoxal_bus::{ApiVersion, ContractBody};

phoxal_api_tree! {
    version y2026_1 {
        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 runtime'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;
        }

        battery {
            /// Battery state - a family that exists only from y2026_1 on.
            struct State {
                voltage_v: f32,
                current_a: f32,
                charge_ratio: f32,
            }

            topic state: state State;
        }

        safety {
            /// Safety runtime 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 runtime 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 runtime'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 runtime'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 runtime'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 runtime 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 runtime'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;
        }

        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 runtime'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 runtime'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 runtime
                /// 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-runtime / 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 runtime subscribes them as its control
            /// input, hence the `command` role.
            struct Heartbeat {
                participant: String,
                readiness: Readiness,
            }

            /// The presence runtime'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;
        }
    }
}

#[cfg(test)]
mod tests;