Skip to content

feat(math): Milestone 2 Phase 1 — spawn-math spatial primitives, f64 WorldPos, reversed-Z, and libm det subset - #10

Merged
brasga-a merged 4 commits into
masterfrom
feat/m2-p1-math
Nov 18, 2026
Merged

brasga-a merged 4 commits into
masterfrom
feat/m2-p1-math

Conversation

@brasga-a

@brasga-a brasga-a commented Nov 18, 2026 •

Copy link
Copy Markdown
Owner

Requirements covered

  • F3D-FR-01 (spawn-math spatial & local f32 primitives: Vec2, Vec3, Vec4, column-major Mat3/Mat4, Quat, Transform, Aabb, Ray, Plane, Sphere, right-handed Y-up -Z forward, radians, meters)
  • F3D-FR-02 (distinct f64 world coordinates WorldPos & DVec3, explicit camera_relative_f32 conversion, reversed-Z finite & infinite-far Vulkan projections with single-site NDC Y-flip preserving a > 0 CCW front faces)
  • F3D-FR-03 (libm deterministic math subset det in f32/f64, clamped inverse trig, yaw/pitch quaternion & basis helpers)
  • ADR-0010 (Math library conventions & precision hierarchy) and ADR-0009 (typed located MathError MATH-0001..MATH-0005 with snapshot tests)

What changed

  • Implemented crates/spawn-math (#![forbid(unsafe_code)], zero spawn-* dependencies, zero third-party types in public API, zero non-test unwrap/expect/panic!/todo!).
  • Enforced shear-free TRS invariants end-to-end: Transform::try_mul_transform + Transform::mul_mat4 (symmetric with try_inverse + inverse_mat4), and right-handed SO(3) orthonormality + reconstruction validation in Quat::try_from_mat3 / Mat4::try_to_scale_rotation_translation / Transform::try_from_mat4 (rejecting sheared matrices while preserving negative-scale reflection TRS round-trips).
  • Added automated verification suites F3D-T01..F3D-T04 and Phase 1 F3D-T13 math hygiene audit.
  • Synchronized AGENTS.md, crates/spawn-math/AGENTS.md, docs/DEPENDENCIES.md, and docs/first-3d/{PLAN,VERIFICATION}.md.

Tests run

$ ./scripts/check.sh -> exit 0 (fmt, clippy --all-targets -D warnings, workspace tests, rustdoc -D warnings, wayland/vulkan checks, cargo deny check)
$ PATH=/usr/bin:/usr/local/bin:/bin ./scripts/check.sh -> exit 0 (headless CI environment)
$ cargo test -p spawn-math -> exit 0
  - 2 unit tests (MathError report snapshot + code stability)
  - 9 F3D-T01 tests (unit + proptest algebraic laws + glam oracle + NaN/Inf/subnormal/zero/singular/180-deg + SO(3)/TRS shear & negative-scale torture cases)
  - 5 F3D-T02 tests (finite & infinite reversed-Z mapping, strict depth monotonicity, single-site +Y -> -Y_ndc, positive Vulkan signed area a > 0)
  - 3 F3D-T03 tests (WorldPos vs Vec3 separation + +-50 km camera-relative f32 precision < 1e-5 m)
  - 4 F3D-T04 tests (det golden-vector to_bits() tables in f32 and f64 across quadrants, subnormals, poles)
  - 1 F3D-T13 Phase 1 test (cargo tree -p spawn-math -e normal -> only libm, public API audit, forbid(unsafe_code))
  - 4 doctests (including 3 compile_fail proofs for WorldPos/Vec3 separation)
$ cargo tree -p spawn-math -e normal -> spawn-math v0.1.0 -> libm v0.2.16
$ cargo deny check -> advisories ok, bans ok, licenses ok, sources ok

Platforms tested

  • Linux x86_64 (Rust 1.99.1 pinned toolchain; headless spawn-math verification + full ./scripts/check.sh workspace gates). Windows CI runs on PR via .github/workflows/ci.yml.

Invariants touched

  • SPN-INV-003 (genre-free engine infrastructure), SPN-INV-004 (zero spawn-* dependencies in spawn-math), SPN-INV-009 (headless compilation & tests), SPN-INV-011 (zero third-party types in public API)
  • SPN-INV-020, SPN-INV-021, SPN-INV-023 (approved dependencies & license check)
  • SPN-INV-030, SPN-INV-031, SPN-INV-032, SPN-INV-033 (no panics on caller input, typed located MathError, #![forbid(unsafe_code)], clippy clean)
  • SPN-INV-044 (det pure-Rust libm subset & IEEE sqrt, explicit FMA policy)
  • SPN-INV-050, SPN-INV-051, SPN-INV-052, SPN-INV-053, SPN-INV-054 (spatial conventions, distinct f64 WorldPos, explicit camera_relative_f32, reversed-Z + single-site Vulkan Y-flip)
  • SPN-INV-084 (no build.rs), SPN-INV-100, SPN-INV-101 (SCAFFOLD -> EXISTS status sync)

Dependencies added/changed (Gate G2)

Crate Version Kind License Purpose
libm 0.2.16 normal (spawn-math) MIT Pure-Rust deterministic transcendentals (default-features = false)
glam 0.34.3 dev (spawn-math) MIT OR Apache-2.0 Independent reference oracle in F3D-T01/F3D-T02
proptest 1.12.0 dev (spawn-math) MIT OR Apache-2.0 Property-based algebraic & projection law tests
insta 1.49.0 dev (spawn-math) Apache-2.0 Snapshot testing for MathError diagnostic reports

All four are pre-approved in docs/DEPENDENCIES.md (In use column updated to Yes (spawn-math)).

Known limitations

  • Scalar implementation only (SIMD optimization remains PLANNED per ADR-0010 until profiling demonstrates a bottleneck).
  • Headless pure-CPU math crate; GPU/window behavior is untouched in Phase 1 (Phases 2–6 remain PLANNED).

@brasga-a
brasga-a changed the base branch from docs/milestone-2-first-3d to master November 18, 2026 19:39
@brasga-a
brasga-a merged commit 9033f0e into master Nov 18, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant