AGENTS.md

Agent notes: rust/

Supplements the root AGENTS.md Geometry & WASM and Build/CI sections (one pure-Rust CSG kernel, produce_element_meshes as the single mesh home, panic=abort vs server-release, the ifc_lite_processing::style parity homes, determinism.yml plus re-pinning both mesh_determinism manifests, no blanket cargo fmt, the PyO3 wheel). Additional rust-tree footguns root does not cover:

• The workspace manifest is repo-root /Cargo.toml, not rust/Cargo.toml (there is none). Profiles (release panic='abort', server-release panic='unwind'), workspace.package version, and shared [workspace.lints] all live at repo root; edit them there.
• cargo test --workspace does not cover rust/python (workspace exclude) or rust/csg-thread-bench (its own detached [workspace]). A public-API change can break the PyO3 wheel or the bench crate with the workspace test still green; build and test those in-dir separately.
• Do not apply numeric clippy rewrites. [workspace.lints.clippy] deliberately allows excessive_precision, manual_range_contains, manual_clamp, neg_cmp_op_on_partial_ord, approx_constant. The .clamp() / RangeInclusive::contains / partial_cmp suggestions change NaN/panic behavior, and the precise literals are intentional.
• [lints] inherit-vs-extend footgun. core/processing/clash/ffi/export/wasm-bindings use [lints] workspace = true, but rust/geometry instead carries a full [lints.clippy] block (a member cannot both inherit workspace lints and add its own). To add a crate-local allow elsewhere, convert it the geometry way; do not append to workspace = true.
• RTC/georef rebase lives in the orchestrator, not the mesher. detect_rtc_offset_with_fallback + router.set_rtc_offset run in processing/src/processor/mod.rs; GeometryRouter and produce_element_meshes do not self-detect it. Driving the router or mesher directly (exporters, benches, ad-hoc tests) skips the rebase, so models over 10km from origin get f32 jitter. Set the offset yourself when bypassing the orchestrator.
• STEP string decode is UTF-8-boundary-sensitive. decode_ifc_string (core/src/step_encoding.rs) handles \X\ \X2\ \X4\ \S\ \P\ escapes; a malformed \S\ immediately before a multibyte char must not panic (#1500). Keep s_escape_before_multibyte_char_does_not_panic green on any change to that decoder.
• Geometry diagnostics are feature-gated. observability = ["dep:tracing"] routes warn/debug through tracing (the server enables it via ifc-lite-processing/observability); default builds compile zero tracing code. Emit via the diag_warn! / diag_debug! macros (geometry/src/diag.rs), never raw eprintln in the kernel, and the feature-off expansion must reproduce the old output byte-for-byte. csg_capture and debug_geometry are the other opt-in features.
• No build.rs anywhere; the tree is pure Rust. The Manifold/Clipper2 C++/cmake kernel was deleted at M9, so a plain cargo build needs no system C++/cmake. The stale "build the Manifold/Clipper2 C++ kernel via cmake" comment in determinism.yml is dead; ignore it.
• The pinned toolchain is repo-root /rust-toolchain.toml (channel = "nightly-2025-11-15", components rust-src + clippy, target wasm32-unknown-unknown); that is what CI uses, and it is now the ONLY toolchain file in the tree. There used to be a second one, rust/rust-toolchain.toml, floating on channel = "nightly" with no date pin and no clippy, which shadowed the root pin for everything under rust/ -- so cargo run from inside rust/ used a different compiler than the gate (measured 9 months apart, clippy 0.1.99 from inside rust/ vs the pinned 0.1.93, disagreeing on four -D warnings lints in ifc-lite-core). It was deleted in #2834; rustup now resolves the root pin from anywhere in the tree.
• Kernel boolean entry points are subtract / subtract_many / union / union_many / intersection (geometry/src/kernel/mesh_bridge.rs). subtract_many returns Option<Mesh> (None on kernel failure), so call sites must handle the fallback rather than unwrap.