@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js

@@ -3,13 +3,17 @@ import { VGEO_ATTRIBUTES } from "../attribute/VGEO_ATTRIBUTES.js";
 import { VGEO_CHILD_OFFSET } from "../frame/VGEO_CHILD_OFFSET.js";
 import { VGEO_CHILD_TABLE_ENTRY_SIZE } from "../frame/VGEO_CHILD_TABLE_ENTRY_SIZE.js";
 import { VGEO_CLUSTER_OFFSET } from "../cluster/VGEO_CLUSTER_OFFSET.js";
+import { VGEO_CLUSTER_OFFSET_V4 } from "../cluster/VGEO_CLUSTER_OFFSET_V4.js";
 import { VGEO_CLUSTER_RECORD_SIZE } from "../cluster/VGEO_CLUSTER_RECORD_SIZE.js";
+import { VGEO_CODEC_DEFLATE } from "../frame/VGEO_CODEC_DEFLATE.js";
 import { VGEO_CODEC_LZ4 } from "../frame/VGEO_CODEC_LZ4.js";
 import { VGEO_CODEC_RAW } from "../frame/VGEO_CODEC_RAW.js";
 import { vgeo_decode_frame_blob } from "../frame/vgeo_decode_frame_blob.js";
+import { VGEO_FORMAT_VERSION } from "../header/VGEO_FORMAT_VERSION.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_frame_decode_bound } from "../frame/vgeo_frame_decode_bound.js";
+import { VGEO_GROUP_OFFSET } from "../page/VGEO_GROUP_OFFSET.js";
 import { VGEO_GROUP_RECORD_SIZE } from "../page/VGEO_GROUP_RECORD_SIZE.js";
 import { VGEO_METRIC_OFFSET } from "../page/VGEO_METRIC_OFFSET.js";
 import { VGEO_NODE_OFFSET } from "../page/VGEO_NODE_OFFSET.js";
@@ -17,6 +21,7 @@ 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_PAGE_OFFSET_V5 } from "../page/VGEO_PAGE_OFFSET_V5.js";
 import { VGEO_PARENT_ENTRY_SIZE } from "../page/VGEO_PARENT_ENTRY_SIZE.js";
 import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "../page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
 import { vgeo_read_frame_extent } from "../frame/vgeo_read_frame_extent.js";
@@ -48,17 +53,27 @@ const NORMAL_COMPRESSION_FLAG = VGEO_ATTRIBUTES[VGEO_ATTRIBUTE.NORMAL].compressi
  * `decoded_size` is four bytes of untrusted file, and honouring one that no block of that length
  * could produce turns corruption into an out-of-memory throw rather than a rejected file.
  *
+ * It is asynchronous because {@link VGEO_CODEC_DEFLATE} is — the platform only offers its zlib as a
+ * stream — and a reader that could not read a deflate page would be refusing assets over an
+ * implementation detail. Everything after the decode is the same synchronous walk of the page's own
+ * tables it has always been, and a raw or LZ4 page never leaves the caller's turn.
+ *
  * @param {Uint8Array} frame_bytes the frame's exact range, from its first byte
  * @param {number} page_index the frame ordinal this range was fetched as — the caller knows it from
  *     the child-table entry or the directory record that named the range
- * @returns {VGeoPage}
+ * @param {number} [format_version] the container header's, which decides how a cluster record
+ *     (§7) and a page header (§6.1) are laid out: version 5 put `subtree_aabb` at offset 40 and
+ *     moved everything after it, and version 6 widened the page band to `u16` over
+ *     `node_table_offset`. Defaults to the current version, which is what a caller holding no
+ *     header should assume — the frame itself does not carry one.
+ * @returns {Promise<VGeoPage>}
  * @throws {Error} when the range is not a frame, uses a codec with no decoder here, or does not
  *     decode as its own header says
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_read_page(frame_bytes, page_index) {
+export async function vgeo_read_page(frame_bytes, page_index, format_version = VGEO_FORMAT_VERSION) {
     const frame_view = new DataView(
         frame_bytes.buffer, frame_bytes.byteOffset, frame_bytes.byteLength
     );
@@ -88,10 +103,15 @@ export function vgeo_read_page(frame_bytes, page_index) {
     // decoder indexes `frame_bytes` with, and the caller keeps the absolute one.
     const frame = vgeo_read_frame_extent(frame_view, 0, page_index);
 
-    if (frame.codec !== VGEO_CODEC_RAW && frame.codec !== VGEO_CODEC_LZ4) {
+    if (
+        frame.codec !== VGEO_CODEC_RAW
+        && frame.codec !== VGEO_CODEC_LZ4
+        && frame.codec !== VGEO_CODEC_DEFLATE
+    ) {
         throw new Error(
             `page ${page_index} uses codec ${frame.codec};`
-            + ` this reader decodes ${VGEO_CODEC_RAW} (raw) and ${VGEO_CODEC_LZ4} (lz4)`
+            + ` this reader decodes ${VGEO_CODEC_RAW} (raw), ${VGEO_CODEC_LZ4} (lz4)`
+            + ` and ${VGEO_CODEC_DEFLATE} (deflate)`
         );
     }
 
@@ -119,16 +139,25 @@ export function vgeo_read_page(frame_bytes, page_index) {
 
     const bytes = new Uint8Array(frame.decoded_size);
 
-    vgeo_decode_frame_blob(bytes, 0, frame_bytes, frame);
+    await vgeo_decode_frame_blob(bytes, 0, frame_bytes, frame);
 
     result.bytes = bytes;
     result.data = new DataView(bytes.buffer);
 
+    /*
+     Version 6 widened `min_level` and `max_level` to `u16` and spent `node_table_offset` on the
+     four bytes, so the page header's fields at offsets 4..8 and 20..24 mean different things either
+     side of it. Everything else in a page — the group table's base, the other table offsets, the
+     parent section, the metric — is where it always was, which is why only these two readers take
+     the flag.
+    */
+    const legacy_page = format_version < 6;
+
     read_child_table(result, frame_view, frame);
-    read_page_header(result);
+    read_page_header(result, legacy_page);
     read_group_table(result);
-    read_node_table(result);
-    read_cluster_table(result);
+    read_node_table(result, legacy_page);
+    read_cluster_table(result, format_version);
     read_parent_tables(result);
 
     return result;
@@ -210,13 +239,23 @@ function read_child_table(page, frame_view, frame) {
  * past.
  *
  * @param {VGeoPage} page
+ * @param {boolean} legacy the container is `format_version` 5 or older
  */
-function read_node_table(page) {
+function read_node_table(page, legacy) {
     const data = page.data;
 
     const count = page.node_count;
 
-    const table = data.getUint32(VGEO_PAGE_OFFSET.NODE_TABLE_OFFSET, LE);
+    /*
+     Stored through version 5, derived from 6 on, and the same number either way: the group table
+     follows the page header and the node table follows the group table, both by construction
+     (§6.1). What stands between a `group_count` that is wrong and a read past the page is the
+     extent check below, and that stood there when the offset was stored too.
+    */
+    const table = legacy
+        ? data.getUint32(VGEO_PAGE_OFFSET_V5.NODE_TABLE_OFFSET, LE)
+        : VGEO_PAGE_HEADER_SIZE
+            + data.getUint16(VGEO_PAGE_OFFSET.GROUP_COUNT, LE) * VGEO_GROUP_RECORD_SIZE;
 
     const end = table + count * VGEO_NODE_RECORD_SIZE;
 
@@ -263,8 +302,9 @@ function read_node_table(page) {
 
 /**
  * @param {VGeoPage} page
+ * @param {boolean} legacy the container is `format_version` 5 or older
  */
-function read_page_header(page) {
+function read_page_header(page, legacy) {
     const data = page.data;
 
     if (page.bytes.byteLength < VGEO_PAGE_HEADER_SIZE) {
@@ -275,9 +315,17 @@ function read_page_header(page) {
     }
 
     page.cluster_count = data.getUint16(VGEO_PAGE_OFFSET.CLUSTER_COUNT, LE);
-    page.min_level = data.getUint8(VGEO_PAGE_OFFSET.MIN_LEVEL);
-    page.max_level = data.getUint8(VGEO_PAGE_OFFSET.MAX_LEVEL);
-    page.node_count = data.getUint16(VGEO_PAGE_OFFSET.NODE_COUNT, LE);
+
+    if (legacy) {
+        page.min_level = data.getUint8(VGEO_PAGE_OFFSET_V5.MIN_LEVEL);
+        page.max_level = data.getUint8(VGEO_PAGE_OFFSET_V5.MAX_LEVEL);
+        page.node_count = data.getUint16(VGEO_PAGE_OFFSET_V5.NODE_COUNT, LE);
+    } else {
+        page.min_level = data.getUint16(VGEO_PAGE_OFFSET.MIN_LEVEL, LE);
+        page.max_level = data.getUint16(VGEO_PAGE_OFFSET.MAX_LEVEL, LE);
+        page.node_count = data.getUint16(VGEO_PAGE_OFFSET.NODE_COUNT, LE);
+    }
+
     page.payload_offset = data.getUint32(VGEO_PAGE_OFFSET.PAYLOAD_OFFSET, LE);
     page.payload_size = data.getUint32(VGEO_PAGE_OFFSET.PAYLOAD_SIZE, LE);
 }
@@ -298,10 +346,14 @@ function read_group_table(page) {
     for (let i = 0; i < count; i++) {
         const record = VGEO_PAGE_HEADER_SIZE + i * VGEO_GROUP_RECORD_SIZE;
 
-        page.group_cluster_first[i] = data.getUint16(record, LE);
-        page.group_cluster_count[i] = data.getUint16(record + 2, LE);
-        page.group_parent_count[i] = data.getUint16(record + 4, LE);
-        page.group_parent_first[i] = data.getUint16(record + 6, LE);
+        page.group_cluster_first[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.CLUSTER_FIRST, LE);
+        page.group_cluster_count[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.CLUSTER_COUNT, LE);
+        page.group_parent_count[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.PARENT_CLUSTER_COUNT, LE);
+        page.group_parent_first[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.PARENT_FIRST, LE);
     }
 }
 
@@ -357,10 +409,21 @@ function read_parent_tables(page) {
 
 /**
  * @param {VGeoPage} page
+ * @param {number} format_version of the container this page came out of
  */
-function read_cluster_table(page) {
+function read_cluster_table(page, format_version) {
     const data = page.data;
 
+    /*
+     Version 5 replaced `bounds_sphere` and `cone_reserved` with `subtree_aabb`, which moved every
+     field from offset 40 on, so reading an older record by the current offsets does not lose a
+     field — it takes `child_ref` out of the middle of a box. The fifty gigabytes of converted
+     version-4 containers are why this branch exists rather than a refusal.
+    */
+    const legacy = format_version < 5;
+
+    const offsets = legacy ? VGEO_CLUSTER_OFFSET_V4 : VGEO_CLUSTER_OFFSET;
+
     const count = page.cluster_count;
 
     const table = data.getUint32(VGEO_PAGE_OFFSET.CLUSTER_TABLE_OFFSET, LE);
@@ -376,7 +439,7 @@ function read_cluster_table(page) {
 
     page.self_sphere = new Float32Array(count * 4);
     page.parent_sphere = new Float32Array(count * 4);
-    page.bounds_sphere = new Float32Array(count * 4);
+    page.subtree_aabb = new Float32Array(count * 6);
     page.aabb = new Float32Array(count * 6);
     page.self_error = new Float32Array(count);
     page.parent_error = new Float32Array(count);
@@ -394,29 +457,49 @@ function read_cluster_table(page) {
 
         for (let c = 0; c < 4; c++) {
             page.self_sphere[i * 4 + c] =
-                data.getFloat32(record + VGEO_CLUSTER_OFFSET.SELF_SPHERE + c * 4, LE);
+                data.getFloat32(record + offsets.SELF_SPHERE + c * 4, LE);
             page.parent_sphere[i * 4 + c] =
-                data.getFloat32(record + VGEO_CLUSTER_OFFSET.PARENT_SPHERE + c * 4, LE);
-            page.bounds_sphere[i * 4 + c] =
-                data.getFloat32(record + VGEO_CLUSTER_OFFSET.BOUNDS_SPHERE + c * 4, LE);
+                data.getFloat32(record + offsets.PARENT_SPHERE + c * 4, LE);
         }
 
         for (let c = 0; c < 6; c++) {
-            page.aabb[i * 6 + c] =
-                data.getFloat32(record + VGEO_CLUSTER_OFFSET.AABB + c * 4, LE);
+            page.aabb[i * 6 + c] = data.getFloat32(record + offsets.AABB + c * 4, LE);
+        }
+
+        if (legacy) {
+            /*
+             The cube around `self_sphere`, which format §11.7 makes contain every vertex below the
+             cluster — so it is a conservative subtree bound, which is the whole of what the cut's
+             test asks of this column. It is looser than the box a version-5 build computes, and
+             looser in exactly the way the sphere the kernel also tests already is.
+            */
+            const cx = page.self_sphere[i * 4];
+            const cy = page.self_sphere[i * 4 + 1];
+            const cz = page.self_sphere[i * 4 + 2];
+            const r = page.self_sphere[i * 4 + 3];
+
+            page.subtree_aabb[i * 6] = cx - r;
+            page.subtree_aabb[i * 6 + 1] = cy - r;
+            page.subtree_aabb[i * 6 + 2] = cz - r;
+            page.subtree_aabb[i * 6 + 3] = cx + r;
+            page.subtree_aabb[i * 6 + 4] = cy + r;
+            page.subtree_aabb[i * 6 + 5] = cz + r;
+        } else {
+            for (let c = 0; c < 6; c++) {
+                page.subtree_aabb[i * 6 + c] =
+                    data.getFloat32(record + offsets.SUBTREE_AABB + c * 4, LE);
+            }
         }
 
-        page.self_error[i] = data.getFloat32(record + VGEO_CLUSTER_OFFSET.SELF_ERROR, LE);
-        page.parent_error[i] = data.getFloat32(record + VGEO_CLUSTER_OFFSET.PARENT_ERROR, LE);
-        page.child_ref[i] = data.getUint16(record + VGEO_CLUSTER_OFFSET.CHILD_REF, LE);
-        page.child_group[i] = data.getUint16(record + VGEO_CLUSTER_OFFSET.CHILD_GROUP, LE);
-        page.encoding_flags[i] = data.getUint32(record + VGEO_CLUSTER_OFFSET.ENCODING_FLAGS, LE);
-        page.cluster_payload_offset[i] =
-            data.getUint32(record + VGEO_CLUSTER_OFFSET.PAYLOAD_OFFSET, LE);
-        page.cluster_payload_size[i] =
-            data.getUint32(record + VGEO_CLUSTER_OFFSET.PAYLOAD_SIZE, LE);
-        page.vertex_count[i] = data.getUint8(record + VGEO_CLUSTER_OFFSET.VERTEX_COUNT);
-        page.triangle_count[i] = data.getUint8(record + VGEO_CLUSTER_OFFSET.TRIANGLE_COUNT);
+        page.self_error[i] = data.getFloat32(record + offsets.SELF_ERROR, LE);
+        page.parent_error[i] = data.getFloat32(record + offsets.PARENT_ERROR, LE);
+        page.child_ref[i] = data.getUint16(record + offsets.CHILD_REF, LE);
+        page.child_group[i] = data.getUint16(record + offsets.CHILD_GROUP, LE);
+        page.encoding_flags[i] = data.getUint32(record + offsets.ENCODING_FLAGS, LE);
+        page.cluster_payload_offset[i] = data.getUint32(record + offsets.PAYLOAD_OFFSET, LE);
+        page.cluster_payload_size[i] = data.getUint32(record + offsets.PAYLOAD_SIZE, LE);
+        page.vertex_count[i] = data.getUint8(record + offsets.VERTEX_COUNT);
+        page.triangle_count[i] = data.getUint8(record + offsets.TRIANGLE_COUNT);
 
         if ((page.encoding_flags[i] & NORMAL_COMPRESSION_FLAG) === 0) {
             page.per_vertex_normal_cluster_count++;

package/src/shade/renderer/geometry/virtual/format/vgeo_validate_container.d.ts

@@ -1,10 +1,14 @@
 /**
  * Audit a `.vgeo` file.
  *
+ * It is asynchronous for the one reason the reader is: {@link VGEO_CODEC_DEFLATE} decodes through
+ * the platform's streaming zlib, and a validator that could not decode a deflate page would pass
+ * every file it could not read.
+ *
  * @param {BinaryBuffer} buffer the whole file, with `capacity` equal to its length
- * @returns {VGeoDefect[]} in discovery order; empty when the file satisfies every invariant
+ * @returns {Promise<VGeoDefect[]>} in discovery order; empty when the file satisfies every invariant
  */
-export function vgeo_validate_container(buffer: BinaryBuffer): VGeoDefect[];
+export function vgeo_validate_container(buffer: BinaryBuffer): Promise<VGeoDefect[]>;
 import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
 import { VGeoDefect } from "./VGeoDefect.js";
 //# sourceMappingURL=vgeo_validate_container.d.ts.map

package/src/shade/renderer/geometry/virtual/format/vgeo_validate_container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AAgtDA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAqFxB;6BAzyD4B,4CAA4C;2BAkD9C,iBAAiB"}
+{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AA+xDA;;;;;;;;;GASG;AACH,gDAHW,YAAY,GACV,QAAQ,UAAU,EAAE,CAAC,CAqFjC;6BA53D4B,4CAA4C;2BAoD9C,iBAAiB"}

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

@@ -2,6 +2,7 @@ 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_DEFLATE } from "./frame/VGEO_CODEC_DEFLATE.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";
@@ -20,6 +21,7 @@ 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_OFFSET } from "./page/VGEO_GROUP_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";
@@ -241,9 +243,16 @@ function check_header(buffer, out) {
     const format_version = buffer.readUint16();
 
     if (format_version !== VGEO_FORMAT_VERSION) {
+        /*
+         Fatal rather than one defect among many. Record layouts move between versions — 5 put
+         `subtree_aabb` where `bounds_sphere` was and shifted everything after it — so reading on
+         would decode every cluster of another version's file by this version's sequence and report
+         a page's worth of invented defects about fields that are not there. The reader keeps the
+         older layouts; this does not.
+        */
         out.push(new VGeoDefect(VGEO_DEFECT.HEADER, `format_version is ${format_version}, this validator knows ${VGEO_FORMAT_VERSION}`));
 
-        usable = false;
+        return false;
     }
 
     const min_reader_version = buffer.readUint16();
@@ -352,7 +361,7 @@ function check_header(buffer, out) {
         out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'reserved u16 at 100 is not zero'));
     }
 
-    const level_count = buffer.readUint8();
+    const level_count = buffer.readUint16();
 
     if (level_count < 1) {
         out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'level_count is 0'));
@@ -372,10 +381,9 @@ function check_header(buffer, out) {
         usable = false;
     }
 
-    if (buffer.readUint8() !== 0) {
-        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'reserved byte at 103 is not zero'));
-    }
-
+    // Byte 103 was reserved through `format_version` 5 and is `level_count`'s high byte from 6 on,
+    // so there is nothing left to check between it and `source_vertex_count`; the read above landed
+    // at 104 and the one below expects to start there.
     const source_vertex_count = Number(buffer.readUint64());
 
     if (source_vertex_count < 3) {
@@ -502,10 +510,12 @@ function check_frames(buffer, frames, out) {
             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;
+        const decodable = frame.codec === VGEO_CODEC_RAW
+            || frame.codec === VGEO_CODEC_LZ4
+            || frame.codec === VGEO_CODEC_DEFLATE;
 
         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)`));
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: codec is ${frame.codec}, this validator knows ${VGEO_CODEC_RAW} (raw), ${VGEO_CODEC_LZ4} (lz4) and ${VGEO_CODEC_DEFLATE} (deflate)`));
         }
 
         if (frame.flags !== 0) {
@@ -570,9 +580,9 @@ function check_frames(buffer, frames, out) {
  * @param {VGeoFrameExtent} frame
  * @param {number} level_count
  * @param {VGeoDefect[]} out
- * @returns {DecodedPage|undefined} `undefined` when the page is too malformed to read further
+ * @returns {Promise<DecodedPage|undefined>} `undefined` when the page is too malformed to read further
  */
-function decode_page(buffer, frame, level_count, out) {
+async function decode_page(buffer, frame, level_count, out) {
     const page = new DecodedPage();
 
     page.page_index = frame.page_index;
@@ -599,7 +609,7 @@ function decode_page(buffer, frame, level_count, out) {
 
         page.buffer = buffer;
         page.base = blob;
-    } else if (frame.codec === VGEO_CODEC_LZ4) {
+    } else if (frame.codec === VGEO_CODEC_LZ4 || frame.codec === VGEO_CODEC_DEFLATE) {
         // 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)) {
@@ -612,7 +622,7 @@ function decode_page(buffer, frame, level_count, out) {
         page.buffer.setCapacity(frame.decoded_size);
 
         try {
-            vgeo_decode_frame_blob(page.buffer.raw_bytes, 0, buffer.raw_bytes, frame);
+            await 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
@@ -640,15 +650,17 @@ function decode_page(buffer, frame, level_count, out) {
 
     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.min_level = decoded.readUint16();
+    page.max_level = decoded.readUint16();
 
     page.cluster_table_offset = decoded.readUint32();
     page.payload_offset = decoded.readUint32();
     page.payload_size = decoded.readUint32();
-    page.node_table_offset = decoded.readUint32();
+
+    page.node_count = decoded.readUint16();
+
+    // What `node_table_offset` occupied through version 5, kept zero rather than reused (§11.10).
+    const node_reserved = decoded.readUint16();
 
     page.parent_table_offset = decoded.readUint32();
     page.parent_entry_count = decoded.readUint16();
@@ -670,6 +682,10 @@ function decode_page(buffer, frame, level_count, out) {
         return undefined;
     }
 
+    if (node_reserved !== 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: the reserved u16 at ${VGEO_PAGE_OFFSET.NODE_COUNT + 2} of the page header is ${node_reserved}, not zero`));
+    }
+
     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}`));
     }
@@ -686,13 +702,14 @@ function decode_page(buffer, frame, level_count, out) {
         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;
-    }
+    /*
+     Derived rather than read: the page header has carried no such field since `format_version` 6,
+     and it never carried anything else — the group table follows the header and the node table
+     follows the group table. The cross-check the stored copy used to provide has not been lost with
+     it, because `cluster_table_offset` *is* stored and can only agree one line down if
+     `group_count` and `node_count` both do.
+    */
+    page.node_table_offset = VGEO_PAGE_HEADER_SIZE + page.group_count * VGEO_GROUP_RECORD_SIZE;
 
     const expected_cluster_table_offset = page.node_table_offset
         + page.node_count * VGEO_NODE_RECORD_SIZE;
@@ -1071,13 +1088,25 @@ function read_groups(page, out) {
     let expected_parent_first = 0;
 
     for (let g = 0; g < page.group_count; g++) {
-        page.seek(VGEO_PAGE_HEADER_SIZE + g * VGEO_GROUP_RECORD_SIZE);
+        const record = VGEO_PAGE_HEADER_SIZE + g * VGEO_GROUP_RECORD_SIZE;
+
+        /**
+         * Each field is sought to by name rather than read in a run, so that this audit and
+         * `vgeo_read_page` address the record through the same table — a validator that agreed
+         * with the reader only by having been written in the same order is a validator that stops
+         * agreeing the first time a field moves.
+         */
+        const read = (field) => {
+            page.seek(record + field);
+
+            return buffer.readUint16();
+        };
 
         const group = {
-            cluster_first: buffer.readUint16(),
-            cluster_count: buffer.readUint16(),
-            parent_cluster_count: buffer.readUint16(),
-            parent_first: buffer.readUint16(),
+            cluster_first: read(VGEO_GROUP_OFFSET.CLUSTER_FIRST),
+            cluster_count: read(VGEO_GROUP_OFFSET.CLUSTER_COUNT),
+            parent_cluster_count: read(VGEO_GROUP_OFFSET.PARENT_CLUSTER_COUNT),
+            parent_first: read(VGEO_GROUP_OFFSET.PARENT_FIRST),
         };
 
         if (group.cluster_count < 1 || group.cluster_count > VGEO_MAX_GROUP_CLUSTER_COUNT) {
@@ -1285,11 +1314,10 @@ function read_clusters(page, out) {
             self_error: buffer.readFloat32(),
             parent_error: buffer.readFloat32(),
             parent_sphere: read_sphere(buffer),
-            bounds_sphere: read_sphere(buffer),
+            subtree_aabb: read_aabb(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(),
@@ -1297,14 +1325,12 @@ function read_clusters(page, out) {
             triangle_count: buffer.readUint8(),
         };
 
-        if (buffer.readUint16() !== 0 || buffer.readUint64() !== 0n) {
+        // six bytes at 106; `cone_reserved` and the four bytes that followed the record's counts
+        // went into `subtree_aabb` when format_version moved to 5
+        if (buffer.readUint16() !== 0 || buffer.readUint32() !== 0) {
             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);
     }
 
@@ -1375,7 +1401,6 @@ function check_cluster_record(page, cluster, object_sphere, object_bounds, out)
     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) {
@@ -1384,8 +1409,26 @@ function check_cluster_record(page, cluster, object_sphere, object_bounds, out)
         }
     }
 
-    if (!cluster.aabb.every(Number.isFinite)) {
-        out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: aabb is not finite`));
+    for (const [name, box] of [['aabb', cluster.aabb], ['subtree_aabb', cluster.subtree_aabb]]) {
+        if (!box.every(Number.isFinite)) {
+            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: ${name} is not finite`));
+        }
+    }
+
+    /*
+     The cut culls a cluster — and with it every cluster reachable below it, because the child group
+     is only ever entered through this one — on `subtree_aabb`, so it must contain this cluster's own
+     box before §11.17's cross-page half checks it contains the child group's boxes. Exact, on the
+     stored values: the builder unions float32 extremes and a union of representable numbers is
+     representable, so there is nothing here for a tolerance to absorb.
+    */
+    for (let axis = 0; axis < 3; axis++) {
+        if (cluster.subtree_aabb[axis] > cluster.aabb[axis]
+            || cluster.subtree_aabb[axis + 3] < cluster.aabb[axis + 3]) {
+            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: subtree_aabb does not contain the cluster's own aabb on axis ${axis}`));
+
+            break;
+        }
     }
 
     if (!Number.isFinite(cluster.self_error) || cluster.self_error < 0) {
@@ -1417,8 +1460,22 @@ function check_cluster_record(page, cluster, object_sphere, object_bounds, out)
             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}`));
+        /*
+         §11.7. The cut's first per-cluster frustum test is on `self_sphere`, and a reader meeting a
+         container written before `subtree_aabb` existed stands this sphere's cube in for that box —
+         both are conservative only because the sphere holds the cluster's own vertices, and by
+         monotonicity every vertex below it. The builder has always made it so and nothing checked
+         it; what used to be checked here was `bounds_sphere`, which the record no longer carries.
+        */
+        if (!sphere_contains_point(cluster.self_sphere, x, y, z)) {
+            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: self_sphere does not contain vertex ${v}`));
+
+            break;
+        }
+
+        if (x < cluster.subtree_aabb[0] || y < cluster.subtree_aabb[1] || z < cluster.subtree_aabb[2]
+            || x > cluster.subtree_aabb[3] || y > cluster.subtree_aabb[4] || z > cluster.subtree_aabb[5]) {
+            out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: subtree_aabb does not contain vertex ${v}`));
 
             break;
         }
@@ -1553,6 +1610,28 @@ function check_dag(pages, page_groups, page_clusters, level_count, out) {
 
                     break;
                 }
+
+                /*
+                 §11.17, the half no single record can settle. The runtime culls this cluster and
+                 everything under it on its `subtree_aabb`, and what is under it is exactly this
+                 child group — so a box that does not contain a child's box is a hole the size of
+                 that child's whole subtree, inside the frustum, with nothing left standing in over
+                 it. Exact, like the containment above it.
+                */
+                let escapes = -1;
+
+                for (let axis = 0; axis < 3 && escapes < 0; axis++) {
+                    if (child.subtree_aabb[axis] < cluster.subtree_aabb[axis]
+                        || child.subtree_aabb[axis + 3] > cluster.subtree_aabb[axis + 3]) {
+                        escapes = axis;
+                    }
+                }
+
+                if (escapes >= 0) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.METRIC, `${where}: subtree_aabb does not contain the subtree_aabb of cluster ${child.index} of the group it refines into, on axis ${escapes}`));
+
+                    break;
+                }
             }
         }
     }
@@ -1701,8 +1780,8 @@ function check_directory(buffer, frames, pages, out) {
             continue;
         }
 
-        reconstructed.writeUint8(page.min_level);
-        reconstructed.writeUint8(page.max_level);
+        reconstructed.writeUint16(page.min_level);
+        reconstructed.writeUint16(page.max_level);
         reconstructed.writeUint16(i === 0 ? VGEO_DIRECTORY_FLAG_ROOT_PAGE : 0);
         reconstructed.writeUint16(page.group_count);
         reconstructed.writeUint16(page.cluster_count);
@@ -1745,10 +1824,14 @@ function check_directory(buffer, frames, pages, out) {
 /**
  * Audit a `.vgeo` file.
  *
+ * It is asynchronous for the one reason the reader is: {@link VGEO_CODEC_DEFLATE} decodes through
+ * the platform's streaming zlib, and a validator that could not decode a deflate page would pass
+ * every file it could not read.
+ *
  * @param {BinaryBuffer} buffer the whole file, with `capacity` equal to its length
- * @returns {VGeoDefect[]} in discovery order; empty when the file satisfies every invariant
+ * @returns {Promise<VGeoDefect[]>} in discovery order; empty when the file satisfies every invariant
  */
-export function vgeo_validate_container(buffer) {
+export async function vgeo_validate_container(buffer) {
     const out = [];
 
     if (!check_header(buffer, out)) {
@@ -1757,7 +1840,7 @@ export function vgeo_validate_container(buffer) {
 
     buffer.position = VGEO_HEADER_OFFSET.LEVEL_COUNT;
 
-    const level_count = buffer.readUint8();
+    const level_count = buffer.readUint16();
 
     buffer.position = VGEO_HEADER_OFFSET.TOTAL_CLUSTERS;
 
@@ -1781,7 +1864,7 @@ export function vgeo_validate_container(buffer) {
     const pages = [];
 
     for (const frame of frames) {
-        const page = decode_page(buffer, frame, level_count, out);
+        const page = await decode_page(buffer, frame, level_count, out);
 
         if (page === undefined) {
             return out;