@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/playground/skinned_mesh_soup/verify_clone_vertices.js

@@ -1,438 +1,438 @@
-/**
- * Read a clone's deformed vertex region back and hold it against an answer the CPU knows.
- *
- * The page can be looked at, and soup is not subtle. What looking at it cannot say is *which*
- * vertices went wrong and in what pattern, and that is the whole difference between "skinning is
- * broken" and a bug you can name: every vertex past the 64th of its meshlet is the workgroup stride
- * loop, every vertex of some meshlets and none of others is the per-meshlet addressing, a scatter
- * with no pattern is the joint palette.
- *
- * This runs in the **bind pose** — `?skin=bind`, no clip registered — because that is the one pose
- * whose answer needs no GPU. At bind every joint's skin matrix is the skin's own frame under the
- * placement, and the mesh entity's row is that same frame under the same placement — the prefab put
- * it there — so the fold `inverse(mesh.global) × joint.global × inverse_bind` is the identity for
- * every joint, the blend collapses whatever the weights are, and the shader's output is its input:
- *
- * ```
- * clone_position = source_position
- * ```
- *
- * Wherever the character stands. Nothing about that involves the pose, so a disagreement here is
- * the skinning *machinery* — the addressing, the layout, the matrix range, the frame — and not the
- * animation.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-import { assert } from "../../../core/assert.js";
-import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
-import { ShadedGeometryFlags } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
-import {
-    MESHLET_METADATA_STRUCT
-} from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-import {
-    GEOMETRY_METADATA_STRUCT
-} from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
-import {
-    SKINNING_WORKGROUP_SIZE
-} from "../../renderer/animation/skinning/shader_meshlet_apply_skinning.js";
-import { number_compare_ascending } from "../../../core/primitives/numbers/number_compare_ascending.js";
-
-/**
- * Copy a slice of a GPU buffer back to the CPU.
- *
- * @param {GPUDevice} device
- * @param {GPUBuffer} buffer
- * @param {number} offset in bytes, a multiple of 4
- * @param {number} size in bytes, a multiple of 4
- * @returns {Promise<ArrayBuffer>}
- */
-async function read_back(device, buffer, offset, size) {
-    const staging = device.createBuffer({
-        label: 'soup/readback',
-        size,
-        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
-    });
-
-    const encoder = device.createCommandEncoder({ label: 'soup/readback' });
-
-    encoder.copyBufferToBuffer(buffer, offset, staging, 0, size);
-
-    device.queue.submit([encoder.finish()]);
-
-    await staging.mapAsync(GPUMapMode.READ);
-
-    const copy = staging.getMappedRange().slice(0);
-
-    staging.unmap();
-    staging.destroy();
-
-    return copy;
-}
-
-/**
- * Transform a point by a column-major 4×4.
- *
- * @param {ArrayLike<number>} m
- * @param {number} x
- * @param {number} y
- * @param {number} z
- * @returns {number[]}
- */
-function transform_point(m, x, y, z) {
-    return [
-        m[0] * x + m[4] * y + m[8] * z + m[12],
-        m[1] * x + m[5] * y + m[9] * z + m[13],
-        m[2] * x + m[6] * y + m[10] * z + m[14],
-    ];
-}
-
-/**
- * Invert a column-major 4×4 that is an affine transform — which every node transform in this engine
- * is. General enough for a `T · R · S` with non-uniform scale, and not for a projection.
- *
- * @param {ArrayLike<number>} m
- * @returns {Float64Array}
- */
-function affine_inverse(m) {
-    const a = m[0], b = m[4], c = m[8];
-    const d = m[1], e = m[5], f = m[9];
-    const g = m[2], h = m[6], i = m[10];
-
-    const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g);
-
-    assert.notEqual(det, 0, 'transform is singular');
-
-    const s = 1 / det;
-
-    const r = new Float64Array(16);
-
-    r[0] = (e * i - f * h) * s;
-    r[1] = (f * g - d * i) * s;
-    r[2] = (d * h - e * g) * s;
-
-    r[4] = (c * h - b * i) * s;
-    r[5] = (a * i - c * g) * s;
-    r[6] = (b * g - a * h) * s;
-
-    r[8] = (b * f - c * e) * s;
-    r[9] = (c * d - a * f) * s;
-    r[10] = (a * e - b * d) * s;
-
-    const tx = m[12], ty = m[13], tz = m[14];
-
-    r[12] = -(r[0] * tx + r[4] * ty + r[8] * tz);
-    r[13] = -(r[1] * tx + r[5] * ty + r[9] * tz);
-    r[14] = -(r[2] * tx + r[6] * ty + r[10] * tz);
-
-    r[15] = 1;
-
-    return r;
-}
-
-/**
- * Contiguous runs of a sorted list of integers, as `[first, last]` pairs.
- *
- * @param {number[]} values
- * @returns {number[][]}
- */
-function runs_of(values) {
-    const runs = [];
-
-    for (const value of values) {
-        const last = runs[runs.length - 1];
-
-        if (last !== undefined && last[1] === value - 1) {
-            last[1] = value;
-        } else {
-            runs.push([value, value]);
-        }
-    }
-
-    return runs;
-}
-
-/**
- * The clone's deformed vertices, against `inverse(mesh.global) × rest`.
- *
- * Reads the GPU's own answer to "where does this geometry id's data live" rather than reconstructing
- * it from the host records: the geometry metadata row, then the clone's meshlet metadata rows, then
- * the data those rows address. That is the same chain the rasterizer and the intersector walk, so a
- * clone whose *addressing* is wrong is caught here rather than being read around.
- *
- * @param {object} options
- * @param {Renderer} options.renderer
- * @param {Scene} options.scene
- * @param {number} options.entity a skinned mesh entity
- * @param {number} [options.tolerance] in mesh-local units. Since compiling the model puts the mesh
- *        on the skin's bind transform, mesh-local *is* world scale — a metre is a metre here, and at
- *        bind the clone should hold the source's own positions. `1e-4` is f32 headroom over a
- *        chain — a matrix product, a quaternion conversion and a screw motion, all at single
- *        precision — against a smallest real violation of `1.6`, so there are four orders between
- *        the two. It was `5e-3` while `dual_quat_from_m4` amplified a near-identity matrix's error
- *        by its square root; `SKINNING_FRAME_PLAN.md` §9 took that out, and the same measurement on
- *        the CPU now reads zero at bind.
- * @returns {Promise<object>}
- */
-export async function verify_clone_vertices({ renderer, scene, entity, tolerance = 1e-4 }) {
-    assert.isNonNegativeInteger(entity, 'entity');
-
-    const dataset = scene.dataset;
-
-    assert.defined(dataset, 'scene.dataset');
-
-    const shaded = dataset.getComponent(entity, ShadedGeometry);
-
-    assert.defined(shaded, `entity ${entity} carries no ShadedGeometry`);
-    assert.ok(shaded.getFlag(ShadedGeometryFlags.Skinned), `entity ${entity} is not a skinned mesh`);
-
-    const geometry = shaded.geometry;
-
-    const graphics = renderer.graphics;
-    const device = graphics.device;
-    const geometries = graphics.geometries;
-
-    const scene_context = renderer.scenes.obtain(scene);
-
-    const clone = scene_context.skinning.clone_of(entity);
-
-    if (clone === undefined) {
-        return {
-            verdict: `FAIL — entity ${entity} has no clone; its mesh row has not been written, or it `
-                + `is not skinned`,
-        };
-    }
-
-    const geometry_index = clone.index;
-
-    // ---- where the clone's meshlets are, as the GPU has it -------------------------------------
-
-    const geometry_row = new DataView(await read_back(
-        device,
-        geometries.buffer_metadata,
-        geometry_index * GEOMETRY_METADATA_STRUCT.size,
-        GEOMETRY_METADATA_STRUCT.size
-    ));
-
-    const meshlets_address = geometry_row.getUint32(
-        GEOMETRY_METADATA_STRUCT.get('meshlets_address').offset, true
-    );
-    const meshlets_count = geometry_row.getUint32(
-        GEOMETRY_METADATA_STRUCT.get('meshlets_count').offset, true
-    );
-
-    const source_batch = geometry.meshlets;
-
-    if (meshlets_count !== source_batch.count) {
-        return {
-            geometry_index,
-            verdict: `FAIL — the clone's geometry row claims ${meshlets_count} meshlets, `
-                + `its source has ${source_batch.count}`,
-        };
-    }
-
-    const meshlet_stride = MESHLET_METADATA_STRUCT.aligned_size;
-
-    const clone_metadata = new DataView(await read_back(
-        device,
-        geometries.meshlets.buffer_metadata,
-        meshlets_address * meshlet_stride,
-        meshlets_count * meshlet_stride
-    ));
-
-    const ADDRESS_OFFSET = MESHLET_METADATA_STRUCT.get('address').offset;
-    const VERTEX_COUNT_OFFSET = MESHLET_METADATA_STRUCT.get('vertex_count').offset;
-    const PRIMITIVE_COUNT_OFFSET = MESHLET_METADATA_STRUCT.get('primitive_count').offset;
-
-    // ---- and where the source's are, to say the clone is somewhere else --------------------------
-
-    /*
-     A clone is a fresh vertex region plus a patch pass that adds `clone.data.offset -
-     source.data.offset` to every one of its meshlet records. If that patch does not land, the
-     clone's records still address the *source's* data: the skinning pass then deforms the shared
-     rest-pose vertices in place, every instance of the model deforms on top of every other, and the
-     source no rasterizer ever wanted deformed goes with them. The addresses differing by one
-     constant is the whole contract, and it is checkable before a single vertex is compared.
-    */
-    const source_record = geometries.get_metadata(geometry);
-
-    if (source_record === undefined) {
-        return {
-            geometry_index,
-            verdict: `FAIL — the mesh's source geometry is not registered, so there is nothing for `
-                + `its clone to be a clone of. The scene has not been built with this mesh in it.`,
-        };
-    }
-
-    const source_metadata = new DataView(await read_back(
-        device,
-        geometries.meshlets.buffer_metadata,
-        source_record.meshlets.metadata.offset * meshlet_stride,
-        meshlets_count * meshlet_stride
-    ));
-
-    // ---- the clone's vertex data, in one read ---------------------------------------------------
-
-    /*
-     Position is the first attribute of the section and is never collapsed to a shared slot (see
-     ENCODED_ORDERED_ATTRIBUTES and MESHLET_ATTRIBUTE_COMPRESSION_FLAGS), so a meshlet's positions
-     start where its attribute section does and the furthest word this needs is the last position
-     word of the furthest meshlet. That is a span, not a set of holes, so it comes back in one copy
-     rather than in `meshlets_count` of them — two hundred round trips through `mapAsync` is a
-     diagnostic nobody runs twice.
-    */
-    const position_word_of = new Uint32Array(meshlets_count);
-
-    let data_low = Infinity;
-    let data_high = 0;
-
-    /** every distinct `clone address − source address`; one entry is the contract */
-    const address_deltas = new Set();
-
-    for (let m = 0; m < meshlets_count; m++) {
-        const row = m * meshlet_stride;
-
-        const address = clone_metadata.getUint32(row + ADDRESS_OFFSET, true);
-        const primitive_count = clone_metadata.getUint32(row + PRIMITIVE_COUNT_OFFSET, true);
-        const vertex_count = clone_metadata.getUint32(row + VERTEX_COUNT_OFFSET, true);
-
-        address_deltas.add(address - source_metadata.getUint32(row + ADDRESS_OFFSET, true));
-
-        const position_word = address + ((primitive_count * 3 + 3) >> 2);
-
-        position_word_of[m] = position_word;
-
-        data_low = Math.min(data_low, position_word);
-        data_high = Math.max(data_high, position_word + vertex_count * 3);
-    }
-
-    if (address_deltas.size !== 1 || address_deltas.has(0)) {
-        return {
-            geometry_index,
-            address_deltas: [...address_deltas].slice(0, 8),
-            verdict: address_deltas.has(0) && address_deltas.size === 1
-                ? `FAIL — every one of the clone's ${meshlets_count} meshlet records addresses the `
-                    + `source's vertex data. The address patch did not run, so the skinning pass is `
-                    + `deforming the shared rest-pose region in place.`
-                : `FAIL — the clone's meshlet records sit at ${address_deltas.size} different `
-                    + `offsets from the source's; a clone is one contiguous region and its patch is `
-                    + `one delta.`,
-        };
-    }
-
-    const data = new Float32Array(await read_back(
-        device,
-        geometries.meshlets.buffer_data,
-        data_low * 4,
-        (data_high - data_low) * 4
-    ));
-
-    // ---- the comparison: the answer the CPU knows is the source itself ---------------------------------------------------------------------
-
-    let vertices = 0;
-    let wrong = 0;
-    let worst = 0;
-    let worst_where = null;
-
-    /** meshlets with at least one wrong vertex */
-    const wrong_meshlets = [];
-
-    /** per-vertex-slot tally: how many meshlets got slot `v` wrong */
-    const wrong_by_slot = new Map();
-
-    const examples = [];
-
-    for (let m = 0; m < meshlets_count; m++) {
-        const source_header = source_batch.read_header(m);
-        const source = source_batch.read_meshlet(m);
-
-        const row = m * meshlet_stride;
-
-        const clone_vertex_count = clone_metadata.getUint32(row + VERTEX_COUNT_OFFSET, true);
-        const clone_primitive_count = clone_metadata.getUint32(row + PRIMITIVE_COUNT_OFFSET, true);
-
-        if (clone_vertex_count !== source_header.vertex_count
-            || clone_primitive_count !== source_header.primitive_count) {
-            return {
-                geometry_index,
-                verdict: `FAIL — clone meshlet ${m} says `
-                    + `${clone_vertex_count} vertices / ${clone_primitive_count} triangles, `
-                    + `its source says ${source_header.vertex_count} / ${source_header.primitive_count}. `
-                    + `The metadata copy or its address patch is wrong, before any skinning ran.`,
-            };
-        }
-
-        const positions = data.subarray(
-            position_word_of[m] - data_low,
-            position_word_of[m] - data_low + clone_vertex_count * 3
-        );
-
-        let meshlet_wrong = 0;
-
-        for (let v = 0; v < clone_vertex_count; v++) {
-            vertices++;
-
-            const error = Math.max(
-                Math.abs(positions[v * 3] - source.attribute_position[v * 3]),
-                Math.abs(positions[v * 3 + 1] - source.attribute_position[v * 3 + 1]),
-                Math.abs(positions[v * 3 + 2] - source.attribute_position[v * 3 + 2]),
-            );
-
-            if (error > worst) {
-                worst = error;
-                worst_where = { meshlet: m, vertex: v };
-            }
-
-            if (error > tolerance) {
-                wrong++;
-                meshlet_wrong++;
-
-                wrong_by_slot.set(v, (wrong_by_slot.get(v) ?? 0) + 1);
-
-                if (examples.length < 8) {
-                    examples.push({
-                        meshlet: m,
-                        vertex: v,
-                        got: [positions[v * 3], positions[v * 3 + 1], positions[v * 3 + 2]],
-                        expected,
-                    });
-                }
-            }
-        }
-
-        if (meshlet_wrong > 0) {
-            wrong_meshlets.push(m);
-        }
-    }
-
-    // The two shapes worth telling apart, named rather than left to be read out of the runs: a
-    // stride-loop bug wrongs every slot at or past the workgroup size and nothing below it, and an
-    // addressing bug wrongs whole meshlets.
-    const slots = [...wrong_by_slot.keys()].sort(number_compare_ascending);
-
-    const lowest_wrong_slot = slots.length > 0 ? slots[0] : null;
-
-    return {
-        geometry_index,
-        meshlets: meshlets_count,
-        address_delta: [...address_deltas][0],
-        vertices,
-        wrong,
-        worst,
-        worst_where,
-        wrong_meshlets: wrong_meshlets.length,
-        wrong_meshlet_runs: runs_of(wrong_meshlets).slice(0, 20),
-        lowest_wrong_slot,
-        highest_correct_slot: slots.length > 0 ? lowest_wrong_slot - 1 : null,
-        wrong_slot_runs: runs_of(slots).slice(0, 20),
-        examples,
-        verdict: wrong === 0
-            ? `pass — all ${vertices} of the clone's vertices are the bind pose, worst error ${worst}`
-            : `FAIL — ${wrong} of ${vertices} vertices in ${wrong_meshlets.length} of `
-                + `${meshlets_count} meshlets are not the bind pose (worst ${worst}); `
-                + `lowest wrong vertex slot ${lowest_wrong_slot}. `
-                + `A lowest slot of ${SKINNING_WORKGROUP_SIZE} is the stride loop; whole meshlets `
-                + `wrong is addressing; a uniform factor is the frame.`,
-    };
-}
+/**
+ * Read a clone's deformed vertex region back and hold it against an answer the CPU knows.
+ *
+ * The page can be looked at, and soup is not subtle. What looking at it cannot say is *which*
+ * vertices went wrong and in what pattern, and that is the whole difference between "skinning is
+ * broken" and a bug you can name: every vertex past the 64th of its meshlet is the workgroup stride
+ * loop, every vertex of some meshlets and none of others is the per-meshlet addressing, a scatter
+ * with no pattern is the joint palette.
+ *
+ * This runs in the **bind pose** — `?skin=bind`, no clip registered — because that is the one pose
+ * whose answer needs no GPU. At bind every joint's skin matrix is the skin's own frame under the
+ * placement, and the mesh entity's row is that same frame under the same placement — the prefab put
+ * it there — so the fold `inverse(mesh.global) × joint.global × inverse_bind` is the identity for
+ * every joint, the blend collapses whatever the weights are, and the shader's output is its input:
+ *
+ * ```
+ * clone_position = source_position
+ * ```
+ *
+ * Wherever the character stands. Nothing about that involves the pose, so a disagreement here is
+ * the skinning *machinery* — the addressing, the layout, the matrix range, the frame — and not the
+ * animation.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+import { assert } from "../../../core/assert.js";
+import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import {
+    GEOMETRY_METADATA_STRUCT
+} from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
+import {
+    SKINNING_WORKGROUP_SIZE
+} from "../../renderer/animation/skinning/shader_meshlet_apply_skinning.js";
+import { number_compare_ascending } from "../../../core/primitives/numbers/number_compare_ascending.js";
+
+/**
+ * Copy a slice of a GPU buffer back to the CPU.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer
+ * @param {number} offset in bytes, a multiple of 4
+ * @param {number} size in bytes, a multiple of 4
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, offset, size) {
+    const staging = device.createBuffer({
+        label: 'soup/readback',
+        size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'soup/readback' });
+
+    encoder.copyBufferToBuffer(buffer, offset, staging, 0, size);
+
+    device.queue.submit([encoder.finish()]);
+
+    await staging.mapAsync(GPUMapMode.READ);
+
+    const copy = staging.getMappedRange().slice(0);
+
+    staging.unmap();
+    staging.destroy();
+
+    return copy;
+}
+
+/**
+ * Transform a point by a column-major 4×4.
+ *
+ * @param {ArrayLike<number>} m
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number[]}
+ */
+function transform_point(m, x, y, z) {
+    return [
+        m[0] * x + m[4] * y + m[8] * z + m[12],
+        m[1] * x + m[5] * y + m[9] * z + m[13],
+        m[2] * x + m[6] * y + m[10] * z + m[14],
+    ];
+}
+
+/**
+ * Invert a column-major 4×4 that is an affine transform — which every node transform in this engine
+ * is. General enough for a `T · R · S` with non-uniform scale, and not for a projection.
+ *
+ * @param {ArrayLike<number>} m
+ * @returns {Float64Array}
+ */
+function affine_inverse(m) {
+    const a = m[0], b = m[4], c = m[8];
+    const d = m[1], e = m[5], f = m[9];
+    const g = m[2], h = m[6], i = m[10];
+
+    const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g);
+
+    assert.notEqual(det, 0, 'transform is singular');
+
+    const s = 1 / det;
+
+    const r = new Float64Array(16);
+
+    r[0] = (e * i - f * h) * s;
+    r[1] = (f * g - d * i) * s;
+    r[2] = (d * h - e * g) * s;
+
+    r[4] = (c * h - b * i) * s;
+    r[5] = (a * i - c * g) * s;
+    r[6] = (b * g - a * h) * s;
+
+    r[8] = (b * f - c * e) * s;
+    r[9] = (c * d - a * f) * s;
+    r[10] = (a * e - b * d) * s;
+
+    const tx = m[12], ty = m[13], tz = m[14];
+
+    r[12] = -(r[0] * tx + r[4] * ty + r[8] * tz);
+    r[13] = -(r[1] * tx + r[5] * ty + r[9] * tz);
+    r[14] = -(r[2] * tx + r[6] * ty + r[10] * tz);
+
+    r[15] = 1;
+
+    return r;
+}
+
+/**
+ * Contiguous runs of a sorted list of integers, as `[first, last]` pairs.
+ *
+ * @param {number[]} values
+ * @returns {number[][]}
+ */
+function runs_of(values) {
+    const runs = [];
+
+    for (const value of values) {
+        const last = runs[runs.length - 1];
+
+        if (last !== undefined && last[1] === value - 1) {
+            last[1] = value;
+        } else {
+            runs.push([value, value]);
+        }
+    }
+
+    return runs;
+}
+
+/**
+ * The clone's deformed vertices, against `inverse(mesh.global) × rest`.
+ *
+ * Reads the GPU's own answer to "where does this geometry id's data live" rather than reconstructing
+ * it from the host records: the geometry metadata row, then the clone's meshlet metadata rows, then
+ * the data those rows address. That is the same chain the rasterizer and the intersector walk, so a
+ * clone whose *addressing* is wrong is caught here rather than being read around.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {number} options.entity a skinned mesh entity
+ * @param {number} [options.tolerance] in mesh-local units. Since compiling the model puts the mesh
+ *        on the skin's bind transform, mesh-local *is* world scale — a metre is a metre here, and at
+ *        bind the clone should hold the source's own positions. `1e-4` is f32 headroom over a
+ *        chain — a matrix product, a quaternion conversion and a screw motion, all at single
+ *        precision — against a smallest real violation of `1.6`, so there are four orders between
+ *        the two. It was `5e-3` while `dual_quat_from_m4` amplified a near-identity matrix's error
+ *        by its square root; `SKINNING_FRAME_PLAN.md` §9 took that out, and the same measurement on
+ *        the CPU now reads zero at bind.
+ * @returns {Promise<object>}
+ */
+export async function verify_clone_vertices({ renderer, scene, entity, tolerance = 1e-4 }) {
+    assert.isNonNegativeInteger(entity, 'entity');
+
+    const dataset = scene.dataset;
+
+    assert.defined(dataset, 'scene.dataset');
+
+    const shaded = dataset.getComponent(entity, ShadedGeometry);
+
+    assert.defined(shaded, `entity ${entity} carries no ShadedGeometry`);
+    assert.ok(shaded.getFlag(ShadedGeometryFlags.Skinned), `entity ${entity} is not a skinned mesh`);
+
+    const geometry = shaded.geometry;
+
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+    const geometries = graphics.geometries;
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const clone = scene_context.skinning.clone_of(entity);
+
+    if (clone === undefined) {
+        return {
+            verdict: `FAIL — entity ${entity} has no clone; its mesh row has not been written, or it `
+                + `is not skinned`,
+        };
+    }
+
+    const geometry_index = clone.index;
+
+    // ---- where the clone's meshlets are, as the GPU has it -------------------------------------
+
+    const geometry_row = new DataView(await read_back(
+        device,
+        geometries.buffer_metadata,
+        geometry_index * GEOMETRY_METADATA_STRUCT.size,
+        GEOMETRY_METADATA_STRUCT.size
+    ));
+
+    const meshlets_address = geometry_row.getUint32(
+        GEOMETRY_METADATA_STRUCT.get('meshlets_address').offset, true
+    );
+    const meshlets_count = geometry_row.getUint32(
+        GEOMETRY_METADATA_STRUCT.get('meshlets_count').offset, true
+    );
+
+    const source_batch = geometry.meshlets;
+
+    if (meshlets_count !== source_batch.count) {
+        return {
+            geometry_index,
+            verdict: `FAIL — the clone's geometry row claims ${meshlets_count} meshlets, `
+                + `its source has ${source_batch.count}`,
+        };
+    }
+
+    const meshlet_stride = MESHLET_METADATA_STRUCT.aligned_size;
+
+    const clone_metadata = new DataView(await read_back(
+        device,
+        geometries.meshlets.buffer_metadata,
+        meshlets_address * meshlet_stride,
+        meshlets_count * meshlet_stride
+    ));
+
+    const ADDRESS_OFFSET = MESHLET_METADATA_STRUCT.get('address').offset;
+    const VERTEX_COUNT_OFFSET = MESHLET_METADATA_STRUCT.get('vertex_count').offset;
+    const PRIMITIVE_COUNT_OFFSET = MESHLET_METADATA_STRUCT.get('primitive_count').offset;
+
+    // ---- and where the source's are, to say the clone is somewhere else --------------------------
+
+    /*
+     A clone is a fresh vertex region plus a patch pass that adds `clone.data.offset -
+     source.data.offset` to every one of its meshlet records. If that patch does not land, the
+     clone's records still address the *source's* data: the skinning pass then deforms the shared
+     rest-pose vertices in place, every instance of the model deforms on top of every other, and the
+     source no rasterizer ever wanted deformed goes with them. The addresses differing by one
+     constant is the whole contract, and it is checkable before a single vertex is compared.
+    */
+    const source_record = geometries.get_metadata(geometry);
+
+    if (source_record === undefined) {
+        return {
+            geometry_index,
+            verdict: `FAIL — the mesh's source geometry is not registered, so there is nothing for `
+                + `its clone to be a clone of. The scene has not been built with this mesh in it.`,
+        };
+    }
+
+    const source_metadata = new DataView(await read_back(
+        device,
+        geometries.meshlets.buffer_metadata,
+        source_record.meshlets.metadata.offset * meshlet_stride,
+        meshlets_count * meshlet_stride
+    ));
+
+    // ---- the clone's vertex data, in one read ---------------------------------------------------
+
+    /*
+     Position is the first attribute of the section and is never collapsed to a shared slot (see
+     ENCODED_ORDERED_ATTRIBUTES and MESHLET_ATTRIBUTE_COMPRESSION_FLAGS), so a meshlet's positions
+     start where its attribute section does and the furthest word this needs is the last position
+     word of the furthest meshlet. That is a span, not a set of holes, so it comes back in one copy
+     rather than in `meshlets_count` of them — two hundred round trips through `mapAsync` is a
+     diagnostic nobody runs twice.
+    */
+    const position_word_of = new Uint32Array(meshlets_count);
+
+    let data_low = Infinity;
+    let data_high = 0;
+
+    /** every distinct `clone address − source address`; one entry is the contract */
+    const address_deltas = new Set();
+
+    for (let m = 0; m < meshlets_count; m++) {
+        const row = m * meshlet_stride;
+
+        const address = clone_metadata.getUint32(row + ADDRESS_OFFSET, true);
+        const primitive_count = clone_metadata.getUint32(row + PRIMITIVE_COUNT_OFFSET, true);
+        const vertex_count = clone_metadata.getUint32(row + VERTEX_COUNT_OFFSET, true);
+
+        address_deltas.add(address - source_metadata.getUint32(row + ADDRESS_OFFSET, true));
+
+        const position_word = address + ((primitive_count * 3 + 3) >> 2);
+
+        position_word_of[m] = position_word;
+
+        data_low = Math.min(data_low, position_word);
+        data_high = Math.max(data_high, position_word + vertex_count * 3);
+    }
+
+    if (address_deltas.size !== 1 || address_deltas.has(0)) {
+        return {
+            geometry_index,
+            address_deltas: [...address_deltas].slice(0, 8),
+            verdict: address_deltas.has(0) && address_deltas.size === 1
+                ? `FAIL — every one of the clone's ${meshlets_count} meshlet records addresses the `
+                    + `source's vertex data. The address patch did not run, so the skinning pass is `
+                    + `deforming the shared rest-pose region in place.`
+                : `FAIL — the clone's meshlet records sit at ${address_deltas.size} different `
+                    + `offsets from the source's; a clone is one contiguous region and its patch is `
+                    + `one delta.`,
+        };
+    }
+
+    const data = new Float32Array(await read_back(
+        device,
+        geometries.meshlets.buffer_data,
+        data_low * 4,
+        (data_high - data_low) * 4
+    ));
+
+    // ---- the comparison: the answer the CPU knows is the source itself ---------------------------------------------------------------------
+
+    let vertices = 0;
+    let wrong = 0;
+    let worst = 0;
+    let worst_where = null;
+
+    /** meshlets with at least one wrong vertex */
+    const wrong_meshlets = [];
+
+    /** per-vertex-slot tally: how many meshlets got slot `v` wrong */
+    const wrong_by_slot = new Map();
+
+    const examples = [];
+
+    for (let m = 0; m < meshlets_count; m++) {
+        const source_header = source_batch.read_header(m);
+        const source = source_batch.read_meshlet(m);
+
+        const row = m * meshlet_stride;
+
+        const clone_vertex_count = clone_metadata.getUint32(row + VERTEX_COUNT_OFFSET, true);
+        const clone_primitive_count = clone_metadata.getUint32(row + PRIMITIVE_COUNT_OFFSET, true);
+
+        if (clone_vertex_count !== source_header.vertex_count
+            || clone_primitive_count !== source_header.primitive_count) {
+            return {
+                geometry_index,
+                verdict: `FAIL — clone meshlet ${m} says `
+                    + `${clone_vertex_count} vertices / ${clone_primitive_count} triangles, `
+                    + `its source says ${source_header.vertex_count} / ${source_header.primitive_count}. `
+                    + `The metadata copy or its address patch is wrong, before any skinning ran.`,
+            };
+        }
+
+        const positions = data.subarray(
+            position_word_of[m] - data_low,
+            position_word_of[m] - data_low + clone_vertex_count * 3
+        );
+
+        let meshlet_wrong = 0;
+
+        for (let v = 0; v < clone_vertex_count; v++) {
+            vertices++;
+
+            const error = Math.max(
+                Math.abs(positions[v * 3] - source.attribute_position[v * 3]),
+                Math.abs(positions[v * 3 + 1] - source.attribute_position[v * 3 + 1]),
+                Math.abs(positions[v * 3 + 2] - source.attribute_position[v * 3 + 2]),
+            );
+
+            if (error > worst) {
+                worst = error;
+                worst_where = { meshlet: m, vertex: v };
+            }
+
+            if (error > tolerance) {
+                wrong++;
+                meshlet_wrong++;
+
+                wrong_by_slot.set(v, (wrong_by_slot.get(v) ?? 0) + 1);
+
+                if (examples.length < 8) {
+                    examples.push({
+                        meshlet: m,
+                        vertex: v,
+                        got: [positions[v * 3], positions[v * 3 + 1], positions[v * 3 + 2]],
+                        expected: [source.attribute_position[v * 3], source.attribute_position[v * 3 + 1], source.attribute_position[v * 3 + 2]],
+                    });
+                }
+            }
+        }
+
+        if (meshlet_wrong > 0) {
+            wrong_meshlets.push(m);
+        }
+    }
+
+    // The two shapes worth telling apart, named rather than left to be read out of the runs: a
+    // stride-loop bug wrongs every slot at or past the workgroup size and nothing below it, and an
+    // addressing bug wrongs whole meshlets.
+    const slots = [...wrong_by_slot.keys()].sort(number_compare_ascending);
+
+    const lowest_wrong_slot = slots.length > 0 ? slots[0] : null;
+
+    return {
+        geometry_index,
+        meshlets: meshlets_count,
+        address_delta: [...address_deltas][0],
+        vertices,
+        wrong,
+        worst,
+        worst_where,
+        wrong_meshlets: wrong_meshlets.length,
+        wrong_meshlet_runs: runs_of(wrong_meshlets).slice(0, 20),
+        lowest_wrong_slot,
+        highest_correct_slot: slots.length > 0 ? lowest_wrong_slot - 1 : null,
+        wrong_slot_runs: runs_of(slots).slice(0, 20),
+        examples,
+        verdict: wrong === 0
+            ? `pass — all ${vertices} of the clone's vertices are the bind pose, worst error ${worst}`
+            : `FAIL — ${wrong} of ${vertices} vertices in ${wrong_meshlets.length} of `
+                + `${meshlets_count} meshlets are not the bind pose (worst ${worst}); `
+                + `lowest wrong vertex slot ${lowest_wrong_slot}. `
+                + `A lowest slot of ${SKINNING_WORKGROUP_SIZE} is the stride loop; whole meshlets `
+                + `wrong is addressing; a uniform factor is the frame.`,
+    };
+}