phoxal-bus 0.43.2

//! The contract primitive traits (D60/D61): the API-version marker and the
//! version-local wire body.
//!
//! These are the two traits the bus client is generic over - the ABI floor every
//! contract body and api-version marker implements. The concrete versioned API
//! versions (`phoxal::api`, …) and the `phoxal_api_tree!` macro that
//! generates their `ApiVersion` / `ContractBody` impls live in the `phoxal-api`
//! crate, which re-exports these traits - so they are reachable as
//! `phoxal_api::ApiVersion` / `phoxal_api::ContractBody`. The `phoxal` engine
//! re-exports this bus crate at `phoxal::bus`, so they are also reachable as
//! `phoxal::bus::ApiVersion` / `phoxal::bus::ContractBody`.

/// Marker trait identifying one API version (D60).
///
/// Implemented only by the zero-variant `enum Api {}` that
/// [`phoxal_api_tree!`] generates inside each revision module. The [`ID`] is the
/// dotted wire revision (`"v0.1"`) and is carried in bus metadata as
/// informational provenance, never in the wire body or the topic key (D62).
///
/// [`ID`]: ApiVersion::ID
/// [`phoxal_api_tree!`]: https://docs.rs/phoxal
pub trait ApiVersion: 'static {
    /// The dotted wire-revision identifier, e.g. `"v0.1"` (the corresponding
    /// Rust module is `v0_1`).
    const ID: &'static str;
}

/// The semantic **and temporal** role a topic plays in its owning service's
/// contract.
///
/// Every topic in a [`phoxal_api_tree!`] declares one of these (D63, plan #00).
/// The role records *intent*, separate from the wire shape: a `Command` and a
/// `State` topic are both pub/sub on the wire, but the owner subscribes a
/// `Command` (it is the service's control input) and publishes a `State` (it is
/// the service's telemetry output).
///
/// The role drives two things:
///
/// - the **side branding** (L1): the api tree's builders read it to pick each
///   leaf's side-branded topic kind
///   (`Publish`/`Subscribe`/`AskQuery`/`ServeQuery`), so taking the wrong side
///   of a topic is a compile error;
/// - the **temporal capability** (#952 section D): the role decides which robot
///   time a publisher of that contract can express at all. A `State` is
///   published at a logical step, a `Measurement` carries a capture stamp, and
///   a `Command` or `Diagnostic` expresses no robot time. The generated body
///   implements exactly one of [`StateContract`] / [`MeasurementContract`] /
///   [`CommandContract`] / [`DiagnosticContract`], and each publisher handle is
///   bounded by its own marker, so reaching for the wrong publisher is a
///   compile error rather than a review question. One topic is the sole
///   exception: the framework's own `world_clock`-role `simulation::Clock`
///   wire-brands and reports `TopicRole::State` exactly like an ordinary state
///   topic, but implements the disjoint [`WorldClockContract`] instead of
///   `StateContract` - see that trait's docs for why.
///
/// [`phoxal_api_tree!`]: https://docs.rs/phoxal
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum TopicRole {
    /// A control input the owning service subscribes (e.g. `drive/target`).
    /// Expresses no robot time: a command is a request, not an observation.
    Command,
    /// State the owning service publishes at a logical step (e.g.
    /// `drive/state`).
    State,
    /// A sensor observation the owning service publishes with a capture stamp
    /// (e.g. `component/{instance}/imu/{capability}/sample`).
    Measurement,
    /// An output that describes the participant rather than the world (health,
    /// logs, runtime evidence). Expresses no robot time.
    Diagnostic,
    /// A request/response topic the owning service answers (e.g. `map/submap`).
    Query,
}

impl TopicRole {
    /// The lowercase grammar keyword for this role, matching how it is written
    /// in `phoxal_api_tree!`.
    pub const fn as_str(self) -> &'static str {
        match self {
            TopicRole::Command => "command",
            TopicRole::State => "state",
            TopicRole::Measurement => "measurement",
            TopicRole::Diagnostic => "diagnostic",
            TopicRole::Query => "query",
        }
    }
}

/// Marker for a body whose topic role is [`TopicRole::State`].
///
/// Generated by `phoxal_api_tree!` for every ordinary `state` topic. Deliberately
/// NOT implemented for the framework's own world-clock contract
/// (`phoxal::api::simulation::Clock`) - see [`WorldClockContract`] for why that
/// exclusion is the enforcement mechanism, not an oversight.
pub trait StateContract: ContractBody {}

/// Marker for the framework's single world-clock contract
/// (`phoxal::api::simulation::Clock`, generated by `phoxal_api_tree!`'s
/// `world_clock` topic role).
///
/// Deliberately a SIBLING of [`StateContract`], not a subtrait of it: if the
/// world clock also implemented `StateContract`, it would still satisfy the
/// ordinary, unrestricted `state_publisher` builder every participant has,
/// which would make "only a simulator can mint world steps" an unenforced
/// convention rather than a compiler rule.
/// Excluding it from `StateContract` is what makes that builder reject it at
/// compile time, forcing every caller through the world-authority-gated
/// `SetupContextSimulatorExt::world_clock_publisher` in the `phoxal` crate
/// instead (`Self: IsSimulator`).
///
/// Bounds [`WorldClockPublisher`](crate::handle::WorldClockPublisher), a
/// dedicated handle type separate from
/// [`StatePublisher`](crate::handle::StatePublisher) even though both publish
/// at a logical step with the same [`StepStamp`](crate::handle::StepStamp)
/// path: sharing one generic handle type across both traits would force
/// `StatePublisher`'s bound onto a common supertrait, which would blur an
/// ordinary participant's "wrong contract for `StatePublisher`" compile error
/// (today a precise `B: StateContract` message with the real `state` topics
/// listed as candidates) into a less legible one naming an internal plumbing
/// trait instead. Two small handle types keep that diagnostic exact.
pub trait WorldClockContract: ContractBody {}

/// Marker for a body whose topic role is [`TopicRole::Measurement`].
///
/// Generated by `phoxal_api_tree!`; it is the bound on
/// [`MeasurementPublisher`](crate::handle::MeasurementPublisher), whose publish
/// path requires a capture stamp the driver derived from its device clock.
pub trait MeasurementContract: ContractBody {}

/// Marker for a body whose topic role is [`TopicRole::Command`].
///
/// Generated by `phoxal_api_tree!`; it is the bound on
/// [`CommandPublisher`](crate::handle::CommandPublisher), which expresses no
/// robot time at all.
pub trait CommandContract: ContractBody {}

/// Marker for a body whose topic role is [`TopicRole::Diagnostic`].
///
/// Generated by `phoxal_api_tree!`; it is the bound on
/// [`DiagnosticPublisher`](crate::handle::DiagnosticPublisher), which expresses
/// no robot time at all.
pub trait DiagnosticContract: ContractBody {}

/// A version-local wire body: a plain serde type bound to exactly one
/// [`ApiVersion`] and one contract topic (D61/D1).
///
/// Every body declared inside a `phoxal_api_tree!` node gets a generated impl.
/// Each body carries its own [`Api`](ContractBody::Api) version marker and
/// version-qualified [`TOPIC`](ContractBody::TOPIC).
/// Participant setup builders accept these bodies directly and preserve the
/// contract type through each typed handle.
///
/// The serde encoding of an implementor *is* the wire payload; there is no version
/// envelope (D62).
///
/// **Wire identity is the key, not a hash (D1).** The version is folded into
/// [`TOPIC`](ContractBody::TOPIC), so `v0.1::drive::Target` and a
/// hypothetically re-minted `v0.2::drive::Target` publish on different Zenoh
/// keys and physically cannot collide. Two participants interoperate on a
/// contract iff they use the exact same version-qualified name, which is
/// realized on the wire by the key.
/// A receiver's per-key Zenoh subscription is the
/// whole fast-reject; the bus decode path validates only the codec.
pub trait ContractBody:
    serde::Serialize + serde::de::DeserializeOwned + Clone + Send + Sync + 'static
{
    /// The single API version this body belongs to. Two bodies from different
    /// versions have different `Api`, so the type system keeps them apart.
    type Api: ApiVersion;
    /// The version-qualified type identity: the dotted wire revision, then the `::`-joined node path
    /// (dynamic-node vars are topic params, never type-path segments), then
    /// the PascalCase type leaf, e.g. `"v0.1::drive::Target"` or
    /// `"v0.1::component::motor::Command"`. This is the contract's source
    /// identity (D1) - two contracts interoperate iff they share this exact
    /// name - as distinct from [`TOPIC`](ContractBody::TOPIC), the resolved
    /// wire key derived from it. `NAME` is exactly the `"::"`-join of
    /// [`VERSION`](ContractBody::VERSION) and
    /// [`CONTRACT`](ContractBody::CONTRACT); it stays available for callers
    /// that want the whole identity as one string (e.g. display), while
    /// consumers that must reason about the revision and the contract
    /// independently use the two split consts instead - a joined name is not
    /// machine-parseable without assuming the version naming scheme.
    const NAME: &'static str;
    /// This body's dotted wire revision alone, e.g. `"v0.1"` - equal to
    /// `<Self::Api as ApiVersion>::ID`, but exposed directly on the body so a
    /// metadata or diagnostics recorder can const-splice it without routing
    /// through `Self::Api`.
    /// Split from [`CONTRACT`](ContractBody::CONTRACT) so a consumer can read
    /// the revision without parsing a joined name.
    const VERSION: &'static str;
    /// This body's contract path within its own version: the `::`-joined
    /// node path (dynamic-node vars excluded, as with `NAME`) plus the
    /// PascalCase type leaf, e.g. `"drive::Target"`. The **logical
    /// contract** - stable across a version bump - is this value alone;
    /// pairing it with [`VERSION`](ContractBody::VERSION) recovers the
    /// full version-qualified identity (`NAME`).
    const CONTRACT: &'static str;
    /// The version-qualified wire key: the dotted wire revision, then the
    /// `/`-joined node path plus the topic leaf, with each dynamic node
    /// contributing a `{var}` placeholder, e.g. `"v0.1/drive/state"` or
    /// `"v0.1/component/{instance}/motor/{capability}/command"`. The concrete
    /// key is produced by the api-local `topic` builder, which fills the
    /// placeholders.
    const TOPIC: &'static str;
    /// The topic role this body was declared with, which fixes both the side
    /// brand and the robot time a publisher of it can express.
    const ROLE: TopicRole;
}