@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -5,7 +5,6 @@ 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";
@@ -17,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.
  *
@@ -42,11 +47,19 @@ const LE = true;
  * 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
@@ -89,15 +102,36 @@ 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.
+     *
+     * §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 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.
+     * 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}
@@ -135,6 +169,16 @@ export class VGeoContainerReader {
      * 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();
@@ -173,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() {
@@ -186,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() {
@@ -196,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.
      *
@@ -243,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));
 
@@ -311,6 +421,38 @@ 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}.
@@ -570,16 +712,75 @@ export class VGeoContainerReader {
         }
     }
 
+    /**
+     * 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);
@@ -594,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);
 
@@ -603,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);
@@ -652,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);
+                }
             }
         };
 
@@ -682,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;
     }
@@ -692,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
@@ -796,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;
-
-        for (let index = 0; index < directory.page_count; index++) {
-            await this.install(index, directory.frame_offset[index], directory.fetch_size[index]);
+        const { vgeo_install_all_pages } = await import('./tool/vgeo_install_all_pages.js');
 
-            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);
     }
 
     /**
@@ -844,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>}
@@ -915,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 });
+    });
+}