@woosh/meep-engine 3.24.0 → 3.25.0

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

@@ -1,7 +1,8 @@
 # Cloth — Design
 
-> Design document. Written 2026-09-10; **M0, M1, M2 and M3's rigged path are implemented**, and
-> every place they contradicted it has been corrected in place with the measurement named beside it.
+> Design document. Written 2026-09-10; **M0 through M5 are implemented** — the solver, chains,
+> collision, the rigged path, self-collision and the worker — and every place they contradicted it has
+> been corrected in place with the measurement named beside it.
 > §17 says what is done and what is not; `MEASUREMENTS.md` is the evidence.
 >
 > Scope: a cloth and soft-chain simulator that lives inside `engine/physics`, collides against the
@@ -271,7 +272,8 @@ engine/physics/cloth/
     cloth_dynamics_map.js           normalised coordinates → row parameters; every constant measured
     ClothCollider.js                component: the RigidBody-analogue for collision
     ClothColliderFlags.js
-    ClothSystem.js                  main-thread system: gather, step, write back
+    ClothWorld.js                   every cloth in a scene, and everything that is not arithmetic
+    ClothSystem.js                  main-thread system: a ClothWorld stepped inline
     ClothInstance.js                one live cloth: the binding between a subtree and a ClothState
     cloth_seed_subtree.js           §11.1's walk: entities → node_parent + animated_position
     cloth_seed_rig.js               §11.2's proxy: joints → node_parent + animated_position
@@ -280,14 +282,14 @@ engine/physics/cloth/
     cloth_write_back.js             that pose → Transform64 + TransformAttachment
     cloth_write_back_rig.js         that pose → Node3D.transform_local
     cloth_gather_colliders.js       the index's overlapping records, in the cloth's own frame
-    WorkerClothSystem.js            drop-in worker variant (WorkerSystem subclass)
-    ClothWorkerCore.js
-    cloth.worker.js
-    makeClothWorker.js
-    cloth_worker_protocol.js
-    ClothSerializationAdapter.js
-    ClothRigSerializationAdapter.js
-    ClothColliderSerializationAdapter.js
+    WorkerClothSystem.js            drop-in worker variant: the same ClothWorld, stepped over there
+    ClothWorkerCore.js              worker side: a ClothState view per registered cloth
+    cloth.worker.js                 the entry point, a real module worker
+    makeClothWorker.js              the spawn expression, isolated because it needs import.meta
+    cloth_worker_protocol.js        the command region: a count, then a block per cloth
+    ClothSerializationAdapter.js    the component + its ClothDynamics, by value
+    ClothColliderSerializationAdapter.js   five authored scalars, the same way
+    ClothRigSerializationAdapter.js NOT BUILT — §3.2's asset identity, and the proxy codec
   collider/
     ClothColliderIndex.js           the index of live cloth colliders + their swept AABBs
     ClothColliderRecord.js          the packed layout: kind, params, both poses, bounds, interpolated pose
@@ -295,10 +297,17 @@ engine/physics/cloth/
     cloth_collider_pack.js          AbstractShape3D → packed record
     cloth_collider_bounds.js        the swept AABB, shared by the index and each cloth's own table
     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
+    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
+    cloth_step_instance.js          one cloth, one step, over nothing but memory — what crosses
     cloth_step.js                   the fixed step: predict, warm start, iterate, dual update, integrate
     cloth_solve_vertex.js           the per-vertex 3x3 block update
+    cloth_wind_accelerate.js        §10's aerodynamic term, and the factor that makes a flag a flag
     constraint/                     one module per row type (§6)
     cloth_color_particles.js        graph colouring of the particle graph
     constraint/cloth_leash_row.js   §6's slack row and its tether row, which are one row model
@@ -340,10 +349,19 @@ Two systems:
 - **`ClothSystem`** owns the simulation. Per fixed step: refresh the animated targets, gather the
   overlapping colliders from the index, step, write back.
 
-Cloth runs at the fixed rate and is interpolated for display, exactly as `PhysicsSystem` does — the
-same producer/`__interp_restore` contract, so a cloth-driven `Transform64` is authoritative during the
-fixed pass and interpolated outside it. Reusing the existing contract rather than inventing a second
-one is what keeps a cloth-driven bone from fighting an animation-driven one.
+  **M5 note: it owns it jointly with `WorkerClothSystem`, and "two systems" is now three.** The two
+  are interchangeable — same components, same declared access, same position in the derived order —
+  and they share a `ClothWorld`, which is the registry and every phase of a step that is not
+  arithmetic. `ClothSystem` calls `cloth_step_instance` between the two halves; `WorkerClothSystem`
+  puts a thread there. §12 has why that is what makes the bit-parity gate structural.
+
+Cloth runs at the fixed rate and its poses are **held** between ticks rather than interpolated, which
+on a display faster than the fixed step is visible and is not wrong. The first draft of this paragraph
+said cloth reuses `PhysicsSystem`'s producer/`__interp_restore` contract; M5 measured that it cannot —
+that contract is entity-keyed and a rigged garment's joints are not entities — and §13.1 and §18 carry
+what the cloth-shaped version would be and what it would cost. What keeps a cloth-driven bone from
+fighting an animation-driven one is not interpolation but `TransformAuthority`, which `cloth_seed_rig`
+claims (§11.2, `MEASUREMENTS.md` §25).
 
 ### 4.1 Ordering, and why the answer is not to be ordered
 
@@ -874,6 +892,15 @@ which arrives with the component in M1 — so **damping is load-bearing for P5 r
 control**, and the M1 spec has to gate on a soft cloth actually settling. `MEASUREMENTS.md` §6.
 *Spec:* a settled cloth reaches sleep within a bounded number of steps and its positions are bit-identical
 across the following 300.
+**M6 note: a cloth also wakes on the air changing, and the test has one sample in it.** §10's "sleep
+wakes on a wind change" is the same shape as the collider test beside it — ask a question three orders
+of magnitude cheaper than the step it decides whether to skip — and the question is the air at the
+cloth's own centre against the air the last *applied* step saw. The last applied rather than the last
+sampled, so a gust that builds slowly accumulates instead of being reset by every step that declined
+to act on it. *Its limit, stated:* one point. A gust that reaches only the hem of a sleeping banner
+and leaves its middle still will not wake it. The collider test has no such gap because a collider's
+pose is seven exact numbers and a field is a continuum.
+
 *M1 landed both halves and measured them.* Every library fabric, on a 12-link chain set swinging at
 3 m/s, sleeps: **220 steps for denim, 770 for silk**, everything else between, and the order is the
 damping order. Sleep stops the **write-back** as well as the step, which is what makes "bit-identical"
@@ -1090,8 +1117,7 @@ the bodies in the scene.
 
 So the design is: **a cloth overlapping a `FluidComponent` samples its velocity field per particle and
 applies aerodynamic drag against it**, scaled by `ClothDynamics#drag`. The term is an external
-acceleration, `a_drag = drag · (u_air − v) · |n·û|`, with the normal-facing factor making a sheet catch
-the wind broadside and slice through it edge-on — the difference between a flag and a rope.
+acceleration, `a_drag = response · facing · (u_air − v)`.
 
 The payoff is that a character running past a cape gets a wake, because the fluid solver already
 produces one; a fire's convection lifts a banner; a door slamming pushes a curtain. None of that needs
@@ -1106,8 +1132,69 @@ Cost control: sampling is per particle per *step*, not per iteration, and a clot
 field's bounds skips it entirely. Sleep (P5) wakes on a wind change so a settled banner does not stay
 asleep through a gust.
 
-This is deferred to M6 — it is the feature most likely to be cut for schedule, and nothing else depends
-on it.
+**M6 built it and corrected this section in four places.**
+
+**The factor above is not `|n·û|`, because half of what this system simulates has no `n`.** This
+paragraph originally wrote the term as `a_drag = drag · (u_air − v) · |n·û|`, "with the normal-facing
+factor making a sheet catch the wind broadside and slice through it edge-on — the difference between a
+flag and a rope". It is right about what it wants and wrong that a normal is available to want it
+with. A chain's particles span a **line** — every direction perpendicular to it is equally a normal,
+so picking one is the history-dependent fabrication §7 P4(a) exists to keep out — and a rope's
+aerodynamics are the *complement* of a sheet's anyway: it catches the flow across it and slices along
+it. Both are one quantity, **the part of the flow the particle's own incident rows cannot let past**:
+take the span `T` of the directions to its stretch-row neighbours in the current configuration, and
+`facing = ‖û − proj_T(û)‖`.
+
+| rank of `T` | what the particle is | the factor |
+|---|---|---|
+| 2 | a point on a surface | `\|û·n\|` with `n = b₁×b₂` — this paragraph's own expression |
+| 1 | a link of a chain | `√(1 − (û·t)²)` — the cross-flow, which is the rope's answer |
+| 0 | an isolated particle | `1` — a bead has no preferred direction |
+
+One expression, three topologies, no stored normal, no orientation, no sign, nothing carried between
+steps. `MEASUREMENTS.md` §47.
+
+**And the factor's headline claim is about *laminar* air, which is a limit rather than a fault.** On
+the playground's banner, turning a uniform wind through ninety degrees takes the mean factor from
+0.221 to **0.000** and the aerodynamic acceleration from 43.2 m/s² to 0.08 — a flag becoming a rope,
+exactly as promised. Turning a **wake** through ninety degrees does nothing at all: 0.216 to 0.280. A
+wake has velocity in every direction, so no orientation of a surface is edge-on to one, and the factor
+is correctly reporting that there is nothing to slice through. That makes this section's argument for
+reading a simulation *stronger* than this section knew. `MEASUREMENTS.md` §51.
+
+**`drag` is not what multiplies the flow, and the difference is a stability argument.** One external
+acceleration is held for the whole fixed step, so an explicit `rate · (u_air − v)` overshoots the air
+once `rate·dt > 1` and diverges past 2 — and §1's first commitment is "not at 5 fps", which is a `dt`
+of 0.2 s and a rate of 10. What the step multiplies by is the **per-step response**
+`(1 − e^(−rate·dt))/dt` (`cloth_drag_response`), the exact solution of the same linear ODE, which
+closes a fraction of the gap that is strictly below one for every rate and every step length. It is
+also the step `GlobalFluidEffector` already takes for the air itself, which is a symmetry rather than
+a coincidence: both are relaxations toward a velocity. `MEASUREMENTS.md` §49.
+
+**The field answers in grid cells per second and cloth needs metres.** `FluidField#sampleVelocity`
+documents that it deliberately does not rescale, "on the assumption that callers (vegetation sway,
+dust drift) interpret the field as a direction × magnitude wind". Cloth is not such a caller: its row
+is a relaxation toward a velocity, so without the multiply by `cell_size` the same wind voxelised at
+0.25 m instead of 1 m blows a garment four times as hard. `ClothFluidWind` converts.
+`MEASUREMENTS.md` §46.
+
+**And this section never said which thread samples, which M5 made a question.** It cannot be the
+worker's: a fluid field is a hundred thousand floats its own solver rewrites every step and may itself
+live on another worker, while the *answer* is three floats a particle. So `cloth_sample_air` runs on
+the **main thread** in both systems and writes into `ClothState#air_velocity` — a region of the
+cloth's own `SharedArrayBuffer`, so nothing is copied — and everything built from it runs in
+`cloth_step_instance` with the rest of the arithmetic, which is what keeps §12's parity structural.
+Measured: 58–62 ns a particle for a field sample, a twenty-fifth of that for the ambient (one sample
+for the whole cloth, which is what §10's "skips it entirely" is worth), and one per cent of a step for
+the term itself. `MEASUREMENTS.md` §48, §49.
+
+**Where the air comes from is a scene's choice and there is no default.** `ClothWorld#wind` is `null`
+until something assigns a source, exactly as the collider index is: a scene without one gets M5's
+cloth rather than an error. Null rather than a still-air ambient, because a source answering zero
+everywhere is not "no wind" — the row is a relaxation toward the air, so still air still resists a
+*moving* cloth, anisotropically. That is better physics than `ClothDynamics#damping`'s isotropic decay
+and it is not free, so it is a thing a scene asks for. What a cloth does in air that is not moving is
+`damping`'s job (§7 P5, where it is load-bearing); what it does in air that *is* is this.
 
 ---
 
@@ -1299,12 +1386,19 @@ garments never override them.
 
 ## 12. Data layout, threading, the worker
 
-**One `SharedArrayBuffer` for the whole cloth world**, not one per instance. `WorkerSystem`'s model is
-a single shared buffer, a single command region and a single atomic publishing one in-flight step, and
-`WorkerFluidSystem` already shows how a variable set of simulated things fits that model: the command
-region carries a count and then a list of ids to step. Cloth does the same — each instance gets a
-region inside the buffer, and the command region names which instances are live this step, so sleeping
-(P5) and culled (§12.1) instances cost nothing but their absence from a list.
+**One `SharedArrayBuffer` per cloth**, and the command region names which cloths are live this step —
+so sleeping (P5) and culled (§12.1) cloths cost nothing but their absence from a list. `WorkerSystem`'s
+model is a single shared buffer, a single command region and a single atomic publishing one in-flight
+step, and `WorkerFluidSystem` shows how a variable set of simulated things fits it.
+
+**M5 corrected "one buffer for the whole cloth world", and `reseed` is why.** A `ClothState` is sized
+at seed from *that cloth's* particle and row counts, and `ClothSystem#reseed` — a chain gaining a link,
+a `ClothDynamics` change the row tables depend on, a rigged garment whose model has just loaded —
+builds a different one while other cloths have steps in flight. A world buffer would therefore need an
+allocator with relocation, and a relocation invalidates every view of every region on both threads at
+once. One buffer per cloth costs one cold-plane message per seed (`add_cloth` / `remove_cloth`, the
+shape `WorkerFluidSystem` already has) and makes a re-seed a re-registration, which is the same code
+path as a first seed. `MEASUREMENTS.md` §39.
 
 SoA throughout:
 
@@ -1315,13 +1409,40 @@ SoA throughout:
 | topology | `Int32Array` | edge pairs, bend stencils, colour ranges, tether anchors |
 | rest data | `Float32Array` | rest lengths, bend weights, `d_geo` |
 | duals | `Float32Array` | `λ` and `k` per persistent constraint |
-| colliders | `Float32Array` | packed records for this step |
+| colliders | `Float32Array` | packed records for this step — `CLOTH_COLLIDER_SLOTS` of them |
 | contacts | `Float32Array` | transient rows + their warm-start `λ`, keyed by (particle, collider slot) |
 
-`ClothDynamics` reaches the worker through the command region, written every step — a dozen words into
-memory the worker already shares, cheaper than tracking dirtiness, and it keeps
+The **step's parameters** reach the worker through the command region, written every step — fourteen
+words into memory the worker already shares, cheaper than tracking dirtiness, and it keeps
 `cloth.dynamics.slack = 0.2` working live, which is the point of a value object rather than a preset
-that has to be re-applied.
+that has to be re-applied. (Thirteen at M5; M6's §10 adds the drag response, and the air itself
+travels as a region of the same buffer rather than as words — `ClothState#air_velocity`, written by
+the main thread and read by the step, which is the one direction the buffer could always carry and
+nothing had used.)
+
+**M5 corrected "`ClothDynamics` reaches the worker".** By the time the step can use them a cloth's
+dynamics have been through `cloth_dynamics_map.js` — a damping retention, a velocity clamp, a
+self-collision radius, gravity rotated into the local frame — and sending the raw component would mean
+running that mapping a second time on the far side, with no way to prove the two copies agreed. What
+crosses is `ClothStepParam`: `dt`, local gravity, substeps, iterations, retention, clamp, contact
+radius, self radius, collider count, and whether self-collision is on. `Float64` throughout, so the
+round trip is exact — an `f32` command region would round the clamp, and a clamp that rounds is a
+velocity that rounds. `MEASUREMENTS.md` §40.
+
+The same block is what makes the parity gate below structural rather than aspirational:
+`ClothSystem` fills the words of a private scratch array and calls `cloth_step_instance`;
+`WorkerClothSystem` fills the same words of the shared command region and the worker calls the same
+function. Neither system computes a step parameter of its own, so neither can compute one differently.
+
+**M6 found the one thing that is not a parameter and still differs: the clock.** A gust is a function
+of time, and a worker cloth is not advanced until its registration is acknowledged — so the two
+systems reach a cloth's *first step* at different tick counts, and a clock that counted ticks hands
+that cloth a different gust on the same step. Measured with the clock put back on ticks, the gate
+fails at step 1, byte 0, which is the step's own result word. `ClothWorld#time` therefore counts the
+steps the world has taken rather than the ticks it has been asked about: it advances at the first
+`advance` of a tick, so a tick in which nothing is advanced does not move the weather. That is also
+the right semantic on its own terms — a paused simulation should not have the wind move.
+`MEASUREMENTS.md` §50.
 
 `Float32` for particle state, not `Float64`. The simulation runs in the cloth's **local frame**, so
 coordinates are garment-sized rather than world-sized and f32 has ample precision; the payoff is half
@@ -1340,6 +1461,16 @@ fixed `CLOTH_CONTACT_SLOTS` per particle inside `ClothState`'s single buffer —
 saturate on a twenty-collider scene and to average a tenth of one — which keeps §12's one-allocation
 property and bounds the worst case at the four *most violated* colliders, which is the four that matter.
 
+**And M5 moved the per-step collider table itself into that buffer**, at a fixed
+`CLOTH_COLLIDER_SLOTS`, which is where the table above always put it. M2 kept it on `ClothInstance`
+and grew it by doubling, on the correct grounds that its size is a property of the world rather than of
+the cloth; what decides is that an array which can be *replaced* mid-run is memory the worker has to be
+told about again before it can name it. So the size stays a property of the world and the region gets a
+capacity. **Sixty-four**, because the measurement showed the bound is a *scene* rather than a garment —
+a cloth's table holds every collider on every character standing inside its query box, which is ten for
+one body and thirty for three — and because an overflow discards colliders in the index's own order
+rather than in order of how much they matter. It warns once. `MEASUREMENTS.md` §41.
+
 **The worker.** `WorkerClothSystem` is a `WorkerSystem` subclass and follows `WorkerFluidSystem`
 exactly, because that pattern is already proven in this repo: `collect` packs colliders and animated
 targets into shared memory and writes the command words, a single `Atomics.store` publishes the step,
@@ -1353,6 +1484,15 @@ identical order. That is what makes the worker a deployment choice rather than a
 it is why the core is a pure function over typed arrays from milestone zero even though the worker does
 not arrive until milestone five.
 
+**M5 measured it and the number is zero**, at every step of a run rather than at the end of one: the
+whole `ClothState` buffer — particles, velocities, every dual and penalty, the collider table, the
+warm-started contact multipliers, the self-collision pair list — compared byte for byte after each of
+420 steps across two scenes, one with a walking anchor and one with colliders and self-collision live.
+What the scene sees differs by exactly one tick: the pose written at tick `T` is step `T − 1`'s. That
+is §4.1's own sentence in a second setting — the cloth's *shape* is one fixed step stale and its
+*position* is not, because the attachment cascade carries the subtree rigidly with the anchor.
+`MEASUREMENTS.md` §40.
+
 Testing the bridge needs no worker: `SystemWorkerLoopback` gives a real `SystemWorkerHost`, a real
 `SharedArrayBuffer` and real `Atomics` in-process, with message delivery and step execution as explicit
 events a spec can order. Only the thread is faked.
@@ -1391,9 +1531,9 @@ What this design takes from the engine rather than building:
 | Constraint-row doctrine | `physics/constraint/solve_constraints.js` |
 | Subtree walk | `TransformAttachmentSystem#findChildrenOf` / `#countChildrenOf`, `TransformAttachment` |
 | Animated targets | `mesh_apply_skeletal_vertex_skinning` (flat arrays, worker-safe) |
-| Wind / aerodynamics | `FluidField#sampleVelocity`, `fluid_build_world_to_grid`, `GlobalFluidEffector` |
+| Wind / aerodynamics | `FluidField#sampleVelocity` (in grid cells a second — §10 converts), `fluid_build_world_to_grid`, `GlobalFluidEffector` as the shape of the ambient *and* as the exact-ODE relaxation step `cloth_drag_response` copies |
 | Worker offload | `ecs/async/WorkerSystem.js`, `SystemWorkerHost`, `SystemWorkerLoopback`, `WorkerFluidSystem` as the worked example |
-| Fixed step + render interpolation | `PhysicsSystem`'s producer/`__interp_restore` contract |
+| Fixed step | `EntityManager`'s fixed-step loop, gate and `fixedStepTick` |
 | Transforms | `Transform64`, `Node3D` |
 | Particle → render-vertex mapping | `Skin` — joints + inverse-bind matrices + the four-weight palette; cloth writes joints and the existing pass does the rest |
 | Reaching a model's joints from its entity | `SceneBundleInstance` (`skins`, `nodes` by name), `register_instance_animation` |
@@ -1404,6 +1544,24 @@ What this design takes from the engine rather than building:
 
 ---
 
+### 13.1 What is *not* reusable — render interpolation
+
+`PhysicsSystem`'s producer/`__interp_restore` contract was in the ledger above and M5 took it out,
+because it cannot express a rigged garment. `Interpolated` is an **entity-keyed marker**: the
+`InterpolationSystem` files snapshots under a `key` it assigns from the entity id at link time. A
+rope's links are entities and a skinned garment's joints are not — `shade_node_to_entity_composition`
+does not expand a skinned node, "and that is a boundary rather than an omission" (§3) — so half the
+feature has nothing to put the component on.
+
+Cloth also needs only half of what that contract does. `__interp_restore` exists to hand the
+simulation its authoritative pose back before it integrates, because the render blend writes into the
+components the simulation reads. Cloth's state is `ClothState.position` in the cloth's local frame and
+its write-back never touches the anchor it reads, so **cloth never reads back what it writes** and has
+nothing to restore. It needs the publish half, over a pose per node rather than a component per entity.
+§18 carries what that would cost. `MEASUREMENTS.md` §43.
+
+---
+
 ## 14. New shared code this justifies
 
 Three pieces belong in `core`, not in `cloth`, because the cloth need exposes a gap the engine has
@@ -1623,13 +1781,36 @@ placement into a bounded quality question and leaves the scheduler alone.
 and belongs with the collision rows that make a particle get *stuck* in the first place — a chain has
 no configuration to be stuck in. Chebyshev acceleration, still gated on contacts that arrive at M2. `β`,
 which M0 could not choose and M1 has no transient rows to choose it with either — every row M1 adds is
-persistent. `ClothSerializationAdapter` and its siblings: nothing in M1's scope list names them, and a
-codec written before `ClothRig` exists would be revised by M3 before it was ever loaded.
+persistent. The serialization adapters: nothing in M1's scope list names them, and a codec written
+before `ClothRig` exists would be revised by M3 before it was ever loaded — **true of one of the three;
+the correction follows this block.**
 Interpolation: cloth writes `Transform64` at the fixed rate and §12's producer/`__interp_restore`
 contract is not wired, which shows as a cloth updating at the fixed rate rather than the frame rate
 and is a visible-but-not-wrong gap. M5 is where it belongs, with the worker.
 **This is the first shippable feature.**
 
+**Corrected 2026-09-13: the deferral above only ever fitted `ClothRig`'s adapter, and it was applied to
+all three of them from here to the end of the plan.** It fits `ClothRigSerializationAdapter`, whose
+component points at a built, shared, immutable asset and therefore needs the asset-identity story §3.2
+only gestures at; and it fits `ClothProxy`'s own codec, which genuinely does depend on what §11.3
+step 9 adds to a proxy. It never fitted `Cloth` or `ClothCollider`. Those two are scalars — `blend`,
+`layer`, `mask`, `flags` and a `ClothDynamics` value object of ten more; `inflation`,
+`friction_scale`, `layer`, `mask`, `flags` — and neither holds a proxy, a skin, or anything either
+geometry path introduces. The evidence that the revision this sentence feared was never coming is M3
+itself: it changed the design in four places (`MEASUREMENTS.md` §24–29) and not one of them was a
+field on either component.
+
+What turned a sequencing call into a hole is that it was **re-deferred rather than re-examined**. M2
+deferred all three "per M1's own reasoning"; M3 deferred them again for M1's reason while, in the same
+list, deferring the unrigged path that the reason had just been made to wait on; and §11.3 step 9 is
+in no milestone at all. A wait with no scheduled end is not a sequencing decision, and what it cost is
+that M6 closed this plan with a subsystem a scene could not contain: a `Cloth` could be added from
+code and from nowhere else. `ClothSerializationAdapter` and `ClothColliderSerializationAdapter` are
+built and specced as of 2026-09-13, outside any milestone and with no `MEASUREMENTS.md` section,
+because there is no measurement behind them — a codec has nothing to measure, and that file's sections
+belong to milestones. `ClothRigSerializationAdapter` and the proxy codec stay deferred, on the reason
+as narrowed here.
+
 **M2 — collision. DONE, 2026-09-10.** `ClothCollider`, `ClothColliderFlags`, `ClothColliderSystem`,
 `ClothColliderIndex`, the packed record and its swept bounds, analytic SDF gradients and
 `PlaneShape3D` in `core` (§14.1, §14.3), the contact row and its friction row, the backstop row, and a
@@ -1659,8 +1840,10 @@ particle get stuck, and also measured the one stuck configuration whose *residua
 the quantity the escape hatch was to watch (§7 P4). It belongs with the self-collision of M4, where a
 particle can be pinched between two rows rather than merely held by one. The backstop row is built,
 specced and driven by the playground, but nothing **authors** one: its plane comes from a garment's own
-skinned surface and a skinned garment is M3. Two-way coupling, per §2. `ClothSerializationAdapter` and
-its siblings, per M1's own reasoning.
+skinned surface and a skinned garment is M3. Two-way coupling, per §2. The serialization adapters, per
+M1's own reasoning — which, as M1 now records, reached only `ClothRig`'s. The other two were not
+blocked by anything M2 had in hand or M3 was about to add, and this line is the first of the two
+restatements that carried them anyway.
 
 **M3 — skinned garments, the rigged path. DONE, 2026-09-10.** `ClothRig`, `ClothProxy`,
 `cloth_proxy_from_joints` (§11.3 steps 5–8), the rig seeder, and joint write-back into
@@ -1695,7 +1878,13 @@ budget. §11.3 step 10's bind-pose collision validation, which `cloth_proxy_from
 because it has a joint tree and no collider set — and which `MEASUREMENTS.md` §29 makes the argument
 for, because a garment authored inside its own body reads as a *tether* failure and costs an hour to
 diagnose. `ClothProxy`'s binary codec and `ClothRigSerializationAdapter`, for M1's own reason: a
-codec written before the unrigged path exists would be revised before it was ever loaded.
+codec written before the unrigged path exists would be revised before it was ever loaded. **Those two
+only, corrected 2026-09-13.** As written this sentence carried `Cloth`'s and `ClothCollider`'s
+adapters with them, over a set of three, for a reason that held for one — and it did so in the same
+list that defers the unrigged path the reason had just been made to wait on, which is what closed the
+loop: the dependency and the thing depending on it were deferred by the same paragraph. Neither scalar
+component holds a proxy, so §3.2's asset-identity question — the real content of M1's reason — was
+never theirs to answer. Both adapters were built on 2026-09-13; M1 carries the full correction.
 
 **M4 — self-collision. DONE, 2026-09-11.** `core/geom/3d/hash-grid/PointHashGrid3.js`, the
 particle-particle row (`solver/constraint/cloth_self_row.js`), the pair search
@@ -1762,13 +1951,110 @@ realisations, a self-tangled sheet unties itself every time the gust stops, so M
 configuration to escape from. The case P4(d) names is a particle wedged between a collider *and* a
 fold, which is collision and self-collision together, and M4 has not measured it.
 
-**M5 — the worker.** `WorkerClothSystem`, `ClothWorkerCore`, `cloth.worker.js`, the protocol.
-*Proofs:* bit-parity between `ClothSystem` and `WorkerClothSystem` as a standing gate; loopback specs
-covering step ordering, message ordering and shutdown; a measured main-thread cost reduction.
-
-**M6 — wind.** Fluid-field sampling, aerodynamic drag, the ambient fallback.
-*Proofs:* a playground with a banner in a simulated wake; a measured cost showing the per-step sampling
-stays inside budget. Cuttable without affecting anything else.
+**M5 — the worker. DONE, 2026-09-12.** `WorkerClothSystem`, `ClothWorkerCore`, `cloth.worker.js`,
+`makeClothWorker` and the protocol — plus the two pieces that had to exist for the parity gate to be
+structural rather than hopeful: `ClothWorld`, which is every cloth in a scene and everything about
+stepping one that is not arithmetic, owned by *both* systems; and `cloth_step_instance`, which is the
+arithmetic, driven by a `Float64` parameter block that is also the command region's per-cloth record.
+`ClothState` gains shared-memory backing, a descriptor, the collider table and a result region.
+*Proofs, all green:* bit-parity over the **whole `ClothState` buffer at every step** of two runs — a
+walking anchor for 240 steps, and colliders plus self-collision for 180 — with the write-back's
+one-tick lag pinned tick by tick rather than asserted at the end; the state a worker steps being the
+main thread's memory rather than a copy; a cloth being neither stepped **nor advanced** until its
+registration is acknowledged, which is what keeps the two systems' step *sequences* identical rather
+than merely similar; a re-seed retiring its registration and waiting again; a despawn between dispatch
+and step not failing the bridge; sleep removing a cloth from the dispatch and `wake` putting it back;
+shutdown settling the step in flight, releasing the gate and dropping the worker; and the derived
+execution order landing `WorkerClothSystem` exactly where `ClothSystem` lands. **10 tests in one new
+spec file**, with the M0–M4 suites unchanged at 183. The engine suite is green at 18,579.
+
+**M5 changed the design in four places**, each with the measurement behind it in `MEASUREMENTS.md`
+§38–44 and each folded back above. In one line each: §12's one buffer for the whole cloth world is one
+buffer per cloth, because `reseed` resizes one while others are in flight; §12's collider table does
+belong in that buffer and therefore needs a capacity rather than a growth policy, and the capacity is
+bounded by the *scene* — thirty records for three characters — rather than by the garment; §12's
+"`ClothDynamics` reaches the worker through the command region" is the *mapped* step parameters rather
+than the component, because mapping them twice is two copies that cannot be proved equal; and §13's
+reuse of `PhysicsSystem`'s interpolation contract does not hold, because that contract is entity-keyed
+and a rigged garment's joints are not entities.
+
+**And the strongest result is again a number rather than a correction.** §12 asks the two systems for
+bit-identical results. Over 420 steps across two scenes, comparing the entire state buffer after every
+one of them, the number of differing bytes is **zero** — and it is zero by construction rather than by
+luck, because there is one `ClothWorld`, one `cloth_step_instance`, and one parameter block that both
+systems fill and neither system interprets. The main thread's share of a thousand-particle garment goes
+from 3.62 ms to 0.18 ms; across the library's shapes, 92% to 96% of it crosses. `MEASUREMENTS.md` §40,
+§41.
+
+**Deliberately not in M5:** **render interpolation**, which §18 said would land here and which M5
+decided against with three findings rather than a deferral — the named contract is entity-keyed and
+cannot reach a rigged garment's joints, cloth needs only the half of it that has no name, and the
+worker removes the cheap implementation by owning `ClothState` outside the fixed pass. What it needs
+instead is a published pose slot, and §18 now carries what that costs (about 0.12 ms a frame on the
+§17 workload, which roughly triples the main thread's share of cloth and leaves it at a seventh of
+its pre-M5 cost) and what it buys (half a link length a step at a walk, a whole one at a sprint).
+`MEASUREMENTS.md` §43. **A playground page**, for a reason about the dev server rather than the cloth:
+`SharedArrayBuffer` needs a cross-origin isolated page, and adding `COOP`/`COEP` to
+`vite.config.mjs` changes how every other playground page in the package loads its subresources —
+to demonstrate a bridge `SystemWorkerLoopback` already tests more precisely than a page could.
+**Culling (§12.1)**, which is a policy over the same dispatch list sleep already uses and belongs with
+a camera. And **a deeper pipeline**: `WorkerSystem` allows one step in flight and the fixed-step gate
+means a cloth could not use a second.
+
+**M6 — wind. DONE, 2026-09-13.** §10 end to end: `wind/AbstractClothWind.js` and the two sources
+behind it (`ClothAmbientWind`, `ClothFluidWind`), `wind/cloth_sample_air.js`,
+`solver/cloth_wind_accelerate.js`, `ClothState`'s air and external-acceleration regions,
+`cloth_drag_response`, the parameter block's fourteenth word, and `ClothWorld`'s wind source, clock
+and wake test.
+*Proofs, all green:* the normal-facing factor on both topologies, which is the whole of what M6 adds
+to the physics — a sheet reading 1.000 broadside and 0.000 edge-on, a chain reading the reverse, and
+neither a skip row nor a strain-limit row able to fabricate a plane out of a line; the two sources
+through the interface, including a field answering in metres rather than grid cells and `varies()`
+being a promise the sampler acts on; the ECS path end to end — a garment blown downwind, one inside a
+`FluidComponent` reading the simulation while one ten metres away reads the weather, a settled banner
+sleeping in a steady wind and waking on a gust, and a scene with no source producing the cloth M5
+shipped **byte for byte** across 120 steps; the drag response closing a fraction of the gap to the
+air that is strictly below one at every step length from 1/240 s to 1 s; and §12's parity gate
+extended to a third run with wind live. **25 tests across three new spec files** — the term's 9, the
+sources' 10, the ECS path's 6 — plus the parity spec's eleventh, for 26 in all, with the M0–M5
+suites unchanged at 193. The engine suite is green at **18,638**, and the same suite run against M5's
+own commit in a detached worktree reads 18,612 on this machine, so the difference is exactly M6's
+twenty-six. A fifth playground page, `playground/wind.html`, with a banner hanging in a real
+`FluidSimulator`'s wake.
+
+**M6 changed the design in five places**, each with the measurement behind it in `MEASUREMENTS.md`
+§45–§52 and each folded back above. In one line each: §10's `|n·û|` cannot be written for a chain,
+which has no normal and wants the complementary factor anyway, so both are one expression over the
+span of the incident rows; §10's "samples its velocity field" needs a unit conversion, because
+`FluidField` answers in grid cells a second and a garment blowing at a speed that depends on the
+voxel size is not a garment; §10 never said which thread samples and it cannot be the worker's, so
+the field stays where it is and three floats a particle cross in the cloth's own buffer; `drag`
+cannot multiply the flow directly, because one acceleration held for a whole fixed step overshoots
+the air once `rate·dt > 1`; and §12's thirteen-word block is fourteen, with a clock that has to count
+steps rather than ticks or the two systems' weather diverges at step 1.
+
+**And the strongest result is again a number rather than a correction.** §10 offers the normal-facing
+factor as the difference between a flag and a rope. In uniform air it is: turning the wind ninety
+degrees at the same speed takes the banner's aerodynamic acceleration from **43.2 m/s² to 0.08**, a
+factor of five hundred. In a **wake** it does nothing at all — 0.216 against 0.280 — because a wake
+has velocity in every direction and no orientation of a surface is edge-on to one. That is not a
+failure of the factor; it is the measurement saying §10's argument for reading a simulation is
+stronger than §10 knew, and that the flag-versus-rope claim is a statement about laminar air.
+`MEASUREMENTS.md` §51.
+
+**Deliberately not in M6:** **a spatially varying ambient.** The gust is uniform in space, so a long
+banner does not see it arrive at one end before the other — and that is what makes the no-simulation
+case cost one sample for a whole garment instead of one a particle (§48). Spatial structure is what a
+fluid field is *for*, and a second, worse one inside the fallback is the duplication §10 exists to
+avoid. **A blend at a field's edge**: a point inside a volume reads the volume and a point outside
+reads the ambient, so a garment straddling the boundary sees a step rather than a ramp. Where the
+ambient is the far field the volume relaxes toward — `GlobalFluidEffector`'s own `wind` — the step is
+small and is mostly the disturbance the volume exists to carry; where it is not, the answer is a
+volume large enough to hold what moves through it. **Two-way coupling into the fluid**, per §2's
+one-way rule: cloth reads the air and does not disturb it, and anything that should has
+`FluidObstacle`. And **per-substep sampling**, because §10 says per step and §48 measures the sample
+at 58 ns a particle — the one part of this that is not free is the one part per-substep sampling
+would double.
 
 **Performance budget — measured at M0, re-measured at M1, and it still does not hold on its own.** One
 character's full cloth complement — 1,024 particles at 2 substeps × 4 iterations, on a triangulated
@@ -1818,7 +2104,31 @@ attributing cost by deletion applies unchanged. What it licenses is that the col
 between nothing and a quarter of a frame and does not scale with the collider count over the range a
 character occupies. Every library entry's own budget is untouched. `MEASUREMENTS.md` §23.
 
-Re-measure at M4 and M5.
+**Re-measured at M5, and no entry is re-sized — but not for the reason the table reads.** The absolute
+column came back 15% to 25% above M4's, on a machine carrying nineteen other node processes at 30–38%
+background CPU, which is exactly the swing M4's own lesson predicts. What licenses leaving the library
+alone is a *paired* measurement instead: `cloth_library_bench.mjs` never touches
+`WorkerClothSystem` — it drives `cloth_step` over a `ClothState` directly — so the only thing M5
+changed that it can see is the buffer layout, and an interleaved A/B of the two layouts in one process
+reads 0.95 to 0.98 with the two states staying bit-identical for 1,600 steps. §33's ordering stands
+entry for entry. `MEASUREMENTS.md` §39, §42.
+
+**Re-measured at M6, and no entry is re-sized — now with a measured reason rather than only a
+disclaimer.** §10's aerodynamic term, priced in the bench's own §33 scenario, moves each entry by
+−2.7% to +9.3% across three runs, with the sign not monotone in `drag`; and with the *physics* held fixed so the two
+sides simulate the same cloth, the whole feature is **one per cent of a step**. The rest of that
+column is a different cloth — a rope blown horizontal costs 3.24× a rope hanging straight down, which
+is §7's warning arriving in a new setting and is about the rope. Three runs of the same bench within
+an hour put the §17 baseline row at 3.49, 3.83 and 4.26 ms, so the absolute column is still the
+machine: M5's advice to re-measure it quietly stands, and M6 adds that a process count is a proxy for
+load rather than a measure of it. `MEASUREMENTS.md` §49, §52.
+
+**And the budget now means something slightly different.** The worker moves the cost rather than
+reducing it, so 2 ms is still 2 ms — but it is 2 ms on a thread that is not drawing the frame, and the
+question it answers has become "does all the cloth in the scene fit in one worker tick" rather than
+"does one garment fit in a frame". The main thread's share of the §17 workload is 0.18 ms.
+`MEASUREMENTS.md` §41. Re-measure the absolute column on a quiet machine, and check the process count
+first.
 
 ---
 
@@ -1942,6 +2252,33 @@ set.
 garment or a runtime hierarchy. Culling (§12.1) covers the off-screen case; the far-but-visible case is
 unaddressed.
 
+**Open — a wake has no direction, and the aerodynamic model has only one term. — MEASURED.** §10's
+normal-facing factor is the whole of M6's aerodynamics, and in uniform air it does exactly what §10
+promises: ninety degrees of flow angle is a factor of five hundred in the force a banner feels. In a
+fluid wake it does nothing — 0.216 against 0.280 — because a wake has velocity in every direction.
+What that leaves open is whether a cloth *in* a wake wants something the linear drag row does not
+carry: the fluttering a real flag does in one comes from a pressure difference across the sheet and a
+shed vortex, not from a relaxation toward a local velocity, and this design has no term for either.
+*Mitigation:* none is needed for what M6 claims — the cloth reads the air the simulation produces and
+is moved by it. It is named because "a banner in a wake looks alive" is what a reader will expect from
+§10 and is not what a drag row alone produces. `MEASUREMENTS.md` §51.
+
+**Open — the ambient is uniform in space and the field boundary is a step.** Two limits of §10's
+fallback, both deliberate and both cheap to see: a gust lifts a whole banner at once rather than
+travelling along it, and a garment carried out of a fluid volume crosses a discontinuity rather than a
+ramp. The first is what makes the no-simulation case cost one sample rather than one a particle; the
+second is small where the ambient is the far field the volume relaxes toward and visible where it is
+not. A blend would want a falloff distance, which is an authored quantity of exactly the kind §3.4
+spent a section removing.
+
+**Open — a fluid volume's wake is steady at a grid a frame can afford. — MEASURED, and it is the
+fluid system's rather than cloth's.** At 18, 26 and 34 cells across, with the simulator's damping and
+vorticity confinement at both ends of their range, the air a banner's width behind a solid post varies
+by under 0.03 m/s: a velocity deficit, not a shedding street. The deficit is real and is a third of
+the free stream, which is what the cloth reads; what is not there is the unsteadiness. Resolving a
+shedding shear layer costs 15 ms a step at 26 cells and 35 at 34, against 5 ms at 18.
+`MEASUREMENTS.md` §51.
+
 **Open — `stretch` is a weak control, and it is not obvious what would make it a strong one.** M1
 measured the strain-limit row removing about a third of the peak over-stretch and never reaching its
 own allowance, because it is a second hard row competing with the first for the same trust region and
@@ -1953,11 +2290,36 @@ penalty band, making `k_max/(m/h²)` a material property rather than a global (w
 §4 shows trades stretchiness against settling); or accepting that near-inextensibility is what fabric
 *is* and demoting `stretch` to a documented weak knob. M2's contacts do not bear on it either way.
 
-**Open — the write-back has no interpolation.** §12 gives cloth `PhysicsSystem`'s producer /
-`__interp_restore` contract, and M1 does not wire it: cloth writes `Transform64` at the fixed rate and
-nothing blends between ticks, so a cloth updates at 60 Hz on a 165 Hz display. That is visible and it
-is not wrong — the poses are authoritative, they are simply held. It lands with M5, where the worker
-makes the fixed-step producer contract load-bearing for a second reason.
+**Open — the write-back has no interpolation, and M5 decided it does not land with the worker.** Cloth
+writes `Transform64` at the fixed rate and nothing blends between ticks, so a cloth updates at 60 Hz on
+a 165 Hz display — 105 of every 165 frames repeat a pose. That is visible and it is not wrong: the
+poses are authoritative, they are simply held. **How** visible is now measured, on M3's cape geometry:
+a node covers 0.47 link lengths in a fixed step at a walk and 1.33 at a sprint (`MEASUREMENTS.md` §43).
+
+What M5 changed is the shape of the remaining work, in three findings that between them delete the
+sentence this note used to end with.
+
+- **`PhysicsSystem`'s producer / `__interp_restore` contract cannot express half the feature.**
+  `Interpolated` is an entity-keyed marker and a rigged garment's joints are `Node3D`s, not entities
+  (§13.1). There is nothing to put the component on and no key to file a snapshot under.
+- **Cloth needs only the publish half.** `__interp_restore` undoes render-time writes before the
+  simulation reads them; cloth's state is its particle array and its write-back never touches the
+  anchor it reads, so there is nothing to restore. The restore it *does* depend on — an anchor on a
+  physics-driven character — it already gets from `PhysicsSystem`.
+- **The worker removes the cheap implementation.** A render-time pass cannot read
+  `ClothState.position`, because the worker owns it from dispatch until the next tick's join, which is
+  essentially all of the time outside the fixed pass. What is needed is a **published pose slot**: the
+  last two steps' node poses, copied out at join and blended at render time — the same double-buffered
+  publish slot `WorkerFluidSystem` names as the unbuilt prerequisite for its own render-time reads.
+
+The slot is nearly free to fill, because `cloth_write_back` already computes every node's local TRS
+and would only have to keep it; what costs is the per-frame pass. For the §17 workload that is about
+0.12 ms a frame — 20.5 ms a second at 165 Hz, against the 10.9 ms a second M5 leaves on the main
+thread and the 217 ms a second it cost before. **Interpolating a cloth would roughly triple the main
+thread's share of it and leave it at a seventh of what it was**, which is the honest shape of the
+trade: the feature is affordable because M5 happened, and it is not free. The cloth-shaped version is
+*simpler* than the engine's, not harder: no restore pass, no serialization adapters, no log, and it
+covers the rigged and entity paths identically because both end in a pose per node.
 
 **Open — the subtree is walked once.** A rope's links do not come and go, so `cloth_seed_subtree` runs
 on first step and `ClothSystem#reseed` is how a caller says the structure changed. That is the same