feat(geom): rmg-geom foundation (split PR 2)

.devcontainer/devcontainer.json

@@ -0,0 +1,37 @@
+{
+  "name": "echo-dev",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "username": "vscode",
+      "installZsh": false
+    },
+    "ghcr.io/devcontainers/features/rust:1": {
+      "profile": "minimal",
+      "components": ["rustfmt", "clippy"]
+    },
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "20"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "rust-lang.rust-analyzer",
+        "serayuzgur.crates",
+        "tamasfe.even-better-toml",
+        "vadimcn.vscode-lldb"
+      ]
+    }
+  },
+  "mounts": [
+    "source=devcontainer-cargo-cache,target=/usr/local/cargo,type=volume",
+    "source=devcontainer-rustup-cache,target=/usr/local/rustup,type=volume"
+  ],
+  "containerEnv": {
+    "CARGO_TERM_COLOR": "always"
+  },
+  "overrideCommand": false,
+  "postCreateCommand": "/bin/bash .devcontainer/post-create.sh"
+}

.devcontainer/post-create.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[devcontainer] Installing MSRV toolchain (1.68.0) and respecting rust-toolchain.toml..."
+if ! command -v rustup >/dev/null 2>&1; then
+  curl --proto '=https' --tlsv1.2 --retry 10 --retry-connrefused --location --silent --show-error --fail https://sh.rustup.rs | sh -s -- --default-toolchain none -y
+  export PATH="$HOME/.cargo/bin:$PATH"
+fi
+
+rustup toolchain install 1.68.0 --profile minimal
+# Do not override default; let rust-toolchain.toml control toolchain selection for this repo.
+# Install optional newer toolchain for local convenience (kept as non-default).
+rustup toolchain install 1.90.0 --profile minimal || true
+# Ensure components/targets are available for the active (rust-toolchain.toml) toolchain.
+rustup component add rustfmt clippy || true
+rustup target add wasm32-unknown-unknown || true
+
+echo "[devcontainer] Priming cargo registry cache (optional)..."
+cargo fetch || true
+
+echo "[devcontainer] Done. Run 'cargo test -p rmg-core' or 'make ci-local' to validate."

.githooks/pre-commit

@@ -49,8 +49,27 @@ if command -v rustup >/dev/null 2>&1; then
   fi
 fi
 
-# 3) Format check (fast)
-cargo fmt --all -- --check
+# 3) Format (auto-fix if opted in)
+_auto_fmt="${ECHO_AUTO_FMT:-1}"
+case "${_auto_fmt}" in
+  1|true|TRUE|yes|YES|on|ON)
+    echo "pre-commit: ECHO_AUTO_FMT=${_auto_fmt} → running cargo fmt (auto-fix)"
+    cargo fmt --all || { echo "pre-commit: cargo fmt failed" >&2; exit 1; }
+    # Re-stage only staged files that were reformatted
+    if STAGED=$(git diff --cached --name-only); then
+      if [[ -n "$STAGED" ]]; then
+        echo "$STAGED" | xargs -r git add --
+      fi
+    fi
+    ;;
+  0|false|FALSE|no|NO|off|OFF)
+    cargo fmt --all -- --check || { echo "pre-commit: cargo fmt check failed" >&2; exit 1; }
+    ;;
+  *)
+    # Unknown value → safest is check-only
+    cargo fmt --all -- --check || { echo "pre-commit: cargo fmt check failed" >&2; exit 1; }
+    ;;
+esac
 
 # 4) Docs guard (scaled): only require docs when core public API changed
 STAGED=$(git diff --cached --name-only)

AGENTS.md

@@ -26,6 +26,12 @@ Welcome to the **Echo** project. This file captures expectations for any LLM age
 - Respect determinism: preferably no random seeds without going through the Echo PRNG.
 - Run `cargo clippy --all-targets -- -D missing_docs` and `cargo test` before every PR; CI will expect a zero-warning, fully documented surface.
 
+### Git Hooks & Local CI
+- Install repo hooks once with `make hooks` (configures `core.hooksPath`).
+- Formatting: pre-commit auto-fixes with `cargo fmt` by default. Set `ECHO_AUTO_FMT=0` to run check-only instead.
+- Toolchain: pre-commit verifies your active toolchain matches `rust-toolchain.toml`.
+- Docs Guard: when core API files change, the hook requires updating `docs/execution-plan.md` and `docs/decision-log.md` (mirrors the CI check).
+
 ## Git Real
 1. **NEVER** use `--force` with any git command. If you think you need it, stop and ask the human for help.
 2. **NEVER** use rebase. Embrace messy distributed history; plain merges capture the truth, rebases rewrite it.

CONTRIBUTING.md

@@ -22,6 +22,10 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize:
 1. Clone the repo and run `cargo check` to ensure the Rust workspace builds.
 2. Read `docs/architecture-outline.md` and `docs/execution-plan.md`.
 3. Review `AGENTS.md` for collaboration norms before touching runtime code.
+4. Optional: develop inside the devcontainer for toolchain parity with CI.
+   - Open in VS Code → "Reopen in Container" (requires the Dev Containers extension).
+   - The container includes Rust stable + MSRV toolchains, clippy/rustfmt, Node, and gh.
+   - Post-create installs MSRV 1.68.0 and wasm target.
 
 ## Branching & Workflow
 - Keep `main` pristine. Create feature branches like `echo/<feature>` or `timeline/<experiment>`.
@@ -53,6 +57,14 @@ Echo is a deterministic, renderer-agnostic engine. We prioritize:
 - TypeScript tooling (when active) lives in `reference/typescript/`; follow local lint configs when reactivated.
 - Avoid non-deterministic APIs (no wall-clock, no uncontrolled randomness). Use Echo’s deterministic services.
 
+### Git Hooks (recommended)
+- Install repo hooks once: `make hooks` (configures `core.hooksPath` to `.githooks`).
+- Pre-commit runs:
+  - cargo fmt (auto-fix by default; set `ECHO_AUTO_FMT=0` for check-only)
+  - Toolchain pin verification (matches `rust-toolchain.toml`)
+  - A minimal docs-guard: when core API files change, it requires updating `docs/execution-plan.md` and `docs/decision-log.md` (mirrors CI)
+- To auto-fix formatting on commit: `ECHO_AUTO_FMT=1 git commit -m "message"`
+
 ## Communication
 - Major updates should land in `docs/execution-plan.md` and `docs/decision-log.md`; rely on GitHub discussions or issues for longer-form proposals.
 - Respect the temporal theme—leave the codebase cleaner for the next timeline traveler.

Cargo.toml

@@ -3,7 +3,8 @@ members = [
     "crates/rmg-core",
     "crates/rmg-ffi",
     "crates/rmg-wasm",
-    "crates/rmg-cli"
+    "crates/rmg-cli",
+    "crates/rmg-geom"
 ]
 resolver = "2"
 

README.md

@@ -171,6 +171,23 @@ There's a ton of other advanced reasons why it's cool, but that's nerd stuff. Le
 - Use expressive commits (`subject` / `body` / optional `trailer`)—tell future us the *why*, not just the *what*.
 - Treat determinism as sacred: prefer Echo’s PRNG, avoid non-deterministic APIs without wrapping them.
 
+### Git Hooks
+
+Install the repo’s hooks so formatting and quick checks run before commits:
+
+```
+make hooks
+```
+
+- The pre-commit hook auto-fixes formatting by default (runs `cargo fmt --all`).
+- To switch to check-only mode for a commit, set `ECHO_AUTO_FMT=0`:
+
+```
+ECHO_AUTO_FMT=0 git commit -m "your message"
+```
+
+You can also export `ECHO_AUTO_FMT=0` in your shell rc if you prefer check-only always.
+
 ### Development Principles
 
 1. **Tests First** – Write failing unit/integration/branch tests before new engine work.

crates/rmg-core/src/tx.rs

@@ -12,7 +12,7 @@
 /// - Zero (`TxId(0)`) is reserved as invalid. [`crate::Engine::begin`] never returns zero.
 /// - External callers using [`TxId::from_raw`] must not construct `TxId(0)` unless
 ///   they have a valid reason (e.g., sentinel in FFI); using invalid ids with engine
-///   operations returns [`EngineError::UnknownTx`].
+///   operations returns [`crate::engine_impl::EngineError::UnknownTx`].
 ///
 /// The `#[repr(transparent)]` attribute ensures FFI ABI compatibility: `TxId` has
 /// the same memory layout as `u64` across the FFI/Wasm boundary.
@@ -23,9 +23,9 @@ pub struct TxId(u64);
 impl TxId {
     /// Constructs a `TxId` from a raw `u64` value.
     ///
-    /// # Safety Note
-    /// Callers must not construct `TxId(0)` as it is reserved as invalid.
-    /// Using an invalid `TxId` with engine operations results in undefined behavior.
+    /// # Note on zero
+    /// Constructing `TxId(0)` is allowed, but engine operations treat it as
+    /// invalid and will return [`crate::engine_impl::EngineError::UnknownTx`].
     #[must_use]
     pub const fn from_raw(value: u64) -> Self {
         Self(value)

crates/rmg-geom/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "rmg-geom"
+version = "0.1.0"
+edition = "2021"
+description = "Echo geometry primitives: AABB, transforms, temporal proxies, and broad-phase scaffolding"
+license = "Apache-2.0"
+repository = "https://github.com/flyingrobots/echo"
+readme = "../../README.md"
+keywords = ["echo", "geometry", "aabb", "broad-phase"]
+categories = ["game-engines", "data-structures"]
+
+[dependencies]
+rmg-core = { path = "../rmg-core" }
+
+[dev-dependencies]

crates/rmg-geom/src/lib.rs

@@ -0,0 +1,33 @@
+#![deny(
+    warnings,
+    clippy::all,
+    clippy::pedantic,
+    rust_2018_idioms,
+    missing_docs,
+    clippy::unwrap_used,
+    clippy::expect_used,
+    clippy::panic
+)]
+#![doc = r"Geometry primitives for Echo.
+
+This crate provides:
+- Axis-aligned bounding boxes (`Aabb`).
+- Rigid transforms (`Transform`).
+- Temporal utilities (`Tick`, `TemporalTransform`, `TemporalProxy`).
+- A minimal broad-phase trait and an AABB-based pairing structure.
+
+Design notes:
+- Deterministic: no ambient RNG; ordering of pair outputs is canonical.
+- Float32 throughout; operations favor clarity and reproducibility.
+- Rustdoc is treated as part of the contract; public items are documented.
+"]
+
+/// Time-aware utilities for broad-phase and motion.
+pub mod temporal;
+/// Foundational geometric types.
+pub mod types;
+// Broad-phase will land in a follow-up PR.
+// pub mod broad;
+
+pub use types::aabb::Aabb;
+pub use types::transform::Transform;

crates/rmg-geom/src/temporal/manifold.rs

@@ -0,0 +1,40 @@
+use crate::temporal::tick::Tick;
+use crate::types::aabb::Aabb;
+
+/// Broad-phase proxy summarizing an entity’s swept position manifold over a tick.
+///
+/// Stores a conservative fat AABB and the owning `entity` identifier (opaque
+/// to the geometry layer). The proxy is suitable for insertion into a broad-
+/// phase accelerator.
+#[derive(Debug, Copy, Clone, PartialEq)]
+pub struct PositionProxy {
+    entity: u64,
+    tick: Tick,
+    fat: Aabb,
+}
+
+impl PositionProxy {
+    /// Creates a new proxy for `entity` at `tick` with precomputed `fat` AABB.
+    #[must_use]
+    pub const fn new(entity: u64, tick: Tick, fat: Aabb) -> Self {
+        Self { entity, tick, fat }
+    }
+
+    /// Opaque entity identifier owning this proxy.
+    #[must_use]
+    pub const fn entity(&self) -> u64 {
+        self.entity
+    }
+
+    /// Tick associated with the motion window.
+    #[must_use]
+    pub const fn tick(&self) -> Tick {
+        self.tick
+    }
+
+    /// Conservative fat AABB for this proxy.
+    #[must_use]
+    pub const fn fat(&self) -> Aabb {
+        self.fat
+    }
+}

crates/rmg-geom/src/temporal/mod.rs

@@ -0,0 +1,8 @@
+//! Temporal types and helpers used for tick-based motion and broad-phase.
+
+#[doc = "Broad-phase proxy carrying entity id, tick, and fat AABB."]
+pub mod manifold;
+#[doc = "Discrete Chronos ticks (u64 newtype)."]
+pub mod tick;
+#[doc = "Start/end transforms over a tick and fat AABB computation."]
+pub mod timespan;

crates/rmg-geom/src/temporal/tick.rs

@@ -0,0 +1,35 @@
+/// Discrete simulation tick in Chronos time.
+///
+/// The engine advances in integer ticks with a fixed `dt` per branch. This
+/// newtype ensures explicit tick passing across APIs.
+#[repr(transparent)]
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Tick {
+    index: u64,
+}
+
+impl Tick {
+    /// Creates a new tick with the given index.
+    #[must_use]
+    pub const fn new(index: u64) -> Self {
+        Self { index }
+    }
+
+    /// Returns the tick index.
+    #[must_use]
+    pub const fn index(&self) -> u64 {
+        self.index
+    }
+}
+
+impl From<u64> for Tick {
+    fn from(value: u64) -> Self {
+        Self { index: value }
+    }
+}
+
+impl From<Tick> for u64 {
+    fn from(t: Tick) -> Self {
+        t.index
+    }
+}

crates/rmg-geom/src/temporal/timespan.rs

@@ -0,0 +1,50 @@
+use crate::types::{aabb::Aabb, transform::Transform};
+
+/// Transform at two adjacent ticks used to bound motion in the broad-phase.
+///
+/// - `start` corresponds to tick `n`.
+/// - `end` corresponds to tick `n+1`.
+///
+/// Determinism and plan:
+/// - `fat_aabb` below currently uses a union of the start/end AABBs. This is
+///   conservative for linear motion and sufficient for pairing/CCD triggers.
+/// - Future: introduce a quantized margin policy (based on velocity, `dt`, and
+///   shape scale) so that fat proxies are identical across peers/branches. The
+///   policy and quantization will be recorded in the graph/spec.
+#[derive(Debug, Copy, Clone, PartialEq)]
+pub struct Timespan {
+    start: Transform,
+    end: Transform,
+}
+
+impl Timespan {
+    /// Creates a new `Timespan` from start and end transforms.
+    #[must_use]
+    pub const fn new(start: Transform, end: Transform) -> Self {
+        Self { start, end }
+    }
+
+    /// Returns the start transform.
+    #[must_use]
+    pub const fn start(&self) -> Transform {
+        self.start
+    }
+
+    /// Returns the end transform.
+    #[must_use]
+    pub const fn end(&self) -> Transform {
+        self.end
+    }
+
+    /// Computes a conservative fat AABB for a collider with local-space `shape` AABB.
+    ///
+    /// The fat box is defined as the union of the shape’s AABBs at the start and
+    /// end transforms. This is conservative for linear motion and suffices for
+    /// broad-phase pairing and CCD triggering.
+    #[must_use]
+    pub fn fat_aabb(&self, shape: &Aabb) -> Aabb {
+        let a0 = shape.transformed(&self.start.to_mat4());
+        let a1 = shape.transformed(&self.end.to_mat4());
+        a0.union(&a1)
+    }
+}