@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -4909,3 +4909,396 @@ reached the block. A mutant that changes `θ` by a part in a thousand in one arm
 fails those two runs and no other. The extended cloth specs 10, unchanged. The whole physics suite
 with its slow, bench and extended specs (`--mode all`): 187 files and 1,898 tests, green,
 `cloth_pathology` among them. `check-types` 18 against a budget of 19.
+
+---
+
+## 67. The cloth-skirt example: a contact that arrives soft, and a self radius capped by the waistband
+
+The website's cloth-skirt example (`meep-website/examples-src/cloth-skirt`, engine 3.46.0, whose cloth
+code is this tree's) shows "a bunch of visible penetrations". This section is the replay that found
+them, the two mechanisms behind them, the fix that landed for one, and three candidates measured for the
+other. Scripts, raw logs and frame renders are in the session's scratchpad (`probes/`), named below.
+
+### The example, replayed headlessly
+
+`skirt_repro.probe.js` rebuilds the example through the real `ClothSystem`: the 64×13 circle skirt from
+`cloth_proxy_from_mesh` (832 particles, rows from 9.8 mm at the waistband to 54 mm at the hem), the
+mannequin's eleven cloth colliders driven by `rumba-track.json` at 60 Hz (thighs to 2.8 m/s, their tips
+to 4.9), the waistband pinned to the abdomen, bend 0.63, damping 0.0125, 6 mm, 2×4, self-collision on.
+25 s, 1,500 steps; the dance is steps 96 onward (1,404 steps). Every metric is in **vertex order** —
+`ClothState#position` is colour-permuted and `ClothInstance#particle_of_node` maps back; read in particle
+order the triangle metrics are garbage (30,000 "crossings" on a flat ring). Per step: how far any free
+particle is inside any body collider and short of the 6 mm contact offset; how far the rendered surface
+(triangle centroids, edge midpoints) is inside one, and separately the **sag**, surface inside with every
+corner outside; pinches (inside one collider, within the offset of another); forearms or hands through the
+surface; contact-slot overflow; inside-episode lengths; and every 30 steps §31's crossings, edges through
+triangles they share no vertex with.
+
+```
+  dance, 1,404 steps                  shipped 2×4    4×8 budget    128×25 mesh at 2×4
+
+  steps with a particle inside           12.7%           0.0%           11.5%
+  deepest particle penetration         12.6 mm          3.8 mm        13.8 mm
+  short of the 6 mm offset by > 1 mm      8.1 mean       0.4            14.1
+  inside episodes, median / max steps     1 / 6          1 / 1          1 / 4
+  surface sag > 5 mm, corners outside     1.4% (8 mm)    0%             0%
+  self-crossings a sample, mean / max   406 / 584      272 / 683    2,132 / 2,716
+  pinched particles                       1.4%, max 2    0              1.0%, max 12
+  forearm or hand through the surface     never          never          never
+  contact slots full                      mean 0.04      0.01           0.21
+```
+
+**Two mechanisms, and they separate on the first two columns.** The thighs through the skirt vanish at
+4×8 and do not move with resolution, so they are the contact row's convergence under a sweeping collider.
+The crossings do not move with the budget, so they are the self-collision model. Neither is the descent.
+
+### Why the thigh showed: the ramp, in ratio terms
+
+A thigh advances 17 mm a substep. A new contact starts at `CLOTH_CONTACT_K_MIN_RATIO = 0.25` of
+`m/h²` — 72 N/m for a 20 g particle at two substeps — and climbed by `β·|C| = 1e3 × 0.017 = 17 N/m` an
+iteration against a ceiling of `8·m/h² = 2,300 N/m`. In the band's own units that is **0.003 of the band
+per contact offset of violation per iteration**: against a limb the penalty never left the floor, the
+multiplier had to carry the push and was rebuilt from a quarter every substep, and four iterations
+built about 60% of it. The thigh sat 5 to 13 mm through for one to six steps on every forward swing.
+The measurement that chose `β` (§17) was a sheet landing on a floor, where the violation per substep
+after touchdown is `h²g`, a third of a millimetre. The reference 2D implementation (Giles et al.) ramps
+at `β = 1e5` against `m/h² ≈ 3,600` and a floor of 1, which is about eight times this engine's rate
+relative to the inertial scale, and ramps active rows only.
+
+`cloth_contact_dual_update` now climbs by `ρ·k_max·|C|/(thickness + inflation)`,
+`ρ = CLOTH_CONTACT_RAMP_RATIO`. The sweep, dance steps with any particle inside / the deepest shortfall of
+the offset / the peak particle speed in the dance:
+
+```
+  variant                        inside   shortfall   peak m/s
+  shipped, floor ¼, β = 1e3       12.7%     18.6 mm     3.95
+  floor 1×                         1.9%     19.1        3.47
+  floor 8× (the ceiling)           1.1%     17.6        6.02   episodes median 4: slaps
+  β = 1e4                          0.2%     13.2        8.41   a spike
+  β = 1e5                          0.6%     17.7        3.84
+  ratio ρ = 0.03                   0.5%     13.1        4.79
+  ratio ρ = 0.05                   0.1%     10.4        3.63
+  ratio ρ = 0.1                    0.1%      7.7        3.73
+  ratio ρ = 0.15                   0.0%      5.0        3.49
+  ratio ρ = 1                      0.1%      7.3        3.23
+  ratio ρ = 4                      0.3%     16.0        4.25
+  ρ = 0.1, active rows only        1.0%     15.5        3.93
+  ρ = 1,   active rows only        0.4%     12.7        3.27
+  ρ = 0.1, seeded from the predicted violation at discovery, then active only
+                                   0.4%     13.9        3.81
+```
+
+The plateau starts at 0.05. Ramping active rows only — the reference's form, and the one-sided ramp §54
+rejected under `β` — leaves the thigh through ten times as often and takes the thrown particle's stopped
+speed (`cloth_contact_row.spec`'s capsule) from 6 to 4 m/s at two substeps and 12 to 9 at four; seeding
+a new row's penalty from Lewin's semi-continuous estimate of its violation over the step, then ramping
+active rows only, does no better. The pre-stiffening of speculative rows is what a fast arrival hits,
+twice measured, and it stays. The tunnelling threshold does not move at any ρ: 6 m/s at two substeps,
+12 at four, the substep bound §7 P3 states; the speeds just past it are chaotic (8 m/s is stopped under
+one ramp and not another), which is why the gate now pins 10 and 12.
+
+### What a ratio ramp does to resting cloth, and the decay
+
+With the ratio ramp every row violated by millimetres while a pile lands is at the ceiling for good, and
+at the ceiling §53's limit cycle is too large for silk to sleep. `cloth_sheet.slow.spec`'s three scenes
+under each form (the twirled skirt's gate is "settles within 2 mm of where it hung"):
+
+```
+  form                             ribbon pile      skirt settle     draped sheet carried
+  shipped β                        asleep at 166    0.9 mm           338°
+  ρ = 0.1, unconditional           never            17.1 mm          316°  (gate ≥ 320°)
+  ρ = 0.1, active rows only        never             2.2 mm          318°
+  ρ = 0.1, seeded + active         never             2.4 mm          pass
+  ρ = 0.1, penalties decay 0.9     pass             26.2 mm          pass
+  ρ = 0.1, penalties decay 0.8     pass              pass            pass
+  ρ = 0.1, penalties decay 0.5     pass              3.2 mm          pass
+```
+
+Active rows only fails it too, and that is the tell: the problem is not the pre-stiffening of
+speculative rows but the penalty a row is *left with* once it has been violated. The resolution is the
+one §18 named when it recorded the coupling, a `γ < 1` for contacts: `CLOTH_CONTACT_GAMMA` decays a
+contact's two penalties per substep at the warm start, the multiplier's `α·γ` untouched, so a quiet row
+sinks back to the floor in a few steps while the multiplier carries its load, and a violated one
+re-climbs within an iteration. `rope_sleep.probe.js`, the 6-link rope of §53 on a floor, asleep at step:
+
+```
+  penalties decayed        both, γ_c      1      0.95     0.9     0.8     0.5
+  floor, friction 0                     326      501     377     308    1005
+  floor, friction 0.5                   193      208     194     196     353
+  cotton rope, floor 0.5                347      220     247     264     277
+  rope on a sphere                      368      369     369     369     399
+
+  normal penalty only, γ_c               1      0.85     0.8     0.75    0.7
+  floor, friction 0                     326      377     308     376    never
+  floor, friction 0.5                   193      189    never    never    209
+```
+
+Decaying the normal penalty alone makes the resting rope's sleep a coin toss; decaying both sleeps every
+scene from 0.5 to 0.95. **0.8** passes the three slow gates; 0.7, 0.75 and 0.85 leave the twirled skirt
+2.7–2.9 mm from where it hung against a 2 mm gate, and 0.9 and 0.5 further. That settle is a chaotic
+quantity — folds fall differently — and 0.8 passing it is luck as much as merit; its real argument is the
+rope table, where 0.8 is in the middle of the flat region. On the skirt the decay changes nothing:
+0.1% of steps inside at 0.8, 0.5% at 0.9.
+
+### Against the measurements that chose the shipped constants
+
+`cloth_m2_measure.mjs`, the shipped build against the ratio ramp alone and with the decay:
+
+```
+                                              shipped β     ρ = 0.1       ρ = 0.1, γ_c = 0.8
+  §17 sheet landing at 3 m/s, floor 1/32:
+    worst penetration                          1.10 mm      0.68 mm       0.69 mm
+    kinetic energy at step 240                 8.6e-9 J     1.1e-9        7.9e-9
+    peak contact force                         1.42 N       1.56 N        1.56 N
+  §17 at 8 m/s: penetration / peak speed       1.69 / 3.64  0.72 / 3.44   0.70 / 3.44
+  §6 capsule swept through a hanging sheet
+    at 2 m/s, worst penetration               17.1 mm       1.8 mm        1.7 mm
+  §5 sheet on a slope, metres slid in 4 s:
+    20°, μ = 0.4 (Coulomb: sticks)             0.194        0.000         0.553
+    10°, μ = 0.2 (Coulomb: sticks)             0.000        0.000         0.070
+    30°, μ = 0.7 (sticks)                      0.000        0.000         0.0003
+    50°, μ = 1.2 (slides)                      2.71         0.31          3.53
+```
+
+The ramp alone is better than the shipped build on every row, friction included — the marginal slope
+case sticks exactly as Coulomb says. The decay gives the friction back: a sheet that should stick creeps
+0.2–0.3 mm in four seconds, and the marginal case slides 0.55 m where the shipped build slid 0.19. The
+friction row's penalty decays too because the normal-only decay is the erratic column above; the friction
+cap reads the current iteration's normal force (§8.3), which is what couples the two. That is the trade
+the pair makes, and it is recorded rather than tuned around: ρ = 0.1 with γ_c = 0.8 ships, both as
+`CLOTH_SOLVER_TUNING` fields, and the friction exactness is the cost.
+
+### What it costs elsewhere
+
+A rope seeded with its tail 20 mm inside a sphere — `cloth_collision.spec`'s "far side of the room"
+rope — is ejected at 6.75 m/s in the shipped build and at 9.5 under ρ = 0.1; the gate noticed only
+because the rope left the sphere's gather reach two steps sooner. The sphere now sits beside the rope's
+middle, 22 mm off the links, gathered and never touched. The three gates in `cloth_contact_row.spec`
+that pinned the old arithmetic re-pin to the ratio, and a new one holds M2 §6's capsule at 2 m/s to
+"never inside the surface" (17 mm red on the shipped ramp, 1.8 mm green). The gather and warm-start
+costs nothing: paired in one process, five skirts stepped alternately, the ratio ramp reads 0.97× the
+shipped step.
+
+### Self-collision: three candidates against the hem
+
+The hem's problem is that `ClothState#self_radius` is one number, `max(thickness, ½·shortest row)` capped
+at `0.4 × closest free pair`, and both lengths are measured over the whole cloth: the waistband's 9.8 mm
+rows and 19.6 mm closest free pair give the 54 mm hem a 6 mm radius. §18 carries it. Three answers were
+measured on the skirt (dance, ρ = 0.1, γ_c = 0.8 throughout) and on §64's eleven ribbon piles
+(`ribbons.probe.js`: silk strips 16×3 at 3 cm on a floor with friction 0.5, 2,400 steps or asleep):
+
+```
+  skirt                                   inside   shortfall   crossings mean / max   kinetic J   pairs   step cost
+  pair row as shipped                      0.1%     10.4 mm       432 / 632            2.58        44
+  per-particle radius                      0.0%      5.1          102 / 180            2.87       135     0.94×
+  predicted travel in the search           0.1%      8.8          412 / 620            2.56        54
+  frozen pair normal                       1.9%     14.8          424 / 663            2.60        46
+  travel + frozen                          0.0%      4.3          443 / 715            2.43        55
+  frozen, gated on the live distance       1.1%     13.0          438 / 697            2.52
+  travel + per-particle                    1.2%     16.2           38 / 144            2.86
+  travel + frozen + per-particle           1.3%     17.3           35 / 125            2.80        79
+  travel + gated frozen + per-particle     0.7%     14.6           27 / 101            2.79
+  point-triangle rows + pair               6.3%     58.2          197 / 463            5.39, peak 18.8 m/s
+  point-triangle + per-particle            6.6%     56.4           89 / 322            6.81, peak 18.8
+  point-triangle + travel + frozen + pp    5.3%     55.3           56 / 273            6.33, peak 18.8
+  point-triangle alone                     6.5%     45.3          237 / 1,015          5.61, peak 18.8
+
+  ribbon piles, 11 scenes                asleep   clean (no crossing ever)   order kept   worst crossings, mean
+  pair row as shipped                      11            6                       7               7.5
+  predicted travel in the search           11            9                       9               5.7
+  frozen pair normal                       11            9                       9               1.6
+  travel + frozen                          11           10                      11               0.2
+  travel + frozen, gated on the distance   11           10                      11               0.2
+  point-triangle alone                      5            7                       9              34.2
+  point-triangle + pair                    11            7                      10               1.6
+  point-triangle + pair + travel + frozen  11           11                      11               0.0
+```
+
+**The per-particle radius** — the shipped formula applied locally,
+`r_i = clamp(thickness, ½·shortest row incident on i, 0.4 × closest free pair of i)` (the prototype used
+the sheet's analytic cap, `0.8·row`; the real one measures it) — takes the skirt's crossings down by
+three quarters with no collider cost and a cheaper step, because the hem holds itself apart and makes
+fewer contacts. It is still the sphere model. On the uniform ribbons it is the shipped row.
+
+**Lewin's two moves on the pair row** (GDC 2018, "Cloth Self Collision with Predictive Contacts") are
+the semi-continuous candidate test — the relative displacement over the step projected on the separating
+direction, which is §35's missing travel term — and the pair's normal frozen for the step, which turns
+the row into a half-space no pair can pass through however far the other rows shove it. On the ribbon
+piles they are worth more than anything else measured: every pile asleep, ten of eleven never crossing,
+all eleven in order, the worst crossings 7.5 → 0.2 a scene. On the skirt they do not touch the
+crossings, which are the radius, and they cost limbs there: 1.9% of steps with a thigh through under
+the frozen normal against 0.1%, 1.1% with it gated on the live distance (a half-space stays active
+after its pair has slid apart tangentially, the artefact the talk names), and 1.2% for the travel term
+on top of the per-particle radius, where the two together take the crossings to 38. The piles keep
+their result under the gate. Why a wider or stickier pair row puts a hem particle into a thigh is not
+measured; the shape of it is a particle pinched between a fold and the limb, with the pair row a plain
+penalty whose shares over several pairs sum past one. It is the number that keeps the two moves from
+landing with the radius.
+
+**Predictive point-triangle rows** were prototyped as the talk's self collision (`pt_rows.mjs`): a
+triangle-AABB hash grid extruded by displacement, the closest point for the weights and the fat-triangle
+test, the face normal signed to the point's side, `C = n̂·(x_p − Σ w x) − 2·thickness ≥ 0` frozen for the
+step, up to four rows a vertex, as plain penalties into the self row's Jacobi scratch. Three things were
+learned, each by a trace of two stacked ribbons (`ribbons_trace.probe.js`):
+
+- As a penalty at the pair row's ratio the row cannot stop a ribbon landing at 10 mm a step inside
+  8 mm of separation; it ends 4 mm through, the next step's detection sides every row the other way,
+  and the rows push the pile inside out. That is the talk's own "failures in collision detection cannot
+  be corrected in subsequent frames", and why it shipped with authored layer order.
+- Stiffer is worse, explosively (peak speeds 3–6 m/s at 4× and 8×). A four-particle row updated
+  Jacobi-style over-corrects: the participants' expected corrections sum to `κ/(1+κ) + 3κ/(9+κ)` for a
+  centroid row, 1.03 at the prototype's κ = 1.5 and 2.6 at 8×. The pair row at ratio 2 sits at exactly 1,
+  which is a mechanism for §65's "the stiffest ratio at which cloth resting on itself comes to rest".
+  With each participant taking its mass-weighted share of the row the sum is 1 at any stiffness, and the
+  landing ribbon is then stopped and rests at 7.7 mm.
+- With the split, on their own they sleep five of eleven piles, push the lowest ribbon into the floor
+  and leave 34 crossings; with the pair row they add the eleventh clean pile; on the skirt every form is
+  unstable — peak speeds at the velocity clamp, a thigh through in 5–7% of steps — with ~1,000 rows a
+  step over 832 particles, where the shares of several rows on one particle sum past 1 again.
+
+So the row that would close §9's gap is a hard row with a multiplier under a Gauss-Seidel treatment, not
+a penalty in the Jacobi scratch, and the talk's cost figures (20 ms to 1 s a frame for the general
+method; 0.1–0.2 ms with authored layers and cached contacts) say what that buys. M4b stays open.
+
+### Gates
+
+Cloth suite 370 (from 369): `cloth_contact_row.spec` gains the swept capsule at 2 m/s, red on the
+shipped ramp at 17 mm. Three of its tests re-pin to the ratio ramp, and `cloth_collision.spec`'s far-side
+rope moves its near sphere beside the rope. The extended cloth specs 10, green on the decayed ramp and
+red without the decay (the ribbon pile, the twirled skirt, the draped sheet). `check-types` not re-run.
+The probe hooks that measured the self-collision candidates are reverted; the scripts are in the
+session scratchpad with `probe_hooks.patch`.
+
+## 68. The self radius is the particle's own
+
+§67 left one answer measured and not landed: the self-collision radius built from the particle's own
+two lengths rather than the cloth's. This lands it. `ClothState` carries two regions filled at seed —
+`self_row`, the shortest stretch row incident on each particle, and `self_free_pair`, the closest pair
+no row governs within twice the longest row (`cloth_self_closest_free_pair`, which used to return one
+number into `ClothInstance#closest_free_pair`) — and `cloth_self_radius_update` fills `self_radius`
+per particle at the top of every step from them and the fabric's thickness,
+`r_i = min(max(t, ½·row_i), 0.4·free_i)`. The pair search tests `d² < (r_i + r_j)²` and hashes at a
+cell of twice the largest radius; the row's rest is `r_i + r_j`. `ClothStepParam.SELF_RADIUS` is gone
+(the stride 15 → 14), and so is `ClothInstance#closest_free_pair`. On a uniform sheet every particle
+gets the number the cloth used to get, to the float.
+
+**The dance, paired.** The example's skirt (64 × 13, 832 particles, 6 mm thick, 2 × 4) on the rumba
+track, two scenes in one process stepped alternately with the order rotated each step, 1,500 steps, the
+dance steps 96–1,499 scored. Arm A has its two lengths flattened to the cloth's minima after the first
+step, which is the old radius at every particle — 6 mm, the thickness, since half the 9.8 mm waistband
+row is below it; arm B is the build.
+
+| arm | radius | steps with a limb through | deepest | crossings mean / worst | pairs a step | ms mean / median / p90 |
+|---|---|---|---|---|---|---|
+| A, one per cloth | 6.0 mm | 0.6% | 8.3 mm | 422 / 618 | 43 | 13.389 / 13.876 / 16.986 |
+| B, per particle | 6.0–18.8 mm | 0.0% | −0.9 mm | 102 / 180 | 135 | 12.944 / 13.352 / 16.434 |
+
+Paired B/A: 0.967 of the mean, 0.962 of the median, 0.963 the median of the per-step ratios. The step
+is cheaper with three times the pairs, and a 300-step re-run that counted contact rows says where: A
+carries 324 contact rows a step (worst 464), B 255 (worst 424), the hem's flutes held apart rather than
+tangled against the legs; the step there 9.015 → 8.799 ms, B/A 0.976 (a quieter box; the ratio is what
+is paired). §67's 432 → 102 is reproduced at 422 → 102.
+
+**The code path, isolated.** The previous `cloth_self_find` and `cloth_self_accumulate_scratch`
+(HEAD's files, reading a scalar) against the new, on the same skirt state frozen 400 steps into the
+dance, search plus scratch, 300 interleaved reps:
+
+| | median | mean | pairs | to the old |
+|---|---|---|---|---|
+| old code, 6 mm | 465 µs | 498 µs | 7 | 1.000 |
+| new code, 6 mm everywhere | 462 µs | 493 µs | 7 | 0.993 |
+| new code, per particle | 562 µs | 598 µs | 203 | 1.207 |
+
+A busier first run gave 665 / 664 / 796 µs, 0.999 and 1.197. Reading the radius from an array costs
+nothing; the per-particle radii find 29× the pairs on that frame for 21% more search and scratch, about
+100 µs of a 13 ms step.
+
+**§64's eleven ribbon piles, as the control.** The same two arms. On the 5, 6 and 8 cm piles the radii
+coincide — 15 mm, half the 30 mm row — and on the 3.2 cm piles they differ as designed: a particle with
+a second ribbon within 32 mm at seed is capped at 12.8–12.9 mm and the rest keep 15 mm, where one
+radius per cloth gave every particle the 12.8.
+
+| scene | A asleep | A worst / end crossings | A order | B asleep | B worst / end crossings | B order | B/A ms |
+|---|---|---|---|---|---|---|---|
+| 2 parallel, 3.2 cm | 188 | 0 / 0 | kept | 188 | 0 / 0 | kept | 1.021 |
+| 2 parallel, 8 cm | 225 | 5 / 2 | swapped | 208 | 4 / 4 | swapped | 1.062 |
+| 2 at 90°, 3.2 cm | 111 | 0 / 0 | kept | 111 | 0 / 0 | kept | 0.992 |
+| 2 at 90°, 8 cm | 126 | 0 / 0 | kept | 126 | 0 / 0 | kept | 1.027 |
+| 3 at 90°, 3.2 cm | 272 | 2 / 2 | kept | 273 | 2 / 2 | kept | 1.021 |
+| 3 at 90°, 8 cm | 251 | 0 / 0 | swapped | 251 | 0 / 0 | swapped | 1.017 |
+| 3 at 30°, 3.2 cm | 256 | 0 / 0 | kept | 273 | 0 / 0 | kept | 1.000 |
+| 3 at 30°, 8 cm | 324 | 10 / 7 | kept | 324 | 10 / 7 | kept | 1.009 |
+| 6 at 30°, 3.2 cm | 224 | 52 / 37 | swapped | 322 | 46 / 16 | swapped | 1.014 |
+| 6 at 30°, 6 cm | 401 | 14 / 0 | swapped | 474 | 13 / 0 | swapped | 0.998 |
+| 3 at 60°, 5 cm (the gate) | 264 | 0 / 0 | kept | 265 | 0 / 0 | kept | 1.042 |
+
+Both arms: 11 of 11 asleep, 6 clean, 7 in order; the worst crossings a scene 7.5 (A) and 6.8 (B); the
+step 1.018× paired (0.992–1.062). The sleep steps that differ where the radii coincide measure a pile's
+chaos, not the change: two bit-identical copies of each scene stepped side by side stay bit-identical
+to the end (checked on all eleven), while arm A's flattening takes the minimum over `Float32` rows that
+differ by 1.3e-8 m between particles, so its radii sit 6.5e-9 m under some of B's, the pair search flips
+a comparison at step 4–8, and the sleep step moves by up to 98 (224 against 322). A difference of that
+size between two piles is noise, measured.
+
+**The twirled skirt gate** (`cloth_sheet.slow.spec`'s 32 × 7 cotton annulus on turning hips: 29 mm rows
+round the waistband, 60 mm rows out to the hem). The hem had the waistband's 14.7 mm and now has 30:
+
+| | radius | draped at | asleep after the stop | hem height from rest | hem radius from rest | deepest in the hips | crossings, worst step |
+|---|---|---|---|---|---|---|---|
+| one per cloth | 14.7 mm | 196 | 412 | 0.35 mm | −13.3 mm | −6.73 mm | 16 |
+| per particle | 14.7–30 mm | 196 | 290 | 5.62 mm | 0.1 mm | −6.72 mm | 0 |
+
+The 16 are the hem's flutes meeting during the twirl at a quarter of their spacing. With its own radius
+the hem comes back to its radius and stands 5.6 mm higher, a fold resting on a fold with a 30 mm shell
+rather than 14.7; the gate's 2 mm on the height, pinned on a measured 0.9, re-pins at 10 mm, and it
+gains `crossed === 0`, red at 16 on the old radius. Nothing is closer to the hips.
+
+### Gates
+
+Cloth suite 373 (from 370): `cloth_self_radius.spec` — an annulus's waist and hem radii from their own
+rows, a uniform sheet unchanged from the cloth-wide number, a particle with no row at the thickness.
+`ClothState.spec`'s layout carries the three regions. `cloth_self_find.spec`, `cloth_self_row.spec` and
+its slow spec fill the array. The extended cloth specs 10, green; the twirled skirt re-pinned and gated
+as above, red on one radius per cloth. `check-types` 18 against 19. The A/B is `ab_radius.probe.js`
+with `ab_scenes.mjs` in the session scratchpad, the control `ribbon_determinism.probe.js` and
+`ribbon_diff.probe.js`, and the slow spec's old arm an alias of `cloth_self_radius.js` that flattens
+(`vitest.slow_flat.config.mjs`).
+
+---
+
+## 69. The gust on the scene's clock, and the parity gate restated
+
+The GPU wind fluid's S5 (`../fluid/GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md` §12, G2, F4) took cloth's
+air off cloth's own ambient and onto the scene's one wind. `ClothAmbientWind` is retired: its gust,
+term for term, is `GlobalFluidEffector#gust`, integrated once a tick by `FluidEffectorsSystem`, and
+cloth reads it through the far field — `ClothGPUFluidWind` (lattices of the GPU wind, read back
+through `GPUFluidSystem#request`; the far field before one lands and wherever none reaches) or
+`ClothFluidWind` (the CPU fields, the far field outside them). §57's clock, each cloth's own age, is
+no longer read by any engine source.
+
+**What that costs the parity gate, measured.** The gust is now a function of the scene's tick, and
+the worker advances a cloth from the tick its registration is acknowledged (§39). Each row is a scene
+of `WorkerClothSystem.spec.js` with one line changed, the gate reading the whole `ClothState` buffer
+after every step:
+
+```
+  scene                                                   wind                        first difference
+  second cloth spawned after the first, under latency     steady (gust 0)             none in 60 steps
+    (registered 3 ticks later by the worker)              gust 3 m/s, period 0.7 s    the second cloth's step 1, byte 0 (216 against 247)
+  one cloth, both registered on the same tick             gust 3 m/s, period 0.7 s    none in 180 steps (far field moving on > 100 of them)
+    the reference spawned a tick before the worker's      gust 3 m/s, period 0.7 s    step 1, byte 0 (246 against 86)
+  §10's field scene, a garment walked out of a volume     steady far field            none in 200 steps
+                                                          far field gusting 1.5 m/s   step 1, byte 0 (27 against 30)
+```
+
+So **the gate is restated**: worker and inline cloth agree for cloths **registered on the same tick**,
+under any deterministic wind, and for any registration **under a time-invariant wind**. The specs hold
+it to those cases, through the GPU wind with no device (lattices answered from the far field) and
+through lattices a spec injects (`ClothGPUFluidWind.spec.js`, `ecs/cloth_wind.spec.js`). Under the
+GPU wind on a device, lattices land when the GPU answers, so two runs of a scene need not read the
+same air: **run-to-run repeatability under the GPU wind is given up** (F4, accepted). Every other cloth
+gate is unchanged: the parity scenes without wind, §7's table, the pathology spec.
+
+*Reproduce:* the probe that edits one line of the spec and prints the first difference is
+`s5_probe_gust.mjs` in the GPU-fluid session's scratchpad.
+

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

@@ -340,8 +340,8 @@ engine/physics/cloth/
     cloth_collider_sdf.js           pose interpolation, localisation, and the field dispatch
   wind/
     AbstractClothWind.js            §10's one interface: sample the air, and say whether it varies
-    ClothAmbientWind.js             a constant plus a band-limited gust — the air where no field is
-    ClothFluidWind.js               every live FluidComponent, with the ambient underneath it
+    ClothGPUFluidWind.js            the GPU wind: lattices read back from GPUFluidSystem, the far field elsewhere
+    ClothFluidWind.js               every live FluidComponent, with the scene's far field underneath it
     cloth_sample_air.js             the air into the cloth's own frame, on the main thread
   solver/
     ClothState.js                   SoA particle + topology + constraint storage over one buffer
@@ -529,10 +529,15 @@ iterate      repeat `iterations` times:
                dual update, for each HARD constraint c:
                  λ_c ← clamp(k_c·C_c + λ_c, fmin_c, fmax_c)
                  k_c ← min(k_c + β·|C_c|, k_max·s_c)
+                 (a contact's normal row: k_c ← min(k_c + ρ·k_max·s_c·|C_c|/offset, k_max·s_c))
 
 integrate    v_i = (x_i - x_i^prev)/h
 ```
 
+A contact's warm start differs in one line from the listing above: its two penalties decay by
+`γ_c = CLOTH_CONTACT_GAMMA` rather than `γ`, the multipliers by `α·γ` as every hard row's do. The
+correction below is why.
+
 The Hessian contribution is gated on the row being *active*. A clamped row's force is constant with
 respect to position, so its true second derivative is zero; adding `k·ggᵀ` anyway would make an
 inactive unilateral constraint resist motion it should not touch. It contributes its (constant) force
@@ -586,6 +591,30 @@ a decision rather than an omission — nothing measured since has asked for a de
 one place it would help is recorded in §18 as a coupling rather than as a bug — but it is an
 **unmeasured** constant and the only one left in the set, so it is named here as one.
 
+**The cloth-skirt example corrected the contact's ramp and gave it a decay (`MEASUREMENTS.md` §67).**
+A thigh advancing 17 mm a substep into a hanging skirt showed through it in 12.7% of the dance's
+steps, up to 13 mm, and four times the iteration budget made that zero: the row was arriving soft.
+`β = 1e3 N/m²` against that garment's band of 72 to 2,300 N/m is **0.003 of the band per contact
+offset of violation**, so against a limb the penalty never left the floor and the multiplier, rebuilt
+from a quarter every substep, could not carry the push in four iterations. The ramp is a ratio now,
+`ρ = CLOTH_CONTACT_RAMP_RATIO = 0.1` of the band per offset of violation per iteration, which keeps the
+shape the M2 measurement picked in the units the contact is defined in: 12.7% → 0.1% of steps, M2's
+landing sheet 1.10 → 0.68 mm, M2 §6's swept capsule 17 → 1.8 mm, the tunnelling threshold unmoved.
+It ramps whether or not the row is active, as before: ramping active rows only, the reference
+implementation's form, leaves the thigh through ten times as often and takes the thrown particle's
+stopped speed from 6 to 4 m/s at two substeps, which is §18's one-sided finding again.
+
+What a ratio ramp does to a **resting** contact is what §18 predicted: every row violated by
+millimetres while a pile lands is at the ceiling for good, where §53's limit cycle is too large for
+silk to sleep — §64's ribbon pile never slept, the twirled skirt settled 17 mm from where it hung, the
+draped sheet was carried 4° less. The resolution is the one §18 named, a `γ < 1` for contacts:
+`γ_c = CLOTH_CONTACT_GAMMA = 0.8` decays a contact's two penalties per substep while the multiplier
+carries the load, and every scene sleeps as before (erratic at 0.7, slow at 0.5; decaying the normal
+penalty alone leaves the resting rope's sleep a coin toss, so both decay). Its cost is static
+friction's exactness: a sheet on a slope it should stick to creeps 0.2–0.3 mm in four seconds, and
+the marginal case, μ a tenth over the tangent, slides 0.55 m where the old ramp slid 0.19 — the ratio
+ramp without the decay made that case stick exactly, so the two together are a trade, not a free win.
+
 **Adaptive initialisation** is VBD's: seed the iteration at `x + h·v + h²·ã` where `ã` interpolates
 between zero and full external acceleration according to whether the previous step looked like free
 fall or like resting contact. Without it, a low iteration count over-stretches under gravity on the
@@ -1257,15 +1286,19 @@ It reads as the same `r` a collider contact uses, which is `ClothDynamics#thickn
 a fold are almost never in contact and the row finds 1.6 to 3.7 pairs across a whole garment. The
 radius is a property of **the proxy**: `ClothState#self_radius`, `max(thickness, shortest_row/2)`,
 so the row's diameter is one particle spacing. At the fabric's own 6 mm the row removes 21% of a
-sheet's self-intersections; at half the shortest row it removes 82%. `MEASUREMENTS.md` §31.
+sheet's self-intersections; at half the shortest row it removes 82%. `MEASUREMENTS.md` §31. And the
+row is **the particle's own** (`ClothState#self_row`), a pair's reach the sum of its two radii: a circle
+skirt's hem has rows five times the waistband's, and one radius per cloth gave it the waistband's, a
+fifth of its spacing, with the flutes through each other at every sample. §67, §68.
 
 **It also needs a ceiling, and the ceiling is a measured length.** A diameter that reaches the
 closest pair *no row governs* puts a cloth which is not folded at all in permanent contact with
 itself — leather, 20 mm thick on a 20 mm proxy, found 1,398 pairs a step across 576 particles
 standing still (§36). On a sheet that distance is two hops and could have been assumed; on a
 rigged garment, whose proxy is strips with nothing joining one to the next, it is the gap the
-artist left between strips and is half what the link length implies. So `ClothInstance` measures
-it once at seed, in the bind pose, and the ceiling is two fifths of it. `MEASUREMENTS.md` §37.
+artist left between strips and is half what the link length implies. So `cloth_build_rows` measures
+it once at seed, in the bind pose, per particle into `ClothState#self_free_pair`, and the ceiling is
+two fifths of it. `MEASUREMENTS.md` §37, §68.
 
 "O(n) with a small constant" is right about the shape and optimistic about the constant: the pair
 search is linear in particles with no term in the pair count, and it is **12% of a frame** at the
@@ -1332,6 +1365,16 @@ Fallback when there is no fluid field in range: a `GlobalFluidEffector`-shaped a
 constant `wind` vector plus a small band-limited noise for gusting — read from the same interface, so
 the cloth code has one path and does not branch on whether a simulation is present.
 
+*Corrected by the GPU wind fluid's S5 (`../fluid/GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md` §12, G2):*
+the fallback is no longer cloth's own. It is the scene's **far field** — its `GlobalFluidEffector`s,
+gust included, folded by `FluidEffectorsSystem` once a tick — which is what the shape above was
+always copying. `ClothAmbientWind` is retired; `ClothGPUFluidWind` reads the GPU wind and
+`ClothFluidWind` the CPU fields, each with the far field underneath. `MEASUREMENTS.md` §69.
+And cloth reads it **by default**: with nothing assigned, `ClothWorld#wind` is a `ClothGPUFluidWind`
+while the scene has an enabled `GPUFluidComponent`, else a `ClothFluidWind` while the far field is not
+zero, else `null` as before — decided again every tick from those facts, so a scene without wind gains
+no drag. An assigned source, `null` included, always wins.
+
 Cost control: sampling is per particle per *step*, not per iteration, and a cloth outside every fluid
 field's bounds skips it entirely. Sleep (P5) wakes on a wind change so a settled banner does not stay
 asleep through a gust.
@@ -1715,6 +1758,15 @@ walk it. The visible consequence is that two garments spawned a second apart are
 the gust rather than in phase with it; for a bounded sum of sinusoids that is indistinguishable from
 weather, which is why this is free. `MEASUREMENTS.md` §57.
 
+**G2 (the GPU wind fluid's S5): the clock is the scene's, and the gate is restated.** The gust moved
+onto `GlobalFluidEffector` and runs on the scene's tick, so every consumer of the wind reads one
+weather — and a cloth steps in the weather of the tick it is advanced on. The worker advances a cloth
+from the tick its registration is acknowledged, so the gate now reads: **worker and inline agree for
+cloths registered on the same tick, and for any registration under a time-invariant wind.** Measured:
+the staggered spawn under a 3 m/s gust differs at the second cloth's step 1, byte 0; registered on
+the same tick, none in 180 steps. Under the GPU wind on a device, lattices land when the GPU answers,
+so run-to-run repeatability is given up too (F4). `MEASUREMENTS.md` §69.
+
 **And post-M6 found the other one, which is not a clock: the two systems ran a tick's phases in
 different orders.** `ClothSystem` ran advance, step and finish per cloth, in hierarchy-depth order, so
 a **nested** cloth advanced against an anchor the cloth above it had already written *this* step;
@@ -2213,8 +2265,8 @@ case and found 1,398 pairs a step on a 576-particle sheet that was barely folded
 distance has to be **measured** rather than assumed to be two hops, because two hops is a fact
 about sheets: the playground's cape has 8 cm links and an 8.5 cm gap between strips, half what the
 link length implies, and the assumed ceiling left it with three pairs permanently in contact at
-rest. `ClothInstance#closest_free_pair` is measured once at seed and the ceiling is two fifths of
-it. On a sheet the two rules agree exactly, so §31–36 stand. `MEASUREMENTS.md` §37.
+rest. `ClothState#self_free_pair` is measured once at seed, per particle, and the ceiling is two
+fifths of it. On a sheet the two rules agree exactly, so §31–36 stand. `MEASUREMENTS.md` §37, §68.
 
 **And the playground earned its keep.** Every measurement from §31 to §36 is on a sheet, because a
 sheet is the only thing here with a surface to pass through. Put the same row on the geometry M3
@@ -2609,6 +2661,14 @@ visible, for a hair rope creeping for thirty-seven seconds instead of three, whi
 rather than fixed; the thing that would actually resolve it is a `γ < 1` for contacts, which is
 §5.2's own open number. `MEASUREMENTS.md` §54.
 
+**— RESOLVED the way it said, when the ramp became a ratio.** The cloth-skirt example turned the ramp
+into `CLOTH_CONTACT_RAMP_RATIO` (§5.2), which made the pre-stiffening total — every row violated by
+millimetres at the ceiling for good — and a resting pile stopped sleeping. `CLOTH_CONTACT_GAMMA = 0.8`
+is the `γ < 1` for contacts, on both penalties. The one-sided ramp was measured again in ratio form and
+lost again (a sweeping thigh through ten times as often, 6 → 4 m/s stopped at two substeps), so the
+pre-stiffening stays and the decay is what bounds it. What the pair costs is static friction's
+exactness, stated in §5.2. `MEASUREMENTS.md` §67.
+
 **Open — a rigid collider driven through pinned cloth wraps rather than parts.** A contact row bounds
 the interpenetration; it cannot prevent it, because the cloth has nowhere to go. The playground's
 spinning-bar scene is the case, and it settles at 18 mm inside a 25 mm bar. This is not a solver
@@ -2845,6 +2905,45 @@ rest" is not enough, because a ribbon can land right through another and lie und
 and not this:* piles land through themselves, 90 of 225 at 2, every one of them while landing. That is
 §35's missing travel term in the pair search. `MEASUREMENTS.md` §64, §65.
 
+**The self radius is one per cloth, and a circle skirt's hem gets the waistband's. — FIXED: the
+radius is the particle's own (§68); Lewin's two pair-row moves wait on their limb cost.**
+`ClothState#self_radius` was `max(thickness, ½·shortest row)` capped at `0.4 × closest free pair`,
+with both the shortest row and the closest free pair measured over the whole cloth. The cloth-skirt
+example's rows run from 9.8 mm at
+the waistband to 54 mm at the hem, so the hem gets a 6 mm radius against a 37–54 mm spacing — a row
+diameter a fifth of the spacing where §9 wants one spacing — and the flutes pass through each other
+at every sample: ~400 edge-through-triangle crossings, budget-independent (272 at 4×8), the example's
+own README says "the flutes sometimes cross". `MEASUREMENTS.md` §67 measured three answers:
+
+- **The shipped formula applied per particle — LANDED (§68)**, `r_i = clamp(thickness, ½·shortest
+  row incident on i, 0.4 × closest free pair of i)`, pairs tested at `r_i + r_j`, both lengths seeded
+  into `ClothState#self_row` and `#self_free_pair` and the radius filled each step by
+  `cloth_self_radius_update`. Paired on the dance: crossings 422 → 102 a step (worst 618 → 180), a
+  thigh through in 0.6% → 0.0% of steps, the step 0.96× for 70 fewer contact rows with the hem held
+  off the legs, search and scratch 1.2× on three times the pairs; the twirled skirt's 16 crossings → 0,
+  and its gate pinned. It is still the sphere model, and a sharp fold still slips between particles.
+- **Lewin's two moves on the pair row (GDC 2018):** the particle's predicted travel in the pair
+  search's reach — §35's missing term — and the pair's normal frozen for the step, which makes the row
+  a half-space a pair cannot pass through however far the other rows shove it. On §64's eleven ribbon
+  piles they take the pair row from 6 clean and 7 in order to 10 clean and 11 in order, every pile
+  asleep, the worst crossings 7.5 → 0.2 a scene, at no new row kind. On the skirt they do not touch
+  the crossings and they cost limbs: a thigh through in 1.1–1.9% of steps against 0.1%, and 1.2% for
+  the travel term on top of the per-particle radius (crossings 38). A half-space stays active after
+  its pair has slid apart tangentially, the artefact the talk names; gating it on the live distance
+  halves the cost and keeps the piles' result. Why a wider or stickier pair row puts a hem particle
+  into a thigh is not measured, and it is what keeps the two moves from landing with the radius.
+- **Predictive point-triangle rows, as the talk's self collision,** as plain penalties into the
+  self row's Jacobi scratch: a four-particle row is only Jacobi-stable with each participant taking
+  its mass-weighted share of the correction (the pair row at ratio 2 sits exactly at the share sum
+  of 1, which is why §65 found it the stiffest that comes to rest), and with that split a ribbon
+  landing from 10 mm a step is stopped at 8 mm of separation. On their own they sleep 5 of 11 piles
+  and push the lowest ribbon into the floor; on the skirt they are unstable at every form tried (peak
+  speeds at the clamp, a thigh through in 5–7% of steps). They add the last pile only on top of the
+  pair row with Lewin's moves. The talk's own numbers say the same: 20 ms to 1 s a frame for the
+  general method, 0.1–0.2 ms only with authored layer order and cached contact sets. M4b stays what
+  it was: the thin-surface closure, not a quick win, and in this solver it wants a hard row with a
+  multiplier and a Gauss-Seidel treatment, not a penalty in the Jacobi scratch.
+
 ---
 
 ## 19. Attachment points

package/src/engine/physics/cloth/collider/ClothColliderKind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClothColliderKind.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderKind.js"],"names":[],"mappings":";;;gCAeU,MAAM"}
+{"version":3,"file":"ClothColliderKind.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderKind.js"],"names":[],"mappings":";;;gCAsBU,MAAM"}

package/src/engine/physics/cloth/collider/ClothColliderKind.js

@@ -1,3 +1,5 @@
+import { ShapeRecordKind } from "../../../../core/geom/3d/shape/record/ShapeRecordKind.js";
+
 /**
  * The shapes cloth collides against.
  *
@@ -9,8 +11,13 @@
  * answer is to add primitive `ClothCollider` children, which is what an author
  * would do for a character anyway.
  *
- * The values are indices into a dispatch, so they are contiguous from zero and
- * their order is the order `cloth_collider_sdf.js` branches in.
+ * A collider's kind and parameters are a core shape record
+ * (`core/geom/3d/shape/record/`), so the values are core's
+ * {@link ShapeRecordKind} and this is the subset of it cloth takes. Core also
+ * packs a rigid `TransformedShape3D` (with a pose offset), a `UnionShape3D`
+ * (as a run of records) and a `ConvexHullShape3D` (as planes in a table of
+ * their own); cloth refuses all three, as it always has, until it has somewhere
+ * to keep what each brings beyond a kind and four parameters.
  *
  * @readonly
  * @enum {number}
@@ -20,19 +27,19 @@
  */
 export const ClothColliderKind = {
     /** Radius in `CCR_PARAM_0`. */
-    Sphere: 0,
+    Sphere: ShapeRecordKind.Sphere,
 
     /** Radius in `CCR_PARAM_0`, segment length in `CCR_PARAM_1`, about local Y. */
-    Capsule: 1,
+    Capsule: ShapeRecordKind.Capsule,
 
     /** Half-extents in `CCR_PARAM_0..2`. */
-    Box: 2,
+    Box: ShapeRecordKind.Box,
 
     /** Radius in `CCR_PARAM_0`, height in `CCR_PARAM_1`, about local Y. */
-    Cylinder: 3,
+    Cylinder: ShapeRecordKind.Cylinder,
 
     /** Outward unit normal in `CCR_PARAM_0..2`, offset in `CCR_PARAM_3`. */
-    Plane: 4
+    Plane: ShapeRecordKind.Plane
 };
 
 Object.freeze(ClothColliderKind);