@woosh/meep-engine 3.1.0 → 3.2.0

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js

@@ -1,599 +1,599 @@
-import { NULL_POINTER } from "../BinaryTopology.js";
-
-/**
- * Which kind of element a defect was found on. Typed constant (no stringly-typed
- * states), mirroring the four pools of {@link BinaryTopology}.
- * @readonly
- */
-export const BT_ELEMENT_TYPE = Object.freeze({
-    VERTEX: 0,
-    EDGE: 1,
-    LOOP: 2,
-    FACE: 3,
-});
-
-/**
- * Structural defects {@link bt_mesh_validate} can report. Each value names a
- * broken invariant of {@link BinaryTopology}, not a symptom.
- * @readonly
- */
-export const BT_DEFECT = Object.freeze({
-    /** A handle points at a pool slot that is not allocated (dangling reference). */
-    DANGLING_REFERENCE: 0,
-    /** A cycle (disk / radial / face-loop) does not return to its start within the pool's size. */
-    CYCLE_NOT_CLOSED: 1,
-    /** `prev` is not the inverse of `next` somewhere on a cycle. */
-    CYCLE_LINK_ASYMMETRIC: 2,
-    /** An edge is missing from the disk cycle of one of its vertices. */
-    EDGE_NOT_IN_DISK: 3,
-    /** An edge sits on the disk cycle of a vertex that is not one of its endpoints. */
-    DISK_EDGE_VERTEX_MISMATCH: 4,
-    /** A loop is missing from the radial cycle of the edge it claims. */
-    LOOP_NOT_IN_RADIAL: 5,
-    /** A loop on an edge's radial cycle does not claim that edge. */
-    RADIAL_LOOP_EDGE_MISMATCH: 6,
-    /** A loop on a face's loop cycle does not claim that face. */
-    FACE_LOOP_FACE_MISMATCH: 7,
-    /** A face's loop cycle is shorter than three corners. */
-    FACE_TOO_FEW_CORNERS: 8,
-    /** The same vertex appears twice on one face's loop cycle. */
-    FACE_VERTEX_REPEATED: 9,
-    /** A loop's edge does not connect that loop's vertex to the next loop's vertex. */
-    LOOP_EDGE_ENDPOINT_MISMATCH: 10,
-    /** An allocated loop is not reachable from any allocated face. */
-    LOOP_ORPHANED: 11,
-    /** A vertex with incident edges has a NULL edge pointer, or vice versa. */
-    VERTEX_EDGE_POINTER_INCONSISTENT: 12,
-    /** A coordinate or normal component is not finite. */
-    NON_FINITE_VALUE: 13,
-});
-
-/**
- * Bit set in `edge_seen` once an edge has been reached through its v1 disk slot.
- * @type {number}
- */
-const SEEN_V1 = 1;
-/**
- * Bit set in `edge_seen` once an edge has been reached through its v2 disk slot.
- * @type {number}
- */
-const SEEN_V2 = 2;
-
-/**
- * @param {object[]} out
- * @param {number} code one of {@link BT_DEFECT}
- * @param {number} element_type one of {@link BT_ELEMENT_TYPE}
- * @param {number} element
- * @param {string} detail
- */
-function record(out, code, element_type, element, detail) {
-    out.push({ code, element_type, element, detail });
-}
-
-/**
- * True when `id` is a live slot of `pool`, i.e. safe to dereference.
- * @param {BinaryElementPool} pool
- * @param {number} id
- * @returns {boolean}
- */
-function is_live(pool, id) {
-    return id !== NULL_POINTER && id < pool.size && pool.is_allocated(id);
-}
-
-/**
- * Check every handle an element stores actually points at a live slot of the
- * right pool. Runs first so the cycle walks below can dereference freely.
- *
- * @param {BinaryTopology} mesh
- * @param {object[]} out
- */
-function check_references(mesh, out) {
-    const vertices = mesh.vertices;
-    const edges = mesh.edges;
-    const loops = mesh.loops;
-    const faces = mesh.faces;
-
-    for (let v = 0; v < vertices.size; v++) {
-        if (!vertices.is_allocated(v)) {
-            continue;
-        }
-
-        const e = mesh.vertex_read_edge(v);
-
-        if (e !== NULL_POINTER && !is_live(edges, e)) {
-            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.VERTEX, v,
-                `vertex ${v} points at edge ${e}, which is not allocated`);
-        }
-    }
-
-    for (let e = 0; e < edges.size; e++) {
-        if (!edges.is_allocated(e)) {
-            continue;
-        }
-
-        const v1 = mesh.edge_read_vertex1(e);
-        const v2 = mesh.edge_read_vertex2(e);
-
-        if (!is_live(vertices, v1)) {
-            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.EDGE, e,
-                `edge ${e} vertex1 = ${v1}, which is not allocated`);
-        }
-
-        if (!is_live(vertices, v2)) {
-            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.EDGE, e,
-                `edge ${e} vertex2 = ${v2}, which is not allocated`);
-        }
-
-        const l = mesh.edge_read_loop(e);
-
-        if (l !== NULL_POINTER && !is_live(loops, l)) {
-            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.EDGE, e,
-                `edge ${e} points at loop ${l}, which is not allocated`);
-        }
-    }
-
-    for (let l = 0; l < loops.size; l++) {
-        if (!loops.is_allocated(l)) {
-            continue;
-        }
-
-        const v = mesh.loop_read_vertex(l);
-        const e = mesh.loop_read_edge(l);
-        const f = mesh.loop_read_face(l);
-
-        if (!is_live(vertices, v)) {
-            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
-                `loop ${l} vertex = ${v}, which is not allocated`);
-        }
-
-        if (!is_live(edges, e)) {
-            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
-                `loop ${l} edge = ${e}, which is not allocated`);
-        }
-
-        if (f !== NULL_POINTER && !is_live(faces, f)) {
-            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
-                `loop ${l} face = ${f}, which is not allocated`);
-        }
-
-        const links = [
-            ['radial_next', mesh.loop_read_radial_next(l)],
-            ['radial_prev', mesh.loop_read_radial_prev(l)],
-            ['next', mesh.loop_read_next(l)],
-            ['prev', mesh.loop_read_prev(l)],
-        ];
-
-        for (let i = 0; i < links.length; i++) {
-            const name = links[i][0];
-            const target = links[i][1];
-
-            if (!is_live(loops, target)) {
-                record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
-                    `loop ${l} ${name} = ${target}, which is not allocated`);
-            }
-        }
-    }
-
-    for (let f = 0; f < faces.size; f++) {
-        if (!faces.is_allocated(f)) {
-            continue;
-        }
-
-        const l = mesh.face_read_loop(f);
-
-        if (!is_live(loops, l)) {
-            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.FACE, f,
-                `face ${f} points at loop ${l}, which is not allocated`);
-        }
-    }
-}
-
-/**
- * Walk every vertex's disk cycle and check it is a closed doubly-linked ring
- * whose members all touch that vertex, then check that every allocated edge was
- * reached through both of its endpoints.
- *
- * Self-loops (`vertex1 === vertex2`) occupy the v1 slot only and their
- * v2_disk_link is unspecified, so they are expected on exactly one side. See the
- * disk cycle convention documented on {@link BinaryTopology}.
- *
- * @param {BinaryTopology} mesh
- * @param {object[]} out
- */
-function check_disk_cycles(mesh, out) {
-    const vertices = mesh.vertices;
-    const edges = mesh.edges;
-
-    const edge_seen = new Uint8Array(edges.size);
-
-    for (let v = 0; v < vertices.size; v++) {
-        if (!vertices.is_allocated(v)) {
-            continue;
-        }
-
-        const start = mesh.vertex_read_edge(v);
-
-        if (start === NULL_POINTER || !is_live(edges, start)) {
-            continue;
-        }
-
-        let e = start;
-        // The cycle cannot legally be longer than the pool, so this bounds a walk over
-        // corrupt links without hiding the corruption -- it is reported below.
-        let steps = 0;
-        let closed = false;
-
-        do {
-            const v1 = mesh.edge_read_vertex1(e);
-            const v2 = mesh.edge_read_vertex2(e);
-
-            const is_v1 = v1 === v;
-
-            if (!is_v1 && v2 !== v) {
-                record(out, BT_DEFECT.DISK_EDGE_VERTEX_MISMATCH, BT_ELEMENT_TYPE.EDGE, e,
-                    `edge ${e} is on vertex ${v}'s disk cycle but connects ${v1} and ${v2}`);
-                break;
-            }
-
-            edge_seen[e] |= is_v1 ? SEEN_V1 : SEEN_V2;
-
-            const next = is_v1 ? mesh.edge_read_v1_disk_next(e) : mesh.edge_read_v2_disk_next(e);
-
-            if (!is_live(edges, next)) {
-                record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.VERTEX, v,
-                    `vertex ${v} disk cycle leaves the pool at edge ${e} (next = ${next})`);
-                break;
-            }
-
-            // prev of next, taken on next's slot for v, must come back to e
-            const next_is_v1 = mesh.edge_read_vertex1(next) === v;
-            const back = next_is_v1 ? mesh.edge_read_v1_disk_prev(next) : mesh.edge_read_v2_disk_prev(next);
-
-            if (back !== e) {
-                record(out, BT_DEFECT.CYCLE_LINK_ASYMMETRIC, BT_ELEMENT_TYPE.VERTEX, v,
-                    `vertex ${v} disk cycle: next(${e}) = ${next} but prev(${next}) = ${back}`);
-                break;
-            }
-
-            e = next;
-            steps++;
-
-            if (e === start) {
-                closed = true;
-                break;
-            }
-        } while (steps <= edges.size);
-
-        if (!closed && steps > edges.size) {
-            record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.VERTEX, v,
-                `vertex ${v} disk cycle did not return to edge ${start} within ${edges.size} steps`);
-        }
-    }
-
-    for (let e = 0; e < edges.size; e++) {
-        if (!edges.is_allocated(e)) {
-            continue;
-        }
-
-        const v1 = mesh.edge_read_vertex1(e);
-        const v2 = mesh.edge_read_vertex2(e);
-
-        if (!is_live(vertices, v1) || !is_live(vertices, v2)) {
-            // already reported by check_references
-            continue;
-        }
-
-        if ((edge_seen[e] & SEEN_V1) === 0) {
-            record(out, BT_DEFECT.EDGE_NOT_IN_DISK, BT_ELEMENT_TYPE.EDGE, e,
-                `edge ${e} is not on the disk cycle of its vertex1 (${v1})`);
-        }
-
-        if (v1 !== v2 && (edge_seen[e] & SEEN_V2) === 0) {
-            record(out, BT_DEFECT.EDGE_NOT_IN_DISK, BT_ELEMENT_TYPE.EDGE, e,
-                `edge ${e} is not on the disk cycle of its vertex2 (${v2})`);
-        }
-    }
-}
-
-/**
- * Walk every edge's radial cycle and check it is a closed doubly-linked ring of
- * loops that all claim that edge, then check every allocated loop was reached
- * through the edge it claims.
- *
- * @param {BinaryTopology} mesh
- * @param {object[]} out
- */
-function check_radial_cycles(mesh, out) {
-    const edges = mesh.edges;
-    const loops = mesh.loops;
-
-    const loop_seen = new Uint8Array(loops.size);
-
-    for (let e = 0; e < edges.size; e++) {
-        if (!edges.is_allocated(e)) {
-            continue;
-        }
-
-        const start = mesh.edge_read_loop(e);
-
-        if (start === NULL_POINTER || !is_live(loops, start)) {
-            continue;
-        }
-
-        let l = start;
-        let steps = 0;
-        let closed = false;
-
-        do {
-            if (mesh.loop_read_edge(l) !== e) {
-                record(out, BT_DEFECT.RADIAL_LOOP_EDGE_MISMATCH, BT_ELEMENT_TYPE.LOOP, l,
-                    `loop ${l} is on edge ${e}'s radial cycle but claims edge ${mesh.loop_read_edge(l)}`);
-                break;
-            }
-
-            loop_seen[l] = 1;
-
-            const next = mesh.loop_read_radial_next(l);
-
-            if (!is_live(loops, next)) {
-                record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.EDGE, e,
-                    `edge ${e} radial cycle leaves the pool at loop ${l} (radial_next = ${next})`);
-                break;
-            }
-
-            const back = mesh.loop_read_radial_prev(next);
-
-            if (back !== l) {
-                record(out, BT_DEFECT.CYCLE_LINK_ASYMMETRIC, BT_ELEMENT_TYPE.EDGE, e,
-                    `edge ${e} radial cycle: radial_next(${l}) = ${next} but radial_prev(${next}) = ${back}`);
-                break;
-            }
-
-            l = next;
-            steps++;
-
-            if (l === start) {
-                closed = true;
-                break;
-            }
-        } while (steps <= loops.size);
-
-        if (!closed && steps > loops.size) {
-            record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.EDGE, e,
-                `edge ${e} radial cycle did not return to loop ${start} within ${loops.size} steps`);
-        }
-    }
-
-    for (let l = 0; l < loops.size; l++) {
-        if (!loops.is_allocated(l)) {
-            continue;
-        }
-
-        const e = mesh.loop_read_edge(l);
-
-        if (!is_live(edges, e)) {
-            // already reported by check_references
-            continue;
-        }
-
-        if (loop_seen[l] === 0) {
-            record(out, BT_DEFECT.LOOP_NOT_IN_RADIAL, BT_ELEMENT_TYPE.LOOP, l,
-                `loop ${l} claims edge ${e} but is not on that edge's radial cycle`);
-        }
-    }
-}
-
-/**
- * Walk every face's loop cycle. Checks closure, `prev`/`next` symmetry, that
- * every corner claims the face, that the face has at least three corners with no
- * repeated vertex, and that each corner's edge spans that corner's vertex and the
- * next corner's vertex. Finally reports allocated loops no face can reach.
- *
- * @param {BinaryTopology} mesh
- * @param {object[]} out
- */
-function check_face_cycles(mesh, out) {
-    const loops = mesh.loops;
-    const faces = mesh.faces;
-
-    const loop_seen = new Uint8Array(loops.size);
-
-    // Reused across faces so a fan of small faces does not allocate per face.
-    const cycle_vertices = [];
-
-    for (let f = 0; f < faces.size; f++) {
-        if (!faces.is_allocated(f)) {
-            continue;
-        }
-
-        const start = mesh.face_read_loop(f);
-
-        if (!is_live(loops, start)) {
-            continue;
-        }
-
-        cycle_vertices.length = 0;
-
-        let l = start;
-        let steps = 0;
-        let closed = false;
-        let broken = false;
-
-        do {
-            if (mesh.loop_read_face(l) !== f) {
-                record(out, BT_DEFECT.FACE_LOOP_FACE_MISMATCH, BT_ELEMENT_TYPE.LOOP, l,
-                    `loop ${l} is on face ${f}'s loop cycle but claims face ${mesh.loop_read_face(l)}`);
-                broken = true;
-                break;
-            }
-
-            loop_seen[l] = 1;
-            cycle_vertices.push(mesh.loop_read_vertex(l));
-
-            const next = mesh.loop_read_next(l);
-
-            if (!is_live(loops, next)) {
-                record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.FACE, f,
-                    `face ${f} loop cycle leaves the pool at loop ${l} (next = ${next})`);
-                broken = true;
-                break;
-            }
-
-            const back = mesh.loop_read_prev(next);
-
-            if (back !== l) {
-                record(out, BT_DEFECT.CYCLE_LINK_ASYMMETRIC, BT_ELEMENT_TYPE.FACE, f,
-                    `face ${f} loop cycle: next(${l}) = ${next} but prev(${next}) = ${back}`);
-                broken = true;
-                break;
-            }
-
-            // the corner's edge must span this corner and the next one
-            const e = mesh.loop_read_edge(l);
-            const v_here = mesh.loop_read_vertex(l);
-            const v_next = mesh.loop_read_vertex(next);
-
-            if (is_live(mesh.edges, e)) {
-                const e1 = mesh.edge_read_vertex1(e);
-                const e2 = mesh.edge_read_vertex2(e);
-
-                const spans = (e1 === v_here && e2 === v_next) || (e1 === v_next && e2 === v_here);
-
-                if (!spans) {
-                    record(out, BT_DEFECT.LOOP_EDGE_ENDPOINT_MISMATCH, BT_ELEMENT_TYPE.LOOP, l,
-                        `loop ${l} spans vertices ${v_here}->${v_next} but its edge ${e} connects ${e1} and ${e2}`);
-                }
-            }
-
-            l = next;
-            steps++;
-
-            if (l === start) {
-                closed = true;
-                break;
-            }
-        } while (steps <= loops.size);
-
-        if (!closed && !broken) {
-            record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.FACE, f,
-                `face ${f} loop cycle did not return to loop ${start} within ${loops.size} steps`);
-            continue;
-        }
-
-        if (broken) {
-            continue;
-        }
-
-        if (cycle_vertices.length < 3) {
-            record(out, BT_DEFECT.FACE_TOO_FEW_CORNERS, BT_ELEMENT_TYPE.FACE, f,
-                `face ${f} has ${cycle_vertices.length} corner(s)`);
-        }
-
-        for (let i = 0; i < cycle_vertices.length; i++) {
-            for (let j = i + 1; j < cycle_vertices.length; j++) {
-                if (cycle_vertices[i] === cycle_vertices[j]) {
-                    record(out, BT_DEFECT.FACE_VERTEX_REPEATED, BT_ELEMENT_TYPE.FACE, f,
-                        `face ${f} visits vertex ${cycle_vertices[i]} at corners ${i} and ${j}`);
-                }
-            }
-        }
-    }
-
-    for (let l = 0; l < loops.size; l++) {
-        if (!loops.is_allocated(l)) {
-            continue;
-        }
-
-        if (loop_seen[l] === 0) {
-            record(out, BT_DEFECT.LOOP_ORPHANED, BT_ELEMENT_TYPE.LOOP, l,
-                `loop ${l} is allocated but no face's loop cycle reaches it`);
-        }
-    }
-}
-
-/**
- * Vertex coordinates and normals, and face normals, must be finite. A NaN here
- * survives every topological check and only surfaces much later as an empty
- * bounding box or a black triangle.
- *
- * @param {BinaryTopology} mesh
- * @param {object[]} out
- */
-function check_finite_values(mesh, out) {
-    const vertices = mesh.vertices;
-    const faces = mesh.faces;
-
-    const scratch = new Float32Array(3);
-
-    for (let v = 0; v < vertices.size; v++) {
-        if (!vertices.is_allocated(v)) {
-            continue;
-        }
-
-        mesh.vertex_read_coordinate(scratch, 0, v);
-
-        if (!Number.isFinite(scratch[0]) || !Number.isFinite(scratch[1]) || !Number.isFinite(scratch[2])) {
-            record(out, BT_DEFECT.NON_FINITE_VALUE, BT_ELEMENT_TYPE.VERTEX, v,
-                `vertex ${v} coordinate is (${scratch[0]}, ${scratch[1]}, ${scratch[2]})`);
-        }
-    }
-
-    for (let f = 0; f < faces.size; f++) {
-        if (!faces.is_allocated(f)) {
-            continue;
-        }
-
-        mesh.face_read_normal(scratch, 0, f);
-
-        if (!Number.isFinite(scratch[0]) || !Number.isFinite(scratch[1]) || !Number.isFinite(scratch[2])) {
-            record(out, BT_DEFECT.NON_FINITE_VALUE, BT_ELEMENT_TYPE.FACE, f,
-                `face ${f} normal is (${scratch[0]}, ${scratch[1]}, ${scratch[2]})`);
-        }
-    }
-}
-
-/**
- * Check every structural invariant of a {@link BinaryTopology} and return the
- * defects found. An empty result means the mesh is internally consistent: every
- * handle resolves, every disk / radial / face-loop cycle is a closed
- * doubly-linked ring, every element agrees with the elements that reference it,
- * and every stored coordinate is finite.
- *
- * This is the counterpart to manifold's `IsManifold()` -- the invariant checker
- * that makes a pile of topology-surgery primitives trustworthy. `BinaryTopology`
- * has ~40 mutators (`bt_edge_collapse`, `bt_vert_splice`, `bt_radial_loop_remove`,
- * `bt_face_poke`, ...), each of which can scribble a cycle; without this, nothing
- * notices until a much later operation reads garbage. Run it in specs after any
- * mutation, and in prototypes after any pipeline stage.
- *
- * What it deliberately does NOT check, because `BinaryTopology` permits all of
- * them by design: wire edges (no incident face), boundary edges (one face),
- * non-manifold edges (three or more faces), n-gon faces, disconnected islands.
- * For those, see {@link bt_mesh_is_manifold} and {@link bt_mesh_is_closed}.
- *
- * O(V + E + L + F) except for the repeated-vertex check, which is quadratic in a
- * single face's corner count (faces are small; a 1000-gon would be the anomaly,
- * not the cost).
- *
- * Cycle walks are bounded by the corresponding pool's size. That bound is the
- * theoretical maximum of a legal cycle, so hitting it is itself a defect and is
- * reported as {@link BT_DEFECT.CYCLE_NOT_CLOSED} rather than swallowed.
- *
- * @param {BinaryTopology} mesh
- * @returns {{code:number, element_type:number, element:number, detail:string}[]}
- *     defects found, in discovery order; empty when the mesh is consistent
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function bt_mesh_validate(mesh) {
-    const out = [];
-
-    check_references(mesh, out);
-    check_disk_cycles(mesh, out);
-    check_radial_cycles(mesh, out);
-    check_face_cycles(mesh, out);
-    check_finite_values(mesh, out);
-
-    return out;
-}
+import { NULL_POINTER } from "../BinaryTopology.js";
+
+/**
+ * Which kind of element a defect was found on. Typed constant (no stringly-typed
+ * states), mirroring the four pools of {@link BinaryTopology}.
+ * @readonly
+ */
+export const BT_ELEMENT_TYPE = Object.freeze({
+    VERTEX: 0,
+    EDGE: 1,
+    LOOP: 2,
+    FACE: 3,
+});
+
+/**
+ * Structural defects {@link bt_mesh_validate} can report. Each value names a
+ * broken invariant of {@link BinaryTopology}, not a symptom.
+ * @readonly
+ */
+export const BT_DEFECT = Object.freeze({
+    /** A handle points at a pool slot that is not allocated (dangling reference). */
+    DANGLING_REFERENCE: 0,
+    /** A cycle (disk / radial / face-loop) does not return to its start within the pool's size. */
+    CYCLE_NOT_CLOSED: 1,
+    /** `prev` is not the inverse of `next` somewhere on a cycle. */
+    CYCLE_LINK_ASYMMETRIC: 2,
+    /** An edge is missing from the disk cycle of one of its vertices. */
+    EDGE_NOT_IN_DISK: 3,
+    /** An edge sits on the disk cycle of a vertex that is not one of its endpoints. */
+    DISK_EDGE_VERTEX_MISMATCH: 4,
+    /** A loop is missing from the radial cycle of the edge it claims. */
+    LOOP_NOT_IN_RADIAL: 5,
+    /** A loop on an edge's radial cycle does not claim that edge. */
+    RADIAL_LOOP_EDGE_MISMATCH: 6,
+    /** A loop on a face's loop cycle does not claim that face. */
+    FACE_LOOP_FACE_MISMATCH: 7,
+    /** A face's loop cycle is shorter than three corners. */
+    FACE_TOO_FEW_CORNERS: 8,
+    /** The same vertex appears twice on one face's loop cycle. */
+    FACE_VERTEX_REPEATED: 9,
+    /** A loop's edge does not connect that loop's vertex to the next loop's vertex. */
+    LOOP_EDGE_ENDPOINT_MISMATCH: 10,
+    /** An allocated loop is not reachable from any allocated face. */
+    LOOP_ORPHANED: 11,
+    /** A vertex with incident edges has a NULL edge pointer, or vice versa. */
+    VERTEX_EDGE_POINTER_INCONSISTENT: 12,
+    /** A coordinate or normal component is not finite. */
+    NON_FINITE_VALUE: 13,
+});
+
+/**
+ * Bit set in `edge_seen` once an edge has been reached through its v1 disk slot.
+ * @type {number}
+ */
+const SEEN_V1 = 1;
+/**
+ * Bit set in `edge_seen` once an edge has been reached through its v2 disk slot.
+ * @type {number}
+ */
+const SEEN_V2 = 2;
+
+/**
+ * @param {object[]} out
+ * @param {number} code one of {@link BT_DEFECT}
+ * @param {number} element_type one of {@link BT_ELEMENT_TYPE}
+ * @param {number} element
+ * @param {string} detail
+ */
+function record(out, code, element_type, element, detail) {
+    out.push({ code, element_type, element, detail });
+}
+
+/**
+ * True when `id` is a live slot of `pool`, i.e. safe to dereference.
+ * @param {BinaryElementPool} pool
+ * @param {number} id
+ * @returns {boolean}
+ */
+function is_live(pool, id) {
+    return id !== NULL_POINTER && id < pool.size && pool.is_allocated(id);
+}
+
+/**
+ * Check every handle an element stores actually points at a live slot of the
+ * right pool. Runs first so the cycle walks below can dereference freely.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_references(mesh, out) {
+    const vertices = mesh.vertices;
+    const edges = mesh.edges;
+    const loops = mesh.loops;
+    const faces = mesh.faces;
+
+    for (let v = 0; v < vertices.size; v++) {
+        if (!vertices.is_allocated(v)) {
+            continue;
+        }
+
+        const e = mesh.vertex_read_edge(v);
+
+        if (e !== NULL_POINTER && !is_live(edges, e)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.VERTEX, v,
+                `vertex ${v} points at edge ${e}, which is not allocated`);
+        }
+    }
+
+    for (let e = 0; e < edges.size; e++) {
+        if (!edges.is_allocated(e)) {
+            continue;
+        }
+
+        const v1 = mesh.edge_read_vertex1(e);
+        const v2 = mesh.edge_read_vertex2(e);
+
+        if (!is_live(vertices, v1)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} vertex1 = ${v1}, which is not allocated`);
+        }
+
+        if (!is_live(vertices, v2)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} vertex2 = ${v2}, which is not allocated`);
+        }
+
+        const l = mesh.edge_read_loop(e);
+
+        if (l !== NULL_POINTER && !is_live(loops, l)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} points at loop ${l}, which is not allocated`);
+        }
+    }
+
+    for (let l = 0; l < loops.size; l++) {
+        if (!loops.is_allocated(l)) {
+            continue;
+        }
+
+        const v = mesh.loop_read_vertex(l);
+        const e = mesh.loop_read_edge(l);
+        const f = mesh.loop_read_face(l);
+
+        if (!is_live(vertices, v)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} vertex = ${v}, which is not allocated`);
+        }
+
+        if (!is_live(edges, e)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} edge = ${e}, which is not allocated`);
+        }
+
+        if (f !== NULL_POINTER && !is_live(faces, f)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} face = ${f}, which is not allocated`);
+        }
+
+        const links = [
+            ['radial_next', mesh.loop_read_radial_next(l)],
+            ['radial_prev', mesh.loop_read_radial_prev(l)],
+            ['next', mesh.loop_read_next(l)],
+            ['prev', mesh.loop_read_prev(l)],
+        ];
+
+        for (let i = 0; i < links.length; i++) {
+            const name = links[i][0];
+            const target = links[i][1];
+
+            if (!is_live(loops, target)) {
+                record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.LOOP, l,
+                    `loop ${l} ${name} = ${target}, which is not allocated`);
+            }
+        }
+    }
+
+    for (let f = 0; f < faces.size; f++) {
+        if (!faces.is_allocated(f)) {
+            continue;
+        }
+
+        const l = mesh.face_read_loop(f);
+
+        if (!is_live(loops, l)) {
+            record(out, BT_DEFECT.DANGLING_REFERENCE, BT_ELEMENT_TYPE.FACE, f,
+                `face ${f} points at loop ${l}, which is not allocated`);
+        }
+    }
+}
+
+/**
+ * Walk every vertex's disk cycle and check it is a closed doubly-linked ring
+ * whose members all touch that vertex, then check that every allocated edge was
+ * reached through both of its endpoints.
+ *
+ * Self-loops (`vertex1 === vertex2`) occupy the v1 slot only and their
+ * v2_disk_link is unspecified, so they are expected on exactly one side. See the
+ * disk cycle convention documented on {@link BinaryTopology}.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_disk_cycles(mesh, out) {
+    const vertices = mesh.vertices;
+    const edges = mesh.edges;
+
+    const edge_seen = new Uint8Array(edges.size);
+
+    for (let v = 0; v < vertices.size; v++) {
+        if (!vertices.is_allocated(v)) {
+            continue;
+        }
+
+        const start = mesh.vertex_read_edge(v);
+
+        if (start === NULL_POINTER || !is_live(edges, start)) {
+            continue;
+        }
+
+        let e = start;
+        // The cycle cannot legally be longer than the pool, so this bounds a walk over
+        // corrupt links without hiding the corruption -- it is reported below.
+        let steps = 0;
+        let closed = false;
+
+        do {
+            const v1 = mesh.edge_read_vertex1(e);
+            const v2 = mesh.edge_read_vertex2(e);
+
+            const is_v1 = v1 === v;
+
+            if (!is_v1 && v2 !== v) {
+                record(out, BT_DEFECT.DISK_EDGE_VERTEX_MISMATCH, BT_ELEMENT_TYPE.EDGE, e,
+                    `edge ${e} is on vertex ${v}'s disk cycle but connects ${v1} and ${v2}`);
+                break;
+            }
+
+            edge_seen[e] |= is_v1 ? SEEN_V1 : SEEN_V2;
+
+            const next = is_v1 ? mesh.edge_read_v1_disk_next(e) : mesh.edge_read_v2_disk_next(e);
+
+            if (!is_live(edges, next)) {
+                record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.VERTEX, v,
+                    `vertex ${v} disk cycle leaves the pool at edge ${e} (next = ${next})`);
+                break;
+            }
+
+            // prev of next, taken on next's slot for v, must come back to e
+            const next_is_v1 = mesh.edge_read_vertex1(next) === v;
+            const back = next_is_v1 ? mesh.edge_read_v1_disk_prev(next) : mesh.edge_read_v2_disk_prev(next);
+
+            if (back !== e) {
+                record(out, BT_DEFECT.CYCLE_LINK_ASYMMETRIC, BT_ELEMENT_TYPE.VERTEX, v,
+                    `vertex ${v} disk cycle: next(${e}) = ${next} but prev(${next}) = ${back}`);
+                break;
+            }
+
+            e = next;
+            steps++;
+
+            if (e === start) {
+                closed = true;
+                break;
+            }
+        } while (steps <= edges.size);
+
+        if (!closed && steps > edges.size) {
+            record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.VERTEX, v,
+                `vertex ${v} disk cycle did not return to edge ${start} within ${edges.size} steps`);
+        }
+    }
+
+    for (let e = 0; e < edges.size; e++) {
+        if (!edges.is_allocated(e)) {
+            continue;
+        }
+
+        const v1 = mesh.edge_read_vertex1(e);
+        const v2 = mesh.edge_read_vertex2(e);
+
+        if (!is_live(vertices, v1) || !is_live(vertices, v2)) {
+            // already reported by check_references
+            continue;
+        }
+
+        if ((edge_seen[e] & SEEN_V1) === 0) {
+            record(out, BT_DEFECT.EDGE_NOT_IN_DISK, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} is not on the disk cycle of its vertex1 (${v1})`);
+        }
+
+        if (v1 !== v2 && (edge_seen[e] & SEEN_V2) === 0) {
+            record(out, BT_DEFECT.EDGE_NOT_IN_DISK, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} is not on the disk cycle of its vertex2 (${v2})`);
+        }
+    }
+}
+
+/**
+ * Walk every edge's radial cycle and check it is a closed doubly-linked ring of
+ * loops that all claim that edge, then check every allocated loop was reached
+ * through the edge it claims.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_radial_cycles(mesh, out) {
+    const edges = mesh.edges;
+    const loops = mesh.loops;
+
+    const loop_seen = new Uint8Array(loops.size);
+
+    for (let e = 0; e < edges.size; e++) {
+        if (!edges.is_allocated(e)) {
+            continue;
+        }
+
+        const start = mesh.edge_read_loop(e);
+
+        if (start === NULL_POINTER || !is_live(loops, start)) {
+            continue;
+        }
+
+        let l = start;
+        let steps = 0;
+        let closed = false;
+
+        do {
+            if (mesh.loop_read_edge(l) !== e) {
+                record(out, BT_DEFECT.RADIAL_LOOP_EDGE_MISMATCH, BT_ELEMENT_TYPE.LOOP, l,
+                    `loop ${l} is on edge ${e}'s radial cycle but claims edge ${mesh.loop_read_edge(l)}`);
+                break;
+            }
+
+            loop_seen[l] = 1;
+
+            const next = mesh.loop_read_radial_next(l);
+
+            if (!is_live(loops, next)) {
+                record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.EDGE, e,
+                    `edge ${e} radial cycle leaves the pool at loop ${l} (radial_next = ${next})`);
+                break;
+            }
+
+            const back = mesh.loop_read_radial_prev(next);
+
+            if (back !== l) {
+                record(out, BT_DEFECT.CYCLE_LINK_ASYMMETRIC, BT_ELEMENT_TYPE.EDGE, e,
+                    `edge ${e} radial cycle: radial_next(${l}) = ${next} but radial_prev(${next}) = ${back}`);
+                break;
+            }
+
+            l = next;
+            steps++;
+
+            if (l === start) {
+                closed = true;
+                break;
+            }
+        } while (steps <= loops.size);
+
+        if (!closed && steps > loops.size) {
+            record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.EDGE, e,
+                `edge ${e} radial cycle did not return to loop ${start} within ${loops.size} steps`);
+        }
+    }
+
+    for (let l = 0; l < loops.size; l++) {
+        if (!loops.is_allocated(l)) {
+            continue;
+        }
+
+        const e = mesh.loop_read_edge(l);
+
+        if (!is_live(edges, e)) {
+            // already reported by check_references
+            continue;
+        }
+
+        if (loop_seen[l] === 0) {
+            record(out, BT_DEFECT.LOOP_NOT_IN_RADIAL, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} claims edge ${e} but is not on that edge's radial cycle`);
+        }
+    }
+}
+
+/**
+ * Walk every face's loop cycle. Checks closure, `prev`/`next` symmetry, that
+ * every corner claims the face, that the face has at least three corners with no
+ * repeated vertex, and that each corner's edge spans that corner's vertex and the
+ * next corner's vertex. Finally reports allocated loops no face can reach.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_face_cycles(mesh, out) {
+    const loops = mesh.loops;
+    const faces = mesh.faces;
+
+    const loop_seen = new Uint8Array(loops.size);
+
+    // Reused across faces so a fan of small faces does not allocate per face.
+    const cycle_vertices = [];
+
+    for (let f = 0; f < faces.size; f++) {
+        if (!faces.is_allocated(f)) {
+            continue;
+        }
+
+        const start = mesh.face_read_loop(f);
+
+        if (!is_live(loops, start)) {
+            continue;
+        }
+
+        cycle_vertices.length = 0;
+
+        let l = start;
+        let steps = 0;
+        let closed = false;
+        let broken = false;
+
+        do {
+            if (mesh.loop_read_face(l) !== f) {
+                record(out, BT_DEFECT.FACE_LOOP_FACE_MISMATCH, BT_ELEMENT_TYPE.LOOP, l,
+                    `loop ${l} is on face ${f}'s loop cycle but claims face ${mesh.loop_read_face(l)}`);
+                broken = true;
+                break;
+            }
+
+            loop_seen[l] = 1;
+            cycle_vertices.push(mesh.loop_read_vertex(l));
+
+            const next = mesh.loop_read_next(l);
+
+            if (!is_live(loops, next)) {
+                record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.FACE, f,
+                    `face ${f} loop cycle leaves the pool at loop ${l} (next = ${next})`);
+                broken = true;
+                break;
+            }
+
+            const back = mesh.loop_read_prev(next);
+
+            if (back !== l) {
+                record(out, BT_DEFECT.CYCLE_LINK_ASYMMETRIC, BT_ELEMENT_TYPE.FACE, f,
+                    `face ${f} loop cycle: next(${l}) = ${next} but prev(${next}) = ${back}`);
+                broken = true;
+                break;
+            }
+
+            // the corner's edge must span this corner and the next one
+            const e = mesh.loop_read_edge(l);
+            const v_here = mesh.loop_read_vertex(l);
+            const v_next = mesh.loop_read_vertex(next);
+
+            if (is_live(mesh.edges, e)) {
+                const e1 = mesh.edge_read_vertex1(e);
+                const e2 = mesh.edge_read_vertex2(e);
+
+                const spans = (e1 === v_here && e2 === v_next) || (e1 === v_next && e2 === v_here);
+
+                if (!spans) {
+                    record(out, BT_DEFECT.LOOP_EDGE_ENDPOINT_MISMATCH, BT_ELEMENT_TYPE.LOOP, l,
+                        `loop ${l} spans vertices ${v_here}->${v_next} but its edge ${e} connects ${e1} and ${e2}`);
+                }
+            }
+
+            l = next;
+            steps++;
+
+            if (l === start) {
+                closed = true;
+                break;
+            }
+        } while (steps <= loops.size);
+
+        if (!closed && !broken) {
+            record(out, BT_DEFECT.CYCLE_NOT_CLOSED, BT_ELEMENT_TYPE.FACE, f,
+                `face ${f} loop cycle did not return to loop ${start} within ${loops.size} steps`);
+            continue;
+        }
+
+        if (broken) {
+            continue;
+        }
+
+        if (cycle_vertices.length < 3) {
+            record(out, BT_DEFECT.FACE_TOO_FEW_CORNERS, BT_ELEMENT_TYPE.FACE, f,
+                `face ${f} has ${cycle_vertices.length} corner(s)`);
+        }
+
+        for (let i = 0; i < cycle_vertices.length; i++) {
+            for (let j = i + 1; j < cycle_vertices.length; j++) {
+                if (cycle_vertices[i] === cycle_vertices[j]) {
+                    record(out, BT_DEFECT.FACE_VERTEX_REPEATED, BT_ELEMENT_TYPE.FACE, f,
+                        `face ${f} visits vertex ${cycle_vertices[i]} at corners ${i} and ${j}`);
+                }
+            }
+        }
+    }
+
+    for (let l = 0; l < loops.size; l++) {
+        if (!loops.is_allocated(l)) {
+            continue;
+        }
+
+        if (loop_seen[l] === 0) {
+            record(out, BT_DEFECT.LOOP_ORPHANED, BT_ELEMENT_TYPE.LOOP, l,
+                `loop ${l} is allocated but no face's loop cycle reaches it`);
+        }
+    }
+}
+
+/**
+ * Vertex coordinates and normals, and face normals, must be finite. A NaN here
+ * survives every topological check and only surfaces much later as an empty
+ * bounding box or a black triangle.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {object[]} out
+ */
+function check_finite_values(mesh, out) {
+    const vertices = mesh.vertices;
+    const faces = mesh.faces;
+
+    const scratch = new Float32Array(3);
+
+    for (let v = 0; v < vertices.size; v++) {
+        if (!vertices.is_allocated(v)) {
+            continue;
+        }
+
+        mesh.vertex_read_coordinate(scratch, 0, v);
+
+        if (!Number.isFinite(scratch[0]) || !Number.isFinite(scratch[1]) || !Number.isFinite(scratch[2])) {
+            record(out, BT_DEFECT.NON_FINITE_VALUE, BT_ELEMENT_TYPE.VERTEX, v,
+                `vertex ${v} coordinate is (${scratch[0]}, ${scratch[1]}, ${scratch[2]})`);
+        }
+    }
+
+    for (let f = 0; f < faces.size; f++) {
+        if (!faces.is_allocated(f)) {
+            continue;
+        }
+
+        mesh.face_read_normal(scratch, 0, f);
+
+        if (!Number.isFinite(scratch[0]) || !Number.isFinite(scratch[1]) || !Number.isFinite(scratch[2])) {
+            record(out, BT_DEFECT.NON_FINITE_VALUE, BT_ELEMENT_TYPE.FACE, f,
+                `face ${f} normal is (${scratch[0]}, ${scratch[1]}, ${scratch[2]})`);
+        }
+    }
+}
+
+/**
+ * Check every structural invariant of a {@link BinaryTopology} and return the
+ * defects found. An empty result means the mesh is internally consistent: every
+ * handle resolves, every disk / radial / face-loop cycle is a closed
+ * doubly-linked ring, every element agrees with the elements that reference it,
+ * and every stored coordinate is finite.
+ *
+ * This is the counterpart to manifold's `IsManifold()` -- the invariant checker
+ * that makes a pile of topology-surgery primitives trustworthy. `BinaryTopology`
+ * has ~40 mutators (`bt_edge_collapse`, `bt_vert_splice`, `bt_radial_loop_remove`,
+ * `bt_face_poke`, ...), each of which can scribble a cycle; without this, nothing
+ * notices until a much later operation reads garbage. Run it in specs after any
+ * mutation, and in prototypes after any pipeline stage.
+ *
+ * What it deliberately does NOT check, because `BinaryTopology` permits all of
+ * them by design: wire edges (no incident face), boundary edges (one face),
+ * non-manifold edges (three or more faces), n-gon faces, disconnected islands.
+ * For those, see {@link bt_mesh_is_manifold} and {@link bt_mesh_is_closed}.
+ *
+ * O(V + E + L + F) except for the repeated-vertex check, which is quadratic in a
+ * single face's corner count (faces are small; a 1000-gon would be the anomaly,
+ * not the cost).
+ *
+ * Cycle walks are bounded by the corresponding pool's size. That bound is the
+ * theoretical maximum of a legal cycle, so hitting it is itself a defect and is
+ * reported as {@link BT_DEFECT.CYCLE_NOT_CLOSED} rather than swallowed.
+ *
+ * @param {BinaryTopology} mesh
+ * @returns {{code:number, element_type:number, element:number, detail:string}[]}
+ *     defects found, in discovery order; empty when the mesh is consistent
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_mesh_validate(mesh) {
+    const out = [];
+
+    check_references(mesh, out);
+    check_disk_cycles(mesh, out);
+    check_radial_cycles(mesh, out);
+    check_face_cycles(mesh, out);
+    check_finite_values(mesh, out);
+
+    return out;
+}