@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -1,9 +1,10 @@
 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";
@@ -15,6 +16,12 @@ import { vgeo_read_page } from "./vgeo_read_page.js";
  */
 const LE = true;
 
+/**
+ * What {@link VGeoContainerReader.release_head} leaves behind, shared because it is empty.
+ * @type {Uint8Array}
+ */
+const NO_HEAD = new Uint8Array(0);
+
 /**
  * A `.vgeo` container, read a page at a time.
  *
@@ -33,11 +40,26 @@ const LE = true;
  * 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.
+ *
+ * **Mechanics, not policy — and the line is deliberate.** Which page to fetch next, which to drop,
+ * how many bytes one asset may hold, how many requests may be in flight across a thousand of them:
+ * none of that is decided here, because none of it can be decided by one reader looking at one file.
+ * `VGeoResidencyManager` is where it is decided and readers register with one; §10's eviction bullet
+ * is the reason for the split rather than an apology for it. What *is* here is everything that is
+ * about the bytes — the fetch, the retries, the quarantine a page that will not arrive ends up in,
+ * and the accounting a budget owner spends against.
+ *
  * **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}.
+ * whole-file audit is `vgeo_audit_container` in `tool/`, it reads every byte of the file, and
+ * nothing on the runtime path can reach it.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -80,21 +102,87 @@ export class VGeoContainerReader {
     #pending = new Map();
 
     /**
-     * The speculative head prefix, kept.
+     * The abort for each fetch in flight, by page index — one per fetch, so a want that went stale
+     * takes down its own request and no other. See {@link cancel}.
+     * @type {Map<number, AbortController>}
+     */
+    #aborts = new Map();
+
+    /**
+     * Pages that could not be read, and why, by page index.
      *
-     * 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.
+     * §10's quarantine. A page that has failed its bounded retries is not asked for again: at a
+     * content-addressed URL the failure is deterministic, so asking again asks the same question,
+     * and a traversal that keeps wanting the page would keep re-issuing it forever. What makes this
+     * survivable rather than a loss is the clamped cut — a quarantined page's parent stays selected
+     * and keeps covering that surface correctly, indefinitely.
+     *
+     * @type {Map<number, string>}
+     */
+    #quarantined = new Map();
+
+    /**
+     * The speculative head prefix, while it is still paying for itself.
+     *
+     * Coarse-first layout is what makes a prefix worth fetching at all: one 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. What it is *not* worth is keeping afterwards — see
+     * {@link release_head}, which runs by itself the first time a read falls outside it.
      *
      * @type {Uint8Array}
      */
-    #head = new Uint8Array(0);
+    #head = NO_HEAD;
 
     /**
      * @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.
+     *
+     * **It is bounded by the residency frontier and not by the session's history**, which is worth
+     * writing down because it has the shape of an index that leaks. An entry exists only while some
+     * resident, selectable cluster refers into a page that is absent, and the two halves are
+     * symmetric — eviction and deactivation release exactly what install and activation counted.
+     * Measured on a 20,000-page container with the 3,280 pages of its eight coarse bands pinned
+     * resident: 6,561 entries after pinning, and still 6,561 after touring all 6,561 pages of the
+     * band below them a window at a time and evicting each window. The frontier, unchanged, rather
+     * than one entry per page visited. Dropping the pinned pages too leaves 3.
+     * {@link pending_reference_page_count} is that number.
+     *
+     * @type {Map<number, Map<number, number>>}
+     */
+    #pending_refs = new Map();
+
     /**
      * @param {VGeoByteSource} source
      * @param {VGeoReadOptions} [options]
@@ -129,6 +217,16 @@ export class VGeoContainerReader {
 
     /**
      * Decoded bytes currently held. The number a residency budget is spent against.
+     *
+     * It is exactly the decoded page images — the same number the directory's `decoded_size` column
+     * and every child-table entry promise *before* a page is fetched, which is what lets a budget
+     * owner admit a page rather than discover its cost after paying for it. It is deliberately not
+     * what the pages cost in the heap: the reader's own per-page bookkeeping — the `VGeoPage`, its
+     * cluster and child tables, the two activation arrays, the map entries — measured 6.4–11.9 KB
+     * per page on top of the image. That is 1.2% of a 544 KB page at the sizes design §5 targets and
+     * 294% of a 2 KB one, so a budget sized against very small pages has to allow for it and one
+     * sized against the design's page size is inside its own rounding.
+     *
      * @returns {number}
      */
     get resident_bytes() {
@@ -142,9 +240,49 @@ export class VGeoContainerReader {
         return this.#pending.size;
     }
 
+    /**
+     * How many not-yet-resident pages the reverse-reference index is holding counters for.
+     *
+     * Diagnostic, and the number a leak in that index would show up in: an entry exists only while
+     * some resident, selectable cluster refers into a page that is not here, so this tracks the
+     * residency frontier and must not track how many pages a session has visited. See
+     * {@link #pending_refs} for what that was measured at.
+     *
+     * @returns {number}
+     */
+    get pending_reference_page_count() {
+        return this.#pending_refs.size;
+    }
+
+    /**
+     * How many bytes of speculative head prefix are still held — zero once {@link release_head} has
+     * run, which is the normal state after the first read that falls outside the prefix.
+     *
+     * @returns {number}
+     */
+    get head_bytes() {
+        return this.#head.byteLength;
+    }
+
+    /**
+     * How many pages have failed their retries and will not be asked for again.
+     * @returns {number}
+     */
+    get quarantined_page_count() {
+        return this.#quarantined.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.
+     *
+     * What the pin costs is worth writing down, because "pinned for life, times a thousand assets"
+     * is the shape of a problem and this one is not: build invariant §11.7 puts exactly one root
+     * cluster in the file, and the assembler gives the root page the complete topmost level — so the
+     * root page *is* that one cluster. Measured on two torus builds, of 7.7K and 42K source
+     * triangles and 8 and 12 levels: 1,732 B and 1,472 B decoded. A thousand of them is under 2 MB,
+     * and no builder-side cap on root size is needed to keep it that way.
+     *
      * @returns {VGeoPage}
      */
     get root() {
@@ -152,13 +290,28 @@ export class VGeoContainerReader {
     }
 
     /**
-     * Every resident page, in page-index order.
+     * Every resident page, sorted by page index.
+     *
+     * A snapshot, and it costs one: an array of every resident page plus a sort of it — 0.29 ms per
+     * access measured at 20,000 resident pages. So this is for a tool, a panel or a test, and **not
+     * for anything that runs per frame**. {@link resident_pages} is the same set in arrival order
+     * and allocates nothing, which is what a per-frame sweep should read.
+     *
      * @returns {VGeoPage[]}
      */
     get pages() {
         return Array.from(this.#pages.values()).sort((a, b) => a.index - b.index);
     }
 
+    /**
+     * Every resident page, in arrival order, allocating nothing.
+     *
+     * @returns {IterableIterator<VGeoPage>}
+     */
+    resident_pages() {
+        return this.#pages.values();
+    }
+
     /**
      * Open a container: header, level table, root page.
      *
@@ -199,7 +352,8 @@ export class VGeoContainerReader {
          §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.
+         whenever the prefix was generous. Nothing is fetched twice: the head only grows at its tail,
+         and it only grows here, once, before anything else has read a byte of the file.
         */
         await this.#grow_head(vgeo_resident_head_size(this.#head));
 
@@ -267,16 +421,366 @@ export class VGeoContainerReader {
         return this.#pages.has(page_index);
     }
 
+    /**
+     * How many of a page's child pages are resident.
+     *
+     * §10's eviction rule is written in terms of this: within a residency tier, a page is evictable
+     * only while it has no resident child pages in that tier, checked against its own child table.
+     * `SAME_PAGE` references never pin and are in no child table by construction (§11.2), so the
+     * table is the whole answer. The *rule* is a policy and lives with the budget owner; this
+     * lookup is about one page's own bytes and lives here.
+     *
+     * @param {number} page_index
+     * @returns {number} zero for a page that is not resident, and for one no child of which is
+     */
+    resident_child_count(page_index) {
+        const page = this.#pages.get(page_index);
+
+        if (page === undefined) {
+            return 0;
+        }
+
+        const children = page.child_page_index;
+
+        let count = 0;
+
+        for (let i = 0; i < children.length; i++) {
+            if (this.#pages.has(children[i])) {
+                count++;
+            }
+        }
+
+        return count;
+    }
+
+    /**
+     * 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);
+        }
+    }
+
+    /**
+     * Whether a page has failed its retries and been quarantined.
+     *
+     * @param {number} page_index
+     * @returns {boolean}
+     */
+    is_quarantined(page_index) {
+        return this.#quarantined.has(page_index);
+    }
+
+    /**
+     * Why a page was quarantined, or `undefined` if it was not.
+     *
+     * §10 asks for the quarantine *and* for telemetry, because a page that stopped arriving is the
+     * difference between a coarse asset and a broken deployment, and on screen the two are the same
+     * picture.
+     *
+     * @param {number} page_index
+     * @returns {string|undefined}
+     */
+    quarantine_reason(page_index) {
+        return this.#quarantined.get(page_index);
+    }
+
+    /**
+     * Every quarantined page and its reason.
+     * @returns {IterableIterator<[number, string]>}
+     */
+    quarantine() {
+        return this.#quarantined.entries();
+    }
+
+    /**
+     * Let a quarantined page be asked for again.
+     *
+     * **When** is a policy and is not decided here. A frame checksum that failed at a
+     * content-addressed URL will fail again and lifting its quarantine buys nothing; a run of 503s
+     * from one edge node is a different thing, and a budget owner that has watched other pages of
+     * other assets arrive since has evidence this reader does not have. So the reader quarantines
+     * for its own lifetime and offers this, and `VGeoResidencyManager` is where the decision to use
+     * it lives.
+     *
+     * @param {number} [page_index] omit to lift every quarantine
+     * @returns {number} how many pages were released
+     */
+    clear_quarantine(page_index = undefined) {
+        if (page_index === undefined) {
+            const released = this.#quarantined.size;
+
+            this.#quarantined.clear();
+
+            return released;
+        }
+
+        return this.#quarantined.delete(page_index) ? 1 : 0;
+    }
+
     /**
      * 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.
+     * without one; a page in quarantine is refused without one.
      *
      * @param {number} page_index
      * @param {number} frame_offset absolute
      * @param {number} fetch_size
      * @returns {Promise<VGeoPage>}
+     * @throws {Error} asynchronously — when the page is already quarantined, when it fails every
+     *     attempt and is quarantined by doing so, or when {@link cancel} abandoned it
      */
     install(page_index, frame_offset, fetch_size) {
         const resident = this.#pages.get(page_index);
@@ -291,8 +795,21 @@ export class VGeoContainerReader {
             return in_flight;
         }
 
-        const fetch = this.#fetch_page(page_index, frame_offset, fetch_size)
-            .finally(() => this.#pending.delete(page_index));
+        const quarantined = this.#quarantined.get(page_index);
+
+        if (quarantined !== undefined) {
+            return Promise.reject(new Error(`page ${page_index} is quarantined: ${quarantined}`));
+        }
+
+        const abort = new AbortController();
+
+        this.#aborts.set(page_index, abort);
+
+        const fetch = this.#fetch_page(page_index, frame_offset, fetch_size, abort.signal)
+            .finally(() => {
+                this.#pending.delete(page_index);
+                this.#aborts.delete(page_index);
+            });
 
         this.#pending.set(page_index, fetch);
 
@@ -300,13 +817,97 @@ export class VGeoContainerReader {
     }
 
     /**
+     * Abandon a fetch that is still in flight.
+     *
+     * **What a want that goes stale mid-flight should do, decided:** abort it while it can still be
+     * aborted, and install it once it cannot. The camera moved, nothing wants the page now, and the
+     * request is worth closing — but once the bytes have landed, refusing to install them is the one
+     * choice that pays for the fetch *and* throws the page away. So an abort that arrives too late
+     * does nothing, the page installs, and it enters residency untouched — which under LRU on
+     * last-touched (design §6) makes it the first candidate for eviction if the camera really is
+     * done with it, and free if it is not.
+     *
+     * The pending promise rejects, so a caller awaiting it sees the abort rather than a page. A
+     * cancelled page is **not** quarantined: nothing was wrong with it.
+     *
+     * @param {number} page_index
+     * @returns {boolean} whether there was a fetch to abandon
+     */
+    cancel(page_index) {
+        const abort = this.#aborts.get(page_index);
+
+        if (abort === undefined) {
+            return false;
+        }
+
+        abort.abort(new Error(`page ${page_index}: the fetch was cancelled`));
+
+        return true;
+    }
+
+    /**
+     * Abandon every fetch in flight.
+     * @returns {number} how many were abandoned
+     */
+    cancel_all() {
+        let cancelled = 0;
+
+        for (const page_index of Array.from(this.#aborts.keys())) {
+            if (this.cancel(page_index)) {
+                cancelled++;
+            }
+        }
+
+        return cancelled;
+    }
+
+    /**
+     * One page, retried a bounded number of times and then quarantined — §10.
+     *
      * @param {number} page_index
      * @param {number} frame_offset
      * @param {number} fetch_size
+     * @param {AbortSignal} signal
      * @returns {Promise<VGeoPage>}
      */
-    async #fetch_page(page_index, frame_offset, fetch_size) {
-        const bytes = await this.#read(frame_offset, fetch_size);
+    async #fetch_page(page_index, frame_offset, fetch_size, signal) {
+        const retries = this.#options.fetch_retries;
+
+        for (let attempt = 0; ; attempt++) {
+            try {
+                return await this.#read_page(page_index, frame_offset, fetch_size, signal);
+            } catch (e) {
+                if (signal.aborted) {
+                    // cancelled rather than failed: nothing is wrong with this page
+                    throw signal.reason ?? e;
+                }
+
+                const reason = String(e?.message ?? e);
+
+                if (attempt >= retries) {
+                    this.#quarantined.set(page_index, reason);
+
+                    throw new Error(
+                        `page ${page_index} is quarantined after ${attempt + 1} attempt(s): ${reason}`
+                    );
+                }
+
+                await delay(this.#options.fetch_retry_backoff_ms * (1 << attempt), signal);
+            }
+        }
+    }
+
+    /**
+     * One attempt: the bytes, the checks, the decode, and the residency it becomes.
+     *
+     * @param {number} page_index
+     * @param {number} frame_offset
+     * @param {number} fetch_size
+     * @param {AbortSignal} signal
+     * @returns {Promise<VGeoPage>}
+     */
+    async #read_page(page_index, frame_offset, fetch_size, signal) {
+        const bytes = await this.#read(frame_offset, fetch_size, signal);
 
         if (this.#options.verify_frames) {
             this.#verify_frame(bytes, page_index);
@@ -323,6 +924,10 @@ export class VGeoContainerReader {
             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);
@@ -345,25 +950,58 @@ export class VGeoContainerReader {
      * 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.
      *
+     * **A page that will not arrive does not take the batch down.** One flaky edge node, or one
+     * corrupt frame out of a thousand assets' worth of pages, must cost exactly that page: it is
+     * retried, then quarantined, then skipped, and what comes back is what did install. *Which*
+     * pages failed is durable rather than a per-call return — see {@link quarantine} — because a
+     * failure that lived only in one call's result is one the next call would repeat.
+     *
+     * The concurrency bound here is this reader's own. A runtime holding many assets wants a bound
+     * across all of them and should install through `VGeoResidencyManager`, which admits every
+     * registered reader's fetches through one scheduler: eight readers calling this at the default
+     * were measured issuing 48 concurrent range requests.
+     *
      * @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
+     * @param {AbortSignal} [signal] stops the batch taking new wants, and abandons what is in flight
      * @returns {Promise<VGeoPage[]>} the pages installed, in completion order
      */
-    async install_wants(wants, limit = wants.length) {
+    async install_wants(wants, limit = wants.length, signal = undefined) {
         // 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 = [];
 
+        /**
+         * Pages *this* batch has on the wire, so that aborting it abandons those and not whatever
+         * another caller started. A signal belongs to one want list; {@link cancel_all} belongs to
+         * the reader, and using the second for the first would make two concurrent batches able to
+         * cancel each other.
+         * @type {Set<number>}
+         */
+        const mine = new Set();
+
         let next = 0;
 
         const worker = async () => {
             while (next < queue.length) {
+                if (signal !== undefined && signal.aborted) {
+                    return;
+                }
+
                 const want = queue[next++];
 
-                installed.push(await this.install_want(want));
+                mine.add(want.page_index);
+
+                try {
+                    installed.push(await this.install_want(want));
+                } catch {
+                    // quarantined, or cancelled — either way, not this batch's business
+                } finally {
+                    mine.delete(want.page_index);
+                }
             }
         };
 
@@ -375,7 +1013,19 @@ export class VGeoContainerReader {
             workers.push(worker());
         }
 
-        await Promise.all(workers);
+        const abandon = () => {
+            for (const page_index of mine) {
+                this.cancel(page_index);
+            }
+        };
+
+        signal?.addEventListener('abort', abandon, { once: true });
+
+        try {
+            await Promise.all(workers);
+        } finally {
+            signal?.removeEventListener('abort', abandon);
+        }
 
         return installed;
     }
@@ -385,7 +1035,8 @@ export class VGeoContainerReader {
      *
      * 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.
+     * not here. What this does is the dropping; {@link resident_child_count} is the lookup the rule
+     * is written in terms of.
      *
      * @param {number} page_index
      * @returns {boolean} whether a page was there to drop
@@ -397,6 +1048,44 @@ export class VGeoContainerReader {
             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;
@@ -451,47 +1140,38 @@ export class VGeoContainerReader {
     /**
      * 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.
-     *
+     * @deprecated it reads the whole file, and a renderer holding a reader must not be able to reach
+     *     that from the reader. Call `vgeo_install_all_pages` in `tool/` instead, which is a tool
+     *     and says so. Kept as a shim because the playground and the specs are what it is for.
      * @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;
+        const { vgeo_install_all_pages } = await import('./tool/vgeo_install_all_pages.js');
 
-        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);
-            }
-        }
+        await vgeo_install_all_pages(this, on_progress);
     }
 
     /**
      * 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.
-     *
+     * @deprecated it reads the entire file into one `ArrayBuffer`, which is the one thing the rest
+     *     of this class exists to avoid and which a multi-GB asset does not survive. Call
+     *     `vgeo_audit_container` in `tool/` instead, which refuses a file too large to audit this
+     *     way rather than attempting it. Kept as a shim for the playground and the specs.
      * @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;
+        /*
+         Imported here rather than at the top of the file on purpose: a static import would put
+         `vgeo_validate_container` — and the whole-file scan it carries — in the same module graph as
+         every runtime that opens a container. The dynamic import is what makes "a runtime path
+         cannot reach the audit" true of the bundle and not only of the documentation.
+        */
+        const { vgeo_audit_container } = await import('./tool/vgeo_audit_container.js');
 
-        return vgeo_validate_container(BinaryBuffer.fromArrayBuffer(whole));
+        return vgeo_audit_container(this);
     }
 
     /**
@@ -499,21 +1179,55 @@ export class VGeoContainerReader {
      *
      * @param {number} offset
      * @param {number} length
+     * @param {AbortSignal} [signal]
      * @returns {Promise<Uint8Array>}
      */
-    #read(offset, length) {
-        if (offset + length <= this.#head.byteLength) {
-            return Promise.resolve(this.#head.subarray(offset, offset + length));
+    #read(offset, length, signal = undefined) {
+        const head = this.#head;
+
+        if (offset + length <= head.byteLength) {
+            return Promise.resolve(head.subarray(offset, offset + length));
+        }
+
+        /*
+         The prefix has stopped paying for itself. File order is coarse-first, so a read past the end
+         of the head is a traversal that has walked past the band the head covered, and the pages
+         inside it that were going to be free already were. Holding it from here on holds bytes
+         nothing will read: measured, a 256 KiB prefix over a 22 MB container covered 105 of its
+         4,000 pages, and once those installed the whole prefix served nothing — while staying
+         outside `resident_bytes` and outside anything `evict` could reach. Across a thousand open
+         assets that was a quarter of a gigabyte no budget could see.
+        */
+        if (head.byteLength > 0) {
+            this.release_head();
         }
 
-        return this.#source.read(offset, length);
+        return this.#source.read(offset, length, signal);
+    }
+
+    /**
+     * Drop the speculative head prefix.
+     *
+     * Nothing depends on it afterwards: the header and level table are parsed into {@link header}
+     * before anything else runs, the root page owns its own decoded bytes, and every later read
+     * names a range the source can serve. A page whose frame lay inside the prefix costs one request
+     * if it is wanted after this — the same request it would have cost had the prefix been smaller.
+     *
+     * @returns {number} bytes released
+     */
+    release_head() {
+        const released = this.#head.byteLength;
+
+        this.#head = NO_HEAD;
+
+        return released;
     }
 
     /**
      * 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.
+     * Called exactly once, from {@link #open}, before anything else has read a byte — so the copy it
+     * makes happens once per reader, and it never re-copies a prefix that is already in use.
      *
      * @param {number} to
      * @returns {Promise<void>}
@@ -570,3 +1284,41 @@ export class VGeoContainerReader {
         }
     }
 }
+
+/**
+ * Wait, unless the caller stops wanting to.
+ *
+ * The timer is cleared on abort rather than left to fire, because a backoff between retries of a
+ * page nobody wants any more is exactly the wait a cancelled fetch should not sit through.
+ *
+ * @param {number} ms
+ * @param {AbortSignal} signal
+ * @returns {Promise<void>}
+ */
+function delay(ms, signal) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+
+    // Checked rather than relied on: `addEventListener` on a signal that has already aborted never
+    // fires, so a wait started on one would run to term with nobody left who wanted it.
+    if (signal.aborted) {
+        return Promise.reject(signal.reason ?? new Error('the wait was cancelled'));
+    }
+
+    return new Promise((resolve, reject) => {
+        const on_abort = () => {
+            clearTimeout(timer);
+
+            reject(signal.reason ?? new Error('the wait was cancelled'));
+        };
+
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', on_abort);
+
+            resolve();
+        }, ms);
+
+        signal.addEventListener('abort', on_abort, { once: true });
+    });
+}