Dev/m3 rebase

.github/workflows/ci.yml

@@ -55,14 +55,46 @@ jobs:
       - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
       - run: cargo test --workspace --all-features --no-fail-fast
 
+  docs:
+    name: rustdoc
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: "-D warnings"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9 # master 2026-03-27
+        with:
+          toolchain: nightly
+          targets: wasm32-wasip2
+      - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+      - run: cargo doc --workspace --no-deps
+
   build-module:
-    name: build example module
+    name: build ${{ matrix.module }} (wasm32-wasip2)
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        module:
+          - example
+          - twap-monitor
+          - ethflow-watcher
+          - price-alert
+          - balance-tracker
+          - stop-loss
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9 # master 2026-03-27
         with:
           toolchain: nightly
           targets: wasm32-wasip2
       - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
-      - run: cargo build -p example --target wasm32-wasip2 --release
+      - run: cargo build -p ${{ matrix.module }} --target wasm32-wasip2 --release
+      - name: report wasm size
+        run: |
+          artifact_name=$(echo "${{ matrix.module }}" | tr '-' '_')
+          wasm_path="target/wasm32-wasip2/release/${artifact_name}.wasm"
+          if [ -f "$wasm_path" ]; then
+            size=$(wc -c < "$wasm_path")
+            echo "${{ matrix.module }} .wasm size: ${size} bytes"
+          fi

Cargo.toml

@@ -1,8 +1,13 @@
 [workspace]
 members = [
     "crates/nexum-engine",
+    "crates/shepherd-sdk",
+    "crates/shepherd-sdk-test",
     "modules/ethflow-watcher",
     "modules/example",
+    "modules/examples/balance-tracker",
+    "modules/examples/price-alert",
+    "modules/examples/stop-loss",
     "modules/twap-monitor",
 ]
 resolver = "2"

crates/nexum-engine/src/runtime/event_loop.rs

@@ -2,7 +2,7 @@
 //! supervisor until a shutdown signal arrives.
 
 use futures::StreamExt;
-use futures::stream::{FuturesUnordered, select_all};
+use futures::stream::{BoxStream, FuturesUnordered, select_all};
 use tracing::{info, warn};
 
 use crate::bindings::nexum;
@@ -93,8 +93,24 @@ pub async fn run(
     log_streams: Vec<TaggedLogStream>,
     shutdown: impl std::future::Future<Output = ()> + Send,
 ) {
-    let mut blocks = select_all(block_streams);
-    let mut logs = select_all(log_streams);
+    // `select_all` over an empty Vec yields `None` immediately, which
+    // would trip the "stream ended -> shut down" arm below before the
+    // first block / log ever flows. Engine configs that subscribe to
+    // only one event kind (e.g. all modules use `[[subscription]] kind
+    // = "block"`) are valid and must not be punished. Replace each
+    // empty side with `stream::pending()` so the corresponding select
+    // arm is never selected; the bail-on-None semantic still fires
+    // when a *non-empty* stream actually closes.
+    let mut blocks: BoxStream<'_, _> = if block_streams.is_empty() {
+        futures::stream::pending().boxed()
+    } else {
+        select_all(block_streams).boxed()
+    };
+    let mut logs: BoxStream<'_, _> = if log_streams.is_empty() {
+        futures::stream::pending().boxed()
+    } else {
+        select_all(log_streams).boxed()
+    };
     let mut shutdown = Box::pin(shutdown);
     loop {
         tokio::select! {

crates/nexum-engine/src/supervisor.rs

@@ -78,7 +78,8 @@ impl Supervisor {
             .with_context(|| format!("load module {}", entry.path.display()))?;
             modules.push(loaded);
         }
-        info!(count = modules.len(), "supervisor up");
+        let alive = modules.iter().filter(|m| m.alive).count();
+        info!(loaded = modules.len(), alive, "supervisor up");
         Ok(Self { modules })
     }
 
@@ -216,21 +217,38 @@ impl Supervisor {
         } else {
             loaded_manifest.config.clone()
         };
-        match bindings
+        // Whether `init` returned `Ok(())`. When `init` returns
+        // `Err(HostError)` the module's strategy state (e.g. an
+        // `OnceLock<Settings>`) is left uninitialised. Existing M3
+        // example modules short-circuit on the missing state via
+        // `SETTINGS.get().is_none() -> return Ok(())`, but future
+        // modules without that guard could panic, and even with the
+        // guard each dispatch wastes fuel + an RPC subscription tick
+        // on a no-op. The `LoadedModule.alive` flag below is set from
+        // this result so the dispatcher skips the failed module
+        // without surfacing it to the dispatch fast-path. See
+        // COW-1070.
+        let init_succeeded = match bindings
             .call_init(&mut store, &config)
             .await
             .map_err(Error::from)?
         {
-            Ok(()) => info!(module = %module_namespace, "init succeeded"),
-            Err(e) => warn!(
-                module = %module_namespace,
-                domain = %e.domain,
-                kind = ?e.kind,
-                code = e.code,
-                message = %e.message,
-                "init failed",
-            ),
-        }
+            Ok(()) => {
+                info!(module = %module_namespace, "init succeeded");
+                true
+            }
+            Err(e) => {
+                warn!(
+                    module = %module_namespace,
+                    domain = %e.domain,
+                    kind = ?e.kind,
+                    code = e.code,
+                    message = %e.message,
+                    "init failed - module loaded but marked dead; dispatcher will skip it",
+                );
+                false
+            }
+        };
         // Refuel after init so the first on_event starts with a full budget.
         store.set_fuel(limits_cfg.fuel())?;
 
@@ -252,7 +270,7 @@ impl Supervisor {
             store,
             subscriptions: loaded_manifest.manifest.subscriptions.clone(),
             fuel_per_event: limits_cfg.fuel(),
-            alive: true,
+            alive: init_succeeded,
         })
     }