# CLAUDE.md — Rust Project Conventions
## Philosophy
This project follows **functional**, **type-driven**, and **domain-driven** design principles. The type system is the primary tool for correctness. If a state is illegal, it should be unrepresentable.
## Architecture
- **Modules by domain context**, not by technical layer.
- Each bounded context gets its own module with its own types.
- Prefer thin `lib.rs` that wires contexts together.
## Types
- **Newtypes** for all domain primitives. Never pass raw `String`, `u64`, `f64`, etc. across function boundaries when they carry domain meaning.
- **Sum types (enums)** to model domain variants and state machines.
- **No public struct fields**. Expose access through getter methods.
- `#[must_use]` on pure functions and types whose values should not be silently dropped.
## Error Handling
- A single project-wide `Error` enum in a dedicated `error` module.
- Implement `std::fmt::Display` and `std::error::Error` by hand. No `thiserror`, no `anyhow`.
- Domain logic returns `Result<T, Error>`. Never panic in library code.
## Style
- **Prefer `match` over `if`/`else`** (exception: branching on `bool`).
- **No `return` keyword**. Every function body is a single expression.
- **No `mut`**. Restructure with shadowing, combinators, or new bindings.
- **Combinators** (`map`, `and_then`, `filter`, `fold`) over imperative loops.
- **Never match on `Option<_>`**. Use combinators.
- **Prefer combinators on `Result<_, _>`**.
- **No `unwrap()`/`expect()`**. Prohibited everywhere, including tests.
- **No `loop` or `for`**. Use iterator combinators or recursion.
- **No `Rc`, `Arc`**. Prefer ownership and borrowing.
- **No naked `as` casts**. Use `From`/`Into` or `TryFrom`/`TryInto`.
- Prefer **iterators** over indexed access.
## Traits
- **No dynamic polymorphism**. Never use `dyn Trait`. All dispatch is static.
- **Implement standard traits** (`Add`, `Sub`, `Display`, etc.) instead of ad-hoc methods.
## Linting
- **Always run `RUSTFLAGS="-D warnings" cargo clippy`** before considering code complete.
## Testing
- Unit tests live in `#[cfg(test)]` modules in the same file.
- Test names describe the property or behavior, not the function name.
- Doc comments on key public APIs include `# Examples` that double as doctests.
## Dependencies
- **proof-cat** provides the sumcheck proving infrastructure.
- **field-cat** provides the `Field` trait, the `FieldBytes` transcript trait, and the concrete fields (`F101`, `BabyBear`, `BFieldElement`).
- **plonkish-cat** provides the PLONKish constraint vocabulary (`Wire`, `Expression`) used by `AirExpr` for documentation cross-references.
- Minimize other dependencies. No `thiserror`, no `anyhow`.
## Documentation
- **Doc comments on all public items**.
- **`# Examples` sections** with runnable code blocks on key public APIs.
- Use backtick links to cross-reference types.