net-mesh-sdk 0.26.0

//! MeshOS SDK — daemon-author surface.
//!
//! This is the customer-facing entry point for writing daemons
//! that participate in MeshOS supervision. The actual
//! implementation lives in the substrate at
//! `net::adapter::net::behavior::meshos::sdk`; this module
//! re-exports the SDK types under a clean `net_sdk::meshos::*`
//! path so consumers don't reach into substrate internals.
//!
//! # Surface
//!
//! - [`MeshOsDaemonSdk`] — one-call entry point. Wraps a
//!   [`MeshOsRuntime`] with daemon-control routing; provides
//!   `register_daemon(...) -> MeshOsDaemonHandle`.
//! - [`MeshOsDaemonHandle`] — per-daemon handle. Owns the
//!   control-event receiver, capability-publish surface,
//!   graceful-shutdown sequence, and read-only metadata view.
//! - [`MetadataView`] / [`MaintenanceStateView`] — read-only
//!   cluster context the daemon can observe.
//! - [`SdkError`] — operator-readable error surface with the
//!   `<<meshos-sdk-kind:KIND>>MSG` discriminator format every
//!   cross-language SDK uses.
//! - Re-exported substrate types: [`DaemonControl`],
//!   [`DaemonHealth`], [`MeshDaemon`], [`CapabilitySet`],
//!   [`EntityKeypair`], [`MeshOsConfig`], [`MeshOsRuntime`].
//!
//! # Daemon-author quickstart
//!
//! ```ignore
//! use net_sdk::meshos::{
//!     CapabilitySet, DaemonControl, DaemonHealth, EntityKeypair, MeshDaemon,
//!     MeshOsConfig, MeshOsDaemonSdk,
//! };
//! use std::sync::Arc;
//!
//! struct TelemetryDaemon { /* … */ }
//!
//! impl MeshDaemon for TelemetryDaemon {
//!     fn name(&self) -> &str { "telemetry" }
//!     fn requirements(&self) -> _ { Default::default() }
//!     fn process(&mut self, _event: &_) -> _ { Ok(vec![]) }
//!     fn health(&self) -> DaemonHealth { DaemonHealth::Healthy }
//! }
//!
//! # async fn run(dispatcher: Arc<impl _>) -> Result<(), Box<dyn std::error::Error>> {
//! let sdk = MeshOsDaemonSdk::start(MeshOsConfig::default(), dispatcher);
//! let mut handle = sdk.register_daemon(
//!     Box::new(TelemetryDaemon { /* … */ }),
//!     EntityKeypair::generate(),
//! )?;
//!
//! while let Some(ev) = handle.next_control().await {
//!     match ev {
//!         DaemonControl::Shutdown { .. } => break,
//!         DaemonControl::BackpressureOn { level } => { /* throttle */ }
//!         _ => {}
//!     }
//! }
//!
//! handle.graceful_shutdown(std::time::Duration::from_secs(5)).await?;
//! sdk.shutdown().await?;
//! # Ok(())
//! # }
//! ```
//!
//! # Macro convenience
//!
//! The substrate re-exports a `daemon_main!` macro that
//! collapses the boilerplate into a single block — see the
//! macro's own documentation in
//! `net::adapter::net::behavior::meshos::sdk::daemon_main`.
//!
//! # Non-goals
//!
//! Per `MESHOS_SDK_PLAN.md`'s locked decisions, this SDK is
//! **daemon-side only**:
//!
//! - No placement / replica / scheduler APIs.
//! - No admin-event issuance (drain, cordon, maintenance, etc).
//! - No "control MeshOS" surfaces (avoid lists, backpressure
//!   tuning, scheduler config).
//! - No federated-execution / MeshDB-query plumbing — those
//!   belong to the (forthcoming) Deck SDK.
//!
//! Operator tooling lives in `DECK_SDK_PLAN.md`'s surface.

// Re-export the substrate-side SDK types under a clean
// `net_sdk::meshos::*` path. The implementation lives in
// `net::adapter::net::behavior::meshos::sdk` — this module is
// the customer-facing seam.
pub use net::adapter::net::behavior::meshos::{
    DaemonControlRouter, MaintenanceStateView, MeshOsDaemonHandle, MeshOsDaemonSdk, MetadataView,
    SdkError, SdkRoutingDispatcher, DEFAULT_CONTROL_CHANNEL_CAPACITY, DEFAULT_GRACEFUL_SHUTDOWN,
};

// Supporting types daemon authors need.
pub use net::adapter::net::behavior::capability::CapabilitySet;
pub use net::adapter::net::behavior::meshos::{
    ActionDispatcher, DispatchError, HealthProbe, InventoryProbe, LocalityProbe, LogLevel, LogLine,
    LoggingDispatcher, MeshOsConfig, MeshOsRuntime, PeerInventory, ProbeRegistry,
    RuntimeShutdownError, RuntimeStats,
};
// Event-source supporting types — exposed so test / demo
// callers can write probes that report `NodeHealth` values
// and so consumers wiring custom event sources can match
// against `NodeId` in the public surface.
pub use net::adapter::net::behavior::meshos::{NodeHealth, NodeId};

// Direct event injection — for in-process / test / demo
// consumers that want to publish events into the runtime's
// fold without going through a source converter. Daemon
// authors don't need these; the daemon-side SDK exposes
// `publish_log` and `next_control` and refuses every other
// event-issuance path by design.
pub use net::adapter::net::behavior::meshos::{
    ChainId, MeshOsEvent, MeshOsHandle, MeshOsHandleError, PlacementIntent, ReplicaUpdate,
};
pub use net::adapter::net::compute::{
    DaemonControl, DaemonError, DaemonHealth, DaemonHostConfig, MeshDaemon,
};
pub use net::adapter::net::EntityKeypair;

// Production RedEX-backed chain appenders. Operators wire
// these when constructing a runtime via
// `MeshOsRuntime::start_with_all_chains(...)` to persist admin
// audit, log, and failure history to cluster-lifetime storage.
pub use net::adapter::net::behavior::meshos::{
    RedexAdminAuditAppender, RedexFailureAppender, RedexLogAppender,
};

// Migration-abort dispatcher seam. Operators wire the
// `OrchestratorMigrationAborter` adapter so an
// `AdminEvent::KillMigration` chain commit actually aborts the
// in-flight migration on every node hosting it.
pub use net::adapter::net::behavior::meshos::{
    MigrationAbortError, MigrationAborter, OrchestratorMigrationAborter,
};

// Migration-snapshot source seam. Operators wire the
// `OrchestratorMigrationSnapshotSource` so the snapshot's
// `in_flight_migrations` field reflects the local
// `MigrationOrchestrator`'s state, letting the ICE blast-radius
// preview enumerate the daemon a `KillMigration` would affect.
pub use net::adapter::net::behavior::meshos::{
    MigrationPhaseSnapshot, MigrationSnapshot, MigrationSnapshotSource,
    OrchestratorMigrationSnapshotSource,
};