diff --git a/.env.example b/.env.example index 2aa349a2..2a2f09e8 100644 --- a/.env.example +++ b/.env.example @@ -22,4 +22,4 @@ 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 +# SHEPHERD_IMAGE=ghcr.io/nullislabs/shepherd:sha-abc1234 diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 30d8172d..c99db0b3 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -6,7 +6,7 @@ # - workflow_dispatch (manual) → publish `manual-` # - pull_request to `main` → build only, no push (CI smoke) # -# Image: ghcr.io//nullis-shepherd +# Image: ghcr.io/nullislabs/shepherd # Auth: GITHUB_TOKEN (scoped to packages:write below). # # Pinned action SHAs match the style of `.github/workflows/ci.yml`. diff --git a/Cargo.lock b/Cargo.lock index 2fdac578..093498a9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5141,7 +5141,7 @@ dependencies = [ ] [[package]] -name = "shepherd" +name = "shepherd-engine" version = "0.1.0" dependencies = [ "anyhow", diff --git a/Cargo.toml b/Cargo.toml index 7e325913..ce6f420e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ members = [ "nexum/crates/nexum-tasks", "nexum/crates/nexum-world", "videre/crates/no-std-probe", - "shepherd/crates/shepherd", + "shepherd/crates/shepherd-engine", "videre/crates/videre-host", "videre/crates/videre-macros", "videre/crates/videre-sdk", diff --git a/Dockerfile b/Dockerfile index 69a38621..c8c297c4 100644 --- a/Dockerfile +++ b/Dockerfile @@ -66,7 +66,7 @@ FROM chef AS build # changed workspace crate. `--locked` stays on the real builds below, which # validate the committed Cargo.lock verbatim. COPY --from=planner /src/recipe.json recipe.json -RUN cargo chef cook --release -p shepherd --recipe-path recipe.json \ +RUN cargo chef cook --release -p shepherd-engine --recipe-path recipe.json \ && cargo chef cook --release --target wasm32-wasip2 \ -p twap-monitor -p ethflow-watcher -p price-alert \ -p balance-tracker --recipe-path recipe.json \ @@ -80,7 +80,7 @@ COPY . . # Engine binary in release. --locked ensures the committed Cargo.lock # is used verbatim so builds are reproducible. -RUN cargo build -p shepherd --release --locked +RUN cargo build -p shepherd-engine --release --locked # Four production modules plus the bundled cow venue adapter. The wasm # artefacts land under diff --git a/README.md b/README.md index e3e7021b..bec578c5 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ A module built against `nexum:host` runs on any Nexum-compatible host. CoW order | `nexum/crates/nexum-runtime/` | The engine: a wasmtime host implementing the `nexum:host` contract. | | `nexum/crates/nexum-launch/` | Launcher library: shared CLI, config load, tracing, preset launch. | | `nexum/crates/nexum-cli/` | The bare `nexum` binary: the core lattice, no extension payload. | -| `shepherd/crates/shepherd/` | The `shepherd` binary: the cow composition root registering the videre venue platform and the Prometheus add-on. | +| `shepherd/crates/shepherd-engine/` | The `shepherd` binary: the cow composition root registering the videre venue platform and the Prometheus add-on. | | `nexum/crates/nexum-sdk/` | Guest SDK: host trait seam, bind macro, chain/config/address helpers, `wasi:http` fetch, tracing facade. | | `videre/crates/videre-sdk/` | Venue-platform SDK: the `videre:venue` client and adapter contracts. | | `shepherd/crates/cow-venue/` | The bundled CoW venue adapter component. | diff --git a/docker-compose.yml b/docker-compose.yml index 3f432658..7753f19e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -10,7 +10,7 @@ # The image either builds from the repo's Dockerfile (`docker compose # build`) or pulls the published ghcr.io artefact when the # `SHEPHERD_IMAGE` env var is set (CI publishes -# `ghcr.io/bleu/nullis-shepherd:` and `:latest` on main). +# `ghcr.io/nullislabs/shepherd:` and `:latest` on main). # # Required mounts: # - ./engine.toml -> /etc/shepherd/engine.toml (operator-supplied) @@ -19,7 +19,7 @@ services: shepherd: - image: ${SHEPHERD_IMAGE:-ghcr.io/bleu/nullis-shepherd:latest} + image: ${SHEPHERD_IMAGE:-ghcr.io/nullislabs/shepherd:latest} # Comment out `build` if you `docker compose pull` instead of # building from source. Leaving it lets `docker compose up # --build` re-build from the local checkout when the image diff --git a/docs/deployment.md b/docs/deployment.md index 6cc400d8..eb0e1332 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -93,13 +93,13 @@ ls -lh target/wasm32-wasip2/release/*.wasm Build and run the `shepherd` binary against an `engine.toml`: ```sh -cargo run -p shepherd -- --engine-config engine.toml +cargo run -p shepherd-engine -- --engine-config engine.toml ``` The single-module shortcut takes positional paths and synthesizes a one-module config: ```sh -cargo run -p shepherd -- \ +cargo run -p shepherd-engine -- \ target/wasm32-wasip2/release/twap_monitor.wasm \ shepherd/modules/twap-monitor/module.toml ``` diff --git a/docs/design/pre-carve-runbook.md b/docs/design/pre-carve-runbook.md index dc973651..44d9e629 100644 --- a/docs/design/pre-carve-runbook.md +++ b/docs/design/pre-carve-runbook.md @@ -42,7 +42,7 @@ Three history-preserving `git-filter-repo --path` extractions, one per repo, run 1. `nexum-runtime` (L1): `--path nexum/` (crates, sdk, sdk-test, world, module-macros, launch, the bare `nexum` bin, `wit/nexum-host`). 2. `videre` (L2): `--path videre/` (sdk, test, macros, host, `wit/videre-*`, echo-venue/echo-client). -3. `shepherd` (L3 bundle): `--path shepherd/` (composable-cow, cow-venue, shepherd-sdk absorbed into the bundle, the `shepherd` bin, the `ethflow-watcher` and `twap-monitor` modules, the `orderbook-mock` tool, `wit/shepherd-cow`). +3. `shepherd` (L3 bundle): `--path shepherd/` (composable-cow, cow-venue, shepherd-sdk absorbed into the bundle, the `shepherd-engine` crate exposing the `shepherd` bin, the `ethflow-watcher` and `twap-monitor` modules, the `orderbook-mock` tool, `wit/shepherd-cow`). Each extraction: diff --git a/docs/operations/e2e-testnet-runbook.md b/docs/operations/e2e-testnet-runbook.md index a78b6b53..07947619 100644 --- a/docs/operations/e2e-testnet-runbook.md +++ b/docs/operations/e2e-testnet-runbook.md @@ -45,7 +45,7 @@ Long form: ```bash just build-e2e # builds the 5 module .wasm artefacts -cargo run -p shepherd -- --engine-config engine.e2e.toml +cargo run -p shepherd-engine -- --engine-config engine.e2e.toml ``` Expected boot (~5 s) ends with: diff --git a/docs/operations/m2-testnet-runbook.md b/docs/operations/m2-testnet-runbook.md index 79ecf38c..34cfc5dc 100644 --- a/docs/operations/m2-testnet-runbook.md +++ b/docs/operations/m2-testnet-runbook.md @@ -25,7 +25,7 @@ Long form: ```bash cargo build -p twap-monitor --target wasm32-wasip2 --release cargo build -p ethflow-watcher --target wasm32-wasip2 --release -cargo run -p shepherd -- --engine-config engine.m2.toml --pretty-logs +cargo run -p shepherd-engine -- --engine-config engine.m2.toml --pretty-logs ``` Expected boot (~5 s): @@ -103,7 +103,7 @@ The local store is a redb file with no standalone dump tool. Reboot the engine o | `connection refused` / WS retries | Public node throttled | Switch RPC to Alchemy / Infura in `engine.m2.toml` | | `module twap-monitor trapped: OutOfFuel` | Dispatch exceeded fuel budget | File an issue; raise `[engine.limits]` fuel temporarily | | `eth_call failed (rate limited)` repeatedly | Public node | Same as above | -| `ParseManifestError: missing capability cow-api` | Engine/module.toml version mismatch | `cargo build -p shepherd --release` and use the fresh binary | +| `ParseManifestError: missing capability cow-api` | Engine/module.toml version mismatch | `cargo build -p shepherd-engine --release` and use the fresh binary | | `data/m2/ls.redb` not created | `state_dir` not writable | Check permissions or change `state_dir` in `engine.m2.toml` | ## 5. References diff --git a/docs/operations/m3-testnet-runbook.md b/docs/operations/m3-testnet-runbook.md index ea655581..bac0badd 100644 --- a/docs/operations/m3-testnet-runbook.md +++ b/docs/operations/m3-testnet-runbook.md @@ -29,7 +29,7 @@ Long form: cargo build -p price-alert --target wasm32-wasip2 --release cargo build -p balance-tracker --target wasm32-wasip2 --release cargo build -p stop-loss --target wasm32-wasip2 --release -cargo run -p shepherd -- --engine-config engine.m3.toml --pretty-logs +cargo run -p shepherd-engine -- --engine-config engine.m3.toml --pretty-logs ``` Expected boot (~10 s): diff --git a/docs/production.md b/docs/production.md index ab2d73d7..dcb2beb9 100644 --- a/docs/production.md +++ b/docs/production.md @@ -4,7 +4,7 @@ Operator handbook for running the `shepherd` binary in production: systemd unit, ## 1. Pre-flight -- Engine built in release: `cargo build -p shepherd --release` gives `target/release/shepherd`. +- Engine built in release: `cargo build -p shepherd-engine --release` gives `target/release/shepherd`. - Module and adapter `.wasm` artefacts present under `target/wasm32-wasip2/release/`. - `engine.toml` with `state_dir` on a persistent path (never `/tmp`), `log_level = "info"`, `[engine.metrics] enabled = true` and `bind_addr = "127.0.0.1:9100"`, one `[chains.]` per subscribed chain with a paid RPC URL, one `[[modules]]` per module, and the `[[adapters]]` cow entry. - The `state_dir` exists and is writable by the service user. diff --git a/engine.m3.toml b/engine.m3.toml index 5a1ee826..2be46716 100644 --- a/engine.m3.toml +++ b/engine.m3.toml @@ -11,7 +11,7 @@ # cargo build -p price-alert --target wasm32-wasip2 --release # cargo build -p balance-tracker --target wasm32-wasip2 --release # cargo build -p cow-venue --features adapter --target wasm32-wasip2 --release -# cargo run -p shepherd -- --engine-config engine.m3.toml +# cargo run -p shepherd-engine -- --engine-config engine.m3.toml [engine] # Separate from data/m2 and the M1 example state. diff --git a/justfile b/justfile index 58c06824..1ad7a290 100644 --- a/justfile +++ b/justfile @@ -1,7 +1,7 @@ # Build the engine binaries: the bare `nexum` engine and the cow # composition root `shepherd`. build-engine: - cargo build -p nexum-cli -p shepherd + cargo build -p nexum-cli -p shepherd-engine # Build the example WASM module build-module: @@ -44,7 +44,7 @@ build-m2: # --pretty-logs keeps the runbook-friendly human-readable formatter; # production deploys omit the flag and emit JSON. run-m2: build-m2 build-cow-venue build-engine - cargo run -p shepherd -- --engine-config engine.m2.toml --pretty-logs + cargo run -p shepherd-engine -- --engine-config engine.m2.toml --pretty-logs # Build the M3 example modules (price-alert + balance-tracker) for # wasm32-wasip2. @@ -57,7 +57,7 @@ build-m3: # --pretty-logs keeps the runbook-friendly human-readable formatter; # production deploys omit the flag and emit JSON. run-m3: build-m3 build-cow-venue build-engine - cargo run -p shepherd -- --engine-config engine.m3.toml --pretty-logs + cargo run -p shepherd-engine -- --engine-config engine.m3.toml --pretty-logs # Build the http-probe example module (wasi:http fetch + allowlist # denial demo) for wasm32-wasip2. @@ -74,7 +74,7 @@ build-e2e: build-m2 build-m3 # downstream `jq` filter can mine submitted/dropped/backoff markers # for the e2e report. See `docs/operations/e2e-testnet-runbook.md`. run-e2e: build-e2e build-cow-venue build-engine - cargo run -p shepherd -- --engine-config engine.e2e.toml + cargo run -p shepherd-engine -- --engine-config engine.e2e.toml # Zero-leak gate: host-layer crate graphs, runtime charter-symbol and # router-field scans, and the nexum:host WIT leaf and foreign-namespace @@ -97,7 +97,7 @@ check-carve-groups: check: cargo check --target wasm32-wasip2 -p example cargo check -p nexum-runtime - cargo check -p nexum-cli -p shepherd + cargo check -p nexum-cli -p shepherd-engine # Run the full CI series locally before pushing. Mirrors # .github/workflows/ci.yml one-to-one: rustfmt, clippy, rustdoc, the diff --git a/scripts/e2e-run.sh b/scripts/e2e-run.sh index b3ec7aac..7daaf0f2 100755 --- a/scripts/e2e-run.sh +++ b/scripts/e2e-run.sh @@ -51,7 +51,7 @@ log "building 4 modules + engine (this can take a minute on first run)" cargo build -p ethflow-watcher --target wasm32-wasip2 --release >/dev/null cargo build -p price-alert --target wasm32-wasip2 --release >/dev/null cargo build -p balance-tracker --target wasm32-wasip2 --release >/dev/null - cargo build -p shepherd --release >/dev/null + cargo build -p shepherd-engine --release >/dev/null ) ts="$(date -u +%Y%m%dT%H%M%SZ)" diff --git a/scripts/load-run.sh b/scripts/load-run.sh index af636aef..d78f497e 100755 --- a/scripts/load-run.sh +++ b/scripts/load-run.sh @@ -80,7 +80,7 @@ log "building modules + engine + load-gen (release)" ( cd "$REPO_ROOT" && cargo build --release --quiet \ --target wasm32-wasip2 \ -p twap-monitor -p ethflow-watcher ) -( cd "$REPO_ROOT" && cargo build --release --quiet -p shepherd -p load-gen ) +( cd "$REPO_ROOT" && cargo build --release --quiet -p shepherd-engine -p load-gen ) log "starting shepherd (engine.load.toml)" ( cd "$REPO_ROOT" && ./target/release/shepherd --engine-config engine.load.toml ) \ diff --git a/shepherd/crates/shepherd/Cargo.toml b/shepherd/crates/shepherd-engine/Cargo.toml similarity index 94% rename from shepherd/crates/shepherd/Cargo.toml rename to shepherd/crates/shepherd-engine/Cargo.toml index 66598d38..1ada836a 100644 --- a/shepherd/crates/shepherd/Cargo.toml +++ b/shepherd/crates/shepherd-engine/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "shepherd" +name = "shepherd-engine" version.workspace = true edition.workspace = true license.workspace = true diff --git a/shepherd/crates/shepherd/src/main.rs b/shepherd/crates/shepherd-engine/src/main.rs similarity index 87% rename from shepherd/crates/shepherd/src/main.rs rename to shepherd/crates/shepherd-engine/src/main.rs index 0bf1be75..8b019e43 100644 --- a/shepherd/crates/shepherd/src/main.rs +++ b/shepherd/crates/shepherd-engine/src/main.rs @@ -1,6 +1,6 @@ -//! The `shepherd` binary: the cow composition root. Boots the -//! reference backends, registers the videre venue platform, and hands -//! both to the generic launcher. +//! `shepherd-engine`: the composition-root crate exposing the +//! `shepherd` binary. Boots the reference backends, registers the +//! videre venue platform, and hands both to the generic launcher. #![cfg_attr(not(test), warn(unused_crate_dependencies))]