# 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. No `controllers/`, `services/`, `models/` splits.
- Each bounded context gets its own module with its own types. Cross-context communication happens through well-defined public interfaces.
- Prefer thin `main.rs`/`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. Prefer enums over booleans or stringly-typed fields.
- **Phantom types** where compile-time state tracking is warranted.
- **No public struct fields**. All fields must be private. Expose access through getter methods and construct through associated functions or builder patterns.
- `#[must_use]` on pure functions and types whose values should not be silently dropped.
## Error Handling
- A single project-wide `Error` enum defined in a dedicated `error` module.
- Each variant wraps an underlying error type from a dependency or domain context.
- Implement `From<UnderlyingError> for Error` for every variant to enable `?` ergonomics throughout the codebase.
- 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`**. The only exception is when branching on a `bool` value, where `if`/`else` is preferred. For everything else, use `match`.
- **No `return` keyword**. Every function body is a single expression. Use `?` for early error propagation and combinators for control flow; never write an explicit `return`.
- **No `mut`**. All bindings and parameters must be immutable. Restructure with shadowing, combinators, or new bindings instead of mutation.
- **Combinators** (`map`, `and_then`, `filter`, `fold`, etc.) over imperative loops and match-and-early-return, where they remain readable.
- **Prefer `and_then` over nested pattern-matching**. When you would nest `match` arms to unwrap successive `Option`/`Result` layers, flatten with `and_then` (or `?`) instead.
- **Pure functions** — isolate side effects at the boundaries. Core domain logic takes values and returns values.
- **No `unwrap()`/`expect()`**. Prohibited everywhere — including tests and `main`. Always propagate or handle errors explicitly.
- **No `loop` or `for`**. Use iterator combinators (`map`, `filter`, `fold`, `for_each`, `scan`, etc.) or recursion. If you think you need a loop, restructure with combinators or a recursive function.
- Prefer **iterators** over indexed access.
## Traits
- Trait definitions follow domain boundaries — a trait represents a domain capability, not a technical pattern.
- **No dynamic polymorphism**. Never use `dyn Trait` or trait objects. All dispatch must be static via generics or `impl Trait`. If a design seems to require `dyn`, restructure with enums or generics instead.
- **Implement the standard trait, not an ad-hoc method**. If a method's signature and semantics match a trait from `core`/`std` (e.g., `Add`, `Sub`, `Mul`, `From`, `Into`, `Display`, `Iterator`, etc.), implement the trait instead of defining a standalone method.
## Linting
```toml
[lints.clippy]
all = { level = "deny", priority = -1 }
pedantic = "warn"
needless_pass_by_value = "warn"
manual_map = "warn"
```
## Verification
- **Always run `RUSTFLAGS="-D warnings" cargo clippy`** before considering code complete. All warnings are errors — code must pass cleanly.
## Testing
- **Property-based tests** via `proptest` where types suggest invariants.
- Unit tests live in the same file as the code they test (`#[cfg(test)]` modules).
- Integration tests go in `tests/` organized by domain context, not by module path.
- Test names describe the property or behavior, not the function name.
## Dependencies
- **`comp-cat-rs`** is the required foundation crate. Always depend on the latest version. Use its `Io`, `Resource`, `Stream`, `Fiber` types for all effectful code, its `Functor`/`Monad` traits as the core abstractions, and its `Kind` trait for higher-kinded type encoding. Do not roll your own effect types when `comp-cat-rs` provides them.
- Minimize other dependencies. Evaluate whether a crate is truly needed or if the functionality can be expressed with `std`, `comp-cat-rs`, and the type system.
- No `thiserror`, no `anyhow` — error handling is explicit and hand-rolled (see above).