@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -1,9 +1,10 @@
 # Cloth — measurements
 
-> Two milestones, appended in order. §1–§8 are **M0**, the solver core; §9–§15
-> are **M1**, the component and the system. Nothing above a milestone boundary
-> is edited by the milestone below it — a measurement that turned out to be
-> incomplete is corrected by a later section saying so, not by a rewrite.
+> Four milestones, appended in order. §1–§8 are **M0**, the solver core;
+> §9–§15 are **M1**, the component and the system; §16–§23 are **M2**,
+> collision; §24–§29 are **M3**, skinned garments. Nothing above a milestone
+> boundary is edited by the milestone below it — a measurement that turned out to
+> be incomplete is corrected by a later section saying so, not by a rewrite.
 
 ---
 
@@ -954,3 +955,1285 @@ leash and the tether bound the reachable set.
 It reads world `Transform64`s "the hierarchy has already composed" and writes
 local ones back, which is the arrangement above, and is why its scoring being
 ambiguous matters less than it looks.
+
+---
+
+# Cloth — M2 measurements
+
+> Written 2026-09-10, against the M2 implementation in `collider/`, the contact
+> and backstop rows in `solver/constraint/`, and `core/geom/3d/shape/sdf/`.
+> Everything above this line is M0's and M1's and is unchanged.
+>
+> Two scripts, both runnable directly under node — the M0 note applies unchanged,
+> and for the same reason:
+>
+> ```
+> node src/engine/physics/cloth/solver/__fixtures__/cloth_m2_measure.mjs
+> node src/engine/physics/cloth/solver/__fixtures__/cloth_m2_band.mjs
+> ```
+>
+> And a third playground page, `playground/collide.html`, which is the packed
+> collider table rather than the ECS: six scenes, a sweep toggle, and the two
+> contact-band sliders live.
+
+---
+
+## 16. What M2 proved wrong in PLAN.md
+
+Six things. The first is a sign error in the design that would have been silent,
+and the second is one M2 made itself and then measured its way out of.
+
+| # | The design said | The measurement said |
+|---|---|---|
+| 0 | §8.2 — swept collision interpolates "between the previous and current **matrices**" | A component-wise lerp of two rotation matrices is not a rotation. In the rotation plane it scales by `cos(θ/2)`, so the shape it poses **shrinks**: at the half-radian per step `CLOTH_ANCHOR_ROTATION_LIMIT` already calls a spin, a 25 cm collider loses 7.8 mm halfway through every step — *twice* a silk garment's thickness. A rigid pose interpolates as a translation and a quaternion. §19 |
+| 1 | §8.2 — the sweep is what stops a fast collider being missed | Only if the contact **set** is swept too. Discovery evaluates at the end-of-step pose, so a capsule that crossed the cloth *within* the step is nowhere near it by then: at 20 m/s the pass created **zero rows** and the sheet was untouched — not tunnelled through so much as never noticed. Adding the collider's travel to the discovery reach costs one subtraction a record and makes 2 to 40 m/s behave alike. §20 |
+| 2 | §6 — the collision row carries `k_contact` and friction carries `k_friction` | By M0's own rule a stiffness that is not `Infinity` is a **soft** row, and a soft row's whole force is `k·C` with `k` capped at `8·(m/h²)` — 4.6 N at one thickness of penetration, against the 11 to 376 N the hard row actually produced on a sheet arriving at 1 to 8 m/s. Both rows are hard. §18 |
+| 3 | §6 — friction clamps at `±μ·f_n` | That is the *signed-slip* formulation, which needs a tangent basis chosen per contact — and any choice continuous frame to frame is state, which is what §7 P4(a) exists to keep out. Written as the magnitude of the slip the row is `[0, μ·f_n]`, the same physics with no basis. §18 |
+| 4 | §5.4 — contact rows "never enter" `ClothState` and are applied Jacobi-style | A collider contact is **unary** — one particle against a surface fixed for the substep — so it couples no two particles and there is no Gauss-Seidel/Jacobi distinction to make. It accumulates in the vertex update like a leash row. What is true is that it comes and goes, which is a *storage* problem and not an ordering one. §18 |
+| 5 | §5.2 — Chebyshev acceleration is "available and disabled" | Built, measured against the contacts it is gated on, and removed. It does not help at any spectral radius tried, costs 2–5%, and diverges past `ρ = 0.9`. §21 |
+
+And one thing that is a property of a configuration rather than of the solver,
+recorded because it looks like a solver failure: **an exactly axis-aligned rope
+pushed by an exactly axis-aligned plane has no lateral degree of freedom to
+buckle into**, and folds into an accordion that is an exact equilibrium. §22.
+
+---
+
+## 17. The contact penalty band, and `β` at last
+
+M0 chose `k_min = k_max` — no ramp — and said so honestly: the ramp exists for
+**transient** rows, a contact that should arrive soft rather than shock the mesh
+on its first frame, and M0 had none. M1 had none either. M2 has them, and this
+is that measurement.
+
+A 400-particle sheet, 4 mm thick, dropped flat onto a ground plane at 2 substeps
+× 4 iterations. Cells are worst penetration in metres over the run / kinetic
+energy after 240 steps. **Every configuration in the grid settles to a resting
+penetration of 7.9e-8 m** — the differences below are entirely about the
+transient.
+
+```
+  arriving at 3 m/s
+
+  k_min/k_max          β=0e+0           β=1e+2           β=1e+3           β=1e+4           β=1e+5
+  × 0.00781    1.08e-2/7.65e-9  1.08e-2/2.83e-8  1.08e-2/1.54e-8  1.08e-2/6.91e-9  1.08e-2/4.06e-6
+  × 0.03125    1.08e-2/2.04e-8  1.08e-2/1.56e-8  1.08e-2/3.20e-8  1.08e-2/4.85e-8  1.08e-2/6.42e-5
+  × 0.12500    1.08e-2/2.89e-6  1.08e-2/2.92e-6  1.08e-2/3.19e-6  1.08e-2/7.42e-6  1.08e-2/4.85e-4
+  × 0.50000    2.22e-2/9.77e-3  2.26e-2/1.38e-2  2.29e-2/3.36e-2  1.99e-2/2.08e-2  2.03e-2/5.71e-3
+  × 1.00000    1.60e-2/1.11e-2  1.60e-2/1.11e-2  1.60e-2/1.11e-2  1.60e-2/1.11e-2  1.60e-2/1.11e-2
+
+  arriving at 8 m/s
+
+  k_min/k_max          β=0e+0           β=1e+2           β=1e+3           β=1e+4           β=1e+5
+  × 0.00781    1.12e-1/2.51e+0  9.51e-2/3.99e-2  8.11e-2/1.09e-1  1.16e-1/2.55e-1  1.14e-1/2.65e-2
+  × 0.03125    1.06e-1/1.95e+0  1.11e-1/2.74e-1  8.55e-2/1.16e-1  8.99e-2/5.01e-1  8.05e-2/6.16e-1
+  × 0.12500    1.22e-1/5.80e-1  1.18e-1/8.35e-2  9.92e-2/2.77e-1  1.28e-1/2.42e-1  1.25e-1/8.04e-2
+  × 0.50000    1.21e-1/2.48e-1  1.19e-1/2.02e-1  1.25e-1/2.29e-1  1.05e-1/2.65e-1  8.47e-2/2.27e-1
+  × 1.00000    9.34e-2/2.76e-1  9.34e-2/2.76e-1  9.34e-2/2.76e-1  9.34e-2/2.76e-1  9.34e-2/2.76e-1
+```
+
+The bottom row is flat across `β` because at `k_min = k_max` the penalty is
+already at the ceiling and `min(k + β|C|, k_max)` has nothing to do — which is
+exactly M0's configuration, reproduced here as the control.
+
+**The floor is what matters, and lower is better.** At `×1` a 3 m/s landing peaks
+at 18.9 N of contact force and settles at 1.1e-2 J; at `×1/8` it peaks at 0.16 N
+and settles at 2.9e-6 J, and the *penetration improves* from 1.6 cm to 1.1 cm at
+the same time. Below about `×1/8` the penetration column stops moving entirely —
+1.08e-2 to three figures from `×1/8` down to `×1/128`.
+
+That flatness is the augmented Lagrangian working as designed and is worth
+stating plainly: **the penalty only has to be large enough to generate a
+multiplier**, and the multiplier carries the load. A stiffer floor buys nothing
+except a harder first frame.
+
+**`β` earns its place at the fast arrival and nowhere else.** At 3 m/s every
+value from 0 to 1e4 is indistinguishable. At 8 m/s, `β = 0` leaves the penalty at
+the floor for the whole impact and the residual energy is 1.95 to 2.51 J against
+0.11 to 0.12 J at `β = 1e3`; and `β = 1e5` reaches the ceiling on millimetre
+violations, giving back most of what the low floor bought — 6.4e-5 J against
+3.2e-8 J on the gentle landing.
+
+**Chosen: `k_min = k_max/32`, `β = 1e3`.** The floor sits in the middle of the
+flat region with two decades of ramp above it; `β` sits in the middle of the
+range where the fast arrival is well behaved and the slow one is unaffected.
+
+### The other direction a contact arrives from
+
+The grid above is cloth arriving at a stationary collider. A garment's contacts
+are mostly the other way round — a bone driven into stationary cloth — and a
+floor low enough to make a landing gentle could plausibly be a floor a pushed
+collider gets further through. Measured, on a sphere driven 6 cm into a hanging
+cape at 1 m/s, beside the same landing:
+
+```
+  floor      cape: sphere driven in at 1 m/s          sheet: landing at 3 m/s
+             worst      resting    kinetic         worst      force N   kinetic
+  ×1.00000    3.02e-3    3.96e-4    3.59e-2       1.32e-2      1.963    2.11e-3
+  ×0.25000    2.60e-3    2.95e-4    2.44e-2       1.08e-2      0.805    1.41e-4
+  ×0.12500    2.56e-3    3.04e-4    2.56e-2       1.08e-2      0.800    2.67e-5
+  ×0.03125    2.66e-3    2.90e-4    2.25e-2       1.08e-2      0.803    9.99e-7
+  ×0.00781    2.71e-3    3.08e-4    2.36e-2       1.08e-2      0.805    5.35e-8
+
+  and the same cape with the sphere driven in faster:
+
+  floor      1 m/s      3 m/s      8 m/s   (worst penetration, m)
+  ×1.00000    3.02e-3    6.54e-3    3.55e-2
+  ×0.12500    2.56e-3    5.53e-3    3.14e-2
+  ×0.03125    2.66e-3    5.69e-3    3.25e-2
+```
+
+They do not disagree. The cape's penetration stays inside its own 4 mm thickness
+at every floor and at every speed up to 3 m/s, and the lower floors are
+marginally *better* rather than worse. The choice above holds on both.
+
+---
+
+## 18. The contact row: hard, and what a soft one could have delivered
+
+§6's table gives Collision a stiffness `k_contact` and Friction a `k_friction`,
+and M0's rule makes that literal: **a row is hard exactly when its stiffness is
+`Infinity`**, so a named stiffness is a statement that both rows are soft
+penalties.
+
+A soft row's entire force is `k·C`, and M0 measured the largest `k` a soft row
+may carry and still dissipate: `8·(m/h²)`. So the most force a soft contact can
+produce before the cloth is a full thickness inside the collider is
+`8·(m/h²)·thickness`. Against what the hard row actually had to produce:
+
+```
+  a soft row's ceiling at one thickness of penetration:     4.608 N
+
+  arriving at  0.0 m/s: the hard row produced       0.582 N   ( 0.13× the ceiling)
+  arriving at  1.0 m/s:                            11.063 N   ( 2.40×)
+  arriving at  3.0 m/s:                            18.908 N   ( 4.10×)
+  arriving at  8.0 m/s:                           375.655 N   (81.52×)
+```
+
+A cloth that is merely *resting* is inside what a soft row could do — 13% of it.
+Anything that arrives is not. A soft contact row is therefore a contact that
+holds a draped garment and fails every time the garment is put down, and the
+failure is proportional to the impact.
+
+Both rows are hard: `Infinity` stiffness, the penalty band of §17, and the
+multiplier carrying the load.
+
+### Friction against the analytic answer
+
+Coulomb says a body sticks when `μ > tan θ` and slides when it does not. A 20×20
+sheet released on an inclined plane, metres travelled downhill in four seconds:
+
+```
+  slope   tan θ     μ=0.0     μ=0.2     μ=0.4     μ=0.7     μ=1.2
+   10°   0.1763     6.9139    0.0001    0.0000    0.0000    0.0000
+   20°   0.3640    13.5772    5.6235    0.0001    0.0001    0.0000
+   30°   0.5774    19.6705   11.7592    5.0431    0.0002    0.0001
+   40°   0.8391    24.5862   16.9339   10.5951    2.8836    0.0002
+   50°   1.1918    27.4699   20.5496   14.9029    8.1086    0.0007
+```
+
+The transition sits on `tan θ` in every row: 0.2 sticks at 10° and slides at 20°,
+0.4 sticks at 20° and slides at 30°, 0.7 sticks at 30° and slides at 40°, 1.2
+sticks at 50°. The sticking cells are tenths of a millimetre over four seconds,
+which is the row holding rather than creeping.
+
+**The clamp is `[0, μ·f_n]`, not `±μ·f_n`.** §6's symmetric pair is the
+signed-slip formulation: a row whose `C` is a displacement along a chosen
+tangent. This row's `C` is the *magnitude* of the slip in the tangent plane, so
+`C ≥ 0` always and the negative half of the clamp would name a force pulling the
+particle further from where it stuck. Writing it as a magnitude is also what
+removes the tangent basis — a signed row needs two of them per contact, and any
+choice that is continuous frame to frame carries state, which is the thing §7
+P4(a) exists to keep out of this system.
+
+**The cap reads the current iteration's normal force, not the previous
+iteration's multiplier.** VBD uses the multiplier, which is one iteration stale
+and therefore exactly zero on a contact's first iteration — so at the one
+iteration per substep §5.1 says the solver must be usable at, friction would
+never act at all.
+
+### Contacts are unary, so §5.4's Jacobi treatment is not needed here
+
+§5.4 says contact rows "cannot be pre-coloured", are "accumulated into a
+per-particle scratch buffer and applied Jacobi-style", and that this is what
+makes a step deterministic regardless of how many contacts a particle picked up.
+
+Half of that is a solution to a problem a *collider* contact does not have. A
+contact against a collider touches **one** particle: the collider is fixed for
+the substep, so the row couples no two particles, so there is no Gauss-Seidel
+versus Jacobi distinction to make and nothing to keep out of the colouring. It
+accumulates in the vertex update exactly like a leash row, in colour order, and
+the step is deterministic because the contact *set* is built by one pass in a
+fixed order over a fixed table.
+
+What is true is that a contact comes and goes, so it cannot be a CSR table sized
+at build time. M2's answer is a fixed **four slots per particle** inside
+`ClothState`'s own buffer, rebuilt each step, keyed on the collider's index
+handle so a multiplier survives the rebuild. §5.4's reasoning applies unchanged
+to M4's particle-particle rows, which really are pairs.
+
+Four slots is generous. On the 20-collider budget scene, over 100 steps × 1,024
+particles: **zero particle-steps reached the slot limit**, and the mean occupancy
+was 0.10 slots per particle. The cost of the generosity is 36 words per particle
+— 147 KB at 1,024 particles against `ClothState`'s 370 KiB, a 40% increase in
+state for a structure that was never more than a quarter full. It is kept at four
+because the case it is sized for is an armpit rather than a sheet on a floor, and
+M3's garments are where that will be visible.
+
+---
+
+## 19. The interpolated pose is a rigid pose, not a lerp of matrices
+
+§8.2 says swept behaviour "comes from interpolating the collider's pose between
+the previous and current **matrices** at the substep's fraction". That is the one
+part of §8 that does not work, and the reason is arithmetic rather than taste: a
+component-wise lerp of two rotation matrices is not a rotation matrix. Halfway
+through a turn of `θ` its columns are shorter by `cos(θ/2)` in the rotation
+plane, so the shape it poses is *shrunk*.
+
+```
+  θ (rad)   |lerp(I,R)·x|   shrink on a 25 cm collider   vs a 4 mm cloth
+    0.050     0.999688           0.078 mm                    0.02×
+    0.100     0.998750           0.312 mm                    0.08×
+    0.250     0.992198           1.951 mm                    0.49×
+    0.500     0.968912           7.772 mm                    1.94×
+    1.000     0.877583          30.604 mm                    7.65×
+    1.571     0.707107          73.223 mm                   18.31×
+```
+
+`CLOTH_ANCHOR_ROTATION_LIMIT` is half a radian per step, so 0.5 is the fastest
+rotation a cloth is allowed to see, and the shrink there is already twice a
+garment's thickness. A collider that shrinks by twice the cloth's thickness
+halfway through every step is a collider cloth passes through for reasons that
+have nothing to do with speed.
+
+A translation and a quaternion interpolate rigidly by construction — the
+quaternion is renormalised, so its column reads 1.000000 at every angle — and
+that is what `ClothColliderRecord` stores. The `nlerp` is not constant angular
+velocity and over the fraction of a fixed step it does not need to be.
+
+---
+
+## 20. Sweeping the poses is not enough; the *set* has to be swept too
+
+M2 built §8.2's pose interpolation, measured it against a capsule driven through
+a hanging sheet, and found it doing nothing at all above 5 m/s. The reason was
+not the interpolation.
+
+`cloth_contact_find` runs once per step and evaluates the field at the
+**end-of-step** pose. A collider that crossed the cloth *within* the step is
+already past it by then, so the speculative margin — twice the contact offset,
+8 mm on a garment — finds nothing, no row is created, and the swept poses have
+nothing to act through.
+
+```
+  speed   pose             worst penetration      deep     rows/step
+   2 m/s  swept (§8.2)      1.85e-2 m           0        16.4
+   2 m/s  end-of-step       3.99e-2 m           4         7.2
+   5 m/s  swept (§8.2)      3.38e-2 m           1        14.5
+   5 m/s  end-of-step       0.00e+0 m           0         1.4
+  10 m/s  swept (§8.2)      3.08e-4 m           0        31.3
+  10 m/s  end-of-step       0.00e+0 m           0         1.4
+  20 m/s  swept (§8.2)      0.00e+0 m           0        94.8
+  20 m/s  end-of-step       0.00e+0 m           0         0.0
+  40 m/s  swept (§8.2)      0.00e+0 m           0       160.0
+  40 m/s  end-of-step       0.00e+0 m           0         0.0
+```
+
+Read the last column first. "end-of-step" — the previous pose set equal to the
+current one, which is what §8.2 would be without the sweep — creates **no rows at
+all** at 20 and 40 m/s. Its zero penetration is not a contact working; it is a
+capsule passing through a sheet that never knew it was there. "deep" counts
+particle-steps more than half a capsule radius inside, and the swept column holds
+it at zero or one across the whole range.
+
+The fix is one subtraction per record per step: **the discovery reach includes
+how far the collider moved.** A particle within `offset·(1 + margin) + travel` of
+the end-of-step surface gets a row, which stays clamped out until a substep's
+interpolated pose actually brings the collider onto it.
+
+That is also the honest boundary of P3. The *set* is swept by this margin and the
+*poses* by `cloth_collider_pose_at`, and both are translation-first: a collider
+spinning fast enough that a point on its surface travels more than its own radius
+within one substep is still missed, and more substeps is the answer to it.
+
+---
+
+## 21. Chebyshev acceleration: built, measured, removed
+
+§5.2 carries Chebyshev acceleration as "available and disabled by default, turned
+on per-dynamics only where it measurably helps", gated on a particle not being in
+contact this step — which is why M0 and M1 could not evaluate it and M2 is the
+first milestone that can.
+
+Implemented as the paper specifies: `ω₁ = 1`, `ω₂ = 2/(2−ρ²)`, `ωₙ = 4/(4−ρ²ωₙ₋₁)`,
+applied as `x ← ω(x − x^(k−1)) + x^(k−1)` after each colour sweep, skipping every
+particle with a contact slot.
+
+```
+  a 400-particle sheet landing at 3 m/s
+
+  ρ        worst pen.   resting pen.   kinetic@240      ms/step
+  0.00       1.60e-2       7.90e-8       1.11e-2         3.604
+  0.50       1.42e-2       7.90e-8       1.67e-2         3.773
+  0.80       1.70e-2       7.90e-8       1.50e-2         3.682
+  0.90       7.72e-2       4.71e-2       7.60e+1         3.345
+  0.95      4.05e+10      3.66e+10      3.87e+26         3.588
+  0.99       diverged — a Hessian pivot reached Infinity
+
+  a hanging cape with a sphere pushed 6 cm into it, where most particles
+  are free and the acceleration has room:
+
+  ρ=0.00   worst 5.78e-4   resting 3.00e-4   kinetic 4.70e-4
+  ρ=0.80   worst 3.31e-4   resting 3.10e-4   kinetic 4.90e-3
+  ρ=0.95   worst 3.06e-3   resting 0.00e+0   kinetic 1.68e+46
+```
+
+The best cell in the table is the cape at `ρ = 0.8`, which takes a third off the
+penetration and pays ten times the residual kinetic energy for it — a livelier
+cloth, not a better-converged one. Everything else is inside the run-to-run
+spread or worse, the cost is 2–5%, and the top of the parameter range detonates.
+
+Removed. The grid is here so that a future attempt starts from the numbers rather
+than from the idea, and `cloth_step.js` says where the branch was.
+
+---
+
+## 22. A rope with no lateral freedom stands on its own end
+
+Not a solver defect, and recorded because it looks exactly like one.
+
+A rope authored exactly along −Y, compressed by a floor whose normal is exactly
++Y, has every force, every constraint gradient and every position on one axis.
+There is no lateral component anywhere in the system, so the accordion fold it
+lands in is an **exact equilibrium**: every link is at its rest length, the
+residual is zero, and nothing — including §7 P4(d)'s escape hatch, which watches
+the residual — has anything to act on.
+
+An 8-link rope of 10 cm links, hanging from the origin onto a floor at −0.4:
+
+```
+  lean    tip y after 200 steps    what it did
+  0                    −0.201      folded, and stayed folded
+  0.001                −0.385      lay down, one thickness clear of the floor
+  0.01                 −0.385      the same
+```
+
+`lean` is a lateral offset per link as a fraction of the link length, so 0.001 is
+a millimetre across a 10 cm link. **One part in a thousand is enough**, and no
+authored scene is closer to symmetric than that. The tip of the leaning rope
+lands at −0.385 against a floor at −0.4 and a `CLOTH_ROPE` thickness of 15 mm,
+which is the contact row holding it exactly one offset clear.
+
+Recorded rather than fixed. The fix would be a lateral perturbation injected by
+the solver, which is noise added to a system whose whole design commitment is
+that it does not need any.
+
+---
+
+## 23. The frame budget with contacts in it
+
+M1 measured the §17 workload — 1,024 particles at 2 substeps × 4 iterations on a
+32×32 patch — at 4.61 ms and re-sized the library around it. M2 adds a broadphase
+pass per particle per step, up to four contact rows per particle, and two field
+evaluations per contact per iteration.
+
+```
+  no collider system           4.426 ms          0 contact rows
+  1 collider, out of range     4.473 ms   +  1.1%       0 contact rows
+  1 collider, touching         5.485 ms   + 23.9%       4 contact rows
+  4 colliders, touching        5.077 ms   + 14.7%      41 contact rows
+  8 colliders, touching        4.610 ms   +  4.2%      72 contact rows
+  20 colliders, touching       4.829 ms   +  9.1%     107 contact rows
+```
+
+**Read the range, not the rows.** The column is not monotone in the collider
+count — one collider costs more than eight — because the variants sit in
+different physical states, which is the same warning §7 gave about attributing
+cost by deletion. A cloth draped over a sphere is not the same workload as one
+hanging free, whatever the row count says.
+
+What the table does license: **the collision layer costs between nothing and a
+quarter of a frame, and does not scale with the collider count over the range a
+character occupies.** The broadphase — a particle against a collider's swept AABB
+— is the part that does scale, and one collider out of range costs 1.1%, so
+twenty of them out of range would be about a fifth of a frame and worth a
+per-cloth spatial structure if a scene ever wants that many.
+
+**The library is not re-sized.** M1's entries were chosen against 4.61 ms for the
+§17 workload and M2 measures 4.43 ms for the same thing — agreement to 4%, inside
+M1's own ±5% spread — and the worst contact case lands at 5.49 ms, which is 19%
+over M1's figure on a workload the library already spends two levers to avoid.
+Every entry's own budget is unchanged; §17's table stands. M4's self-collision is
+the next thing that could move it, and §17 already says so.
+
+---
+
+# Cloth — M3 measurements
+
+> Written 2026-09-10, against the M3 implementation in `build/` and the rig path
+> in `ecs/`. Everything above this line is M0's, M1's and M2's and is unchanged.
+>
+> Two scripts, both runnable directly under node — the M0 note applies unchanged:
+>
+> ```
+> node src/engine/physics/cloth/ecs/__fixtures__/cloth_m3_measure.mjs
+> node src/engine/physics/cloth/build/__fixtures__/cloth_m3_joint_budget.mjs
+> ```
+>
+> And a fourth playground page, `playground/garment.html`, which is a `Node3D`
+> skeleton with a `Skin` over it and a garment built out of some of its joints.
+
+---
+
+## 24. What M3 proved wrong in PLAN.md
+
+Four things, and the first is the one the whole rig path turns on.
+
+| # | The design said | The measurement said |
+|---|---|---|
+| 0 | §11.2 — the writable handle is "the joint's `Node3D.transform_local` — **the same handle the animation systems write**" | The animation systems do not write it. `TransformAuthority` is explicit: a node a clip drives is `GPU`, and "the CPU allocates and seeds the row, then never writes to it again, so the node's own `transform_local` stops describing it and should not be read as if it did". Cloth writing it on such a node writes to something nothing reads. The seed **claims `CPU`** on every joint it drives, which takes those joints away from the animation — the right trade for a cape, and an authoring error for a garment whose joints are also keyed. §25 |
+| 1 | §11.1 — the rig path is "where the animated pose comes from the skeleton and **is live**" | Not for a rigged garment, and for the reason above: cloth owns those joints, so nothing else poses them, so their authored pose is the proxy's baked bind pose — constant in the anchor's frame, exactly as a rope's is. What moves is the anchor. The live case is the *unrigged* path, where the targets are mesh vertices skinned to the character's skeleton. §25 |
+| 2 | §11.3 step 5 — the fixed set comes from skin weights | That is the right rule for the unrigged path, where the particles are mesh vertices and there is no joint tree. For a rigged garment the **topology** is the answer: a joint whose parent is outside the named set is a joint the garment hangs from, and they all have to hang from the same bone. No weights are read. §25 |
+| 3 | §11.2's table — "output joints, order of magnitude, skirt: ~60" | For a 64 cm cape driven by a gust, 60 joints leaves a worst-case reconstruction error of about 5% of the garment's own size — five grid cells. RMS error goes as **1/joints** and the worst as **N^−0.83**; getting the worst inside a garment's own thickness needs about a thousand. §28 |
+
+And one finding that is not a correction but is the thing an author will hit
+first: **a garment authored inside its own body collider reads as a tether
+failure.** §29.
+
+---
+
+## 25. The two paths are the same solver, and the number is zero
+
+§11 claims the entity path and the rig path are "the solver, identical either
+way; only seeding and write-back differ". That is a claim about trajectories and
+it is checkable: build the same garment twice — five strips of seven links under
+one anchor, once as an entity subtree and once as the joints of a `Skin` —
+drive both the same way, and compare the particles in the cloth's own frame.
+
+```
+  fabric    motion     worst disagreement   as a fraction of the shortest link
+  SILK      still      0.00e+0 m          0.00e+0
+  SILK      walk       0.00e+0 m          0.00e+0
+  SILK      sprint     0.00e+0 m          0.00e+0
+  DENIM     still      0.00e+0 m          0.00e+0
+  DENIM     walk       0.00e+0 m          0.00e+0
+  DENIM     sprint     0.00e+0 m          0.00e+0
+  CHAIN     still      0.00e+0 m          0.00e+0
+  CHAIN     walk       0.00e+0 m          0.00e+0
+  CHAIN     sprint     0.00e+0 m          0.00e+0
+```
+
+**Bit-identical**, across three fabrics and three motion profiles, after 600
+steps. Not "agreeing to rounding" — the same bits.
+
+That is not luck and it is worth saying why, because it is the shape the code was
+given to make it true. M3 moved the row builder out of `cloth_seed_subtree.js`
+into `cloth_build_rows.js`, and the two seeders' *entire* job is to produce a
+`node_parent` array and an `animated_position` array. Everything after that —
+geodesics, link rows, strain limits, skip rows, leashes, the colouring, the
+`ClothState` — is one function called by both. A second copy for the rig path
+would have made §11's claim true of the solver and false of everything above it,
+and this table is what that would have cost.
+
+The write-back is the same story one level up: `cloth_reconstruct_pose.js` turns
+particles into a pose and stops, and the two writers put that pose onto an
+entity's `Transform64` + `TransformAttachment` or onto a `Node3D`.
+
+### Cloth takes the joints, and that is the design rather than a side effect
+
+§11.2 says the writable handle is `Node3D.transform_local`, "the same handle the
+animation systems write". They do not. `TransformAuthority`'s own docblock is
+unambiguous:
+
+> The GPU owns the TRS — animation clips, effects, anything writing through the
+> pose accumulator. The CPU allocates and seeds the row, then never writes to it
+> again, so the node's own `transform_local` stops describing it and should not
+> be read as if it did.
+
+And `instantiate_scene_bundle` stamps `TransformAuthority.GPU` on every node a
+clip channel targets. So a cape joint that an artist keyed — even with a
+placeholder curve — is a joint whose `transform_local` nothing reads, and cloth
+writing it would be writing into a field that stopped being the truth.
+
+`cloth_seed_rig` therefore **claims `TransformAuthority.CPU`** on every joint it
+drives. The consequence is stated rather than hidden: those joints stop being
+animatable by a clip, because two writers of one row is the race the enum exists
+to prevent. For a cape that is the point of simulating it. For a garment whose
+joints are also keyed it is an authoring error, and the claim is where it
+surfaces.
+
+### The anchor's pose is computed, never read back
+
+A joint of an animated skeleton has no CPU-side `transform_global` — nothing
+maintains it — so the rig path evaluates the anchor's world pose with
+`pose_evaluate_world` over the clips the entity is playing. That is the engine's
+own sanctioned answer to "where is this bone", the one
+`query_entity_node_world_pose` gives gameplay, and using it means a cape and a
+scabbard on the same shoulder are placed by the same evaluator off the same
+clock. M3 lifted `collect_entity_playbacks` out of that query so both callers
+gather the same playbacks rather than two lists that could disagree.
+
+---
+
+## 26. The tether on a fanned garment
+
+Worst `max(|x − anchor| / d_geo)` over 600 steps, both paths, five strips of
+seven.
+
+```
+  fabric    motion     entity path   rig path
+  SILK      still         1.0005      1.0005
+  SILK      walk          1.0027      1.0027
+  SILK      sprint        1.1254      1.1254
+  DENIM     still         1.0026      1.0026
+  DENIM     walk          1.0019      1.0019
+  DENIM     sprint        1.4561      1.4561
+  CHAIN     still         1.0002      1.0002
+  CHAIN     walk          1.0029      1.0029
+  CHAIN     sprint        1.1738      1.1738
+```
+
+Resting and walking are inside 0.3%, which is M1's own figure. **Sprinting is
+not**, and denim reaches 1.46.
+
+The two columns being identical is the point: this is not the rig path failing,
+it is §7 P2's conditional bound showing on a shape M1 did not measure. M1's
+profile drove a **20-link rope of uniform 10 cm links with a 2 m reach**, and a
+±9 m/s square wave moves the anchor 15 cm a step — 7% of that reach. The garment
+here has a 0.68 m reach, so the same 15 cm is 22% of it, and it is a *fan*: five
+strips whose first links are nearly horizontal, so a sideways reversal loads them
+across rather than along.
+
+Denim is worst because it is the entry that spends its levers on particles rather
+than on iterations: 2×2 against silk's 2×4, so half the correction authority for
+the same displacement. That is the library's own trade, priced.
+
+The excursion is transient in every case and nothing teleports. What it says is
+that §7 P2's "no particle is ever further from the anchor than `d_geo`" needs its
+conditional read as a statement about **the anchor's displacement against the
+garment's reach**, not only against the shortest row: a short, wide garment on a
+fast anchor is the case that finds it.
+
+---
+
+## 27. What the rig path costs
+
+The same garment, the same steps, the same fabric, best of three rounds.
+
+```
+  garment                  entity path    rig path    difference
+  5 strips × 7 (35 joints)   0.0988 ms    0.1034 ms      +4.6%
+  3 strips × 9 (27 joints)   0.0861 ms    0.0883 ms      +2.5%
+  12 strips × 10 (120)       0.3082 ms    0.3183 ms      +3.2%
+```
+
+Two to five per cent, which is the CPU pose evaluation of the anchor joint plus a
+`Node3D` write-back in place of a `Transform64` one. The anchor evaluation is a
+walk up the joint chain per cloth per step and does not scale with the garment,
+which is why the largest garment shows the smallest relative difference.
+
+For scale against §17's budget: 120 joints is 0.32 ms, and a garment's joint
+count is a *proxy* rather than a simulation resolution — the whole point of §11.2's
+three tiers is that a 5,000-vertex render mesh rides 120 joints. Nothing in the
+library needs re-sizing.
+
+---
+
+## 28. How many joints a drape takes — §18's open question
+
+§18 carries the unrigged path's joint budget as open, with the mitigation that
+**M3 measures the fidelity curve before fixing a budget**. The unrigged runtime
+path is not in M3; this is the experiment that says what it would cost.
+
+A 33×33 cape at 2 cm — 1,089 particles, 64 cm square, pinned along its top edge
+and driven by a gust — is simulated at full resolution and is the reference. A
+`k × k` grid of those particles is nominated as joints; every particle is bound
+to the four nearest of them in the mesh's own parameter space with
+inverse-distance weights, which is exactly what a four-weight palette does; and
+the garment is reconstructed each frame by linear blend skinning from the joints'
+fitted frames.
+
+```
+  joints    RMS error        worst      as % of the garment    degenerate frames
+       4    6.13e-2 m    1.92e-1 m      29.93%                     0
+       9    2.14e-2 m    1.22e-1 m      19.13%                     0
+      16    1.19e-2 m    7.51e-2 m      11.73%                     0
+      25    8.01e-3 m    6.81e-2 m      10.65%                     0
+      36    5.92e-3 m    5.10e-2 m       7.97%                     0
+      49    4.44e-3 m    3.97e-2 m       6.21%                     0
+      81    2.77e-3 m    2.36e-2 m       3.69%                     0
+     121    2.04e-3 m    1.90e-2 m       2.97%                     0
+     289    9.35e-4 m    5.60e-3 m       0.88%                     0
+```
+
+**RMS error is inversely proportional to the joint count** — `RMS × joints` is
+0.245 at 4 joints and 0.270 at 289, flat across a factor of 72 — and the worst
+case falls more slowly, as about `N^−0.83`.
+
+That gives the budget its shape. §11.2's table guesses "~60 output joints" for a
+skirt; at 60 the worst-case error on this cape is about 5% of its own size, which
+is five grid cells and reads as faceting. Putting the worst inside **one grid
+cell** takes about 120 joints; inside the garment's own 4 mm thickness takes
+about a thousand, which is not a budget, it is the simulation resolution again.
+
+So the honest statement for a future unrigged path is: **80 to 120 joints for a
+cape of this size, and the four-weight palette is what sets that** — the error at
+289 joints is still 0.88%, and it is not the frames that are losing it.
+
+### The frames did not degenerate, and that is measured rather than argued
+
+§18's second open risk is that "a fold that collapses a triangle fan has no
+well-defined frame". The run counts a frame as degenerate when either fitted
+tangent falls below 1e-4 m. **Across 800 frames × up to 121 joints, in the table
+above and in a deliberately crumpled variant — bending at 1e-7 and a gust four
+times as hard — the count is zero:**
+
+```
+  joints    RMS error        worst      as % of the garment    degenerate frames
+      16    3.69e-2 m    1.52e-1 m      23.82%                     0
+      36    1.94e-2 m    8.97e-2 m      14.01%                     0
+      81    1.05e-2 m    5.12e-2 m       8.00%                     0
+     121    8.17e-3 m    4.86e-2 m       7.60%                     0
+```
+
+The mechanism is worth stating, because it is why it did not happen rather than a
+promise that it cannot. A tangent is a difference across **two links**, and the
+stretch rows are hard, so each of those links holds its length; the only way the
+difference vanishes is a fold of exactly 180° at the joint's own vertex, which is
+a measure-zero configuration the bend rows are actively pushing away from. It is
+*possible* — hard rows do not forbid it — and a future unrigged path should keep
+the epsilon and the fallback rather than delete them on the strength of a zero.
+
+What the crumpled variant does show is that the error roughly triples: a garment
+with no bending resistance needs about three times the joints for the same
+fidelity, which is the other half of the budget question and says that the number
+is per-fabric rather than per-garment.
+
+---
+
+## 29. A garment authored inside its own body reads as a tether failure
+
+Not a correction, and the first thing an author will hit.
+
+The M3 playground's first cape was authored 9 cm behind the chest, and the
+character's torso collider was a capsule of 16 cm radius on the spine — so the
+garment's first links started **inside the body**. What that looks like is not a
+garment stuck in a torso. It looks like this:
+
+```
+  worst |x − anchor| / d_geo, a cape at rest, no motion at all
+
+  with the body colliders      1.3117
+  without them                 1.0000
+```
+
+The contact row pushes the first links out of the collider, the tether row pulls
+them back, the contact wins — measured at 363 N of multiplier on a link holding
+a 0.12 kg strip — and the readout says the tether is failing by 31%. It is not.
+Both rows are doing exactly what they are for, and the configuration is one
+neither of them should ever have been given.
+
+§11.3's step 10 is the answer and it says so: the build validates "that the
+skinned bind pose is collision-free against the character's `ClothCollider` set",
+and fails loudly with the offending vertex and collider named. **M3 does not
+build that check** — `cloth_proxy_from_joints` has a joint tree and no collider
+set — and this measurement is the argument for it being the next thing the build
+gains rather than a nicety. Moving the garment 21 cm back and shrinking the torso
+capsule to 13 cm returns the resting figure to 1.0022.
+
+---
+
+# Cloth — M4 measurements
+
+> Written 2026-09-11, against the M4 implementation in `solver/` and the grid in
+> `core/geom/3d/hash-grid/`. Everything above this line is M0's, M1's, M2's and
+> M3's and is unchanged.
+>
+> Two scripts, both runnable directly under node — the M0 note applies unchanged:
+>
+> ```
+> node src/engine/physics/cloth/solver/__fixtures__/cloth_m4_measure.mjs
+> node src/engine/physics/cloth/ecs/__fixtures__/cloth_library_bench.mjs
+> ```
+>
+> The second is M1's, extended here with the section that prices self-collision
+> against each entry's own size and budget.
+>
+> **A folding sheet is chaotic**, and one run of one gust says nothing about a
+> parameter. Every folding measurement below is the mean over **twelve gust
+> realisations** — the same sheet, the same everything, twelve phases and rates
+> of the driving gust. The first version of §32 ran one realisation per row, and
+> at one the noise was larger than the effect and pointed at a different answer.
+
+---
+
+## 30. What M4 proved wrong in PLAN.md
+
+Four things, and the first is the one the whole tier turns on.
+
+| # | The design said | The measurement said |
+|---|---|---|
+| 0 | §9 — pairs closer than `r_i + r_j` get the unilateral row from §6, whose `r` reads as the same `ClothDynamics#thickness` a collider contact uses | Not at a garment's real proportions. A fabric is 4 to 20 mm thick and a proxy's particles are 2 to 8 cm apart, so the two layers of a fold are almost never within a fabric thickness of each other. At the fabric's own 6 mm the row removes **21%** of a folding sheet's self-intersections; at half the shortest row — a diameter of one particle spacing — it removes **82%**. The radius is a property of *the proxy*, not of the cloth it stands for. §31 |
+| 1 | §14.2 — a 3D uniform hash grid "modelled on `core/geom/2d/hash-grid/SpatialHashGrid.js`" | The 2D grid is a **persistent, incremental** structure: a bounded array of cells, elements that are AABBs and carry identity, and insert/remove/move as the primitive operations. Cloth's grid is none of those. Its elements are points with no identity across steps, its domain is unbounded, and every particle moves every step — so the operation that matters is *rebuild*, and insert/remove never runs at all. `PointHashGrid3` is a counting sort into a power-of-two hash and shares no structure with the 2D grid. The rebuild is 10% to 12% of the step it sits in front of, and most of everything self-collision costs. §34 |
+| 2 | §9 — the flag is "set on the library entries that need it (skirts, long coats, hair) and clear on the ones that do not (capes, ponytails, banners)" | That list is drawn along the wrong axis. What decides is not what the garment *is* but how far the fabric bends: the floppier the fabric the more it passes through itself. Silk, hair and cotton tangle 8 to 11 times a sample and the row removes 71% to 81%; leather tangles 0.18 times and the row makes it *worse*. §33 |
+| 3 | §9 — "Both tiers derive their normals from the proxy's surface orientation, per P4(a)" | M4a's normal is the line between the two particles, because a particle pair has no surface in it. What P4(a) actually asks for — nothing history-dependent, no "which side was this on last frame" to latch onto — the pair normal satisfies completely and more simply: recomputed every iteration from the current positions, with no multiplier, no warm start and no identity across steps. The sentence is right about M4b, where a point-triangle stencil genuinely needs an orientation to choose a side. |
+
+**And two findings with no line in PLAN.md to correct**, because §9 never wrote a
+radius down at all. `max(thickness, shortest_row/2)` has an upper end and leather
+is on it (§36) — and that upper end has to be *measured* rather than reasoned
+from a sheet's topology, because the geometry M3 ships is not a sheet (§37).
+
+Two things the implementation **confirmed** rather than corrected, both of them
+places where an earlier milestone wrote down what M4 would find:
+
+- **§5.4's Jacobi paragraph.** M2 measured that a *collider* contact is unary
+  and needs none of it, and left the paragraph standing "for M4's rows, which
+  really are pairs". They are, and it does. `cloth_self_row.js` accumulates the
+  pair list into a per-particle `(f, H)` scratch once per iteration and every
+  vertex update adds its own entry, which is what keeps the step independent of
+  the order the colours were swept in.
+- **§9's "it prevents the great majority of visible interpenetration".** 82% of
+  it, at the radius §31 settles on. The tier's stated limit — cloth passing
+  *between* particles — is real and is what the other 18% is: §35 went looking
+  for a cheaper explanation, a pair search running one step behind the solver,
+  and ruled it out.
+
+---
+
+## 31. The radius is the proxy's resolution, not the fabric's thickness
+
+§6 writes the row as `‖x_i − x_j‖ − (r_i + r_j)` and §9 says the pairs that get
+one are those "closer than `r_i + r_j`". Both read naturally as the same `r` a
+collider contact uses, which is `ClothDynamics#thickness` — how thick the fabric
+is. M4 was built that way and it barely worked: on a folding garment the pair
+list held **1.6 to 3.7 pairs a step across the whole cloth**, and no stiffness
+made the sheet stop passing through itself.
+
+The arithmetic is not subtle once it is written down. A fabric is 4 to 20 mm
+thick. A proxy's particles are 2 to 8 cm apart. Two layers of a fold are within
+a *fabric thickness* of each other only when their particles happen to line up,
+and nothing makes them line up.
+
+A 12×12 sheet at 2 cm spacing, 6 mm thick, driven into a fold. Only the radius
+moves; the stiffness, the gust and the mesh are held fixed. "Crossings" counts
+edges passing through triangles they share no vertex with — §17's own metric —
+sampled every twentieth step and averaged over twelve gust realisations. The
+same sheet with no row at all sits at **11.39**.
+
+```
+  radius   diameter   pairs/step   crossings: mean / worst    overlap mean
+
+     3 mm       6 mm         0.5       10.60 /  156           5.2 mm
+     6 mm      12 mm         2.6        9.00 /  190          10.7 mm   <- the fabric thickness
+     8 mm      16 mm         3.9        5.33 /   86          14.4 mm
+    10 mm      20 mm         4.8        2.03 /   71          18.4 mm   <- half the shortest row
+    12 mm      24 mm         5.5        0.91 /   64          20.1 mm
+    16 mm      32 mm         8.2        0.02 /    5          24.8 mm
+```
+
+At the fabric's own thickness the row removes 21% of the crossings. At half the
+shortest row — a diameter of exactly one particle spacing — it removes 82%. The
+radius is a property of **the proxy**, and `ClothState#self_radius` is a separate
+field from `contact_radius` for that reason: a collider contact really is about
+how thick the cloth is, and this is not.
+
+`ClothSystem` writes `max(thickness, shortest_row / 2)`, under a ceiling §36 and
+§37 derive. The `max` is not decoration: a heavy fabric on a coarse proxy — 2 cm
+of leather on 3 cm particles — is the one case where the fabric is the longer of
+the two lengths, and there the thickness is right.
+
+### The column does not turn over, and the reason to stop is not in it
+
+12 mm is better than 10, and 16 mm — a diameter of 1.6 particle spacings — very
+nearly eliminates crossings. §36 carries the sweep further and it keeps
+improving right up to a cliff at two spacings that has nothing to do with
+crossings at all.
+
+**So the shipped value is not the minimum of this table, and it would be
+dishonest to present it as one.** Half the shortest row is a *fidelity* choice:
+a self-collision radius is the cloth's apparent half-thickness, and at a
+diameter of 1.6 spacings a silk cape on 8 cm particles would hold the two layers
+of a fold nearly 13 cm apart. For 4 mm of silk that is absurd, and no crossing
+count can see it — the metric being optimised cannot measure the thing that
+stops the optimisation. A diameter of one particle spacing is the largest
+separation the proxy can be said to *mean*, since it is the mesh's own finest
+feature, and it delivers §9's "great majority" at 82%.
+
+What would settle it properly is a number M4 does not have: what the search
+costs as a function of cell size. §34 shows the search is nearly all of the cost
+and that it scales with particles, but a wider radius is a wider *cell*, and
+every walk then visits more candidates. Someone who wants a stricter garment can
+raise the radius today — the table above is the dial, and the ceiling in §36 is
+where it stops — but they should measure that first.
+
+---
+
+## 32. How stiff the row has to be, and what it is actually for
+
+Same sheet, same gust, radius fixed at half the shortest row; the penalty moves.
+`CLOTH_SELF_RATIO` is a multiple of `m_eff/h²` exactly as the bend and leash
+bands are, and `m_eff` for a pair with two free ends is half a particle.
+
+```
+  k / (m_eff/h²)   overlap: mean / worst    crossings: mean / worst / rest    pairs   kinetic
+
+               0     19.4 /  19.7 mm        11.39 /  146 /   0.0      0.0   6.86e-3
+               1     17.4 /  19.2 mm         3.42 /   51 /   0.0      6.9   6.63e-3
+               2     16.6 /  19.3 mm         3.36 /   76 /   0.0      5.8   5.81e-3
+               4     17.2 /  19.3 mm         2.75 /   83 /   0.0      4.8   6.28e-3
+               8     18.4 /  19.8 mm         2.03 /   71 /   0.0      4.8   7.57e-3
+              16     16.8 /  19.5 mm         2.03 /   96 /   0.0      4.6   7.00e-3
+              32     16.8 /  19.3 mm         2.45 /  123 /   0.0      4.4   5.24e-3
+              64     17.5 /  19.5 mm         3.87 /  125 /   0.0      4.3   6.81e-3
+```
+
+Four readings, and the last two are the ones worth keeping.
+
+**Most of the win is in having a row at all.** 11.39 crossings a sample without
+one, 3.42 with the softest row in the table. The remaining sweep moves it from
+3.42 to 2.03 — a third of what the first newton bought.
+
+**The mean bottoms at 8 to 16 and the worst case gets steadily worse the whole
+way up.** 51 crossings at the worst realisation with `k = 1`, 125 with `k = 64`.
+A stiff penalty removes the average tangle and creates a rarer, larger one: it
+throws a particle hard enough to put the sheet through itself somewhere the row
+was not looking. `CLOTH_SELF_RATIO` ships at **8**, which is the joint minimum of
+the mean and is well down the worst-case curve.
+
+**M0's dissipative band does not bind this row.** M0 measured that a soft row
+stiffer than about `8·(m/h²)` makes the step add energy rather than lose it, and
+`cloth_step` originally justified the ratio by that ceiling. The kinetic column
+says otherwise: across a sixty-four-fold range of stiffness it moves between
+5.2e-3 and 7.6e-3 with no trend at all. The band was measured on rows that are
+**on every step** — a bend row, a leash. A self-collision row is one-sided and
+vanishes the instant it is satisfied, so it does work only while it is
+compressing and has no standing spring to pump. Eight is the right number here
+and the band is not the reason; the comment in `cloth_step.js` no longer claims
+it is.
+
+**The row never achieves its own separation, and it is not meant to.** The
+overlap column is `diameter − distance` at the worst governed pair, and it barely
+moves: 19.4 mm without the row and 16.6 to 18.4 mm with it, out of a 20 mm
+diameter. Inside a fold the hard stretch rows are holding the sheet's own
+geometry and a soft penalty cannot outvote them. What it can do is decide *which
+side* of the fold a particle ends up on, which is what a crossing count measures
+and what §9 asks the tier for.
+
+### The settled sheet is clean either way, which is the whole flag question
+
+The `rest` column is zero in every row of the table, the `k = 0` row included. A
+sheet with no bending resistance flattens itself once the gust stops and takes
+its tangles out with it. Every crossing counted above happened while the cloth
+was *moving*.
+
+That is not a small caveat, it is the shape of the answer: if tangling were
+transient for every fabric, the flag would never be worth setting. It is not —
+what makes a tangle stay is bending. §33.
+
+---
+
+## 33. Which entries set the flag, and what it costs them
+
+§9 says the flag is "set on the library entries that need it (skirts, long
+coats, hair) and clear on the ones that do not (capes, ponytails, banners)".
+That list is drawn along what the garment *is*. The measurement is drawn along
+how far the fabric bends, and it separates the entries far more sharply.
+
+The same folding sheet, twelve realisations, with each library entry's own
+`bend` — a ratio of the bend row's inertial scale, mapped the way
+`cloth_build_rows` maps it — and nothing else changed.
+
+```
+  entry      bend   row?    crossings: mean / worst    pairs    removed
+
+  SILK      0.04   none         8.08 /  167      0.0
+  SILK      0.04   with         2.37 /   77      4.5     71%
+  HAIR      0.20   none        10.62 /  139      0.0
+  HAIR      0.20   with         1.98 /   71      4.4     81%
+  COTTON    0.25   none         9.36 /  135      0.0
+  COTTON    0.25   with         1.99 /   49      4.7     79%
+  DENIM     0.62   none         3.59 /  103      0.0
+  DENIM     0.62   with         1.37 /   70      2.2     62%
+  LEATHER   1.00   none         0.18 /   39      0.0
+  LEATHER   1.00   with         0.41 /   44      0.3    -137%
+```
+
+**Leather does not tangle, and the row makes it worse.** 0.18 crossings a sample
+unaided — call it none — and 0.3 pairs a step, which is the row finding almost
+nothing and pushing on a sheet that had not asked. A fabric at the top of the
+bend scale will not fold tightly enough to pass through itself; there is nothing
+for the tier to prevent, and the handful of pairs it does find are noise it is
+adding rather than removing. The sign of that last column is the whole argument
+for the flag being off by default.
+
+**Denim tangles a third as much as cotton** and the row removes 62% of it. It is
+the one genuinely marginal entry, and it is also the entry that has already spent
+both of its performance levers (§17): 576 particles at 2×2. It stays clear.
+
+**Silk, cotton and hair are where the tier earns its keep** — 8 to 11 crossings a
+sample unaided, 71% to 81% of them gone. Cotton is "the default fabric, and the
+one every other entry is a deviation from", and a default that shows nine
+crossings in every sample taken while it moves is a bad default.
+
+So the flag moves from one entry to three: `CLOTH_SILK` and `CLOTH_COTTON` join
+`CLOTH_HAIR`. `CLOTH_DENIM`, `CLOTH_LEATHER`, `CLOTH_ROPE` and `CLOTH_CHAIN`
+stay clear — the first two on the table above, the chains because a chain has no
+surface to pass through and a coiling rope is a case this measurement does not
+cover.
+
+### What that costs
+
+The solver-level figure first, on the folding sheet, so the shape of the cost is
+visible before the entries are priced:
+
+```
+  particles   without      with       delta     pairs/step   slots full
+
+        144   0.445 ms   0.508 ms     14.3%          2.6          0
+        256   0.813 ms   0.936 ms     15.1%          7.1          0
+        484   1.541 ms   1.806 ms     17.2%         20.6          0
+       1024   3.491 ms   4.100 ms     17.5%         36.0          0
+```
+
+Flat at 14% to 18%, and the pair list never once hit its cap — 36 pairs a step
+across 1,024 particles at the widest, against a ceiling of eight per particle.
+The cost is not in the pairs; §34 says where it is.
+
+And then every entry at its own size, its own budget and its own row set, from
+`cloth_library_bench.mjs` — the same harness M1 sized the library with, driven by
+a gust so the pair list is doing work:
+
+```
+SILK      2x4     1.427 ms ->   1.802 ms    26.3%  inside pairs  318.0 full 0
+COTTON    2x4     1.478 ms ->   1.802 ms    22.0%  inside pairs  325.1 full 0
+DENIM     2x2     1.297 ms ->   1.765 ms    36.1%  inside pairs  607.8 full 0
+LEATHER   2x2     1.315 ms ->   1.828 ms    39.0%  inside pairs  740.2 full 0
+ROPE      2x4     0.116 ms ->   0.129 ms    11.5%  inside pairs    0.0 full 0
+CHAIN     2x6     0.165 ms ->   0.183 ms    11.0%  inside pairs    0.0 full 0
+HAIR      2x4     1.438 ms ->   1.798 ms    25.1%  inside pairs  315.7 full 0
+```
+
+**Every entry stays inside 2 ms, and the three that set the flag have about a
+tenth of a frame left.** 1.80 ms against 2.00 for silk, cotton and hair — which
+is the thinnest headroom in the library and is the thing to watch when M5 or M6
+adds anything to the step. The bare figures agree with M1's to within 4%
+(silk 1.427 against a claimed 1.49, denim 1.297 against 1.28), so **no entry is
+re-sized**: §17's table stands, and self-collision is spent out of headroom
+rather than out of a lever.
+
+The delta here — 22% to 26% — is larger than the 14% to 17% above because this
+harness folds a 400-particle sheet hard enough to find 318 pairs a step against
+the folding sheet's 5. That is the honest worst case for a garment of this size,
+and it is the figure the entries were checked against.
+
+**The chains find nothing**, which is the measurement behind leaving `CLOTH_ROPE`
+and `CLOTH_CHAIN` clear: 0.0 pairs a step, and the 11% they still pay is the
+grid being built and walked for a cloth that will never have a pair in it. A
+hanging chain's nearest ungoverned particles are three links apart and its links
+are 5 cm long; nothing about a rope brings them within one link of each other
+except coiling, which this harness does not do.
+
+**Leather is the entry the §36 clamp is for.** Before it, this same row read
+1,398 pairs a step — the row had found the mesh rather than a fold. Clamped, its
+radius comes down from 20 mm to 16 mm and it reads 740, and those are folds. It
+still does not set the flag.
+
+(§37 later replaced the ceiling's *derivation* without moving any number here:
+every entry's radius on this harness is identical under both rules, because on a
+sheet the closest ungoverned pair is exactly two hops. The bench takes the
+production path so that stays true rather than being assumed.)
+
+### The other cost is memory, and four of seven entries pay it for nothing
+
+`ClothState` is one `ArrayBuffer`, sized at seed, and M4's three regions —
+`self_pair`, `self_force`, `self_hessian` — are in it whether or not the flag
+is ever set. On the §17 workload:
+
+```
+  1,024 particles, 2,945 stretch rows, 2,821 bend rows
+
+  whole state buffer      637,344 bytes
+  self-collision          102,400 bytes   16.1%
+```
+
+Four of the seven library entries never read a byte of it. The reason it is
+unconditional is that the flag can be toggled without a reseed today —
+`cloth_dynamics_change_needs_reseed` returns false for it, because nothing in
+the row tables depends on it — so a lazily-sized region would have to become a
+reseed trigger. That is a change to the reseed contract for 100 KB a garment,
+and M4 leaves it: **recorded, not fixed**, and the number is here so whoever
+decides has it.
+
+---
+
+## 34. The grid is the cost, and it is not the 2D grid
+
+§14.2 asks for "a 3D uniform hash grid, modelled on
+`core/geom/2d/hash-grid/SpatialHashGrid.js`". What landed shares the *idea* and
+none of the structure, and the reason is worth writing down because the next
+person to want a broadphase in `core` will read that sentence too.
+
+The 2D grid is **persistent and incremental**. Its cells are a bounded array
+sized at construction, its elements are AABBs that carry identity and user data,
+and its primitives are `element_insert`, `element_remove` and the linked-list
+surgery that moves one between cells. That is the right shape for a world of
+things that mostly sit still and occasionally move — which is what it was built
+for.
+
+A cloth's particles are the opposite of that in all four respects. They are
+**points**, not boxes. They carry **no identity across steps** — a pair list is
+rebuilt from scratch every step precisely because there is nothing on a pair
+worth keeping (`cloth_self_row.js`). Their domain is **unbounded**: a garment
+travels with its character and a fixed cell array would have to be re-based every
+frame. And **every particle moves every step**, so the incremental primitive
+never gets to be incremental; a full pass of remove-and-reinsert is a rebuild
+with extra bookkeeping.
+
+`PointHashGrid3` is therefore a counting sort — count per bucket, prefix-sum,
+scatter — into a power-of-two hash of the integer cell, and it has no insert, no
+remove and no element identity at all. Two files, one word in common.
+
+### The rebuild is most of what self-collision costs
+
+Which makes it the thing to defend. The same folding sheet, timing the pair
+search separately from the step it feeds:
+
+```
+  particles      step       search        rows     search as % of the whole
+
+        144   0.442 ms   0.048 ms   0.010 ms               9.6%
+        256   0.806 ms   0.113 ms   0.001 ms              12.3%
+        484   1.615 ms   0.217 ms   0.011 ms              11.8%
+       1024   3.547 ms   0.482 ms   0.164 ms              11.5%
+```
+
+`step` is the solver with no pairs at all; `search` is `cloth_self_find`;
+`rows` is what the pairs then cost inside the solve, taken as the difference
+between two runs. That last column is a difference of two minima from separate
+runs and at 484 it comes out *negative*, which is the harness saying the quantity
+is below its own noise floor rather than saying the rows are free. Read it as
+"small": between 0.005 and 0.14 ms against a search of 0.05 to 0.50.
+
+So the **search is most of it and the rows are the remainder** — two thirds to
+all of it across the four sizes, and the spread is the `rows` column's noise
+rather than anything about the sizes. And the search scales the way a counting
+sort does: linear in particles to within the noise, with no term in the pair
+count at all. §9's "O(n) with a small constant" is right about the shape and
+optimistic about the constant — half a microsecond a particle, which is 11% of
+a frame at the §17 workload.
+
+The consequence for whoever takes M4b — point-triangle and edge-edge — is that
+the extra stencils are not what will cost; they ride on a grid that has already
+been built. The estimate in §9 that M4b "roughly triples the self-collision cost"
+is the thing to re-measure first, and this table is the reason to doubt it.
+
+---
+
+## 35. What is left is not the search being one step behind
+
+`ClothSystem` calls `cloth_self_find` and then `cloth_step`. The pair set is
+therefore discovered from the positions the *previous* step left, and the row
+acts on positions `cloth_predict` has already moved. A pair that becomes a
+contact **during** the step is not in the list, and by the time the next step
+looks, the two particles have already crossed.
+
+That is the shape of the gap §20 found in the contact set, where the answer was
+to widen the discovery reach by the collider's own travel —
+`cloth_contact_find` carries `CLOTH_CONTACT_MARGIN` and adds `TRAVEL[record]`
+for it. The self-collision search has no equivalent, and §32 leaves 2.03
+crossings a sample unaccounted for. The obvious suspicion is that they are the
+same thing.
+
+They are not. Here the search runs at a multiple of the row's radius while the
+row is unchanged, so the extra pairs are found and then found to be out of
+contact — which is what a travel margin would do:
+
+```
+  search radius   pairs/step   crossings: mean / worst   slots full
+
+          1.0x          4.8        2.03 /   71          0
+          1.5x         32.3        2.13 /   69          0
+          2.0x        187.8        1.77 /  110          0
+          3.0x        738.9        4.76 /   89          0
+```
+
+**The pair list grows a hundred and fifty times over and the crossing count does
+not move.** 2.03 at the shipped width, 2.13 at one and a half, 1.77 at two —
+inside the spread of twelve realisations — and then *worse* at three.
+
+So the residual is not a discovery problem. It is the limit §9 states and does
+not hide: a particle-particle row can only act when two **particles** are close,
+and a sheet can pass through itself between them. No width of search reaches
+that, because the thing that needs a row is a point against a triangle and there
+is no point-triangle row here. This is M4b's, and M4b is deferred.
+
+**Why three times over is worse rather than merely wasteful.** The list holds
+`CLOTH_SELF_PAIRS_PER_PARTICLE` — eight per particle — and a particle at the cap
+keeps the eight it found *first in grid order*. At the shipped radius every
+candidate inside it is in contact, so which eight is arbitrary among equals. At
+three times it, almost none of them are, and the budget goes on pairs that will
+be discarded a moment later by the distance test while the pairs that mattered
+never make the list. The cap is what turns a wider search from a cost into a
+regression, and it is the thing to redesign first if anyone does want a swept
+search: a second radius with its own budget, or the search moved inside the
+substep loop after `cloth_predict`.
+
+---
+
+## 36. `max(thickness, …)` has an upper end, and leather is over it
+
+§31 settles the radius at half the shortest row and keeps a `max` against the
+fabric's thickness, for the case it named: a heavy fabric on a coarse proxy,
+where the fabric is the longer of the two lengths. Nobody looked at where that
+branch stops being safe.
+
+**On this topology the nearest pair no row governs is two hops away.** One hop is
+a stretch row. The mesh diagonal is a stretch row too. The two vertices *across*
+a diagonal are the four particles of a bend stencil. Everything closer than two
+hops is excluded by construction — which is exactly what makes half a hop the
+right radius, and it also means a **diameter** that reaches two hops puts a flat,
+undisturbed sheet in contact with itself everywhere.
+
+The same folding sheet, sweeping the diameter as a multiple of the particle
+spacing, with pairs counted both while it folds and after it settles:
+
+```
+  diameter / spacing   pairs while folding   pairs at rest   crossings
+  diameter / spacing   pairs while folding   pairs at rest   crossings
+
+               0.5x                   1.8             0.4       10.76
+               0.8x                   3.9             0.0        5.33
+               1.0x                   4.8             0.0        2.03
+               1.4x                   6.1             0.0        0.18
+               1.8x                  13.1             0.0        0.04
+               1.9x                  22.4             0.0        0.03
+               2.0x                 103.7            78.7        0.02
+               2.2x                 220.5           218.0        0.00
+```
+
+And where the library lands on a 2 cm proxy, under `max(thickness, 10 mm)`:
+
+```
+    SILK      thickness  4 mm  ->  radius 10 mm  =  1.0x spacing
+    HAIR      thickness  6 mm  ->  radius 10 mm  =  1.0x spacing
+    COTTON    thickness  8 mm  ->  radius 10 mm  =  1.0x spacing
+    DENIM     thickness 14 mm  ->  radius 14 mm  =  1.4x spacing
+    LEATHER   thickness 20 mm  ->  radius 20 mm  =  2.0x spacing
+```
+
+**The cliff is exactly where the topology says, and it is a cliff.** At 1.9
+spacings a settled sheet has no pairs at all; at 2.0 it has seventy-nine, and at
+2.2 it has two hundred and eighteen — on a cloth that is hanging still. Nothing
+about the fold changed. The row simply reached the first pair the mesh had not
+already claimed, and from there it is in contact with itself everywhere, for
+ever, pushing a flat sheet apart with a force that has nothing to resolve.
+
+Note also that the crossing column is *still improving* across the cliff. A
+measurement that only counted crossings would walk straight over it, which is
+the argument for the "pairs at rest" column existing.
+
+**Leather is on the number.** 20 mm of hide on a 20 mm proxy gives the row a
+diameter of exactly two spacings. Before the clamp, the library bench found it
+**1,398 pairs a step** on a 576-particle sheet — more than two per particle, on
+a cloth that was barely folded. Silk found 318 on the same harness.
+
+The radius is now clamped at both ends, and the ceiling leaves two tenths of a
+spacing between itself and the cliff — the table says the sheet is clean well
+before that. **§37 then makes the ceiling a measured length rather than a
+multiple of the shortest row**, because the two-hop argument above is a fact
+about *sheets* and a rigged garment is not one. On a sheet the two agree
+exactly, so nothing in this section moves.
+
+This is the one M4 finding with no line in PLAN.md to correct: §9 never wrote a
+radius down at all, which is how the whole question stayed open long enough to
+be got wrong twice — once too small, once too large.
+
+---
+
+## 37. What a rigged garment shows that a sheet cannot
+
+Everything from §31 to §36 was measured on a triangulated sheet, because a sheet
+is the only thing in the system with a *surface* to pass through. The
+playground's cape is not a sheet. It is five strips of seven links, and **nothing
+joins one strip to the next** — §11.3's proxy is joint indices and a topology,
+and that topology is a set of chains.
+
+Two things follow, and the second is a correction.
+
+### Without the row a cape collapses to half the width it was drawn at
+
+```
+  the playground's cape — 5 strips of 7, silk, settled from the bind pose
+
+  bind pose                     0.340 m wide
+  settled, no self-collision    0.178 m          −48%
+  settled, with it              0.351 m           +3%
+```
+
+Nothing holds the strips apart but this row. Under gravity each one swings
+inward and they end up occupying the same space, so the cape settles at half the
+width the artist drew and its strips hang through one another. **This is the
+first thing in M4 that self-collision visibly does on the geometry M3 actually
+ships**, and no sheet measurement could have found it: a sheet's neighbouring
+columns are held apart by the stretch rows between them, and a cape's strips have
+nothing between them at all.
+
+It is also the answer to a question §32 left open. There, every tangle was
+transient — the sheet untied itself whenever the gust stopped, which is why
+§17's escape hatch still has nothing to escape from. This one is not transient.
+It is what the garment settles *into*.
+
+### And the ceiling has to be measured, not derived from the shortest row
+
+§36 clamps the radius at four fifths of the shortest row, reasoning from a
+sheet: the nearest pair no row governs is two hops away, so four fifths of one
+hop leaves a margin. On a sheet that is exactly right —
+`cloth_self_closest_free_pair` returns 2.0000× the spacing at both 2 cm and
+5 cm, and the two ceilings agree to the precision Float32 positions carry.
+
+On the cape they do not agree at all:
+
+```
+  shortest row — a link, along a strip      0.0801 m
+  two hops, which a sheet would predict     0.1602 m
+  the closest ungoverned pair, measured     0.0850 m
+```
+
+The gap *between* strips is half what the link length implies, because it is a
+different length entirely: the artist put those joints where the garment needed
+them, and nothing relates that to how finely each strip is subdivided. Derived
+from the shortest row the ceiling came out at 0.064 m, the 0.040 m floor took
+precedence, and the settled cape carried **three pairs permanently in contact** —
+lateral ones, with nothing to do with folding. Measured, the ceiling is 0.034 m
+and the settled cape carries **none**.
+
+So `CLOTH_SELF_RADIUS_MAX_RATIO` is two fifths of `ClothInstance#closest_free_pair`
+rather than four fifths of the shortest row, and `closest_free_pair` is measured
+once at seed, in the bind pose, by the same grid and the same exclusion set the
+pair search uses.
+
+**§31 through §36 are unaffected.** Every one of them was taken on a sheet, where
+the new rule reproduces the old one to the precision the positions carry, and
+`cloth_self_radius.spec.js` pins exactly that so it cannot drift.
+
+### What measuring it costs
+
+Once per seed, and every cloth pays it whether or not the flag is set, because
+the flag can be turned on later without a re-seed:
+
+```
+  1,024 particles, 2,945 stretch rows, 2,821 bend rows
+
+  the exclusion set    1.792 ms
+  the free-pair walk   0.664 ms
+                       2.455 ms, once
+```
+
+The exclusion set is the larger half and it is not new work — it was built
+lazily on the first self-collision step before, so a cloth that sets the flag
+paid it anyway. What is new is that a cloth which never sets the flag now pays
+it too, at seed, alongside the subtree walk and the graph colouring that seeding
+already does. Nothing pays it per step.
+
+---