M3 epic: SDK + examples + tutorial + QA validation

.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@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 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

.gitignore

@@ -21,3 +21,11 @@ Thumbs.db
 # Environment
 .env
 .env.*
+
+# Agent skills / AI tooling — installed locally, never committed.
+.agents/
+.claude/
+skills-lock.json
+
+# Engine runtime state (default state_dir from engine.toml).
+data/

Cargo.toml

@@ -1,7 +1,14 @@
 [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"
 
@@ -10,6 +17,20 @@ edition = "2024"
 license = "AGPL-3.0"
 repository = "https://github.com/nullisLabs/shepherd"
 
+# `cowprotocol` v1.0.0-alpha.3 (the crates.io release the engine
+# depends on) was cut from `cowdao-grants/cow-rs` PR #5 at commit
+# `1742ffa`. `bleu/cow-rs` main has diverged since with: the
+# `composable::Proof` width fix (relevant to the TWAP poll path),
+# `OrderCreation` zero-from-address fast-fail, the `order_book` /
+# `composable` submodule splits, `OrderPostErrorKind` + `retry_hint()`
+# (BLEU-822, the protocol-level retry contract M2 modules dispatch
+# on), and `OrderBookApi::with_base_url(chain, base_url)` for barn /
+# staging routing (BLEU-823). Patching to that commit picks the lot
+# up without waiting for an alpha.4 publish. Drop once
+# `cowprotocol >= 1.0.0-alpha.4` ships.
+[patch.crates-io]
+cowprotocol = { git = "https://github.com/bleu/cow-rs", rev = "57f5f553ab28c9fff54089daf2d39b4282f3e4dd" }
+
 [profile.dev]
 panic = "abort"
 

README.md

@@ -46,10 +46,71 @@ just build
 
 # Run the runtime against the example module
 just run
+
+# Run unit tests
+just test
 ```
 
 Without Nix, you need: Rust (edition 2024, see `rust-toolchain.toml` if present), the `wasm32-wasip2` target, and `wasm-tools`.
 
+## Running
+
+### Single-module (development)
+
+```sh
+nexum-engine <path-to-component.wasm> [<module.toml>]
+```
+
+The `module.toml` is optional; without it the engine prints a deprecation warning and loads the module with empty capabilities and config (0.1 fallback).
+
+### Multi-module (production)
+
+```sh
+nexum-engine --engine-config engine.toml
+```
+
+`engine.toml` declares RPC endpoints, the state directory, and a `[[modules]]` list:
+
+```toml
+[engine]
+state_dir = "/var/lib/shepherd"
+log_level  = "info"
+
+[chains.1]
+rpc_url = "wss://mainnet.infura.io/ws/v3/..."
+
+[[modules]]
+path     = "modules/twap-monitor/twap-monitor.wasm"
+manifest = "modules/twap-monitor/module.toml"
+
+[[modules]]
+path = "modules/ethflow-watcher/ethflow-watcher.wasm"
+```
+
+### Module manifest (`module.toml`)
+
+```toml
+[module]
+name    = "twap-monitor"
+version = "0.1.0"
+
+[capabilities]
+required = ["chain", "local-store", "cow-api"]
+optional = ["http"]
+
+[capabilities.http]
+allow = ["api.cow.fi"]
+
+[[subscription]]
+kind     = "log"
+chain_id = 1
+address  = "0xfdaFc9d1902f4e0b84f65F49f244b32b31013b74"  # ComposableCoW (canonical CREATE2 address, same on every supported chain)
+
+[[subscription]]
+kind     = "block"
+chain_id = 1
+```
+
 ## Documentation
 
 The `docs/` directory contains the design corpus:

crates/nexum-engine/Cargo.toml

@@ -6,10 +6,56 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
+# WASM Component Model runtime.
 wasmtime = { version = "45", features = ["component-model"] }
 wasmtime-wasi = "45"
+
+# Async + error plumbing.
 anyhow = "1"
+thiserror = "2"
 tokio = { version = "1", features = ["full"] }
-getrandom = "0.4"
+
+# Manifest parsing.
 serde = { version = "1", features = ["derive"] }
 toml = "1"
+serde_json = "1"
+
+# Observability. `tracing` replaces the prior `eprintln!` debug log
+# so the engine can drop into a structured log pipeline in production.
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "env-filter", "ansi"] }
+
+# `cow-api` backend. cowprotocol pulls `OrderBookApi`, `OrderCreation`,
+# `OrderUid`, the orderbook base URL table per `Chain`, and the typed
+# error surface the host re-projects into `HostError`. Pinned to the
+# crates.io release Shepherd is shipping against.
+cowprotocol = "1.0.0-alpha"
+# REST passthrough for `cow_api::request`. cowprotocol pulls reqwest
+# transitively for its own client; we depend on it directly so the
+# import is explicit and survives any future cowprotocol feature
+# rearrangement.
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+
+# `chain` backend. Each configured chain owns a `DynProvider` built
+# from a `WsConnect`/`Http` transport so the host's `request` /
+# `request-batch` impls can hand a raw `(method, params)` pair to
+# alloy's JSON-RPC layer without reimplementing the codec.
+alloy-provider      = { version = "1.5", default-features = false, features = ["ws", "ipc", "pubsub", "reqwest"] }
+alloy-rpc-client    = { version = "1.5", default-features = false }
+alloy-rpc-types-eth = { version = "1.5", default-features = false, features = ["std"] }
+alloy-transport     = { version = "1.5", default-features = false }
+alloy-transport-ws  = { version = "1.5", default-features = false }
+alloy-primitives    = { version = "1.5", default-features = false, features = ["std", "serde"] }
+futures             = "0.3"
+
+# `local-store` backend. Per-module namespacing is enforced
+# host-side via a `[len:u8][module_name][raw_key]` prefix.
+redb = "2"
+
+# Misc.
+getrandom = "0.4"
+url = "2"
+
+[dev-dependencies]
+tempfile = "3"
+wiremock = "0.6"

crates/nexum-engine/src/bindings.rs

@@ -0,0 +1,16 @@
+//! WIT bindings generated by `wasmtime::component::bindgen!`.
+//!
+//! Both `wit/nexum-host` and `wit/shepherd-cow` packages are listed
+//! explicitly so wit-parser can resolve the cross-package reference
+//! natively - no vendored `deps/` tree needed. The world name is fully
+//! qualified.
+//!
+//! Every `Host` trait impl in `crate::host::impls` consumes types
+//! generated here.
+
+wasmtime::component::bindgen!({
+    path: ["../../wit/nexum-host", "../../wit/shepherd-cow"],
+    world: "shepherd:cow/shepherd",
+    imports: { default: async },
+    exports: { default: async },
+});

crates/nexum-engine/src/cli.rs

@@ -0,0 +1,46 @@
+//! Manual CLI parser. Kept hand-rolled (instead of pulling clap) because
+//! the surface is small and unlikely to grow in 0.2.
+
+use std::path::PathBuf;
+
+/// Parsed CLI surface.
+///
+/// `nexum-engine [<wasm-path> [<manifest-path>]] [--engine-config <path>]`
+///
+/// Positional `<wasm-path>` is a backwards-compat shortcut that
+/// synthesises a one-module engine config. Production deployments pass
+/// `--engine-config` and declare modules in TOML.
+#[derive(Debug, Default)]
+pub struct Cli {
+    pub wasm: Option<PathBuf>,
+    pub manifest: Option<PathBuf>,
+    pub engine_config: Option<PathBuf>,
+}
+
+impl Cli {
+    pub fn parse() -> Self {
+        let mut args = std::env::args().skip(1);
+        let mut cli = Self::default();
+        let mut positional = Vec::new();
+        while let Some(arg) = args.next() {
+            match arg.as_str() {
+                "--engine-config" => cli.engine_config = args.next().map(PathBuf::from),
+                "-h" | "--help" => {
+                    eprintln!(
+                        "usage: nexum-engine [<wasm-path> [<manifest-path>]] \
+                         [--engine-config <path>]"
+                    );
+                    std::process::exit(0);
+                }
+                _ => positional.push(arg),
+            }
+        }
+        if let Some(p) = positional.first() {
+            cli.wasm = Some(PathBuf::from(p));
+        }
+        if let Some(p) = positional.get(1) {
+            cli.manifest = Some(PathBuf::from(p));
+        }
+        cli
+    }
+}