@woosh/meep-engine 3.25.0 → 3.26.0

package/src/core/geom/3d/shape/UnionShape3D.js

@@ -7,6 +7,7 @@ import { min2 } from "../../../math/min2.js";
 import { seededRandom } from "../../../math/random/seededRandom.js";
 import { number_compare_ascending } from "../../../primitives/numbers/number_compare_ascending.js";
 import { v3_dot } from "../../vec3/v3_dot.js";
+import { Ray3 } from "../ray/Ray3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
 
@@ -326,6 +327,69 @@ export class UnionShape3D extends AbstractShape3D {
 
     }
 
+    /**
+     * Nearest hit across the children, which all share the union's own frame — so, unlike the other
+     * two wrappers, there is no ray to re-frame and no answer to map back.
+     *
+     * Each child is handed the best distance so far as its `tMax`, so a child can only report a hit by
+     * beating every child before it. That is what makes it safe to let the children write straight into
+     * `hit`: a child that writes is a child that won, and a child that misses leaves `hit` untouched by
+     * the family convention, so the standing answer survives it.
+     *
+     * The distance to narrow on is recovered from the point the child wrote, as
+     * `(p − origin)·direction` — the shape-level API hands back a point where the narrowphase's
+     * `refine_ray_union` has the distance already. Two children closer together than a float32 ulp
+     * of the coordinates involved are therefore a tie, settled by whichever is listed last.
+     *
+     * That ulp is the API's, not this method's: a child writes `origin + direction · t` into a float32
+     * `hit` before anything here reads it, so the resolution is already spent by the time a LONE shape
+     * answers. Measured against the narrowphase over 4,000 rays per scale, this union's error tracks a
+     * lone sphere's within a factor of two everywhere — 3e-6 near the origin, 1e-3 at 1e4 out, 0.1 at
+     * 1e6, where one float32 ulp IS 0.06 world units. A compound collider that far out wants a float64
+     * ray, which is what the narrowphase path already gives it; it does not want a different union.
+     *
+     * DIVERGENCE from `refine_ray_union`: that one carries a sentinel for a shape it cannot answer and
+     * poisons the entire union with it, because reporting the nearest of the children it COULD answer
+     * would be a hit confidently too far. There is no sentinel in this API — a child that does not
+     * implement `raycast` throws from {@link AbstractShape3D#raycast} — but the effect is the one that
+     * matters: every child is visited unconditionally, so such a child is never quietly skipped, and
+     * the throw leaves the union with no answer rather than a partial one.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray union-frame ray (origin in [0..2], unit direction in [3..5], tMax in [6])
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit, ray) {
+        const children = this.children;
+        const child_count = children.length;
+
+        const ox = ray[0], oy = ray[1], oz = ray[2];
+        const dx = ray[3], dy = ray[4], dz = ray[5];
+
+        // Allocated per call rather than kept as a module scratch: a union may hold another wrapper,
+        // and every level of that recursion needs its own narrowing ray alive across the loop below.
+        const child_ray = new Ray3();
+
+        child_ray[0] = ox; child_ray[1] = oy; child_ray[2] = oz;
+        child_ray[3] = dx; child_ray[4] = dy; child_ray[5] = dz;
+        child_ray[6] = ray[6];
+
+        let found = false;
+
+        for (let i = 0; i < child_count; i++) {
+            if (!children[i].raycast(hit, child_ray)) {
+                continue;
+            }
+
+            // The direction is unit, so the hit's projection onto it IS the distance travelled.
+            child_ray[6] = (hit[0] - ox) * dx + (hit[1] - oy) * dy + (hit[2] - oz) * dz;
+
+            found = true;
+        }
+
+        return found;
+    }
+
     /**
      *
      * @param {UnionShape3D} other

package/src/engine/physics/cloth/MEASUREMENTS.md

@@ -3096,6 +3096,14 @@ construction rather than by arrangement. It sits **above** the sleep tests
 deliberately: a world whose every cloth is asleep still has weather, and §10's
 "sleep wakes on a wind change" is the whole reason it needs to.
 
+> **Corrected by §57.** Everything above is right about a scene with *one* cloth
+> in it, which is the scene this was measured in. A second cloth registering
+> while the first is running spends its registration ticks in a world whose clock
+> is moving, so the world clock — however it counts — hands it a different gust
+> under the two systems. The gust now reads the asking cloth's own age and
+> `ClothWorld#time` keeps only the job below: telling a source that reads the
+> scene when to walk it.
+
 ### The number
 
 ```
@@ -3287,3 +3295,577 @@ stands and M6 adds one clause to it: re-measure the absolute column on a quiet
 machine, take a paired reading even then, and if the answer is that the library
 is genuinely at its ceiling, the lever to spend is the one §17 prices rather than
 the feature that happened to be measured last.
+
+---
+
+# Cloth — post-M6 measurements
+
+> Written 2026-09-13, against the fixes listed in §17's post-M6 entry.
+> Everything above this line is M0's through M6's and is unchanged, except where
+> a section below is named *inside* the one it corrects.
+>
+> The scripts are the ones the milestones already carry; where a number here
+> came from something else, the section says what.
+
+---
+
+## 53. A cloth resting on a collider never slept, and the speed was not the thing to read
+
+§7 P5's gate is free-hanging chains, and every library fabric passes it. Put the
+same chain on a floor and four of the seven never sleep at all.
+
+```
+  8-link rope, 10 cm links, 2 % of lateral lean, dropped for 2,400 steps
+  "-1" is "still awake when the run ended"
+
+  entry      free    floor mu=0    floor mu=0.5    sphere mu=0
+  SILK        386        1029             398             631
+  COTTON      236          -1              -1             362
+  DENIM       101         198             164             220
+  LEATHER     139         192              -1            2312
+  ROPE        283         911              -1             427
+  CHAIN       144         419             245             293
+  HAIR        143         271            2129             280
+```
+
+A cloth that sleeps in 283 steps hanging free and never sleeps lying on the
+ground is not a cloth that is behaving differently; it is a **test** that is
+reading the wrong quantity.
+
+### What is actually happening
+
+Traced on cotton on a frictionless floor, six hundred steps after it has come to
+rest, the configuration is a clean **period-4 limit cycle**:
+
+```
+  step   peak speed   peak travel   contact penalty, four live slots
+     0    6.806e-3      5.801e-5     628.4  1544.9  1553.7  561.1
+     1    9.568e-3      5.328e-5     628.9  1545.1  1554.0  561.6
+     2    1.443e-2      6.116e-5     629.3  1545.7  1554.3  562.1
+     3    1.229e-2      1.061e-4     629.8  1546.3  1554.8  562.6
+     4    6.806e-3      5.801e-5     630.2  1546.6  1555.3  563.2   <- repeats
+```
+
+The cloth travels **a tenth of a millimetre a step**, which nobody can see, at a
+peak particle speed of **1.5e-2 m/s**, which is **eighteen times** the sleep
+threshold of 8.0e-4 m/s. Both numbers are correct and they disagree about
+whether the cloth is at rest, because a limit cycle has bounded displacement and
+un-bounded-below speed.
+
+The penalty column says where the cycle gets its energy: it climbs
+monotonically — `k + β·|C|` in `cloth_contact_dual_update` — and **never comes
+back down**, because `γ = 1` and `clamp_band`'s floor is the contact's own
+`0.25·(m/h²)`. Two of the four slots are already at the ceiling of `8·(m/h²)`,
+which is exactly the ratio §6 measured a row adding energy above.
+
+### Two candidates, and only the second survives
+
+The *friction re-anchor* — `cloth_contact_row.js` moving the anchor to the
+particle whenever the row's force clamps out — is **not** it, and no experiment
+is needed to say so: cotton fails on a floor whose friction is **zero**, where
+`friction <= 0` zeroes the friction multiplier before the anchor is ever read.
+It is ruled out by the μ = 0 column of the table above.
+
+The *penalty ramp* is it, and the fix for it is not in scope: `γ` is
+unmeasured-by-decision (§5.2), a `γ < 1` would have to be re-measured against
+every hard row in the system, and the motion it sustains is a tenth of a
+millimetre. **The defect worth fixing is that the sleep test disagrees with the
+plan.** §7 P5 has said "maximum particle displacement over a window" since M0 and
+M1 implemented an instantaneous speed.
+
+### The rule, and the threshold
+
+Displacement from an anchor taken when the window opened, re-anchored the moment
+any particle leaves the threshold; `CLOTH_SLEEP_STEPS` consecutive steps inside
+it is sleep. Swept over the ratio, every entry × every scene, "steps to sleep":
+
+```
+  ratio of reach     worst    where                      any awake at 2,400?
+  1e-3 (as speed)      -1     COTTON on a floor                  4 of 28
+  1e-3                872     SILK on a frictionless floor            no
+  5e-4                961     SILK on a frictionless floor            no
+  2e-4                965     SILK on a frictionless floor            no
+  1e-4               1773     COTTON on a frictionless floor          no
+```
+
+**5e-4 is the value**, and it is chosen to be *no looser* than the speed test it
+replaces rather than to be the fastest: over a 30-step window at the engine's
+60 Hz fixed step, half a thousandth of a reach per window is the same millimetre
+a second per step that `CLOTH_SLEEP_SPEED_RATIO` named. 1e-3 would sleep sooner
+and would be a real relaxation of the gate; 1e-4 costs nearly twice the worst
+case and buys nothing visible.
+
+With it in place, the table at the top of this section reads:
+
+```
+  entry      free    floor mu=0    floor mu=0.5    sphere mu=0
+  SILK        325         961             309             573
+  COTTON      180         361             277             325
+  DENIM        92         195             128             194
+  LEATHER     127         175             109             151
+  ROPE        235         840             941             393
+  CHAIN       143         425             201             261
+  HAIR        132         260             177             246
+```
+
+Nothing is awake, the worst case is 961 steps and the free-hanging column has
+not got worse — it is uniformly *faster*, because a chain settling through a
+swing covers less ground per window than its instantaneous speed suggested.
+
+### What it costs
+
+One compare-only pass over the particle positions per cloth per step, on the
+main thread, in `ClothWorld#finish`, with no square root — the displacements are
+compared squared — and one `Float32Array` of `3·particle_count` per instance. It
+does not enter the step, so `cloth_library_bench.mjs` cannot see it and does not:
+the library column is unchanged across this commit.
+
+*Reproduce:* `cloth_pathology.spec.js`, the two P5 sleep tests. The table above
+is the same scenario driven from a script rather than through vitest.
+
+---
+
+## 54. A collider that does not move is not a collider a cloth cannot hit
+
+§20 measured the discovery reach missing a **moving collider** and fixed it by
+folding the collider's travel into the reach. The mirror case was argued away in
+the same docblock rather than measured: a fixed margin of `2·(thickness +
+inflation)` "covers half a metre a second of approach", and anything faster is
+"one the velocity clamp of §7 P1 is already the bound on".
+
+**It is not.** That clamp is `4 · shortest_row · substeps · iterations / dt`,
+which for a garment's rows at 2 × 4 is about **154 m/s** — three orders of
+magnitude above the half metre a second the margin actually covers. Everything
+between is uncovered, and a character walks through it.
+
+### The reproduction
+
+One particle at 8 mm thickness, thrown along +X at a **static** 3 cm capsule,
+no gravity so that nothing but the contact can change its velocity, 2 substeps ×
+4 iterations. "Warned" is whether a row existed by the time the particle was
+first sampled inside the contact offset; "far side" is whether it ended past the
+capsule rather than bounced off it.
+
+```
+              with |v|·dt in the reach          as M2 shipped
+  speed      warned    far side    x_final     warned    far side    x_final
+    1 m/s      yes         no       -0.672        no         no       -1.464
+    2          yes         no       -1.268        no         no       -2.058
+    3          yes         no       -1.371        no        YES      +13.315
+    4          yes         no       -2.220        no        YES      +14.294
+    5          yes         no       -0.532        no        YES      +25.516
+    6          yes         no       -1.287        no        YES      +19.800
+    8          yes        YES      +26.285        —         YES      +26.467
+   10          yes        YES      +31.285        no        YES      +33.133
+```
+
+Two separate readings. **`warned` is never true without the term, at any
+speed** — the first row a particle ever gets is the one that finds it already
+inside, which is the opposite of what a speculative contact is for. And from
+**3 m/s** the particle is not stopped at all: the row the next step finally
+creates is evaluated where the particle now is, which is on the far side, and
+its normal points away from the collider, so the first thing the contact does is
+push it the rest of the way out. §7 P4(a) chose orientation over history
+deliberately and this is the price of that choice when discovery is late.
+
+### What the fix does and does not buy
+
+Swept, in half-metre steps from 1 to 12 m/s, whether the particle is stopped:
+
+```
+  substeps     stopped up to      through from
+      2            6.0 m/s          6.5 m/s
+      4           12.0 m/s          — nothing in range
+```
+
+A clean threshold, and it is `substeps` rather than discovery: a row that exists
+is still evaluated at substep positions, so a particle that crosses a whole
+collider inside one substep has a row that never sees it touching. §7 P3 has
+always said "more substeps in the affected `ClothDynamics`"; this is the first
+measurement of where that lands. Discovery being right is necessary and not
+sufficient, and the two are now separable — unswept at four substeps still
+tunnels at 8 m/s.
+
+### What it costs
+
+Interleaved A/B in one process, alternating which side runs first, `dt` against
+zero — zero being exactly the reach M2 shipped:
+
+```
+  1,024 particles, one ground plane, best of eight interleaved pairs
+
+  approach            with travel     as M2 shipped      ratio
+  at rest                45.16 ns         45.35 ns       0.996
+  falling at 3 m/s       92.32 ns         55.88 ns       1.652
+```
+
+**At rest it is free** — the square root disappears into the measurement's own
+noise. Moving, it is 36 ns a particle a step, and that is not the arithmetic: it
+is the records a wider reach lets past the AABB reject, which is the feature
+rather than its overhead. Against the 4.5 ms §23 measures for this workload it
+is **0.8 % of a step**, and `cloth_library_bench.mjs` cannot see it at all,
+because the bench drives `cloth_step` with no collider table — the library
+column is unchanged across this commit, which is the regression check rather
+than the measurement.
+
+### And it moved a sleep number, which is a coupling worth naming
+
+`cloth_contact_dual_update` ramps the penalty by `β·|C|` on the **unsigned**
+residual, so a row that is not touching ramps too. That was nearly invisible
+while rows only appeared within 16 mm; with the reach carrying a falling cloth's
+travel, rows now appear tens of centimetres out and reach `k_max` long before
+contact, and `γ = 1` never brings them down again. §53's table moves with it:
+most entries settle *sooner*, and hair on a floor with friction goes from 177
+steps to **2,202** — a creep at 1.6 times the sleep window's threshold rather
+than a cloth that has stopped.
+
+Making the ramp one-sided is the obvious repair and **the measurement says not
+to**:
+
+```
+  stopped up to, half-metre steps from 1 to 12 m/s
+
+                        2 substeps            4 substeps
+  ramp on |C|             6.0 m/s              12.0 m/s, no holes
+  ramp on max(C, 0)       6.0 m/s, hole at 5    9.5 m/s, holes at 10–11.5
+```
+
+The pre-stiffening of a speculative row is what gives a fast arrival something
+solid to hit; removing it trades a visible failure — cloth through a character —
+for an invisible one — a hair rope taking thirty-seven seconds to stop creeping
+instead of three. So the ramp is left alone and the coupling is recorded in §18.
+
+---
+
+## 55. A collider arriving and a collider retiring, and what each one was not told
+
+Two defects at the two ends of a collider's life, both of them a *set* question
+answered with a *pose*.
+
+### Arriving
+
+§7 P5's wake test compares each overlapping collider's previous pose with its
+current one. `ClothColliderSystem#link` calls `placePose`, which sets both — on
+purpose, so a new collider's first step sweeps nothing, because it did not move,
+it appeared. The two facts together say a collider that appears inside a
+sleeping cloth has not moved.
+
+```
+  6-link rope, 10 cm links, left to settle: asleep at step 236
+  a sphere of radius 0.2 spawned around its lower half, never moved
+
+  300 steps later:   asleep      links inside the sphere
+  before             yes         4 of 6
+  after              no          0 of 6
+```
+
+§1's first commitment names this case in its own words, and the gate for it was
+`cloth_collision.spec.js`'s "a collider that appeared but has not moved does not
+wake anything" — a test that was passing because the thing it asserted was the
+defect.
+
+The fix is the **handle set**: `ClothInstance` keeps the handles the last step
+gathered, and the wake test compares this step's against them before it compares
+poses. One integer per record, on a path that was already doing a broadphase
+query, against a step three orders of magnitude more expensive.
+
+Two details it turns on. The wake test's query has to use the **same reach** the
+last step's gather used, or it is comparing the answers to two different
+questions and wakes on the margin rather than on the world; `gather_reach` is
+recorded beside the set. And a `PlaneShape3D`'s AABB is unbounded, so a plane is
+in *every* cloth's set the moment it exists: adding one anywhere wakes every
+sleeping cloth once, which costs the thirty steps it takes to find nothing and
+go back to sleep. That is stated rather than worked around — a bounded collider
+five metres away does not wake anything, and the spec pins both.
+
+### Retiring
+
+`ClothColliderIndex#add` popped a retired slot immediately. A handle is a slot
+index, and `cloth_contact_find` matches warm-started contacts on the handle
+alone — so a collider removed and another added within one tick are, to every
+cloth in the scene, the same collider.
+
+```
+  a rope settled on a floor for 400 steps, then in one step:
+  remove the floor, add a different collider
+
+  the floor's handle:         0
+  the replacement's handle:   0        <- the cloth cannot tell
+  the particle's multiplier:  0.0981 before, 0.0970 after
+  the friction anchor:        carried, still in the old floor's frame
+```
+
+Both index docblocks claimed the opposite — "any cloth holding warm-started
+contacts against it drops them on its next step" — and the claim is true only if
+the handle is *absent* for a step, which nothing made it. `remove` now retires
+into a list `advance` drains one step later. The cost is one slot held back for
+one step; the alternative, a generation word beside the handle, is the same
+guarantee threaded through the per-cloth table, the key array and the warm-start
+scan.
+
+### They compose, and that is not a coincidence
+
+The deferral makes the handle absent for a step; the set comparison is what makes
+a **sleeping** cloth notice that absence, wake, and clear its slots before
+anything else can take the number. Either alone leaves a case open: without the
+deferral the slot is reused before the cloth steps, and without the set test a
+sleeping cloth never steps at all.
+
+*Reproduce:* `cloth_collision.spec.js` — the far collider, the overlapping
+collider, the leaving collider and the replaced collider — and
+`ClothColliderIndex.spec.js`'s retirement test.
+
+---
+
+## 56. The parity gate had one cloth in it, and a second cloth is a different gate
+
+§40 made the gate structural: one parameter block, one `cloth_step_instance`,
+neither system computing a number of its own. Every scene it was measured on has
+exactly one cloth in it, and two of the three things that can differ between the
+systems only exist when there are two.
+
+### A nested pair
+
+`ClothSystem` ran advance, step and finish **per cloth**, walking
+`ClothWorld#instances` in hierarchy-depth order — a sort that existed precisely
+so a nested cloth would advance against an anchor the cloth above it had already
+written this step. `WorkerClothSystem` cannot do that: the step it writes back at
+the top of a tick happened on another thread during the last one, so its `apply`
+writes T−1 and its `collect` then advances everything for T.
+
+```
+  a 4-link rope hung from link 3 of a 6-link rope, no wind, 120 steps
+
+  outer cloth:  identical, every step
+  inner cloth:  differs at step 1, byte 24
+```
+
+Byte 24 is inside the particle positions, which is the honest place for it: the
+child is simulating against a different anchor, not reporting a different number
+about the same one.
+
+**Three loops on both sides** — advance every cloth, then step every cloth, then
+finish every cloth — and the depth sort has nothing left to decide, so it is
+gone. What a nested cloth reads is its parent one fixed step stale, which is the
+same trade §4.1 already makes for an anchor and measures at a few centimetres.
+
+**That was necessary and not sufficient**, and the second half is more
+interesting than the first. `cloth_write_back` composed every node's world pose
+as `anchor ⊗ local particle position`, reading the anchor from the live
+`Transform64`. For `ClothSystem` that is the anchor the step ran on, because the
+step happened between the two. For the worker it is not: it writes step T−1's
+particles against tick T's anchor.
+
+```
+  the inner cloth's anchor, as each system's write-back left it
+
+  step    reference       worker (before)    worker (after)
+     2    0.038945        0.069849           0.038945
+     3    0.038341        0.069079           0.038341
+     4    0.037680        0.068171           0.037680
+```
+
+The worker's column before the fix is the parent's *current* anchor plus a
+one-step-old shape — a pose that describes neither step. Nothing rendered can
+tell, because the attachment cascade re-derives position from the anchor and the
+local transforms either way (§4.1); a nested cloth reading that pose as its own
+anchor can. The write-back now uses `ClothInstance#anchor_translation` and
+`#anchor_rotation`, which `advance` already caches and which the collider gather
+already reads for the same reason.
+
+### What the gate is now
+
+`WorkerClothSystem.spec.js` compares the whole buffer of **both** cloths at every
+one of 120 steps, with the parent's anchor walked through a turn so the child has
+something to be wrong about, and self-checks that the child actually moved.
+
+---
+
+## 57. A world clock is right for the first cloth in a scene and wrong for the second
+
+§50 put the wind clock on steps rather than ticks so that a cloth's first step
+got the same weather under both systems. It did, and the scene it was measured
+in had one cloth.
+
+With cloth A already running, cloth B's registration takes k ticks — and A is
+advanced on every one of them, so the world clock moves while B waits. B
+therefore reaches **its own first step** at a different clock value under the two
+systems:
+
+```
+  A primed and running, B spawned, a two-tick delivery for B's registration
+
+  B's own step 1:   reference clock 0.1000 s
+                    worker clock    0.1333 s
+
+  differing bytes in B's buffer:  step 1, byte 0, and every step after
+  the same run with gust = 0:     none
+```
+
+The `gust = 0` row is what identifies the cause. Latency is not the problem —
+§39 already made an unacknowledged cloth neither stepped nor advanced, so B's
+step *sequence* is identical — the problem is that a shared clock is not a
+property of the cloth asking.
+
+**The clock is now the asking cloth's own age**, `ClothInstance#age`, seconds
+*this instance* has stepped, handed to `AbstractClothWind#sample` per call. The
+source holds no clock: `ClothAmbientWind#__time` is gone and `begin` keeps only
+the job it can do correctly, which is telling a source that reads the scene —
+`ClothFluidWind`'s field walk — when to walk it. `ClothWorld#time` stays for
+exactly that.
+
+*What it changes behaviourally:* two garments spawned a second apart are a second
+apart in the gust rather than in phase with it. For a bounded sum of three
+sinusoids with no spatial structure (§48) that is not a weaker model, it is the
+same model sampled at a different phase — and a scene in which every banner
+gusts in lockstep was the odder of the two pictures.
+
+*What it does not change:* a fluid field's velocities are a snapshot of the tick,
+not a function of a clock, so `ClothFluidWind` passes the age through to its
+ambient fallback and ignores it otherwise.
+
+*Reproduce:* `WorkerClothSystem.spec.js`, the staggered-spawn parity test.
+
+---
+
+## 58. The library, re-measured, and what the bench can and cannot see
+
+`cloth_library_bench.mjs`, before this pass and after it, on the same machine
+within the hour:
+
+```
+  entry     budget     before      after     delta
+  SILK      2x4       1.561 ms    1.649 ms    +5.6%
+  COTTON    2x4       1.655 ms    1.546 ms    -6.6%
+  DENIM     2x2       1.261 ms    1.343 ms    +6.5%
+  LEATHER   2x2       1.346 ms    1.246 ms    -7.4%
+  ROPE      2x4       0.043 ms    0.042 ms    -2.3%
+  CHAIN     2x6       0.063 ms    0.063 ms    +0.0%
+  HAIR      2x4       1.537 ms    1.702 ms   +10.7%
+```
+
+**Both signs, no pattern, ±11%** — which is §42's and §52's lesson arriving a
+third time, and here it is not merely a disclaimer: **the bench cannot see any
+of this pass's solver work**, and reading the code is what says so rather than
+reading the column. It builds a `ClothState` and calls `cloth_step` with a null
+collider table, so `cloth_contact_find` — the one function §54 changed — never
+runs; and it never constructs a `ClothWorld`, so the sleep window, the wake test,
+the write-back's anchor and the wind clock are all outside it. The column is a
+**regression check** on the paths this pass did not touch, and it passes: no
+entry moves outside the spread three runs of the unchanged bench already produce
+(§52 put the §17 baseline row at 3.49, 3.83 and 4.26 ms within an hour).
+
+What *is* priced, and is priced by a paired measurement rather than by this
+column, is §54's discovery reach: free at rest, 1.65× on the discovery pass for a
+cloth falling at 3 m/s, which is 0.8% of a step. §53's sleep window is one
+compare-only pass over positions on the main thread, in `ClothWorld#finish`,
+which the bench also cannot see and which sits beside a write-back that already
+walks every node.
+
+**No entry is re-sized.** Three passes have now said the same thing about this
+column and the advice does not change: re-measure it on a quiet machine, take a
+paired reading even then, and check the process count first.
+
+---
+
+## 59. The broadphase was a scan, and the margin it scanned with was metres wide
+
+Two defects, found from one downstream console line: a cape overlapping **80**
+cloth colliders against a per-cloth table of 64. Both are about the gather, and
+only one of them is the one the warning names.
+
+### The margin
+
+`cloth_gather_colliders` fattened the cloth's particle bounds by the §7 P1
+velocity clamp read as a distance — `4 · shortest_row · substeps · iterations`.
+That is not a distance the cloth can travel; it is a bound on what the solver
+could undo. Over the shipped library at 60 Hz:
+
+```
+  entry       sub x it   row 2cm    row 4cm    row 8cm
+  SILK        2 x 4      0.64 m     1.28 m     2.56 m
+  COTTON      2 x 4      0.64 m     1.28 m     2.56 m
+  DENIM       2 x 2      0.32 m     0.64 m     1.28 m
+  CHAIN       2 x 6      0.96 m     1.92 m     3.84 m
+```
+
+The fattening is routinely larger than the garment. `cloth_contact_find` had
+already reached this conclusion for itself at §54 — it calls the same clamp
+"about 154 m/s … three orders of magnitude" past the speeds that matter and
+reaches with `|v_i|·dt` instead — and the gather was never brought along.
+
+Being enormous also hid what it was **missing**. The narrowphase reaches
+`(radius + inflation) · (1 + CLOTH_CONTACT_MARGIN) + collider travel +
+|v_i|·dt`; the gather's fixed term was `2 · contact_radius` and nothing else, so
+a wide enough `ClothCollider#inflation` was a contact the gather never handed
+over. `cloth_gather_reach` is now that expression, maximised over the records
+the gather cannot yet know it will get — which is what `ClothColliderIndex`'s
+`max_inflation` and `max_collider_travel` are for. It is a **bound** and not an
+estimate: the gather reads velocity before the step and `cloth_contact_find`
+reads it after `damp`, which only ever scales down.
+
+Measured on the rope of §20 — eight 10 cm links at 2 × 4, five colliders placed
+2 m away and one against the tail:
+
+```
+  gather margin, hanging       3.2006 m  ->  0.0209 m
+  colliders gathered                  6  ->  1
+```
+
+The 3.2006 m does not move when the rope is thrown at 9 m/s. The new one does,
+which is the entire point of it.
+
+### The scan
+
+`ClothColliderIndex#query` was a linear scan over every live record, run once
+per cloth per step — `clothes × colliders`. The docblock defended it on two
+grounds and both were wrong. The set size ("twenty or so, and never the whole
+world") was §41's count of colliders overlapping **one garment**, which is a
+narrowphase input being used to size a world-wide structure. The churn argument
+("a tree over twenty leaves that all move every frame costs more to keep than to
+skip") is answered by `PhysicsSystem`, which keeps two dynamic BVHs over bodies
+that all move every frame and pays for it with `compute_fat_world_aabb`'s refit
+skip. The third ground, `PlaneShape3D`'s unbounded AABB, is real and is not a
+reason for anything: the half-space is constructed in exactly one place in this
+engine — the JSON shape adapter — and no scene builds one, so the planes sit in
+a list beside the tree that is empty in every scene that has ever run.
+
+Colliders drifting 0.4 to 2 mm a step, every cloth gathering every step, paired
+runs with the order alternated:
+
+```
+  colliders  cloths   scan pose  scan gather   tree pose  tree gather   gather
+      64        8       0.012        0.001        0.010        0.004     0.4x
+     256       16       0.047        0.009        0.046        0.011     0.8x
+    1024       32       0.207        0.073        0.205        0.029     2.5x
+    4096       64       0.961        1.090        0.912        0.076    14.4x
+   16384      128       4.684        9.930        4.293        0.205    48.5x
+```
+
+`pose` is `advance` plus a `setPose` per collider, which is O(colliders) once a
+step in both and is unchanged — tree maintenance is inside the noise. `gather`
+is the `clothes × colliders` term, and it is gone. Below a few hundred
+colliders the scan is very slightly ahead, on numbers too small to matter.
+
+### Two things the tree got wrong first, both measured
+
+**A leaf inserted before its pose homes at the origin.** `add` built the leaf
+and `link` placed it immediately afterwards — but `insert_leaf` picks a sibling
+from where the box *is*, and `node_move_aabb` refits ancestors without ever
+asking whether the leaf still belongs under them. So a scene added-then-placed
+built its whole tree out of one coincident point and never rebuilt it: a root 21
+deep whose every branch overlapped every query, **128 gathers at 128 ms against
+0.2 ms** for the same leaves inserted at their real positions. The leaf is now
+created on the first `setPose`, and a leaf that escapes its slack is removed and
+re-inserted rather than refit.
+
+**A `Float32` leaf over a `Float64` world loses a bound.** The tree's nodes are
+`Float32` and the table is `Float64` precisely because a world coordinate can be
+far from the origin. One `Float32` ulp is a proportion of the magnitude — a
+millimetre at 10 km, a whole metre at 10,000 km — so a box widened by a fixed
+5 cm and then stored can come back **45 cm inside its own record**, and a leaf
+smaller than its record is a collider the tree silently stops answering with.
+The slack now carries a relative term of two ulps as well as the constant. It
+fails without it, and only for a cloth grazing a face: a query box as wide as
+the collider survives losing one side, which is why the first spec written for
+this passed and pinned nothing.