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//! - [`origin`] - the boot-anchored origin of one real execution.
21//! - [`rendezvous`] - the shared host paths and advisory locking through which
22//!   a client and the one execution supervisor find and fence each other.
23//! - [`wire_schema`] - the deterministic model of the shapes those contracts
24//!   put on the wire, which compatibility CI checks against published
25//!   baselines.
26//! - [`contract_surface`] - the record model each contract-owning crate states
27//!   its whole boundary in, built out of those shapes.
28
29pub mod clock;
30pub mod contract_surface;
31pub mod emit;
32pub mod identity;
33pub mod metadata;
34pub mod origin;
35pub mod rendezvous;
36pub mod version;
37pub mod wire_schema;
38
39/// The contract surface this crate owns: the participant-metadata document
40/// every binary embeds.
41///
42/// Not public API. It exists so compatibility CI can read a crate's declared
43/// process boundary out of the crate itself, and its shape may change with the
44/// checker.
45#[doc(hidden)]
46pub mod __compat {
47    use crate::contract_surface::{ContractRecord, ContractSurface};
48    use crate::metadata::ParticipantMetadata;
49    use crate::wire_schema::DescribeWire;
50
51    /// The canonical rendering of this crate's contract surface.
52    #[must_use]
53    pub fn contract_surface() -> String {
54        ContractSurface::new([ContractRecord::document(
55            "ParticipantMetadata",
56            crate::metadata::PARTICIPANT_METADATA_SCHEMA_TAG,
57            ParticipantMetadata::wire_schema(),
58        )])
59        .canonical_json()
60    }
61
62    #[cfg(test)]
63    mod tests {
64        use super::contract_surface;
65
66        /// The surface is one JSON document, it names the embedded document's
67        /// tag, and two calls produce the same bytes - which is what lets a
68        /// checker compare it with a stored baseline by string equality.
69        #[test]
70        fn the_surface_is_deterministic_json_naming_the_metadata_document() {
71            let rendered = contract_surface();
72            serde_json::from_str::<serde_json::Value>(&rendered).expect("the surface is JSON");
73            assert_eq!(contract_surface(), rendered);
74            assert!(
75                rendered.contains(crate::metadata::PARTICIPANT_METADATA_SCHEMA_TAG),
76                "{rendered}"
77            );
78            assert!(rendered.contains(r#""record":"document""#), "{rendered}");
79            assert!(rendered.contains("config_schema"), "{rendered}");
80        }
81    }
82}
phoxal_runtime_contract/lib.rs

phoxal_runtime_contract/
lib.rs
