Struct MeshOsRuntime 

pub struct MeshOsRuntime { /* private fields */ }

One-stop entry point. Spawns the loop + executor as tokio tasks; exposes the publish handle, snapshot reader, and executor stats; drives a clean shutdown via Self::shutdown.

Implementations

impl MeshOsRuntime

pub fn start<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, ) -> Self

Spawn the loop + executor and return a live runtime. The dispatcher is whatever wires the action variants to the substrate-side mechanics (DaemonRegistry, migration orchestrator, admin chain commits). Tests can pass an super::executor::LoggingDispatcher for the log-only path.

For non-default wiring (admin verifier, chain appenders, migration aborter, …) use MeshOsRuntimeBuilder instead — the start_with_* stair-step constructors below are backward-compat forwarders that flatten the builder’s with_* calls into one positional signature.

pub fn start_with_probes<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, probes: ProbeRegistry, ) -> Self

Like Self::start, but accepts a pre-populated ProbeRegistry. The registry is cloned and retained — consumers can keep adding probes after start_with_probes via Self::add_locality_probe / Self::add_health_probe or by holding their own clone of the registry.

pub fn start_full<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, probes: ProbeRegistry, scheduler: SchedulerRegistry, ) -> Self

Like Self::start, but accepts both probe and scheduler registries.

pub fn start_with_daemon_registry<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, probes: ProbeRegistry, scheduler: SchedulerRegistry, daemon_registry: Arc<DaemonRegistry>, ) -> Self

Most general entry point. Accepts probe + scheduler registries AND a pre-built DaemonRegistry the runtime will attach its lifecycle sink to. start, start_with_probes, and start_full build new registries internally; callers that need to share a registry with other subsystems pass theirs in here.

pub fn start_with_options<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, probes: ProbeRegistry, scheduler: SchedulerRegistry, daemon_registry: Arc<DaemonRegistry>, control_sink: Option<Arc<dyn ControlSink>>, ) -> Self

Most-general constructor with an optional super::control::ControlSink for fan-out of MeshOsControl events. The SDK uses this path; substrate code that doesn’t care about control fan-out should call one of the simpler start* constructors.

pub fn start_with_all<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, probes: ProbeRegistry, scheduler: SchedulerRegistry, daemon_registry: Arc<DaemonRegistry>, control_sink: Option<Arc<dyn ControlSink>>, admin_verifier: Option<Arc<AdminVerifier>>, ) -> Self

Maximum-control constructor — accepts every optional extension the loop supports, including the ICE admin verifier that gates MeshOsEvent::SignedIceCommit folding on multi-operator signature verification.

pub fn start_with_audit_chain<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, probes: ProbeRegistry, scheduler: SchedulerRegistry, daemon_registry: Arc<DaemonRegistry>, control_sink: Option<Arc<dyn ControlSink>>, admin_verifier: Option<Arc<AdminVerifier>>, admin_audit_appender: Option<Arc<dyn AdminAuditChainAppender>>, ) -> Self

Like Self::start_with_all but also accepts an optional super::audit_chain::AdminAuditChainAppender. Production deployments wire a chain-backed appender here so the audit ring’s bounded history extends to cluster-lifetime replay. Test + in-process callers leave it None and read the in-memory ring through the snapshot.

pub fn start_with_chains<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, probes: ProbeRegistry, scheduler: SchedulerRegistry, daemon_registry: Arc<DaemonRegistry>, control_sink: Option<Arc<dyn ControlSink>>, admin_verifier: Option<Arc<AdminVerifier>>, admin_audit_appender: Option<Arc<dyn AdminAuditChainAppender>>, log_appender: Option<Arc<dyn LogChainAppender>>, ) -> Self

Like Self::start_with_audit_chain but also accepts an optional super::log_chain::LogChainAppender for per-node log-chain history.

pub fn start_with_all_chains<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, probes: ProbeRegistry, scheduler: SchedulerRegistry, daemon_registry: Arc<DaemonRegistry>, control_sink: Option<Arc<dyn ControlSink>>, admin_verifier: Option<Arc<AdminVerifier>>, admin_audit_appender: Option<Arc<dyn AdminAuditChainAppender>>, log_appender: Option<Arc<dyn LogChainAppender>>, failure_appender: Option<Arc<dyn FailureChainAppender>>, ) -> Self

Maximal-options constructor — accepts every chain seam the substrate exposes (admin audit, log, failure). Production deployments wiring all three TypedRedexFile<*> chains call this directly; the other start_with_* constructors forward with None defaults for the appenders they don’t surface. To also wire the migration-abort dispatcher (so an ICE KillMigration commit actually aborts the in-flight migration), use Self::start_with_full_extensions.

pub fn start_with_full_extensions<D: ActionDispatcher>( config: MeshOsConfig, dispatcher: Arc<D>, probes: ProbeRegistry, scheduler: SchedulerRegistry, daemon_registry: Arc<DaemonRegistry>, control_sink: Option<Arc<dyn ControlSink>>, admin_verifier: Option<Arc<AdminVerifier>>, admin_audit_appender: Option<Arc<dyn AdminAuditChainAppender>>, log_appender: Option<Arc<dyn LogChainAppender>>, failure_appender: Option<Arc<dyn FailureChainAppender>>, migration_aborter: Option<Arc<dyn MigrationAborter>>, migration_snapshot_source: Option<Arc<dyn MigrationSnapshotSource>>, ) -> Self

Full-extensions constructor — every chain seam plus the migration-abort dispatcher and the migration-snapshot source. Production deployments that want a KillMigration chain commit to actually abort the in-flight migration wire an super::migration_aborter::OrchestratorMigrationAborter; to let the ICE blast-radius preview enumerate the targeted daemon, also wire an super::migration_snapshot_source::OrchestratorMigrationSnapshotSource. Both wrap the same Arc<MigrationOrchestrator> so a single orchestrator handle covers both seams.

pub fn dropped_actions(&self) -> u64

Sample the current count of reconcile-emitted actions the executor’s mpsc rejected (queue full). A growing counter is the signal that reconcile is outpacing the dispatcher.

pub fn this_node(&self) -> NodeId

MeshOsConfig::this_node captured at construction. SDK consumers use this to stamp per-daemon metadata views so MetadataView::node_id reflects the runtime’s identity instead of the previous hard-coded 0.

pub fn install_placement_scorer( &self, scorer: Arc<dyn PlacementScorer>, ) -> Option<Arc<dyn PlacementScorer>>

Install / replace the active placement scorer. Subsequent reconcile passes use the new scorer.

pub fn scheduler_registry(&self) -> SchedulerRegistry

Clone the scheduler registry.

pub fn add_locality_probe(&self, probe: Arc<dyn LocalityProbe>)

Install a LocalityProbe on the live loop. The probe is polled on the next Tick (and every Tick after).

pub fn add_health_probe(&self, probe: Arc<dyn HealthProbe>)

Install a HealthProbe on the live loop. Same cadence as locality probes.

pub fn add_inventory_probe(&self, probe: Arc<dyn InventoryProbe>)

Install an super::probes::InventoryProbe on the live loop. Polled on every Tick alongside the other probes; samples populate the per-peer inventory axes (PeerSnapshot::cpu_load_1m / mem_* / disk_* / saturation_trend / capability_set / software_version / forked_from).

pub fn clear_locality_probes(&self)

Detach every installed LocalityProbe. Pair with Self::add_locality_probe when a caller swaps probe sources mid-flight (test harnesses, hot-config reload).

pub fn clear_health_probes(&self)

Detach every installed HealthProbe. Same shape as Self::clear_locality_probes.

pub fn clear_inventory_probes(&self)

Detach every installed super::probes::InventoryProbe. Same shape as Self::clear_locality_probes; required when swapping sources because last-writer-wins per peer means a stale probe left installed can stomp a live replacement.

pub fn probe_registry(&self) -> ProbeRegistry

Clone the probe registry. Used by tests + advanced callers that want to install probes outside the runtime’s own lifetime.

pub fn daemon_registry(&self) -> &Arc<DaemonRegistry>

Borrow the runtime’s DaemonRegistry. The lifecycle sink is already attached, so any register / unregister call on the returned registry surfaces as a DaemonLifecycleSignal event in the loop’s event stream. SDK consumers (Rust + future language bindings) register daemons through this handle.

pub fn recovery_registry(&self) -> &RecoveryRegistry

Borrow the X-13 recovery registry. SDK consumers register per-group RecoveryHandler closures here; the loop runs them once per tick from inside the tick handler (after poll_probes, before run_reconcile). Cheap to clone the returned reference — the registry is Arc-wrapped.

pub fn handle(&self) -> &MeshOsHandle

Borrow the publish handle. Source converters (attach_to_daemon_registry, etc.) clone this to push events into the loop.

pub fn handle_clone(&self) -> MeshOsHandle

Clone the publish handle. Cheap (one mpsc::Sender clone).

pub fn snapshot_reader(&self) -> &MeshOsSnapshotReader

Borrow the snapshot reader. Phase F consumers (Deck integration, snapshot folds) clone this for out-of-loop reads.

pub fn snapshot(&self) -> MeshOsSnapshot

Sample the most recent post-reconcile snapshot.

pub fn executor_stats(&self) -> ExecutorStatsSnapshot

Sample the executor counters. Atomic loads — consistent per-counter but not as a single snapshot.

pub async fn shutdown(self) -> Result<RuntimeStats, RuntimeShutdownError>

Drive a clean shutdown. Publishes MeshOsEvent::Shutdown to the loop, waits for the loop task to exit, drops the handle so the executor’s receiver returns None, then waits for the executor to drain. Returns the final stats.

timeout bounds each join — past it, the future returns Err(RuntimeShutdownError::Timeout) and the caller decides what to do with the tasks. Default is 2 s — generous for the test surface, tight enough for production.

pub async fn shutdown_with_timeout( self, timeout: Duration, ) -> Result<RuntimeStats, RuntimeShutdownError>

shutdown with an explicit timeout.

Trait Implementations

impl Drop for MeshOsRuntime

fn drop(&mut self)

If the runtime was dropped without an explicit shutdown, abort whichever tasks are still in flight rather than detach them. Detaching would leak the loop + executor task tree along with the dispatcher Arc and the snapshot cell for the remainder of the process. After a clean shutdown_with_timeout the option fields are None, so this is a no-op.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.