sdk

commit 55af5f70f803c699bab123f5f3942b4e4da448f1
parent 03c568672034f9d33e896c9585eaea2362c664d6
Author: triesap <tyson@radroots.org>
Date:   Mon,  3 Aug 2026 10:14:13 +0000

sdk: make the SDK std-only and finalize root modules

- expose only the governed client and error root types
- establish clone send and sync client handle contracts
- retain explicit public module ownership without broad reexports
- verify rustdoc architecture and public API boundaries

Diffstat:
M
crates/sdk/src/client.rs
 | 
18
++++++++++++++++++
M
crates/sdk/src/error.rs
 | 
22
++++++++++++++++++++++
M
crates/sdk/src/lib.rs
 | 
8
++++++--
M
crates/sdk/tests/package_boundary.rs
 | 
17
+++++++++++++++++

4 files changed, 63 insertions(+), 2 deletions(-)
diff --git a/crates/sdk/src/client.rs b/crates/sdk/src/client.rs
@@ -1 +1,19 @@
 //! Client construction and lifecycle.
+
+/// Cloneable handle to a composed Radroots client.
+///
+/// Construction is intentionally introduced by the ordered builder
+/// composition step; this type establishes the durable root identity only.
+#[derive(Clone, Debug)]
+pub struct Client {
+    _private: (),
+}
+
+/// Explicit composition boundary for a [`Client`].
+///
+/// The lower capability fields and construction methods are added by the
+/// ordered composition step.
+#[derive(Debug)]
+pub struct ClientBuilder {
+    _private: (),
+}
diff --git a/crates/sdk/src/error.rs b/crates/sdk/src/error.rs
@@ -1 +1,23 @@
 //! SDK-owned error boundary.
+
+use std::{error, fmt};
+
+/// Narrow SDK error boundary.
+///
+/// Concrete variants are introduced with the owning operation contracts.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub struct Error {
+    _private: (),
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("Radroots SDK operation failed")
+    }
+}
+
+impl error::Error for Error {}
+
+/// SDK result alias.
+pub type Result<T> = std::result::Result<T, Error>;
diff --git a/crates/sdk/src/lib.rs b/crates/sdk/src/lib.rs
@@ -1,7 +1,8 @@
 //! Host-neutral asynchronous client engine for Radroots.
 //!
-//! This checkpoint establishes the final package and module ownership
-//! boundary. Client behavior is introduced through the ordered SDK refactor.
+//! Advanced hosts compose capabilities through [`ClientBuilder`] and operate
+//! through a cloneable [`Client`]. All fallible root operations use [`Result`]
+//! and the SDK-owned [`Error`] boundary.
 
 #![forbid(unsafe_code)]
 
@@ -16,3 +17,6 @@ pub mod storage;
 pub mod sync;
 pub mod trade;
 pub mod transport;
+
+pub use crate::client::{Client, ClientBuilder};
+pub use crate::error::{Error, Result};
diff --git a/crates/sdk/tests/package_boundary.rs b/crates/sdk/tests/package_boundary.rs
@@ -54,6 +54,23 @@ fn root_declares_exact_final_module_skeleton() {
     ]);
     assert_eq!(actual, expected);
     assert!(!ROOT.contains("no_std"));
+    assert_eq!(ROOT.matches("pub use crate::").count(), 2);
+    assert!(ROOT.contains("pub use crate::client::{Client, ClientBuilder};"));
+    assert!(ROOT.contains("pub use crate::error::{Error, Result};"));
+    assert!(!ROOT.contains("pub use radroots_"));
+}
+
+#[test]
+fn root_types_have_the_required_std_contracts() {
+    fn assert_client<T: Clone + Send + Sync>() {}
+    fn assert_builder<T: Send + Sync>() {}
+    fn assert_error<T: std::error::Error + Send + Sync + 'static>() {}
+
+    assert_client::<radroots_sdk::Client>();
+    assert_builder::<radroots_sdk::ClientBuilder>();
+    assert_error::<radroots_sdk::Error>();
+    let result: radroots_sdk::Result<()> = Ok(());
+    assert!(result.is_ok());
 }
 
 fn dependency_names(manifest: &str) -> BTreeSet<&str> {