# Repository Guidelines
## Project Structure & Module Organization
The crate’s core API lives in `src/lib.rs`, which defines the `MappedMemory` and `PagedMemory` primitives plus the `PageStore` trait. Platform-specific signal and memory plumbing is isolated in `src/machdep.rs`; keep OS-conditional logic there rather than in public APIs. Tests sit in the `#[cfg(test)]` module at the end of `src/lib.rs`, mirroring real-world fault scenarios. Build outputs land in `target/`; do not check that directory in.
## Build, Test, and Development Commands
Use `cargo build` for a fast debug build and `cargo build --release` before benchmarking allocator changes. Run `cargo test` to execute the in-crate unit tests that exercise the page-fault handling pipeline. Invoke `cargo fmt` to apply the repo’s `rustfmt.toml` layout rules, and prefer `cargo clippy --all-targets --all-features` for linting before opening a review.
## Coding Style & Naming Conventions
Follow Rust 2021 idioms with 4-space indentation and a 120-column soft limit (enforced by `rustfmt.toml`). Keep modules and free functions in `snake_case`; trait and type names stay in `UpperCamelCase`. Use descriptive, OS-agnostic names in `lib.rs`, reserving architecture-specific identifiers for `machdep.rs`. Favor small, focused `pub` APIs and document unsafe blocks with a comment explaining invariants.
## Testing Guidelines
Unit tests live alongside the code; name them after the behavior under test (e.g., `lazy_population`, `out_of_order_scan`). When adding new paging flows, seed random generators deterministically as in the existing tests (`ChaChaRng::from_seed([0; 32])`) so runs remain reproducible. Run `cargo test -- --nocapture` if you need to inspect debug output guarded by `#[cfg(debug_assertions)]`. Add regression tests that cover both initial page faults and replays after `release_page`.
## Commit & Pull Request Guidelines
Keep commit subjects short, imperative, and optionally scoped—recent history shows patterns like `ci: run on macos (#5)` and `fix aarch64 linux (#7)`. Reference related issues or PRs in parentheses when applicable. For pull requests, summarize the affected memory-management paths, list any new commands or configuration flags, and include before/after behavior notes or screenshots when instrumentation output changes. Confirm `cargo test` and `cargo fmt` pass before requesting review.