ADR 0002: Rust Cargo workspace with layered crates

• Status: Accepted (2026-11-10)
• Date: 2026-11-10
• Deciders: Vincent Mader
• Related: 05-architecture.md; ADR 0012, 0013

Context

The thesis code is Python with dense N³ arrays and Python loops, which limits resolution and makes the p = 2 study impossible. The global default stack is Rust. The same core must run natively (studies), in wasm (web app), and from Python (oracles, figures).

Decision

A Cargo workspace in repo/ (the git root; a private GitHub repository coagulation until submission) with the crates coag-core, coag-disk, coag-dust, coag-kernel, coag-sampling, coag-integrate, coag-sim, coag-cli, coag-py, and later web/. Dependencies point only from lower to higher layers as drawn in the architecture document. Library crates are #![forbid(unsafe_code)] unless a measured hotspot justifies otherwise (then an ADR). publish = false until the licence question (Q1) is decided. Workspace lints and edition per the rust skill, versions pinned in M1 after checking current releases.

Alternatives considered

• One crate: simpler at first, but couples physics to numerics and slows compile times; splitting later is a bigger refactor.
• Python + Numba (as in early thesis versions): fast to write, but no wasm path, weaker typing, and the cost study needs control over memory layout.
• C++/Fortran (common in astro codes): no advantage over Rust for this project and against the default stack.

Consequences

• Clear test boundaries per layer; analytic kernels and 2D kernels plug in without touching integrators.
• Some boilerplate for crate interfaces.
• Co-authors who only use Python need the coag-py bridge (ADR 0013).