ENG2-P8-08: cgmath → core/math migration (deprecated dep, 36 files)

[aram-devdocs]

Parent

• Program: ENG2 — GoudEngine v2 Rebuild (see the pinned master tracking issue)
• Phase / Milestone: Phase 8 — Capability Gaps (eng2-p8-capabilities)
• Batch / Group: Batch 8.2 — Gameplay services, Group D
• Runbook spec: docs/src/runbook/phases/phase-8.md (committed with the roadmap)

Summary

Migrate the remaining 36 files using the deprecated/unmaintained cgmath crate onto the engine's own core/math types, then remove the cgmath dependency and its two ignored RUSTSEC advisories entirely.

Architecture Context

Layer: Cuts across Layer 1 (Foundation, core/math/ is the migration target) through Layer 4 (Engine, libs/graphics/renderer3d/ holds most remaining usages).
Modules/types touched:

• goud_engine/src/core/math/ (vec2.rs, vec3.rs, vec4.rs, mod.rs) — the FFI-safe, #[repr(C)] destination types; extend with any matrix/quaternion operations libs/graphics/renderer3d/ currently gets from cgmath (Matrix4, Quaternion, etc.) that core/math does not yet provide.
• All 36 files currently importing cgmath (full list in Agent Notes) — replace cgmath::Vector3/Matrix4/etc. with core::math equivalents.
• goud_engine/Cargo.toml — remove the cgmath = "0.18.0" dependency once all 36 call sites are migrated.
• deny.toml — remove the two now-obsolete ignored advisories once cgmath is gone.

Boundary constraints (only those that apply):

• Downward-only deps: this is purely internal type substitution; no layer-boundary changes.

Pattern to follow: core/math/vec3.rs:1-16 — the existing Vec3 (#[repr(C)], Clone, Copy, Debug, PartialEq, Default, Serialize, Deserialize) is the template for any new matrix/quaternion type added to close the gap with cgmath's feature set.

Scope

• Audit core/math's current feature set against every cgmath operation used across the 36 files (vector ops already covered by Vec2/Vec3/Vec4; identify missing matrix/quaternion/transform operations).
• Extend core/math with any missing operations (matrix multiply, inverse, quaternion slerp, etc.) needed to fully replace cgmath — no partial migration that keeps cgmath as a dependency for "just the hard parts."
• Migrate all 36 files off cgmath imports onto core/math types, file by file (this is intentionally scheduled after Phases 2/3/6, which the roadmap notes already deleted much cgmath-using code — re-audit the file count before starting, since it may be lower than 36 by the time this issue executes).
• Remove cgmath = "0.18.0" from goud_engine/Cargo.toml.
• Remove the RUSTSEC-2026-0196 and RUSTSEC-2026-0197 ignore entries from deny.toml once the dependency is gone.
• Tests: existing math/transform unit tests must continue to pass unchanged in behavior (this is a representation migration, not a behavior change) — add regression tests for any newly-added core/math operations.

Acceptance Criteria

• cgmath does not appear in goud_engine/Cargo.toml or Cargo.lock.
• grep -rl cgmath goud_engine/src returns zero matches.
• deny.toml no longer ignores RUSTSEC-2026-0196/RUSTSEC-2026-0197, and cargo deny check advisories passes without them.
• cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings clean; cargo test green; ./codegen.sh && git diff --exit-code (drift gate)

Breaking Change & Throne Follow-up

None — additive/internal (pure internal type substitution; no FFI-visible or SDK-visible API changes, since core/math types are already the FFI-facing representation).

Blocked By

None (deliberately sequenced last within Phase 8 batch 8.2 per the roadmap: Phases 2, 3, and 6 already delete much cgmath-using rendering/transform code as a side effect of their own work, shrinking this migration's surface before it starts).

Files Likely Touched

• Modified: goud_engine/src/core/math/{mod.rs,vec2.rs,vec3.rs,vec4.rs} plus new matrix/quaternion files if needed; all remaining files from the 36-file list below that still import cgmath at execution time
• Modified: goud_engine/Cargo.toml, deny.toml

Agent Notes

• cgmath = "0.18.0" is declared at goud_engine/Cargo.toml:38. deny.toml:86-87 explicitly documents it as unmaintained and tracks its removal under 🚨 Security vulnerabilities found in Rust dependencies #704: { id = "RUSTSEC-2026-0196", reason = "cgmath unmaintained (not a vulnerability); the engine's math library. Migration to a maintained alternative is tracked #704." } and { id = "RUSTSEC-2026-0197", reason = "cgmath Matrix::swap_columns UB only on identical indices; the engine never calls it with identical indices. Pending migration — tracked #704." }.
• Grep-confirmed 36 files importing cgmath at audit time (re-check this count before starting — Phases 2/3/6 land first and are expected to shrink it): core/math/{mod.rs,tests.rs,vec2.rs,vec3.rs,vec4.rs}; ecs/components/global_transform/{core.rs,decomposition.rs,mod.rs,operations.rs}; ecs/components/transform/{core.rs,quat.rs,tests.rs}; ffi/renderer3d/{environment/mod.rs,lighting.rs,materials.rs}; libs/graphics/renderer3d/{core_model_instances.rs,core_models/{lifecycle.rs,mod.rs},core_particles.rs,core_primitives.rs,core_skinned.rs,core_static_batch.rs,core/object_transforms.rs,frustum.rs,material.rs,mesh.rs,render_instanced.rs,render/{mod.rs,shadow_render.rs,util.rs},shadow.rs,skinned_mesh.rs,tests.rs,types.rs}; rendering/sprite_batch/culling.rs; sdk/rendering_3d.rs.
• core/math already provides the FFI-safe destination types: Vec3 (core/math/vec3.rs:1-16) is #[repr(C)] with x/y/z f32 fields and derives Serialize/Deserialize — this is the pattern any new matrix/quaternion type added during migration must follow, since core/math types are what actually crosses the FFI boundary today (unlike cgmath types, which never should).
• This is deliberately the last item in its batch: the roadmap notes Phases 2/3/6 (render core, ECS/FFI unification, 2D render v2) already delete substantial cgmath-using rendering and transform code as a side effect of unrelated work, so re-run the 36-file audit at execution time rather than trusting this count as still current.

Verification

cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings
cargo test
./codegen.sh && git diff --exit-code
cargo deny check advisories
grep -rl cgmath goud_engine/src  # must return nothing