WP-PG.50: restore full-quality contact streams in the dart detector

CHANGELOG.md

@@ -193,6 +193,27 @@
 
 * Collision
 
+  * Restore full-quality contact streams in the `dart` detector: emit the
+    complete four-contact face manifold from solver-facing queries instead
+    of the previous three-contact target (a tripod manifold cannot hold a
+    resting face-face box stack), give side-lying cylinders a stable
+    two-point contact-line manifold instead of one point that wanders
+    ~90 mm under micro-motion, and keep shallow crossed-cylinder contacts
+    that the convex fallback intermittently missed
+    ([#3056](https://github.com/dartsim/dart/issues/3056)), and make the
+    aligned cylinder-box path invariant to spin about the cylinder axis so
+    upright cylinders take the stable analytic cap patch instead of
+    creeping through degenerate convex-fallback rim points. Generated
+    resting scenes settle and deactivate up to 4x faster, the dense
+    mixed-shape pile fixture now reaches full deactivation with zero
+    penetration under default settings (4 of 5 tested seeds within the
+    original 20-second window, all tested seeds by 60 seconds), and the
+    complete bundle measures slightly faster than the pre-consolidation
+    detector on the dense active-container fixture while reporting fuller
+    manifolds. FCL, Bullet, and ODE results are bit-identical;
+    the built-in default (`fcl`) is unchanged:
+    [#PENDING](https://github.com/dartsim/dart/pulls)
+
   * Provide the DART-owned collision backend through the built-in `dart`
     detector, including soft-body, ellipsoid, cone, and capsule coverage. The
     released `DARTCollide` entry points and detector ABI remain compatible, as

dart/collision/dart/DARTCollisionDetector.cpp

@@ -254,9 +254,16 @@ class CollisionThreadPool
 namespace {
 
 //==============================================================================
-// Three non-collinear contacts define a stable planar patch while avoiding a
-// fourth redundant solver row on contact-rich native scenes.
-constexpr std::size_t kSolverFacingManifoldContactTarget = 3u;
+// Solver-facing queries carry the full manifold capacity. Three contacts are
+// not enough for a resting face-face box stack: the tripod support polygon
+// stops containing the weight vector under micro-tilts toward the missing
+// corner, so stacked boxes rock indefinitely, penetration never converges,
+// and the deactivation gates (correctly) never let the island sleep
+// (issue #3056 S6 pile fixture). Callers still bound the stream through
+// CollisionOption's per-pair cap; DARTCollide keeps its explicit unlimited
+// adapter request.
+constexpr std::size_t kSolverFacingManifoldContactTarget
+    = native::ContactManifold::kMaxContacts;
 
 // Bound retained parallel scratch independently of scene pair count. Batches
 // are merged before the broadphase or Cartesian traversal continues, keeping
@@ -294,8 +301,8 @@ native::CollisionOption makeNativeOption(
     const std::size_t maxPairContacts
         = option.getEffectiveMaxNumContactsPerPair();
     // DARTCollide uses an explicit unlimited per-pair request to preserve its
-    // released full-manifold behavior. Ordinary detector queries retain the
-    // solver-facing three-contact target, including wider finite requests.
+    // released full-manifold behavior. Ordinary detector queries clamp wider
+    // finite requests to the solver-facing manifold target above.
     const bool preserveCompleteManifold
         = option.maxNumContactsPerPair
           == std::numeric_limits<std::size_t>::max();