phoxal

The Phoxal robot framework as one crate: a coherent, manifest-driven stack for production-oriented autonomous robots — typed bus, simulation-first validation, and a complete platform-runtime contract set, with the same conventions from authoring to deployment.

[dependencies]
phoxal = "0.4"

Modules

Module	What it is
[`phoxal::bus`]	Typed Zenoh transport. `Bus::{publish, subscriber, request, responder}` take a typed `Topic<Kind>`; payloads are plain `serde` data; schema identity + version travel in a `BusMetadata` attachment, so wire mismatches are loud decode errors.
[`phoxal::model`]	Authored manifest schemas: `robot.yaml`, `structure.urdf`, `component.yaml`, `simulation.yaml`. `model::v1::Robot` is the resolved superset.
[`phoxal::spatial`]	Geometry, frames, transforms, risk model.
[`phoxal::api`]	The typed bus wire contracts under `phoxal::api::v1::<domain>` (`drive`, `localize`, `mission`, …, plus `component`, `presence`, `simulation`). Topics are built with the fluent generated builder `phoxal::api::v1::topic`, e.g. `topic::new().v1().drive().target()` → `Topic<PubSub<Target>>`. Instance ids are method arguments (`component("base").motor("left").command()`); pass `phoxal::bus::topic::ANY` for subscribe wildcards (`component(ANY).motor(ANY).command()`). The leaf return type carries the payload, so the bus rejects a wrong payload at compile time.
[`phoxal::runtime`]	The `Runtime` trait, `execute()` bootstrap, logical clock, runtime context, decision logging.
[`phoxal::scenario`]	Webots-backed validation harness (feature `scenario`).

Writing a user runtime

Implement the phoxal::runtime::Runtime trait and hand it to execute(); the contracts you consume/produce come from phoxal::api::*:

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    phoxal::runtime::execute::<MyRuntime>().await
}

A runtime reads and writes contracts through the typed Io with fluent topics:

use phoxal::api::v1::{topic, drive::Target, drive::State};

// subscribe (wildcard ok): map (at_ns, payload) into the runtime's Input
io.subscribe_topic(topic::new().v1().drive().target(), InputPolicy::latest(), Input::Target).await?;

// publish: the timestamp is an argument, the payload is plain data
let state = io.publisher_topic(topic::new().v1().drive().state()).await?;
state.put(now_ns, &State { /* … */ }).await?;

The platform runtime binaries (phoxal-runtime-<name>) ship as container images, not crates — they depend on this crate but are not published here.

Features

scenario — the Webots validation harness (off by default so production runtime images don't carry test code).

Status

Pre-1.0, building in public. The API is a single version-first axis, phoxal::api::v1; a breaking re-cut of the whole contract surface becomes api::v2, while an individual contract's payload revision bumps its per-leaf version in the topic_tree!. Breaking changes are loud, not quiet.

License