bullet-bots: Instructions file for Codex

bullet-bots

Event-driven trading bot framework in Rust. Typed event bus, typed feeds per event kind, strategies implemented as actors. Pluggable exchange adapters and strategies connect through a shared harness that handles lifecycle, shutdown, and multi-source event dispatch.

Instructions are layered: this file holds what every task needs; each area has its own AGENTS.md (see "Where things live"). Read the one for the area you touch.

Build & Test

just dev [filter]          # check (workspace, incremental) + tests matching filter (none without one). After each edit.
just pre                   # fmt + clippy + unit/integration tests. Before each commit.
just check                 # workspace typecheck only, no codegen
just lint                  # clippy, pedantic, -D warnings
just test                  # unit/integration tests via cargo test (seconds); `just ci` uses nextest
just fmt                   # nightly fmt (required for import grouping)
just ci                    # mirrors CI: fmt --check, clippy, nextest, doctests, cargo deny, cargo shear
just validate [config]     # validate a config (funding-arb queries venues read-only)
just seed-target [from]    # new worktree: clone a warm target/ (copy-on-write, seconds)
just warm                  # main checkout: warm the seed source (a post-merge hook runs it
                           # automatically when a pull changes dependencies or rust-toolchain.toml)
just ci-timings [n]        # CI "Clippy + tests" durations (~1m warm cache, ~7m cold node)

Inner loop. just dev [filter] after each edit, just pre before every commit, just ci once before submitting. Every local build uses --workspace, never -p: -p builds dependencies with a different feature set, so mixing them compiles the dependency tree twice and makes a seeded target/ useless. Incremental builds only redo changed crates and their dependents, so workspace-wide costs seconds. Local tests use cargo test: on macOS every spawned binary pays an XProtect scan, and nextest spawns one process per test (just test ~5s vs ~41s with nextest). CI (Linux) uses nextest (.config/nextest.toml, ci profile: retries once, no fail-fast); doctests run separately (cargo test --doc).