@woosh/meep-engine 3.1.0 → 3.2.0

package/src/engine/physics/REVIEW_002.md

@@ -1,151 +1,151 @@
-# REVIEW_002 — TGS solver, contact robustness, and constraints
-
-Retrospective on the "competent → great" push: promoting the solver from
-single-step PGS to substepped TGS, fixing the contact-robustness issues that
-surfaced, and standing up the 6-DOF constraint subsystem. Companion to the
-engine-comparison docs (`CANNON_REVIEW`, `RAPIER_REVIEW`, `JOLT_REVIEW`,
-`BULLET_REVIEW`); this one is a build retrospective, not a comparison.
-
-Scope: the work tracked in `PLAN.md` under "Solver quality" + "Constraints /
-joints". What landed, the hard-won lessons, where the implementation
-deviated from the original plan and why, and what's deferred.
-
----
-
-## What landed
-
-**TGS (Temporal Gauss-Seidel), Phases 1–3.** The solver is now a staged
-pipeline driven by a substep loop:
-`prepare → per substep [redetect-concave / refresh-convex → warm-start →
-solve-velocity → solve-position] → restitution`. Defaults: 4 substeps, 4
-velocity + 1 position iteration per substep. Split-impulse position
-correction (pseudo-velocity folded into the pose, never into real velocity);
-one-shot restitution; SPOOK compliance as the soft-constraint dial.
-
-**Contact robustness.**
-- Box-box SAT reference tie-break deadband → aligned cube stacks 4–10 high
-  settle to zero velocity and sleep.
-- Per-substep concave re-detection → a dynamic concave mesh body (torus knot)
-  settles instead of rocking.
-
-**Constraints — 6-DOF configurable joint** (PhysX D6 / Jolt SixDOF model):
-one constraint type, each of 3 linear + 3 angular DOFs independently
-locked/free/limited/spring/motor. Landed modes: LOCKED linear (ball-socket)
-and LOCKED angular (hinge, weld). Solved as a parallel row set inside the
-same substep loop; island-integrated; generation-checked against stale body
-references.
-
-Coverage went ~698 → 720+ physics tests, all green. Falling-tower bench
-unchanged (~48 ms / 1000 active bodies).
-
----
-
-## Hard-won lessons
-
-These cost real debugging and are the reason the code looks the way it does.
-
-1. **Per-substep warm-start is mandatory under substepping.** The first
-   substep attempt warm-started once per outer step and applied gravity per
-   substep. That mismatch — replaying a *full-frame* impulse against a
-   *single substep* of gravity — over-pushes resting contacts and **explodes**
-   deep stacks (a 10-cube stack hit 9 m of drift / 13 m/s). The fix: gravity
-   per substep **and** warm-start per substep, so each substep's gravity and
-   each substep's replayed impulse cancel exactly at rest. A resting body
-   holds at `v = 0`, `j_n ≈ m·g·h`.
-
-2. **Restitution must gate on the running-max normal impulse, not the
-   end-of-loop value.** With per-substep warm-start, a transient collision's
-   accumulated `j_n` relaxes back to ~0 by the end of the loop (no sustained
-   load to hold it), so gating restitution on the final `j_n` silently killed
-   every bounce. Tracking `maxNormalImpulse` over the whole step (Box2D-v3's
-   trick) is what makes restitution fire.
-
-3. **Analytic separation re-derivation is great for convex, wrong for
-   dynamic concave.** Re-deriving each substep's penetration from frozen
-   witness anchors + current pose (no narrowphase re-run) is cheap and exact
-   *while the contact feature is stable* — true for a convex primitive under
-   the small per-step motion. For a concave body rocking on a mesh, the
-   supporting triangle (and its normal) genuinely changes mid-step, so
-   freezing it pumps energy in. Resolution: convex pairs use the cheap
-   analytic refresh; concave-involved pairs re-run narrowphase geometry each
-   substep (`redetect_concave_contacts`). Hybrid, gated by collider convexity.
-
-4. **The aligned-stack instability was not the solver.** Cube stacks crept
-   and toppled; the instinct was "solver convergence". Dumping
-   `box_box_manifold` across a settling pair showed the normal and contact
-   *count* were stable, but the *reference face* flip-flopped between A and B
-   each frame (their SAT overlaps are exactly equal for aligned boxes, so
-   float noise from a sub-degree wobble decided the winner). That reordered
-   the contacts → flipped the Gauss-Seidel sweep order → alternating bias →
-   creep. A 6-line relative+absolute tie-break deadband (bias ties toward the
-   earlier-tested axis) fixed stacks 4–10. **Lesson: diagnose the manifold
-   before blaming the solver.**
-
-5. **Granularity is everything for dynamic concave.** The first instinct
-   ("decompose the mesh into the exact Delaunay tets we already have") is
-   wrong: a Suzanne is ~8000 tets → ~8000 colliders → ~8000 dynamic-BVH
-   leaves refit every frame. Tet meshing is a *volumetric* (FEM/soft-body)
-   tool. Rigid collision wants the *fewest* convex pieces — a single convex
-   hull for most dynamic objects, or a few-hull (V-HACD-style) decomposition.
-   Recorded as the long-term path; the per-substep re-detection is the
-   interim.
-
-6. **One configurable 6-DOF constraint beats N joint types.** The row math is
-   contact-shaped (Jacobian + effective mass + bias + bounds), so it slots
-   into the existing solver. Concrete joints become *config*: ball-socket =
-   lock 3 linear; hinge = lock 3 linear + 2 angular; weld = lock 6. This
-   minimises distinct code paths — the whole point.
-
-7. **Sign conventions: linear A−B, angular B−A.** The linear rows use
-   "A minus B" (impulse +to A); the angular rows use "B minus A" (impulse
-   +to B). Each is internally consistent — the body-order difference just
-   folds the sign in. Derived carefully against the SPOOK Baumgarte target
-   (`dC/dt = vrel`); both worked first try once written down.
-
----
-
-## Deviations from the original plan (and why)
-
-- **Joints run as a parallel row set, not by porting contacts onto a shared
-  constraint base.** The plan floated either. Porting the working,
-  well-tuned contact path carried regression risk for no immediate benefit;
-  running joints as a second row family in the same substep loop gets the
-  coupling (shared warm-start / islands / substep cadence) at far lower risk.
-  Unifying remains optional.
-
-- **Convex contacts use analytic refresh, not per-substep match-and-merge.**
-  The plan said "substeps refresh contacts via match-and-merge". Analytic
-  re-derivation is cheaper and avoids manifold-lifecycle churn for the convex
-  majority; match-and-merge-style re-detection is reserved for the concave
-  minority (lesson 3).
-
-- **Dynamic concave: per-substep re-detection now, convex proxies later** —
-  not the tet-compound idea first sketched (lesson 5).
-
----
-
-## Deferred (with rationale)
-
-- **Constraints**: prismatic (needs frame-basis linear rows — today's linear
-  locks use world axes, exact only when all 3 are locked), limits, motors,
-  springs (SPOOK soft), swing-twist (ragdoll cone), the raycast-vehicle
-  layer, and extras (pulley/gear/conveyor/breakable). Sequenced in `PLAN.md`.
-- **Trajectory accuracy**: gravity is substepped, so ballistic integration is
-  at the substep rate — good. No higher-order integrator pursued.
-- **Per-island parallel solve / CCD shape-cast / closed-form
-  triangle-vs-primitive remainder**: unchanged backlog items.
-- **Convex hull builder + few-hull decomposition**: the production answer for
-  dynamic concave (lesson 5), not yet built.
-
----
-
-## Bottom line
-
-The engine moved from "competent PGS" to a substepped TGS solver with stable
-stacks, accurate restitution, robust mass ratios, settling dynamic concave
-bodies, and a working 6-DOF constraint (ball-socket / hinge / weld) — i.e.
-chains, ropes, and the structural joints for ragdolls and mechanisms. The
-costliest mistakes were all about *substepping invariants* (warm-start and
-restitution-gating cadence) and *not trusting assumptions* (the stack bug was
-narrowphase, not the solver). The remaining constraint work is incremental
-on a validated framework.
+# REVIEW_002 — TGS solver, contact robustness, and constraints
+
+Retrospective on the "competent → great" push: promoting the solver from
+single-step PGS to substepped TGS, fixing the contact-robustness issues that
+surfaced, and standing up the 6-DOF constraint subsystem. Companion to the
+engine-comparison docs (`CANNON_REVIEW`, `RAPIER_REVIEW`, `JOLT_REVIEW`,
+`BULLET_REVIEW`); this one is a build retrospective, not a comparison.
+
+Scope: the work tracked in `PLAN.md` under "Solver quality" + "Constraints /
+joints". What landed, the hard-won lessons, where the implementation
+deviated from the original plan and why, and what's deferred.
+
+---
+
+## What landed
+
+**TGS (Temporal Gauss-Seidel), Phases 1–3.** The solver is now a staged
+pipeline driven by a substep loop:
+`prepare → per substep [redetect-concave / refresh-convex → warm-start →
+solve-velocity → solve-position] → restitution`. Defaults: 4 substeps, 4
+velocity + 1 position iteration per substep. Split-impulse position
+correction (pseudo-velocity folded into the pose, never into real velocity);
+one-shot restitution; SPOOK compliance as the soft-constraint dial.
+
+**Contact robustness.**
+- Box-box SAT reference tie-break deadband → aligned cube stacks 4–10 high
+  settle to zero velocity and sleep.
+- Per-substep concave re-detection → a dynamic concave mesh body (torus knot)
+  settles instead of rocking.
+
+**Constraints — 6-DOF configurable joint** (PhysX D6 / Jolt SixDOF model):
+one constraint type, each of 3 linear + 3 angular DOFs independently
+locked/free/limited/spring/motor. Landed modes: LOCKED linear (ball-socket)
+and LOCKED angular (hinge, weld). Solved as a parallel row set inside the
+same substep loop; island-integrated; generation-checked against stale body
+references.
+
+Coverage went ~698 → 720+ physics tests, all green. Falling-tower bench
+unchanged (~48 ms / 1000 active bodies).
+
+---
+
+## Hard-won lessons
+
+These cost real debugging and are the reason the code looks the way it does.
+
+1. **Per-substep warm-start is mandatory under substepping.** The first
+   substep attempt warm-started once per outer step and applied gravity per
+   substep. That mismatch — replaying a *full-frame* impulse against a
+   *single substep* of gravity — over-pushes resting contacts and **explodes**
+   deep stacks (a 10-cube stack hit 9 m of drift / 13 m/s). The fix: gravity
+   per substep **and** warm-start per substep, so each substep's gravity and
+   each substep's replayed impulse cancel exactly at rest. A resting body
+   holds at `v = 0`, `j_n ≈ m·g·h`.
+
+2. **Restitution must gate on the running-max normal impulse, not the
+   end-of-loop value.** With per-substep warm-start, a transient collision's
+   accumulated `j_n` relaxes back to ~0 by the end of the loop (no sustained
+   load to hold it), so gating restitution on the final `j_n` silently killed
+   every bounce. Tracking `maxNormalImpulse` over the whole step (Box2D-v3's
+   trick) is what makes restitution fire.
+
+3. **Analytic separation re-derivation is great for convex, wrong for
+   dynamic concave.** Re-deriving each substep's penetration from frozen
+   witness anchors + current pose (no narrowphase re-run) is cheap and exact
+   *while the contact feature is stable* — true for a convex primitive under
+   the small per-step motion. For a concave body rocking on a mesh, the
+   supporting triangle (and its normal) genuinely changes mid-step, so
+   freezing it pumps energy in. Resolution: convex pairs use the cheap
+   analytic refresh; concave-involved pairs re-run narrowphase geometry each
+   substep (`redetect_concave_contacts`). Hybrid, gated by collider convexity.
+
+4. **The aligned-stack instability was not the solver.** Cube stacks crept
+   and toppled; the instinct was "solver convergence". Dumping
+   `box_box_manifold` across a settling pair showed the normal and contact
+   *count* were stable, but the *reference face* flip-flopped between A and B
+   each frame (their SAT overlaps are exactly equal for aligned boxes, so
+   float noise from a sub-degree wobble decided the winner). That reordered
+   the contacts → flipped the Gauss-Seidel sweep order → alternating bias →
+   creep. A 6-line relative+absolute tie-break deadband (bias ties toward the
+   earlier-tested axis) fixed stacks 4–10. **Lesson: diagnose the manifold
+   before blaming the solver.**
+
+5. **Granularity is everything for dynamic concave.** The first instinct
+   ("decompose the mesh into the exact Delaunay tets we already have") is
+   wrong: a Suzanne is ~8000 tets → ~8000 colliders → ~8000 dynamic-BVH
+   leaves refit every frame. Tet meshing is a *volumetric* (FEM/soft-body)
+   tool. Rigid collision wants the *fewest* convex pieces — a single convex
+   hull for most dynamic objects, or a few-hull (V-HACD-style) decomposition.
+   Recorded as the long-term path; the per-substep re-detection is the
+   interim.
+
+6. **One configurable 6-DOF constraint beats N joint types.** The row math is
+   contact-shaped (Jacobian + effective mass + bias + bounds), so it slots
+   into the existing solver. Concrete joints become *config*: ball-socket =
+   lock 3 linear; hinge = lock 3 linear + 2 angular; weld = lock 6. This
+   minimises distinct code paths — the whole point.
+
+7. **Sign conventions: linear A−B, angular B−A.** The linear rows use
+   "A minus B" (impulse +to A); the angular rows use "B minus A" (impulse
+   +to B). Each is internally consistent — the body-order difference just
+   folds the sign in. Derived carefully against the SPOOK Baumgarte target
+   (`dC/dt = vrel`); both worked first try once written down.
+
+---
+
+## Deviations from the original plan (and why)
+
+- **Joints run as a parallel row set, not by porting contacts onto a shared
+  constraint base.** The plan floated either. Porting the working,
+  well-tuned contact path carried regression risk for no immediate benefit;
+  running joints as a second row family in the same substep loop gets the
+  coupling (shared warm-start / islands / substep cadence) at far lower risk.
+  Unifying remains optional.
+
+- **Convex contacts use analytic refresh, not per-substep match-and-merge.**
+  The plan said "substeps refresh contacts via match-and-merge". Analytic
+  re-derivation is cheaper and avoids manifold-lifecycle churn for the convex
+  majority; match-and-merge-style re-detection is reserved for the concave
+  minority (lesson 3).
+
+- **Dynamic concave: per-substep re-detection now, convex proxies later** —
+  not the tet-compound idea first sketched (lesson 5).
+
+---
+
+## Deferred (with rationale)
+
+- **Constraints**: prismatic (needs frame-basis linear rows — today's linear
+  locks use world axes, exact only when all 3 are locked), limits, motors,
+  springs (SPOOK soft), swing-twist (ragdoll cone), the raycast-vehicle
+  layer, and extras (pulley/gear/conveyor/breakable). Sequenced in `PLAN.md`.
+- **Trajectory accuracy**: gravity is substepped, so ballistic integration is
+  at the substep rate — good. No higher-order integrator pursued.
+- **Per-island parallel solve / CCD shape-cast / closed-form
+  triangle-vs-primitive remainder**: unchanged backlog items.
+- **Convex hull builder + few-hull decomposition**: the production answer for
+  dynamic concave (lesson 5), not yet built.
+
+---
+
+## Bottom line
+
+The engine moved from "competent PGS" to a substepped TGS solver with stable
+stacks, accurate restitution, robust mass ratios, settling dynamic concave
+bodies, and a working 6-DOF constraint (ball-socket / hinge / weld) — i.e.
+chains, ropes, and the structural joints for ragdolls and mechanisms. The
+costliest mistakes were all about *substepping invariants* (warm-start and
+restitution-gating cadence) and *not trusting assumptions* (the stack bug was
+narrowphase, not the solver). The remaining constraint work is incremental
+on a validated framework.

package/src/engine/physics/REVIEW_003.md

@@ -1,166 +1,166 @@
-# REVIEW_003 — 6-DOF joints, full DOF-mode set, and the raycast vehicle
-
-Retrospective on the constraints push: completing the 6-DOF joint across every
-per-DOF mode (lock / free / limit / motor / spring), adding accurate cone-twist
-range-of-motion, and building the raycast-vehicle layer on top. Companion to
-`REVIEW_002` (TGS solver + contact robustness + the first joint modes); this one
-covers `PLAN.md` → "Constraints / joints" phases 3–7.
-
-Scope: what landed, the hard-won lessons, where the build deviated from the plan
-and why, and what's deferred.
-
----
-
-## What landed
-
-**One mode-agnostic constraint row.** The joint solver resolves every DOF —
-linear or angular — through a single scalar velocity row parameterised by
-`(effective mass, bias, impulse clamp, regularisation γ)`. The `DofMode` only
-chooses those parameters:
-
-- **LOCKED** — bilateral, `bias = β/h · C`, clamp `(−∞, +∞)`. Ball-socket /
-  hinge / weld / prismatic are configurations of locked vs free DOFs.
-- **LIMITED** — a *speculative (β=1) one-sided* velocity constraint: `bias =
-  (pos − bound)/h`, clamp one-sided. Slider end-stops and joint ROM.
-- **MOTOR** — `bias = −targetVelocity`, clamp `±maxForce·h`. Powered doors,
-  wheel drive, pistons.
-- **SPRING** — a regularised (compliant) row: `γ = 1/(h·(c+h·k))`, `bias =
-  (k/denom)·C`, softened mass `1/(K+γ)`, plus the `+γ·λ_accum` term. Suspension,
-  bungees, soft-return.
-
-Adding each mode was a localised change to the row-parameter setup; the
-warm-start and the iteration loop never changed shape. SPRING added exactly one
-term (`+γ·λ_accum`, γ defaulting to 0), so LOCKED/LIMITED/MOTOR stayed
-bit-for-bit identical.
-
-**Frame-basis everything.** Both linear and angular rows resolve in frame A's
-basis axes, clearing the early world-axis linear debt — the solver is fully
-frame-relative.
-
-**Cone-twist (swing-twist).** Opt-in `Joint.swingTwist` switches the angular
-position measure from the per-axis small-angle vector to a swing-twist
-decomposition (X = twist, Y/Z = swing) with *exact* angles, reusing the LIMITED
-/ SPRING rows. Wide ragdoll ROM now holds at the true angle.
-
-**Raycast vehicle.** `vehicle/RaycastVehicle.js` — a chassis body + raycast
-wheels, a controller on the public `raycast` + `applyForceAt`/`applyImpulseAt`
-API. Suspension (spring+damper along the contact normal) + tyre friction
-(lateral grip + drive/brake clamped to a friction circle μ·N) + steering. The
-6-DOF spring+motor is the alternative "simulated wheel" path.
-
-Coverage ~720 → **732 physics tests**, all green. Joint tests 9 → 19; vehicle
-tests +6; one swing-twist micro-bench (`test.skip`).
-
----
-
-## Hard-won lessons
-
-1. **A limit must not bounce — velocity-Baumgarte injects energy.** The first
-   LIMITED cut waited for the DOF to cross a stop, then pushed back with a
-   Baumgarte bias. On a spin-into-stop with no opposing load the restorative
-   *velocity* it added didn't dissipate — the DOF coasted back through the whole
-   range. This is the same energy injection the contact solver avoids by using
-   split-impulse instead of velocity-Baumgarte. The fix: a **speculative (β=1)
-   one-sided velocity constraint** that removes exactly the approach velocity so
-   the DOF *lands on* the stop (zero penetration → zero rebound), self-gates to
-   a no-op away from the bound, and — because only the push-out side of the bias
-   is clamped — eases a teleport out instead of yanking. A loaded stop (gravity
-   on a slider) rests cleanly: per-substep load and per-substep warm-start
-   cancel, the resting-contact invariant again.
-
-2. **One row, many modes — but only because the *fixed point* is shared.**
-   Folding LOCKED and LIMITED (and later MOTOR/SPRING) into one solve worked
-   because they differ only in `(bias, clamp, γ)`. The proof it was safe was
-   mechanical: LOCKED's prior tests stayed green untouched after each
-   generalisation. Resisting the urge to special-case kept the loop tiny and
-   made every later mode a few lines.
-
-3. **Spring = regularisation, and it reproduces the analytic equilibrium.** The
-   SPOOK soft constraint (`γ` compliance + `(k/denom)·C` bias + softened mass)
-   isn't an approximation to dial in — a vertical strut settles at *exactly*
-   `m·g/k`, an undamped one oscillates and conserves energy, a stiff one stays
-   stable at 4 substeps. Getting the discrete coefficients right (Catto's
-   implicit-Euler form) made it behave like a real spring on the first run.
-
-4. **Swing-twist: exact position, first-order Jacobian.** The win is measuring
-   the limit *position* as a true angle (a 1.2 rad swing stops at 1.2, not the
-   small-angle proxy's ~1.287). The velocity Jacobian stays the cheap `ω·axis`
-   first-order one — PhysX/Jolt do the same. Keeping it opt-in means welds and
-   tight hinges don't pay the `atan2`/`sqrt` cost.
-
-5. **Benchmark before inlining — but inline when it's 5×.** Rather than assume,
-   the swing-twist decomposition was measured inlined (allocation-free scalar
-   math) vs the object-based `Quaternion.computeSwingAndTwist`: ~5× faster than
-   the method with reused out-params, ~10× vs naive fresh allocation (property
-   getters + `normalize` + a quaternion multiply + GC). In a per-substep
-   per-joint hot loop that margin justifies the duplicated math; the Quaternion
-   method stays for general callers. Making all three variants produce identical
-   results (matching sinks) was what made the comparison trustworthy.
-
-6. **The raycast vehicle is a force controller, and its failure modes are
-   physical.** Too much drive on a light, high-CG car wheelies and flips; too
-   much speed into a hard steer rolls it. These aren't solver bugs — they're the
-   model being honest. The tests use a low, heavy car and moderate inputs so the
-   *controller* (suspension equilibrium, grip, drive, steer) is what's under
-   test, not the operator. Spotting "the car launched, went airborne, then slept
-   on its roof" from `contacts=0, y=0.29, sleep=1` saved chasing a non-bug.
-
-7. **An external per-frame controller can't fully honour the substep
-   invariant.** Suspension is applied once per frame as a `dt`-force, but gravity
-   is per-substep — so a resting chassis carries a ~`g·h` end-of-step
-   velocity-sample artifact (it hovers position-stable to sub-cm, but the
-   sampled `v_y` isn't zero the way a resting *contact* body's is). Contacts
-   avoid this because their warm-start cancels each substep's gravity inside the
-   loop; a frame-level controller has no such hook. Documented, not hidden.
-
----
-
-## Deviations from the plan (and why)
-
-- **LIMITED is speculative-velocity, not split-impulse.** The plan sketched
-  limits as bounded rows; the bounce lesson pushed it to a β=1 speculative
-  velocity constraint, which needs no separate position pass and rests cleanly.
-- **Swing-twist is inlined, not `Quaternion.computeSwingAndTwist`.** The note
-  said "reuse the Quaternion method"; the benchmark said inline (lesson 5). The
-  method stays for non-hot callers.
-- **Swing-twist is opt-in (`swingTwist` flag), not the default measure.** Keeps
-  the cheaper small-angle path for welds/hinges and zero regression risk; the
-  flag is a genuine angular-mode choice (PhysX D6 / Jolt SwingTwist), not an
-  auto/override sentinel.
-- **Vehicle is a standalone controller, not an ECS component+system.** It rides
-  the public query+force API exactly as the plan framed it ("on top of the
-  queries"), which keeps it decoupled and matches Bullet/Godot usage.
-
----
-
-## Deferred (with rationale)
-
-- **Raycast narrowphase refinement** — the suspension ray (and every shape
-  query) currently resolves to the leaf's inflated AABB: exact for axis-aligned
-  box ground, coarse for spheres/capsules/rotated boxes/meshes. This is the next
-  item; it sharpens vehicle ride height and all query accuracy. Tracked
-  separately.
-- **Vehicle extras** — anti-roll bars, engine/gearbox curves, configurable
-  weight transfer / anti-squat, wheel-collision (vs raycast-only). The core is
-  in; these are tuning layers.
-- **Elliptical/conical swing limit** — the cone is currently box-shaped
-  (independent Y/Z swing limits). A single combined swing-magnitude row would
-  give a circular/elliptical cone.
-- **Per-substep joint warm-start for the vehicle** — would remove the `g·h`
-  velocity-sample artifact, at the cost of running the controller inside the
-  substep loop.
-- Carried from REVIEW_002: convex-hull / few-hull decomposition for production
-  dynamic concave; per-island parallel solve; shape-cast CCD.
-
----
-
-## Bottom line
-
-The 6-DOF joint now spans the whole taxonomy from one row solve — ball-socket,
-hinge, weld, prismatic, slider/ROM end-stops, powered doors/wheels, springs/
-suspension, and accurate ragdoll cone-twist — and the raycast vehicle sits on
-top of it and the query API. The costliest lessons were again about *not
-injecting energy* (the limit bounce, mirroring the contact split-impulse
-rationale) and *measuring before optimising* (the swing-twist inline bench). The
-constraints plan (phases 1–7) is complete; the highest-leverage next step is
-raycast narrowphase, which every query — and the vehicle — would sharpen.
+# REVIEW_003 — 6-DOF joints, full DOF-mode set, and the raycast vehicle
+
+Retrospective on the constraints push: completing the 6-DOF joint across every
+per-DOF mode (lock / free / limit / motor / spring), adding accurate cone-twist
+range-of-motion, and building the raycast-vehicle layer on top. Companion to
+`REVIEW_002` (TGS solver + contact robustness + the first joint modes); this one
+covers `PLAN.md` → "Constraints / joints" phases 3–7.
+
+Scope: what landed, the hard-won lessons, where the build deviated from the plan
+and why, and what's deferred.
+
+---
+
+## What landed
+
+**One mode-agnostic constraint row.** The joint solver resolves every DOF —
+linear or angular — through a single scalar velocity row parameterised by
+`(effective mass, bias, impulse clamp, regularisation γ)`. The `DofMode` only
+chooses those parameters:
+
+- **LOCKED** — bilateral, `bias = β/h · C`, clamp `(−∞, +∞)`. Ball-socket /
+  hinge / weld / prismatic are configurations of locked vs free DOFs.
+- **LIMITED** — a *speculative (β=1) one-sided* velocity constraint: `bias =
+  (pos − bound)/h`, clamp one-sided. Slider end-stops and joint ROM.
+- **MOTOR** — `bias = −targetVelocity`, clamp `±maxForce·h`. Powered doors,
+  wheel drive, pistons.
+- **SPRING** — a regularised (compliant) row: `γ = 1/(h·(c+h·k))`, `bias =
+  (k/denom)·C`, softened mass `1/(K+γ)`, plus the `+γ·λ_accum` term. Suspension,
+  bungees, soft-return.
+
+Adding each mode was a localised change to the row-parameter setup; the
+warm-start and the iteration loop never changed shape. SPRING added exactly one
+term (`+γ·λ_accum`, γ defaulting to 0), so LOCKED/LIMITED/MOTOR stayed
+bit-for-bit identical.
+
+**Frame-basis everything.** Both linear and angular rows resolve in frame A's
+basis axes, clearing the early world-axis linear debt — the solver is fully
+frame-relative.
+
+**Cone-twist (swing-twist).** Opt-in `Joint.swingTwist` switches the angular
+position measure from the per-axis small-angle vector to a swing-twist
+decomposition (X = twist, Y/Z = swing) with *exact* angles, reusing the LIMITED
+/ SPRING rows. Wide ragdoll ROM now holds at the true angle.
+
+**Raycast vehicle.** `vehicle/RaycastVehicle.js` — a chassis body + raycast
+wheels, a controller on the public `raycast` + `applyForceAt`/`applyImpulseAt`
+API. Suspension (spring+damper along the contact normal) + tyre friction
+(lateral grip + drive/brake clamped to a friction circle μ·N) + steering. The
+6-DOF spring+motor is the alternative "simulated wheel" path.
+
+Coverage ~720 → **732 physics tests**, all green. Joint tests 9 → 19; vehicle
+tests +6; one swing-twist micro-bench (`test.skip`).
+
+---
+
+## Hard-won lessons
+
+1. **A limit must not bounce — velocity-Baumgarte injects energy.** The first
+   LIMITED cut waited for the DOF to cross a stop, then pushed back with a
+   Baumgarte bias. On a spin-into-stop with no opposing load the restorative
+   *velocity* it added didn't dissipate — the DOF coasted back through the whole
+   range. This is the same energy injection the contact solver avoids by using
+   split-impulse instead of velocity-Baumgarte. The fix: a **speculative (β=1)
+   one-sided velocity constraint** that removes exactly the approach velocity so
+   the DOF *lands on* the stop (zero penetration → zero rebound), self-gates to
+   a no-op away from the bound, and — because only the push-out side of the bias
+   is clamped — eases a teleport out instead of yanking. A loaded stop (gravity
+   on a slider) rests cleanly: per-substep load and per-substep warm-start
+   cancel, the resting-contact invariant again.
+
+2. **One row, many modes — but only because the *fixed point* is shared.**
+   Folding LOCKED and LIMITED (and later MOTOR/SPRING) into one solve worked
+   because they differ only in `(bias, clamp, γ)`. The proof it was safe was
+   mechanical: LOCKED's prior tests stayed green untouched after each
+   generalisation. Resisting the urge to special-case kept the loop tiny and
+   made every later mode a few lines.
+
+3. **Spring = regularisation, and it reproduces the analytic equilibrium.** The
+   SPOOK soft constraint (`γ` compliance + `(k/denom)·C` bias + softened mass)
+   isn't an approximation to dial in — a vertical strut settles at *exactly*
+   `m·g/k`, an undamped one oscillates and conserves energy, a stiff one stays
+   stable at 4 substeps. Getting the discrete coefficients right (Catto's
+   implicit-Euler form) made it behave like a real spring on the first run.
+
+4. **Swing-twist: exact position, first-order Jacobian.** The win is measuring
+   the limit *position* as a true angle (a 1.2 rad swing stops at 1.2, not the
+   small-angle proxy's ~1.287). The velocity Jacobian stays the cheap `ω·axis`
+   first-order one — PhysX/Jolt do the same. Keeping it opt-in means welds and
+   tight hinges don't pay the `atan2`/`sqrt` cost.
+
+5. **Benchmark before inlining — but inline when it's 5×.** Rather than assume,
+   the swing-twist decomposition was measured inlined (allocation-free scalar
+   math) vs the object-based `Quaternion.computeSwingAndTwist`: ~5× faster than
+   the method with reused out-params, ~10× vs naive fresh allocation (property
+   getters + `normalize` + a quaternion multiply + GC). In a per-substep
+   per-joint hot loop that margin justifies the duplicated math; the Quaternion
+   method stays for general callers. Making all three variants produce identical
+   results (matching sinks) was what made the comparison trustworthy.
+
+6. **The raycast vehicle is a force controller, and its failure modes are
+   physical.** Too much drive on a light, high-CG car wheelies and flips; too
+   much speed into a hard steer rolls it. These aren't solver bugs — they're the
+   model being honest. The tests use a low, heavy car and moderate inputs so the
+   *controller* (suspension equilibrium, grip, drive, steer) is what's under
+   test, not the operator. Spotting "the car launched, went airborne, then slept
+   on its roof" from `contacts=0, y=0.29, sleep=1` saved chasing a non-bug.
+
+7. **An external per-frame controller can't fully honour the substep
+   invariant.** Suspension is applied once per frame as a `dt`-force, but gravity
+   is per-substep — so a resting chassis carries a ~`g·h` end-of-step
+   velocity-sample artifact (it hovers position-stable to sub-cm, but the
+   sampled `v_y` isn't zero the way a resting *contact* body's is). Contacts
+   avoid this because their warm-start cancels each substep's gravity inside the
+   loop; a frame-level controller has no such hook. Documented, not hidden.
+
+---
+
+## Deviations from the plan (and why)
+
+- **LIMITED is speculative-velocity, not split-impulse.** The plan sketched
+  limits as bounded rows; the bounce lesson pushed it to a β=1 speculative
+  velocity constraint, which needs no separate position pass and rests cleanly.
+- **Swing-twist is inlined, not `Quaternion.computeSwingAndTwist`.** The note
+  said "reuse the Quaternion method"; the benchmark said inline (lesson 5). The
+  method stays for non-hot callers.
+- **Swing-twist is opt-in (`swingTwist` flag), not the default measure.** Keeps
+  the cheaper small-angle path for welds/hinges and zero regression risk; the
+  flag is a genuine angular-mode choice (PhysX D6 / Jolt SwingTwist), not an
+  auto/override sentinel.
+- **Vehicle is a standalone controller, not an ECS component+system.** It rides
+  the public query+force API exactly as the plan framed it ("on top of the
+  queries"), which keeps it decoupled and matches Bullet/Godot usage.
+
+---
+
+## Deferred (with rationale)
+
+- **Raycast narrowphase refinement** — the suspension ray (and every shape
+  query) currently resolves to the leaf's inflated AABB: exact for axis-aligned
+  box ground, coarse for spheres/capsules/rotated boxes/meshes. This is the next
+  item; it sharpens vehicle ride height and all query accuracy. Tracked
+  separately.
+- **Vehicle extras** — anti-roll bars, engine/gearbox curves, configurable
+  weight transfer / anti-squat, wheel-collision (vs raycast-only). The core is
+  in; these are tuning layers.
+- **Elliptical/conical swing limit** — the cone is currently box-shaped
+  (independent Y/Z swing limits). A single combined swing-magnitude row would
+  give a circular/elliptical cone.
+- **Per-substep joint warm-start for the vehicle** — would remove the `g·h`
+  velocity-sample artifact, at the cost of running the controller inside the
+  substep loop.
+- Carried from REVIEW_002: convex-hull / few-hull decomposition for production
+  dynamic concave; per-island parallel solve; shape-cast CCD.
+
+---
+
+## Bottom line
+
+The 6-DOF joint now spans the whole taxonomy from one row solve — ball-socket,
+hinge, weld, prismatic, slider/ROM end-stops, powered doors/wheels, springs/
+suspension, and accurate ragdoll cone-twist — and the raycast vehicle sits on
+top of it and the query API. The costliest lessons were again about *not
+injecting energy* (the limit bounce, mirroring the contact split-impulse
+rationale) and *measuring before optimising* (the swing-twist inline bench). The
+constraints plan (phases 1–7) is complete; the highest-leverage next step is
+raycast narrowphase, which every query — and the vehicle — would sharpen.