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,108 @@ edition = "2024"
 license = "AGPL-3.0"
 repository = "https://github.com/nullisLabs/shepherd"
 
+# Shared dependency table. Only deps consumed by 2+ crates across the
+# full workspace (nexum-engine + every downstream module crate) are
+# hoisted here; single-consumer deps stay per-crate. Crates inherit
+# with `dep.workspace = true` and may add features per call site via
+# `dep = { workspace = true, features = ["extra"] }`. Version drift
+# across crates (the failure mode that prompted hoisting in the first
+# place, e.g. cowprotocol on `1.0.0-alpha` vs `1.0.0-alpha.3`) is now
+# impossible by construction.
+[workspace.dependencies]
+# Error + async plumbing.
+anyhow = "1"
+thiserror = "2"
+tokio = { version = "1", features = ["full"] }
+futures = "0.3"
+
+# Serde + config.
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# Observability.
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "env-filter", "ansi", "json"] }
+
+# `strum::IntoStaticStr` on every error / event enum gives a free
+# snake_case `&'static str` for every variant, which feeds directly
+# into `metrics::counter!(..., "error_kind" => name)` and
+# `tracing::warn!(error_kind = name, ...)` recordings without an
+# ad-hoc `match err { ... => "connect" ... }` ladder per call site.
+strum = { version = "0.26", features = ["derive"] }
+
+# `auto_impl::auto_impl(&, Arc, Box)` forwarding impls for traits
+# held through smart pointers. Available workspace-wide so any future
+# `Arc<dyn Trait>` boundary can opt in without touching root manifest.
+auto_impl = "1"
+
+# `derive_more` newtype boilerplate (`Deref`, `From`, `Display`, ...).
+# `default-features = false, features = ["full"]` keeps the proc-macro
+# surface predictable; per-derive opt-in via the standard `#[derive(...)]`
+# syntax. Available workspace-wide; not pulled in by default.
+derive_more = { version = "1", default-features = false, features = ["full"] }
+
+# CLI parser. Used by every binary crate (engine, load-gen,
+# orderbook-mock, shepherd-backtest) via the derive macro.
+clap = { version = "4", features = ["derive"] }
+
+# alloy stack. Engine uses the full provider/transport surface;
+# guest-facing crates use `alloy-primitives` + `alloy-sol-types` for
+# typed protocol values. Pinned together so a single workspace bump
+# moves every consumer at once.
+alloy-primitives = { version = "1.5", default-features = false, features = ["std", "serde"] }
+alloy-sol-types = { version = "1.5", default-features = false, features = ["std"] }
+alloy-provider = { version = "1.5", default-features = false, features = ["ws", "ipc", "pubsub", "reqwest"] }
+alloy-rpc-types-eth = { version = "1.5", default-features = false, features = ["std"] }
+alloy-transport-ws = { version = "1.5", default-features = false }
+
+# CoW Protocol bindings. Pinned to one version across the workspace
+# (was `1.0.0-alpha` in engine vs `1.0.0-alpha.3` in SDK before
+# hoisting). Default features stay on so the engine picks up
+# `http-client` for `OrderBookApi`; guest-side consumers (SDK,
+# strategies) opt out with `default-features = false` for the
+# `cdylib` wasm-target builds.
+cowprotocol = "1.0.0-alpha.3"
+
+# HTTP transport for `cow_api::request` REST passthrough and the
+# orderbook-mock test surface.
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+
+# `wit-bindgen` is consumed by every guest module crate (example +
+# every strategy + every fixture). Hoisted so a single bump moves
+# them in lock-step.
+wit-bindgen = { version = "0.57", default-features = false, features = ["macros", "realloc"] }
+
+# Workspace-standard lint set. New crates inherit via
+# `[lints] workspace = true` in their package manifest. `unsafe_code`
+# cannot be denied workspace-wide because every wit-bindgen guest
+# module emits an `unsafe extern "C"` shim; modules carrying that
+# macro keep the default-warn allowance, and unsafe in non-binding
+# code still trips review by convention.
+[workspace.lints.rust]
+unsafe_op_in_unsafe_fn = "warn"
+
+[workspace.lints.clippy]
+# Deny the easy footguns. Each crate carries its own narrower
+# `#![deny(...)]` where the cost of a violation is high (e.g. the
+# binary entrypoints carry `unused_crate_dependencies` warn).
+dbg_macro = "deny"
+todo = "deny"
+
+# `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

@@ -5,11 +5,70 @@ edition.workspace = true
 license.workspace = true
 repository.workspace = true
 
+[lints]
+workspace = true
+
 [dependencies]
+# WASM Component Model runtime.
 wasmtime = { version = "45", features = ["component-model"] }
 wasmtime-wasi = "45"
-anyhow = "1"
-tokio = { version = "1", features = ["full"] }
-getrandom = "0.4"
-serde = { version = "1", features = ["derive"] }
+
+# Async + error plumbing.
+anyhow.workspace = true
+thiserror.workspace = true
+# `strum::IntoStaticStr` on error enums gives metric labels (`error_kind`)
+# free via a snake_case `&'static str` for every variant. Used at
+# `tracing::warn!(error_kind = <variant_name>.into(), ...)` sites and
+# any `metrics::counter!(... "error_kind" => kind)` recordings, so the
+# Prometheus labels stay in lock-step with the Rust enum source of
+# truth instead of needing a `match err { ... => "connect" ... }`
+# ladder per call site. Pinned via the workspace so every consumer
+# moves in lockstep.
+strum.workspace = true
+tokio.workspace = true
+clap.workspace = true
+
+# Manifest parsing.
+serde.workspace = true
 toml = "1"
+serde_json.workspace = true
+
+# Observability. `tracing` replaces the prior `eprintln!` debug log
+# so the engine can drop into a structured log pipeline in production.
+tracing.workspace = true
+tracing-subscriber = { workspace = true, 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 via the
+# workspace so every crate that touches cowprotocol moves in lockstep.
+cowprotocol.workspace = true
+# 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.workspace = true
+
+# `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.workspace = true
+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.workspace = true
+alloy-primitives.workspace = true
+futures.workspace = true
+
+# `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,38 @@
+//! CLI surface for the `nexum-engine` binary, derived via clap.
+//!
+//! The 0.2 binary accepts either a positional `<wasm-path> [<manifest-path>]`
+//! shortcut that synthesises a one-module engine config, or a
+//! `--engine-config <path>` flag that points at a TOML declaring
+//! multiple modules. Production deployments use the second form; the
+//! positional shortcut stays for parity with the M1 reference CLI and
+//! for smoke tests.
+
+use std::path::PathBuf;
+
+use clap::Parser;
+
+/// Parsed CLI surface.
+///
+/// `nexum-engine [<wasm-path> [<manifest-path>]] [--engine-config <path>]`
+#[derive(Parser, Debug, Default)]
+#[command(
+    name = "nexum-engine",
+    about = "Run one or more Wasm Component modules under the Shepherd supervisor",
+    long_about = None,
+    version,
+)]
+pub struct Cli {
+    /// Optional positional path to a Wasm Component file. Synthesises
+    /// a one-module engine config when no `--engine-config` is given.
+    pub wasm: Option<PathBuf>,
+
+    /// Optional positional path to the module's `nexum.toml` manifest.
+    /// Only consulted alongside the positional `wasm` shortcut.
+    pub manifest: Option<PathBuf>,
+
+    /// Optional explicit path to the engine-wide `engine.toml` config.
+    /// When omitted, the engine resolves the default search path
+    /// documented in `engine_config::load_or_default`.
+    #[arg(long = "engine-config")]
+    pub engine_config: Option<PathBuf>,
+}