Trait ContractBody

Source

pub trait ContractBody:
    Serialize
    + DeserializeOwned
    + Clone
    + Send
    + Sync
    + 'static {
    type Api: ApiVersion;

    const FAMILY: &'static str;
    const SCHEMA_ID: &'static str;
    const TOPIC: &'static str;
}

Expand description

The contract primitive traits, re-exported from the phoxal-bus crate (the ABI floor) so they stay addressable at phoxal_api::ApiVersion / phoxal_api::ContractBody.

ApiVersion is the marker trait identifying one dated API version (D60), implemented only by the zero-variant enum Api {} that phoxal_api_tree! generates inside each version module; its ID is the dated module name ("y2026_1") and is carried in bus metadata as informational provenance. 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 family/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/FAMILY/SCHEMA_ID/TOPIC. Runtime decode compatibility keys off SCHEMA_ID; its serde encoding is the wire payload, with no version envelope (D62). A version-local wire body: a plain serde type bound to exactly one ApiVersion and one contract family/topic (D61).

Every body declared inside a phoxal_api_tree! node gets a generated impl. Handles, SetupContext builders, and the Service/Driver derive assertions all key off Api/FAMILY/TOPIC, which is how a body from the wrong API version is rejected at compile time.

The serde encoding of an implementor is the wire payload; there is no version envelope (D62). Version and family travel as bus metadata, derived from Api and FAMILY.

Runtime decode compatibility keys off SCHEMA_ID, not the graph API version. SCHEMA_ID is a normalized hash of the body’s transitive wire shape. The canonical hash input is phoxal.schema/v0\n followed by this grammar:

body    = unit | newtype | tuple | struct | enum
struct  = "struct{" field* "}"
field   = "f" byte_len ":" utf8_name "=" ty ";"
enum    = "enum(" repr "){" variant* "}"
repr    = "external" | "internal(tag=" name ")"
        | "adjacent(tag=" name ",content=" name ")" | "untagged"
variant = "v" byte_len ":" utf8_name "=" payload ";"
payload = unit | "newtype(" ty ")" | tuple | struct
newtype = "newtype(" ty ")"
tuple   = "tuple(" (ty ";")* ")"
ty      = nil | bool | string | bytes | integer | float | option | seq | array
        | map | tuple | body
integer = "u8" | "u16" | "u32" | "u64" | "u128"
        | "i8" | "i16" | "i32" | "i64" | "i128"
float   = "f32" | "f64"
option  = "option(" ty ")"
seq     = "seq(" ty ")"
array   = "array[" decimal_len "](" ty ")"
map     = "map(" ty "," ty ")"
name    = byte_len ":" utf8_name

Fields stay in declared order and use their serde wire names, including rename and rename_all. Enums include serde representation mode, variant wire names, and payload shapes. Nested API-tree structs and enums are expanded transitively, with generic type parameters substituted by concrete type arguments before expansion. Only understood serde attributes and known wire-neutral attributes such as doc comments and simple derives are accepted. Non-wire details such as Rust type identifiers when the wire shape has already been expanded are excluded. The displayed id is lower-hex sha256(canonical_string), truncated to the first 16 hex characters.

Required Associated Constants§

Source

const FAMILY: &'static str

Canonical contract family id: the ::-joined node path plus the body type name, with dynamic variables excluded, e.g. "drive::State" or "component::motor::Command".

Source

const SCHEMA_ID: &'static str

Per-contract compatibility id: lower-hex SHA-256 of the canonical transitive wire-shape string, truncated to 16 hex characters.

Source

const TOPIC: &'static str

Versionless topic key: the /-joined node path plus the topic leaf, with each dynamic node contributing a {var} placeholder, e.g. "drive/state" or "component/{instance}/motor/{capability}/command". The concrete key is produced by the api-local topic builder, which fills the placeholders.

Required Associated Types§

Source

type Api: ApiVersion

The single API version this body belongs to. Two bodies from different versions have different Api, so the type system keeps them apart.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

ContractBody

Trait ContractBody Copy item path

Required Associated Constants§

const FAMILY: &'static str

const SCHEMA_ID: &'static str

const TOPIC: &'static str

Required Associated Types§

type Api: ApiVersion

Dyn Compatibility§

Implementors§

impl ContractBody for Clock

const FAMILY: &'static str = "simulation::Clock"

const SCHEMA_ID: &'static str = "1a4038c598a3dac2"

const TOPIC: &'static str = "simulation/clock"

type Api = Api

impl ContractBody for phoxal_api::y2026_1::mission::Command

const FAMILY: &'static str = "mission::Command"

const SCHEMA_ID: &'static str = "68bc120004663097"

const TOPIC: &'static str = "mission/command"

type Api = Api

impl ContractBody for phoxal_api::y2026_1::power::Command

const FAMILY: &'static str = "power::Command"

const SCHEMA_ID: &'static str = "dcdefd20c4c485ed"

const TOPIC: &'static str = "power/command"

type Api = Api

impl ContractBody for phoxal_api::y2026_1::component::motor::Command

const FAMILY: &'static str = "component::motor::Command"

const SCHEMA_ID: &'static str = "790522170ea1f8f4"

const TOPIC: &'static str = "component/{instance}/motor/{capability}/command"

type Api = Api

impl ContractBody for phoxal_api::y2026_1::component::led::Command

const FAMILY: &'static str = "component::led::Command"

const SCHEMA_ID: &'static str = "e05d002af8729ff0"

const TOPIC: &'static str = "component/{instance}/led/{capability}/command"

type Api = Api

impl ContractBody for Contact

const FAMILY: &'static str = "simulation::Contact"

const SCHEMA_ID: &'static str = "200769283abb0336"

const TOPIC: &'static str = "simulation/contact"

type Api = Api

impl ContractBody for Control

const FAMILY: &'static str = "simulation::Control"

const SCHEMA_ID: &'static str = "fcbdfc9e6d42d4e9"

const TOPIC: &'static str = "simulation/control"

type Api = Api

impl ContractBody for Detections

const FAMILY: &'static str = "perception::Detections"

const SCHEMA_ID: &'static str = "718008c4c81fe4e2"

const TOPIC: &'static str = "perception/detections"

type Api = Api

impl ContractBody for EmergencyStopRequest

const FAMILY: &'static str = "safety::EmergencyStopRequest"

const SCHEMA_ID: &'static str = "5ff421d098148b38"

const TOPIC: &'static str = "safety/estop"

type Api = Api

impl ContractBody for Event

const FAMILY: &'static str = "logs::Event"

const SCHEMA_ID: &'static str = "7cb8d62644f449bc"

const TOPIC: &'static str = "logs/{participant_id}"

type Api = Api

impl ContractBody for phoxal_api::y2026_1::component::camera::Frame

const FAMILY: &'static str = "component::camera::Frame"

const SCHEMA_ID: &'static str = "dfb562871eedbb45"

const TOPIC: &'static str = "component/{instance}/camera/{capability}/frame"

type Api = Api

impl ContractBody for phoxal_api::y2026_1::component::depth::Frame

const FAMILY: &'static str = "component::depth::Frame"

const SCHEMA_ID: &'static str = "7fe2cbf61a5f574d"

const TOPIC: &'static str = "component/{instance}/depth/{capability}/frame"

type Api = Api

impl ContractBody for phoxal_api::y2026_1::component::microphone::Frame

const FAMILY: &'static str = "component::microphone::Frame"

const SCHEMA_ID: &'static str = "b0a3f1c7894ca41c"

const TOPIC: &'static str = "component/{instance}/microphone/{capability}/frame"

type Api = Api

impl ContractBody for Frontiers

const FAMILY: &'static str = "explore::Frontiers"

const SCHEMA_ID: &'static str = "042440272ebda4cb"

const TOPIC: &'static str = "explore/frontiers"

type Api = Api

Trait ContractBody