M5 epic: multi-chain deploy + packaging + docs reconciliation

.dockerignore

@@ -0,0 +1,55 @@
+# Build context exclusion list for `docker build .`. Keeping the
+# context lean matters: every byte sent to the daemon is hashed for
+# the build's source-changed signal, and the production multi-stage
+# Dockerfile already invalidates the dependency layer cache on any
+# Cargo.lock / Cargo.toml change.
+
+# Cargo build artefacts — re-built inside the build stage anyway.
+/target/
+target/
+**/target/
+
+# Runtime state directory the engine writes the redb file into. Never
+# part of the image.
+/data/
+data/
+
+# Backtest tooling output: large JSON fixtures + Python venv state.
+# Re-collected on demand via `tools/backtest-collect/backtest_collect.py`.
+tools/backtest-collect/fixtures-*.json
+tools/baseline-latency/data/
+tools/**/__pycache__/
+tools/**/*.pyc
+
+# NOTE: `modules/fixtures/*-bomb` are listed in the workspace
+# `Cargo.toml`, so excluding them breaks `cargo build` ("failed to
+# load manifest for workspace member"). They're tiny crates and the
+# Dockerfile doesn't COPY them to the runtime stage, so the
+# image size impact is zero. Keep them in the build context.
+
+# Local-only configs. The production `engine.toml` is supplied at
+# runtime via a bind-mount (`/etc/shepherd/engine.toml`).
+engine.toml
+engine.e2e.toml
+engine.load.toml
+engine.m2.toml
+engine.m3.toml
+
+# Git + GitHub metadata.
+/.git/
+/.github/
+.gitignore
+
+# Editor / OS noise.
+.vscode/
+.idea/
+.DS_Store
+*.swp
+
+# Operator-side docs reports the image doesn't need. Source markdown
+# stays so it's discoverable inside the container if an operator
+# `docker exec`s in for a quick `cat docs/production.md`.
+docs/operations/load-reports/
+docs/operations/e2e-reports/
+docs/operations/backtest-reports/
+docs/operations/baselines/

.env.example

@@ -0,0 +1,25 @@
+# Operator template — copy to `.env` and fill in your paid RPC URLs.
+# `.env` is gitignored; never commit a populated copy.
+#
+# Workflow:
+#   cp .env.example .env
+#   $EDITOR .env
+#   docker compose up -d
+#
+# The engine reads these via `${VAR}` placeholders in
+# `engine.docker.toml` (substitution happens at config-load time,
+# before TOML parse, so a missing variable fails fast).
+#
+# Use `wss://` schemes — `eth_subscribe` is WebSocket-only and the
+# engine emits a boot-time ERROR on http(s):// URLs (see
+# docs/production.md §6 and engine_config::validate_transports).
+
+MAINNET_RPC_URL=wss://eth-mainnet.g.alchemy.com/v2/REPLACE_ME
+GNOSIS_RPC_URL=wss://gnosis-mainnet.g.alchemy.com/v2/REPLACE_ME
+SEPOLIA_RPC_URL=wss://eth-sepolia.g.alchemy.com/v2/REPLACE_ME
+ARBITRUM_RPC_URL=wss://arb-mainnet.g.alchemy.com/v2/REPLACE_ME
+BASE_RPC_URL=wss://base-mainnet.g.alchemy.com/v2/REPLACE_ME
+
+# Optional: override the published image with a locally-built or
+# pinned-by-SHA tag. Leave unset to pull `:latest` from ghcr.io.
+# SHEPHERD_IMAGE=ghcr.io/bleu/nullis-shepherd:sha-abc1234

.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

.github/workflows/docker.yml

@@ -0,0 +1,88 @@
+# Docker image build + publish to ghcr.io.
+#
+# Triggers:
+#   - push to `main`               → publish `latest` + `sha-<sha>`
+#   - tag push `v*`                → publish `v<tag>` + `latest`
+#   - workflow_dispatch (manual)   → publish `manual-<run_id>`
+#   - pull_request to `main`       → build only, no push (CI smoke)
+#
+# Image: ghcr.io/<owner>/nullis-shepherd
+# Auth:  GITHUB_TOKEN (scoped to packages:write below).
+#
+# Pinned action SHAs match the style of `.github/workflows/ci.yml`.
+
+name: docker
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    name: build + push (${{ github.event_name }})
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Docker buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+
+      - name: Log in to ghcr.io
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Compute image metadata
+        id: meta
+        uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804 # v5.7.0
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            # `latest` on push to main and on tag.
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=ref,event=tag
+            # `sha-<short>` on every event so a soak run can pin an
+            # exact build.
+            type=sha,prefix=sha-,format=short
+            # manual-<run_id> for workflow_dispatch.
+            type=raw,value=manual-${{ github.run_id }},enable=${{ github.event_name == 'workflow_dispatch' }}
+            # `pr-<n>` on pull-request builds so the smoke artefact
+            # is identifiable. PR builds are NOT pushed (see `push:`).
+            type=ref,event=pr,prefix=pr-
+
+      - name: Build + push
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        with:
+          context: .
+          file: ./Dockerfile
+          # Push on every non-PR event; PR builds are local-only smoke.
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # Layer cache via the registry: the previous successful
+          # build's intermediate layers are reused so a Cargo.toml-only
+          # change re-compiles only the changed crate.
+          cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache
+          cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache,mode=max,ignore-error=true
+          # `amd64` is enough for the soak VM. Add `arm64` once an
+          # operator surfaces a real need; multi-arch ~2x the build.
+          platforms: linux/amd64

.gitignore

@@ -21,3 +21,30 @@ Thumbs.db
 # Environment
 .env
 .env.*
+# Exception: the committed template (operator copies it to `.env`,
+# which is then caught by the rule above).
+!.env.example
+
+# Agent skills / AI tooling — installed locally, never committed.
+.agents/
+.claude/
+skills-lock.json
+
+# Engine runtime state (default state_dir from engine.toml).
+data/
+
+# E2E automation: rendered configs with embedded RPC keys + script state
+# never get committed.
+*.local.toml
+scripts/.state
+scripts/.env
+
+# Operator-supplied engine config (carries paid RPC URLs / API keys).
+# The committed siblings `engine.example.toml`, `engine.docker.toml`,
+# and `engine.{m2,m3,e2e,load}.toml` are placeholder templates.
+/engine.toml
+
+# Generated reports under e2e-reports/ (operator commits the filled-in ones
+# manually via `git add -f`).
+docs/operations/e2e-reports/engine-*.log
+docs/operations/e2e-reports/metrics-*.txt

Cargo.toml

@@ -1,7 +1,20 @@
 [workspace]
 members = [
     "crates/nexum-engine",
+    "crates/shepherd-backtest",
+    "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/fixtures/flaky-bomb",
+    "modules/fixtures/fuel-bomb",
+    "modules/fixtures/memory-bomb",
+    "modules/twap-monitor",
+    "tools/load-gen",
+    "tools/orderbook-mock",
 ]
 resolver = "2"
 
@@ -10,6 +23,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"