apiVersion: conventions/v1
version: 0.1.0
updated: "2026-06-29"
name: code_standards
title: Rust code standards
scope: rust
status: active
summary: Result-based errors (no unwrap), thiserror domain enums, pure domain crates + thin FFI/WASM shims, SAFETY comments, snake_case serde. From v2 simulator/magic-civilization.
appliesTo: ["**/*.rs"]
rules:
  - id: no_unwrap
    level: must
    text: "Propagate via Result<_, Error>. `.unwrap()` forbidden; `.expect(\"reason\")` only when panic is provably impossible."
  - id: thiserror
    level: must
    text: Domain error enums via `thiserror`; errors carry context (`#[from]`, source chaining).
  - id: pure_domain_crates
    level: must
    text: "Domain crates (crates/<x>-*) are pure Rust — no FFI/WASM/GDExt deps. API crates are thin shims (WASM/GDExt surfaces) with no business logic."
  - id: unsafe_documented
    level: must
    text: "Every `unsafe` block has a `// SAFETY:` comment justifying the invariants."
  - id: serde_snake
    level: should
    text: 'Serde with #[serde(rename_all = "snake_case")] on wire types.'
  - id: no_dead_code
    level: must
    text: "`#[allow(dead_code)]` forbidden — delete unused code. `todo!()`/`unimplemented!()` forbidden in shipped code."
  - id: tracing
    level: should
    text: Structured logging via `tracing` (never `log`, never `println!` in libraries).
  - id: workspace
    level: should
    text: "Cargo workspace resolver=\"2\"; pure domain crates + API shim crates clearly separated."