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

phoxal_runtime_contract/
lib.rs
