@woosh/meep-engine 3.1.0 → 3.3.0

package/src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js

@@ -1,1622 +1,1622 @@
-import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
-import { round_up } from "../../../../../core/math/round_up.js";
-import { VGEO_CHILD_TABLE_ENTRY_SIZE } from "./frame/VGEO_CHILD_TABLE_ENTRY_SIZE.js";
-import { VGEO_CLUSTER_RECORD_SIZE } from "./cluster/VGEO_CLUSTER_RECORD_SIZE.js";
-import { VGEO_CODEC_LZ4 } from "./frame/VGEO_CODEC_LZ4.js";
-import { VGEO_CODEC_RAW } from "./frame/VGEO_CODEC_RAW.js";
-import { vgeo_compute_asset_id } from "./checksum/vgeo_compute_asset_id.js";
-import { vgeo_compute_directory_block_checksum } from "./checksum/vgeo_compute_directory_block_checksum.js";
-import { vgeo_compute_frame_checksum } from "./checksum/vgeo_compute_frame_checksum.js";
-import { vgeo_compute_header_checksum } from "./checksum/vgeo_compute_header_checksum.js";
-import { VGEO_DEFECT } from "./VGEO_DEFECT.js";
-import { vgeo_directory_block_count } from "./directory/vgeo_directory_block_count.js";
-import { VGEO_DIRECTORY_FLAG_ROOT_PAGE } from "./directory/VGEO_DIRECTORY_FLAG_ROOT_PAGE.js";
-import { VGEO_DIRECTORY_RECORD_SIZE } from "./directory/VGEO_DIRECTORY_RECORD_SIZE.js";
-import { vgeo_decode_frame_blob } from "./frame/vgeo_decode_frame_blob.js";
-import { VGEO_ENCODING_FLAGS_MASK } from "./payload/VGEO_ENCODING_FLAGS_MASK.js";
-import { VGEO_FORMAT_VERSION } from "./header/VGEO_FORMAT_VERSION.js";
-import { VGEO_FRAME_ALIGNMENT } from "./frame/VGEO_FRAME_ALIGNMENT.js";
-import { vgeo_frame_decode_bound } from "./frame/vgeo_frame_decode_bound.js";
-import { VGEO_FRAME_HEADER_SIZE } from "./frame/VGEO_FRAME_HEADER_SIZE.js";
-import { VGEO_FRAME_OFFSET } from "./frame/VGEO_FRAME_OFFSET.js";
-import { VGEO_GROUP_RECORD_SIZE } from "./page/VGEO_GROUP_RECORD_SIZE.js";
-import { VGEO_HASH_ALGO_XXH3 } from "./header/VGEO_HASH_ALGO_XXH3.js";
-import { VGEO_HEADER_OFFSET } from "./header/VGEO_HEADER_OFFSET.js";
-import { VGEO_HEADER_SIZE } from "./header/VGEO_HEADER_SIZE.js";
-import { VGEO_LEVEL_RECORD_SIZE } from "./header/VGEO_LEVEL_RECORD_SIZE.js";
-import { VGEO_MAGIC } from "./header/VGEO_MAGIC.js";
-import { VGEO_MAX_CHILD_REF } from "./cluster/VGEO_MAX_CHILD_REF.js";
-import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "./cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
-import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "./cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
-import { VGEO_MAX_GROUP_CLUSTER_COUNT } from "./page/VGEO_MAX_GROUP_CLUSTER_COUNT.js";
-import { VGEO_MIN_READER_VERSION } from "./header/VGEO_MIN_READER_VERSION.js";
-import { VGEO_NO_CHILD } from "./cluster/VGEO_NO_CHILD.js";
-import { VGEO_NO_GROUP } from "./cluster/VGEO_NO_GROUP.js";
-import { VGEO_NODE_FANOUT } from "./page/VGEO_NODE_FANOUT.js";
-import { VGEO_NODE_FLAG_LEAF } from "./page/VGEO_NODE_FLAG_LEAF.js";
-import { VGEO_NODE_OFFSET } from "./page/VGEO_NODE_OFFSET.js";
-import { VGEO_NODE_RECORD_SIZE } from "./page/VGEO_NODE_RECORD_SIZE.js";
-import { VGEO_PAGE_HEADER_SIZE } from "./page/VGEO_PAGE_HEADER_SIZE.js";
-import { VGEO_PAGE_MAGIC } from "./frame/VGEO_PAGE_MAGIC.js";
-import { VGEO_PAGE_OFFSET } from "./page/VGEO_PAGE_OFFSET.js";
-import { vgeo_payload_attribute_offset } from "./payload/vgeo_payload_attribute_offset.js";
-import { VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1 } from "./header/VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1.js";
-import { vgeo_payload_size } from "./payload/vgeo_payload_size.js";
-import { VGEO_SAME_PAGE } from "./cluster/VGEO_SAME_PAGE.js";
-import { vgeo_scan_frames } from "./frame/vgeo_scan_frames.js";
-import { VGeoDefect } from "./VGeoDefect.js";
-
-/**
- * A full audit of a `.vgeo` file against VGEO_FORMAT §11 — every build invariant, every checksum,
- * and the directory checked against what a frame scan reconstructs.
- *
- * It reads nothing but the bytes it is given: no builder state, no side channel. That is the point —
- * a file that passes here is one a reader can trust, whoever produced it.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * A page's decoded form. Under codec 0 the decoded page is the frame's own bytes, so this holds the
- * absolute offset of its first byte rather than a copy; a compressing codec decodes into its own
- * buffer and `base` is 0 there. Everything downstream reads through {@link buffer} and {@link seek},
- * so which of the two it was never reaches a check.
- */
-class DecodedPage {
-    /**
-     * @type {number}
-     */
-    page_index = 0;
-
-    /**
-     * @type {VGeoFrameExtent}
-     */
-    frame = null;
-
-    /**
-     * Where the decoded page's byte 0 sits in {@link buffer}.
-     * @type {number}
-     */
-    base = 0;
-
-    /**
-     * @type {BinaryBuffer}
-     */
-    buffer = null;
-
-    /**
-     * @type {number}
-     */
-    size = 0;
-
-    group_count = 0;
-    cluster_count = 0;
-    min_level = 0;
-    max_level = 0;
-
-    /**
-     * @type {number}
-     */
-    node_count = 0;
-
-    /**
-     * @type {number}
-     */
-    node_table_offset = 0;
-
-    /**
-     * @type {VGeoMetric}
-     */
-    metric = null;
-    cluster_table_offset = 0;
-    payload_offset = 0;
-    payload_size = 0;
-
-    /**
-     * `[page_index, ...]` in child-table order.
-     * @type {number[]}
-     */
-    child_pages = [];
-
-    /**
-     * Position `buffer` at a page-relative offset.
-     * @param {number} offset
-     */
-    seek(offset) {
-        this.buffer.position = this.base + offset;
-    }
-}
-
-/**
- * @param {BinaryBuffer} buffer positioned at the sphere
- * @returns {number[]} `[x, y, z, radius]`
- */
-function read_sphere(buffer) {
-    const result = new Float32Array(4);
-
-    buffer.readFloat32Array(result, 0, 4);
-
-    return Array.from(result);
-}
-
-/**
- * @param {BinaryBuffer} buffer positioned at the box
- * @returns {number[]} `[min_x, min_y, min_z, max_x, max_y, max_z]`
- */
-function read_aabb(buffer) {
-    const result = new Float32Array(6);
-
-    buffer.readFloat32Array(result, 0, 6);
-
-    return Array.from(result);
-}
-
-/**
- * @param {number[]} outer
- * @param {number[]} inner
- * @returns {boolean} whether `outer` contains `inner`, evaluated on the stored values exactly
- */
-function sphere_contains_sphere(outer, inner) {
-    const dx = inner[0] - outer[0];
-    const dy = inner[1] - outer[1];
-    const dz = inner[2] - outer[2];
-
-    return Math.sqrt(dx * dx + dy * dy + dz * dz) + inner[3] <= outer[3];
-}
-
-/**
- * @param {number[]} sphere
- * @param {number} x
- * @param {number} y
- * @param {number} z
- * @returns {boolean}
- */
-function sphere_contains_point(sphere, x, y, z) {
-    const dx = x - sphere[0];
-    const dy = y - sphere[1];
-    const dz = z - sphere[2];
-
-    return Math.sqrt(dx * dx + dy * dy + dz * dz) <= sphere[3];
-}
-
-/**
- * @param {BinaryBuffer} buffer whole file
- * @param {VGeoDefect[]} out
- * @returns {boolean} whether the header is sane enough for the rest of the audit to proceed
- */
-function check_header(buffer, out) {
-    if (buffer.capacity < VGEO_HEADER_SIZE) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `file is ${buffer.capacity} bytes, shorter than the ${VGEO_HEADER_SIZE} byte header`));
-
-        return false;
-    }
-
-    let usable = true;
-
-    buffer.position = 0;
-
-    const magic = buffer.readUint32();
-
-    if (magic !== VGEO_MAGIC) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `magic is 0x${magic.toString(16)}, expected 0x${VGEO_MAGIC.toString(16)}`));
-
-        usable = false;
-    }
-
-    const format_version = buffer.readUint16();
-
-    if (format_version !== VGEO_FORMAT_VERSION) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `format_version is ${format_version}, this validator knows ${VGEO_FORMAT_VERSION}`));
-
-        usable = false;
-    }
-
-    const min_reader_version = buffer.readUint16();
-
-    if (min_reader_version !== VGEO_MIN_READER_VERSION) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `min_reader_version is ${min_reader_version}, expected ${VGEO_MIN_READER_VERSION}`));
-    }
-
-    const header_size = buffer.readUint16();
-
-    if (header_size !== VGEO_HEADER_SIZE) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `header_size is ${header_size}, expected ${VGEO_HEADER_SIZE}`));
-    }
-
-    const hash_algo = buffer.readUint8();
-
-    if (hash_algo !== VGEO_HASH_ALGO_XXH3) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `hash_algo is ${hash_algo}, expected ${VGEO_HASH_ALGO_XXH3}`));
-
-        usable = false;
-    }
-
-    if (buffer.readUint8() !== 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'reserved byte at 11 is not zero'));
-    }
-
-    const feature_flags_required = buffer.readUint32();
-
-    if (feature_flags_required !== 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `feature_flags_required is 0x${feature_flags_required.toString(16)}, no bit is defined`));
-
-        usable = false;
-    }
-
-    buffer.position = VGEO_HEADER_OFFSET.PAYLOAD_ENCODING;
-
-    const payload_encoding = buffer.readUint32();
-
-    if (payload_encoding !== VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `payload_encoding is ${payload_encoding}, expected ${VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1}`));
-
-        usable = false;
-    }
-
-    buffer.position = VGEO_HEADER_OFFSET.TOTAL_PAGES;
-
-    const total_pages = buffer.readUint32();
-
-    if (total_pages < 1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'total_pages is 0'));
-
-        usable = false;
-    }
-
-    const total_clusters = Number(buffer.readUint64());
-
-    if (total_clusters < 1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'total_clusters is 0'));
-    }
-
-    const total_groups = Number(buffer.readUint64());
-
-    if (total_groups < 1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'total_groups is 0'));
-    }
-
-    const root_page_offset = Number(buffer.readUint64());
-
-    buffer.position = VGEO_HEADER_OFFSET.DIRECTORY_OFFSET;
-
-    const directory_offset = Number(buffer.readUint64());
-
-    if (directory_offset % VGEO_FRAME_ALIGNMENT !== 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `directory_offset ${directory_offset} is not ${VGEO_FRAME_ALIGNMENT}-aligned`));
-
-        usable = false;
-    }
-
-    if (directory_offset <= VGEO_HEADER_SIZE || directory_offset > buffer.capacity) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `directory_offset ${directory_offset} is outside the file`));
-
-        return false;
-    }
-
-    const dir_block_checksums_offset = Number(buffer.readUint64());
-
-    const expected_dir_block_offset = directory_offset + total_pages * VGEO_DIRECTORY_RECORD_SIZE;
-
-    if (dir_block_checksums_offset !== expected_dir_block_offset) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `dir_block_checksums_offset is ${dir_block_checksums_offset}, expected ${expected_dir_block_offset}`));
-
-        usable = false;
-    }
-
-    const expected_length = dir_block_checksums_offset + vgeo_directory_block_count(total_pages) * 8;
-
-    if (usable && buffer.capacity !== expected_length) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `file is ${buffer.capacity} bytes, the header describes ${expected_length}`));
-
-        usable = false;
-    }
-
-    buffer.position = 100;
-
-    if (buffer.readUint16() !== 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'reserved u16 at 100 is not zero'));
-    }
-
-    const level_count = buffer.readUint8();
-
-    if (level_count < 1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'level_count is 0'));
-
-        usable = false;
-    }
-
-    // The frame region begins after the level table, not at a fixed offset — which is what keeps
-    // the header, the whole table and the always-resident root page in one contiguous head fetch.
-    const expected_root_page_offset = round_up(
-        VGEO_HEADER_SIZE + level_count * VGEO_LEVEL_RECORD_SIZE, VGEO_FRAME_ALIGNMENT
-    );
-
-    if (root_page_offset !== expected_root_page_offset) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `root_page_offset is ${root_page_offset}; ${level_count} levels of level table put it at ${expected_root_page_offset}`));
-
-        usable = false;
-    }
-
-    if (buffer.readUint8() !== 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'reserved byte at 103 is not zero'));
-    }
-
-    const source_vertex_count = Number(buffer.readUint64());
-
-    if (source_vertex_count < 3) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `source_vertex_count is ${source_vertex_count}, must be at least 3`));
-    }
-
-    const source_face_count = Number(buffer.readUint64());
-
-    if (source_face_count < 1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `source_face_count is ${source_face_count}, must be at least 1`));
-    }
-
-    const object_sphere = read_sphere(buffer);
-
-    if (!object_sphere.every(Number.isFinite) || object_sphere[3] < 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `object_sphere is not a finite non-negative sphere: ${object_sphere}`));
-    }
-
-    const object_bounds = read_aabb(buffer);
-
-    if (!object_bounds.every(Number.isFinite)) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `object_bounds is not finite: ${object_bounds}`));
-    }
-
-    for (let axis = 0; axis < 3; axis++) {
-        if (object_bounds[axis] > object_bounds[axis + 3]) {
-            out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `object_bounds axis ${axis} has min > max`));
-        }
-    }
-
-    for (let offset = 160; offset < VGEO_HEADER_OFFSET.HEADER_CHECKSUM; offset++) {
-        if (buffer.raw_bytes[offset] !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `reserved byte at ${offset} is not zero`));
-
-            break;
-        }
-    }
-
-    return usable;
-}
-
-/**
- * @param {BinaryBuffer} buffer whole file
- * @param {VGeoDefect[]} out
- */
-function check_hashes(buffer, out) {
-    buffer.position = VGEO_HEADER_OFFSET.HEADER_CHECKSUM;
-
-    const stored_header_checksum = buffer.readUint64();
-    const computed_header_checksum = vgeo_compute_header_checksum(buffer);
-
-    if (stored_header_checksum !== computed_header_checksum) {
-        out.push(new VGeoDefect(VGEO_DEFECT.CHECKSUM, `header_checksum is ${stored_header_checksum.toString(16)}, computed ${computed_header_checksum.toString(16)}`));
-    }
-
-    buffer.position = VGEO_HEADER_OFFSET.ASSET_ID;
-
-    const stored_low = buffer.readUint64();
-    const stored_high = buffer.readUint64();
-
-    const computed = vgeo_compute_asset_id(buffer);
-
-    if (stored_low !== computed.low64 || stored_high !== computed.high64) {
-        out.push(new VGeoDefect(VGEO_DEFECT.CHECKSUM, `asset_id is ${stored_high.toString(16)}${stored_low.toString(16)}, computed ${computed.toString()}`));
-    }
-}
-
-/**
- * @param {BinaryBuffer} buffer whole file
- * @param {VGeoFrameExtent[]} frames
- * @param {VGeoDefect[]} out
- */
-function check_frames(buffer, frames, out) {
-    buffer.position = VGEO_HEADER_OFFSET.TOTAL_PAGES;
-
-    const total_pages = buffer.readUint32();
-
-    buffer.position = VGEO_HEADER_OFFSET.DIRECTORY_OFFSET;
-
-    const directory_offset = Number(buffer.readUint64());
-
-    if (frames.length !== total_pages) {
-        out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `frame scan found ${frames.length} frames, header says total_pages = ${total_pages}`));
-    }
-
-    if (frames.length > 0) {
-        const last = frames[frames.length - 1];
-
-        const end = last.frame_offset + last.fetch_size;
-
-        if (end !== directory_offset) {
-            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `frame region ends at ${end}, directory_offset is ${directory_offset}; the two must coincide exactly`));
-        }
-    }
-
-    buffer.position = VGEO_HEADER_OFFSET.ASSET_ID;
-
-    const asset_id_low = buffer.readUint64();
-
-    for (const frame of frames) {
-        buffer.position = frame.frame_offset;
-
-        const magic = buffer.readUint32();
-
-        if (magic !== VGEO_PAGE_MAGIC) {
-            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: magic is 0x${magic.toString(16)}, expected 0x${VGEO_PAGE_MAGIC.toString(16)}`));
-        }
-
-        const decodable = frame.codec === VGEO_CODEC_RAW || frame.codec === VGEO_CODEC_LZ4;
-
-        if (!decodable) {
-            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: codec is ${frame.codec}, this validator knows ${VGEO_CODEC_RAW} (raw) and ${VGEO_CODEC_LZ4} (lz4)`));
-        }
-
-        if (frame.flags !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: frame flags are 0x${frame.flags.toString(16)}, no bit is defined`));
-        }
-
-        if (frame.codec === VGEO_CODEC_RAW && frame.decoded_size !== frame.stored_size) {
-            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: raw frame has stored_size ${frame.stored_size} and decoded_size ${frame.decoded_size}`));
-        }
-
-        // A `decoded_size` above what the stored bytes could physically produce is caught here
-        // rather than at decode, because a reader allocates against it *before* it decodes — see
-        // {@link vgeo_frame_decode_bound}.
-        if (decodable && frame.decoded_size > vgeo_frame_decode_bound(frame.codec, frame.stored_size)) {
-            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: decoded_size ${frame.decoded_size} is more than codec ${frame.codec} could produce from ${frame.stored_size} stored bytes`));
-        }
-
-        if (frame.frame_offset % VGEO_FRAME_ALIGNMENT !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: frame_offset ${frame.frame_offset} is not ${VGEO_FRAME_ALIGNMENT}-aligned`));
-        }
-
-        if (frame.frame_offset + frame.extent > directory_offset) {
-            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: frame runs past directory_offset`));
-
-            continue;
-        }
-
-        buffer.position = frame.frame_offset + VGEO_FRAME_OFFSET.CHECKSUM;
-
-        const stored_checksum = buffer.readUint64();
-        const computed_checksum = vgeo_compute_frame_checksum(buffer, frame, asset_id_low);
-
-        if (stored_checksum !== computed_checksum) {
-            out.push(new VGeoDefect(VGEO_DEFECT.CHECKSUM, `page ${frame.page_index}: frame checksum is ${stored_checksum.toString(16)}, computed ${computed_checksum.toString(16)}`));
-        }
-    }
-
-    if (frames.length > 0) {
-        buffer.position = VGEO_HEADER_OFFSET.ROOT_PAGE_FETCH_SIZE;
-
-        const root_fetch_size = buffer.readUint32();
-        const root_decoded_size = buffer.readUint32();
-
-        if (root_fetch_size !== frames[0].fetch_size) {
-            out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `root_page_fetch_size is ${root_fetch_size}, the root frame's is ${frames[0].fetch_size}`));
-        }
-
-        if (root_decoded_size !== frames[0].decoded_size) {
-            out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `root_page_decoded_size is ${root_decoded_size}, the root frame's is ${frames[0].decoded_size}`));
-        }
-    }
-}
-
-/**
- * Decode one page and check its internal layout.
- *
- * @param {BinaryBuffer} buffer whole file
- * @param {VGeoFrameExtent} frame
- * @param {number} level_count
- * @param {VGeoDefect[]} out
- * @returns {DecodedPage|undefined} `undefined` when the page is too malformed to read further
- */
-function decode_page(buffer, frame, level_count, out) {
-    const page = new DecodedPage();
-
-    page.page_index = frame.page_index;
-    page.frame = frame;
-    page.size = frame.decoded_size;
-
-    const blob = frame.frame_offset
-        + VGEO_FRAME_HEADER_SIZE
-        + VGEO_CHILD_TABLE_ENTRY_SIZE * frame.child_page_count;
-
-    // Everything below reads the blob, so it has to be in the file first. `check_frames` has
-    // already reported a frame that runs past the directory; what this stops is the reading.
-    if (blob + frame.stored_size > buffer.capacity) {
-        return undefined;
-    }
-
-    if (frame.codec === VGEO_CODEC_RAW) {
-        // Nothing to decode: the page *is* those bytes. `check_frames` has already reported it if
-        // the two sizes disagree, and with them disagreeing the page's own length is not knowable,
-        // so there is nothing left to audit.
-        if (frame.stored_size !== frame.decoded_size) {
-            return undefined;
-        }
-
-        page.buffer = buffer;
-        page.base = blob;
-    } else if (frame.codec === VGEO_CODEC_LZ4) {
-        // Bounded by `check_frames`, which has reported it, before it is believed — so a corrupt
-        // length field is a defect rather than an allocation.
-        if (frame.decoded_size > vgeo_frame_decode_bound(frame.codec, frame.stored_size)) {
-            return undefined;
-        }
-
-        page.buffer = new BinaryBuffer();
-        page.base = 0;
-
-        page.buffer.setCapacity(frame.decoded_size);
-
-        try {
-            vgeo_decode_frame_blob(page.buffer.raw_bytes, 0, buffer.raw_bytes, frame);
-        } catch (error) {
-            // Not suppression — the decoder's own message is what says *how* the blob is malformed,
-            // and a validator that threw here would be unable to report the one thing it exists to
-            // report.
-            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: ${error.message}`));
-
-            return undefined;
-        }
-    } else {
-        // `check_frames` has already named the codec; there is no decoder to go on with.
-        return undefined;
-    }
-
-    if (page.size < VGEO_PAGE_HEADER_SIZE) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: decoded page is ${page.size} bytes, shorter than its header`));
-
-        return undefined;
-    }
-
-    // Everything from here on is a read of the *decoded* page, which under a compressing codec is
-    // not the file — so it goes through the page's own buffer and never the one passed in.
-    const decoded = page.buffer;
-
-    page.seek(0);
-
-    page.group_count = decoded.readUint16();
-    page.cluster_count = decoded.readUint16();
-    page.min_level = decoded.readUint8();
-    page.max_level = decoded.readUint8();
-
-    page.node_count = decoded.readUint16();
-
-    page.cluster_table_offset = decoded.readUint32();
-    page.payload_offset = decoded.readUint32();
-    page.payload_size = decoded.readUint32();
-    page.node_table_offset = decoded.readUint32();
-
-    for (let offset = 24; offset < VGEO_PAGE_OFFSET.METRIC; offset++) {
-        if (decoded.raw_bytes[page.base + offset] !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: reserved byte at ${offset} in the page header is not zero`));
-
-            break;
-        }
-    }
-
-    page.seek(VGEO_PAGE_OFFSET.METRIC);
-
-    page.metric = read_metric(decoded);
-
-    if (page.group_count < 1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: group_count is 0`));
-
-        return undefined;
-    }
-
-    if (page.cluster_count < 1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: cluster_count is 0`));
-
-        return undefined;
-    }
-
-    if (page.min_level > page.max_level) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: min_level ${page.min_level} exceeds max_level ${page.max_level}`));
-    }
-
-    if (page.max_level >= level_count) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: max_level ${page.max_level} is outside level_count ${level_count}`));
-    }
-
-    // One node per group is the worst the tree can come to — a leaf holds up to the fanout, and
-    // every interior node has at least two children — so 2·groups bounds it whatever the shape.
-    if (page.node_count < 1 || page.node_count > 2 * page.group_count) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: node_count is ${page.node_count}, outside 1..${2 * page.group_count} for ${page.group_count} groups`));
-
-        return undefined;
-    }
-
-    const expected_node_table_offset = VGEO_PAGE_HEADER_SIZE + page.group_count * VGEO_GROUP_RECORD_SIZE;
-
-    if (page.node_table_offset !== expected_node_table_offset) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: node_table_offset is ${page.node_table_offset}, expected ${expected_node_table_offset}`));
-
-        return undefined;
-    }
-
-    const expected_cluster_table_offset = page.node_table_offset
-        + page.node_count * VGEO_NODE_RECORD_SIZE;
-
-    if (page.cluster_table_offset !== expected_cluster_table_offset) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: cluster_table_offset is ${page.cluster_table_offset}, expected ${expected_cluster_table_offset}`));
-
-        return undefined;
-    }
-
-    const expected_payload_offset = page.cluster_table_offset + page.cluster_count * VGEO_CLUSTER_RECORD_SIZE;
-
-    if (page.payload_offset !== expected_payload_offset) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: payload_offset is ${page.payload_offset}, expected ${expected_payload_offset}`));
-
-        return undefined;
-    }
-
-    if (page.payload_offset + page.payload_size !== page.size) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: payload ends at ${page.payload_offset + page.payload_size}, the decoded page is ${page.size} bytes`));
-
-        return undefined;
-    }
-
-    for (let i = 0; i < frame.child_page_count; i++) {
-        buffer.position = frame.frame_offset + VGEO_FRAME_HEADER_SIZE + i * VGEO_CHILD_TABLE_ENTRY_SIZE + 8;
-
-        page.child_pages.push(buffer.readUint32());
-    }
-
-    return page;
-}
-
-/**
- * A traversal metric, wherever it is carried.
- */
-class VGeoMetric {
-    /**
-     * @type {Float32Array}
-     */
-    sphere = new Float32Array(4);
-
-    /**
-     * @type {number}
-     */
-    min_self_error = 0;
-
-    /**
-     * @type {number}
-     */
-    max_parent_error = 0;
-}
-
-/**
- * @param {BinaryBuffer} buffer positioned at the metric
- * @returns {VGeoMetric}
- */
-function read_metric(buffer) {
-    const result = new VGeoMetric();
-
-    buffer.readFloat32Array(result.sphere, 0, 4);
-
-    result.min_self_error = buffer.readFloat32();
-    result.max_parent_error = buffer.readFloat32();
-
-    return result;
-}
-
-/**
- * Does `outer` contain `inner`? Both are `[centre xyz, radius]`.
- *
- * Slack is a relative epsilon on the radius: the spheres a node aggregates were combined in float32
- * pairwise, and an exact containment test would flag the last bit of that arithmetic as a defect.
- *
- * @param {Float32Array} outer
- * @param {Float32Array} inner
- * @returns {boolean}
- */
-function sphere_contains(outer, inner) {
-    const dx = inner[0] - outer[0];
-    const dy = inner[1] - outer[1];
-    const dz = inner[2] - outer[2];
-
-    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
-
-    return distance + inner[3] <= outer[3] * (1 + 1e-4) + 1e-4;
-}
-
-/**
- * A page's group tree: that it is a tree over exactly this page's groups, and that a node's metric
- * really does bound everything under it.
- *
- * The second half is what makes the structure worth anything. A traversal skips a subtree when the
- * node's `max_parent_error` projects to no more than the threshold, and culls one when its sphere
- * misses the frustum; both are only sound if the node's numbers dominate every group beneath it. A
- * node whose sphere is too small silently drops geometry, and nothing downstream would notice.
- *
- * @param {DecodedPage[]} pages
- * @param {object[][]} page_groups
- * @param {object[][]} page_clusters
- * @param {VGeoDefect[]} out
- */
-function check_page_nodes(pages, page_groups, page_clusters, out) {
-    for (const page of pages) {
-        const groups = page_groups[page.page_index];
-        const clusters = page_clusters[page.page_index];
-
-        const buffer = page.buffer;
-
-        const nodes = [];
-
-        for (let index = 0; index < page.node_count; index++) {
-            const base = page.base + page.node_table_offset + index * VGEO_NODE_RECORD_SIZE;
-
-            buffer.position = base + VGEO_NODE_OFFSET.METRIC;
-
-            const node = { metric: read_metric(buffer) };
-
-            buffer.position = base + VGEO_NODE_OFFSET.CHILD_FIRST;
-
-            node.child_first = buffer.readUint16();
-            node.child_count = buffer.readUint16();
-
-            const flags = buffer.readUint16();
-
-            node.is_leaf = (flags & VGEO_NODE_FLAG_LEAF) !== 0;
-
-            if ((flags & ~VGEO_NODE_FLAG_LEAF) !== 0) {
-                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: unknown flag bits ${flags}`));
-            }
-
-            nodes.push(node);
-        }
-
-        /**
-         * How many times each group is reached through a leaf. Exactly once, or the tree is not a
-         * partition of the page and a traversal either misses geometry or draws it twice.
-         * @type {Int32Array}
-         */
-        const group_hits = new Int32Array(groups.length);
-
-        let structural = true;
-
-        nodes.forEach((node, index) => {
-            if (node.child_count < 1 || node.child_count > VGEO_NODE_FANOUT) {
-                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: child_count ${node.child_count} is outside 1..${VGEO_NODE_FANOUT}`));
-
-                structural = false;
-
-                return;
-            }
-
-            const limit = node.is_leaf ? groups.length : nodes.length;
-
-            if (node.child_first + node.child_count > limit) {
-                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: children ${node.child_first}..${node.child_first + node.child_count} run past the ${node.is_leaf ? 'group' : 'node'} table's ${limit}`));
-
-                structural = false;
-
-                return;
-            }
-
-            if (node.is_leaf) {
-                for (let i = 0; i < node.child_count; i++) {
-                    group_hits[node.child_first + i]++;
-                }
-
-                return;
-            }
-
-            if (node.child_first <= index) {
-                // Breadth-first layout: a parent is always allocated before its children. Without
-                // it a reader has no bound on the walk and a malformed file can loop it forever.
-                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: child run starts at ${node.child_first}, which is not after the parent`));
-
-                structural = false;
-            }
-        });
-
-        if (!structural) {
-            continue;
-        }
-
-        const unreached = group_hits.reduce((count, hits) => count + (hits === 0 ? 1 : 0), 0);
-        const repeated = group_hits.reduce((count, hits) => count + (hits > 1 ? 1 : 0), 0);
-
-        if (unreached !== 0 || repeated !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index}: the node tree reaches ${unreached} of its ${groups.length} groups not at all and ${repeated} more than once`));
-
-            continue;
-        }
-
-        /**
-         * @param {number} index
-         * @param {VGeoMetric} covered
-         * @param {string} what
-         */
-        function expect_bounds(index, covered, what) {
-            const metric = nodes[index].metric;
-
-            if (!sphere_contains(metric.sphere, covered.sphere)) {
-                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: its sphere does not contain ${what}`));
-            }
-
-            if (metric.min_self_error > covered.min_self_error) {
-                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: min_self_error ${metric.min_self_error} is above ${what}'s ${covered.min_self_error}`));
-            }
-
-            if (metric.max_parent_error < covered.max_parent_error) {
-                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: max_parent_error ${metric.max_parent_error} is below ${what}'s ${covered.max_parent_error}`));
-            }
-        }
-
-        nodes.forEach((node, index) => {
-            for (let i = 0; i < node.child_count; i++) {
-                if (!node.is_leaf) {
-                    expect_bounds(index, nodes[node.child_first + i].metric, `node ${node.child_first + i}`);
-
-                    continue;
-                }
-
-                const group = groups[node.child_first + i];
-
-                const covered = new VGeoMetric();
-
-                covered.min_self_error = Number.POSITIVE_INFINITY;
-                covered.max_parent_error = 0;
-
-                let first = true;
-
-                for (let c = 0; c < group.cluster_count; c++) {
-                    const cluster = clusters[group.cluster_first + c];
-
-                    if (cluster === undefined) {
-                        continue;
-                    }
-
-                    covered.min_self_error = Math.min(covered.min_self_error, cluster.self_error);
-                    covered.max_parent_error = Math.max(covered.max_parent_error, cluster.parent_error);
-
-                    if (first) {
-                        covered.sphere.set(cluster.parent_sphere);
-
-                        first = false;
-                    }
-                }
-
-                if (first) {
-                    continue;
-                }
-
-                expect_bounds(index, covered, `group ${node.child_first + i}`);
-            }
-        });
-
-        const root = nodes[0];
-
-        if (
-            root !== undefined
-            && (
-                !sphere_contains(page.metric.sphere, root.metric.sphere)
-                || page.metric.min_self_error !== root.metric.min_self_error
-                || page.metric.max_parent_error !== root.metric.max_parent_error
-            )
-        ) {
-            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index}: the page header's metric disagrees with its root node's`));
-        }
-    }
-}
-
-/**
- * @param {BinaryBuffer} buffer whole file
- * @param {VGeoFrameExtent[]} frames
- * @param {DecodedPage[]} pages
- * @param {VGeoDefect[]} out
- */
-function check_child_tables(buffer, frames, pages, out) {
-    for (const page of pages) {
-        const frame = page.frame;
-
-        const seen = new Set();
-
-        for (let i = 0; i < frame.child_page_count; i++) {
-            buffer.position = frame.frame_offset + VGEO_FRAME_HEADER_SIZE + i * VGEO_CHILD_TABLE_ENTRY_SIZE;
-
-            const child_frame_offset = Number(buffer.readUint64());
-            const child_page_index = buffer.readUint32();
-            const child_fetch_size = buffer.readUint32();
-            const child_decoded_size = buffer.readUint32();
-            const reserved = buffer.readUint32();
-
-            const metric = read_metric(buffer);
-
-            const child_page = pages.find((candidate) => candidate.page_index === child_page_index);
-
-            if (child_page !== undefined && child_page.metric !== null) {
-                // Copied, so it can be read before the child is fetched — which is the whole point
-                // — and therefore able to drift from the truth. Nothing else would catch it: a
-                // traversal that trusts a stale metric skips a page it needed and leaves a hole.
-                if (
-                    metric.sphere.some((value, axis) => value !== child_page.metric.sphere[axis])
-                    || metric.min_self_error !== child_page.metric.min_self_error
-                    || metric.max_parent_error !== child_page.metric.max_parent_error
-                ) {
-                    out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: its metric for page ${child_page_index} disagrees with that page's own`));
-                }
-            }
-
-            if (reserved !== 0) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: reserved is not zero`));
-            }
-
-            if (seen.has(child_page_index)) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index}: child page ${child_page_index} appears more than once; the table must be deduplicated`));
-            }
-
-            seen.add(child_page_index);
-
-            if (child_page_index >= frames.length) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: page_index ${child_page_index} does not exist`));
-
-                continue;
-            }
-
-            if (child_page_index === page.page_index) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: a page may not name itself; same-page children use the SAME_PAGE sentinel`));
-            }
-
-            const child = frames[child_page_index];
-
-            if (child_frame_offset !== child.frame_offset) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: frame_offset ${child_frame_offset}, the frame is at ${child.frame_offset}`));
-            }
-
-            if (child_frame_offset <= frame.frame_offset) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: child frame_offset ${child_frame_offset} is not strictly ahead of ${frame.frame_offset}; file order must be topological`));
-            }
-
-            if (child_fetch_size !== child.fetch_size) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: fetch_size ${child_fetch_size}, the frame's is ${child.fetch_size}`));
-            }
-
-            if (child_decoded_size !== child.decoded_size) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: decoded_size ${child_decoded_size}, the frame's is ${child.decoded_size}`));
-            }
-        }
-    }
-}
-
-/**
- * @param {DecodedPage} page
- * @param {VGeoDefect[]} out
- * @returns {{cluster_first:number, cluster_count:number, parent_cluster_count:number}[]}
- */
-function read_groups(page, out) {
-    const result = [];
-
-    const buffer = page.buffer;
-
-    let expected_first = 0;
-
-    for (let g = 0; g < page.group_count; g++) {
-        page.seek(VGEO_PAGE_HEADER_SIZE + g * VGEO_GROUP_RECORD_SIZE);
-
-        const group = {
-            cluster_first: buffer.readUint16(),
-            cluster_count: buffer.readUint16(),
-            parent_cluster_count: buffer.readUint16(),
-        };
-
-        if (buffer.readUint16() !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: reserved is not zero`));
-        }
-
-        if (group.cluster_count < 1 || group.cluster_count > VGEO_MAX_GROUP_CLUSTER_COUNT) {
-            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: cluster_count ${group.cluster_count} is outside [1, ${VGEO_MAX_GROUP_CLUSTER_COUNT}]`));
-        }
-
-        if (group.cluster_first !== expected_first) {
-            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: cluster_first ${group.cluster_first}, expected ${expected_first}; a page's groups must tile its cluster records in order`));
-        }
-
-        expected_first = group.cluster_first + group.cluster_count;
-
-        result.push(group);
-    }
-
-    if (expected_first !== page.cluster_count) {
-        out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index}: groups cover ${expected_first} clusters, the page holds ${page.cluster_count}`));
-    }
-
-    return result;
-}
-
-/**
- * Decode a cluster's local positions from its payload — the only way to check that the culling
- * bounds actually bound anything.
- *
- * @param {DecodedPage} page
- * @param {object} cluster
- * @returns {Float32Array} `vertex_count * 3` coordinates
- */
-function read_cluster_positions(page, cluster) {
-    page.seek(
-        page.payload_offset
-        + cluster.payload_offset
-        + vgeo_payload_attribute_offset(0, cluster.vertex_count, cluster.triangle_count, cluster.encoding_flags)
-    );
-
-    const result = new Float32Array(cluster.vertex_count * 3);
-
-    page.buffer.readFloat32Array(result, 0, result.length);
-
-    return result;
-}
-
-/**
- * @param {DecodedPage} page
- * @param {VGeoDefect[]} out
- * @returns {object[]}
- */
-function read_clusters(page, out) {
-    const result = [];
-
-    const buffer = page.buffer;
-
-    for (let c = 0; c < page.cluster_count; c++) {
-        page.seek(page.cluster_table_offset + c * VGEO_CLUSTER_RECORD_SIZE);
-
-        const cluster = {
-            index: c,
-            self_sphere: read_sphere(buffer),
-            self_error: buffer.readFloat32(),
-            parent_error: buffer.readFloat32(),
-            parent_sphere: read_sphere(buffer),
-            bounds_sphere: read_sphere(buffer),
-            aabb: read_aabb(buffer),
-            child_ref: buffer.readUint16(),
-            child_group: buffer.readUint16(),
-            cone_reserved: buffer.readUint32(),
-            encoding_flags: buffer.readUint32(),
-            payload_offset: buffer.readUint32(),
-            payload_size: buffer.readUint32(),
-            vertex_count: buffer.readUint8(),
-            triangle_count: buffer.readUint8(),
-        };
-
-        if (buffer.readUint16() !== 0 || buffer.readUint64() !== 0n) {
-            out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `page ${page.page_index} cluster ${c}: reserved tail is not zero`));
-        }
-
-        if (cluster.cone_reserved !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `page ${page.page_index} cluster ${c}: cone_reserved is not zero`));
-        }
-
-        result.push(cluster);
-    }
-
-    return result;
-}
-
-/**
- * Everything about one cluster that its own record settles: counts, flags, payload extent, bounds
- * that actually bound, and finite metric values.
- *
- * @param {DecodedPage} page
- * @param {object} cluster
- * @param {number[]} object_sphere
- * @param {number[]} object_bounds
- * @param {VGeoDefect[]} out
- */
-function check_cluster_record(page, cluster, object_sphere, object_bounds, out) {
-    const where = `page ${page.page_index} cluster ${cluster.index}`;
-
-    if (cluster.vertex_count < 3 || cluster.vertex_count > VGEO_MAX_CLUSTER_VERTEX_COUNT) {
-        out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: vertex_count ${cluster.vertex_count} is outside [3, ${VGEO_MAX_CLUSTER_VERTEX_COUNT}]`));
-
-        return;
-    }
-
-    if (cluster.triangle_count < 1 || cluster.triangle_count > VGEO_MAX_CLUSTER_TRIANGLE_COUNT) {
-        out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: triangle_count ${cluster.triangle_count} is outside [1, ${VGEO_MAX_CLUSTER_TRIANGLE_COUNT}]`));
-
-        return;
-    }
-
-    if ((cluster.encoding_flags & ~VGEO_ENCODING_FLAGS_MASK) !== 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: encoding_flags 0x${cluster.encoding_flags.toString(16)} sets a bit that must be clear (skinning bits and reserved bits)`));
-    }
-
-    if (cluster.payload_offset % 4 !== 0 || cluster.payload_size % 4 !== 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: payload offset ${cluster.payload_offset} / size ${cluster.payload_size} is not a multiple of 4`));
-
-        return;
-    }
-
-    const expected_size = vgeo_payload_size(cluster.vertex_count, cluster.triangle_count, cluster.encoding_flags);
-
-    if (cluster.payload_size !== expected_size) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: payload_size ${cluster.payload_size}, the encoding needs ${expected_size}`));
-
-        return;
-    }
-
-    if (cluster.payload_offset + cluster.payload_size > page.payload_size) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: payload runs past the page's payload section`));
-
-        return;
-    }
-
-    const index_base = page.base + page.payload_offset + cluster.payload_offset;
-
-    for (let i = 0; i < cluster.triangle_count * 3; i++) {
-        const index = page.buffer.raw_bytes[index_base + i];
-
-        if (index >= cluster.vertex_count) {
-            out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: local index ${index} at ${i} is outside the cluster's ${cluster.vertex_count} vertices`));
-
-            break;
-        }
-    }
-
-    const named_spheres = [
-        ['self_sphere', cluster.self_sphere],
-        ['parent_sphere', cluster.parent_sphere],
-        ['bounds_sphere', cluster.bounds_sphere],
-    ];
-
-    for (const [name, sphere] of named_spheres) {
-        if (!sphere.every(Number.isFinite) || sphere[3] < 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: ${name} is not a finite non-negative sphere: ${sphere}`));
-        }
-    }
-
-    if (!cluster.aabb.every(Number.isFinite)) {
-        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: aabb is not finite`));
-    }
-
-    if (!Number.isFinite(cluster.self_error) || cluster.self_error < 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: self_error ${cluster.self_error} must be finite and non-negative`));
-    }
-
-    if (Number.isNaN(cluster.parent_error) || cluster.parent_error < 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: parent_error ${cluster.parent_error} must be non-negative and not NaN`));
-    }
-
-    if (cluster.parent_error < cluster.self_error) {
-        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: parent_error ${cluster.parent_error} is below self_error ${cluster.self_error}`));
-    }
-
-    if (!sphere_contains_sphere(cluster.parent_sphere, cluster.self_sphere)) {
-        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: parent_sphere does not contain self_sphere`));
-    }
-
-    const positions = read_cluster_positions(page, cluster);
-
-    for (let v = 0; v < cluster.vertex_count; v++) {
-        const x = positions[v * 3];
-        const y = positions[v * 3 + 1];
-        const z = positions[v * 3 + 2];
-
-        if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
-            out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: vertex ${v} is not finite`));
-
-            break;
-        }
-
-        if (!sphere_contains_point(cluster.bounds_sphere, x, y, z)) {
-            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: bounds_sphere does not contain vertex ${v}`));
-
-            break;
-        }
-
-        if (x < cluster.aabb[0] || y < cluster.aabb[1] || z < cluster.aabb[2]
-            || x > cluster.aabb[3] || y > cluster.aabb[4] || z > cluster.aabb[5]) {
-            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: aabb does not contain vertex ${v}`));
-
-            break;
-        }
-
-        if (!sphere_contains_point(object_sphere, x, y, z)) {
-            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: the header's object_sphere does not contain vertex ${v}`));
-
-            break;
-        }
-
-        if (x < object_bounds[0] || y < object_bounds[1] || z < object_bounds[2]
-            || x > object_bounds[3] || y > object_bounds[4] || z > object_bounds[5]) {
-            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: the header's object_bounds does not contain vertex ${v}`));
-
-            break;
-        }
-    }
-}
-
-/**
- * The whole cross-page audit: child references resolve and point at a strictly coarser band than the
- * cluster making them, the DAG has exactly one root, every group's `parent_cluster_count` is exact,
- * the metric pair a step writes is the same on both sides of that step, and every page is reachable
- * from the root.
- *
- * @param {DecodedPage[]} pages
- * @param {object[][]} page_groups
- * @param {object[][]} page_clusters
- * @param {number} level_count
- * @param {VGeoDefect[]} out
- */
-function check_dag(pages, page_groups, page_clusters, level_count, out) {
-    /**
-     * How many clusters name each `page:group`, so that `parent_cluster_count` can be counted rather
-     * than trusted.
-     * @type {Map<string, number>}
-     */
-    const reference_counts = new Map();
-
-    for (const page of pages) {
-        for (const cluster of page_clusters[page.page_index]) {
-            const where = `page ${page.page_index} cluster ${cluster.index}`;
-
-            if (cluster.child_ref === VGEO_NO_CHILD) {
-                if (cluster.child_group !== VGEO_NO_GROUP) {
-                    out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: child_ref is NO_CHILD but child_group is ${cluster.child_group}`));
-                }
-
-                if (cluster.self_error !== 0) {
-                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: a leaf must carry self_error 0, has ${cluster.self_error}`));
-                }
-
-                continue;
-            }
-
-            if (cluster.child_group === VGEO_NO_GROUP) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: child_group is NO_GROUP but child_ref is ${cluster.child_ref}`));
-
-                continue;
-            }
-
-            let child_page_index;
-
-            if (cluster.child_ref === VGEO_SAME_PAGE) {
-                if (page.min_level === page.max_level) {
-                    out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: SAME_PAGE is legal only in a page whose band spans more than one level`));
-
-                    continue;
-                }
-
-                child_page_index = page.page_index;
-            } else {
-                if (cluster.child_ref > VGEO_MAX_CHILD_REF || cluster.child_ref >= page.child_pages.length) {
-                    out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: child_ref ${cluster.child_ref} is outside the page's ${page.child_pages.length} child-table entries`));
-
-                    continue;
-                }
-
-                child_page_index = page.child_pages[cluster.child_ref];
-            }
-
-            if (pages[child_page_index] === undefined) {
-                continue;
-            }
-
-            if (
-                cluster.child_ref !== VGEO_SAME_PAGE
-                && pages[child_page_index].max_level >= page.max_level
-            ) {
-                // The band is what puts pages in file order, and a child sitting at or above its
-                // parent's band is a reference that points backwards — the one thing that makes the
-                // file untraversable in a single forward pass.
-                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `${where}: its child group is in page ${child_page_index}, whose band tops out at ${pages[child_page_index].max_level} — not below this page's ${page.max_level}`));
-            }
-
-            const child_groups = page_groups[child_page_index];
-
-            if (cluster.child_group >= child_groups.length) {
-                out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: child_group ${cluster.child_group} does not exist in page ${child_page_index}`));
-
-                continue;
-            }
-
-            const key = `${child_page_index}:${cluster.child_group}`;
-
-            reference_counts.set(key, (reference_counts.get(key) ?? 0) + 1);
-
-            const group = child_groups[cluster.child_group];
-
-            for (let i = 0; i < group.cluster_count; i++) {
-                const child = page_clusters[child_page_index][group.cluster_first + i];
-
-                if (child === undefined) {
-                    break;
-                }
-
-                if (child.parent_error !== cluster.self_error) {
-                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: self_error ${cluster.self_error} disagrees with the consumed cluster's parent_error ${child.parent_error}; one group step writes one value on both sides`));
-
-                    break;
-                }
-
-                if (child.parent_sphere.some((value, axis) => value !== cluster.self_sphere[axis])) {
-                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: self_sphere disagrees with the consumed cluster's parent_sphere`));
-
-                    break;
-                }
-            }
-        }
-    }
-
-    // Exactly one root. The runtime's cut starts at the root and walks down; a second parentless
-    // cluster is a second entry point it would never visit, and its whole subtree with it. It is
-    // also the shape a build that stopped converging leaves behind, which is the likelier cause.
-    const roots = [];
-
-    for (const page of pages) {
-        for (const cluster of page_clusters[page.page_index]) {
-            if (cluster.parent_error === Number.POSITIVE_INFINITY) {
-                roots.push({ page: page.page_index, cluster: cluster.index });
-            }
-        }
-    }
-
-    const where_roots = roots.slice(0, 4).map((root) => `page ${root.page} cluster ${root.cluster}`);
-
-    if (roots.length !== 1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `the DAG has ${roots.length} root clusters, expected exactly one${roots.length === 0 ? '' : `: ${where_roots.join(', ')}`}`));
-    } else if (roots[0].page !== 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `the root cluster is in ${where_roots[0]}, not the always-resident root page`));
-    }
-
-    for (const page of pages) {
-        page_groups[page.page_index].forEach((group, group_index) => {
-            const counted = reference_counts.get(`${page.page_index}:${group_index}`) ?? 0;
-
-            if (group.parent_cluster_count !== counted) {
-                out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${group_index}: parent_cluster_count is ${group.parent_cluster_count}, ${counted} clusters name it`));
-            }
-
-            const is_root_group = page.page_index === 0 && page.max_level === level_count - 1;
-
-            if (counted === 0 && !is_root_group) {
-                out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${group_index}: no cluster names it, yet it is not one of the root page's topmost-level groups`));
-            }
-
-            for (let i = 0; i < group.cluster_count; i++) {
-                const cluster = page_clusters[page.page_index][group.cluster_first + i];
-
-                if (cluster === undefined) {
-                    break;
-                }
-
-                const is_root = cluster.parent_error === Number.POSITIVE_INFINITY;
-
-                if (is_root !== (counted === 0)) {
-                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `page ${page.page_index} cluster ${cluster.index}: parent_error is ${cluster.parent_error} while its group has ${counted} parents; +Infinity holds exactly for a group nothing consumes`));
-
-                    break;
-                }
-
-                if (is_root && cluster.parent_sphere.some((value, axis) => value !== cluster.self_sphere[axis])) {
-                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `page ${page.page_index} cluster ${cluster.index}: a root's parent_sphere must duplicate its self_sphere`));
-
-                    break;
-                }
-            }
-        });
-    }
-
-    const reached = new Set([0]);
-    const queue = [0];
-
-    while (queue.length > 0) {
-        const page_index = queue.pop();
-
-        for (const child of pages[page_index].child_pages) {
-            if (pages[child] !== undefined && !reached.has(child)) {
-                reached.add(child);
-                queue.push(child);
-            }
-        }
-    }
-
-    for (const page of pages) {
-        if (!reached.has(page.page_index)) {
-            out.push(new VGeoDefect(VGEO_DEFECT.REACHABILITY, `page ${page.page_index} is not reachable from the root page`));
-        }
-    }
-}
-
-/**
- * @param {DecodedPage[]} pages
- * @param {number} level_count
- * @param {VGeoDefect[]} out
- */
-function check_page_order(pages, level_count, out) {
-    const root = pages[0];
-
-    if (root === undefined) {
-        return;
-    }
-
-    if (root.max_level !== level_count - 1) {
-        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_ORDER, `the root page's max_level is ${root.max_level}, the topmost level is ${level_count - 1}`));
-    }
-
-    for (let i = 1; i < pages.length; i++) {
-        if (pages[i].max_level > pages[i - 1].max_level) {
-            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_ORDER, `page ${i} has max_level ${pages[i].max_level} after page ${i - 1}'s ${pages[i - 1].max_level}; file order must run coarse first`));
-        }
-
-        if (pages[i].max_level === level_count - 1) {
-            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_ORDER, `page ${i} also carries the topmost level; the root page must hold it complete`));
-        }
-    }
-}
-
-/**
- * The directory is derived data: rebuild it from a frame scan and require the file's copy to match
- * byte for byte, then verify its block checksums.
- *
- * @param {BinaryBuffer} buffer whole file
- * @param {VGeoFrameExtent[]} frames
- * @param {DecodedPage[]} pages
- * @param {VGeoDefect[]} out
- */
-function check_directory(buffer, frames, pages, out) {
-    buffer.position = VGEO_HEADER_OFFSET.TOTAL_PAGES;
-
-    const total_pages = buffer.readUint32();
-
-    buffer.position = VGEO_HEADER_OFFSET.DIRECTORY_OFFSET;
-
-    const directory_offset = Number(buffer.readUint64());
-    const dir_block_checksums_offset = Number(buffer.readUint64());
-
-    const reconstructed = new BinaryBuffer();
-
-    reconstructed.setCapacity(total_pages * VGEO_DIRECTORY_RECORD_SIZE);
-
-    for (let i = 0; i < Math.min(total_pages, frames.length); i++) {
-        const frame = frames[i];
-        const page = pages[i];
-
-        reconstructed.position = i * VGEO_DIRECTORY_RECORD_SIZE;
-
-        reconstructed.writeUint64(BigInt(frame.frame_offset));
-        reconstructed.writeUint32(frame.fetch_size);
-        reconstructed.writeUint32(frame.decoded_size);
-
-        if (page === undefined) {
-            continue;
-        }
-
-        reconstructed.writeUint8(page.min_level);
-        reconstructed.writeUint8(page.max_level);
-        reconstructed.writeUint16(i === 0 ? VGEO_DIRECTORY_FLAG_ROOT_PAGE : 0);
-        reconstructed.writeUint16(page.group_count);
-        reconstructed.writeUint16(page.cluster_count);
-    }
-
-    const stored = buffer.raw_bytes;
-    const expected = reconstructed.raw_bytes;
-
-    for (let i = 0; i < expected.length; i++) {
-        if (stored[directory_offset + i] !== expected[i]) {
-            const record = (i / VGEO_DIRECTORY_RECORD_SIZE) | 0;
-
-            out.push(new VGeoDefect(VGEO_DEFECT.DIRECTORY, `directory record ${record} disagrees with a frame scan at byte ${i % VGEO_DIRECTORY_RECORD_SIZE}: the file has ${stored[directory_offset + i]}, the frames say ${expected[i]}`));
-
-            break;
-        }
-    }
-
-    buffer.position = VGEO_HEADER_OFFSET.ASSET_ID + 8;
-
-    const asset_id_high = buffer.readUint64();
-
-    const block_count = vgeo_directory_block_count(total_pages);
-
-    for (let block = 0; block < block_count; block++) {
-        buffer.position = dir_block_checksums_offset + block * 8;
-
-        const stored_checksum = buffer.readUint64();
-
-        const computed = vgeo_compute_directory_block_checksum(
-            buffer, directory_offset, total_pages, block, asset_id_high
-        );
-
-        if (stored_checksum !== computed) {
-            out.push(new VGeoDefect(VGEO_DEFECT.CHECKSUM, `directory block ${block}: checksum is ${stored_checksum.toString(16)}, computed ${computed.toString(16)}`));
-        }
-    }
-}
-
-/**
- * Audit a `.vgeo` file.
- *
- * @param {BinaryBuffer} buffer the whole file, with `capacity` equal to its length
- * @returns {VGeoDefect[]} in discovery order; empty when the file satisfies every invariant
- */
-export function vgeo_validate_container(buffer) {
-    const out = [];
-
-    if (!check_header(buffer, out)) {
-        return out;
-    }
-
-    buffer.position = VGEO_HEADER_OFFSET.LEVEL_COUNT;
-
-    const level_count = buffer.readUint8();
-
-    buffer.position = VGEO_HEADER_OFFSET.TOTAL_CLUSTERS;
-
-    const total_clusters = Number(buffer.readUint64());
-    const total_groups = Number(buffer.readUint64());
-
-    buffer.position = VGEO_HEADER_OFFSET.OBJECT_SPHERE;
-
-    const object_sphere = read_sphere(buffer);
-    const object_bounds = read_aabb(buffer);
-
-    check_hashes(buffer, out);
-
-    const frames = vgeo_scan_frames(buffer);
-
-    check_frames(buffer, frames, out);
-
-    /**
-     * @type {DecodedPage[]}
-     */
-    const pages = [];
-
-    for (const frame of frames) {
-        const page = decode_page(buffer, frame, level_count, out);
-
-        if (page === undefined) {
-            return out;
-        }
-
-        pages.push(page);
-    }
-
-    check_child_tables(buffer, frames, pages, out);
-    check_page_order(pages, level_count, out);
-
-    const page_groups = [];
-    const page_clusters = [];
-
-    let counted_clusters = 0;
-    let counted_groups = 0;
-
-    for (const page of pages) {
-        const groups = read_groups(page, out);
-        const clusters = read_clusters(page, out);
-
-        page_groups.push(groups);
-        page_clusters.push(clusters);
-
-        counted_groups += groups.length;
-        counted_clusters += clusters.length;
-
-        for (const cluster of clusters) {
-            check_cluster_record(page, cluster, object_sphere, object_bounds, out);
-        }
-    }
-
-    if (counted_clusters !== total_clusters) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `total_clusters is ${total_clusters}, the pages hold ${counted_clusters}`));
-    }
-
-    if (counted_groups !== total_groups) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `total_groups is ${total_groups}, the pages hold ${counted_groups}`));
-    }
-
-    check_page_nodes(pages, page_groups, page_clusters, out);
-
-    check_dag(pages, page_groups, page_clusters, level_count, out);
-    check_directory(buffer, frames, pages, out);
-
-    return out;
-}
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { round_up } from "../../../../../core/math/round_up.js";
+import { VGEO_CHILD_TABLE_ENTRY_SIZE } from "./frame/VGEO_CHILD_TABLE_ENTRY_SIZE.js";
+import { VGEO_CLUSTER_RECORD_SIZE } from "./cluster/VGEO_CLUSTER_RECORD_SIZE.js";
+import { VGEO_CODEC_LZ4 } from "./frame/VGEO_CODEC_LZ4.js";
+import { VGEO_CODEC_RAW } from "./frame/VGEO_CODEC_RAW.js";
+import { vgeo_compute_asset_id } from "./checksum/vgeo_compute_asset_id.js";
+import { vgeo_compute_directory_block_checksum } from "./checksum/vgeo_compute_directory_block_checksum.js";
+import { vgeo_compute_frame_checksum } from "./checksum/vgeo_compute_frame_checksum.js";
+import { vgeo_compute_header_checksum } from "./checksum/vgeo_compute_header_checksum.js";
+import { VGEO_DEFECT } from "./VGEO_DEFECT.js";
+import { vgeo_directory_block_count } from "./directory/vgeo_directory_block_count.js";
+import { VGEO_DIRECTORY_FLAG_ROOT_PAGE } from "./directory/VGEO_DIRECTORY_FLAG_ROOT_PAGE.js";
+import { VGEO_DIRECTORY_RECORD_SIZE } from "./directory/VGEO_DIRECTORY_RECORD_SIZE.js";
+import { vgeo_decode_frame_blob } from "./frame/vgeo_decode_frame_blob.js";
+import { VGEO_ENCODING_FLAGS_MASK } from "./payload/VGEO_ENCODING_FLAGS_MASK.js";
+import { VGEO_FORMAT_VERSION } from "./header/VGEO_FORMAT_VERSION.js";
+import { VGEO_FRAME_ALIGNMENT } from "./frame/VGEO_FRAME_ALIGNMENT.js";
+import { vgeo_frame_decode_bound } from "./frame/vgeo_frame_decode_bound.js";
+import { VGEO_FRAME_HEADER_SIZE } from "./frame/VGEO_FRAME_HEADER_SIZE.js";
+import { VGEO_FRAME_OFFSET } from "./frame/VGEO_FRAME_OFFSET.js";
+import { VGEO_GROUP_RECORD_SIZE } from "./page/VGEO_GROUP_RECORD_SIZE.js";
+import { VGEO_HASH_ALGO_XXH3 } from "./header/VGEO_HASH_ALGO_XXH3.js";
+import { VGEO_HEADER_OFFSET } from "./header/VGEO_HEADER_OFFSET.js";
+import { VGEO_HEADER_SIZE } from "./header/VGEO_HEADER_SIZE.js";
+import { VGEO_LEVEL_RECORD_SIZE } from "./header/VGEO_LEVEL_RECORD_SIZE.js";
+import { VGEO_MAGIC } from "./header/VGEO_MAGIC.js";
+import { VGEO_MAX_CHILD_REF } from "./cluster/VGEO_MAX_CHILD_REF.js";
+import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "./cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
+import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "./cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
+import { VGEO_MAX_GROUP_CLUSTER_COUNT } from "./page/VGEO_MAX_GROUP_CLUSTER_COUNT.js";
+import { VGEO_MIN_READER_VERSION } from "./header/VGEO_MIN_READER_VERSION.js";
+import { VGEO_NO_CHILD } from "./cluster/VGEO_NO_CHILD.js";
+import { VGEO_NO_GROUP } from "./cluster/VGEO_NO_GROUP.js";
+import { VGEO_NODE_FANOUT } from "./page/VGEO_NODE_FANOUT.js";
+import { VGEO_NODE_FLAG_LEAF } from "./page/VGEO_NODE_FLAG_LEAF.js";
+import { VGEO_NODE_OFFSET } from "./page/VGEO_NODE_OFFSET.js";
+import { VGEO_NODE_RECORD_SIZE } from "./page/VGEO_NODE_RECORD_SIZE.js";
+import { VGEO_PAGE_HEADER_SIZE } from "./page/VGEO_PAGE_HEADER_SIZE.js";
+import { VGEO_PAGE_MAGIC } from "./frame/VGEO_PAGE_MAGIC.js";
+import { VGEO_PAGE_OFFSET } from "./page/VGEO_PAGE_OFFSET.js";
+import { vgeo_payload_attribute_offset } from "./payload/vgeo_payload_attribute_offset.js";
+import { VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1 } from "./header/VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1.js";
+import { vgeo_payload_size } from "./payload/vgeo_payload_size.js";
+import { VGEO_SAME_PAGE } from "./cluster/VGEO_SAME_PAGE.js";
+import { vgeo_scan_frames } from "./frame/vgeo_scan_frames.js";
+import { VGeoDefect } from "./VGeoDefect.js";
+
+/**
+ * A full audit of a `.vgeo` file against VGEO_FORMAT §11 — every build invariant, every checksum,
+ * and the directory checked against what a frame scan reconstructs.
+ *
+ * It reads nothing but the bytes it is given: no builder state, no side channel. That is the point —
+ * a file that passes here is one a reader can trust, whoever produced it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * A page's decoded form. Under codec 0 the decoded page is the frame's own bytes, so this holds the
+ * absolute offset of its first byte rather than a copy; a compressing codec decodes into its own
+ * buffer and `base` is 0 there. Everything downstream reads through {@link buffer} and {@link seek},
+ * so which of the two it was never reaches a check.
+ */
+class DecodedPage {
+    /**
+     * @type {number}
+     */
+    page_index = 0;
+
+    /**
+     * @type {VGeoFrameExtent}
+     */
+    frame = null;
+
+    /**
+     * Where the decoded page's byte 0 sits in {@link buffer}.
+     * @type {number}
+     */
+    base = 0;
+
+    /**
+     * @type {BinaryBuffer}
+     */
+    buffer = null;
+
+    /**
+     * @type {number}
+     */
+    size = 0;
+
+    group_count = 0;
+    cluster_count = 0;
+    min_level = 0;
+    max_level = 0;
+
+    /**
+     * @type {number}
+     */
+    node_count = 0;
+
+    /**
+     * @type {number}
+     */
+    node_table_offset = 0;
+
+    /**
+     * @type {VGeoMetric}
+     */
+    metric = null;
+    cluster_table_offset = 0;
+    payload_offset = 0;
+    payload_size = 0;
+
+    /**
+     * `[page_index, ...]` in child-table order.
+     * @type {number[]}
+     */
+    child_pages = [];
+
+    /**
+     * Position `buffer` at a page-relative offset.
+     * @param {number} offset
+     */
+    seek(offset) {
+        this.buffer.position = this.base + offset;
+    }
+}
+
+/**
+ * @param {BinaryBuffer} buffer positioned at the sphere
+ * @returns {number[]} `[x, y, z, radius]`
+ */
+function read_sphere(buffer) {
+    const result = new Float32Array(4);
+
+    buffer.readFloat32Array(result, 0, 4);
+
+    return Array.from(result);
+}
+
+/**
+ * @param {BinaryBuffer} buffer positioned at the box
+ * @returns {number[]} `[min_x, min_y, min_z, max_x, max_y, max_z]`
+ */
+function read_aabb(buffer) {
+    const result = new Float32Array(6);
+
+    buffer.readFloat32Array(result, 0, 6);
+
+    return Array.from(result);
+}
+
+/**
+ * @param {number[]} outer
+ * @param {number[]} inner
+ * @returns {boolean} whether `outer` contains `inner`, evaluated on the stored values exactly
+ */
+function sphere_contains_sphere(outer, inner) {
+    const dx = inner[0] - outer[0];
+    const dy = inner[1] - outer[1];
+    const dz = inner[2] - outer[2];
+
+    return Math.sqrt(dx * dx + dy * dy + dz * dz) + inner[3] <= outer[3];
+}
+
+/**
+ * @param {number[]} sphere
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {boolean}
+ */
+function sphere_contains_point(sphere, x, y, z) {
+    const dx = x - sphere[0];
+    const dy = y - sphere[1];
+    const dz = z - sphere[2];
+
+    return Math.sqrt(dx * dx + dy * dy + dz * dz) <= sphere[3];
+}
+
+/**
+ * @param {BinaryBuffer} buffer whole file
+ * @param {VGeoDefect[]} out
+ * @returns {boolean} whether the header is sane enough for the rest of the audit to proceed
+ */
+function check_header(buffer, out) {
+    if (buffer.capacity < VGEO_HEADER_SIZE) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `file is ${buffer.capacity} bytes, shorter than the ${VGEO_HEADER_SIZE} byte header`));
+
+        return false;
+    }
+
+    let usable = true;
+
+    buffer.position = 0;
+
+    const magic = buffer.readUint32();
+
+    if (magic !== VGEO_MAGIC) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `magic is 0x${magic.toString(16)}, expected 0x${VGEO_MAGIC.toString(16)}`));
+
+        usable = false;
+    }
+
+    const format_version = buffer.readUint16();
+
+    if (format_version !== VGEO_FORMAT_VERSION) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `format_version is ${format_version}, this validator knows ${VGEO_FORMAT_VERSION}`));
+
+        usable = false;
+    }
+
+    const min_reader_version = buffer.readUint16();
+
+    if (min_reader_version !== VGEO_MIN_READER_VERSION) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `min_reader_version is ${min_reader_version}, expected ${VGEO_MIN_READER_VERSION}`));
+    }
+
+    const header_size = buffer.readUint16();
+
+    if (header_size !== VGEO_HEADER_SIZE) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `header_size is ${header_size}, expected ${VGEO_HEADER_SIZE}`));
+    }
+
+    const hash_algo = buffer.readUint8();
+
+    if (hash_algo !== VGEO_HASH_ALGO_XXH3) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `hash_algo is ${hash_algo}, expected ${VGEO_HASH_ALGO_XXH3}`));
+
+        usable = false;
+    }
+
+    if (buffer.readUint8() !== 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'reserved byte at 11 is not zero'));
+    }
+
+    const feature_flags_required = buffer.readUint32();
+
+    if (feature_flags_required !== 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `feature_flags_required is 0x${feature_flags_required.toString(16)}, no bit is defined`));
+
+        usable = false;
+    }
+
+    buffer.position = VGEO_HEADER_OFFSET.PAYLOAD_ENCODING;
+
+    const payload_encoding = buffer.readUint32();
+
+    if (payload_encoding !== VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `payload_encoding is ${payload_encoding}, expected ${VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1}`));
+
+        usable = false;
+    }
+
+    buffer.position = VGEO_HEADER_OFFSET.TOTAL_PAGES;
+
+    const total_pages = buffer.readUint32();
+
+    if (total_pages < 1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'total_pages is 0'));
+
+        usable = false;
+    }
+
+    const total_clusters = Number(buffer.readUint64());
+
+    if (total_clusters < 1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'total_clusters is 0'));
+    }
+
+    const total_groups = Number(buffer.readUint64());
+
+    if (total_groups < 1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'total_groups is 0'));
+    }
+
+    const root_page_offset = Number(buffer.readUint64());
+
+    buffer.position = VGEO_HEADER_OFFSET.DIRECTORY_OFFSET;
+
+    const directory_offset = Number(buffer.readUint64());
+
+    if (directory_offset % VGEO_FRAME_ALIGNMENT !== 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `directory_offset ${directory_offset} is not ${VGEO_FRAME_ALIGNMENT}-aligned`));
+
+        usable = false;
+    }
+
+    if (directory_offset <= VGEO_HEADER_SIZE || directory_offset > buffer.capacity) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `directory_offset ${directory_offset} is outside the file`));
+
+        return false;
+    }
+
+    const dir_block_checksums_offset = Number(buffer.readUint64());
+
+    const expected_dir_block_offset = directory_offset + total_pages * VGEO_DIRECTORY_RECORD_SIZE;
+
+    if (dir_block_checksums_offset !== expected_dir_block_offset) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `dir_block_checksums_offset is ${dir_block_checksums_offset}, expected ${expected_dir_block_offset}`));
+
+        usable = false;
+    }
+
+    const expected_length = dir_block_checksums_offset + vgeo_directory_block_count(total_pages) * 8;
+
+    if (usable && buffer.capacity !== expected_length) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `file is ${buffer.capacity} bytes, the header describes ${expected_length}`));
+
+        usable = false;
+    }
+
+    buffer.position = 100;
+
+    if (buffer.readUint16() !== 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'reserved u16 at 100 is not zero'));
+    }
+
+    const level_count = buffer.readUint8();
+
+    if (level_count < 1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'level_count is 0'));
+
+        usable = false;
+    }
+
+    // The frame region begins after the level table, not at a fixed offset — which is what keeps
+    // the header, the whole table and the always-resident root page in one contiguous head fetch.
+    const expected_root_page_offset = round_up(
+        VGEO_HEADER_SIZE + level_count * VGEO_LEVEL_RECORD_SIZE, VGEO_FRAME_ALIGNMENT
+    );
+
+    if (root_page_offset !== expected_root_page_offset) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `root_page_offset is ${root_page_offset}; ${level_count} levels of level table put it at ${expected_root_page_offset}`));
+
+        usable = false;
+    }
+
+    if (buffer.readUint8() !== 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'reserved byte at 103 is not zero'));
+    }
+
+    const source_vertex_count = Number(buffer.readUint64());
+
+    if (source_vertex_count < 3) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `source_vertex_count is ${source_vertex_count}, must be at least 3`));
+    }
+
+    const source_face_count = Number(buffer.readUint64());
+
+    if (source_face_count < 1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `source_face_count is ${source_face_count}, must be at least 1`));
+    }
+
+    const object_sphere = read_sphere(buffer);
+
+    if (!object_sphere.every(Number.isFinite) || object_sphere[3] < 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `object_sphere is not a finite non-negative sphere: ${object_sphere}`));
+    }
+
+    const object_bounds = read_aabb(buffer);
+
+    if (!object_bounds.every(Number.isFinite)) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `object_bounds is not finite: ${object_bounds}`));
+    }
+
+    for (let axis = 0; axis < 3; axis++) {
+        if (object_bounds[axis] > object_bounds[axis + 3]) {
+            out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `object_bounds axis ${axis} has min > max`));
+        }
+    }
+
+    for (let offset = 160; offset < VGEO_HEADER_OFFSET.HEADER_CHECKSUM; offset++) {
+        if (buffer.raw_bytes[offset] !== 0) {
+            out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `reserved byte at ${offset} is not zero`));
+
+            break;
+        }
+    }
+
+    return usable;
+}
+
+/**
+ * @param {BinaryBuffer} buffer whole file
+ * @param {VGeoDefect[]} out
+ */
+function check_hashes(buffer, out) {
+    buffer.position = VGEO_HEADER_OFFSET.HEADER_CHECKSUM;
+
+    const stored_header_checksum = buffer.readUint64();
+    const computed_header_checksum = vgeo_compute_header_checksum(buffer);
+
+    if (stored_header_checksum !== computed_header_checksum) {
+        out.push(new VGeoDefect(VGEO_DEFECT.CHECKSUM, `header_checksum is ${stored_header_checksum.toString(16)}, computed ${computed_header_checksum.toString(16)}`));
+    }
+
+    buffer.position = VGEO_HEADER_OFFSET.ASSET_ID;
+
+    const stored_low = buffer.readUint64();
+    const stored_high = buffer.readUint64();
+
+    const computed = vgeo_compute_asset_id(buffer);
+
+    if (stored_low !== computed.low64 || stored_high !== computed.high64) {
+        out.push(new VGeoDefect(VGEO_DEFECT.CHECKSUM, `asset_id is ${stored_high.toString(16)}${stored_low.toString(16)}, computed ${computed.toString()}`));
+    }
+}
+
+/**
+ * @param {BinaryBuffer} buffer whole file
+ * @param {VGeoFrameExtent[]} frames
+ * @param {VGeoDefect[]} out
+ */
+function check_frames(buffer, frames, out) {
+    buffer.position = VGEO_HEADER_OFFSET.TOTAL_PAGES;
+
+    const total_pages = buffer.readUint32();
+
+    buffer.position = VGEO_HEADER_OFFSET.DIRECTORY_OFFSET;
+
+    const directory_offset = Number(buffer.readUint64());
+
+    if (frames.length !== total_pages) {
+        out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `frame scan found ${frames.length} frames, header says total_pages = ${total_pages}`));
+    }
+
+    if (frames.length > 0) {
+        const last = frames[frames.length - 1];
+
+        const end = last.frame_offset + last.fetch_size;
+
+        if (end !== directory_offset) {
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `frame region ends at ${end}, directory_offset is ${directory_offset}; the two must coincide exactly`));
+        }
+    }
+
+    buffer.position = VGEO_HEADER_OFFSET.ASSET_ID;
+
+    const asset_id_low = buffer.readUint64();
+
+    for (const frame of frames) {
+        buffer.position = frame.frame_offset;
+
+        const magic = buffer.readUint32();
+
+        if (magic !== VGEO_PAGE_MAGIC) {
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: magic is 0x${magic.toString(16)}, expected 0x${VGEO_PAGE_MAGIC.toString(16)}`));
+        }
+
+        const decodable = frame.codec === VGEO_CODEC_RAW || frame.codec === VGEO_CODEC_LZ4;
+
+        if (!decodable) {
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: codec is ${frame.codec}, this validator knows ${VGEO_CODEC_RAW} (raw) and ${VGEO_CODEC_LZ4} (lz4)`));
+        }
+
+        if (frame.flags !== 0) {
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: frame flags are 0x${frame.flags.toString(16)}, no bit is defined`));
+        }
+
+        if (frame.codec === VGEO_CODEC_RAW && frame.decoded_size !== frame.stored_size) {
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: raw frame has stored_size ${frame.stored_size} and decoded_size ${frame.decoded_size}`));
+        }
+
+        // A `decoded_size` above what the stored bytes could physically produce is caught here
+        // rather than at decode, because a reader allocates against it *before* it decodes — see
+        // {@link vgeo_frame_decode_bound}.
+        if (decodable && frame.decoded_size > vgeo_frame_decode_bound(frame.codec, frame.stored_size)) {
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: decoded_size ${frame.decoded_size} is more than codec ${frame.codec} could produce from ${frame.stored_size} stored bytes`));
+        }
+
+        if (frame.frame_offset % VGEO_FRAME_ALIGNMENT !== 0) {
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: frame_offset ${frame.frame_offset} is not ${VGEO_FRAME_ALIGNMENT}-aligned`));
+        }
+
+        if (frame.frame_offset + frame.extent > directory_offset) {
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: frame runs past directory_offset`));
+
+            continue;
+        }
+
+        buffer.position = frame.frame_offset + VGEO_FRAME_OFFSET.CHECKSUM;
+
+        const stored_checksum = buffer.readUint64();
+        const computed_checksum = vgeo_compute_frame_checksum(buffer, frame, asset_id_low);
+
+        if (stored_checksum !== computed_checksum) {
+            out.push(new VGeoDefect(VGEO_DEFECT.CHECKSUM, `page ${frame.page_index}: frame checksum is ${stored_checksum.toString(16)}, computed ${computed_checksum.toString(16)}`));
+        }
+    }
+
+    if (frames.length > 0) {
+        buffer.position = VGEO_HEADER_OFFSET.ROOT_PAGE_FETCH_SIZE;
+
+        const root_fetch_size = buffer.readUint32();
+        const root_decoded_size = buffer.readUint32();
+
+        if (root_fetch_size !== frames[0].fetch_size) {
+            out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `root_page_fetch_size is ${root_fetch_size}, the root frame's is ${frames[0].fetch_size}`));
+        }
+
+        if (root_decoded_size !== frames[0].decoded_size) {
+            out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `root_page_decoded_size is ${root_decoded_size}, the root frame's is ${frames[0].decoded_size}`));
+        }
+    }
+}
+
+/**
+ * Decode one page and check its internal layout.
+ *
+ * @param {BinaryBuffer} buffer whole file
+ * @param {VGeoFrameExtent} frame
+ * @param {number} level_count
+ * @param {VGeoDefect[]} out
+ * @returns {DecodedPage|undefined} `undefined` when the page is too malformed to read further
+ */
+function decode_page(buffer, frame, level_count, out) {
+    const page = new DecodedPage();
+
+    page.page_index = frame.page_index;
+    page.frame = frame;
+    page.size = frame.decoded_size;
+
+    const blob = frame.frame_offset
+        + VGEO_FRAME_HEADER_SIZE
+        + VGEO_CHILD_TABLE_ENTRY_SIZE * frame.child_page_count;
+
+    // Everything below reads the blob, so it has to be in the file first. `check_frames` has
+    // already reported a frame that runs past the directory; what this stops is the reading.
+    if (blob + frame.stored_size > buffer.capacity) {
+        return undefined;
+    }
+
+    if (frame.codec === VGEO_CODEC_RAW) {
+        // Nothing to decode: the page *is* those bytes. `check_frames` has already reported it if
+        // the two sizes disagree, and with them disagreeing the page's own length is not knowable,
+        // so there is nothing left to audit.
+        if (frame.stored_size !== frame.decoded_size) {
+            return undefined;
+        }
+
+        page.buffer = buffer;
+        page.base = blob;
+    } else if (frame.codec === VGEO_CODEC_LZ4) {
+        // Bounded by `check_frames`, which has reported it, before it is believed — so a corrupt
+        // length field is a defect rather than an allocation.
+        if (frame.decoded_size > vgeo_frame_decode_bound(frame.codec, frame.stored_size)) {
+            return undefined;
+        }
+
+        page.buffer = new BinaryBuffer();
+        page.base = 0;
+
+        page.buffer.setCapacity(frame.decoded_size);
+
+        try {
+            vgeo_decode_frame_blob(page.buffer.raw_bytes, 0, buffer.raw_bytes, frame);
+        } catch (error) {
+            // Not suppression — the decoder's own message is what says *how* the blob is malformed,
+            // and a validator that threw here would be unable to report the one thing it exists to
+            // report.
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: ${error.message}`));
+
+            return undefined;
+        }
+    } else {
+        // `check_frames` has already named the codec; there is no decoder to go on with.
+        return undefined;
+    }
+
+    if (page.size < VGEO_PAGE_HEADER_SIZE) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: decoded page is ${page.size} bytes, shorter than its header`));
+
+        return undefined;
+    }
+
+    // Everything from here on is a read of the *decoded* page, which under a compressing codec is
+    // not the file — so it goes through the page's own buffer and never the one passed in.
+    const decoded = page.buffer;
+
+    page.seek(0);
+
+    page.group_count = decoded.readUint16();
+    page.cluster_count = decoded.readUint16();
+    page.min_level = decoded.readUint8();
+    page.max_level = decoded.readUint8();
+
+    page.node_count = decoded.readUint16();
+
+    page.cluster_table_offset = decoded.readUint32();
+    page.payload_offset = decoded.readUint32();
+    page.payload_size = decoded.readUint32();
+    page.node_table_offset = decoded.readUint32();
+
+    for (let offset = 24; offset < VGEO_PAGE_OFFSET.METRIC; offset++) {
+        if (decoded.raw_bytes[page.base + offset] !== 0) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: reserved byte at ${offset} in the page header is not zero`));
+
+            break;
+        }
+    }
+
+    page.seek(VGEO_PAGE_OFFSET.METRIC);
+
+    page.metric = read_metric(decoded);
+
+    if (page.group_count < 1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: group_count is 0`));
+
+        return undefined;
+    }
+
+    if (page.cluster_count < 1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: cluster_count is 0`));
+
+        return undefined;
+    }
+
+    if (page.min_level > page.max_level) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: min_level ${page.min_level} exceeds max_level ${page.max_level}`));
+    }
+
+    if (page.max_level >= level_count) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: max_level ${page.max_level} is outside level_count ${level_count}`));
+    }
+
+    // One node per group is the worst the tree can come to — a leaf holds up to the fanout, and
+    // every interior node has at least two children — so 2·groups bounds it whatever the shape.
+    if (page.node_count < 1 || page.node_count > 2 * page.group_count) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: node_count is ${page.node_count}, outside 1..${2 * page.group_count} for ${page.group_count} groups`));
+
+        return undefined;
+    }
+
+    const expected_node_table_offset = VGEO_PAGE_HEADER_SIZE + page.group_count * VGEO_GROUP_RECORD_SIZE;
+
+    if (page.node_table_offset !== expected_node_table_offset) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: node_table_offset is ${page.node_table_offset}, expected ${expected_node_table_offset}`));
+
+        return undefined;
+    }
+
+    const expected_cluster_table_offset = page.node_table_offset
+        + page.node_count * VGEO_NODE_RECORD_SIZE;
+
+    if (page.cluster_table_offset !== expected_cluster_table_offset) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: cluster_table_offset is ${page.cluster_table_offset}, expected ${expected_cluster_table_offset}`));
+
+        return undefined;
+    }
+
+    const expected_payload_offset = page.cluster_table_offset + page.cluster_count * VGEO_CLUSTER_RECORD_SIZE;
+
+    if (page.payload_offset !== expected_payload_offset) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: payload_offset is ${page.payload_offset}, expected ${expected_payload_offset}`));
+
+        return undefined;
+    }
+
+    if (page.payload_offset + page.payload_size !== page.size) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: payload ends at ${page.payload_offset + page.payload_size}, the decoded page is ${page.size} bytes`));
+
+        return undefined;
+    }
+
+    for (let i = 0; i < frame.child_page_count; i++) {
+        buffer.position = frame.frame_offset + VGEO_FRAME_HEADER_SIZE + i * VGEO_CHILD_TABLE_ENTRY_SIZE + 8;
+
+        page.child_pages.push(buffer.readUint32());
+    }
+
+    return page;
+}
+
+/**
+ * A traversal metric, wherever it is carried.
+ */
+class VGeoMetric {
+    /**
+     * @type {Float32Array}
+     */
+    sphere = new Float32Array(4);
+
+    /**
+     * @type {number}
+     */
+    min_self_error = 0;
+
+    /**
+     * @type {number}
+     */
+    max_parent_error = 0;
+}
+
+/**
+ * @param {BinaryBuffer} buffer positioned at the metric
+ * @returns {VGeoMetric}
+ */
+function read_metric(buffer) {
+    const result = new VGeoMetric();
+
+    buffer.readFloat32Array(result.sphere, 0, 4);
+
+    result.min_self_error = buffer.readFloat32();
+    result.max_parent_error = buffer.readFloat32();
+
+    return result;
+}
+
+/**
+ * Does `outer` contain `inner`? Both are `[centre xyz, radius]`.
+ *
+ * Slack is a relative epsilon on the radius: the spheres a node aggregates were combined in float32
+ * pairwise, and an exact containment test would flag the last bit of that arithmetic as a defect.
+ *
+ * @param {Float32Array} outer
+ * @param {Float32Array} inner
+ * @returns {boolean}
+ */
+function sphere_contains(outer, inner) {
+    const dx = inner[0] - outer[0];
+    const dy = inner[1] - outer[1];
+    const dz = inner[2] - outer[2];
+
+    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    return distance + inner[3] <= outer[3] * (1 + 1e-4) + 1e-4;
+}
+
+/**
+ * A page's group tree: that it is a tree over exactly this page's groups, and that a node's metric
+ * really does bound everything under it.
+ *
+ * The second half is what makes the structure worth anything. A traversal skips a subtree when the
+ * node's `max_parent_error` projects to no more than the threshold, and culls one when its sphere
+ * misses the frustum; both are only sound if the node's numbers dominate every group beneath it. A
+ * node whose sphere is too small silently drops geometry, and nothing downstream would notice.
+ *
+ * @param {DecodedPage[]} pages
+ * @param {object[][]} page_groups
+ * @param {object[][]} page_clusters
+ * @param {VGeoDefect[]} out
+ */
+function check_page_nodes(pages, page_groups, page_clusters, out) {
+    for (const page of pages) {
+        const groups = page_groups[page.page_index];
+        const clusters = page_clusters[page.page_index];
+
+        const buffer = page.buffer;
+
+        const nodes = [];
+
+        for (let index = 0; index < page.node_count; index++) {
+            const base = page.base + page.node_table_offset + index * VGEO_NODE_RECORD_SIZE;
+
+            buffer.position = base + VGEO_NODE_OFFSET.METRIC;
+
+            const node = { metric: read_metric(buffer) };
+
+            buffer.position = base + VGEO_NODE_OFFSET.CHILD_FIRST;
+
+            node.child_first = buffer.readUint16();
+            node.child_count = buffer.readUint16();
+
+            const flags = buffer.readUint16();
+
+            node.is_leaf = (flags & VGEO_NODE_FLAG_LEAF) !== 0;
+
+            if ((flags & ~VGEO_NODE_FLAG_LEAF) !== 0) {
+                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: unknown flag bits ${flags}`));
+            }
+
+            nodes.push(node);
+        }
+
+        /**
+         * How many times each group is reached through a leaf. Exactly once, or the tree is not a
+         * partition of the page and a traversal either misses geometry or draws it twice.
+         * @type {Int32Array}
+         */
+        const group_hits = new Int32Array(groups.length);
+
+        let structural = true;
+
+        nodes.forEach((node, index) => {
+            if (node.child_count < 1 || node.child_count > VGEO_NODE_FANOUT) {
+                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: child_count ${node.child_count} is outside 1..${VGEO_NODE_FANOUT}`));
+
+                structural = false;
+
+                return;
+            }
+
+            const limit = node.is_leaf ? groups.length : nodes.length;
+
+            if (node.child_first + node.child_count > limit) {
+                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: children ${node.child_first}..${node.child_first + node.child_count} run past the ${node.is_leaf ? 'group' : 'node'} table's ${limit}`));
+
+                structural = false;
+
+                return;
+            }
+
+            if (node.is_leaf) {
+                for (let i = 0; i < node.child_count; i++) {
+                    group_hits[node.child_first + i]++;
+                }
+
+                return;
+            }
+
+            if (node.child_first <= index) {
+                // Breadth-first layout: a parent is always allocated before its children. Without
+                // it a reader has no bound on the walk and a malformed file can loop it forever.
+                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: child run starts at ${node.child_first}, which is not after the parent`));
+
+                structural = false;
+            }
+        });
+
+        if (!structural) {
+            continue;
+        }
+
+        const unreached = group_hits.reduce((count, hits) => count + (hits === 0 ? 1 : 0), 0);
+        const repeated = group_hits.reduce((count, hits) => count + (hits > 1 ? 1 : 0), 0);
+
+        if (unreached !== 0 || repeated !== 0) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index}: the node tree reaches ${unreached} of its ${groups.length} groups not at all and ${repeated} more than once`));
+
+            continue;
+        }
+
+        /**
+         * @param {number} index
+         * @param {VGeoMetric} covered
+         * @param {string} what
+         */
+        function expect_bounds(index, covered, what) {
+            const metric = nodes[index].metric;
+
+            if (!sphere_contains(metric.sphere, covered.sphere)) {
+                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: its sphere does not contain ${what}`));
+            }
+
+            if (metric.min_self_error > covered.min_self_error) {
+                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: min_self_error ${metric.min_self_error} is above ${what}'s ${covered.min_self_error}`));
+            }
+
+            if (metric.max_parent_error < covered.max_parent_error) {
+                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} node ${index}: max_parent_error ${metric.max_parent_error} is below ${what}'s ${covered.max_parent_error}`));
+            }
+        }
+
+        nodes.forEach((node, index) => {
+            for (let i = 0; i < node.child_count; i++) {
+                if (!node.is_leaf) {
+                    expect_bounds(index, nodes[node.child_first + i].metric, `node ${node.child_first + i}`);
+
+                    continue;
+                }
+
+                const group = groups[node.child_first + i];
+
+                const covered = new VGeoMetric();
+
+                covered.min_self_error = Number.POSITIVE_INFINITY;
+                covered.max_parent_error = 0;
+
+                let first = true;
+
+                for (let c = 0; c < group.cluster_count; c++) {
+                    const cluster = clusters[group.cluster_first + c];
+
+                    if (cluster === undefined) {
+                        continue;
+                    }
+
+                    covered.min_self_error = Math.min(covered.min_self_error, cluster.self_error);
+                    covered.max_parent_error = Math.max(covered.max_parent_error, cluster.parent_error);
+
+                    if (first) {
+                        covered.sphere.set(cluster.parent_sphere);
+
+                        first = false;
+                    }
+                }
+
+                if (first) {
+                    continue;
+                }
+
+                expect_bounds(index, covered, `group ${node.child_first + i}`);
+            }
+        });
+
+        const root = nodes[0];
+
+        if (
+            root !== undefined
+            && (
+                !sphere_contains(page.metric.sphere, root.metric.sphere)
+                || page.metric.min_self_error !== root.metric.min_self_error
+                || page.metric.max_parent_error !== root.metric.max_parent_error
+            )
+        ) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index}: the page header's metric disagrees with its root node's`));
+        }
+    }
+}
+
+/**
+ * @param {BinaryBuffer} buffer whole file
+ * @param {VGeoFrameExtent[]} frames
+ * @param {DecodedPage[]} pages
+ * @param {VGeoDefect[]} out
+ */
+function check_child_tables(buffer, frames, pages, out) {
+    for (const page of pages) {
+        const frame = page.frame;
+
+        const seen = new Set();
+
+        for (let i = 0; i < frame.child_page_count; i++) {
+            buffer.position = frame.frame_offset + VGEO_FRAME_HEADER_SIZE + i * VGEO_CHILD_TABLE_ENTRY_SIZE;
+
+            const child_frame_offset = Number(buffer.readUint64());
+            const child_page_index = buffer.readUint32();
+            const child_fetch_size = buffer.readUint32();
+            const child_decoded_size = buffer.readUint32();
+            const reserved = buffer.readUint32();
+
+            const metric = read_metric(buffer);
+
+            const child_page = pages.find((candidate) => candidate.page_index === child_page_index);
+
+            if (child_page !== undefined && child_page.metric !== null) {
+                // Copied, so it can be read before the child is fetched — which is the whole point
+                // — and therefore able to drift from the truth. Nothing else would catch it: a
+                // traversal that trusts a stale metric skips a page it needed and leaves a hole.
+                if (
+                    metric.sphere.some((value, axis) => value !== child_page.metric.sphere[axis])
+                    || metric.min_self_error !== child_page.metric.min_self_error
+                    || metric.max_parent_error !== child_page.metric.max_parent_error
+                ) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: its metric for page ${child_page_index} disagrees with that page's own`));
+                }
+            }
+
+            if (reserved !== 0) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: reserved is not zero`));
+            }
+
+            if (seen.has(child_page_index)) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index}: child page ${child_page_index} appears more than once; the table must be deduplicated`));
+            }
+
+            seen.add(child_page_index);
+
+            if (child_page_index >= frames.length) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: page_index ${child_page_index} does not exist`));
+
+                continue;
+            }
+
+            if (child_page_index === page.page_index) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: a page may not name itself; same-page children use the SAME_PAGE sentinel`));
+            }
+
+            const child = frames[child_page_index];
+
+            if (child_frame_offset !== child.frame_offset) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: frame_offset ${child_frame_offset}, the frame is at ${child.frame_offset}`));
+            }
+
+            if (child_frame_offset <= frame.frame_offset) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: child frame_offset ${child_frame_offset} is not strictly ahead of ${frame.frame_offset}; file order must be topological`));
+            }
+
+            if (child_fetch_size !== child.fetch_size) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: fetch_size ${child_fetch_size}, the frame's is ${child.fetch_size}`));
+            }
+
+            if (child_decoded_size !== child.decoded_size) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CHILD_TABLE, `page ${page.page_index} entry ${i}: decoded_size ${child_decoded_size}, the frame's is ${child.decoded_size}`));
+            }
+        }
+    }
+}
+
+/**
+ * @param {DecodedPage} page
+ * @param {VGeoDefect[]} out
+ * @returns {{cluster_first:number, cluster_count:number, parent_cluster_count:number}[]}
+ */
+function read_groups(page, out) {
+    const result = [];
+
+    const buffer = page.buffer;
+
+    let expected_first = 0;
+
+    for (let g = 0; g < page.group_count; g++) {
+        page.seek(VGEO_PAGE_HEADER_SIZE + g * VGEO_GROUP_RECORD_SIZE);
+
+        const group = {
+            cluster_first: buffer.readUint16(),
+            cluster_count: buffer.readUint16(),
+            parent_cluster_count: buffer.readUint16(),
+        };
+
+        if (buffer.readUint16() !== 0) {
+            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: reserved is not zero`));
+        }
+
+        if (group.cluster_count < 1 || group.cluster_count > VGEO_MAX_GROUP_CLUSTER_COUNT) {
+            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: cluster_count ${group.cluster_count} is outside [1, ${VGEO_MAX_GROUP_CLUSTER_COUNT}]`));
+        }
+
+        if (group.cluster_first !== expected_first) {
+            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: cluster_first ${group.cluster_first}, expected ${expected_first}; a page's groups must tile its cluster records in order`));
+        }
+
+        expected_first = group.cluster_first + group.cluster_count;
+
+        result.push(group);
+    }
+
+    if (expected_first !== page.cluster_count) {
+        out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index}: groups cover ${expected_first} clusters, the page holds ${page.cluster_count}`));
+    }
+
+    return result;
+}
+
+/**
+ * Decode a cluster's local positions from its payload — the only way to check that the culling
+ * bounds actually bound anything.
+ *
+ * @param {DecodedPage} page
+ * @param {object} cluster
+ * @returns {Float32Array} `vertex_count * 3` coordinates
+ */
+function read_cluster_positions(page, cluster) {
+    page.seek(
+        page.payload_offset
+        + cluster.payload_offset
+        + vgeo_payload_attribute_offset(0, cluster.vertex_count, cluster.triangle_count, cluster.encoding_flags)
+    );
+
+    const result = new Float32Array(cluster.vertex_count * 3);
+
+    page.buffer.readFloat32Array(result, 0, result.length);
+
+    return result;
+}
+
+/**
+ * @param {DecodedPage} page
+ * @param {VGeoDefect[]} out
+ * @returns {object[]}
+ */
+function read_clusters(page, out) {
+    const result = [];
+
+    const buffer = page.buffer;
+
+    for (let c = 0; c < page.cluster_count; c++) {
+        page.seek(page.cluster_table_offset + c * VGEO_CLUSTER_RECORD_SIZE);
+
+        const cluster = {
+            index: c,
+            self_sphere: read_sphere(buffer),
+            self_error: buffer.readFloat32(),
+            parent_error: buffer.readFloat32(),
+            parent_sphere: read_sphere(buffer),
+            bounds_sphere: read_sphere(buffer),
+            aabb: read_aabb(buffer),
+            child_ref: buffer.readUint16(),
+            child_group: buffer.readUint16(),
+            cone_reserved: buffer.readUint32(),
+            encoding_flags: buffer.readUint32(),
+            payload_offset: buffer.readUint32(),
+            payload_size: buffer.readUint32(),
+            vertex_count: buffer.readUint8(),
+            triangle_count: buffer.readUint8(),
+        };
+
+        if (buffer.readUint16() !== 0 || buffer.readUint64() !== 0n) {
+            out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `page ${page.page_index} cluster ${c}: reserved tail is not zero`));
+        }
+
+        if (cluster.cone_reserved !== 0) {
+            out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `page ${page.page_index} cluster ${c}: cone_reserved is not zero`));
+        }
+
+        result.push(cluster);
+    }
+
+    return result;
+}
+
+/**
+ * Everything about one cluster that its own record settles: counts, flags, payload extent, bounds
+ * that actually bound, and finite metric values.
+ *
+ * @param {DecodedPage} page
+ * @param {object} cluster
+ * @param {number[]} object_sphere
+ * @param {number[]} object_bounds
+ * @param {VGeoDefect[]} out
+ */
+function check_cluster_record(page, cluster, object_sphere, object_bounds, out) {
+    const where = `page ${page.page_index} cluster ${cluster.index}`;
+
+    if (cluster.vertex_count < 3 || cluster.vertex_count > VGEO_MAX_CLUSTER_VERTEX_COUNT) {
+        out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: vertex_count ${cluster.vertex_count} is outside [3, ${VGEO_MAX_CLUSTER_VERTEX_COUNT}]`));
+
+        return;
+    }
+
+    if (cluster.triangle_count < 1 || cluster.triangle_count > VGEO_MAX_CLUSTER_TRIANGLE_COUNT) {
+        out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: triangle_count ${cluster.triangle_count} is outside [1, ${VGEO_MAX_CLUSTER_TRIANGLE_COUNT}]`));
+
+        return;
+    }
+
+    if ((cluster.encoding_flags & ~VGEO_ENCODING_FLAGS_MASK) !== 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: encoding_flags 0x${cluster.encoding_flags.toString(16)} sets a bit that must be clear (skinning bits and reserved bits)`));
+    }
+
+    if (cluster.payload_offset % 4 !== 0 || cluster.payload_size % 4 !== 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: payload offset ${cluster.payload_offset} / size ${cluster.payload_size} is not a multiple of 4`));
+
+        return;
+    }
+
+    const expected_size = vgeo_payload_size(cluster.vertex_count, cluster.triangle_count, cluster.encoding_flags);
+
+    if (cluster.payload_size !== expected_size) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: payload_size ${cluster.payload_size}, the encoding needs ${expected_size}`));
+
+        return;
+    }
+
+    if (cluster.payload_offset + cluster.payload_size > page.payload_size) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: payload runs past the page's payload section`));
+
+        return;
+    }
+
+    const index_base = page.base + page.payload_offset + cluster.payload_offset;
+
+    for (let i = 0; i < cluster.triangle_count * 3; i++) {
+        const index = page.buffer.raw_bytes[index_base + i];
+
+        if (index >= cluster.vertex_count) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: local index ${index} at ${i} is outside the cluster's ${cluster.vertex_count} vertices`));
+
+            break;
+        }
+    }
+
+    const named_spheres = [
+        ['self_sphere', cluster.self_sphere],
+        ['parent_sphere', cluster.parent_sphere],
+        ['bounds_sphere', cluster.bounds_sphere],
+    ];
+
+    for (const [name, sphere] of named_spheres) {
+        if (!sphere.every(Number.isFinite) || sphere[3] < 0) {
+            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: ${name} is not a finite non-negative sphere: ${sphere}`));
+        }
+    }
+
+    if (!cluster.aabb.every(Number.isFinite)) {
+        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: aabb is not finite`));
+    }
+
+    if (!Number.isFinite(cluster.self_error) || cluster.self_error < 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: self_error ${cluster.self_error} must be finite and non-negative`));
+    }
+
+    if (Number.isNaN(cluster.parent_error) || cluster.parent_error < 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: parent_error ${cluster.parent_error} must be non-negative and not NaN`));
+    }
+
+    if (cluster.parent_error < cluster.self_error) {
+        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: parent_error ${cluster.parent_error} is below self_error ${cluster.self_error}`));
+    }
+
+    if (!sphere_contains_sphere(cluster.parent_sphere, cluster.self_sphere)) {
+        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: parent_sphere does not contain self_sphere`));
+    }
+
+    const positions = read_cluster_positions(page, cluster);
+
+    for (let v = 0; v < cluster.vertex_count; v++) {
+        const x = positions[v * 3];
+        const y = positions[v * 3 + 1];
+        const z = positions[v * 3 + 2];
+
+        if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAYLOAD, `${where}: vertex ${v} is not finite`));
+
+            break;
+        }
+
+        if (!sphere_contains_point(cluster.bounds_sphere, x, y, z)) {
+            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: bounds_sphere does not contain vertex ${v}`));
+
+            break;
+        }
+
+        if (x < cluster.aabb[0] || y < cluster.aabb[1] || z < cluster.aabb[2]
+            || x > cluster.aabb[3] || y > cluster.aabb[4] || z > cluster.aabb[5]) {
+            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: aabb does not contain vertex ${v}`));
+
+            break;
+        }
+
+        if (!sphere_contains_point(object_sphere, x, y, z)) {
+            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: the header's object_sphere does not contain vertex ${v}`));
+
+            break;
+        }
+
+        if (x < object_bounds[0] || y < object_bounds[1] || z < object_bounds[2]
+            || x > object_bounds[3] || y > object_bounds[4] || z > object_bounds[5]) {
+            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: the header's object_bounds does not contain vertex ${v}`));
+
+            break;
+        }
+    }
+}
+
+/**
+ * The whole cross-page audit: child references resolve and point at a strictly coarser band than the
+ * cluster making them, the DAG has exactly one root, every group's `parent_cluster_count` is exact,
+ * the metric pair a step writes is the same on both sides of that step, and every page is reachable
+ * from the root.
+ *
+ * @param {DecodedPage[]} pages
+ * @param {object[][]} page_groups
+ * @param {object[][]} page_clusters
+ * @param {number} level_count
+ * @param {VGeoDefect[]} out
+ */
+function check_dag(pages, page_groups, page_clusters, level_count, out) {
+    /**
+     * How many clusters name each `page:group`, so that `parent_cluster_count` can be counted rather
+     * than trusted.
+     * @type {Map<string, number>}
+     */
+    const reference_counts = new Map();
+
+    for (const page of pages) {
+        for (const cluster of page_clusters[page.page_index]) {
+            const where = `page ${page.page_index} cluster ${cluster.index}`;
+
+            if (cluster.child_ref === VGEO_NO_CHILD) {
+                if (cluster.child_group !== VGEO_NO_GROUP) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: child_ref is NO_CHILD but child_group is ${cluster.child_group}`));
+                }
+
+                if (cluster.self_error !== 0) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: a leaf must carry self_error 0, has ${cluster.self_error}`));
+                }
+
+                continue;
+            }
+
+            if (cluster.child_group === VGEO_NO_GROUP) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: child_group is NO_GROUP but child_ref is ${cluster.child_ref}`));
+
+                continue;
+            }
+
+            let child_page_index;
+
+            if (cluster.child_ref === VGEO_SAME_PAGE) {
+                if (page.min_level === page.max_level) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: SAME_PAGE is legal only in a page whose band spans more than one level`));
+
+                    continue;
+                }
+
+                child_page_index = page.page_index;
+            } else {
+                if (cluster.child_ref > VGEO_MAX_CHILD_REF || cluster.child_ref >= page.child_pages.length) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: child_ref ${cluster.child_ref} is outside the page's ${page.child_pages.length} child-table entries`));
+
+                    continue;
+                }
+
+                child_page_index = page.child_pages[cluster.child_ref];
+            }
+
+            if (pages[child_page_index] === undefined) {
+                continue;
+            }
+
+            if (
+                cluster.child_ref !== VGEO_SAME_PAGE
+                && pages[child_page_index].max_level >= page.max_level
+            ) {
+                // The band is what puts pages in file order, and a child sitting at or above its
+                // parent's band is a reference that points backwards — the one thing that makes the
+                // file untraversable in a single forward pass.
+                out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `${where}: its child group is in page ${child_page_index}, whose band tops out at ${pages[child_page_index].max_level} — not below this page's ${page.max_level}`));
+            }
+
+            const child_groups = page_groups[child_page_index];
+
+            if (cluster.child_group >= child_groups.length) {
+                out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `${where}: child_group ${cluster.child_group} does not exist in page ${child_page_index}`));
+
+                continue;
+            }
+
+            const key = `${child_page_index}:${cluster.child_group}`;
+
+            reference_counts.set(key, (reference_counts.get(key) ?? 0) + 1);
+
+            const group = child_groups[cluster.child_group];
+
+            for (let i = 0; i < group.cluster_count; i++) {
+                const child = page_clusters[child_page_index][group.cluster_first + i];
+
+                if (child === undefined) {
+                    break;
+                }
+
+                if (child.parent_error !== cluster.self_error) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: self_error ${cluster.self_error} disagrees with the consumed cluster's parent_error ${child.parent_error}; one group step writes one value on both sides`));
+
+                    break;
+                }
+
+                if (child.parent_sphere.some((value, axis) => value !== cluster.self_sphere[axis])) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: self_sphere disagrees with the consumed cluster's parent_sphere`));
+
+                    break;
+                }
+            }
+        }
+    }
+
+    // Exactly one root. The runtime's cut starts at the root and walks down; a second parentless
+    // cluster is a second entry point it would never visit, and its whole subtree with it. It is
+    // also the shape a build that stopped converging leaves behind, which is the likelier cause.
+    const roots = [];
+
+    for (const page of pages) {
+        for (const cluster of page_clusters[page.page_index]) {
+            if (cluster.parent_error === Number.POSITIVE_INFINITY) {
+                roots.push({ page: page.page_index, cluster: cluster.index });
+            }
+        }
+    }
+
+    const where_roots = roots.slice(0, 4).map((root) => `page ${root.page} cluster ${root.cluster}`);
+
+    if (roots.length !== 1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.CLUSTER, `the DAG has ${roots.length} root clusters, expected exactly one${roots.length === 0 ? '' : `: ${where_roots.join(', ')}`}`));
+    } else if (roots[0].page !== 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `the root cluster is in ${where_roots[0]}, not the always-resident root page`));
+    }
+
+    for (const page of pages) {
+        page_groups[page.page_index].forEach((group, group_index) => {
+            const counted = reference_counts.get(`${page.page_index}:${group_index}`) ?? 0;
+
+            if (group.parent_cluster_count !== counted) {
+                out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${group_index}: parent_cluster_count is ${group.parent_cluster_count}, ${counted} clusters name it`));
+            }
+
+            const is_root_group = page.page_index === 0 && page.max_level === level_count - 1;
+
+            if (counted === 0 && !is_root_group) {
+                out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${group_index}: no cluster names it, yet it is not one of the root page's topmost-level groups`));
+            }
+
+            for (let i = 0; i < group.cluster_count; i++) {
+                const cluster = page_clusters[page.page_index][group.cluster_first + i];
+
+                if (cluster === undefined) {
+                    break;
+                }
+
+                const is_root = cluster.parent_error === Number.POSITIVE_INFINITY;
+
+                if (is_root !== (counted === 0)) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `page ${page.page_index} cluster ${cluster.index}: parent_error is ${cluster.parent_error} while its group has ${counted} parents; +Infinity holds exactly for a group nothing consumes`));
+
+                    break;
+                }
+
+                if (is_root && cluster.parent_sphere.some((value, axis) => value !== cluster.self_sphere[axis])) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `page ${page.page_index} cluster ${cluster.index}: a root's parent_sphere must duplicate its self_sphere`));
+
+                    break;
+                }
+            }
+        });
+    }
+
+    const reached = new Set([0]);
+    const queue = [0];
+
+    while (queue.length > 0) {
+        const page_index = queue.pop();
+
+        for (const child of pages[page_index].child_pages) {
+            if (pages[child] !== undefined && !reached.has(child)) {
+                reached.add(child);
+                queue.push(child);
+            }
+        }
+    }
+
+    for (const page of pages) {
+        if (!reached.has(page.page_index)) {
+            out.push(new VGeoDefect(VGEO_DEFECT.REACHABILITY, `page ${page.page_index} is not reachable from the root page`));
+        }
+    }
+}
+
+/**
+ * @param {DecodedPage[]} pages
+ * @param {number} level_count
+ * @param {VGeoDefect[]} out
+ */
+function check_page_order(pages, level_count, out) {
+    const root = pages[0];
+
+    if (root === undefined) {
+        return;
+    }
+
+    if (root.max_level !== level_count - 1) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_ORDER, `the root page's max_level is ${root.max_level}, the topmost level is ${level_count - 1}`));
+    }
+
+    for (let i = 1; i < pages.length; i++) {
+        if (pages[i].max_level > pages[i - 1].max_level) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_ORDER, `page ${i} has max_level ${pages[i].max_level} after page ${i - 1}'s ${pages[i - 1].max_level}; file order must run coarse first`));
+        }
+
+        if (pages[i].max_level === level_count - 1) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_ORDER, `page ${i} also carries the topmost level; the root page must hold it complete`));
+        }
+    }
+}
+
+/**
+ * The directory is derived data: rebuild it from a frame scan and require the file's copy to match
+ * byte for byte, then verify its block checksums.
+ *
+ * @param {BinaryBuffer} buffer whole file
+ * @param {VGeoFrameExtent[]} frames
+ * @param {DecodedPage[]} pages
+ * @param {VGeoDefect[]} out
+ */
+function check_directory(buffer, frames, pages, out) {
+    buffer.position = VGEO_HEADER_OFFSET.TOTAL_PAGES;
+
+    const total_pages = buffer.readUint32();
+
+    buffer.position = VGEO_HEADER_OFFSET.DIRECTORY_OFFSET;
+
+    const directory_offset = Number(buffer.readUint64());
+    const dir_block_checksums_offset = Number(buffer.readUint64());
+
+    const reconstructed = new BinaryBuffer();
+
+    reconstructed.setCapacity(total_pages * VGEO_DIRECTORY_RECORD_SIZE);
+
+    for (let i = 0; i < Math.min(total_pages, frames.length); i++) {
+        const frame = frames[i];
+        const page = pages[i];
+
+        reconstructed.position = i * VGEO_DIRECTORY_RECORD_SIZE;
+
+        reconstructed.writeUint64(BigInt(frame.frame_offset));
+        reconstructed.writeUint32(frame.fetch_size);
+        reconstructed.writeUint32(frame.decoded_size);
+
+        if (page === undefined) {
+            continue;
+        }
+
+        reconstructed.writeUint8(page.min_level);
+        reconstructed.writeUint8(page.max_level);
+        reconstructed.writeUint16(i === 0 ? VGEO_DIRECTORY_FLAG_ROOT_PAGE : 0);
+        reconstructed.writeUint16(page.group_count);
+        reconstructed.writeUint16(page.cluster_count);
+    }
+
+    const stored = buffer.raw_bytes;
+    const expected = reconstructed.raw_bytes;
+
+    for (let i = 0; i < expected.length; i++) {
+        if (stored[directory_offset + i] !== expected[i]) {
+            const record = (i / VGEO_DIRECTORY_RECORD_SIZE) | 0;
+
+            out.push(new VGeoDefect(VGEO_DEFECT.DIRECTORY, `directory record ${record} disagrees with a frame scan at byte ${i % VGEO_DIRECTORY_RECORD_SIZE}: the file has ${stored[directory_offset + i]}, the frames say ${expected[i]}`));
+
+            break;
+        }
+    }
+
+    buffer.position = VGEO_HEADER_OFFSET.ASSET_ID + 8;
+
+    const asset_id_high = buffer.readUint64();
+
+    const block_count = vgeo_directory_block_count(total_pages);
+
+    for (let block = 0; block < block_count; block++) {
+        buffer.position = dir_block_checksums_offset + block * 8;
+
+        const stored_checksum = buffer.readUint64();
+
+        const computed = vgeo_compute_directory_block_checksum(
+            buffer, directory_offset, total_pages, block, asset_id_high
+        );
+
+        if (stored_checksum !== computed) {
+            out.push(new VGeoDefect(VGEO_DEFECT.CHECKSUM, `directory block ${block}: checksum is ${stored_checksum.toString(16)}, computed ${computed.toString(16)}`));
+        }
+    }
+}
+
+/**
+ * Audit a `.vgeo` file.
+ *
+ * @param {BinaryBuffer} buffer the whole file, with `capacity` equal to its length
+ * @returns {VGeoDefect[]} in discovery order; empty when the file satisfies every invariant
+ */
+export function vgeo_validate_container(buffer) {
+    const out = [];
+
+    if (!check_header(buffer, out)) {
+        return out;
+    }
+
+    buffer.position = VGEO_HEADER_OFFSET.LEVEL_COUNT;
+
+    const level_count = buffer.readUint8();
+
+    buffer.position = VGEO_HEADER_OFFSET.TOTAL_CLUSTERS;
+
+    const total_clusters = Number(buffer.readUint64());
+    const total_groups = Number(buffer.readUint64());
+
+    buffer.position = VGEO_HEADER_OFFSET.OBJECT_SPHERE;
+
+    const object_sphere = read_sphere(buffer);
+    const object_bounds = read_aabb(buffer);
+
+    check_hashes(buffer, out);
+
+    const frames = vgeo_scan_frames(buffer);
+
+    check_frames(buffer, frames, out);
+
+    /**
+     * @type {DecodedPage[]}
+     */
+    const pages = [];
+
+    for (const frame of frames) {
+        const page = decode_page(buffer, frame, level_count, out);
+
+        if (page === undefined) {
+            return out;
+        }
+
+        pages.push(page);
+    }
+
+    check_child_tables(buffer, frames, pages, out);
+    check_page_order(pages, level_count, out);
+
+    const page_groups = [];
+    const page_clusters = [];
+
+    let counted_clusters = 0;
+    let counted_groups = 0;
+
+    for (const page of pages) {
+        const groups = read_groups(page, out);
+        const clusters = read_clusters(page, out);
+
+        page_groups.push(groups);
+        page_clusters.push(clusters);
+
+        counted_groups += groups.length;
+        counted_clusters += clusters.length;
+
+        for (const cluster of clusters) {
+            check_cluster_record(page, cluster, object_sphere, object_bounds, out);
+        }
+    }
+
+    if (counted_clusters !== total_clusters) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `total_clusters is ${total_clusters}, the pages hold ${counted_clusters}`));
+    }
+
+    if (counted_groups !== total_groups) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `total_groups is ${total_groups}, the pages hold ${counted_groups}`));
+    }
+
+    check_page_nodes(pages, page_groups, page_clusters, out);
+
+    check_dag(pages, page_groups, page_clusters, level_count, out);
+    check_directory(buffer, frames, pages, out);
+
+    return out;
+}