phoxal-api 0.21.1

//! 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 the current production surface and may change in place while the
//! pre-stability topology is simplified. `v2` is the single preview surface for
//! contracts that have not entered production. 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.
//!
//! [`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,
                TargetStale,
                TargetFromFuture,
                TargetNotFinite,
                ActuatorCommandNotFinite,
                Inactive,
                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>,
                target_age_ns: Option<u64>,
            }

            topic target: command Target;
            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 {
                HostIntegrationUnavailable,
                CommandRejected,
            }

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

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

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

        motion {
            struct Target {
                linear_x_mps: f32,
                angular_z_radps: f32,
                curvature_limit_radpm: Option<f32>,
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum Source {
                Manual,
                Navigation,
                EmergencyStop,
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum ZeroReason {
                NoCandidate,
                ManualCandidateStale,
                NavigationCandidateStale,
                ManualCandidateFromFuture,
                NavigationCandidateFromFuture,
                ManualCandidateNotFinite,
                NavigationCandidateNotFinite,
                EmergencyStopEngaged,
                SafetyConstraintsUnavailable,
                SafetyProtectiveStop,
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum SafetyRuntime {
                Absent,
                Present,
            }

            struct ManualCommand {
                linear_x_mps: f64,
                angular_z_radps: f64,
            }

            #[derive(Eq)]
            struct EmergencyStopRequest {
                engaged: bool,
            }

            struct State {
                manual_candidate_age_ns: Option<u64>,
                autonomous_candidate_age_ns: Option<u64>,
                safety_constraints_age_ns: Option<u64>,
                selected_source: Option<Source>,
                final_target: Target,
                zero_reason: Option<ZeroReason>,
                safety_runtime: SafetyRuntime,
                software_estop_engaged: bool,
                component_estop_blocked: bool,
                active_safety_constraints: Vec<super::safety::Constraint>,
            }

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

        safety {
            /// Why safety is stopping or limiting body motion.
            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum ConstraintReason {
                WorldUnavailable,
                MapUnavailable,
                DrivableSpaceUnavailable,
                LocalizationUnavailable,
                LocalizationUncertain,
                ObstacleProximity,
                RangeSensorFault,
                DriveFault,
                BatteryLow,
                BatteryCritical,
                SpeedZone,
                OperatorPolicy,
            }

            /// Typed origin of one constraint, suitable for operator diagnosis.
            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum ConstraintSourceKind {
                WorldModel,
                Map,
                Localization,
                Range,
                Drive,
                Battery,
                Operator,
            }

            struct ConstraintSource {
                kind: ConstraintSourceKind,
                participant_id: String,
                component_id: Option<String>,
                capability_id: Option<String>,
            }

            struct Constraint {
                reason: ConstraintReason,
                source: ConstraintSource,
                stop: bool,
                max_linear_speed_mps: Option<f32>,
                max_angular_speed_radps: Option<f32>,
                observed_value: Option<f32>,
                valid_from_ns: u64,
                expires_at_ns: u64,
            }

            /// The sole safety-to-motion control product. Motion accepts it only
            /// in the same epoch and before `expires_at_ns`.
            struct MotionConstraints {
                sequence: u64,
                stop: bool,
                max_linear_speed_mps: Option<f32>,
                max_angular_speed_radps: Option<f32>,
                constraints: Vec<Constraint>,
                expires_at_ns: u64,
            }

            /// Operator-facing state mirrors the exact product consumed by motion.
            struct State {
                clear: bool,
                motion: MotionConstraints,
            }

            topic constraints: state MotionConstraints;
            topic state: state State;
        }

        navigation {
            #[derive(Eq)]
            struct RequestId {
                value: String,
            }

            struct Pose {
                x_m: f64,
                y_m: f64,
                yaw_rad: Option<f64>,
            }

            struct Path {
                poses: Vec<Pose>,
                map_revision: Option<u64>,
            }

            enum RequestKind {
                GotoPose(Pose),
                FollowPath(Path),
                Cancel(RequestId),
            }

            struct Request {
                request_id: RequestId,
                kind: RequestKind,
            }

            enum State {
                Idle,
                Accepted(RequestId),
                Running(RequestId),
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum FailureReason {
                LocalizationUnavailable,
                MapUnavailable,
                MapChanged,
                NoPath,
                Blocked,
                Internal,
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum RefusalReason {
                Busy,
                InvalidRequest,
                Unsupported,
            }

            enum Outcome {
                Succeeded,
                Failed(FailureReason),
                Refused(RefusalReason),
                Cancelled,
                TimedOut,
            }

            struct Progress {
                request_id: RequestId,
                distance_remaining_m: f64,
                path_index: u32,
            }

            struct Result {
                request_id: RequestId,
                outcome: Outcome,
            }

            struct Candidate {
                request_id: RequestId,
                linear_x_mps: f32,
                angular_z_radps: f32,
            }

            struct FrontierRequest {
                map_revision: Option<u64>,
            }

            struct Frontier {
                x_m: f64,
                y_m: f64,
                score: f32,
                size: u32,
            }

            struct FrontierResponse {
                frontier: Option<Frontier>,
                map_revision: Option<u64>,
            }

            topic request: command Request;
            topic state: state State;
            topic progress: state Progress;
            topic result: state Result;
            topic candidate: state Candidate;
            topic next_frontier: query FrontierRequest => FrontierResponse;
        }

        behavior {
            #[derive(Eq)]
            struct RequestId {
                value: String,
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum ConflictPolicy {
                Reject,
                Queue,
                Interrupt,
            }

            enum Value {
                Bool(bool),
                Integer(i64),
                Number(f64),
                String(String),
                Pose(super::navigation::Pose),
            }

            struct Request {
                request_id: RequestId,
                behavior_id: String,
                args: ::std::collections::BTreeMap<String, Value>,
                priority: u8,
                conflict_policy: ConflictPolicy,
            }

            enum Command {
                Pause,
                Resume,
                Cancel,
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum ExecutionStatus {
                Idle,
                Running,
                Paused,
                Succeeded,
                Failed,
                Cancelled,
                Abandoned,
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum NodeStatus {
                Idle,
                Running,
                Succeeded,
                Failed,
                Skipped,
                Waiting,
                Cancelling,
            }

            #[derive(Copy, Eq)]
            #[serde(rename_all = "snake_case")]
            enum FailureReason {
                MissingCapability,
                ActionRefused,
                ActionFailed,
                ActionTimedOut,
                ActionCancelled,
                ConditionFailed,
                SafetyStopped,
                EmergencyStopped,
                ResourceConflict,
                InvalidArgument,
                InvalidBlackboardValue,
                SubtreeFailed,
                ExecutionAbandoned,
                InternalError,
            }

            struct Failure {
                reason: FailureReason,
                detail: Option<String>,
                node_path: Option<String>,
                action_id: Option<String>,
            }

            struct DefinitionRef {
                id: String,
                version: String,
                content_hash: String,
            }

            struct State {
                execution_id: Option<String>,
                root_behavior_id: Option<String>,
                active_request_id: Option<RequestId>,
                active_behavior_id: Option<String>,
                status: ExecutionStatus,
                active_node_path: Option<String>,
                failure: Option<Failure>,
            }

            struct Snapshot {
                execution_id: Option<String>,
                root: Option<DefinitionRef>,
                definition_stack: Vec<DefinitionRef>,
                active_request_id: Option<RequestId>,
                active_behavior_id: Option<String>,
                status: ExecutionStatus,
                node_statuses: ::std::collections::BTreeMap<String, NodeStatus>,
                active_node_path: Option<String>,
                blackboard: ::std::collections::BTreeMap<String, Value>,
                args: ::std::collections::BTreeMap<String, Value>,
                started_at_ns: Option<u64>,
                updated_at_ns: u64,
                failure: Option<Failure>,
            }

            enum EventKind {
                ExecutionStarted,
                ExecutionPaused,
                ExecutionResumed,
                ExecutionCompleted,
                ExecutionCancelled,
                ExecutionAbandoned,
                NodeTransition(NodeStatus),
                RequestAccepted,
                RequestCompleted(ExecutionStatus),
                RequestRejected(FailureReason),
            }

            struct Event {
                sequence: u64,
                execution_id: Option<String>,
                request_id: Option<RequestId>,
                behavior_id: Option<String>,
                content_hash: Option<String>,
                node_path: Option<String>,
                kind: EventKind,
                failure: Option<Failure>,
                participant_id: String,
                logical_time_ns: u64,
            }

            topic command: command Command;
            topic request: command Request;
            topic state: state State;
            topic snapshot: state Snapshot;
            topic event: state Event;
        }

        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;
            }
        }




        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 remains preview while hardware ownership evolves.
            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 {
            /// One real mounted filesystem in a host resource sample.
            struct Disk {
                mount_point: String,
                file_system: String,
                used_bytes: u64,
                total_bytes: u64,
            }

            /// Host OS resource sample (published by the new tool-telemetry).
            struct Host {
                cpu_pct: f32,
                ram_used_bytes: u64,
                ram_total_bytes: u64,
                swap_used_bytes: u64,
                swap_total_bytes: u64,
                load_1m: f32,
                load_5m: f32,
                load_15m: f32,
                uptime_s: Option<u64>,
                disks: Vec<Disk>,
                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 {
            /// Whether an observed controller is ready for the fixed manual
            /// input preset, disconnected, or connected without a compatible
            /// control mapping.
            enum DeviceStatus {
                Ready,
                Disconnected,
                Unsupported,
            }

            /// 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,
                status: DeviceStatus,
            }

            /// The joypad tool's published device state.
            struct Devices {
                available: Vec<Device>,
                selected: Option<String>,
                enabled: bool,
                /// Structural reason manual input cannot be enabled in this
                /// session (for example robot-model or backend limitations),
                /// independent of transient device/request errors.
                unavailable_reason: Option<String>,
                /// Most recent failed select/enable/rescan request, cleared by
                /// the next successful authoritative request.
                last_error: Option<String>,
            }

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

            /// Client asks the tool to enable or disable manual input.
            struct SetEnabled {
                enabled: bool,
            }

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

            topic devices: state Devices;
            topic select: command Select;
            topic set_enabled: command SetEnabled;
            topic rescan: command Rescan;
        }
    }
}

#[cfg(test)]
mod tests;