@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,2239 @@
+# Cloth — measurements
+
+> 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.
+
+---
+
+# Cloth — M0 measurements
+
+> What the solver core actually does, measured. Written 2026-09-10, against the
+> M0 implementation in `solver/`.
+>
+> Every number here is reproducible from two scripts, both runnable directly
+> under node (through vitest, imported bindings become getters and the
+> cross-module calls that make up the inner loop stop inlining — which is
+> exactly what is being measured):
+>
+> ```
+> node src/engine/physics/cloth/solver/__fixtures__/cloth_constants_sweep.mjs
+> node src/engine/physics/cloth/solver/__fixtures__/cloth_bench.mjs
+> ```
+>
+> There is also a playground, which is where the §6 finding came from:
+> `npm run dev --workspace @woosh/meep-engine`, then
+> `/src/engine/physics/cloth/playground/`. Its presets are the interesting rows
+> of this document, one click each.
+
+---
+
+## 1. What M0 proved wrong in PLAN.md
+
+Six things, in the order they were found. Each is folded back into the design
+document; this is the evidence.
+
+| # | The design said | The measurement said |
+|---|---|---|
+| 0 | §6 — a stretch row carries a material stiffness `k_stretch` | A *penalty* stiffer than about `8·(m/h²)` makes the step **add** energy — measured at +6.8 J on a sheet whose whole potential is 1.2 J — and no iteration count removes it. Cloth's stretch rows have to be hard. §6 below. |
+| 1 | §5.3 — an SPD Hessian means "no update can increase the local energy" | SPD buys a descent **direction**. A full Newton step of 1 overshoots and climbs where the model stops resembling the energy. §5.3 below. |
+| 2 | §5.2 — drop the geometric-stiffness term `fc·∂²C/∂x²` entirely | Its PSD half is what stops the update overshooting sideways. Keep it; the NSD half is still dropped. §5.1 |
+| 3 | §5.2 — the multiplier and the penalty band apply to every row | They apply only to **hard** rows. On a soft row the multiplier drives `C → 0` and makes a 1 kN/m spring 100× stiffer than Hooke. §3 |
+| 4 | §5.2 — `k_min` and `k_max` are stiffnesses | They are only meaningful as **ratios of the row's own `m/h²`** — the same ratio works across five decades of particle mass; a fixed stiffness does not. §4 |
+| 5 | §5.2 — the 3×3 solve "never fails" | The *cofactor* solve fails: a determinant of −4.8e8 on a matrix with eigenvalues 0.12, 0.12, 5.4e8. LDLᵀ does not. §5.2 |
+| 6 | §17 — under 2 ms per frame per character | **3.50 ms** best case, 4.42 ms median, for 1,024 particles at 2×4. Over by 1.75×. And gathering neighbours is *not* what dominates. §7 |
+
+A seventh is a gap rather than an error: §7 P5's jitter mechanism (`γ` decaying
+warm-started duals) only reaches hard rows, because a soft row has no multiplier
+to decay. §6.
+
+---
+
+## 2. The constants
+
+```
+α = 0.25   γ = 1   β = 1e5 (unexercised)   k_min = k_max = 8·(m/h²)
+```
+
+`cloth_solver_constants.js` carries them and says why. The short version:
+
+- **α and γ act only through their product.** At a fixed `α·γ` the answer does
+  not move at all between `γ = 0.3` and `γ = 1`. `γ` sits at 1 because its
+  second job — decaying the penalty — has nothing to do while the band is a
+  single point.
+- **`α·γ ≥ 0.5` diverges.** 0.25 is a factor of two clear.
+- **`k_min = k_max` disables the ramp**, which measured as good as any ramped
+  alternative for M0's persistent rows and removes a scale-dependence that a
+  live ramp reintroduces. The ramp exists for *transient* rows — a contact that
+  should arrive soft rather than shock the mesh on its first frame — and M0 has
+  none, so **β cannot be chosen from M0 data and M2 must measure it.**
+
+### α·γ against the penalty ceiling — 20-link hard chain
+
+Cells are `worst |C|/L₀` / `kinetic energy after 400 steps, J`. The kinetic
+column is the one to read: past `α·γ = 0.3` the chain stops settling long before
+it stops being finite.
+
+```
+k_max/(m/h²)          α·γ=0       α·γ=0.1       α·γ=0.2      α·γ=0.25       α·γ=0.3       α·γ=0.4       α·γ=0.5       α·γ=0.6
+1               3.6e-1/3e-7   3.1e-1/2e-7   2.8e-1/1e-7   2.6e-1/4e-7   2.4e-1/1e-6   2.2e-1/3e-6   1.7e-1/2e-3   8.5e-1/5e-3
+2              1.9e-1/1e-10  1.7e-1/2e-11  1.5e-1/3e-10   1.4e-1/2e-9  1.3e-1/5e-11   1.0e-1/1e-7   9.7e-2/3e-3      diverged
+4              1.0e-1/1e-13  9.1e-2/1e-13  7.9e-2/1e-12  7.3e-2/2e-12  6.7e-2/3e-12   5.7e-2/3e-7   2.8e-1/3e-2      diverged
+8              5.6e-2/2e-13  4.9e-2/3e-14  4.1e-2/3e-13  3.8e-2/1e-11   3.5e-2/2e-9   6.6e-2/3e-4      diverged      diverged
+16              4.9e-2/1e-5  2.5e-2/1e-10   2.1e-2/1e-6   4.1e-2/7e-5   3.3e-2/2e-4   2.7e-2/1e-3      diverged      diverged
+32              5.5e-2/5e-5   4.9e-2/5e-5   4.4e-2/4e-5   4.1e-2/4e-5   3.9e-2/4e-5   7.6e-2/1e-3      diverged      diverged
+128             7.0e-2/3e-4   6.4e-2/2e-4   5.9e-2/2e-4   5.7e-2/2e-4   5.5e-2/2e-4   5.0e-2/2e-4      diverged      diverged
+1024            1.3e-1/2e-3   7.3e-2/3e-4   7.6e-2/5e-4   7.3e-2/4e-4   7.1e-2/4e-4   6.6e-2/4e-4      diverged      diverged
+```
+
+---
+
+## 3. Soft rows must not carry a multiplier
+
+The first thing the sweep established, and it reshaped everything after it.
+
+A row whose material stiffness is finite is representable as a plain penalty,
+and **a plain penalty at the material stiffness is the material law**. There is
+nothing for a multiplier to add, and adding one anyway is not a small error:
+`λ ← λ + k·C` is an augmented Lagrangian on the equality `C = 0`, so it drives
+`C` to zero whatever `k` is. A 0.05 kg mass on a 1 kN/m spring, whose analytic
+extension is 0.49 mm, settled at **4.8 µm — a hundred times stiffer than it was
+authored as.**
+
+The fix is that a row is **hard** exactly when its stiffness is `Infinity`,
+which makes §6's table literal rather than introducing a threshold. A hard row
+gets the augmented Lagrangian; a soft row is a pure penalty and carries no
+multiplier. Afterwards a soft row reads exactly Hooke, and reads it whatever the
+five constants are doing:
+
+```
+  chosen       extension/Hooke = 1.0000
+  α=0          extension/Hooke = 1.0000
+  α=1 γ=1      extension/Hooke = 1.0000
+  β=0          extension/Hooke = 1.0000
+  band ×1024   extension/Hooke = 1.0000
+```
+
+That insensitivity is what makes α, β, γ and the band honest as *global* solver
+internals rather than things an author would eventually have to reach for.
+
+### What the multiplier actually buys
+
+Not a smaller residual. Measured across chain depths of 5 to 40 and stiffnesses
+from 1e2 to 1e9 at the same budget, a hard row and a stiff penalty give
+comparable `|C|/L₀`, and which wins depends on the phase of the oscillation the
+snapshot catches. What it buys is **settling**: a hard 20-link chain comes to
+rest at 1e-14 J where the same chain on a penalty of any stiffness sits in a
+limit cycle at 1e-4 J. Ten orders of magnitude, and it is §7 P5 rather than P2.
+
+---
+
+## 4. The penalty band is a ratio, not a stiffness
+
+Same 20-link hard chain, `α·γ = 0.25`, with `k_max` held at a fixed **multiple**
+of the row's own `m/h²` while the particle mass moves across five decades. The
+residual column repeats exactly; against a fixed stiffness in N/m it does not.
+
+```
+mass (kg)     m/h²          ×0.3            ×1            ×2            ×4            ×8           ×16           ×64          ×256
+5e-6        7.2e-2   7.4e-1/4e-6   2.6e-1/4e-9  1.4e-1/2e-11  7.3e-2/2e-14  3.8e-2/1e-13   4.1e-2/7e-7   4.8e-2/1e-6   6.5e-2/3e-6
+5e-4        7.2e+0   7.4e-1/4e-4   2.6e-1/4e-7   1.4e-1/2e-9  7.3e-2/2e-12  3.8e-2/1e-11   4.1e-2/7e-5   4.8e-2/1e-4   6.5e-2/3e-4
+5e-2        7.2e+2   7.4e-1/4e-2   2.6e-1/4e-5   1.4e-1/2e-7  7.3e-2/2e-10   3.8e-2/1e-9   4.1e-2/7e-3   4.8e-2/1e-2   6.5e-2/3e-2
+5e+0        7.2e+4   7.4e-1/4e+0   2.6e-1/4e-3   1.4e-1/2e-5   7.3e-2/2e-8   3.8e-2/2e-7   4.1e-2/7e-1   4.8e-2/1e+0   6.5e-2/3e+0
+```
+
+§5.2's own prose already names `k_max/(m/h²)` as the quantity that matters. It
+stopped one step short of making the ratio the parameter.
+
+The optimum is ×8: below it the row is too soft to converge, above it the chain
+stops settling (the kinetic column climbs by four orders of magnitude between
+×8 and ×16). The row's scale is its **effective** inertia along the constraint,
+`1/((wᵢ + wⱼ)·h²)`, so a row with one pinned end sees the free particle's own
+`m/h²` and an interior row sees half of it.
+
+---
+
+## 5. The vertex update
+
+### 5.1 The geometric-stiffness term, half of it
+
+For a distance row `∂²C/∂x² = (I − g gᵀ)/L`, which is positive semidefinite
+exactly when the row is in tension. Dropping the whole term — §5.2's
+instruction — leaves `H` underestimating the curvature perpendicular to the row
+by `fc/L`, so the update overshoots sideways once that passes the mass term.
+One free particle between two anchors, stepping the tension up:
+
+```
+  m/h²         fc/L        ratio    ΔE/E with the term dropped   with its PSD half kept
+  1.44e+2   1.06e+2     7.33e-1                        −65.6%                   −62.9%
+  1.44e+2   5.53e+2     3.84e+0                        +21.9%                   −30.1%
+  1.44e+2   5.53e+4     3.84e+2                        +80.8%                   −33.9%
+  1.44e+2   1.45e+6     1.01e+4                       +718.0%                   −22.6%
+  1.44e+2   9.94e+6     6.90e+4                      +4140.0%                   −19.1%
+```
+
+The crossover is exactly where the theory puts it, at `fc/L ≈ m/h²`. Keeping the
+PSD half costs nothing structurally: every term in `H` is still positive
+semidefinite on top of a positive definite mass term, so the SPD-by-construction
+argument is intact and there is still no threshold. The compression half stays
+dropped, and dropping it there is conservative — it makes the step shorter than
+Newton, not longer.
+
+The term is added whether or not the row is at a clamp. A saturated row applies
+a force of constant *magnitude*, but that force still swings as the row rotates,
+so its geometric curvature is real even though its penalty curvature is gone.
+
+### 5.2 LDLᵀ, not a cofactor inverse
+
+The two agree in exact arithmetic. In `Float64` they do not. A vertex carrying
+one very stiff row against a small mass term assembles
+
+```
+  H = [[1.7099e+8, −2.1651e+8,  1.2729e+8],
+       [         ,  2.7415e+8, −1.6118e+8],
+       [         ,           ,  9.4759e+7]]
+
+  eigenvalues 1.198e−1, 1.198e−1, 5.399e+8   (all positive; condition 4.5e9)
+  true determinant                7.752e+6
+  cofactor determinant           −4.828e+8     ← wrong sign
+  LDLᵀ pivots     1.710e+8, 3.120e−1, 1.453e−1  (product 7.752e+6, exact)
+```
+
+The determinant is a sum of triple products that has to cancel by the condition
+number squared; the factorisation never forms them. The dev-build assertion
+checks the three pivots, which *is* positive definiteness rather than a proxy
+for it, and it held across every update in the fuzz.
+
+### 5.3 A descent direction is not a monotone step
+
+`Δ = H⁻¹f` with `H` positive definite gives `f·Δ = fᵀH⁻¹f > 0`. That guarantees
+the energy falls for a *small enough* step. The update takes a full step of 1,
+and where the quadratic model stops resembling the energy, a full step climbs.
+Walking one such step:
+
+```
+  t          E(x₀ + t·Δ)          ΔE
+  0        −1.9122412072e+7    0
+  1e−9     −1.9122412098e+7   −2.6e−2      falling
+  1e−7     −1.9122414636e+7   −2.6e+0      falling
+  1e−5     −1.9122668457e+7   −2.6e+2      falling
+  1e−3     −1.9133645206e+7   −1.1e+4      falling — this is the minimum
+  1e−2     −1.8901856618e+7   +2.2e+5      past it
+  0.5      −3.1478025715e+6   +1.6e+7
+  1        +1.9273328443e+7   +3.8e+7      the step the solver takes
+```
+
+The direction is right; the length is a thousand times too long. So the step is
+capped at the **shortest row incident on the particle** — the distance over
+which "the direction to a neighbour" means anything. That radius is the mesh's
+own geometry rather than a tuned constant, it is already in hand from the
+accumulation, and for cloth in any ordinary motion it never binds.
+
+With all three corrections in place:
+
+| | fraction of updates that climb | worst, relative to the local energy scale |
+|---|---|---|
+| realistic cape, hard rows | 0.0040% | 8.6e−2 |
+| realistic cape, soft rows | 0.0041% | 1.5e−1 |
+| absurd fuzz, 3.0M updates | 1.52% | 1.00 |
+
+Those are the thresholds the standing gate in `cloth_solve_vertex.spec.js` holds
+the solver to.
+
+---
+
+## 6. Settling, and the gap in P5
+
+At the chosen constants a **hard** chain settles hard: a 20-link chain reaches
+1e-11 J and an 80-link one 1e-9 J, and the residual falls monotonically with the
+iteration budget with nothing diverging at any depth.
+
+```
+iterations           n=1           n=2           n=5          n=10          n=20          n=40          n=80
+1            3.2e-3/0e+0  6.4e-3/1e-16   4.6e-2/3e-5   9.5e-2/6e-7   1.3e-1/2e-3   1.2e+0/2e-2   9.6e-1/3e-1
+2            3.2e-4/0e+0   4.2e-3/0e+0  1.4e-2/2e-16   3.4e-2/1e-6   1.4e-1/6e-4   1.2e-1/7e-3   8.9e-1/1e-2
+4            3.9e-6/0e+0   4.1e-4/0e+0  6.8e-3/1e-16  1.7e-2/2e-15  3.8e-2/1e-11   9.0e-2/3e-5   1.4e-1/7e-3
+8            0.0e+0/0e+0  2.9e-5/1e-17  1.7e-3/1e-16  7.2e-3/1e-15  1.7e-2/9e-14  3.8e-2/8e-13   8.0e-2/1e-4
+16           0.0e+0/0e+0   2.8e-7/0e+0  4.1e-4/5e-16  2.1e-3/1e-15  6.9e-3/3e-14  1.6e-2/2e-13  3.6e-2/9e-10
+```
+
+A **soft** row above a certain stiffness does not settle at all, and the reason
+is worse than "nothing is damping it".
+
+The threshold is the same ratio §4 turns up: **`k/(m/h²)`**. Below about 8 the
+step is dissipative and the cloth comes to rest; above it the cloth sustains a
+limit cycle for as long as you run it. Measured on a 16×20 sheet, 0.3 kg, hung
+from the top edge at 60 Hz × 2 substeps × 4 iterations, over 1,500 steps:
+
+```
+  row                       k/(m/h²)     final kinetic energy
+  hard (AL, k pinned at ×8)        8                 1.9e-12 J     settles
+  soft, 1e2 N/m                  7.4                 7.4e-09 J     settles
+  soft, 1e3 N/m                   74                 1.9e-02 J     does not
+  soft, 1e4 N/m                  740                 7.4e-03 J     does not
+  soft, 1e5 N/m                 7400                 2.9e-02 J     does not
+  soft, 1e4 at 16 iterations     740                 3.3e-03 J     does not
+  soft, 1e4 at 8 substeps        740                 1.4e-03 J     does not
+```
+
+More iterations and more substeps shrink it; neither removes it.
+
+And the step is **adding energy**, not merely failing to remove it. Tracking the
+full mechanical energy — kinetic plus gravitational plus elastic — from the rest
+configuration:
+
+```
+  soft 1e2 (ratio 7)     −0.016 J, and flat from step 300 onwards      dissipative
+  soft 1e4 (ratio 740)   +6.8 J, wandering between +1 and +7 J        creating it
+```
+
+For scale, that sheet's entire gravitational potential over its own length is
+about 1.2 J, so at ratio 740 the solve manufactures several times the whole
+system's energy budget and then holds it there. It stays bounded — the SPD
+Hessian and the trust region cap every individual step — but bounded is not
+rest.
+
+Two consequences.
+
+**§7 P5's mechanism covers hard rows only.** `γ` decays a multiplier and a soft
+row has none, so no value of any solver constant reaches this. What does reach
+it is `ClothDynamics#damping`, which arrives with the component in M1 — which
+means damping is load-bearing for P5 rather than a taste control, and M1's spec
+has to gate on a soft cloth actually settling.
+
+**§6's assignment of stretch to a soft material stiffness does not survive.**
+Real fabric wants a stretch stiffness far above `8·(m/h²)` — for a half-gram
+particle at 60 Hz × 2 substeps that boundary is around 60 N/m, which is a rubber
+band, not a fabric. So a cloth's stretch rows have to be **hard**, and the
+augmented Lagrangian is not an optional refinement over a stiff penalty: it is
+the only formulation of that row that rests. That is the same conclusion §3
+reaches from the other direction, and it is why the playground defaults to hard
+rows.
+
+### Iteration-count insensitivity
+
+§5.1 claims that adding iterations converges towards the *same* answer rather
+than changing which answer it is. On the cape (20×30 at 2 cm, inextensible, hung
+from its top edge and dropped through 90°), the hem across the budget:
+
+```
+  iterations= 1  hem=−0.6450 m  residual=7.2e-1
+  iterations= 2  hem=−0.6201 m  residual=2.0e-1
+  iterations= 4  hem=−0.5993 m  residual=7.5e-2
+  iterations= 8  hem=−0.5466 m  residual=7.2e-2
+  iterations=16  hem=−0.5626 m  residual=1.4e-2
+  iterations=32  hem=−0.5459 m  residual=8.0e-3
+```
+
+The sheet is 0.58 m long, so the answer moves 18% of its own length between 1
+iteration and 32, and the residual moves by two orders of magnitude. The claim
+holds in the sense that matters — the answer converges rather than changing
+character, and one iteration is stable rather than broken — but "insensitive" is
+too strong for a mesh 30 rows deep at this budget. §7 P2's tether row is what
+closes that gap, and it lands in M1.
+
+### Hostile regimes
+
+All eight survive at the chosen constants.
+
+```
+  stiff + 5 fps       ok    1 kg particles on 1e8 N/m rows, 1 substep, 1 iteration
+  light + 240 fps     ok    10 mg particles, 4 substeps, 8 iterations
+  10 m spacing        ok    a 6×6 sheet with 10 m between particles at 15 fps
+  a thousand g        ok    gravity at −9810 m/s²
+  soft as water       ok    1e−2 N/m rows (sags 123 m, which is correct)
+  zero g, 100 m/s     ok    no gravity, particles thrown at 100 m/s
+  inextensible        ok    stiffness Infinity
+  inextensible cape   ok    600 particles, stiffness Infinity
+```
+
+---
+
+## 7. The performance budget
+
+§17 budgets **under 2 ms per frame per character**, for about 1,000 particles at
+2 substeps × 4 iterations, and says the figure is an estimate to be replaced by
+a measurement. Replaced:
+
+```
+# 1024 particles (32×32 patch at 2 cm, 0.5 kg), 2 substeps × 4 iterations
+# 2945 stretch rows, 2821 bend rows, 4 colours, 370.4 KiB of state
+# 8192 vertex updates per frame, 16.8 row incidences per particle
+# Node v24.15.0 on win32/x64, 1200 warm-up frames then 1500 measured, 4 rounds
+
+  round minima   3.504  3.506  3.644  3.484        best 3.48 ms, spread ±5%
+```
+
+**3.48 ms against a 2.000 ms budget — over by 1.74×**, and 3.55 ms when the
+benchmark runs the same configuration alongside its four variants. The minimum is the
+headline because it is what varies least between runs; a cloth's median moves by
+a factor of two depending on whether it is still swinging, and the mean and p95
+move with whatever else the machine is doing.
+
+### What the frame is made of
+
+Deleting the workload piece by piece, all five variants in one run so the
+comparison is internally consistent:
+
+```
+variant                          MIN ms   median      share of the frame
+everything                        3.552    5.023
+no bend rows                      2.688    3.267      bend rows    0.864 ms  24.3%
+no stretch rows                   1.133    2.055      stretch rows 2.419 ms  68.1%
+no rows at all                    0.253    0.490      everything else       7.1%
+shuffled within each colour       3.563    4.771      locality              +0.3%
+```
+
+The rows are the frame; predict, warm start, the dual updates and integrate
+together are 7% of it, and the cost is close to linear in both particles and
+sweeps. The split between the two row kinds moves by a few points between runs
+— bend read 18% in one run and 24% in another — so treat it as "stretch is most
+of it, bend is most of the rest".
+
+Two things this table does **not** license, and an earlier draft of this
+document claimed both.
+
+It does not say a stretch row costs four times what a bend row costs *per
+visit*. The three variants are in different physical states — a cloth with no
+stretch rows is in free fall rather than draping — so the split measures what
+each row kind *causes* in a running step, not the arithmetic in its accumulate.
+
+And it does not license attributing the stretch share to any particular part of
+that accumulate. See below.
+
+### A warning, because M2, M4 and M5 are told to re-measure
+
+**An isolated loop over one accumulate measures the wrong workload.** Without
+`predict` and `integrate` around it, the solve converges after a few passes and
+the positions stop changing; from then on the loop reads a static array with
+perfectly predictable branches, and every number it produces is of a cloth that
+has stopped moving.
+
+The size of the error, measured both ways on the same mesh:
+
+```
+                        isolated loop        by deletion, in the running step
+  bend accumulate       0.72 ms              0.70 ms          agree
+  stretch accumulate    0.47 ms              2.64 ms          disagree, 5.6×
+  both                  1.19 ms              3.34 ms
+```
+
+Bend agrees; stretch does not, and the gap is most of the frame. The dev-build
+assertion machinery is not the explanation — the non-finite tripwire and the
+pivot assertion's message together are 0.118 ms, 3.4% of the step. Nor is it
+`cloth_solve_vertex`'s own arithmetic: the eight colour sweeps called exactly as
+`cloth_step` calls them come to 1.88 ms, and driven on their own — with no
+predict to disturb the cloth — they too are measuring a converged mesh.
+
+The honest statement is that **only the end-to-end figures here are
+trustworthy**, and the per-row breakdown an earlier draft gave has been removed
+rather than reconciled. Whoever re-measures at M2 should keep the whole step
+running and vary one thing at a time.
+
+### Gathering neighbours is not what dominates
+
+§17 predicted it would. The controlled test is to **move every particle to a
+different slot inside its own colour range**. The colouring is untouched — a
+particle's colour *is* which range it sits in, and every particle stays in its
+own — so the sweep does the same work in the same order over the same rows with
+the same branches, and the only thing that moves is the address each particle
+lives at.
+
+The control is exact, and checkably so: the reference cloth and the shuffled one
+produce **bit-identical** trajectories, agreeing on the hem position to six
+decimals and on kinetic energy to five significant figures after 200 steps.
+
+```
+  1024 particles, 370 KiB of state    +0.3%
+```
+
+Destroying within-colour locality entirely costs nothing measurable at the size
+§17 budgets for — the whole state fits in L2 — so **§17's "gathering neighbour
+positions is what will actually dominate" is wrong**, and there is no
+memory-layout optimisation to win here. Whether that survives at four times the
+size is *not* measured: a cruder probe suggested around 11% at 4,096 particles,
+but that probe relabelled the source vertices, which also changed the greedy
+colouring from four colours to ten, so it is not quotable.
+
+Two earlier drafts got this wrong before this one got it right. The first used a
+variant labelled "mesh order, not colour order" that did nothing of the kind —
+it left the particles in colour-permuted storage and merely collapsed the colour
+loop. The second relabelled the source numbering, which moves the particles but
+changes the colouring with them. Only shuffling *within* a colour isolates the
+one variable, and it was worth three attempts because this is the number that
+contradicts the plan.
+
+### Scaling, and what fits
+
+Four rounds each, so the spread is the figure's real precision:
+
+```
+  config                              round minima            best   spread
+  1024 @ 2×4  (the §17 workload)      3.504 3.506 3.644 3.484   3.48   ±5%
+  1024 @ 2×2  (half the iterations)   1.700 1.713 1.695 1.716   1.69   ±1%   inside
+  1024 @ 1×4  (half the substeps)     1.683 1.734 1.765 1.703   1.68   ±5%   inside
+   484 @ 2×4  (half the particles)    1.543 1.586 1.595 1.605   1.54   ±4%   inside
+   256 @ 2×4                          0.792 0.804 0.791 0.785   0.79   ±2%   inside
+```
+
+§18's levers, priced:
+
+| Lever | Result |
+|---|---|
+| Fewer iterations — "safe, the solver is stable at one" | 1,024 particles at 2×2: **1.69 ms**, comfortably inside |
+| Fewer particles in the proxy | ~500 particles at the full 2×4: **1.54 ms** |
+| Fewer substeps | 1,024 at 1×4: **1.68 ms** |
+| The barycentric binding fallback (§11.2) | not needed to reach the budget |
+
+Any one lever is enough on its own, and they compose. What the budget is *not*
+reachable at is 1,000 particles at 2×4, which is the figure §17 wrote down.
+
+**Note what the worker does not do.** §12 moves this off the main thread; it does
+not make it cheaper. "2 ms on the worker" with several characters in flight is a
+scheduling question this measurement does not answer.
+
+## 8. Topology note
+
+The benchmark's 32×32 patch carries **16.8 row incidences per particle** against
+§17's "about a dozen". That is the honest number for a triangulated sheet with a
+stretch row per edge — including the quad diagonals — and a quadratic bend row
+per interior edge, and it makes this measurement about 40% conservative against
+the workload §17 imagined. A proxy that dropped the diagonals, or used a
+quad-dominant mesh, would carry fewer.
+
+---
+
+# Cloth — M1 measurements
+
+> Written 2026-09-10, against the M1 implementation in `ecs/`. Everything above
+> this line is M0's and unchanged.
+>
+> Two scripts, both runnable directly under node — the M0 note applies unchanged,
+> and for the same reason:
+>
+> ```
+> node src/engine/physics/cloth/ecs/__fixtures__/cloth_m1_measure.mjs
+> node src/engine/physics/cloth/ecs/__fixtures__/cloth_library_bench.mjs
+> ```
+>
+> And a second playground page, `playground/rig.html`, which is the entity
+> subtree rather than the solver: a real `EntityManager`, real entities, and
+> `ClothSystem` walking and writing back.
+
+---
+
+## 9. What M1 proved wrong in PLAN.md
+
+Six things, and the first three are sign and scale errors in §6 and §7 that the
+implementation could not have been written around.
+
+| # | The design said | The measurement said |
+|---|---|---|
+| 0 | §6 — slack, tether and strain-limit rows clamp to `(−∞, 0]` | Under the solver's own `f -= fc·g` that is the force which pushes a distance row **apart**. A row bounding a distance from *above* needs `[0, +∞)`, and with the table's clamp it never binds at all. §10 |
+| 1 | §3.4 — the leash radius is `slack · d_geo,i` | That makes `slack = 1` a real constraint: a rope hanging straight down cannot swing through 90°, because its tip would move `√2·d_geo`. `2·d_geo` is *provably* inactive given the tether, so the map is `2·slack·d_geo`. §10 |
+| 2 | §7 P1 — the velocity clamp is derived from `thickness` and `h` | `thickness` is a contact radius, so a clamp built from it is a **tunnelling** bound, and a tunnelling bound sits below ordinary cloth speeds: silk at 4 mm gives 0.24 m/s against a measured 29 m/s. The scale that works is the solver's own correction authority. §13 |
+| 3 | §11.1 — "bend rows along each chain" | A chain has no diamond to build a quadratic hinge stencil on. A **skip row** — an ordinary stretch row to the grandparent — costs no new row kind and holds a curved rest shape the quadratic stencil explicitly cannot. §11 |
+| 4 | §17 — the levers each close the 2 ms budget on their own | M1's rows changed the arithmetic. 1,024 particles at 2×4 is **4.61 ms**, not M0's 3.41, and **no single lever reaches 2 ms**. Every garment entry spends two. §14 |
+| 5 | §6 — a strain-limit row governs how far the fabric may extend | It removes about a third of the peak over-stretch at every budget and **never reaches its own allowance** — at `stretch = 1` it asks for 0.1% and delivers 5.9% at 1×1. `ClothDynamics#stretch` is the weakest field in the parameter set. §11 |
+| 6 | §11.1 — the write-back writes `Transform64` | It has to write the **local** `TransformAttachment#transform` too. Writing only the world one leaves the pose one announcement away from being replaced by the authored one, which makes where cloth runs a correctness question; writing both makes a recomposition reproduce it to 1.7e-15 m. §15 |
+
+And one thing §4.1 flagged as possibly impossible, which turned out to be
+exactly that: **neither of the engine's two ordering mechanisms can place cloth
+after a poser**, for a structural reason rather than an arithmetic one. What M1
+ships is not a third mechanism — it is a write-back that does not need one. §15.
+
+---
+
+## 10. The leash: tether, slack, and the bound that is not unconditional
+
+### The tether is what makes a low budget viable
+
+A 30-link × 3-strand rig at 5 cm, authored horizontally and dropped through
+ninety degrees, `worst max(‖x − p_anchor‖ / d_geo)` over 600 steps:
+
+```
+  budget      tethered     no tether
+  1x1           1.0155        1.4650
+  1x2           1.0039        1.1899
+  2x2           1.0020        1.0568
+  2x4           1.0012        1.0199
+```
+
+That is §7 P2's claim with a number on it. At one iteration per substep the
+untethered rig reaches **half again its own length** — the rubber cape — and the
+tethered one is inside 1.6%. Note the second column at 2×4: four times the
+budget gets the untethered rig to 1.020, which is still worse than one iteration
+*with* tethers. The tether is not a cheaper way to buy convergence; it answers a
+question the per-edge rows cannot, because a per-edge force travels one hop per
+iteration and a long-range row does not travel at all.
+
+### The clamp direction, which §6 has backwards
+
+The solver applies `f -= fc·g`, so a **positive** `fc` on a distance row pulls
+its two ends together — that is what `cloth_stretch_row.js` means when it adds
+geometric stiffness for a row "in tension" at `fc > 0`. A row that bounds a
+distance from above must therefore admit positive force and no negative force.
+
+§6's table gives Slack, Tether and Strain limit `f_min = −∞, f_max = 0`, which
+admits only the force that pushes the two ends apart. Such a row does not bind
+weakly; it never binds at all, and it would drive a particle *away* from its
+leash centre. The table's collision and self-collision rows are consistent with
+the correct rule once you notice that the collision row writes `C` with the
+opposite sense, so the fix is one column in three rows plus the gloss above it:
+"`[0, +∞)` is push-only, `(−∞, 0]` is pull-only" is only true relative to a
+particular sign of `C`. The exact rule is **`[0, +∞)` admits only forces that
+reduce `C`, and `(−∞, 0]` only forces that increase it.**
+
+`cloth_leash_row.spec.js` demonstrates it directly: a particle five metres out
+on a two-metre leash assembles `f = (−30, 0, 0)`, and under §6's clamp that is
+clamped to zero.
+
+### `slack = 1` was a constraint, and should not have been
+
+§3.4 sets each particle's leash radius to `slack · d_geo,i`, and says `slack = 1`
+means "a particle may be anywhere within its own reach of its animated
+position". It does mean that, and that is a real bound: a rope hanging straight
+down cannot swing through ninety degrees, because its tip has to move `√2·d_geo`
+to get there and its leash is `d_geo`.
+
+The radius at which the row is provably inert is `2·d_geo`, and the proof is two
+lines. The tether already holds every particle within `d_geo` of the anchor; the
+animated position it is leashed to is also within `d_geo` of the anchor, since a
+chord is never longer than the arc it subtends; so by the triangle inequality the
+two are never more than `2·d_geo` apart. `r_i = 2·slack·d_geo,i` therefore makes
+`slack = 1` mean exactly "no leash", with no sentinel value and no
+discontinuity — the row is simply not built, because a row that cannot bind is
+not worth visiting.
+
+### The bound is conditional on the solver's correction authority
+
+The trust region caps each vertex update at the shortest row incident on the
+particle (§5.3), so one fixed step can move a particle at most
+`shortest_row · substeps · iterations`. Past that, a bound is not being violated
+so much as not being given a chance to act. The same rig, kicked sideways:
+
+```
+  budget   kick      correction authority     worst    final
+  1x1      2 m/s     3.0 m/s                  1.043   1.0025
+  1x1      6 m/s     3.0 m/s                  1.227   1.0025
+  1x1     16 m/s     3.0 m/s                  6.867   1.0025
+  2x4      2 m/s    24.0 m/s                  1.003   1.0000
+  2x4      6 m/s    24.0 m/s                  1.001   1.0000
+  2x4     16 m/s    24.0 m/s                  1.063   1.0000
+```
+
+A kick five times the authority reaches **6.9× the cloth's own reach**; the same
+kick against eight times the authority reaches 1.06×. The excursion is transient
+in every case — the final column is the reachable-set guarantee of §7 P4(c)
+holding, error not accumulating — but "no particle is ever further from the
+anchor than `d_geo`" is not true as stated, and §7 P2 should say what it is
+conditional on.
+
+This is also where M1's velocity clamp comes from. §13.
+
+---
+
+## 11. The strain limit, and what `stretch` is worth
+
+A 24-link rope at 5 cm, authored horizontally and dropped, `worst max(link
+length / rest length)` over 600 steps. "Allowance" is what
+`cloth_strain_allowance(stretch)` asks for:
+
+```
+  budget   stretch   allowance   with the row   without it
+  1x1        0.2        1.0829         1.0863       1.0922
+  1x1        0.5        1.0158         1.0631       1.0922
+  1x1        1.0        1.0010         1.0586       1.0922
+  2x2        0.2        1.0829         1.0351       1.0351
+  2x2        0.5        1.0158         1.0289       1.0351
+  2x2        1.0        1.0010         1.0216       1.0351
+  2x4        0.2        1.0829         1.0140       1.0140
+  2x4        0.5        1.0158         1.0140       1.0140
+  2x4        1.0        1.0010         1.0094       1.0140
+```
+
+Two readings, and the second is the important one.
+
+**The row works**: it removes 34–38% of the peak over-stretch, consistently, at
+every budget. On a chain that costs nothing measurable and it is worth having.
+
+**And it does not do what §6 says it does.** At `stretch = 1` it asks for 0.1%
+of strain and delivers 5.9% at 1×1 — a factor of fifty out. The reason is
+structural rather than a tuning failure: a strain-limit row is a *second hard
+row on the same edge with the same gradient*, so it competes for the same trust
+region and the same penalty band as the fabric row it is backing up. It can add
+force in a direction force is already being added in, and nothing more.
+
+The consequence for the parameter set is that **`stretch` is a weak control over
+most of its range**. Below about `stretch = 0.35` its allowance is looser than
+what a hard row does unaided and the row is inert — see the 0.2 rows, where
+adding it changes nothing at 2×2 and 2×4. Above it the row helps but cannot
+reach what it was asked for. The library says so by which entries set
+`ClothDynamicsFlags.StrainLimit`: the ones at 2×4, where the residual is already
+around 1%, clear it; the ones at 2×2 and the chains keep it.
+
+---
+
+## 12. Settling, sleep, and the damping gate
+
+### Every library fabric settles and sleeps
+
+A 12-link chain at 8 cm, set swinging at 3 m/s, run until the sleep test fires
+(30 consecutive steps with no particle faster than `1e-3 · reach` per second):
+
+```
+  SILK      770 steps      ROPE      501
+  COTTON    438            CHAIN     285
+  DENIM     220            HAIR      295
+  LEATHER   238
+```
+
+Twelve seconds at the slowest, and the order is the damping order, which is what
+it should be. Sleep stops the step **and the write-back**, which is what makes
+§7 P5's "bit-identical across the following 300 steps" a fact rather than a
+hope: a pose that is not rewritten cannot drift, and one that is rewritten from
+unchanged inputs is only probably identical.
+
+### Damping is load-bearing, and here is the size of it
+
+`MEASUREMENTS.md` §6 measured that a **soft** row above about `8·(m/h²)` makes
+the step add energy, and that no solver constant reaches it because `α·γ` decays
+a multiplier and a soft row has none. M1's mapping never produces such a cloth —
+`stretch` maps to `Infinity` precisely because of that measurement — so the row
+stiffness is written in by hand to reproduce it. A 16-link rope at 5 cm with its
+stretch rows forced to 1e5 N/m, a ratio of about 350 against the particle's
+`m/h²` of 288, after 1,500 steps:
+
+```
+  damping        kinetic energy
+  0                    2.90e-03 J     the limit cycle
+  0.02                 6.18e-05 J
+  0.05                 2.39e-05 J
+  0.12                 1.28e-06 J     the library's own value
+  0.3                  7.30e-11 J
+  1                    1.82e-12 J
+```
+
+Three orders of magnitude between undamped and the library default, and seven at
+the top of the range. Note what damping does *not* do: it does not stop the step
+adding energy, it removes energy faster than the step adds it. The equilibrium
+is bounded rather than zero, which is why the numbers keep falling all the way
+to `damping = 1` instead of hitting a floor.
+
+---
+
+## 13. Teleport, locomotion, and where the velocity clamp comes from
+
+### Teleport
+
+A 16-link rope at 10 cm, swinging on an anchor that has been moving, then
+teleported a kilometre:
+
+```
+  mode    teleports   peak speed   first-step local shift   tip
+  Reset       1          0.000 m/s              1.4890 m    (1000.000, −1.600)
+  Keep        1          5.582 m/s              0.0779 m    (1000.003, −1.600)
+```
+
+`Reset` re-seeds at the animated pose with zero velocity and the stabilisation
+window ramps the velocity limit back from nothing over 20 steps; the peak speed
+of exactly zero is what a rope authored hanging straight down does when it is
+put back exactly there. `Keep` carries the shape across: the first-step shift is
+one step of ordinary motion, against a metre and a half for the reset, and the
+peak of 5.6 m/s is the swing it was already carrying.
+
+**`Keep` is free, and that is a property of the frame rather than a
+coincidence.** MagicaCloth2's `Keep` applies the anchor delta rigidly to every
+particle; in a frame anchored to the cloth's own entity the particles are
+already anchor-relative, so "apply the delta" is doing nothing at all. The
+implementation of `ClothFlags.TeleportKeep` is a `return`.
+
+### Fast locomotion
+
+20 links at 10 cm, the anchor running a square wave in velocity — sprint, stop
+dead, sprint back, stop dead, one second a phase, fifteen seconds. "Peak" is the
+fastest particle in the cloth-local frame, which is what the clamp bounds:
+
+```
+  entry      peak        clamp     headroom   teleports   worst tether
+  SILK      29.32 m/s   192.0 m/s     6.5x        0          1.0000
+  COTTON    13.97       192.0        13.7        0          0.9999
+  DENIM     13.29        96.0         7.2        0          1.0035
+  LEATHER   16.80        96.0         5.7        0          1.0018
+  ROPE      13.11       192.0        14.6        0          1.0004
+  CHAIN     11.32       288.0        25.4        0          1.0003
+  HAIR      13.19       192.0        14.6        0          0.9996
+```
+
+Nothing teleports — a sprint is locomotion and the threshold knows it — nothing
+leaves its own reach by more than 0.35%, and the smallest headroom over the
+clamp in the whole library is 5.7×.
+
+### Why the clamp is not derived from `thickness`
+
+§7 P1 asks for a "per-particle velocity clamp derived from `thickness` and `h`",
+and the table above is why that cannot be M1's clamp. `thickness` is a contact
+radius. A clamp built from it answers "may a swept contact still catch this
+particle", and the answer to that sits *below* ordinary cloth speeds rather than
+above them: silk is 4 mm thick, so at 60 Hz one radius per step is 0.24 m/s
+against the 29.3 m/s the same silk reaches behind a sprinter. Any multiple large
+enough to stop the clamp being a *behaviour* for silk is large enough to be
+meaningless for leather, whose thickness is five times silk's and whose speeds
+are not.
+
+The scale that does work is the solver's own **correction authority**,
+`shortest_row · substeps · iterations / dt` — the quantity §10 measured a cloth
+losing its bound past. A clamp at four times it is a bound on the solver being
+asked to do more than it can, it scales with the mesh and the budget rather than
+with a radius nothing reads until M2, and the headroom column above says it is a
+backstop rather than a behaviour. M2 still needs the tunnelling bound; it is a
+different number for a different job and it arrives with the contacts.
+
+### Inertia
+
+The same profile, 10 links, measuring how far the tip lags the anchor:
+
+```
+  inertia 0      0.0000 m       welded into the anchor frame
+  inertia 0.25   0.2031 m
+  inertia 0.5    0.3681 m
+  inertia 0.75   0.5249 m
+  inertia 1      0.6522 m       feels all of it
+```
+
+Monotone, and zero at zero to the last digit — a cloth that feels none of its
+anchor's motion hangs from a sprinting anchor exactly as it would from a
+stationary one, which is what makes `inertia` a dial rather than a switch with a
+meaningless middle.
+
+---
+
+## 14. The performance budget, again
+
+M0 measured the §17 workload at 3.48 ms and priced three levers that each closed
+it. **M1 added rows, and the levers no longer close it.** A 32×32 sheet at 2 cm,
+2 substeps × 4 iterations, adding M1's rows one at a time to M0's:
+
+```
+  rows                     particles / stretch / bend / leash        best
+  M0 rows only             1024  2945  2821     0                  3.412 ms
+  + strain limit           1024  5890  2821     0                  4.145 ms
+  + tether                 1024  5890  2821   992                  4.505 ms
+  + slack                  1024  5890  2821  1984                  4.605 ms
+```
+
+The strain limit is the expensive one, at 0.73 ms — it doubles the stretch
+table, and §7 already said the stretch rows are 69% of the frame. The tether is
+0.36 ms and load-bearing. The slack row is 0.10 ms.
+
+Against that, the levers:
+
+```
+  config          with strain limit      without it
+  1024 @ 2x4      4.669 ms  OVER         4.146 ms  OVER
+  1024 @ 2x2      2.380     OVER         2.106     OVER
+  1024 @ 1x4      2.395     OVER         2.071     OVER
+  1024 @ 1x2      1.167     inside       1.030     inside
+   576 @ 2x2      1.280     inside       1.096     inside
+   484 @ 2x4      2.533     OVER         2.019     OVER
+   484 @ 2x2      1.093     inside       0.909     inside
+   400 @ 2x4      1.721     inside       1.493     inside
+   324 @ 2x4      1.400     inside       1.259     inside
+   256 @ 2x4      1.107     inside       0.959     inside
+```
+
+**No single lever reaches 2 ms.** M0's three — half the iterations, half the
+substeps, half the particles — land at 2.38, 2.40 and 2.53 respectively. Every
+one of them lands *inside* when a second lever is spent with it, and that is what
+the library ships:
+
+```
+  entry     budget   particles / stretch / bend / leash / colours     best
+  SILK       2x4      400  1121  1045   760  4                      1.488 ms
+  COTTON     2x4      400  1121  1045   760  4                      1.484 ms
+  DENIM      2x2      576  3266  1541  1104  4                      1.256 ms
+  LEATHER    2x2      576  3266  1541  1104  4                      1.248 ms
+  ROPE       2x4       41   119     0    40  3                      0.043 ms
+  CHAIN      2x6       41   119     0    40  3                      0.064 ms
+  HAIR       2x4      400  1121  1045   760  4                      1.429 ms
+```
+
+Node v24.15.0 on win32/x64, 600 warm-up frames then 900 measured, 3 rounds, the
+minimum of the minima. The M0 warning still applies and was heeded: each round
+builds a fresh cloth, because a benchmark that reuses a settled one measures a
+converged mesh.
+
+Two notes for whoever re-measures at M2. The 3.412 ms in the first table against
+M0's 3.48 for the same workload is the two harnesses agreeing to 2%, which is
+inside M0's own ±5% spread — the row counts and the topology are the same patch.
+And the unreconciled factor-of-five between deletion and isolated-loop
+attribution that §7 records is **not** resolved here; nothing in M1 re-opened it,
+and nothing here should be quoted as having settled it.
+
+---
+
+## 15. System ordering: not expressible, and not needed
+
+§4.1 named this as M1's to establish and admitted the honest possibility that it
+needs a mechanism the engine does not have. The first half is true. The second
+half was the wrong conclusion to draw from it.
+
+### Why neither mechanism reaches it
+
+The engine orders systems two ways: registration order, and what each system
+declares in `components_used`. `EntityManager#updateExecutionOrder` scores each
+system as a **sum** over the components it references, weighting `Create` above
+`Write` above `Read`, and sorts descending. A score can therefore only be
+*raised* by touching more components or touching them at a higher access level —
+so the only way to sort **later** is to touch strictly less than the system you
+have to follow, and a consumer of a posed hierarchy touches strictly more.
+
+Measured, with the real systems and a poser registered *first*:
+
+```
+  ClothSystem -> TransformAttachmentSystem -> PoserSystem
+```
+
+Registration order cannot rescue it, because ties break by registration and this
+is not a tie. Declaring less is not honestly available either — cloth reads
+`Cloth` to know which entities it owns, and `ClothExclude` and
+`TransformAttachment` to walk them.
+
+### What the declaration does buy
+
+Half of the ordering, and the half that is a real data dependency. Cloth **writes**
+`TransformAttachment#transform` and `TransformAttachmentSystem` **reads** it, so
+writer-before-reader puts cloth first and the attachment system publishes its
+result. That falls out of `components_used` with nothing else asked for, and it
+is the first line of the order above.
+
+### What M1 did about the other half
+
+**A first attempt added a third mechanism** — an execution-phase number on
+`System`, sorted ahead of the score, with a `PostPose` value that `ClothSystem`
+declared. It worked, and it was wrong twice over: it put the vocabulary of
+animation and posing into `engine/ecs`, a layer that has none, and it bought an
+ordering the design should not have needed. It is recorded here because the
+reasoning that produced it — "the relation is real, the scheduler cannot express
+it, therefore extend the scheduler" — is exactly the reasoning to be suspicious
+of.
+
+What ships instead removes the need. Cloth writes each node's **local**
+`TransformAttachment#transform` alongside its world `Transform64`, so a hierarchy
+recomposition reproduces the simulated pose instead of replacing it with the
+authored one:
+
+```
+  a full recomposition after the write-back moves the pose by   1.665e-15 m
+```
+
+(Compared over the matrix. The quaternion can come back **negated** —
+`multiplyTransforms` decomposes the matrix it just wrote, and `q` and `−q` name
+one rotation, so the sign is the decomposition's to choose. Worth knowing before
+writing any bit-identity assertion over a `Transform64`.)
+
+With that, where cloth runs is a quality question. Running before the poser means
+reading last step's anchor pose, so the **shape** is one fixed step stale; the
+**position** is not, because the attachment cascade carries the whole subtree
+rigidly with the anchor from cloth's own local transforms. A 16-link, 1.6 m rope,
+worst world-space difference per node between the two orderings:
+
+```
+  profile      61 steps   121 steps   240 steps   900 steps
+  walk  2.4 m/s   0.046 m     0.032 m     0.050 m     0.049 m
+  sprint  ±9 m/s  0.149 m     0.131 m     0.349 m     0.142 m
+```
+
+Three per cent of the cloth's own length under ordinary motion, up to a fifth of
+it at the sharpest velocity reversal a square wave produces, and **not
+accumulating** — the same figure after fifteen seconds as after two, because the
+leash and the tether bound the reachable set.
+
+**`InverseKinematicsSystem` is the same shape and reaches the same conclusion.**
+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.
+
+---