@woosh/meep-engine 3.21.0 → 3.22.0

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

@@ -0,0 +1,956 @@
+# Cloth — measurements
+
+> Two milestones, appended in order. §1–§8 are **M0**, the solver core; §9–§15
+> are **M1**, the component and the system. Nothing above a milestone boundary
+> is edited by the milestone below it — a measurement that turned out to be
+> incomplete is corrected by a later section saying so, not by a rewrite.
+
+---
+
+# 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.