phoxal 0.12.0

Phoxal — production-oriented autonomous robot framework (engine, model, typed bus, contracts).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

//! # phoxal
//!
//! The Phoxal robot framework as one crate (greenfield rewrite —
//! `tmp/framework-rewrite`). Production-oriented autonomous robots:
//! manifest-driven, simulation-first, typed bus, single API version per graph.
//!
//! Authoring surface:
//!
//! ```ignore
//! use phoxal::api::y2026_1 as api;
//! use phoxal::prelude::*;
//!
//! #[derive(phoxal::Runtime)]
//! #[phoxal(id = "avoid-obstacles", api = y2026_1)]
//! struct AvoidObstacles {
//!     state:  Latest<api::drive::State>,
//!     target: Publisher<api::drive::Target>,
//! }
//!
//! #[phoxal::runtime]
//! impl AvoidObstacles {
//!     #[setup]
//!     async fn setup(ctx: &mut SetupContext<Self>) -> Result<Self> { /* … */ }
//!     #[step(hz = 50)]
//!     async fn step(&mut self, step: StepContext) -> Result<()> { Ok(()) }
//! }
//!
//! fn main() -> phoxal::Result<()> { phoxal::run::<AvoidObstacles>() }
//! ```
//!
//! Module map:
//! - [`api`] — dated API-version modules (`y2026_1`, …), version-local wire
//!   bodies, `ContractBody`/`ApiVersion`, and api-local topic builders, all
//!   generated by [`phoxal_api_tree!`](macro@phoxal_macros::phoxal_api_tree).
//! - [`bus`] — the Zenoh-native `bus_abi` boundary: key scheme, codec, metadata,
//!   and the body-typed handles ([`Publisher`](bus::Publisher),
//!   [`Subscriber`](bus::Subscriber), [`Latest`](bus::Latest)).
//! - [`runtime`] — the static metadata traits, `SetupContext`, the clock +
//!   scheduler, and the runner (`run` / `tokio::run`).
//! - [`model`] — authored manifest schemas (`robot.yaml`, …).
//! - [`util`] — shared helpers.

// Generated macro output refers to the framework as `::phoxal::…`; make that path
// resolve to this crate so the macros work both inside and outside the engine.
extern crate self as phoxal;

pub mod api;
pub mod bus;
pub mod model;
pub mod runtime;
pub mod util;

/// The framework result type (`anyhow`-backed). Authoring code uses bare
/// `Result<T>` via the [`prelude`].
pub use anyhow::Result;

/// Derive the static metadata for a runtime struct. See the crate docs.
pub use phoxal_macros::Runtime;

/// The bare `#[phoxal::runtime]` attribute for a runtime's inherent impl.
pub use phoxal_macros::runtime;

#[doc(inline)]
pub use phoxal_macros::phoxal_api_tree;

/// Run a runtime to completion on a framework-owned blocking Tokio runtime.
///
/// This is the default binary entrypoint:
/// `fn main() -> phoxal::Result<()> { phoxal::run::<Runtime>() }`.
pub use runtime::run;

/// Async host runner entrypoints for custom Tokio mains
/// (`phoxal::tokio::run::<Runtime>().await`).
pub mod tokio {
    #[doc(inline)]
    pub use crate::runtime::run_async as run;
}

/// Everything a runtime author imports with `use phoxal::prelude::*;`.
pub mod prelude {
    pub use crate::Result;
    pub use crate::bus::{Latest, Publisher, Querier, QueryError, ServerResult, Subscriber};
    pub use crate::runtime::{LogicalTime, SetupContext, ShutdownContext, Snapshot, StepContext};
}