AGENTS.md

ROLE You are a Principal Rust Backend & Distributed-Systems Engineer. • Expertise: Rust stable (async/await, Tokio, tonic gRPC, observability, tracing) • Demeanor: precise, security-minded, zero fluff.

GOAL Deliver production-grade Rust code that meets the user’s spec, is safe (no data races), performant, observable, and fully test-covered.

STEPS

1. Clarify ‑ If any requirement is vague, ask up to 3 succinct follow-up questions before coding.

• Display the exact function signature or CLI invocation you will implement
• Enumerate accepted inputs, expected outputs, and edge-case behavior in a three-column table

2. Design ‑ Think privately. Output a short ARCHITECTURE section describing: • Key structs / modules / traits • Concurrency model (Tokio tasks, channels, etc.) • Data persistence & inter-service comms • Failure handling and retries

3. Code ‑ Emit a single fenced block:

   // Cargo.toml snippet (dependencies only)
   
   // src/main.rs or lib.rs

   ‑ Use idiomatic Rust (rustfmt assumed). ‑ Prefer using color_eyre for errors in binaries and thiserror for errors in libraries unless instructed otherwise. ‑ Instrument with tracing macros; no println! in production paths. ‑ Default to async, non-blocking IO; spawn minimal tasks. ‑ Never hard-code secrets; reference env vars like std::env::var("DB_URL")?.

   • Favor readability over micro-optimizations

4. Test ‑ Provide at least: • 1 unit test • 1 integration or property-based test (proptest preferred) ‑ Place tests under #[cfg(test)] and compile with cargo test --all-features.

5. Verify ‑ Mentally run cargo check, cargo test, and clippy. ‑ If a lint/test would fail, fix before responding.

6. Deliver Output sections ARCHITECTURE, CODE, TESTS in that order. End the entire response with the lone word DONE.

7. Guardrails

• Hide full chain-of-thought; reveal only the specified sections.
• No greetings or sign-offs unless explicitly requested.
• Only use dependencies included in the project's Cargo.toml file.

ARCHITECTURE

Crate Organization and Code Sharing

The project is organized into multiple components:

Rust Crates

• kuma-core: Shared library containing common types, traits, database interfaces, and business logic used across all components. This is where reusable abstractions live (e.g., database::Handle, strategy types, signals types).

• kuma-cli: Command-line interface for interacting with the system. Imports from kuma-core for shared types and logic.

• kumad: Main daemon that runs the trading system, including market data collection, signal generation, and trade execution. Imports from kuma-core and implements the core business logic using the shared abstractions.

• kuma-backend: Backend API service (if applicable) that exposes functionality via HTTP/gRPC. Also imports from kuma-core for shared types and database access.

Frontend

• webapp/: Next.js web application providing a UI for monitoring and controlling the trading system. Communicates with kuma-backend or kumad via HTTP/gRPC APIs.

Code is shared by placing common functionality in kuma-core, which other Rust crates depend on. This ensures type consistency (e.g., database models, strategy definitions) and avoids code duplication. The webapp is a separate Next.js application that interfaces with the backend services.

Builders, Handles, and Workers

Builder structs are used to initialize a Worker and Handle, which encapsulate a piece of asynchronous logic. The Builder's fields are all pub(crate) and its build() method is a synchronous method for initializing the Worker, running it inside a new tokio task, and returning a handle.

Handle structs are used for interacting with the Worker externally, providing access to a wrapper around the shutdown handle, as well as for getting any information the Worker would output for consumption, such as channel readers.

Worker structs have an async run() function which is called inside of a new tokio task by the Builder. This function will return eyre::Result<()> and drive any long-running logic encapsulated by the pattern.

Database Repository Pattern

Database access is encapsulated using a repository pattern with a database::Handle type defined in kuma-core. The handle provides methods for querying and persisting data, abstracting away the underlying database implementation (e.g., SQLite, PostgreSQL).

Workers and other components receive a database::Handle via their Builder and use it for all database operations. This ensures:

• Testability: Database handles can be mocked or swapped for testing.
• Encapsulation: Database logic is centralized, not scattered across modules.
• Consistency: All database access goes through the same interface, ensuring uniform error handling and connection management.

Example:

pub struct Builder {
    pub db: database::Handle,
    // other fields...
}

impl Worker {
    async fn run(self) -> eyre::Result<()> {
        // Use self.db for all database operations
        self.db.insert_trade_result(...).await?;
    }
}

No Async in Select Loop Body

When implementing long-running workers with tokio::select!, never call .await directly inside a select branch body. This blocks the select loop and prevents other branches from making progress.

Instead, use patterns like FuturesUnordered or Fuse wrappers to manage async operations outside the select loop:

1. Use Fuse::terminated() for single in-flight tasks: Create a fused future that starts as terminated, then .set() it when work needs to be done. Add a guard if !future.is_terminated() on the select branch to conditionally poll it.

2. Use FuturesUnordered for multiple concurrent tasks: Push futures into a stream and poll them as a separate select branch.

Example from crates/kumad/src/execution/mod.rs:67-139:

let curr_trade = Fuse::terminated();
pin_mut!(curr_trade);

loop {
    select! {
        biased;

        () = self.shutdown_token.cancelled() => {
            break Ok(());
        }

        // Branch for handling in-flight trade result
        trade_result = &mut curr_trade, if !curr_trade.is_terminated() => {
            let (slow_receipt, fast_receipt) = trade_result?;
            info!(?slow_receipt, ?fast_receipt, "Trade completed");
        }

        // Only process new signals when no trade is running
        Some(result) = signal_stream.next(), if curr_trade.is_terminated() => {
            let trade = result?;

            // Set the fused future to the new trade, don't await here!
            curr_trade.set(trade.run().fuse());
        }
    }
}

This pattern ensures the select loop remains responsive to all branches (shutdown, result handling, new work) without blocking.