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 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>,
                /// Complete records lost before publication because a bounded
                /// queue or publish attempt was saturated.
                dropped: u32,
                /// Values or fields truncated inside this published record to
                /// keep its wire representation bounded.
                #[serde(default)]
                truncated: u32,
            }

            topic self: state Event;
        }

        tool {
            /// Opaque identity for one retention-tool process together with a
            /// position in its completed follow stream. A snapshot cursor
            /// covers the retained completed items; a bus snapshot's optional
            /// `current` window deliberately has the next sequence. Consumers
            /// compare `generation` for equality only and must never parse or
            /// order it.
            #[derive(Eq)]
            struct Cursor {
                generation: String,
                sequence: u64,
            }

            /// Which side of one participant-local bus buffer a runtime row
            /// measures. The version-qualified `topic` field remains the wire
            /// identity; direction is never inferred from its spelling.
            #[derive(Copy, Eq, Ord, PartialOrd)]
            #[serde(rename_all = "snake_case")]
            enum RuntimeDirection {
                Publish,
                Subscribe,
                /// Used only by the bounded overflow row, which may combine
                /// omitted rows from both directions.
                Mixed,
            }

            /// The concrete bounded buffer whose pressure a runtime row
            /// measures.
            #[derive(Copy, Eq, Ord, PartialOrd)]
            #[serde(rename_all = "snake_case")]
            enum RuntimeBufferKind {
                /// Per-topic view of the one shared process outbound queue.
                /// Its sample capacity is repeated on each row and must not be
                /// summed; the queue's separate byte pressure is not in v1.
                Outbound,
                /// Keep-last slot. Depth `1` means occupied, never backlog.
                Latest,
                Subscriber,
                /// Used only by the bounded overflow row.
                Mixed,
            }

            /// Host-monotonic scheduled-step work completed during one rollup
            /// window. An unscheduled participant reports `None` instead.
            struct RuntimeStep {
                target_period_ns: u64,
                completed: u64,
                errors: u64,
                mean_duration_ns: u64,
                max_duration_ns: u64,
                mean_lateness_ns: u64,
                max_lateness_ns: u64,
                missed_ticks: u64,
                overruns: u64,
            }

            /// One exact version-qualified topic/direction/buffer row. These
            /// are process-lifetime setup declarations: dropping an authoring
            /// handle does not dynamically unregister a row. Empty `topic`
            /// plus `Mixed` direction/kind identifies the explicit overflow
            /// row; `overflowed_rows` is zero on normal rows.
            struct RuntimeTopic {
                topic: String,
                direction: RuntimeDirection,
                buffer_kind: RuntimeBufferKind,
                count: u64,
                /// Finite, non-negative message rate. Retention tools clamp
                /// malformed non-finite inputs before they reach snapshots.
                rate_hz: f32,
                drops: u64,
                latest_overwrites: u64,
                bounded_evictions: u64,
                /// Sample capacity. Outbound rows repeat the shared process
                /// queue capacity and are non-additive; byte pressure is not
                /// represented. Latest capacity/depth describe slot occupancy.
                capacity: u64,
                current_depth: u64,
                high_water_depth: u64,
                decode_errors: u64,
                overflowed_rows: u32,
            }

            log {
                /// Requests tool-log's complete current bounded snapshot. The
                /// first protocol version intentionally has no pagination or
                /// filtering surface.
                struct SnapshotRequest {}

                /// Wall-clock timestamp copied from one participant-originated
                /// structured `v1::logs` event.
                struct Timestamp {
                    unix_seconds: i64,
                    nanos: u32,
                }

                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum Level {
                    Error,
                    Warn,
                    Info,
                    Debug,
                    Trace,
                }

                #[serde(untagged)]
                enum LogValue {
                    Bool(bool),
                    I64(i64),
                    U64(u64),
                    F64(f64),
                    String(String),
                }

                /// One retained participant log. `sequence` is assigned by
                /// tool-log at ingest and is independent of the producer's
                /// `source_sequence`.
                struct Record {
                    sequence: u64,
                    participant_id: String,
                    source_sequence: u64,
                    time: Timestamp,
                    level: Level,
                    target: String,
                    message: String,
                    fields: ::std::collections::BTreeMap<String, LogValue>,
                    dropped: u32,
                    truncated: u32,
                }

                /// The complete bounded tool-log state at `cursor`.
                struct Snapshot {
                    cursor: crate::v1::tool::Cursor,
                    /// Cumulative structured log samples evicted from
                    /// tool-log's bounded ingest subscriber in this process.
                    /// An increase is observable, unrecoverable source loss;
                    /// it is distinct from producer-side `Record::dropped`.
                    ingest_dropped: u64,
                    records: Vec<Record>,
                }

                /// One live record following the snapshot query. A consumer
                /// must re-query when the generation changes or the sequence is
                /// not exactly one after its installed cursor.
                struct Follow {
                    cursor: crate::v1::tool::Cursor,
                    /// Current cumulative tool-log ingest loss counter.
                    ingest_dropped: u64,
                    record: Record,
                }

                topic snapshot: query SnapshotRequest => Snapshot;
                topic follow: state Follow;
            }

            bus {
                /// Requests tool-bus's complete current bounded snapshot. The
                /// first protocol version intentionally has no pagination or
                /// filtering surface.
                struct SnapshotRequest {}

                /// One topic-producer pair measured during a one-second window.
                /// Empty topic and producer identify the bounded overflow row.
                struct TopicMetric {
                    topic: String,
                    from_participant: String,
                    ingress_rate_hz: f32,
                    count: u64,
                }

                /// One retained bus-rate window. `window_ns` is a duration, not
                /// a production timestamp.
                struct Window {
                    sequence: u64,
                    topics: Vec<TopicMetric>,
                    throughput_msg_s: f32,
                    window_ns: u64,
                }

                /// The current partial counters plus the bounded recent
                /// completed-window history. The partial `current` window has
                /// the next sequence that its eventual follow item will use;
                /// the snapshot cursor covers only `windows`.
                struct Snapshot {
                    cursor: crate::v1::tool::Cursor,
                    current: Option<Window>,
                    windows: Vec<Window>,
                }

                /// One newly completed bus-rate window.
                struct Follow {
                    cursor: crate::v1::tool::Cursor,
                    window: Window,
                }

                topic snapshot: query SnapshotRequest => Snapshot;
                topic follow: state Follow;
            }

            device {
                /// One mounted filesystem capacity observation. The contract
                /// intentionally excludes OS-specific device names and I/O
                /// counters; an unavailable storage inventory is represented
                /// by `Sample::disks == None`, never fabricated zero rows.
                struct Disk {
                    mount_point: String,
                    file_system: String,
                    used_bytes: u64,
                    total_bytes: u64,
                }

                /// Portable whole-device observations produced by one
                /// runner-owned tool-device. Every optional field is `None`
                /// when the current platform cannot provide a truthful value.
                /// These totals must never be attributed to a runtime.
                struct Sample {
                    /// Logical device identity within the robot root. The
                    /// current execution environment is always `main`.
                    device_id: String,
                    cpu_pct: Option<f32>,
                    ram_used_bytes: Option<u64>,
                    ram_total_bytes: Option<u64>,
                    swap_used_bytes: Option<u64>,
                    swap_total_bytes: Option<u64>,
                    load_1m: Option<f32>,
                    load_5m: Option<f32>,
                    load_15m: Option<f32>,
                    uptime_s: Option<u64>,
                    disks: Option<Vec<Disk>>,
                    /// Host-monotonic duration between sampler refreshes.
                    window_ns: u64,
                }

                /// Requests tool-telemetry's bounded device history.
                struct SnapshotRequest {
                    /// Optional exact logical device filter.
                    device_id: Option<String>,
                    /// Maximum newest records to return. Zero selects the
                    /// tool's bounded default.
                    limit: u32,
                    /// Exclusive global ingest-sequence upper bound.
                    before_sequence: Option<u64>,
                }

                struct Record {
                    sequence: u64,
                    sample: Sample,
                    /// Text fields or rows truncated by tool-telemetry.
                    truncated: u32,
                }

                struct Snapshot {
                    cursor: crate::v1::tool::Cursor,
                    records: Vec<Record>,
                    /// Records evicted by the absolute capacity bound before
                    /// their five-minute age horizon elapsed.
                    capacity_evictions: u64,
                    next_before_sequence: Option<u64>,
                }

                struct Follow {
                    cursor: crate::v1::tool::Cursor,
                    record: Record,
                }

                topic sample: state Sample;
                topic snapshot: query SnapshotRequest => Snapshot;
                topic follow: state Follow;
            }

            runtime {
                /// Runner-originated portable performance rollup. The runner
                /// publishes at most one per host-monotonic grid interval;
                /// envelope provenance identifies the participant. Interval
                /// counters are best-effort sequential atomic samples, not a
                /// transactional stop-the-world boundary, so concurrent queue
                /// activity may land on either neighboring rollup.
                struct Rollup {
                    window_ns: u64,
                    step: Option<crate::v1::tool::RuntimeStep>,
                    topics: Vec<crate::v1::tool::RuntimeTopic>,
                    overflow: Option<crate::v1::tool::RuntimeTopic>,
                }

                /// Requests tool-telemetry's current bounded five-minute
                /// runtime history.
                struct SnapshotRequest {
                    /// Optional exact participant filter. `None` selects the
                    /// complete per-robot history.
                    participant_id: Option<String>,
                    /// Maximum newest records to return. Zero selects the
                    /// tool's bounded default.
                    limit: u32,
                    /// Exclusive global ingest-sequence upper bound for
                    /// backward pagination. `None` starts at the newest record.
                    before_sequence: Option<u64>,
                }

                /// One retained rollup. `sequence` is assigned by
                /// tool-telemetry at ingest, independent of producer metadata.
                /// Duplicate normal topic keys are deterministically
                /// re-aggregated before row bounds are applied.
                struct Record {
                    sequence: u64,
                    participant_id: String,
                    /// Text values truncated by tool-telemetry's ingest bound.
                    /// Oversized/excess topic identities are not truncated;
                    /// they are aggregated into the explicit overflow row.
                    truncated: u32,
                    window_ns: u64,
                    step: Option<crate::v1::tool::RuntimeStep>,
                    topics: Vec<crate::v1::tool::RuntimeTopic>,
                    overflow: Option<crate::v1::tool::RuntimeTopic>,
                }

                struct Snapshot {
                    cursor: crate::v1::tool::Cursor,
                    records: Vec<Record>,
                    /// Records evicted by the absolute memory cap before their
                    /// five-minute age horizon elapsed.
                    capacity_evictions: u64,
                    /// Pass this as the next request's `before_sequence` to
                    /// continue backward. `None` means the retained matching
                    /// history is complete.
                    next_before_sequence: Option<u64>,
                }

                struct Follow {
                    cursor: crate::v1::tool::Cursor,
                    record: Record,
                }

                topic rollup: state Rollup;
                topic snapshot: query SnapshotRequest => Snapshot;
                topic follow: state Follow;
            }
        }

        bus {
            uplink {
                /// Reserved observable state for a future authenticated router
                /// uplink. Phase 1 has no publisher for this contract.
                #[derive(Copy, Eq)]
                #[serde(rename_all = "snake_case")]
                enum UplinkPhase {
                    Disabled,
                    Connecting,
                    Connected,
                    /// Reserved for future retry telemetry.
                    Retrying,
                }

                /// Reserved router-owned state for a future optional site uplink.
                struct State {
                    phase: UplinkPhase,
                    connect: Option<String>,
                    /// Reserved for future retry telemetry.
                    retry_attempt: u32,
                    /// Optional human-readable diagnostic while not connected,
                    /// such as DNS failure or waiting for the configured remote
                    /// link. Invalid endpoints fail configuration before startup.
                    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;
        }

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

        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>,
                /// One-shot acknowledgement of a failed select/enable/rescan
                /// request. Event-driven consumers may show it once; periodic
                /// state heartbeats omit it. The tool also writes the failure
                /// to its log stream for durable diagnostics.
                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;