@woosh/meep-engine 3.60.3 → 3.60.5

package/src/engine/ecs/async/WORKER_SYSTEM_PLAN.md

@@ -1,262 +0,0 @@
-# `WorkerSystem` (Design A) — implementation plan
-
-Companion to [`../ASYNC_SYSTEMS_PROPOSAL.md`](../ASYNC_SYSTEMS_PROPOSAL.md). This is the
-SharedArrayBuffer + Atomics variant with a **synchronous hot path**: the `System`
-tick stays synchronous, the worker owns the data between ticks, and a fixed-step
-gate in `EntityManager` keeps exactly one step in flight.
-
-> **Status: implemented.** Where the built code diverged from this plan, the plan
-> has been updated to match — see §6.
-
-First consumer: `WorkerFluidSystem`, a drop-in alternative to `FluidSystem`.
-
----
-
-## 1. Design in one page
-
-Per fixed tick `T`, a `WorkerSystem` does exactly two things:
-
-1. **Join** the outstanding step — the gate has already guaranteed its `DONE`, so
-   this is a load and a hook call, never a wait.
-2. **Dispatch** step `T` — write the command words, `Atomics.store(REQ, T)`,
-   `Atomics.notify`.
-
-Between dispatch and the next join the **worker owns the shared state**. The main
-thread must not touch it. The gate makes that safe for the simulation:
-`EntityManager` refuses to begin a tick while a step is outstanding, so every
-system's `fixedUpdate` runs with the worker idle.
-
-**Exactly one step is in flight**, which is structural rather than a tuning knob.
-The worker mutates shared state in place, so the main thread has nowhere to build
-a second step's input while the first runs; and `REQ` holds a single tick, so a
-second dispatch before the worker consumed the first would overwrite it and
-silently drop a step. A deeper pipeline needs double-buffered payloads and a
-request queue — a different design, not a parameter on this one.
-
-```
-fixed tick:      T                        T+1                      T+2
-main thread:  join(T-1)                join(T)                  join(T+1)
-              dispatch(T)              dispatch(T+1)            dispatch(T+2)
-              ...other systems,        ...other systems,
-                 render, idle...          render, idle...
-worker:          └── steps T ─────────┘  └── steps T+1 ────────┘
-```
-
-Two planes:
-
-- **Hot plane** — `Atomics` over a `SharedArrayBuffer`. Per-tick, zero-copy,
-  zero allocation, no message queue.
-- **Cold plane** — `postMessage`. Structural changes only (register a new field,
-  boot payloads). Rare, and never on the critical path.
-
-Because a futex-parked worker (`Atomics.wait`) does not turn its event loop, cold
-messages would never be delivered while the worker is parked or busy. A `MSG_SEQ`
-counter + `notify` wakes the pump, which yields to the event loop, lets the
-message land, and re-enters via `setTimeout(0)`. The main thread does **not**
-stall on this: newly registered work is simply excluded from dispatch until the
-worker acks it via `ACK_SEQ`.
-
-### Control block (`Int32Array` header at the head of one SAB)
-
-| slot | name | writer | meaning |
-|---|---|---|---|
-| 0 | `REQ` | main | latest dispatched tick |
-| 1 | `DONE` | worker | latest completed tick |
-| 2 | `ERR` | worker | 0 = ok, else the step threw |
-| 3 | `QUIT` | main | 1 = terminate the pump |
-| 4 | `MSG_SEQ` | main | bumped when a cold message is posted |
-| 5 | `ACK_SEQ` | worker | echoes `MSG_SEQ` once handled |
-
-Publication is protocol-ordered, not per-word-atomic: the worker finishes all
-plain writes to the shared payload, *then* seq-cst-stores `DONE`. Main seq-cst-loads
-`DONE ≥ T` *before* reading. That pair is the happens-before edge, so the payload
-itself needs no atomics.
-
-Followed by a `Float64Array` **command region** — per-tick parameters, written by
-main before the `REQ` store, read by the worker after the `REQ` load.
-
-### Deadlock safety
-
-The gate is the one new way to stall the simulation, so every path must be
-provably non-blocking:
-
-| situation | outcome |
-|---|---|
-| worker computing | `DONE` lands → gate opens |
-| step threw | host sets `ERR` **and** `DONE` → gate opens, main disables the system |
-| worker `onerror` / dead | `#failed = true` → gate returns `true` unconditionally |
-| worker never booted | gate is registered *after* the ready handshake; `startup` never resolves, so `fixedUpdate` never runs |
-| **worker hangs or is killed silently** | no `DONE`, no `error` event — caught by a wall-clock deadline (`step_deadline_ms`) that fails the bridge, which opens the gate |
-| shutdown | gate unregistered before terminate |
-| never dispatched (priming, `collect` declined, detached dataset) | nothing in flight → gate returns `true` |
-| `collect` / `apply` throws | `EntityManager` logs it; no dispatch happens that tick, so the gate stays open |
-
-A worker that is merely *slow* costs the bounded spin, then the loop breaks with
-the accumulator loaded.
-
-**A gated system runs at most one fixed step per `simulate()` call.** Once it has
-dispatched, the gate closes for the rest of that cycle, so the fixed rate is
-capped at the rate `simulate()` is called — normally the frame rate. Unlike an
-over-budget main-thread system, which can still run several steps inside the
-15 ms catch-up budget, a gated one cannot repay accumulated debt at all: if the
-worker cannot sustain the fixed step rate, the simulation runs slower than real
-time indefinitely and `__fixedStepAccumulator` grows without bound. This is
-reported once via `console.warn` after `BLOCKED_CYCLES_BEFORE_WARNING`
-consecutive blocked cycles, because the failure is otherwise invisible — the
-fixed loop's own runaway warning sits downstream of the gate's `break` and never
-fires. Fixed step size and per-step worker cost have to be chosen with that
-ceiling in mind.
-
----
-
-## 2. Files
-
-### Framework — `engine/ecs/async/`
-
-| file | contents |
-|---|---|
-| `WorkerSystemProtocol.js` | control-slot enum, sizing, `worker_system_allocate_shared`, spin helper |
-| `WorkerSystem.js` | `WorkerSystem extends System` — lifecycle, hot path, cold path, gate |
-| `SystemWorkerHost.js` | worker-side pump: wait → step → publish, message yield, error capture |
-| `SystemWorkerLoopback.js` | in-process stand-in for a `Worker`, so bridges are testable without a thread |
-| `WorkerSystem.spec.js` | main-thread lifecycle + gate, real SABs, real atomics |
-| `SystemWorkerHost.spec.js` | worker-side pump including the real `Atomics.wait` park |
-
-### Core hook — `engine/ecs/EntityManager.js`
-
-`registerFixedStepGate(gate)` / `unregisterFixedStepGate(gate)` plus one check in
-the fixed loop before `fixedStepTick++`. No other semantics change; when no gate
-is registered the added cost is one `length !== 0` test per step.
-
-### Fluid — `engine/physics/fluid/`
-
-| file | contents |
-|---|---|
-| `FluidField.js` | **modified**: `shared_memory` flag → single-SAB allocation, `getSharedDescriptor()` / `fromSharedDescriptor()` |
-| `ecs/fluid_reanchor_field.js`, `ecs/fluid_build_world_to_grid.js`, `ecs/fluid_gather_visible_effectors.js`, `ecs/fluid_sync_effectors_from_transform.js` | **extracted** from `FluidSystem` so both systems share one implementation rather than two that can drift |
-| `ecs/fluid_worker_protocol.js` | command word layout + enum packing, shared by both sides |
-| `ecs/FluidWorkerCore.js` | worker-side logic — pure, no worker globals, node-testable |
-| `ecs/WorkerFluidSystem.js` | the system |
-| `ecs/fluid.worker.js` | worker entry: `SystemWorkerHost.serve(new FluidWorkerCore())` |
-| `ecs/makeFluidWorker.js` | `new Worker(new URL(...))` factory — **never imported by specs** (`import.meta` is a Jest parse error) |
-| `ecs/WorkerFluidSystem.spec.js` | parity vs `FluidSystem`, ownership, lifecycle |
-
----
-
-## 3. `WorkerFluidSystem` specifics
-
-### Work split
-
-`FluidSimulator.step()` phase 1 is "apply effectors"; phases 2–6 are the solve
-(~80% of which is the pressure Poisson). So:
-
-- **main thread**: reanchor/shift, effector `syncFromTransform`, AABB broad-phase,
-  and `effector.apply(field, dt, world_to_grid)` — arbitrary user-authored
-  effector classes keep running on the main thread, unserialized.
-- **worker**: `sim.step(field, dt, [], IDENTITY)` — the *same* method with an empty
-  effector list, which is exactly phases 2–6.
-
-This needs **zero changes to `FluidSimulator`**, and makes parity exact by
-construction: identical code, identical order, identical float data.
-
-### Memory
-
-`FluidField` gains one opt-in flag. When `shared_memory = true`, `build()` allocates
-a **single** `SharedArrayBuffer` and sub-views every buffer into it (f32 lattices
-first, then the u8 masks, each offset aligned to its element size), so the whole
-field travels as one object on the cold plane. Layout is derived deterministically
-from `(resolution, scalar names, half_precision_pressure)`, so
-`fromSharedDescriptor` recomputes identical offsets rather than shipping a table.
-
-`makeArrayBuffer` is deliberately **not** used: it reads the bare global
-`crossOriginIsolated` (a `ReferenceError` under node) and silently falls back to a
-non-shared `ArrayBuffer`, which for a worker bridge is a silent correctness
-disaster — main and worker would each mutate their own copy. `WorkerFluidSystem`
-instead throws at link time when a field isn't SAB-backed.
-
-### Drop-in scope
-
-Drop-in at the system level: `FluidComponent`, effectors, `FluidObstacleSystem`,
-and the sampling API are untouched. Two things the caller must do:
-
-1. `field.shared_memory = true` before `field.build()` (throws with instructions
-   otherwise).
-2. Supply a worker factory: `new WorkerFluidSystem({ worker_factory: makeFluidWorker })`.
-
-### Ownership contract (the one real semantic difference)
-
-`FluidSystem` leaves the field consistent at all times. `WorkerFluidSystem` leaves
-it worker-owned between dispatch and the next join. Precisely:
-
-- Systems that touch fluid fields must run **earlier in the fixed pass** than
-  `WorkerFluidSystem`. Note this is *not* controlled by registration order: the
-  order is derived from `components_used` (`orderSystemsByDeclaredAccess` — a
-  writer runs before a same-pass reader, and the score picks among free systems
-  and decides which member of a cycle runs first). Two systems touch the field
-  from outside the fluid step. Each is on a cycle with `WorkerFluidSystem`, so
-  the **score** puts it first, and a spec holds each there in both registration
-  orders as a standing assertion — because if the scheduler ever reorders them,
-  the symptom is a silent data race rather than a visible failure:
-  - `FluidObstacleSystem` writes solid masks. It and `WorkerFluidSystem` both read
-    and write `FluidComponent` (20 against 11 in a game-like composition);
-    `WorkerFluidSystem.spec.js` holds it first.
-  - Cloth (`ClothSystem`, `WorkerClothSystem`) reads the velocity field through
-    `ClothFluidWind`, once a tick in `ClothWorld#advance`, and declares that
-    read. It also writes the `Transform64` every fluid system reads, so the edges
-    run both ways (cloth 49 against `WorkerFluidSystem`'s 15);
-    `cloth_wind.spec.js` holds cloth first. Before the read was declared, the
-    `Transform64` edge alone ran it first: measured 2026-10-16 over all four
-    cloth × fluid pairs and a census of every `System` subclass, and declaring
-    it flipped no cloth–fluid pair. There, step `T − 1` has landed (the gate)
-    and step `T` is not yet dispatched, so cloth reads a complete field — under
-    either fluid system the one step `T − 1` left.
-- `update()`-phase and render-phase readers see a step in progress. **Today there
-  are no such readers** — cloth is the one consumer outside the fluid package, and
-  it reads inside the fixed pass, above — so the exposure is zero, but it is a real
-  constraint and is documented on the class. The escape hatch, if a reader ever
-  appears, is a double-buffered publish slot (2× memory, one worker-side copy per
-  step); not built now because it would erase most of the zero-copy win for a
-  hypothetical.
-
-### Latency
-
-One tick (`K = 1`) of visible latency: at tick `T` the field shows the result of
-step `T − 1`. The *sequence* of states is identical to `FluidSystem`'s, only
-observed one tick later.
-
----
-
-## 4. Testing
-
-Real `SharedArrayBuffer`, real `Atomics`, real `FluidSimulator`, real
-`EntityManager`/`EntityComponentDataset`/`Entity`. The only stand-in is the browser
-`Worker` itself — a genuine platform boundary that cannot exist in node, faked by a
-`LoopbackWorker` that implements the same message interface and lets the spec drive
-the real `SystemWorkerHost`/`FluidWorkerCore` pump by hand. All protocol logic,
-atomics, and solver code under test is production code.
-
-Cases:
-
-1. **Protocol** — dispatch/join round trip; `DONE` ordering; `ERR` capture keeps
-   `DONE` advancing; cold message yield + ack.
-2. **Gate** — blocks advancement until the result lands; opens for a failed worker;
-   opens when nothing was dispatched; accumulator retains time on block.
-3. **Parity** — `FluidSystem` and `WorkerFluidSystem` over an identical scene
-   (moving transform, effectors, obstacles) for N ticks produce **bit-identical**
-   fields.
-4. **Ownership** — the field is not mutated by the main thread between dispatch
-   and join.
-5. **Lifecycle** — link/unlink registers/removes fields; non-shared field throws;
-   shutdown settles and terminates.
-
----
-
-## 5. Order of work
-
-1. `WorkerSystemProtocol.js` + `SystemWorkerHost.js` + `WorkerSystem.js`
-2. `EntityManager` gate + spec
-3. `WorkerSystem.spec.js`
-4. `FluidField` shared allocation + spec additions
-5. `fluid_worker_protocol.js`, `FluidWorkerCore.js`, `WorkerFluidSystem.js`, entry + factory
-6. `WorkerFluidSystem.spec.js` (parity is the gate)
-7. Adversarial review, then commit

package/src/engine/ecs/ik/PLAN.md

@@ -1,179 +0,0 @@
-# IK — trees, goals on bones, joints and contacts from physics
-
-> Revision 5, 2026-10-06. **S1–S4 are implemented** (2026-10-06); S5 is later. What implementing
-> it measured or decided beyond this text is in §9. The solver (§2) was accepted at revision 2. Revisions 3–5 settle the components, limits, contacts and clip-driven bones. Each
-> revision went through an adversarial review. Numbers come from one-off probes outside the repo,
-> and every stage re-pins what it relies on with a failing spec first.
-
-## 1. Where it stands (master `c01c0ebbd`)
-
-- `physics/inverse_kinematics/fabrik/` solves one chain, and nothing calls it.
-- The ECS IK (`2BIK`, `1BSA`) reads name-keyed `IKConstraint` lists on an `InverseKinematics`
-  component, and probes `Terrain` directly.
-- **Holds** (`gpu_authority_hold`): a CPU writer takes a joint's `TransformAttachment`. The
-  animation manager mutes every clip binding that names the joint, and `t64_evaluate_world` /
-  `T64WorldCache` read the held offset. Cloth uses this.
-- `two_joint_ik` takes the knee's hinge. The CPU pose twin matches the GPU resolve.
-
-## 2. Solver: frame FABRIK over a tree
-
-**Unchanged.**
-- Every solved joint is a frame: rigid offsets to its children, with its rotation fitted inward
-  (from its old position) and outward. With one child this is the paper's pull.
-- Fits start from the carried rotation, so nothing drifts.
-- A goal's path runs from its effector to its `chain_root`. A link carries the weight of the goals
-  whose path holds both ends, and a `chain_root` takes rotation, never position.
-- The target is `lerp(carried, goal, w)`. Weight 0 gives the same pose as no goal, and the result is
-  continuous in `w`.
-- Two-bone paths use `two_joint_ik`. Twist is held from the animated pose, and the effector's
-  rotation is slerped toward the goal after the solve.
-- Worst error at 16 iterations is 0.005–1.34 mm across the probe cases. The paper's point branches
-  miss by 8–49 mm once written back.
-
-## 3. Components: on the bones, limits from physics
-
-Data lives on the entity it describes, and the tree is the `TransformAttachment` hierarchy. Meep's
-own rig setup puts these components on the bones when the instance is created.
-
-**`IKGoal`, on the effector bone.**
-
-| field | meaning |
-|---|---|
-| `target` | entity id. Its world pose is the goal. |
-| `chain_root` | entity id, an ancestor-or-self of the effector: the highest bone this goal rotates |
-| `position_weight`, `rotation_weight` | 0..1 |
-
-- References are fixed while attached.
-- The goal removes itself when its target or any joint on its path is destroyed, as
-  `TransformAttachment` does when its parent dies.
-- A rejected goal holds nothing. Rejection is a real branch plus an assert, because asserts are
-  stripped in production. A goal is rejected for:
-  - a `chain_root` that is not an ancestor-or-self of the effector;
-  - a target hanging below its own path;
-  - a two-bone path whose knee has no bend side.
-- A target hanging below *another* goal's joints in the same tree (a grip on a weapon held by the
-  other hand) is read from the solver's current frames on every iteration. Convergence is measured
-  in S4.
-- Across groups, dependencies order the solves, and a cycle rejects both groups.
-
-**Joint limits are the physics `Joint` on the bone.** Physics already has this as a 6-DOF
-description (PhysX D6): per-axis `DofMode`, limits, `localBasisA/B`, and two entity ids.
-- On a bone, `entityA` is the parent bone and `entityB` is the bone itself.
-- Asserted at link:
-  - `entityA` equals `TransformAttachment.parent`;
-  - `localBasisA = rest_local · localBasisB`;
-  - `swingTwist` is on. Without it, physics measures angles as 2 sin(θ/2), so limits above 114.6°
-    never engage and physics and IK would disagree.
-- **Hinge** (`asHinge`) gives the knee's `mid_axis`. Its bend side comes from asymmetric limits.
-- **Cone-twist** gives twist on X and separate Y/Z swing, and IK clamps to the same box physics
-  allows.
-- IK ignores anchors, linear DOFs, SPRING and MOTOR.
-- **Shared maths.** `swing_twist_error*` moves from `physics/constraint/solve_constraints.js` to
-  `core/geom/3d/quaternion/`; the clamp is new.
-- **Contract.** Physics simulates a `Joint` only when both sides have a body (or `JOINT_WORLD`).
-  Otherwise it is a kinematic limit. Nothing observes `Joint` today.
-
-**Solver settings** (`max_iterations`, `tolerance`) belong to the system.
-
-## 4. Contacts come from physics
-
-A foot is a joint, the ground is a collider, and contact points are physics' job. IK probes
-nothing: today's terrain prober goes, and nothing here touches `Terrain` or `ClingToTerrain`.
-
-- **A goal that should touch a surface** gets its target from a physics query: a ray or shape cast
-  (`PhysicsSystem.raycast`, `shapeCast`) from a reference the rig provides, returning a
-  `PhysicsSurfacePoint` (position, normal, entity).
-- **The component lives in the physics package.** It is a generic contact-probe component that
-  places its entity at the hit and aligns it to the normal. It knows nothing about IK or feet, so
-  footsteps, decals and AI can use it too. Physics has no query component today;
-  `PhysicsSurfacePoint` was written with "a ground sensor" in mind.
-- **Its contract:**
-  - it exact-evaluates a GPU-composed reference through `T64WorldCache`;
-  - it writes its own attachment offset;
-  - it skips the character's own colliders (same `ParentEntity` root);
-  - it runs in `update`, before IK;
-  - its reference must not be held by IK, or the target would chase IK's output (asserted by the
-    IK side, §3).
-- Pelvis lowering comes later.
-
-## 5. Bones a clip drives: IK holds them
-
-Downstream code (`t64_evaluate_world`, `T64WorldCache`, sockets, cloth anchors, the GPU hierarchy)
-reads the held offset exactly as it reads cloth's, and never learns that IK exists.
-
-- **Link:** hold `TransformAttachment` on every joint of the path, capture the offsets, and write the
-  evaluated base pose at once, so no frame shows the bind pose.
-- **Every tick:** write each held joint's full local: translation, rotation and scale, since a hold
-  mutes every channel. The base comes from `pose_evaluate_local`, never from a held offset.
-- **Unlink:** write the captured offset back, then unhold, guarded by `entityExists`.
-- **One holder per joint:** IK on a cloth-held joint trips the existing assert.
-- **Cost:** 37 / 127 / 531 µs per character per tick at 2 / 8 / 30 registered clips (34 levels),
-  because every level scans every channel of every clip.
-- **Ordering:** IK declares what it reads, `Animation` and `AnimationGraphController`. The drivers
-  declare that they write them. With the scheduler fixed (below), IK then runs after the drivers.
-  Cloth needs no order against IK: it runs in `fixedUpdate` on the previous update's consistent
-  state.
-
-## 6. Prerequisites (separate tasks)
-
-1. **Holds: LANDED** (`84f2f7267`, `c01c0ebbd`). A clip that binds during a hold takes the rest the holder
-   leaves when the hold ends, and that offset reaches the row.
-2. **Pose evaluator:** index channels by target (the cost row above). Sockets and cloth gain too.
-3. **Scheduler:** a system that reads X and writes Y sorts before the writer of X. Measured with
-   synthetic components: Producer (X) and Consumer (X → Y) order as `Consumer > Producer` in both
-   registration orders. `system_execution_order.spec.js` covers only a pure reader. The fix stays
-   inside derived ordering.
-
-## 7. Stages
-
-Each stage is red-then-green.
-
-1. **S1 Frame FABRIK:** a pure solver over typed arrays.
-2. **S2 Two-bone paths:** `two_joint_ik` with the hinge read from the `Joint`.
-3. **S3 Limits:** the shared swing-twist maths, the clamp, and `Joint` frames inside the passes.
-4. **S4 ECS, landing together:**
-   - `IKGoal` and its system (groups, holds, base evaluation, target reads, declarations);
-   - the physics contact-probe component;
-   - in the same change, `InverseKinematics`, `IKConstraint`, `2BIK`, `1BSA`, the terrain prober
-     and the adapter go (hard break).
-5. **S5 Later:** pelvis lowering, twist distribution, goal priority, pole goals.
-
-## 8. Sources
-
-- [A] Aristidou, Chrysanthou, Lasenby, *Extending FABRIK with model constraints*, CAVW 2016
-- [C] Aristidou, Lasenby, *FABRIK*, Graphical Models 73, 2011
-- [D] Baerlocher, Boulic, *Parametrization and range of motion of the ball-and-socket joint*, 2001
-- [G] UE 5.4 source: `Plugins/Experimental/FullBodyIK/Source/PBIK/`, `AnimNode_FootPlacement`
-- [N] ozz-animation `ik_two_bone_job.h`, `samples/foot_ik/sample_foot_ik.cc`
-
-## 9. After implementation (2026-10-06)
-
-Measured while implementing S1–S4, and decided with the owner where it changed anything.
-
-- **The fit** is 8 steps of power iteration warm-started from the carried rotation: 110–130 ns a fit
-  against 610–790 ns for the exact Jacobi fit, which also turns the chest about its shoulder line
-  from rounding (a 40–175° bend at the chest joint, converged, where the warm start bends 0–54°).
-- **The 0/0** of this mechanism is a target on the effector's parent, at any bone lengths: the parent
-  is fitted toward a child sitting on its old position. A target at a limb's top with equal bones is
-  finite and reached. A straight arm turned only at the shoulder, its target exactly on the elbow,
-  has no side to fold to and stays (finite); 1e-12 m off, it reaches.
-- **An effector inside another goal's path** (a goal on the elbow under a goal on the hand) is one
-  more proposal in its joint's mean, weighted by its goal's weight (owner's decision; pinning it at
-  its target moved the pose 161 mm at weight 0). Weight 0 is no goal, 0.001 moves it 0.05 mm, and two
-  equal goals that disagree meet half way.
-- **`FrameFabrikProblem` takes `base_local_rotation`**: a goal's root is limited against its
-  parent's fixed frame, which world rotations alone do not give.
-- **A hinge alone on a longer path can lock**: the arc fits never twist the shoulder to bring an
-  elbow's hinge plane round, so a target off it left the arm straight, 350 / 334 mm short; a
-  cone-twist on the shoulder unlocks it (1.4 mm at 16 iterations, 0 at 64). Hinges also slow a grip
-  pair down: 65 / 220 mm at 16 iterations, 0 at 64. Two-bone paths are analytic and unaffected.
-  Stated, not fixed.
-- **"Below its own path"** means the deepest posed bone the target hangs from is a bone of the goal's
-  own path. A grip on a weapon in the other hand hangs below the gripping hand's own chest too, but
-  the other arm's bones carry it, so it is read from the solver's frames. Known only with every goal,
-  so it is found when the groups are formed; a target below the effector itself is refused at link.
-- **The contact probe** casts a sphere of `radius`, a ray at 0. It and IK both read and write
-  `TransformAttachment`, so declared access leaves them a cycle and the scheduler keeps their
-  registration order: the probe is registered first (owner's decision). That its reference must not
-  be held by a CPU writer is documented on `ContactProbe`, not asserted (owner's decision): IK cannot
-  check it without knowing the probe's component.