Development

Development

Local checks

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --lib
cargo test -p karta-core --test synthetic_memory_eval

For retrieval changes, also run:

cargo test -p karta-core --test activate_retrieval_invariants

CI gate

Every PR must pass:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo nextest run --workspace --no-fail-fast

Real evals

Require .env with LLM credentials:

cp .env.example .env
# fill credentials
cargo test --test real_eval -- --ignored --nocapture

BEAM eval

BEAM_DATASET_PATH=data/beam-100k.json   cargo test --test beam_100k beam_100k_single -- --ignored --nocapture

Style rules

• Rust 2024.
• cargo fmt and clippy warning-deny before push.
• No mocked LLM calls in eval/benchmark code.
• Write-time organization beats read-time cleverness.
• No bulk reformat/refactor mixed with feature work.
• Comments explain why, not what.

Commit messages

• Imperative mood.
• First line under 72 chars.
• One logical change per commit.
• Explain why in body.
• Include benchmark impact if change moves retrieval score.

PR checklist

• fmt pass.
• clippy pass.
• tests pass.
• retrieval/dream/scoring changes include benchmark impact note.
• docs updated for behavior/config/API changes.
• no incomplete benchmark numbers.

Recommended loop

bacon

bacon.toml and rust-toolchain.toml are committed for reproducible iteration.