# Repository Guidelines
Tokitai is a Rust-based mathematical operator compiler that treats algebraic laws, valuation, locality, and precision as first-class scheduling inputs. It is an SCI-Q2 paper artifact; read `ARCHITECTURE.md`, `ARTIFACT.md`, and `CLAIMS.md` before touching claim-boundary code.
## Project Structure & Module Organization
- `src/` – library and binaries; module map in `src/lib.rs`:
- `backend/` – CPU and ROCm/HIP backends (`hip_*` modules gated on `rocm-hip`).
- `ir/`, `planner/`, `op/`, `object/`, `domain/`, `verify/` – IR, scheduling, operator registry, object system, mathematical domains, verification.
- `facade.rs`, `theory.rs`, `training_runner.rs`, `infer.rs` – top-level orchestrators.
- `bin/` – `gpu_smoke`, `train_quality_moe`, `infer_quality_moe`, `collect_paper_artifacts`, `model_server`.
- `tests/` – integration tests, one file per surface.
- `examples/` – runnable demos; `paper_benchmarks.rs` regenerates `target/paper-results/`.
- `docs/` – design notes; `docs/paper/` holds paper artifacts.
- `scripts/` – theorem/Lean checkers.
## Build, Test, and Development Commands
- `cargo build` / `cargo build --features rocm-hip` – default vs. GPU build. The `rocm-hip` feature is required for `hip_*` modules and the `gpu_smoke`, `train_quality_moe`, `infer_quality_moe`, `collect_paper_artifacts` binaries.
- `cargo build --features model-server` – builds `model_server` (adds `axum` + `tokio`).
- `cargo test` – full integration suite under default features. ROCm/HIP tests need `cargo test --features rocm-hip --test <name>` (e.g. `rocm_padic_stratified_benchmarks`).
- `cargo run --example paper_benchmarks` – regenerate paper results.
- `cargo fmt --check` / `cargo fmt` – formatting gate (see `ARTIFACT.md`).
- `scripts/check_*.sh`, `scripts/optional_lean_check.sh` – optional proof smoke checks.
## Coding Style & Naming Conventions
- Rust 2024 edition, 4-space indent, no project `rustfmt`/`clippy` config – use toolchain defaults; CI runs `cargo fmt --check`.
- Modules are short snake_case nouns; files mirror the primary type. `hip_*` is the ROCm/HIP prefix; p-adic/sheaf code is suffixed `_padic` / `_sheaf`.
- Public API lives in `src/facade.rs`; extend the facade rather than re-exposing internals.
- Gate any ROCm/HIP-only module with `#[cfg(feature = "rocm-hip")]` to keep the default build CPU-only.
## Testing Guidelines
- Tests live in `tests/` under the standard `cargo test` harness; one file per surface.
- CPU oracle and conformance tests run under default features and are the correctness baseline for accelerated paths.
- Before pushing: `cargo fmt --check && cargo test`.
- Release-gate checks (`scripts/check_*.sh`, `tests/theory_release_gate.rs`) guard paper claim boundaries – do not weaken them without updating `CLAIMS.md`.
## Commit & Pull Request Guidelines
- No commit history yet; adopt Conventional Commits: `type(scope): summary` (e.g. `feat(planner): add p-adic valuation skip`).
- Keep commits scoped to one logical change; update `CLAIMS.md` or `todo.json` when touching claim-boundary code.
- PRs should describe the change, link the relevant `P###` task in `todo.json`/`CLAIMS.md`, list test commands run, and attach regenerated `target/paper-results/*` artifacts for benchmark-affecting changes.
- CI gates: `cargo fmt --check` and `cargo test` must pass before review.
## Agent-Specific Instructions
- `CLAIMS.md` is the source of truth for what the code may claim. Do not weaken `production_speedup_claim_allowed`, `portable_rocm_claim_allowed`, `verified_hip_machine_code_claim_allowed`, or `full_formalization_claim_allowed` without a `P###` trace entry.
- Default to CPU reference paths; ROCm/HIP is opt-in via `--features rocm-hip` and not portable across hardware.
- Never hand-edit generated files under `target/`, `var/`, or `target/paper-results/` – regenerate them via the documented `cargo` / `scripts/` invocations.
- When adding an operator, register it in `src/op/registry.rs` and add a lowering/contract test under `tests/` before opening a PR.