phoxal_runtime_contract/
lib.rs

1//! Stable data crossing Phoxal process boundaries.
2//!
3//! This crate deliberately contains no participant runner, bus transport,
4//! command-line parser, or project compiler. It is the shared vocabulary used
5//! by framework participants, the framework supervisor, and clients such as
6//! `phoxal-cli`.
7//!
8//! There is no crate-root facade: every public item is reached through the
9//! module that owns its contract, so a type has exactly one path and an import
10//! already says which process-boundary contract it belongs to.
11//!
12//! - [`identity`] - the execution, producer, and timeline identities that reach
13//!   the wire.
14//! - [`version`] - the version identities two binaries compare to establish
15//!   that they speak the same contracts.
16//! - [`metadata`] - the record every participant binary embeds at compile time,
17//!   and its strict parser.
18//! - [`emit`] - the one sanctioned writer of that record, in both of its
19//!   evaluation modes.
20//! - [`rendezvous`] - the shared host paths and advisory locking through which
21//!   a client and the one execution supervisor find and fence each other.
22//! - [`wire_schema`] - the deterministic model of the shapes those contracts
23//!   put on the wire, which compatibility CI checks against published
24//!   baselines.
25//! - [`contract_surface`] - the record model each contract-owning crate states
26//!   its whole boundary in, built out of those shapes.
27
28pub mod contract_surface;
29pub mod emit;
30pub mod identity;
31pub mod metadata;
32pub mod rendezvous;
33pub mod version;
34pub mod wire_schema;
35
36/// The contract surface this crate owns: the participant-metadata document
37/// every binary embeds.
38///
39/// Not public API. It exists so compatibility CI can read a crate's declared
40/// process boundary out of the crate itself, and its shape may change with the
41/// checker.
42#[doc(hidden)]
43pub mod __compat {
44    use crate::contract_surface::{ContractRecord, ContractSurface};
45    use crate::metadata::ParticipantMetadata;
46    use crate::wire_schema::DescribeWire;
47
48    /// The canonical rendering of this crate's contract surface.
49    #[must_use]
50    pub fn contract_surface() -> String {
51        ContractSurface::new([ContractRecord::document(
52            "ParticipantMetadata",
53            crate::metadata::PARTICIPANT_METADATA_SCHEMA_TAG,
54            ParticipantMetadata::wire_schema(),
55        )])
56        .canonical_json()
57    }
58
59    #[cfg(test)]
60    mod tests {
61        use super::contract_surface;
62
63        /// The surface is one JSON document, it names the embedded document's
64        /// tag, and two calls produce the same bytes - which is what lets a
65        /// checker compare it with a stored baseline by string equality.
66        #[test]
67        fn the_surface_is_deterministic_json_naming_the_metadata_document() {
68            let rendered = contract_surface();
69            serde_json::from_str::<serde_json::Value>(&rendered).expect("the surface is JSON");
70            assert_eq!(contract_surface(), rendered);
71            assert!(
72                rendered.contains(crate::metadata::PARTICIPANT_METADATA_SCHEMA_TAG),
73                "{rendered}"
74            );
75            assert!(rendered.contains(r#""record":"document""#), "{rendered}");
76            assert!(rendered.contains("config_schema"), "{rendered}");
77        }
78    }
79}
phoxal_runtime_contract/lib.rs

phoxal_runtime_contract/
lib.rs
