medicallib_rust/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Source: src/ (crate root src/lib.rs). Core modules in src/organs/, types in src/types.rs, errors in src/error.rs, FFI in src/ffi.rs.
• Tests: integration tests in tests/ (e.g., tests/patient.rs).
• Examples: examples/ (Rust usage and tracing demos), plus C FFI example in examples/c/ with header in ffi/medicallib.h.
• Benchmarks: benches/ (Criterion-based; see benches/heart.rs).
• Docs: README.md, ARCHITECTURE.md, INSTALL.md, MIGRATION.md.

Build, Test, and Development Commands

• Build library (debug): cargo build
• Build with FFI (shared lib): cargo build --release --features ffi
• Run tests: cargo test (single test file: cargo test --test patient)
• Run examples: cargo run --example usage (or tracing_demo)
• Benchmarks (Criterion): cargo bench
• Lint: cargo clippy --all-targets -- -D warnings
• Format: cargo fmt --all
• Docs (open): cargo doc --no-deps --open

Coding Style & Naming Conventions

• Rust style via rustfmt; 4-space indentation; wrap at ~100 cols where reasonable.
• Naming: modules/files snake_case, types/traits CamelCase, functions/vars snake_case, constants SCREAMING_SNAKE_CASE.
• Public API changes must be intentional; update examples and docs when modifying src/ffi.rs or src/organs/*.

Testing Guidelines

• Prefer integration tests in tests/ named after features (e.g., basic.rs, ffi.rs).
• Add unit tests near code under #[cfg(test)] for small invariants.
• Keep tests deterministic; avoid sleeping/time unless necessary.
• Run cargo test locally and ensure cargo clippy passes before opening a PR.

Commit & Pull Request Guidelines

• Commits: clear, imperative subject (e.g., "Add heart rate update clamp"). Conventional Commits (feat/fix/refactor/docs/test) are welcome.
• PRs: concise description, link issues, note breaking changes, and include tests or examples. Add screenshots only if relevant to docs.

Security & FFI Notes

• FFI: when changing src/ffi.rs, update C header ffi/medicallib.h and verify examples/c/ffi_example.c still builds against the produced cdylib.
• Avoid unsafe unless essential; document safety contracts.

Agent-Specific Tips

• Maintain module organization under src/organs/ and keep APIs cohesive.
• Do not introduce new runtime dependencies without discussion; prefer standard library and existing crates.