# Coding Standards
## Style
* `rustfmt` (workspace `rustfmt.toml`, edition 2024). `cargo fmt --all` must
be a no-op.
* `cargo clippy --workspace --all-targets` must be warning-free.
* Doc comments on all public items (`#![warn(missing_docs)]` per crate).
* Comments explain **non-obvious intent, constraints, and tradeoffs** —
never restate the code.
## Unsafe policy (§41)
* All crates except `katra-abi` use `#![forbid(unsafe_code)]`.
* `katra-io`'s io_uring module and `katra-memory`'s mmap are the only other
sanctioned boundaries; they use `#![deny(unsafe_code)]` + targeted
`#[allow]` with a **module-level safety contract**.
* Every unsafe block states: why unsafe is required, what invariants are
assumed, who guarantees them, and how they are tested.
## Error model
See `docs/standards/error-model.md`. Policy code switches on
`KatraError::category()`, never on message strings.
## Naming and vocabulary
Use the shared vocabulary from `katra-core` (Scopes, EventKinds, Payloads,
DeadlineClasses, PromotionStates). Add event kinds only at the end of the
enums (append-only trace-format discipline). Never invent a parallel
vocabulary for the same concept.
## Tests
* Unit tests live next to the code; integration behavior is covered by the
**courts** (`katra-courts`), which are falsifiable and recorded.
* Deterministic where possible: seeded RNGs (SplitMix64), no wall-clock
dependence in assertions, bounded bounds for CI.
* Performance-sensitive paths carry micro-tests (`raw_push_cost`,
`convert_cost`, `probe_is_cheap_enough`).
## Reproducibility
`Cargo.lock` is committed. Benchmarks record seed, command line, tool
version, and host info in every receipt.