docs(math): deterministic harness notes

[flyingrobots]

Brings over small doc additions from docs/update-math-plan into main:

• docs/math-validation-plan.md: notes on Rust harness and fixture strategy
• docs/spec-deterministic-math.md: note about Rust float32 primitives as source of truth

No code changes. Keeps runtime determinism contract untouched.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

📥 Commits

Reviewing files that changed from the base of the PR and between 68189a3 and a11e53e.

📒 Files selected for processing (1)

• docs/spec-deterministic-math.md (4 hunks)

 __________________________________________
< The GIL can’t stop these rabbit threads. >
 ------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

Summary by CodeRabbit

• Documentation
  • Updated math validation testing strategy with completed task milestones.
  • Extended specification documentation with implementation status and parity notes for mathematical operations.

Walkthrough

Documentation updates marking completion of Rust-based math validation harness implementation and adding cross-language parity notes to the deterministic math specification, tracking which operations have Rust implementations versus remaining TODO items.

Changes

Cohort / File(s)	Change Summary
Math Validation Plan docs/math-validation-plan.md	Marks two tasks complete: reference fixtures generated for scalar/vector/matrix/quaternion/PRNG; Rust validation suite implemented (cargo test). Documents future TypeScript Vitest mirroring.
Deterministic Math Spec docs/spec-deterministic-math.md	Adds Rust parity notes across Mode, Vec2/Vec3/Vec4, Mat3/Mat4, Quat, Transform, and PRNG sections indicating implementation status and pending operations.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

• Documentation-only changes with no logic, API signatures, or runtime impact
• Straightforward status tracking and parity references that require basic verification

Possibly related PRs

• Core: add deterministic math module #4: Implements the actual Rust math validation harness, fixtures (math.rs, math_validation.rs, math-fixtures.json), and corresponding deterministic math module that this documentation references.

Poem

🦀 Docs that track the work we've done,
Math validation—Rust has won!
Vec3 adds, quaternions spin,
Parity grows, let Phase 2 begin! ✨

---

From: Linus Torvalds torvalds@linux-foundation.org
To: PR Author
Cc: code-rabbit@vger.kernel.org

Look, documentation is great. It really is. But let's be honest here: you're updating markdown files to track what's already been implemented elsewhere. That's not a feature, that's notes about features.

The Rust harness is done. Good. Vec3 has add/sub/scale/dot/cross? Fantastic. But for Vec2 and Vec4 you left them as TODO. TODO. In documentation. That's like leaving a half-eaten sandwich on the kitchen counter and documenting that you did it. Either finish it or don't, but don't make me read about your incomplete work.

That said, at least you're being transparent about what's missing. I respect that. The parity tracking is sensible. Just don't make a habit of committing aspirational documentation without the code to back it up.

BunBun

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "docs(math): deterministic harness notes" is clearly related to the primary change in the changeset. The math-validation-plan.md file update is fundamentally about documenting the Rust harness validation strategy and fixture approach, which directly aligns with "deterministic harness notes." The title is concise, uses proper documentation conventions, and accurately reflects a significant aspect of the changeset. While it doesn't exhaustively capture all updates (such as the Rust parity notes in spec-deterministic-math.md), it effectively summarizes the main focus of the changes.
Description Check	✅ Passed	The description is clearly related to the changeset and provides accurate, relevant context. It explicitly maps the changes to the two modified files (math-validation-plan.md and spec-deterministic-math.md), mentions the Rust harness and fixture strategy as well as Rust float32 primitives, and clarifies that there are no code changes. The description directly corresponds to what the raw summary documents and provides sufficient context for understanding the PR's purpose without unnecessary verbosity.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a771189 and 68189a3.

📒 Files selected for processing (2)

• docs/math-validation-plan.md (2 hunks)
• docs/spec-deterministic-math.md (3 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

docs/spec-deterministic-math.md

50-50: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

56-56: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

62-62: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Security Audit

🔇 Additional comments (3)

docs/math-validation-plan.md (2)

45-47: Documentation accurately reflects completed Rust harness strategy. The Tooling section now correctly describes the shift from ephemeral Vitest snapshots to a deterministic, referenceable Rust validation harness backed by JSON fixtures. Clear roadmap to TypeScript mirroring. ✓

---

61-62: Task completion tracking is consistent with PR objectives. Fixture generation and Rust-based validation suite implementation are correctly marked complete; remaining tasks properly remain open. No discrepancies detected. ✓

docs/spec-deterministic-math.md (1)

29-29: Parity notes are well-placed, but verify they track actual Rust implementation status. The six Rust parity additions (lines 29, 48, 54, 60, 65, 91) clearly document cross-language capability gaps and provide valuable context for FFI/WASM adapter developers. However, these notes make specific claims about method availability that could become stale if Rust implementations progress separately. Ensure this documentation stays synchronized with actual rmg-core code as development continues.

Can you confirm these parity claims match the current state of rmg-core implementations?

• Vec3: add/sub/scale/dot/cross/length/normalize present; Vec2/Vec4 actually TODO?
• Mat4: multiply/transform_point present; identity/fromRotation/invert actually pending?
• Quat: identity/fromAxisAngle/multiply/normalize/to_mat4 present; slerp actually TBD?
• PRNG: seeding/next_f32/next_int present; state/jump actually deferred?

Also applies to: 48-48, 54-54, 60-60, 65-65, 91-91