[glue] Introduce commonware-glue

.github/workflows/publish.yml

@@ -130,6 +130,11 @@ jobs:
       continue-on-error: true
       env:
         CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+    - name: Publish glue
+      run: cargo publish --manifest-path glue/Cargo.toml
+      continue-on-error: true
+      env:
+        CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
     - name: Publish chat
       run: cargo publish --manifest-path examples/chat/Cargo.toml
       continue-on-error: true

Cargo.toml

@@ -11,6 +11,7 @@ members = [
     "cryptography",
     "deployer",
     "formatting",
+    "glue",
     "macros",
     "macros/impl",
     "math",
@@ -114,6 +115,7 @@ commonware-consensus = { version = "2026.4.0", path = "consensus" }
 commonware-cryptography = { version = "2026.4.0", path = "cryptography", default-features = false }
 commonware-deployer = { version = "2026.4.0", path = "deployer", default-features = false }
 commonware-formatting = { version = "2026.4.0", path = "formatting", default-features = false }
+commonware-glue = { version = "2026.4.0", path = "glue" }
 commonware-invariants = { version = "2026.4.0", path = "invariants" }
 commonware-macros = { version = "2026.4.0", path = "macros", default-features = false }
 commonware-macros-impl = { version = "2026.4.0", path = "macros/impl" }

README.md

@@ -21,6 +21,7 @@ _Primitives are designed for deployment in adversarial environments. If you find
 * [consensus](./consensus/README.md): Order opaque messages in a Byzantine environment.
 * [cryptography](./cryptography/README.md): Generate keys, sign arbitrary messages, and deterministically verify signatures.
 * [deployer](./deployer/README.md): Deploy infrastructure across cloud providers.
+* [glue](./glue/README.md): Bootstrap applications with commonware primitive compositions.
 * [math](./math/README.md): Create and manipulate mathematical objects.
 * [p2p](./p2p/README.md): Communicate with authenticated peers over encrypted connections.
 * [parallel](./parallel/README.md): Parallelize fold operations with pluggable execution strategies.

glue/Cargo.toml

@@ -0,0 +1,61 @@
+[package]
+name = "commonware-glue"
+edition.workspace = true
+publish = true
+version.workspace = true
+license.workspace = true
+description = "Bootstrap applications with commonware primitive compositions."
+readme = "README.md"
+homepage.workspace = true
+repository = "https://github.com/commonwarexyz/monorepo/tree/main/glue"
+
+[lints]
+workspace = true
+
+[dependencies]
+arbitrary = { workspace = true, optional = true, features = ["derive"] }
+bytes.workspace = true
+commonware-actor.workspace = true
+commonware-codec.workspace = true
+commonware-consensus.workspace = true
+commonware-cryptography.workspace = true
+commonware-macros.workspace = true
+commonware-p2p.workspace = true
+commonware-parallel.workspace = true
+commonware-resolver.workspace = true
+commonware-runtime.workspace = true
+commonware-storage.workspace = true
+commonware-utils.workspace = true
+futures.workspace = true
+prometheus-client.workspace = true
+rand.workspace = true
+rand_core.workspace = true
+thiserror.workspace = true
+tracing.workspace = true
+
+[dev-dependencies]
+commonware-broadcast.workspace = true
+commonware-codec.workspace = true
+commonware-conformance.workspace = true
+commonware-consensus = { workspace = true, features = ["mocks"] }
+commonware-cryptography = { workspace = true, features = ["mocks"] }
+commonware-formatting.workspace = true
+commonware-p2p.workspace = true
+commonware-parallel.workspace = true
+commonware-resolver.workspace = true
+commonware-storage.workspace = true
+tracing-subscriber.workspace = true
+
+[features]
+test-utils = []
+arbitrary = [
+	"commonware-codec/arbitrary",
+	"commonware-consensus/arbitrary",
+	"commonware-cryptography/arbitrary",
+	"commonware-p2p/arbitrary",
+	"commonware-resolver/arbitrary",
+	"commonware-runtime/arbitrary",
+	"commonware-storage/arbitrary",
+	"commonware-utils/arbitrary",
+	"dep:arbitrary",
+]

glue/README.md

@@ -0,0 +1,9 @@
+# commonware-glue
+
+[![Crates.io](https://img.shields.io/crates/v/commonware-glue.svg)](https://crates.io/crates/commonware-glue)
+
+Bootstrap applications with commonware primitive compositions.
+
+## Status
+
+Stability varies by primitive. See [README](https://github.com/commonwarexyz/monorepo#stability) for details.

glue/conformance.toml

@@ -0,0 +1,7 @@
+["commonware_glue::stateful::db::p2p::handler::tests::conformance::CodecConformance<Request<mmr::Family>>"]
+n_cases = 65536
+hash = "44c363dc52376203a66269a71e13f7271c1a9beb1f8ee9dd9864a3ce7ae2c281"
+
+["commonware_glue::stateful::db::p2p::handler::tests::conformance::CodecConformance<Response<mmr::Family,u64,sha256::Digest>>"]
+n_cases = 65536
+hash = "7ca1ff124e5835f5be5d9b915233b9df088db121a0f5c3baa54b9ab8daf8bd78"

glue/src/lib.rs

@@ -0,0 +1,12 @@
+#![doc = include_str!("../README.md")]
+#![doc(
+    html_logo_url = "https://commonware.xyz/imgs/rustdoc_logo.svg",
+    html_favicon_url = "https://commonware.xyz/favicon.ico"
+)]
+
+commonware_macros::stability_scope!(ALPHA {
+    pub mod stateful;
+
+    #[cfg(any(test, feature = "test-utils"))]
+    pub mod simulate;
+});

glue/src/simulate/action.rs

@@ -0,0 +1,84 @@
+//! Simulation action types for testing.
+
+use commonware_cryptography::PublicKey;
+use commonware_p2p::simulated::Link;
+use commonware_runtime::deterministic;
+use std::time::Duration;
+
+/// Crash strategy for a simulation run.
+#[derive(Clone)]
+pub enum Crash<P: PublicKey> {
+    /// Periodically crash random validators and restart them after
+    /// a downtime period.
+    Random {
+        /// How often to trigger crashes.
+        frequency: Duration,
+        /// How long crashed validators stay offline.
+        downtime: Duration,
+        /// Number of validators to crash each time.
+        count: usize,
+    },
+
+    /// Delay some validators from starting until after N finalizations.
+    Delay {
+        /// Number of validators to delay.
+        count: usize,
+        /// Number of finalizations before starting delayed validators.
+        after: u64,
+    },
+
+    /// Time-indexed action schedule for precise control.
+    Schedule(Schedule<P>),
+}
+
+/// A time-ordered sequence of simulation actions.
+#[derive(Clone)]
+pub struct Schedule<P: PublicKey> {
+    /// Time-indexed actions.
+    pub events: Vec<(Duration, Action<P>)>,
+}
+
+impl<P: PublicKey> Schedule<P> {
+    /// Create an empty schedule.
+    pub const fn new() -> Self {
+        Self { events: vec![] }
+    }
+
+    /// Add an action at the given simulation time.
+    pub fn at(mut self, time: Duration, action: Action<P>) -> Self {
+        self.events.push((time, action));
+        self
+    }
+}
+
+impl<P: PublicKey> Default for Schedule<P> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// A single simulation action to apply at a specific time.
+#[derive(Clone)]
+pub enum Action<P: PublicKey> {
+    /// Update deterministic storage fault injection.
+    SetStorageFault(deterministic::FaultConfig),
+
+    /// Reset all directed links, restoring full connectivity with the given link.
+    Heal(Link),
+
+    /// Update a specific directed link by removing and re-adding it.
+    UpdateLink {
+        /// Source peer.
+        from: P,
+        /// Destination peer.
+        to: P,
+        /// New link configuration.
+        link: Link,
+    },
+
+    /// Crash a specific validator.
+    Crash(P),
+
+    /// Restart a previously crashed validator.
+    Restart(P),
+}

glue/src/simulate/engine.rs

@@ -0,0 +1,78 @@
+//! Engine definition trait and supporting types.
+
+use super::tracker::FinalizationUpdate;
+use commonware_cryptography::PublicKey;
+use commonware_p2p::simulated::{self, Oracle};
+use commonware_runtime::{deterministic, Handle, Quota};
+use commonware_utils::channel::mpsc;
+use std::future::Future;
+
+/// A registered p2p channel pair (sender, receiver).
+pub type ChannelPair<P> = (
+    simulated::Sender<P, deterministic::Context>,
+    simulated::Receiver<P>,
+);
+
+/// Arguments passed to [`EngineDefinition::init`].
+pub struct InitContext<'a, P: PublicKey> {
+    /// Labeled runtime context for this validator.
+    pub context: deterministic::Context,
+    /// Index of this validator in the participant list.
+    pub index: usize,
+    /// This validator's public key.
+    pub public_key: &'a P,
+    /// Network oracle for peer management.
+    pub oracle: &'a Oracle<P, deterministic::Context>,
+    /// Registered p2p channel pairs (same order as `channels()`).
+    pub channels: Vec<ChannelPair<P>>,
+    /// All participants in the simulation.
+    pub participants: &'a [P],
+    /// Channel for reporting finalization events to the harness.
+    pub monitor: mpsc::Sender<FinalizationUpdate<P>>,
+}
+
+/// Defines how to construct and start one validator's service stack.
+///
+/// The harness calls these methods for each validator in the simulation.
+/// The lifecycle is:
+/// 1. `channels()` -- declare which p2p channels are needed.
+/// 2. `init()` -- construct the engine (actors, archives, mailboxes).
+/// 3. `start()` -- start all actors, return a joinable handle.
+///
+/// On restart after a crash, `init()` and `start()` are called again
+/// with the same validator identity but a fresh runtime context (storage
+/// state is preserved by the deterministic runtime).
+pub trait EngineDefinition: Clone + Send + 'static {
+    /// The public key type used by this engine.
+    type PublicKey: PublicKey;
+
+    /// The constructed engine, passed from `init` to `start`.
+    type Engine: Send + 'static;
+
+    /// Per-validator state inspectable by property checkers.
+    type State: Send + Sync + 'static;
+
+    /// The participants for this simulation.
+    ///
+    /// Called once by the harness to determine the validator set. The engine
+    /// is responsible for generating keys and any associated state (signing
+    /// schemes, databases, etc.) during construction.
+    fn participants(&self) -> Vec<Self::PublicKey>;
+
+    /// Which p2p channels to register for each validator.
+    ///
+    /// Returns `(channel_id, quota)` pairs. The harness registers each
+    /// on the simulated oracle and passes sender/receiver pairs to
+    /// `init` in the same order.
+    fn channels(&self) -> Vec<(u64, Quota)>;
+
+    /// Construct the engine for a single validator.
+    fn init(
+        &self,
+        ctx: InitContext<'_, Self::PublicKey>,
+    ) -> impl Future<Output = (Self::Engine, Self::State)> + Send;
+
+    /// Start all actors in the engine. Returns a handle the harness
+    /// can join on (or abort on crash).
+    fn start(engine: Self::Engine) -> Handle<()>;
+}