Skip to content

runtime: extract a generic launcher and split the bare and cow binaries#446

Merged
mfw78 merged 1 commit into
dev/m1from
feat/m2-generic-launcher
Jul 21, 2026
Merged

runtime: extract a generic launcher and split the bare and cow binaries#446
mfw78 merged 1 commit into
dev/m1from
feat/m2-generic-launcher

Conversation

@mfw78

@mfw78 mfw78 commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

Closes #380

What

Extracts a generic nexum-launch library (shared CLI, config load, tracing init, preset-driven launch) out of nexum-cli. nexum-cli now ships a bare nexum binary composed over nexum-launch with Ext=() and zero cow dependencies. Adds a new shepherd binary crate that owns the cow composition root (reference lattice + cow-api extension + Prometheus add-on), wired over the same launcher. Updates the Dockerfile, justfile, and check-venue-agnostic.sh to build/ship/scan shepherd as the production binary and to sweep nexum-launch and nexum-cli for venue leakage alongside nexum-runtime.

Why

The CLI composition root previously wired the cow extension in directly, making nexum-cli depend on shepherd-cow-host - a backwards edge from a generic host binary into a specific downstream extension. Splitting a generic launcher library plus a bare Ext=() engine binary from the cow composition root keeps the host layer venue-agnostic and moves cow wiring to where it belongs.

Closes #380

Testing

Existing gate: fmt, clippy, workspace check, nextest, doctests.

AI Assistance

Implemented with Claude Code.

@lgahdl lgahdl left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clean extraction — verified the Runtime trait shape at the actual head commit and shepherd/nexum-cli's usage matches it correctly (no trait/impl mismatch), the backwards-edge from the host layer into shepherd-cow-host is genuinely fixed (coupling moved to exactly crates/shepherd, confirmed by nexum-launch's Cargo.toml having zero cow deps and check-venue-agnostic.sh now sweeping nexum-launch/nexum-cli), and every Dockerfile/justfile/script touch point consistently retargets shepherd as the shipped binary with no stale path left. Extensibility for a future third composition is clean too (new bin crate + Runtime impl + a 2-line main.rs, no changes needed to nexum-launch).

One naming note worth considering, not blocking: the new crate/binary is named shepherd, same as the repo itself, while every other cow-domain crate in the workspace uses a shepherd-* prefix (shepherd-cow-host, shepherd-sdk, shepherd-backtest) — but this one is actually the top-level composition root, not a cow-domain crate, so the bare name reads inconsistently with that existing convention and is ambiguous with the repo name in cargo tree -p shepherd/search contexts. Something like shepherd-engine might disambiguate. Also a very small doc nit: crates/shepherd/src/main.rs's crate doc says "the engine itself stays cow-free," which could be misread as self-contradictory since shepherd is the one binary that isn't cow-free — it means the nexum-runtime/nexum-launch layers underneath. Approving either way, these are non-blocking.

@mfw78
mfw78 force-pushed the feat/m2-adapters-in-sweeps branch from 44b6d6a to 734c391 Compare July 20, 2026 13:17
Base automatically changed from feat/m2-adapters-in-sweeps to dev/m1 July 21, 2026 00:15
nexum-launch owns the shared CLI, config load, tracing init, and the
preset-driven run; nexum-cli becomes the bare Ext=() engine binary over
CoreRuntime with no cow edge; the cow composition root moves to a new
shepherd binary wiring the cow-api extension as a Runtime preset. The
venue-agnostic guard's crate-graph check now covers the launcher and
the bare binary, and the cow deployment tooling builds shepherd.
@mfw78

mfw78 commented Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Thanks - checked both notes against the end-of-train state.

Doc nit ("the engine itself stays cow-free") - addressed by end-of-train. The crate doc is reworded at the tip (24c4d9e) to:

The shepherd binary: the cow composition root. Boots the reference backends, registers the videre venue platform, and hands it all to the generic launcher; CoW enters only as the bundled cow-venue adapter component, and the engine itself stays venue- and cow-free.

That separates "the cow composition root" (this binary) from "the engine" (the launcher/runtime underneath, which stays cow-free), so the self-contradiction reading is resolved in context. No change needed.

Naming (shepherd vs shepherd-*) - still valid at HEAD. The crate is still bare shepherd at the tip, and it is more pronounced at M5 where crates/shepherd is promoted to the repo root. Since a rename touches the same Dockerfile/justfile/script surface this PR just retargeted, and the crate moves to root at M5, I have filed it as a naming-decision follow-up (#516) to settle deliberately - likely shepherd-engine for the crate while keeping the shepherd binary via [[bin]], or accepting the bare composition-root name. Not blocking.

@mfw78
mfw78 merged commit 934f7c9 into dev/m1 Jul 21, 2026
5 of 6 checks passed
@mfw78
mfw78 deleted the feat/m2-generic-launcher branch July 21, 2026 00:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants