@driftengine/physics 3.61.1 → 3.61.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/physics",
-  "version": "3.61.1",
+  "version": "3.61.2",
   "description": "Collision shapes, spatial queries and swept kinematic collision",
   "license": "Apache-2.0",
   "type": "module",
@@ -21,6 +21,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.mjs",
     "!src/**/__snapshots__",
+    "scripts",
     "README.md",
     "LICENSE",
     "NOTICE"

package/scripts/decompose-check.ts

@@ -0,0 +1,551 @@
+/**
+ * That convex decomposition produces hulls worth having, on meshes generated here.
+ *
+ * **No asset, no GPU, no network** — every mesh is built by this file, so the check runs anywhere
+ * and is the same run twice. The meshes are not a sample of what people import; each one is chosen
+ * because it breaks a different assumption a decomposition can be built on.
+ *
+ * | Mesh | What it is for |
+ * |---|---|
+ * | Prism | Convex already. The answer is one part, and anything else means the merge cannot recognise a solid it need not divide |
+ * | L-beam | The simplest concave solid. Two parts is the right answer and its bloat should be nothing at all |
+ * | Cup | A cavity, open at the top. The decomposition that fills it passes every count-based check and is useless |
+ * | Torus | A hole straight through, which is what defeats a fill that assumes a watertight surface |
+ * | Staircase | Ten steps against a budget of eight, so the merge has to choose which to join |
+ *
+ * **Two numbers carry the result and they fail in opposite directions.** `bloat` is the empty space
+ * the hulls added: a single hull of a cup has an enormous one. `coverage` is the fraction of the
+ * solid that ended up inside its own part: support sampling can only lose material, never add it,
+ * so this is the other side of the same ledger. A decomposition is good when both are small
+ * departures from their ideals, and a check that watched only one of them would pass a hull that
+ * swallowed the cavity or a hull that had shrunk away from the thing it stands for.
+ *
+ * **The resolution sweep is the assertion, not a detail.** Every one of these bounds held at a
+ * single resolution while the fill was silently leaking, because the leak inflated the source
+ * volume as much as it inflated the hulls. Running eight resolutions is what made the defect
+ * visible: the answers were correct at four of them and wrong at the other four, with nothing in
+ * the shapes to explain which.
+ *
+ *     npx tsx packages/physics/scripts/decompose-check.ts
+ */
+
+import { BODY_DYNAMIC, BODY_STATIC } from '../src/bodies.ts';
+import { PhysicsWorld } from '../src/world.ts';
+import { boxShape, sphereShape } from '../src/shape.ts';
+import { meshShape } from '../src/meshShape.ts';
+import { decomposeConvex } from '../src/decompose.ts';
+import type { ConvexPart, Decomposition } from '../src/decompose.ts';
+import { hullShape } from '../src/shape.ts';
+
+interface Mesh {
+  readonly positions: number[];
+  readonly indices: number[];
+}
+
+function emptyMesh(): Mesh {
+  return { positions: [], indices: [] };
+}
+
+/** A box, as twelve triangles, appended to a mesh already under construction. */
+function addBox(
+  mesh: Mesh,
+  cx: number,
+  cy: number,
+  cz: number,
+  hx: number,
+  hy: number,
+  hz: number,
+): void {
+  const base = mesh.positions.length / 3;
+  for (let i = 0; i < 8; i++) {
+    mesh.positions.push(cx + (i & 1 ? hx : -hx), cy + (i & 2 ? hy : -hy), cz + (i & 4 ? hz : -hz));
+  }
+  const faces = [
+    [0, 2, 3, 1],
+    [4, 5, 7, 6],
+    [0, 1, 5, 4],
+    [2, 6, 7, 3],
+    [0, 4, 6, 2],
+    [1, 3, 7, 5],
+  ];
+  for (const face of faces) {
+    const [a, b, c, d] = face as [number, number, number, number];
+    mesh.indices.push(base + a, base + b, base + c, base + a, base + c, base + d);
+  }
+}
+
+/** A ring of `sides` points at a radius and a height, returning its first index. */
+function addRing(mesh: Mesh, sides: number, radius: number, y: number): number {
+  const base = mesh.positions.length / 3;
+  for (let i = 0; i < sides; i++) {
+    const angle = (i / sides) * Math.PI * 2;
+    mesh.positions.push(Math.cos(angle) * radius, y, Math.sin(angle) * radius);
+  }
+  return base;
+}
+
+function addQuad(mesh: Mesh, a: number, b: number, c: number, d: number): void {
+  mesh.indices.push(a, b, c, a, c, d);
+}
+
+/** A wall between two rings wound the same way, seen from outside the lower one. */
+function addTube(mesh: Mesh, sides: number, lo: number, hi: number): void {
+  for (let i = 0; i < sides; i++) {
+    const j = (i + 1) % sides;
+    addQuad(mesh, lo + i, lo + j, hi + j, hi + i);
+  }
+}
+
+/** A closed n-gon prism: the side wall and a fan closing each end. */
+function prismMesh(sides: number, radius: number, height: number): Mesh {
+  const mesh = emptyMesh();
+  const lo = addRing(mesh, sides, radius, 0);
+  const hi = addRing(mesh, sides, radius, height);
+  addTube(mesh, sides, lo, hi);
+  const centreLo = mesh.positions.length / 3;
+  mesh.positions.push(0, 0, 0);
+  const centreHi = mesh.positions.length / 3;
+  mesh.positions.push(0, height, 0);
+  for (let i = 0; i < sides; i++) {
+    const j = (i + 1) % sides;
+    mesh.indices.push(centreLo, lo + j, lo + i);
+    mesh.indices.push(centreHi, hi + i, hi + j);
+  }
+  return mesh;
+}
+
+/** Two boxes meeting at a corner. The one shape whose right answer is not in doubt. */
+function lBeamMesh(): Mesh {
+  const mesh = emptyMesh();
+  addBox(mesh, 0, 0, 0, 1, 0.25, 0.25);
+  addBox(mesh, -0.75, 0.75, 0, 0.25, 0.5, 0.25);
+  return mesh;
+}
+
+/** A cup: an outer wall, a cavity open at the top, and a floor between them. */
+function cupMesh(sides: number, outer: number, inner: number, height: number, floor: number): Mesh {
+  const mesh = emptyMesh();
+  const outerLo = addRing(mesh, sides, outer, 0);
+  const outerHi = addRing(mesh, sides, outer, height);
+  const innerLo = addRing(mesh, sides, inner, floor);
+  const innerHi = addRing(mesh, sides, inner, height);
+  addTube(mesh, sides, outerLo, outerHi);
+  addTube(mesh, sides, innerHi, innerLo);
+  const centreLo = mesh.positions.length / 3;
+  mesh.positions.push(0, 0, 0);
+  const centreFloor = mesh.positions.length / 3;
+  mesh.positions.push(0, floor, 0);
+  for (let i = 0; i < sides; i++) {
+    const j = (i + 1) % sides;
+    mesh.indices.push(centreLo, outerLo + j, outerLo + i);
+    mesh.indices.push(centreFloor, innerLo + i, innerLo + j);
+    addQuad(mesh, outerHi + i, outerHi + j, innerHi + j, innerHi + i);
+  }
+  return mesh;
+}
+
+/** A torus, as a grid of quads. A hole through the middle and no end caps to close. */
+function torusMesh(major: number, minor: number, ringCount: number, sides: number): Mesh {
+  const mesh = emptyMesh();
+  for (let r = 0; r < ringCount; r++) {
+    const a = (r / ringCount) * Math.PI * 2;
+    const cx = Math.cos(a) * major;
+    const cz = Math.sin(a) * major;
+    for (let s = 0; s < sides; s++) {
+      const b = (s / sides) * Math.PI * 2;
+      const radial = major + Math.cos(b) * minor;
+      mesh.positions.push(Math.cos(a) * radial, Math.sin(b) * minor, Math.sin(a) * radial);
+    }
+    void cx;
+    void cz;
+  }
+  for (let r = 0; r < ringCount; r++) {
+    const rn = (r + 1) % ringCount;
+    for (let s = 0; s < sides; s++) {
+      const sn = (s + 1) % sides;
+      addQuad(mesh, r * sides + s, rn * sides + s, rn * sides + sn, r * sides + sn);
+    }
+  }
+  return mesh;
+}
+
+/** Ten steps rising along x, each a box. More parts than the budget, on purpose. */
+function stairsMesh(steps: number): Mesh {
+  const mesh = emptyMesh();
+  for (let i = 0; i < steps; i++) {
+    const height = (i + 1) * 0.1;
+    addBox(mesh, i * 0.2 - 1, height * 0.5, 0, 0.1, height * 0.5, 0.5);
+  }
+  return mesh;
+}
+
+interface Bound {
+  readonly maxParts: number;
+  /**
+   * The most the parts' volumes may add up to beyond the source, as a fraction of it.
+   *
+   * **This one double-counts wherever two hulls overlap, and that is deliberate**: it is the number
+   * a body's mass is computed from, because `combineMassProperties` sums the parts. `maxBulge` below
+   * is the same measurement without the double count, and the two differ by a lot on exactly the
+   * shapes where the parts pile up on each other.
+   */
+  readonly maxBloat: number;
+  /** The most space the parts occupy **together**, counting shared space once. */
+  readonly maxBulge: number;
+  /** The least of the solid that must end up inside its own part. */
+  readonly minCoverage: number;
+}
+
+/**
+ * The volume the parts occupy together, by sampling, counting shared space once.
+ *
+ * **Measured at one resolution per mesh rather than at all eight**, because it costs a grid of
+ * samples against every part and the summed figure is what moves with resolution anyway. What it is
+ * here to catch is the case the sum cannot distinguish: parts that pile up on each other read as
+ * enormous bloat while the collider they form is tight, and a decomposition should not be failed
+ * for that.
+ */
+function bulgeOf(parts: readonly ConvexPart[], samples: number): number {
+  const shapes = parts.map((part) => hullShape(part.points));
+  let minX = Infinity,
+    minY = Infinity,
+    minZ = Infinity;
+  let maxX = -Infinity,
+    maxY = -Infinity,
+    maxZ = -Infinity;
+  for (const shape of shapes) {
+    for (let i = 0; i < shape.vertices.length; i += 3) {
+      minX = Math.min(minX, shape.vertices[i] as number);
+      maxX = Math.max(maxX, shape.vertices[i] as number);
+      minY = Math.min(minY, shape.vertices[i + 1] as number);
+      maxY = Math.max(maxY, shape.vertices[i + 1] as number);
+      minZ = Math.min(minZ, shape.vertices[i + 2] as number);
+      maxZ = Math.max(maxZ, shape.vertices[i + 2] as number);
+    }
+  }
+  const inside = (shape: (typeof shapes)[number], x: number, y: number, z: number): boolean => {
+    const planes = shape.facePlanes;
+    for (let i = 0; i + 3 < planes.length; i += 4) {
+      const d =
+        (planes[i] as number) * x +
+        (planes[i + 1] as number) * y +
+        (planes[i + 2] as number) * z -
+        (planes[i + 3] as number);
+      if (d > 1e-9) return false;
+    }
+    return true;
+  };
+  let hits = 0;
+  for (let ix = 0; ix < samples; ix++) {
+    const x = minX + ((ix + 0.5) / samples) * (maxX - minX);
+    for (let iy = 0; iy < samples; iy++) {
+      const y = minY + ((iy + 0.5) / samples) * (maxY - minY);
+      for (let iz = 0; iz < samples; iz++) {
+        const z = minZ + ((iz + 0.5) / samples) * (maxZ - minZ);
+        for (const shape of shapes) {
+          if (inside(shape, x, y, z)) {
+            hits++;
+            break;
+          }
+        }
+      }
+    }
+  }
+  return (hits / (samples * samples * samples)) * (maxX - minX) * (maxY - minY) * (maxZ - minZ);
+}
+
+const RESOLUTIONS = [32, 40, 48, 56, 64, 72, 80, 96];
+
+const CASES: readonly {
+  name: string;
+  mesh: Mesh;
+  maxHulls: number;
+  bound: Bound;
+}[] = [
+  {
+    name: 'prism (convex)',
+    mesh: prismMesh(24, 1, 1),
+    maxHulls: 8,
+    /*
+     * **One part, and this is the control for everything below.** A convex solid needs no
+     * decomposition, so a run that returns two has a merge which cannot see that it is finished —
+     * and every bloat figure on a concave mesh would then be measuring the wrong thing.
+     */
+    bound: { maxParts: 1, maxBloat: 0.2, maxBulge: 0.2, minCoverage: 0.93 },
+  },
+  {
+    name: 'L-beam',
+    mesh: lBeamMesh(),
+    maxHulls: 8,
+    bound: { maxParts: 2, maxBloat: 0.02, maxBulge: 0.02, minCoverage: 0.99 },
+  },
+  {
+    name: 'cup (cavity)',
+    mesh: cupMesh(24, 1, 0.75, 1, 0.25),
+    maxHulls: 16,
+    /*
+     * **The bound that decides whether this row shipped anything.** Filling the cavity roughly
+     * doubles the volume the hulls hold, so anything near 1.0 here is a decomposition that has
+     * produced a solid cylinder and called it a cup. Ten per cent leaves room for the staircase the
+     * cells make of a curved wall and no room at all for the failure.
+     */
+    bound: { maxParts: 16, maxBloat: 0.1, maxBulge: 0.06, minCoverage: 0.9 },
+  },
+  {
+    name: 'torus (hole)',
+    mesh: torusMesh(1, 0.35, 32, 16),
+    maxHulls: 16,
+    /*
+     * **The loosest bounds here, and they are the measurement rather than an aspiration.** A fat
+     * curved tube is the worst case for a decomposition seeded from axis-aligned boxes: every hull
+     * chords the ring it follows, and the budget is not what limits it — the same torus measures
+     * 26.7% at eight parts and 20.6% at thirty-two, so the parts are not the constraint and neither
+     * is the merge, which reaches the same figure with its tail switched off entirely.
+     *
+     * The two numbers are far apart here for the reason `maxBloat` explains: **27.0% summed against
+     * 16.2% occupied**, so eleven points of it is the same space counted twice where neighbouring
+     * hulls overlap. The collider bulges by a sixth; the mass computed from it is out by a quarter.
+     *
+     * *What would improve it* is seeds that follow curvature instead of the axes, or splitting by
+     * fitted planes instead of merging boxes. `docs/IMPROVEMENTS.md` carries that.
+     */
+    bound: { maxParts: 16, maxBloat: 0.32, maxBulge: 0.2, minCoverage: 0.88 },
+  },
+  {
+    name: 'staircase',
+    mesh: stairsMesh(10),
+    maxHulls: 8,
+    bound: { maxParts: 8, maxBloat: 0.2, maxBulge: 0.15, minCoverage: 0.95 },
+  },
+];
+
+function report(d: Decomposition): string {
+  const points = d.parts.map((p) => p.points.length / 3);
+  return (
+    `${String(d.parts.length).padStart(2)} parts  ` +
+    `bloat ${(d.bloat * 100).toFixed(1).padStart(6)}%  ` +
+    `coverage ${(d.coverage * 100).toFixed(1).padStart(5)}%  ` +
+    `points ${String(Math.max(...points)).padStart(2)}`
+  );
+}
+
+let failures = 0;
+const fail = (message: string): void => {
+  failures++;
+  console.log(`  FAIL  ${message}`);
+};
+
+console.log('Convex decomposition, on meshes this file generates.\n');
+
+for (const testCase of CASES) {
+  console.log(`${testCase.name}  (budget ${testCase.maxHulls})`);
+  let worstBloat = -Infinity;
+  let worstCoverage = Infinity;
+  let mostParts = 0;
+  let mostPoints = 0;
+
+  for (const resolution of RESOLUTIONS) {
+    const d = decomposeConvex(testCase.mesh.positions, testCase.mesh.indices, {
+      resolution,
+      maxHulls: testCase.maxHulls,
+    });
+    console.log(`  res ${String(resolution).padStart(2)}  ${report(d)}`);
+    worstBloat = Math.max(worstBloat, d.bloat);
+    worstCoverage = Math.min(worstCoverage, d.coverage);
+    mostParts = Math.max(mostParts, d.parts.length);
+    for (const part of d.parts) mostPoints = Math.max(mostPoints, part.points.length / 3);
+  }
+
+  /* The occupied volume, once, at the middle of the sweep. */
+  const middle = decomposeConvex(testCase.mesh.positions, testCase.mesh.indices, {
+    resolution: 64,
+    maxHulls: testCase.maxHulls,
+  });
+  const bulge = (bulgeOf(middle.parts, 110) - middle.sourceVolume) / middle.sourceVolume;
+  console.log(
+    `  res 64  occupied together: ${(bulge * 100).toFixed(1)}% over the source, ` +
+      `against ${(middle.bloat * 100).toFixed(1)}% summed`,
+  );
+
+  const { bound } = testCase;
+  if (bulge > bound.maxBulge) {
+    fail(
+      `${testCase.name}: the parts occupy ${(bulge * 100).toFixed(1)}% over the source, against a ` +
+        `bound of ${(bound.maxBulge * 100).toFixed(0)}%`,
+    );
+  }
+  if (mostParts > bound.maxParts) {
+    fail(`${testCase.name}: ${mostParts} parts against a bound of ${bound.maxParts}`);
+  }
+  if (worstBloat > bound.maxBloat) {
+    fail(
+      `${testCase.name}: bloat ${(worstBloat * 100).toFixed(1)}% against a bound of ` +
+        `${(bound.maxBloat * 100).toFixed(0)}%`,
+    );
+  }
+  if (worstCoverage < bound.minCoverage) {
+    fail(
+      `${testCase.name}: coverage ${(worstCoverage * 100).toFixed(1)}% against a bound of ` +
+        `${(bound.minCoverage * 100).toFixed(0)}%`,
+    );
+  }
+  /*
+   * **`hullShape` refuses more than 64 points**, so a part that reached it would not be a poor hull
+   * — it would be an exception at the moment somebody tried to use the decomposition. The direction
+   * set caps this by construction and the bound is here to say so if that ever stops being true.
+   */
+  if (mostPoints > 64)
+    fail(`${testCase.name}: a part carries ${mostPoints} points, over hullShape's 64`);
+  console.log('');
+}
+
+/*
+ * **Determinism, run twice in one process and compared byte for byte.** The merge is a heap over
+ * candidate pairs and a heap without a tie-break orders equal costs by insertion, so two runs that
+ * inserted in a different order would decompose the same mesh differently. Nothing else in this
+ * check would notice: every bound above is a summary statistic and would hold on either answer.
+ */
+{
+  const mesh = cupMesh(24, 1, 0.75, 1, 0.25);
+  const a = decomposeConvex(mesh.positions, mesh.indices, { resolution: 48 });
+  const b = decomposeConvex(mesh.positions, mesh.indices, { resolution: 48 });
+  let identical = a.parts.length === b.parts.length;
+  for (let i = 0; identical && i < a.parts.length; i++) {
+    const pa = a.parts[i] as { points: Float32Array };
+    const pb = b.parts[i] as { points: Float32Array };
+    identical = pa.points.length === pb.points.length;
+    for (let k = 0; identical && k < pa.points.length; k++) {
+      identical = pa.points[k] === pb.points[k];
+    }
+  }
+  console.log(`determinism: two runs of the cup agree ${identical ? 'exactly' : 'NOT AT ALL'}`);
+  if (!identical) fail('two runs of the same mesh produced different hulls');
+}
+
+/*
+ * **The fill, measured against a volume that is known rather than reported.** A closed prism's
+ * volume has a closed form, and the check that the voxelised source approaches it from above is the
+ * one that would have caught the tangency defect on the day it was written: a leaking fill answers
+ * with the shell, which is a small fraction of the solid and shrinks as the cells do.
+ */
+{
+  const sides = 24;
+  const mesh = prismMesh(sides, 1, 1);
+  const exact = 0.5 * sides * Math.sin((Math.PI * 2) / sides);
+  console.log(`\nfill against the closed form (${exact.toFixed(4)}):`);
+  let worst = 0;
+  for (const resolution of RESOLUTIONS) {
+    const d = decomposeConvex(mesh.positions, mesh.indices, { resolution, maxHulls: 8 });
+    const ratio = d.sourceVolume / exact;
+    console.log(
+      `  res ${String(resolution).padStart(2)}  ${d.sourceVolume.toFixed(4)}  ${ratio.toFixed(3)}x`,
+    );
+    if (ratio < 1)
+      fail(
+        `res ${resolution}: the fill answered ${ratio.toFixed(3)}x, below the solid it rasterised`,
+      );
+    worst = Math.max(worst, ratio);
+  }
+  if (worst > 1.25)
+    fail(`the fill over-marks by ${worst.toFixed(3)}x, more than a cell of surface explains`);
+}
+
+/*
+ * **What a volume figure cannot say.** Everything above measures the hulls against the mesh; nothing
+ * above measures whether a body made of them behaves like the thing it stands for. A decomposition
+ * that quietly filled a cavity would pass a bloat bound set a little too loose and fail here by a
+ * whole ball radius.
+ */
+{
+  console.log('\nA ball dropped into the cup, against the same cup as one hull:');
+  const mesh = cupMesh(24, 1, 0.75, 1, 0.25);
+  const rest = (maxHulls: number): number => {
+    const d = decomposeConvex(mesh.positions, mesh.indices, { resolution: 64, maxHulls });
+    const shapes = d.parts.map((part) => hullShape(part.points));
+    const world = new PhysicsWorld();
+    if (shapes.length === 1)
+      world.addBody({ type: BODY_STATIC, shape: shapes[0] as ReturnType<typeof hullShape> });
+    else world.addBody({ type: BODY_STATIC, shapes });
+    const ball = world.addBody({ type: BODY_DYNAMIC, shape: sphereShape(0.4), y: 2.2 });
+    for (let i = 0; i < 400; i++) world.step(1 / 120);
+    return world.bodies.posY[ball] ?? 0;
+  };
+  const decomposed = rest(16);
+  const single = rest(1);
+  console.log(`  decomposed: rests at y = ${decomposed.toFixed(3)}`);
+  console.log(`  one hull:   rests at y = ${single.toFixed(3)}`);
+  /*
+   * **The claim is where the ball comes to rest, not merely that it is low**, and the difference is
+   * a mutation that passed. "Below the rim" was the first wording, and a compound whose narrow phase
+   * only ever looked at part 0 satisfied it by dropping the ball through the world to **y = -52.3**:
+   * below the rim, comfortably separated from the control, and the feature entirely absent.
+   *
+   * The cavity floor is at 0.25 and the ball's radius is 0.4, so a ball the cup actually holds rests
+   * at 0.65. The rim is at 1.0, so one held out rests at 1.4.
+   */
+  if (Math.abs(decomposed - 0.65) > 0.15) {
+    fail(`the ball rests at ${decomposed.toFixed(3)}, and the cup's floor would hold it at 0.65`);
+  }
+  if (Math.abs(single - 1.4) > 0.15) {
+    fail(`the control ball rests at ${single.toFixed(3)}, and the rim would hold it at 1.4`);
+  }
+  if (!(single - decomposed > 0.4)) {
+    fail(
+      `the two rest heights differ by ${(single - decomposed).toFixed(3)}, which decides nothing`,
+    );
+  }
+}
+
+/*
+ * **And the manifold budget, which nothing else here would notice.** A compound against a mesh
+ * shares one set of contact planes between its parts. Giving the whole budget to whichever part is
+ * tried first leaves the far parts with no plane at all, and the body tips — on a *box* floor every
+ * part gets a plane by construction, so the two floors are the same scene reached twice.
+ */
+{
+  console.log('\nA decomposed staircase settling on a mesh floor, against a box floor:');
+  const stairs = stairsMesh(10);
+  const d = decomposeConvex(stairs.positions, stairs.indices, { resolution: 48, maxHulls: 8 });
+  const shapes = d.parts.map((part) => hullShape(part.points));
+  const settle = (onMesh: boolean): { y: number; tilt: number } => {
+    const world = new PhysicsWorld();
+    if (onMesh) {
+      const floor: number[] = [];
+      const index: number[] = [];
+      for (let i = 0; i < 4; i++) {
+        floor.push(i & 1 ? 6 : -6, 0, i & 2 ? 6 : -6);
+      }
+      index.push(0, 2, 1, 1, 2, 3);
+      world.addBody({
+        type: BODY_STATIC,
+        shape: meshShape(new Float32Array(floor), new Uint32Array(index)),
+      });
+    } else {
+      world.addBody({ type: BODY_STATIC, shape: boxShape(6, 0.5, 6), y: -0.5 });
+    }
+    const body = world.addBody({ type: BODY_DYNAMIC, shapes, y: 1.5 });
+    for (let i = 0; i < 600; i++) world.step(1 / 120);
+    const qx = world.bodies.rotX[body] ?? 0;
+    const qz = world.bodies.rotZ[body] ?? 0;
+    return { y: world.bodies.posY[body] ?? 0, tilt: Math.sqrt(qx * qx + qz * qz) };
+  };
+  const onMesh = settle(true);
+  const onBox = settle(false);
+  console.log(`  mesh floor: y = ${onMesh.y.toFixed(4)}  tilt = ${onMesh.tilt.toFixed(4)}`);
+  console.log(`  box floor:  y = ${onBox.y.toFixed(4)}  tilt = ${onBox.tilt.toFixed(4)}`);
+  /* The solver's own slop is 5 mm, so that is what "the same" means here. */
+  if (Math.abs(onMesh.y - onBox.y) > 0.005) {
+    fail(
+      `the staircase settles ${Math.abs(onMesh.y - onBox.y).toFixed(4)} apart on the two floors, ` +
+        'so parts are being crowded out of the manifold budget',
+    );
+  }
+  if (Math.abs(onMesh.tilt - onBox.tilt) > 0.02) {
+    fail(
+      `the staircase tilts differently on the two floors: ${onMesh.tilt.toFixed(4)} against ${onBox.tilt.toFixed(4)}`,
+    );
+  }
+}
+
+console.log(failures === 0 ? '\nAll bounds held.' : `\n${failures} bound(s) failed.`);
+process.exit(failures === 0 ? 0 : 1);

package/scripts/island-bench.ts

@@ -0,0 +1,235 @@
+/**
+ * What the island solve costs, and what a worker pool behind the executor seam could take off it.
+ *
+ * **`executor.ts` says the pool's threshold is a measurement, and this is that measurement.** It is
+ * a benchmark rather than a test: nothing here asserts, because a wall-clock number on one machine
+ * is evidence rather than a contract. `npm run bench:islands`.
+ *
+ * It prints three things a decision needs:
+ *
+ * 1. **How much of a tick is the island solve.** That is the fraction a pool can touch at all, and
+ *    Amdahl's law caps every speedup at it.
+ * 2. **How many islands a world actually has.** The parallelism is `min(workers, islands)` — never
+ *    the body count, which is what `executor.ts`'s own comment named and which is wrong: a
+ *    thousand-box tower is one island and a pool can do nothing with it.
+ * 3. **What one island costs**, against the handshake a fork-join pays.
+ */
+import { BODY_DYNAMIC, BODY_STATIC } from '../src/bodies';
+import type { Executor, IslandSolver } from '../src/executor';
+import { JOINT_DISTANCE } from '../src/joints';
+import { boxShape } from '../src/shape';
+import { PhysicsWorld } from '../src/world';
+import { createIslandPool } from '../src/workers';
+import { Worker } from 'node:worker_threads';
+
+/** The real entry point, spawned the way Node spawns one. A browser uses the package default. */
+const spawn = () =>
+  new Worker(new URL('../src/islandWorker.ts', import.meta.url)) as unknown as {
+    postMessage(value: unknown): void;
+    terminate(): void | Promise<number>;
+  };
+
+const DT = 1 / 60;
+
+/** A serial runner that also records how long the islands took and how many there were. */
+class TimingExecutor implements Executor {
+  readonly name = 'timing';
+  totalUs = 0;
+  ticks = 0;
+  islands = 0;
+
+  run(count: number, solver: IslandSolver): void {
+    const started = performance.now();
+    for (let i = 0; i < count; i++) solver.solveIsland(i);
+    this.totalUs += (performance.now() - started) * 1000;
+    this.ticks += 1;
+    this.islands = count;
+  }
+
+  reset(): void {
+    this.totalUs = 0;
+    this.ticks = 0;
+  }
+}
+
+/** `stacks` towers of `high` boxes, spaced far enough apart that each tower is its own island. */
+function build(stacks: number, high: number): { world: PhysicsWorld; timer: TimingExecutor } {
+  const world = new PhysicsWorld({ allowSleep: false });
+  const timer = new TimingExecutor();
+  world.executor = timer;
+  world.addBody({ type: BODY_STATIC, shape: boxShape(2000, 1, 2000), y: -1, friction: 0.8 });
+  for (let s = 0; s < stacks; s++) {
+    for (let i = 0; i < high; i++) {
+      world.addBody({
+        type: BODY_DYNAMIC,
+        shape: boxShape(0.5, 0.5, 0.5),
+        x: s * 6,
+        y: 0.5 + i * 1.02,
+        density: 500,
+        friction: 0.8,
+      });
+    }
+  }
+  return { world, timer };
+}
+
+/**
+ * A hundred boxes strung together by joints, which is **one island** by definition.
+ *
+ * A tall tower would have been the obvious shape and is the wrong one: it topples inside a second
+ * and becomes seventy islands, which measures the opposite of what it was built to show. Joints put
+ * bodies in one island whatever they then do.
+ */
+function chain(links: number): { world: PhysicsWorld; timer: TimingExecutor } {
+  const world = new PhysicsWorld({ allowSleep: false });
+  const timer = new TimingExecutor();
+  world.executor = timer;
+  world.addBody({ type: BODY_STATIC, shape: boxShape(2000, 1, 2000), y: -1, friction: 0.8 });
+  let previous = -1;
+  for (let i = 0; i < links; i++) {
+    const body = world.addBody({
+      type: BODY_DYNAMIC,
+      shape: boxShape(0.3, 0.3, 0.3),
+      x: i * 0.8,
+      y: 4,
+      density: 500,
+      friction: 0.8,
+    });
+    if (previous >= 0) {
+      world.addJoint({ type: JOINT_DISTANCE, bodyA: previous, bodyB: body, length: 0.8 });
+    }
+    previous = body;
+  }
+  return { world, timer };
+}
+
+function report(world: PhysicsWorld, timer: TimingExecutor, bodies: number): void {
+  for (let i = 0; i < 60; i++) world.step(DT);
+  timer.reset();
+  const runs = 180;
+  const started = performance.now();
+  for (let i = 0; i < runs; i++) world.step(DT);
+  const tick = ((performance.now() - started) / runs) * 1000;
+  const solve = timer.totalUs / timer.ticks;
+  const perIsland = solve / Math.max(timer.islands, 1);
+  console.log(
+    [
+      String(bodies).padStart(7),
+      String(timer.islands).padStart(8),
+      tick.toFixed(0).padStart(8),
+      solve.toFixed(0).padStart(9),
+      `${((solve / tick) * 100).toFixed(0)}%`.padStart(8),
+      perIsland.toFixed(1).padStart(11),
+    ].join(' | '),
+  );
+}
+
+function row(stacks: number, high: number): void {
+  const { world, timer } = build(stacks, high);
+  report(world, timer, stacks * high);
+}
+
+console.log(' bodies |  islands |  tick us | solve us |   solve% | us/island');
+for (const [stacks, high] of [
+  [1, 10],
+  [4, 10],
+  [16, 10],
+  [64, 10],
+  [256, 10],
+] as const) {
+  row(stacks, high);
+}
+const linked = chain(100);
+report(linked.world, linked.timer, 100);
+console.log(
+  '\nThe last row is a hundred jointed boxes: one island, however many bodies, so a pool of any\n' +
+    'size can do nothing with it. The parallelism is bounded by the island count and never by the\n' +
+    'body count, which is what `executor.ts` said until this was measured.',
+);
+
+/**
+ * And what the pool actually takes off a tick, against both bounds it is held between.
+ *
+ * **Two ceilings, and the scene picks which one binds.** Amdahl's is `1 / (1 - solve share)`, from
+ * the column above. The other is `total island cost / largest island cost`, because the tick cannot
+ * end before its slowest island does — which is why the jointed chain gains nothing at any worker
+ * count and why a printed speedup means little without the bound beside it.
+ *
+ * Nothing here asserts. A wall-clock number on one machine is evidence, and the gate that has to
+ * hold is `workerPool.test.mjs`, which compares bits.
+ */
+function pooled(stacks: number, high: number, workers: number): void {
+  const world = new PhysicsWorld({ allowSleep: false, workers, spawn, pool: createIslandPool });
+  if (world.parallelism.running !== workers) {
+    console.log(`  ${workers} workers: not running — ${world.parallelism.reason}`);
+    world.dispose();
+    return;
+  }
+  const serial = new PhysicsWorld({ allowSleep: false });
+  for (const target of [world, serial]) {
+    target.addBody({ type: BODY_STATIC, shape: boxShape(2000, 1, 2000), y: -1, friction: 0.8 });
+    for (let s = 0; s < stacks; s++) {
+      for (let i = 0; i < high; i++) {
+        target.addBody({
+          type: BODY_DYNAMIC,
+          shape: boxShape(0.5, 0.5, 0.5),
+          x: s * 6,
+          y: 0.5 + i * 1.02,
+          density: 500,
+          friction: 0.8,
+        });
+      }
+    }
+  }
+  const time = (target: PhysicsWorld): number => {
+    for (let i = 0; i < 30; i++) target.step(DT);
+    const started = performance.now();
+    for (let i = 0; i < 120; i++) target.step(DT);
+    return ((performance.now() - started) / 120) * 1000;
+  };
+  const one = time(serial);
+  const many = time(world);
+  const solved = (world.executor as { solvedPerWorker: number[] }).solvedPerWorker;
+  console.log(
+    `  ${String(workers).padStart(2)} workers: ${one.toFixed(0).padStart(6)} us serial | ` +
+      `${many.toFixed(0).padStart(6)} us pooled | ${(one / many).toFixed(2)}x | ` +
+      `islands taken off this thread: ${solved.reduce((a, b) => a + b, 0)}`,
+  );
+  world.dispose();
+}
+
+console.log('\n256 stacks of 10, so there are 256 islands to hand out:');
+for (const workers of [1, 2, 4, 8]) pooled(256, 10, workers);
+console.log('\nAnd the jointed chain, which is one island and therefore has nothing to split:');
+const oneIsland = new PhysicsWorld({
+  allowSleep: false,
+  workers: 4,
+  spawn,
+  pool: createIslandPool,
+});
+if (oneIsland.parallelism.running === 4) {
+  oneIsland.addBody({ type: BODY_STATIC, shape: boxShape(2000, 1, 2000), y: -1, friction: 0.8 });
+  let last = -1;
+  for (let i = 0; i < 100; i++) {
+    const body = oneIsland.addBody({
+      type: BODY_DYNAMIC,
+      shape: boxShape(0.3, 0.3, 0.3),
+      x: i * 0.8,
+      y: 4,
+      density: 500,
+      friction: 0.8,
+    });
+    if (last >= 0)
+      oneIsland.addJoint({ type: JOINT_DISTANCE, bodyA: last, bodyB: body, length: 0.8 });
+    last = body;
+  }
+  for (let i = 0; i < 30; i++) oneIsland.step(DT);
+  const started = performance.now();
+  for (let i = 0; i < 120; i++) oneIsland.step(DT);
+  console.log(
+    `  4 workers on one island: ${(((performance.now() - started) / 120) * 1000).toFixed(0)} us a tick`,
+  );
+} else {
+  console.log(`  not running — ${oneIsland.parallelism.reason}`);
+}
+oneIsland.dispose();

package/scripts/streaming-check.ts

@@ -0,0 +1,358 @@
+/**
+ * That a world whose colliders stream is both fast and still correct.
+ *
+ * **The report.** A consumer moving to a 9.3 × 4.9 km world could not rebuild its `ColliderSet` at
+ * a region crossing: measured on their machine, a rebuild costs about 2.1 µs a box and is linear,
+ * which is 16.9 ms at the 6,076 colliders they have and 41.2 ms at the 15,000 they are moving to —
+ * a whole frame today and two and a half in the world coming, every few seconds, while somebody is
+ * driving. The alternative they shipped was one set per region and a query against the nine around
+ * the player, which measured 1.19 µs a query against 0.16 µs for a single set: affordable, and a
+ * 7.5x multiplier on every collision query in the game.
+ *
+ * **What this measures.** The engine's real sweep, in Node, against one set that is mutated as a
+ * body drives across region boundaries — groups added ahead of it and dropped behind it — at five
+ * frame rates: exactly sixty, sixty with the jitter a real clock has, 59.94 like a real panel, 120
+ * and 144.
+ *
+ * **Three of the six assertions are about speed and three are about whether removal works at
+ * all**, and the second three exist because the first three cannot see the defect this machinery
+ * can actually have. A `remove` that misses a bucket entry leaves the slot marked dead — so the
+ * fingerprint skips it and is right, and nothing walks it by index — while the stale entry goes on
+ * naming it: `query` returns it, and the sweep reads its stale bounds and collides with geometry
+ * that is gone. Frame time is unchanged, the query ratio is unchanged, the hash is unchanged, and
+ * a player drives into a wall that is not there.
+ *
+ * **It churns for hundreds of crossings before it measures.** Live slots reach free-list order
+ * only after that, and free-list order is unrelated to spatial order while the freshly built
+ * comparison set has slot order equal to input order — which is what assertion 2 is exposed to. A
+ * short run passes for a reason the field would not.
+ *
+ * If this ever fails at every rate except 59.94, the cause is not here: at that rate the steps per
+ * frame are exactly one, and a fault that hides there is a fault in the loop's stepping and not in
+ * the collider set.
+ *
+ * **The geometry is built before the clock starts, and the first draft of this check did not do
+ * that.** It called `boxCollider` inside the crossing frame and reported 6 to 7 ms, which read
+ * exactly like a broadphase that had not been fixed. Measured apart: generating 150 colliders is
+ * 2.086 ms, because `boxCollider` runs `hullShape` on eight points, while `add` is 0.164 ms and
+ * `remove` is 0.165 ms. So five sixths of that frame was the harness inventing a world. A streamer
+ * loads geometry from data or builds it off the main thread; what this track changed is the two
+ * calls that put it into the set and take it out, and those are what the clock is around.
+ *
+ * `npm run check:streaming`.
+ */
+import { AXIS_X, AXIS_Z } from '../src/collide/body';
+import { moveAxis } from '../src/collide/sweep';
+import type { Body } from '../src/collide/body';
+import { ColliderSet, boxCollider } from '../src/colliderSet';
+import type { Collider, ColliderGroup } from '../src/colliderSet';
+import { fingerprintColliders } from '../src/fingerprint';
+
+/** Metres a side. The consumer's own region size, so the numbers are about their world. */
+const REGION = 500;
+/** Colliders in a region, at the density the world being moved to has. */
+const PER_REGION = 150;
+/** How many regions stay resident around the player: the ring a streamer keeps. */
+const RESIDENT = 9;
+/** Crossings driven before anything is measured. See the header on free-list order. */
+const WARMUP_CROSSINGS = 400;
+/** Crossings measured after that. */
+const MEASURED_CROSSINGS = 200;
+/** Regions the drive will touch, generated once and shared by all five rates. */
+const TOTAL_REGIONS = WARMUP_CROSSINGS + MEASURED_CROSSINGS + RESIDENT;
+/** Metres a second. Ninety an hour, which is what the report was driving at. */
+const SPEED = 25;
+
+/**
+ * What a crossing may typically cost, in milliseconds.
+ *
+ * **Measured at 0.090 ms, and the rebuild it replaces costs 41 ms at this size.** So the threshold
+ * sits far closer to what is measured than to what it replaces, and a regression that matters here
+ * is an order of magnitude and not a few per cent. Five times the measurement is headroom for a
+ * slower machine, not slack for a change.
+ *
+ * **This is the median and not the maximum**, which is the split the first draft of this check got
+ * wrong. See `CROSSING_WORST_MS`.
+ */
+const CROSSING_MEDIAN_MS = 0.5;
+
+/**
+ * What a crossing may cost in the worst case, in milliseconds: a whole frame.
+ *
+ * **Because the maximum here is the runtime's and not the engine's.** Measured over two hundred
+ * crossings the median is 0.090 ms and the p99 is 0.38 ms, while the maximum lands between 1.6 and
+ * 4.4 ms at every rate — and it moves between runs on identical work, which is a garbage
+ * collection landing in the sample. Two hundred samples put the p99 on its last two, so no
+ * percentile at this sample size can tell a pause from a regression.
+ *
+ * So the two claims are asserted separately: the collider work is the median, and the claim a
+ * player would care about is that **no crossing drops a frame even with the runtime's pauses in
+ * it**, which is this one. A threshold on the maximum tight enough to catch a regression would be
+ * a check that fails at random, which is worse than no check.
+ */
+const CROSSING_WORST_MS = 16.7;
+
+/**
+ * How much dearer a query on the streamed set may be than on a freshly built one.
+ *
+ * **Not 1.0, and the reason is cache locality rather than anything the structure does wrong.**
+ * After hundreds of cycles the live slots sit in free-list order, which is a function of load
+ * history, while the comparison set has slot order equal to input order — and the sweep indexes
+ * `data` at exactly those slots. The number that matters is that it is nowhere near the 7.5x the
+ * per-region workaround costs: this is the assertion that the workaround can be deleted. If it
+ * ever approaches 7.5 the answer is a compaction pass and not a bug hunt.
+ *
+ * Measured between 1.24 and 1.30 across the five rates, so this sits nearer the measurement than
+ * the thing it rules out.
+ */
+const QUERY_RATIO = 2.5;
+
+const FRAME_RATES: readonly (readonly [string, number, number])[] = [
+  ['60', 60, 0],
+  ['60 jittered', 60, 0.3],
+  ['59.94', 59.94, 0],
+  ['120', 120, 0],
+  ['144', 144, 0],
+];
+
+/** A deterministic generator, so a failure is reproducible and a rerun is comparable. */
+function rng(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (Math.imul(state, 1103515245) + 12345) >>> 0;
+    return state / 4294967296;
+  };
+}
+
+/**
+ * One region's colliders, laid along the drive so the body meets them.
+ *
+ * **Seeded from the region index**, so every rate drives the same world and a failure at one rate
+ * and not another is about the loop and not about the geometry.
+ */
+function region(index: number): Collider[] {
+  const random = rng(0x9e37 + index * 2654435761);
+  const boxes: Collider[] = [];
+  const originX = index * REGION;
+  for (let i = 0; i < PER_REGION; i++) {
+    const x = originX + random() * REGION;
+    const z = (random() - 0.5) * 60;
+    /* Kept clear of the driving line at z = 0 so the body meets walls without being trapped by
+       them: this measures a broadphase, not a pathfinder. */
+    const offset = z >= 0 ? z + 6 : z - 6;
+    boxes.push(boxCollider(x, 1.5, offset, 1 + random() * 3, 1.5, 1 + random() * 3));
+  }
+  return boxes;
+}
+
+/*
+ * **Every region built once, before any clock starts.** See the header: generating a region is
+ * 2.086 ms of `hullShape` and is the consumer's cost, not the engine's, and leaving it inside the
+ * timed frame made a fixed broadphase read as a broken one.
+ */
+const WORLD: readonly Collider[][] = Array.from({ length: TOTAL_REGIONS }, (_, i) => region(i));
+
+interface Rig {
+  readonly set: ColliderSet;
+  readonly resident: Map<number, ColliderGroup>;
+}
+
+function newRig(): Rig {
+  return { set: new ColliderSet([]), resident: new Map() };
+}
+
+/** Load what the player can see and drop what they cannot, which is what a streamer does. */
+function stream(rig: Rig, centre: number): void {
+  const half = (RESIDENT - 1) / 2;
+  for (let r = centre - half; r <= centre + half; r++) {
+    if (r < 0 || r >= WORLD.length || rig.resident.has(r)) continue;
+    rig.resident.set(r, rig.set.add(WORLD[r] as Collider[]));
+  }
+  for (const [r, group] of [...rig.resident]) {
+    if (Math.abs(r - centre) <= half) continue;
+    rig.set.remove(group);
+    rig.resident.delete(r);
+  }
+}
+
+/** Every live collider in the set, as a fresh dense array, for the comparison build. */
+function liveColliders(set: ColliderSet): Collider[] {
+  const out: Collider[] = [];
+  for (let slot = 0; slot < set.capacity; slot++) {
+    if (!set.liveAt(slot)) continue;
+    const o = slot * 6;
+    out.push({
+      minX: set.data[o] as number,
+      minY: set.data[o + 1] as number,
+      minZ: set.data[o + 2] as number,
+      maxX: set.data[o + 3] as number,
+      maxY: set.data[o + 4] as number,
+      maxZ: set.data[o + 5] as number,
+      shape: set.shapeAt(slot),
+    });
+  }
+  return out;
+}
+
+/** Microseconds a query, averaged over a sweep of the resident band. */
+function queryCostUs(set: ColliderSet, centre: number, samples: number): number {
+  const hits = new Int32Array(ColliderSet.MAX_HITS);
+  const from = (centre - 4) * REGION;
+  const started = performance.now();
+  for (let i = 0; i < samples; i++) {
+    const x = from + ((i * 977) % (REGION * RESIDENT));
+    set.query(x - 0.5, 0, -1.5, x + 0.5, 2, 1.5, hits);
+  }
+  return ((performance.now() - started) * 1000) / samples;
+}
+
+const failures: string[] = [];
+function check(ok: boolean, message: string): void {
+  console.log(`${ok ? '  ok  ' : '  FAIL'} ${message}`);
+  if (!ok) failures.push(message);
+}
+
+/* ------------------------------------------------------------------ 3, 4, 5, 6 */
+
+console.log('\ncorrectness');
+
+/*
+ * **Assertion 3.** A set built in one shot hashes to the string it hashed to before any of this
+ * existed. The literal is the same one `fingerprint.test.ts` pins, and it is here as well as there
+ * because a recording is compared against a *running* engine and not against a unit test.
+ */
+{
+  const one = new ColliderSet([
+    { minX: -1, minY: -2, minZ: -3, maxX: 1, maxY: 2, maxZ: 3 },
+    { minX: 9.5, minY: -4.5, minZ: 6.5, maxX: 10.5, maxY: -3.5, maxZ: 7.5 },
+  ]);
+  check(
+    fingerprintColliders(one) === '8e0eb495365aade7',
+    `a one-shot set fingerprints as it always did (${fingerprintColliders(one)})`,
+  );
+}
+
+/*
+ * **Assertion 4.** After a group is dropped, a query over the volume it occupied returns none of
+ * its slots, and a body driven through where it stood passes. The second half is the one a player
+ * would notice, and it is the reason this is not just a query test.
+ */
+{
+  const set = new ColliderSet([]);
+  const wall = set.add([boxCollider(10, 1.5, 0, 0.5, 1.5, 8)]);
+  const body: Body = { x: 0, y: 1, z: 0, hx: 0.4, hy: 1, hz: 0.4 };
+  let travelled = 0;
+  for (let i = 0; i < 400; i++) travelled += moveAxis(body, set, AXIS_X, 0.05);
+  check(
+    travelled < 12,
+    `a wall stops the body while it is there (travelled ${travelled.toFixed(2)} m)`,
+  );
+
+  set.remove(wall);
+  const hits = new Int32Array(ColliderSet.MAX_HITS);
+  check(set.query(9, 0, -8, 11, 3, 8, hits) === 0, 'a query over the dropped volume finds nothing');
+
+  const after: Body = { x: 0, y: 1, z: 0, hx: 0.4, hy: 1, hz: 0.4 };
+  let free = 0;
+  for (let i = 0; i < 400; i++) free += moveAxis(after, set, AXIS_X, 0.05);
+  check(free > 19.9, `and the body passes through where it was (travelled ${free.toFixed(2)} m)`);
+}
+
+/*
+ * **Assertion 5.** The inverse, which catches an insert that ran late or not at all: a group put
+ * down ahead of the body is solid by the time the body reaches it.
+ */
+{
+  const set = new ColliderSet([]);
+  const body: Body = { x: 0, y: 1, z: 0, hx: 0.4, hy: 1, hz: 0.4 };
+  for (let i = 0; i < 100; i++) moveAxis(body, set, AXIS_X, 0.05);
+  set.add([boxCollider(10, 1.5, 0, 0.5, 1.5, 8)]);
+  let travelled = body.x;
+  for (let i = 0; i < 400; i++) moveAxis(body, set, AXIS_X, 0.05);
+  travelled = body.x;
+  check(
+    travelled < 12,
+    `a group added ahead is solid when the body arrives (stopped at ${travelled.toFixed(2)} m)`,
+  );
+}
+
+/* ------------------------------------------------------------------ 1, 2, 6 */
+
+console.log('\nthe drive, at five rates');
+
+for (const [name, hz, jitter] of FRAME_RATES) {
+  const rig = newRig();
+  const random = rng(hz * 1000);
+  const body: Body = { x: 0, y: 1, z: 0, hx: 0.4, hy: 1, hz: 0.4 };
+  const crossingMs: number[] = [];
+  let crossings = 0;
+  let region0 = -1;
+
+  const total = WARMUP_CROSSINGS + MEASURED_CROSSINGS;
+  while (crossings < total) {
+    const dt = (1 / hz) * (1 + (jitter === 0 ? 0 : (random() - 0.5) * 2 * jitter));
+    body.x += SPEED * dt;
+    moveAxis(body, rig.set, AXIS_X, 0);
+    moveAxis(body, rig.set, AXIS_Z, 0);
+
+    const here = Math.floor(body.x / REGION);
+    if (here === region0) continue;
+
+    const started = performance.now();
+    stream(rig, here);
+    const ms = performance.now() - started;
+    region0 = here;
+    crossings++;
+    /* Warm-up crossings are driven but not judged: the first ones allocate, and the free list has
+       not reached the order assertion 2 is exposed to. */
+    if (crossings > WARMUP_CROSSINGS) crossingMs.push(ms);
+  }
+  crossingMs.sort((a, b) => a - b);
+  const at = (q: number): number =>
+    crossingMs[Math.min(crossingMs.length - 1, Math.floor(crossingMs.length * q))] as number;
+  const medianMs = at(0.5);
+  const p99Ms = at(0.99);
+  const worstMs = crossingMs[crossingMs.length - 1] as number;
+
+  const centre = Math.floor(body.x / REGION);
+  const comparison = new ColliderSet(liveColliders(rig.set));
+  /* Discarded: the first timed loop of the process pays for JIT that every later one inherits, and
+     charging it to whichever set went first made that set look 40% dearer than it is. */
+  queryCostUs(rig.set, centre, 20000);
+  queryCostUs(comparison, centre, 20000);
+  const streamed = queryCostUs(rig.set, centre, 40000);
+  const fresh = queryCostUs(comparison, centre, 40000);
+  const ratio = streamed / fresh;
+  const dead = rig.set.auditCells();
+  const cost = rig.set.bytes();
+
+  console.log(
+    `\n  ${name} Hz — ${rig.set.count} live in ${rig.set.capacity} slots, ` +
+      `${(cost.total / 1048576).toFixed(2)} MB resident`,
+  );
+  console.log(
+    `    crossing: median ${medianMs.toFixed(3)} ms, p99 ${p99Ms.toFixed(3)} ms, worst ${worstMs.toFixed(3)} ms`,
+  );
+  check(
+    medianMs < CROSSING_MEDIAN_MS,
+    `a crossing costs ${medianMs.toFixed(3)} ms < ${CROSSING_MEDIAN_MS} ms (a rebuild here is 41 ms)`,
+  );
+  check(
+    worstMs < CROSSING_WORST_MS,
+    `and the worst of ${crossingMs.length} drops no frame: ${worstMs.toFixed(3)} ms < ${CROSSING_WORST_MS} ms`,
+  );
+  check(
+    ratio < QUERY_RATIO,
+    `query ${streamed.toFixed(3)} µs vs ${fresh.toFixed(3)} µs fresh — ${ratio.toFixed(2)}x < ${QUERY_RATIO}x ` +
+      '(the per-region workaround costs 7.5x)',
+  );
+  check(dead === 0, `no bucket names a dead slot (${dead})`);
+}
+
+console.log('');
+if (failures.length > 0) {
+  console.error(`${failures.length} failed:`);
+  for (const f of failures) console.error(`  ${f}`);
+  process.exit(1);
+}
+console.log('all assertions passed');