README.md (3824B)
1 # radroots_protocol 2 3 `radroots_protocol` defines the passive, versioned wire contracts shared by 4 Radroots processes and language bindings. It is a `no_std + alloc` foundation 5 crate: it validates schema identities and contract catalogs, but performs no 6 network, storage, signing, scheduling, or process-lifecycle work. 7 8 The crate is pre-release and its Cargo version is frozen at `0.1.0-alpha` until 9 explicitly changed. Cargo package versions are independent from the version 10 numbers embedded in wire and schema contracts. 11 12 ## Contract surface 13 14 | Module | Authority | 15 | --- | --- | 16 | `capability::v1` | transport capabilities, maturity, and availability | 17 | `error::v1` | stable, redaction-safe error reports and recovery guidance | 18 | `event::v1` | event-kind catalogs and the serialized trade-state vocabulary | 19 | `runtime::v1` | operation descriptors, risk, approval, idempotency, and effects | 20 | `radrootsd::transport_publish::v5` | daemon transport-publish request, job, outcome, and capability DTOs | 21 | `schema` | schema IDs, module generations, descriptors, and aggregate registries | 22 23 All serialized DTOs live below an explicit generation module. The crate root 24 does not reexport individual DTOs, so consumers must name the contract version 25 they use. 26 27 ## Features 28 29 | Feature | Default | Effect | 30 | --- | --- | --- | 31 | `std` | yes | implements standard-library error integration and enables `serde?/std` | 32 | `serde` | yes | derives serialization and deserialization for wire-contract types | 33 34 Disabling default features leaves the catalog and structural validation APIs 35 available with `alloc` only. Enable `serde` without `std` for portable encoded 36 DTOs. 37 38 ## Validate the aggregate contract 39 40 ```rust 41 use radroots_protocol::{capability, event, runtime, schema}; 42 43 capability::v1::validate_catalog(capability::v1::CATALOG).unwrap(); 44 event::v1::validate_catalog(event::v1::CATALOG).unwrap(); 45 event::v1::validate_trade_state_vocabulary(event::v1::TRADE_STATE_VOCABULARY) 46 .unwrap(); 47 runtime::v1::validate_catalog(runtime::v1::CATALOG).unwrap(); 48 49 let registry = schema::protocol_v1_registry().unwrap(); 50 assert!(!registry.is_empty()); 51 ``` 52 53 For a runnable version, see 54 [`examples/inspect_contract.rs`](examples/inspect_contract.rs). 55 56 ## Serialization and trust boundaries 57 58 Wire representations are stable only within their named generation. A caller 59 must deserialize into the intended version, run the module's structural 60 validation, and apply its own authorization and policy checks before acting on 61 the data. Successful deserialization alone does not make input trusted. 62 63 Stable error reports intentionally carry only safe messages and bounded detail 64 values. Use `error::v1::ErrorReport::redacted_from_source` at sensitive 65 boundaries; do not copy secrets, credentials, raw upstream errors, or private 66 payloads into protocol DTOs. 67 68 ## Side effects, cancellation, and commit points 69 70 This crate has no side effects, asynchronous work, cancellation mechanism, or 71 commit point. Runtime operation descriptors describe those properties; they do 72 not execute operations. The owning SDK, daemon, storage, signing, or transport 73 implementation must define cancellation behavior and must not report a commit 74 until its own durable boundary has succeeded. 75 76 ## Intended consumers 77 78 The direct consumers are Radroots domain crates, SDK and daemon runtimes, 79 transport/storage/signing boundaries, generated bindings, and conformance 80 tools. Applications should normally enter through `radroots` or 81 `radroots_sdk`, using this crate directly only when implementing or inspecting 82 a versioned boundary. 83 84 The package charter is the 85 [Release V1 specification](../../contracts/crates/release_v1/radroots_crates_release_v1.toml). 86 The reviewed Rust surface is recorded in the 87 [public API baseline](../../contracts/api_baselines/radroots_protocol.txt).