@woosh/meep-engine 3.20.0 → 3.22.0

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

@@ -0,0 +1,917 @@
+import { assert } from "../../../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../../../core/binary/BinaryBuffer.js";
+import { vgeo_compute_frame_checksum } from "../checksum/vgeo_compute_frame_checksum.js";
+import { VGEO_NO_CHILD } from "../cluster/VGEO_NO_CHILD.js";
+import { VGEO_SAME_PAGE } from "../cluster/VGEO_SAME_PAGE.js";
+import { VGEO_FRAME_OFFSET } from "../frame/VGEO_FRAME_OFFSET.js";
+import { vgeo_read_frame_extent } from "../frame/vgeo_read_frame_extent.js";
+import { vgeo_validate_container } from "../vgeo_validate_container.js";
+import { VGeoReadOptions } from "./VGeoReadOptions.js";
+import { vgeo_read_directory } from "./vgeo_read_directory.js";
+import { vgeo_read_header, vgeo_resident_head_size, VGEO_MIN_HEAD_BYTES } from "./vgeo_read_header.js";
+import { vgeo_read_page } from "./vgeo_read_page.js";
+
+/**
+ * Everything in the container is little-endian (`VGEO_FORMAT.md` §2).
+ * @type {boolean}
+ */
+const LE = true;
+
+/**
+ * A `.vgeo` container, read a page at a time.
+ *
+ * **Nothing here ever holds the whole file.** Opening it reads a head prefix — the header, the level
+ * table, and the root frame, which §10 calls the always-resident set — and after that a page arrives
+ * only when something asks for it, from exactly the byte range the page pointing at it wrote down.
+ * That is not an optimization bolted onto a whole-file reader; it is the shape the format was
+ * designed for, and a reader built the other way cannot be made into this one.
+ *
+ * What that buys, concretely: a 27-million-triangle asset opens in the bytes of its root page, and a
+ * view of it costs the pages that view actually selects. What it costs is that a traversal has to
+ * cope with a page it wants and does not have — which the format also already answers, because the
+ * clamped cut is watertight and correct at every arrival order (§10, activation).
+ *
+ * Residency is this object. {@link page} answers for what is here, {@link install_want} brings one
+ * more, {@link evict} drops one, and a {@link VGeoPage} owns its own bytes and tables so that
+ * dropping it drops everything it cost.
+ *
+ * **Selectability is the other half of it, and it is not the same question.** {@link is_selectable}
+ * answers §10's activation invariant — whether a group's *entire ancestor cone* is here, not merely
+ * its own bytes — held as one counter per resident group. A traversal that clamps on residency
+ * instead refines into a group through the parents that arrived while a coarse cluster still stands
+ * in for one that did not, and draws both over the same surface. That is what activation is for, and
+ * it is why installing a page does bookkeeping rather than only filling a map.
+ *
+ * **Validation is not on this path.** The mandatory reject rules of §4 and §10 are applied
+ * unconditionally by {@link vgeo_read_header} and {@link vgeo_read_page} — a file whose magic,
+ * versions, encoding or codec this build does not understand is refused rather than misread. The
+ * whole-file audit is {@link validate}, it reads every byte of the file, and it is off by default;
+ * see {@link VGeoReadOptions.validate}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoContainerReader {
+    /**
+     * @type {VGeoContainerHeader}
+     */
+    header = undefined;
+
+    /**
+     * The page directory, once {@link read_directory} has been asked for it. A traversal never needs
+     * it; a tool looking at every page does.
+     * @type {VGeoDirectory|undefined}
+     */
+    directory = undefined;
+
+    /**
+     * @type {VGeoByteSource}
+     */
+    #source;
+
+    /**
+     * @type {VGeoReadOptions}
+     */
+    #options;
+
+    /**
+     * Resident pages, by page index.
+     * @type {Map<number, VGeoPage>}
+     */
+    #pages = new Map();
+
+    /**
+     * Fetches in flight, by page index — so that two clusters wanting the same page produce one
+     * request. Wants dedup on page index across clusters, groups and instances (§10), and this is
+     * where that happens for the ones already on the wire.
+     * @type {Map<number, Promise<VGeoPage>>}
+     */
+    #pending = new Map();
+
+    /**
+     * The speculative head prefix, kept.
+     *
+     * Coarse-first layout is what makes this worth keeping rather than parsing and dropping: a
+     * prefix that overshot the root frame overshot into the pages the traversal is most likely to
+     * want next, and serving those from here costs no request at all.
+     *
+     * @type {Uint8Array}
+     */
+    #head = new Uint8Array(0);
+
+    /**
+     * @type {number}
+     */
+    #resident_bytes = 0;
+
+    /**
+     * Live references into each resident page's groups, one counter per group.
+     *
+     * §10's activation counter. A reference is live when the cluster making it sits in an installed
+     * page *and* in a group that is itself selectable, so the counter reaching a group's
+     * `parent_cluster_count` means its entire ancestor cone is here — which is the closure the cut
+     * rule needs, held as one number per group instead of a dependency list.
+     *
+     * @type {Map<number, Uint16Array>}
+     */
+    #live_refs = new Map();
+
+    /**
+     * Which groups of each resident page are selectable, one byte per group.
+     *
+     * Derived from {@link #live_refs} and flipped by {@link #cascade_activate}, not recomputed: a
+     * traversal reads this per cluster and residency changes far less often than a frame does.
+     *
+     * @type {Map<number, Uint8Array>}
+     */
+    #selectable = new Map();
+
+    /**
+     * Live references made *into pages that are not here yet*, by page index and then by group.
+     *
+     * The reverse-reference index §10 asks for. A page cannot be told about a reference into it
+     * before it exists, and recomputing the whole closure on every install would make activation
+     * cost the resident set rather than the arrival — so the references wait here, and installing
+     * the page starts its counters from the truth. Evicting a page moves its counters back here for
+     * the same reason: the parents making those references are still resident and still selectable.
+     *
+     * @type {Map<number, Map<number, number>>}
+     */
+    #pending_refs = new Map();
+
+    /**
+     * @param {VGeoByteSource} source
+     * @param {VGeoReadOptions} [options]
+     */
+    constructor(source, options = new VGeoReadOptions()) {
+        assert.defined(source, 'source');
+
+        this.#source = source;
+        this.#options = options;
+    }
+
+    /**
+     * @returns {VGeoByteSource}
+     */
+    get source() {
+        return this.#source;
+    }
+
+    /**
+     * @returns {VGeoReadOptions}
+     */
+    get options() {
+        return this.#options;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get resident_page_count() {
+        return this.#pages.size;
+    }
+
+    /**
+     * Decoded bytes currently held. The number a residency budget is spent against.
+     * @returns {number}
+     */
+    get resident_bytes() {
+        return this.#resident_bytes;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get pending_page_count() {
+        return this.#pending.size;
+    }
+
+    /**
+     * The root page, which is pinned for the life of the reader — §10 makes it the one page that is
+     * never evictable, because every traversal starts by walking its parentless groups.
+     * @returns {VGeoPage}
+     */
+    get root() {
+        return this.#pages.get(0);
+    }
+
+    /**
+     * Every resident page, in page-index order.
+     * @returns {VGeoPage[]}
+     */
+    get pages() {
+        return Array.from(this.#pages.values()).sort((a, b) => a.index - b.index);
+    }
+
+    /**
+     * Open a container: header, level table, root page.
+     *
+     * @param {VGeoByteSource} source
+     * @param {VGeoReadOptions} [options]
+     * @returns {Promise<VGeoContainerReader>}
+     * @throws {Error} when the bytes are not a `.vgeo` this build reads, or the root frame does not
+     *     match what the header says about it
+     */
+    static async open(source, options = new VGeoReadOptions()) {
+        const reader = new VGeoContainerReader(source, options);
+
+        await reader.#open();
+
+        return reader;
+    }
+
+    /**
+     * @returns {Promise<void>}
+     */
+    async #open() {
+        const source = this.#source;
+
+        if (source.byte_length < VGEO_MIN_HEAD_BYTES) {
+            throw new Error(
+                `${source.name} is ${source.byte_length} bytes, shorter than a .vgeo header`
+            );
+        }
+
+        const prefix = Math.min(
+            source.byte_length,
+            Math.max(this.#options.head_prefix_bytes, VGEO_MIN_HEAD_BYTES)
+        );
+
+        this.#head = await source.read(0, prefix);
+
+        /*
+         §10's always-resident set: the header, the level table, and the root frame — in that order,
+         contiguously, and bounded by two fields of the fixed header. Whatever the prefix already
+         covered, one range brings the rest, so a cold start is two requests at worst and one
+         whenever the prefix was generous. Nothing is fetched twice: the head only grows at its tail.
+        */
+        await this.#grow_head(vgeo_resident_head_size(this.#head));
+
+        this.header = vgeo_read_header(this.#head);
+
+        await this.#install_root();
+
+        if (this.#options.validate) {
+            await this.validate();
+        }
+    }
+
+    /**
+     * Install page 0, checking it against what the header promised — §10's cold-start rule.
+     *
+     * @returns {Promise<void>}
+     */
+    async #install_root() {
+        const header = this.header;
+
+        const root = await this.install(
+            0, header.root_page_offset, header.root_page_fetch_size
+        );
+
+        /*
+         Both of these are §10 reject rules rather than validation: the header states the root's
+         extent and decoded size so that a reader can admit RAM and size a fetch before it has seen
+         the frame, and a root frame that disagrees means one of the two numbers is wrong. Which one
+         is unknowable from here, and reading on under either is how a reader ends up trusting a
+         number it has already caught lying.
+         */
+        if (root.decoded_size !== header.root_page_decoded_size) {
+            throw new Error(
+                `the root frame decodes to ${root.decoded_size} bytes and the header says`
+                + ` ${header.root_page_decoded_size}`
+            );
+        }
+
+        if (root.fetch_size !== header.root_page_fetch_size) {
+            throw new Error(
+                `the root frame occupies ${root.fetch_size} bytes and the header says`
+                + ` ${header.root_page_fetch_size}`
+            );
+        }
+    }
+
+    /**
+     * The page, if it is here.
+     *
+     * Synchronous and total: a traversal asks this per cluster and must not await inside itself, so
+     * `undefined` is an answer it acts on — clamp, and record a want — rather than a case to handle.
+     *
+     * @param {number} page_index
+     * @returns {VGeoPage|undefined}
+     */
+    page(page_index) {
+        return this.#pages.get(page_index);
+    }
+
+    /**
+     * @param {number} page_index
+     * @returns {boolean}
+     */
+    is_resident(page_index) {
+        return this.#pages.has(page_index);
+    }
+
+    /**
+     * Whether a group may be selected from — §10's activation invariant, and **not** the same
+     * question as {@link is_resident}.
+     *
+     * A group is selectable iff every one of its `parent_cluster_count` references is live: the
+     * referencing cluster's page is installed and that cluster's own group is selectable. Groups
+     * with no parents at all — exactly the root page's topmost level — are selectable the moment
+     * their page is.
+     *
+     * The distinction is load-bearing and it is invisible until an asset is big enough to put one
+     * group's parents in two pages. Refining into a group whose page merely *arrived* draws it
+     * underneath the coarse cluster still standing in for the parent that did not, and the two
+     * surfaces fight over the same pixels. Residency says the bytes are here; selectability says
+     * nothing above them is missing, which is what "no holes and no double-draw, in any arrival
+     * order" actually rests on.
+     *
+     * Synchronous and total, like {@link page}: the traversal asks it per cluster and acts on a
+     * `false` by clamping.
+     *
+     * @param {number} page_index
+     * @param {number} group index within that page
+     * @returns {boolean}
+     */
+    is_selectable(page_index, group) {
+        const selectable = this.#selectable.get(page_index);
+
+        if (selectable === undefined) {
+            return false;
+        }
+
+        return selectable[group] === 1;
+    }
+
+    /**
+     * Bring a freshly installed page into the activation state.
+     *
+     * @param {VGeoPage} page
+     */
+    #activate_page(page) {
+        const group_count = page.group_cluster_first.length;
+
+        const live = new Uint16Array(group_count);
+        const selectable = new Uint8Array(group_count);
+
+        const pending = this.#pending_refs.get(page.index);
+
+        if (pending !== undefined) {
+            for (const [group, count] of pending) {
+                if (group < group_count) {
+                    live[group] = count;
+                }
+            }
+
+            this.#pending_refs.delete(page.index);
+        }
+
+        this.#live_refs.set(page.index, live);
+        this.#selectable.set(page.index, selectable);
+
+        /**
+         * Page and group index, interleaved, as {@link vgeo_select_cut}'s own stack is.
+         * @type {number[]}
+         */
+        const queue = [];
+
+        for (let group = 0; group < group_count; group++) {
+            if (live[group] === page.group_parent_count[group]) {
+                queue.push(page.index, group);
+            }
+        }
+
+        this.#cascade_activate(queue);
+    }
+
+    /**
+     * Flip the queued groups selectable, and follow their references down.
+     *
+     * A group becoming selectable makes every reference its clusters hold live, which can complete
+     * the count of a group one level down, and so on. The cascade is what lets a page arrive in any
+     * order: whatever it unblocks, it unblocks now, and whatever it does not stays clamped without
+     * anybody having to ask again.
+     *
+     * @param {number[]} queue page and group index, interleaved
+     */
+    #cascade_activate(queue) {
+        while (queue.length > 0) {
+            const group = queue.pop();
+            const page_index = queue.pop();
+
+            const page = this.#pages.get(page_index);
+            const selectable = this.#selectable.get(page_index);
+
+            if (page === undefined || selectable[group] === 1) {
+                continue;
+            }
+
+            selectable[group] = 1;
+
+            const first = page.group_cluster_first[group];
+            const count = page.group_cluster_count[group];
+
+            for (let i = 0; i < count; i++) {
+                const cluster = first + i;
+
+                const child_page = this.#child_page_of(page, cluster);
+
+                if (child_page < 0) {
+                    continue;
+                }
+
+                const child_group = page.child_group[cluster];
+
+                const live = this.#live_refs.get(child_page);
+
+                if (live === undefined) {
+                    this.#hold_reference(child_page, child_group);
+
+                    continue;
+                }
+
+                if (child_group >= live.length) {
+                    // a `child_group` outside the child page's table; the traversal reports the
+                    // broken reference, and counting it here would corrupt a neighbour's counter
+                    continue;
+                }
+
+                live[child_group]++;
+
+                if (live[child_group] === this.#pages.get(child_page).group_parent_count[child_group]) {
+                    queue.push(child_page, child_group);
+                }
+            }
+        }
+    }
+
+    /**
+     * Retract a group's selectability and everything that rested on it.
+     *
+     * The mirror of the cascade, and the reason eviction is not simply forgetting a page: a group
+     * one level down was selectable *because* of the references this one made, and leaving those
+     * counted would leave it drawable with a hole above it.
+     *
+     * @param {number} page_index
+     * @param {number} group
+     */
+    #cascade_deactivate(page_index, group) {
+        const page = this.#pages.get(page_index);
+        const selectable = this.#selectable.get(page_index);
+
+        if (page === undefined || selectable === undefined || selectable[group] !== 1) {
+            return;
+        }
+
+        selectable[group] = 0;
+
+        const first = page.group_cluster_first[group];
+        const count = page.group_cluster_count[group];
+
+        for (let i = 0; i < count; i++) {
+            const cluster = first + i;
+
+            const child_page = this.#child_page_of(page, cluster);
+
+            if (child_page < 0) {
+                continue;
+            }
+
+            const child_group = page.child_group[cluster];
+
+            const live = this.#live_refs.get(child_page);
+
+            if (live === undefined) {
+                this.#release_reference(child_page, child_group);
+
+                continue;
+            }
+
+            if (child_group >= live.length) {
+                continue;
+            }
+
+            live[child_group]--;
+
+            if (live[child_group] < this.#pages.get(child_page).group_parent_count[child_group]) {
+                this.#cascade_deactivate(child_page, child_group);
+            }
+        }
+    }
+
+    /**
+     * The page a cluster's child group lives in, or `-1` where there is none to resolve — a leaf, or
+     * a `child_ref` outside this page's child table.
+     *
+     * `SAME_PAGE` resolves to the page itself and is *not* a shortcut past activation: page-local
+     * says nothing about where the group's other parents are, and a group referenced from inside its
+     * own page can still be waiting on one that is not.
+     *
+     * @param {VGeoPage} page
+     * @param {number} cluster
+     * @returns {number}
+     */
+    #child_page_of(page, cluster) {
+        const child_ref = page.child_ref[cluster];
+
+        if (child_ref === VGEO_NO_CHILD) {
+            return -1;
+        }
+
+        if (child_ref === VGEO_SAME_PAGE) {
+            return page.index;
+        }
+
+        if (child_ref >= page.child_page_index.length) {
+            return -1;
+        }
+
+        return page.child_page_index[child_ref];
+    }
+
+    /**
+     * @param {number} page_index a page that is not resident
+     * @param {number} group
+     */
+    #hold_reference(page_index, group) {
+        let held = this.#pending_refs.get(page_index);
+
+        if (held === undefined) {
+            held = new Map();
+
+            this.#pending_refs.set(page_index, held);
+        }
+
+        held.set(group, (held.get(group) ?? 0) + 1);
+    }
+
+    /**
+     * @param {number} page_index a page that is not resident
+     * @param {number} group
+     */
+    #release_reference(page_index, group) {
+        const held = this.#pending_refs.get(page_index);
+
+        if (held === undefined) {
+            return;
+        }
+
+        const left = (held.get(group) ?? 0) - 1;
+
+        if (left > 0) {
+            held.set(group, left);
+        } else {
+            held.delete(group);
+        }
+
+        if (held.size === 0) {
+            this.#pending_refs.delete(page_index);
+        }
+    }
+
+    /**
+     * Fetch and install one page, from the exact range something already resident named.
+     *
+     * Concurrent calls for the same page share one fetch; a page already resident is returned
+     * without one.
+     *
+     * @param {number} page_index
+     * @param {number} frame_offset absolute
+     * @param {number} fetch_size
+     * @returns {Promise<VGeoPage>}
+     */
+    install(page_index, frame_offset, fetch_size) {
+        const resident = this.#pages.get(page_index);
+
+        if (resident !== undefined) {
+            return Promise.resolve(resident);
+        }
+
+        const in_flight = this.#pending.get(page_index);
+
+        if (in_flight !== undefined) {
+            return in_flight;
+        }
+
+        const fetch = this.#fetch_page(page_index, frame_offset, fetch_size)
+            .finally(() => this.#pending.delete(page_index));
+
+        this.#pending.set(page_index, fetch);
+
+        return fetch;
+    }
+
+    /**
+     * @param {number} page_index
+     * @param {number} frame_offset
+     * @param {number} fetch_size
+     * @returns {Promise<VGeoPage>}
+     */
+    async #fetch_page(page_index, frame_offset, fetch_size) {
+        const bytes = await this.#read(frame_offset, fetch_size);
+
+        if (this.#options.verify_frames) {
+            this.#verify_frame(bytes, page_index);
+        }
+
+        const page = vgeo_read_page(bytes, page_index);
+
+        page.frame_offset = frame_offset;
+
+        // Two callers can reach here for one page only if the second started before the first
+        // resolved, which `#pending` already prevents — but residency is the accounting, so it is
+        // read here rather than assumed.
+        if (!this.#pages.has(page_index)) {
+            this.#pages.set(page_index, page);
+
+            this.#resident_bytes += page.decoded_size;
+
+            // after the page is resident, because the cascade reads residency to decide whether a
+            // reference lands on a counter or waits in the pending index — including this page's own
+            this.#activate_page(page);
+        }
+
+        return this.#pages.get(page_index);
+    }
+
+    /**
+     * Install the page a want names.
+     *
+     * @param {VGeoPageWant} want
+     * @returns {Promise<VGeoPage>}
+     */
+    install_want(want) {
+        return this.install(want.page_index, want.frame_offset, want.fetch_size);
+    }
+
+    /**
+     * Install a batch of wants, most wanted first, with a bounded number of fetches in flight.
+     *
+     * Ordered by {@link VGeoPageWant.priority}, which is how far past the pixel threshold the
+     * clamped cluster projected — so a caller that stops early has fetched the pages that would fix
+     * the most visible coarseness, not an arbitrary prefix of the list.
+     *
+     * @param {VGeoPageWant[]} wants
+     * @param {number} [limit] most pages to install; the rest are left for the next traversal to
+     *     want again, which it will, from a cut taken with everything this call did install
+     * @returns {Promise<VGeoPage[]>} the pages installed, in completion order
+     */
+    async install_wants(wants, limit = wants.length) {
+        // Sorted before it is cut, not after: a limit applied to the caller's order would install an
+        // arbitrary prefix and the ranking would have bought nothing.
+        const queue = wants.slice().sort((a, b) => b.priority - a.priority).slice(0, limit);
+
+        const installed = [];
+
+        let next = 0;
+
+        const worker = async () => {
+            while (next < queue.length) {
+                const want = queue[next++];
+
+                installed.push(await this.install_want(want));
+            }
+        };
+
+        const workers = [];
+
+        const width = Math.min(this.#options.max_concurrent_fetches, queue.length);
+
+        for (let i = 0; i < width; i++) {
+            workers.push(worker());
+        }
+
+        await Promise.all(workers);
+
+        return installed;
+    }
+
+    /**
+     * Drop a page.
+     *
+     * The eviction *rule* — a page is evictable only while it has no resident child pages, and the
+     * root is pinned (§10) — is a residency policy and belongs to whatever is managing the budget,
+     * not here. What this does is the dropping.
+     *
+     * @param {number} page_index
+     * @returns {boolean} whether a page was there to drop
+     */
+    evict(page_index) {
+        const page = this.#pages.get(page_index);
+
+        if (page === undefined) {
+            return false;
+        }
+
+        /*
+         Retract before dropping: the references this page's selectable groups made are read out of
+         its own cluster records, and a page that has already been forgotten cannot say what it was
+         holding up. Under §10's eviction rule — a page is evictable only while it has no resident
+         child pages — this decrements nothing that is still resident and costs a walk of the page.
+         When a caller evicts against that rule anyway, the cascade is what stops a child page from
+         staying drawable with nothing above it.
+        */
+        const selectable = this.#selectable.get(page_index);
+
+        for (let group = 0; group < selectable.length; group++) {
+            this.#cascade_deactivate(page_index, group);
+        }
+
+        /*
+         References *into* this page do not go away with it — the clusters making them are in pages
+         that are still here and still selectable — so they move back to the pending index, and a
+         re-install starts its counters where they left off rather than at zero.
+        */
+        const live = this.#live_refs.get(page_index);
+
+        const held = new Map();
+
+        for (let group = 0; group < live.length; group++) {
+            if (live[group] > 0) {
+                held.set(group, live[group]);
+            }
+        }
+
+        if (held.size > 0) {
+            this.#pending_refs.set(page_index, held);
+        } else {
+            this.#pending_refs.delete(page_index);
+        }
+
+        this.#live_refs.delete(page_index);
+        this.#selectable.delete(page_index);
+
+        this.#pages.delete(page_index);
+
+        this.#resident_bytes -= page.decoded_size;
+
+        return true;
+    }
+
+    /**
+     * Drop every page but the root, which is pinned.
+     *
+     * @returns {number} pages dropped
+     */
+    evict_all() {
+        let dropped = 0;
+
+        for (const index of Array.from(this.#pages.keys())) {
+            if (index !== 0 && this.evict(index)) {
+                dropped++;
+            }
+        }
+
+        return dropped;
+    }
+
+    /**
+     * Read the page directory, and keep it on {@link directory}.
+     *
+     * One fetch of a region that is 32 bytes per page — a hundred kilobytes for a file with three
+     * thousand pages. Auxiliary by design: nothing a traversal does needs it, and asking for it says
+     * the caller wants to reach pages the DAG does not lead it to.
+     *
+     * @returns {Promise<VGeoDirectory>}
+     */
+    async read_directory() {
+        if (this.directory !== undefined) {
+            return this.directory;
+        }
+
+        const header = this.header;
+
+        const end = header.dir_block_checksums_offset > header.directory_offset
+            ? header.dir_block_checksums_offset
+            : this.#source.byte_length;
+
+        const bytes = await this.#read(header.directory_offset, end - header.directory_offset);
+
+        this.directory = vgeo_read_directory(bytes, header.total_pages);
+
+        return this.directory;
+    }
+
+    /**
+     * Install every page the directory lists.
+     *
+     * The opposite of what this reader is for, and exactly what a tool wants when the question is
+     * about the file rather than about a view of it — the pages no cut reaches are the ones a bug
+     * hides in.
+     *
+     * @param {function(number, number): void} [on_progress] called with pages installed and total
+     * @returns {Promise<void>}
+     */
+    async install_all_pages(on_progress = undefined) {
+        const directory = await this.read_directory();
+
+        let done = 0;
+
+        for (let index = 0; index < directory.page_count; index++) {
+            await this.install(index, directory.frame_offset[index], directory.fetch_size[index]);
+
+            done++;
+
+            if (on_progress !== undefined) {
+                on_progress(done, directory.page_count);
+            }
+        }
+    }
+
+    /**
+     * The whole-file audit — every build invariant of §11, every checksum, and the directory against
+     * what a frame scan reconstructs.
+     *
+     * **This reads the entire file**, which is the one thing the rest of this class exists to avoid,
+     * and it is why it is a separate call and off by default. It answers a question about whoever
+     * produced the file; nothing about reading one depends on it having been asked.
+     *
+     * @returns {Promise<VGeoDefect[]>} empty is the only good answer
+     */
+    async validate() {
+        const bytes = await this.#source.read(0, this.#source.byte_length);
+
+        const whole = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+            ? bytes.buffer
+            : bytes.slice().buffer;
+
+        return vgeo_validate_container(BinaryBuffer.fromArrayBuffer(whole));
+    }
+
+    /**
+     * A byte range, from the kept head prefix where it lies inside it and from the source otherwise.
+     *
+     * @param {number} offset
+     * @param {number} length
+     * @returns {Promise<Uint8Array>}
+     */
+    #read(offset, length) {
+        if (offset + length <= this.#head.byteLength) {
+            return Promise.resolve(this.#head.subarray(offset, offset + length));
+        }
+
+        return this.#source.read(offset, length);
+    }
+
+    /**
+     * Extend the kept head prefix to `to` bytes, fetching only the part that is missing.
+     *
+     * Only ever at the tail, which is what keeps a cold start from paying for the same bytes twice:
+     * the header is read once even when the prefix that carried it stopped short of the level table.
+     *
+     * @param {number} to
+     * @returns {Promise<void>}
+     */
+    async #grow_head(to) {
+        const target = Math.min(to, this.#source.byte_length);
+
+        const have = this.#head.byteLength;
+
+        if (target <= have) {
+            return;
+        }
+
+        const tail = await this.#source.read(have, target - have);
+
+        const grown = new Uint8Array(target);
+
+        grown.set(this.#head, 0);
+        grown.set(tail, have);
+
+        this.#head = grown;
+    }
+
+    /**
+     * Check a frame against its identity-seeded checksum before anything decodes it.
+     *
+     * The seed is `asset_id_low64 XOR page_index`, so this catches a well-formed frame of the wrong
+     * page or the wrong asset as well as corruption — which is the case a traversal can actually
+     * produce, by following a child-table entry whose offset is wrong.
+     *
+     * @param {Uint8Array} bytes the fetched frame
+     * @param {number} page_index
+     */
+    #verify_frame(bytes, page_index) {
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+
+        const frame = vgeo_read_frame_extent(view, 0, page_index);
+
+        const stored = view.getBigUint64(VGEO_FRAME_OFFSET.CHECKSUM, LE);
+
+        const copy = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength
+            ? bytes.buffer
+            : bytes.slice().buffer;
+
+        const computed = vgeo_compute_frame_checksum(
+            BinaryBuffer.fromArrayBuffer(copy), frame, this.header.asset_id_low64
+        );
+
+        if (computed !== stored) {
+            throw new Error(
+                `page ${page_index}: its frame checksums to 0x${computed.toString(16)}`
+                + ` and stores 0x${stored.toString(16)}`
+            );
+        }
+    }
+}