diff --git a/crates/rmg-core/src/math/mod.rs b/crates/rmg-core/src/math/mod.rs index 69634cf0..5fc531bd 100644 --- a/crates/rmg-core/src/math/mod.rs +++ b/crates/rmg-core/src/math/mod.rs @@ -8,6 +8,7 @@ use std::f32::consts::TAU; mod mat4; mod prng; mod quat; +mod scalar; mod vec3; #[doc(inline)] @@ -17,6 +18,8 @@ pub use prng::Prng; #[doc(inline)] pub use quat::Quat; #[doc(inline)] +pub use scalar::Scalar; +#[doc(inline)] pub use vec3::Vec3; /// Degeneracy threshold used by math routines to detect near-zero magnitudes. diff --git a/crates/rmg-core/src/math/scalar.rs b/crates/rmg-core/src/math/scalar.rs new file mode 100644 index 00000000..36f1dbc4 --- /dev/null +++ b/crates/rmg-core/src/math/scalar.rs @@ -0,0 +1,84 @@ +//! Deterministic scalar arithmetic abstraction for Echo math. +//! +//! This trait provides a minimal, platform-stable surface for numeric code in +//! Echo to depend on without committing to a single concrete representation. +//! Implementations must uphold determinism across supported platforms and are +//! expected to encapsulate representation-specific policies (e.g., float32 +//! canonicalization or fixed-point scaling). +//! +//! Scope (Issue #115): +//! - Core arithmetic: add, sub, mul, div, neg. +//! - Core transcendentals: sin, cos (angles in radians). +//! +//! Out of scope for this commit: +//! - Canonicalization of `-0.0` to `+0.0` and subnormal flushing (to be handled +//! by concrete float wrappers in a follow-up task). +//! - Lookup-table or polynomial-backed trig implementations (tracked separately; +//! this trait only declares the API). +//! - Concrete backends: `F32Scalar` and `DFix64` will implement this trait in +//! subsequent changes. +//! +//! Determinism contract: +//! - Operations must be pure and total for all valid inputs of the +//! implementation’s domain. +//! - For floating-point backends, implementations are responsible for any +//! canonicalization/flush semantics required by Echo’s determinism policy. +//! - Trigonometric functions interpret arguments as radians and must be +//! consistent across platforms for identical inputs (e.g., via LUT/polynomial +//! in later work). + +use core::ops::{Add, Div, Mul, Neg, Sub}; + +/// Deterministic scalar arithmetic and basic transcendentals. +/// +/// This trait abstracts the numeric core used by Echo so that engine code can +/// be written generically and later bound to either a deterministic float32 +/// wrapper (`F32Scalar`) or a fixed-point implementation (`DFix64`). Arithmetic +/// operators are required via the standard operator traits for ergonomic use of +/// `+`, `-`, `*`, `/`, and unary `-` in generic code. +pub trait Scalar: + Copy + + core::fmt::Debug + + PartialEq + + Send + + Sync + + 'static + + Add + + Sub + + Mul + + Div + + Neg +{ + /// Returns the additive identity (zero). + fn zero() -> Self; + + /// Returns the multiplicative identity (one). + fn one() -> Self; + + /// Returns the sine of `self` (radians) under deterministic semantics. + fn sin(self) -> Self; + + /// Returns the cosine of `self` (radians) under deterministic semantics. + fn cos(self) -> Self; + + /// Returns both sine and cosine of `self` (radians). + /// + /// Default implementation computes `sin` and `cos` separately; concrete + /// implementations may override for efficiency or shared range reduction. + fn sin_cos(self) -> (Self, Self) { + (self.sin(), self.cos()) + } + + /// Converts from `f32` into this scalar type. + /// + /// This is intended for boundary crossings (e.g., deserializing payloads) + /// and test scaffolding. Implementations must apply any necessary + /// canonicalization required by Echo’s determinism policy. + fn from_f32(value: f32) -> Self; + + /// Converts this scalar value to `f32` for interop and diagnostics. + /// + /// Implementations should define rounding policy precisely (e.g., ties to + /// even) and ensure platform-stable results. + fn to_f32(self) -> f32; +} diff --git a/docs/decision-log.md b/docs/decision-log.md index 9f005a5a..6527b03f 100644 --- a/docs/decision-log.md +++ b/docs/decision-log.md @@ -4,6 +4,7 @@ | Date | Context | Decision | Rationale | Consequence | | ---- | ------- | -------- | --------- | ----------- | +| 2025-11-03 | Scalar foundation | Add `rmg-core::math::Scalar` trait (operator supertraits + sin/cos) | Arithmetic via `Add/Sub/Mul/Div/Neg` supertraits for ergonomic `+ - * /`; `sin/cos` methods declared; canonicalization/LUTs deferred | Unblocks F32Scalar and DFix64 implementations; math code can target a stable trait | | 2025-10-23 | Repo reset | Adopt pnpm + TS skeleton | Monorepo scaffolding for Echo | Phase 0 tasks established | | 2025-10-24 | Branch tree spec | Integrate roaring bitmaps and chunk epochs | Deterministic merges & diffs | Snapshot policy updated | | 2025-10-24 | Codex’s Baby spec | Event envelopes, temporal bridge integration | Align with causality layer | Security envelopes + inspector updates | diff --git a/docs/echo-total.md b/docs/echo-total.md index 3de3cf86..a402b25b 100644 --- a/docs/echo-total.md +++ b/docs/echo-total.md @@ -260,6 +260,14 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s ## Today’s Intent +> 2025-11-03 — Issue #115: Scalar trait scaffold + +- Added `rmg-core::math::scalar::Scalar` trait declaring deterministic scalar operations. +- Arithmetic is required via operator supertraits: `Add/Sub/Mul/Div/Neg` with `Output = Self` for ergonomic `+ - * / -` use in generics. +- Explicit APIs included: `zero`, `one`, `sin`, `cos`, `sin_cos` (default), `from_f32`, `to_f32`. +- No implementations yet (F32Scalar/DFix64 follow); no canonicalization or LUTs in this change. +- Exported via `rmg-core::math::Scalar` for consumers. + > 2025-11-02 — PR-12: benches updates (CI docs guard) - Dependency policy: pin `blake3` in `rmg-benches` to `1.8.2` (no wildcard). @@ -598,6 +606,7 @@ Remember: every entry here shrinks temporal drift between Codices. Leave breadcr | Date | Context | Decision | Rationale | Consequence | | ---- | ------- | -------- | --------- | ----------- | +| 2025-11-03 | Scalar foundation | Add `rmg-core::math::Scalar` trait (operator supertraits + sin/cos) | Arithmetic via `Add/Sub/Mul/Div/Neg` supertraits for ergonomic `+ - * /`; `sin/cos` methods declared; canonicalization/LUTs deferred | Unblocks F32Scalar and DFix64 implementations; math code can target a stable trait | | 2025-10-23 | Repo reset | Adopt pnpm + TS skeleton | Monorepo scaffolding for Echo | Phase 0 tasks established | | 2025-10-24 | Branch tree spec | Integrate roaring bitmaps and chunk epochs | Deterministic merges & diffs | Snapshot policy updated | | 2025-10-24 | Codex’s Baby spec | Event envelopes, temporal bridge integration | Align with causality layer | Security envelopes + inspector updates | diff --git a/docs/execution-plan.md b/docs/execution-plan.md index 2014045f..6cef3ef7 100644 --- a/docs/execution-plan.md +++ b/docs/execution-plan.md @@ -33,6 +33,14 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s ## Today’s Intent +> 2025-11-03 — Issue #115: Scalar trait scaffold + +- Added `rmg-core::math::scalar::Scalar` trait declaring deterministic scalar operations. +- Arithmetic is required via operator supertraits: `Add/Sub/Mul/Div/Neg` with `Output = Self` for ergonomic `+ - * / -` use in generics. +- Explicit APIs included: `zero`, `one`, `sin`, `cos`, `sin_cos` (default), `from_f32`, `to_f32`. +- No implementations yet (F32Scalar/DFix64 follow); no canonicalization or LUTs in this change. +- Exported via `rmg-core::math::Scalar` for consumers. + > 2025-11-02 — PR-12: benches updates (CI docs guard) - Dependency policy: pin `blake3` in `rmg-benches` to `1.8.2` (no wildcard).