qvdjs 2.0.4 → 2.0.6

package/dist/index.js

@@ -1,6 +1,6 @@
 import fs2 from 'fs';
 import path2 from 'path';
-import assert3 from 'assert';
+import assert4 from 'assert';
 import crypto2 from 'crypto';
 import { setTimeout } from 'timers/promises';
 import xml from 'xml2js';
@@ -959,7 +959,7 @@ function changedAfterCheck(checked, change) {
   });
 }
 async function openChecked(checked, purpose, failed, { nofollow = NOFOLLOW } = {}) {
-  assert3(purpose === "read" || checked.stats !== null, "A rewrite in place is of a file that exists.");
+  assert4(purpose === "read" || checked.stats !== null, "A rewrite in place is of a file that exists.");
   const noFollow = checked.onDisk ? nofollow : 0;
   const flags = (purpose === "rewrite" ? O_WRONLY : O_RDONLY) | noFollow;
   let handle;
@@ -1535,9 +1535,9 @@ var init_QvdFileWriter = __esm({
        * Writes the data to the QVD file.
        */
       async _writeData() {
-        assert3(this._header, "The QVD file header has not been parsed.");
-        assert3(this._symbolBuffer, "The QVD file symbol table has not been parsed.");
-        assert3(this._indexBuffer, "The QVD file index table has not been parsed.");
+        assert4(this._header, "The QVD file header has not been parsed.");
+        assert4(this._symbolBuffer, "The QVD file symbol table has not been parsed.");
+        assert4(this._indexBuffer, "The QVD file index table has not been parsed.");
         this._emitProgress("write", 0, 1);
         const headerBuffer = Buffer.concat([Buffer.from(this._header, "utf-8"), Buffer.from([0])]);
         const failed = rethrowAsIoError(this._path, "write");
@@ -1985,7 +1985,7 @@ var init_QvdFileWriter = __esm({
             const key = keys[slot];
             offset = typeof key === "number" ? writeSymbol(columnBuffer, offset, kinds[slot], key, texts[slot]) : writeSymbol(columnBuffer, offset, kinds[slot], null, key);
           }
-          assert3(offset === byteLength, "A column was encoded into a different number of bytes than it was sized for.");
+          assert4(offset === byteLength, "A column was encoded into a different number of bytes than it was sized for.");
           columnBuffers.push(columnBuffer);
           this._symbolTableMetadata?.push([symbolsOffset, byteLength, containsNull[column]]);
           this._symbolCounts?.push(keys.length);
@@ -2024,9 +2024,9 @@ var init_QvdFileWriter = __esm({
        * @private
        */
       _buildIndexTable() {
-        assert3(this._symbolCounts, "The QVD file symbol table has not been built.");
-        assert3(this._symbolTableMetadata, "The QVD file symbol table metadata has not been built.");
-        assert3(this._symbolIndexByValue, "The QVD file symbol index has not been built.");
+        assert4(this._symbolCounts, "The QVD file symbol table has not been built.");
+        assert4(this._symbolTableMetadata, "The QVD file symbol table metadata has not been built.");
+        assert4(this._symbolIndexByValue, "The QVD file symbol index has not been built.");
         this._indexTableMetadata = [];
         const columns = this._df.columns;
         const data = this._df.data;
@@ -2206,7 +2206,7 @@ function recommendedChunkFor(budget, symbolTableSize, windowRows, totalRows, col
   }
   return low;
 }
-function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePath, safetyFactor = 0.8, columnCount = 0, materialisesRows = true, live = null) {
+function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePath, safetyFactor = 0.8, columnCount = 0, materialisesRows = true, live = null, bytesHeld = 0) {
   if (typeof safetyFactor !== "number" || safetyFactor < 0 || safetyFactor > 1) {
     throw new QvdValidationError("safetyFactor must be a number between 0.0 and 1.0", { safetyFactor });
   }
@@ -2219,7 +2219,10 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
   const liveRowsPerChunk = live === null ? 1 : live.perChunk;
   const liveRows = rowsLive === null ? rowsToLoad : Math.min(rowsLive, rowsToLoad);
   const heapMemory = estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount, materialisesRows, rowsLive);
-  const externalMemory = estimateExternalMemory(liveRows, columnCount);
+  const held = typeof bytesHeld === "number" ? bytesHeld : bytesHeld.held;
+  const heldForRows = typeof bytesHeld === "number" ? () => bytesHeld : bytesHeld.forRows;
+  const heldForChunk = typeof bytesHeld === "number" ? () => bytesHeld : bytesHeld.forChunk;
+  const externalMemory = estimateExternalMemory(liveRows, columnCount) + held;
   const bounded = budget.candidates.map((candidate) => {
     const heapOnly = candidate.source === "V8 heap limit";
     return {
@@ -2241,14 +2244,19 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
   const maxAllowedMemory = binding ? binding.allowed : budget.bytes * safetyFactor;
   if (binding) {
     const includeExternal = !binding.heapOnly;
-    const recommendedMaxRows = recommendedRowsFor(
-      maxAllowedMemory,
+    const rowsHeldBudget = /* @__PURE__ */ __name((rows) => maxAllowedMemory - (includeExternal ? heldForRows(rows) : 0), "rowsHeldBudget");
+    const fitting = /* @__PURE__ */ __name((rows) => recommendedRowsFor(
+      rowsHeldBudget(rows),
       symbolTableSize,
       totalRows,
       columnCount,
       materialisesRows,
       includeExternal
-    );
+    ), "fitting");
+    const firstGuess = fitting(liveRows);
+    const over = fitting(firstGuess);
+    const under = fitting(over);
+    const recommendedMaxRows = Math.max(firstGuess, under);
     const sizeMB = Math.round(symbolTableSize / 1024 / 1024);
     const estimatedMB = Math.round(estimatedMemory / 1024 / 1024);
     const availableMB = Math.round(maxAllowedMemory / 1024 / 1024);
@@ -2261,15 +2269,20 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
     const observedBreakdown = budget.observed.map((entry) => `${entry.source} ${Math.round(entry.bytes / 1024 / 1024)}MB`).join(", ");
     const containerBound = binding.source === "container memory limit";
     const chunked = rowsLive !== null;
-    const recommendedChunk = chunked ? recommendedChunkFor(
-      maxAllowedMemory,
+    const chunkHeldBudget = /* @__PURE__ */ __name((rows) => maxAllowedMemory - (includeExternal ? heldForChunk(rows) : 0), "chunkHeldBudget");
+    const chunkFitting = /* @__PURE__ */ __name((rows) => recommendedChunkFor(
+      chunkHeldBudget(rows),
       symbolTableSize,
       maxRows,
       totalRows,
       columnCount,
       liveRowsPerChunk,
       includeExternal
-    ) : 0;
+    ), "chunkFitting");
+    const callersChunk = chunked ? Math.max(1, Math.floor(rowsLive / Math.max(1, liveRowsPerChunk))) : 0;
+    const firstChunk = chunked ? chunkFitting(callersChunk) : 0;
+    const overChunk = chunked ? chunkFitting(firstChunk) : 0;
+    const recommendedChunk = chunked ? Math.max(firstChunk, chunkFitting(overChunk)) : 0;
     const knob = chunked ? "chunkSize" : "limit";
     const recommendedValue = chunked ? recommendedChunk : recommendedMaxRows;
     const nothingFits = recommendedValue === 0;
@@ -2464,6 +2477,7 @@ function validateSymbolTableSize(symbolTableLength, filePath, totalRows) {
 function validateFieldMetadata(field, symbolBufferLength, filePath) {
   const symbolsOffset = headerInteger(field["Offset"]);
   const symbolsLength = headerInteger(field["Length"]);
+  const symbolCount = headerInteger(field["NoOfSymbols"]);
   if (isNaN(symbolsOffset) || !Number.isSafeInteger(symbolsOffset) || symbolsOffset < 0) {
     throw new QvdCorruptedError("Invalid symbol offset", {
       field: field["FieldName"],
@@ -2480,6 +2494,14 @@ function validateFieldMetadata(field, symbolBufferLength, filePath) {
       stage: "parseSymbolTable"
     });
   }
+  if (isNaN(symbolCount) || !Number.isSafeInteger(symbolCount) || symbolCount < 0) {
+    throw new QvdCorruptedError("Invalid symbol count", {
+      field: field["FieldName"],
+      noOfSymbols: symbolCount,
+      file: filePath,
+      stage: "parseSymbolTable"
+    });
+  }
   if (symbolsOffset + symbolsLength > symbolBufferLength) {
     throw new QvdCorruptedError("Symbol data extends beyond buffer", {
       field: field["FieldName"],
@@ -2735,12 +2757,25 @@ var init_validationUtils = __esm({
     __name(validateFieldBitMetadata, "validateFieldBitMetadata");
   }
 });
-
-// src/util/symbolParser.js
-function textEnd(symbolBuffer, from, kind, fieldName, filePath) {
-  const bufferLength = symbolBuffer.length;
-  const found = symbolBuffer.indexOf(0, from);
-  if ((found === -1 ? bufferLength : found) - from > MAX_TEXT_BYTES) {
+function nulFinder(area, { reach, rebaseAfter }) {
+  assert4(reach - rebaseAfter > MAX_TEXT_BYTES, "A text search view must hold the longest text a symbol may have.");
+  if (area.length <= reach) {
+    return (from) => area.indexOf(0, from);
+  }
+  let base = 0;
+  let view = area.subarray(0, reach);
+  return (from) => {
+    if (from - base > rebaseAfter) {
+      base = from;
+      view = area.subarray(base, Math.min(area.length, base + reach));
+    }
+    const found = view.indexOf(0, from - base);
+    return found === -1 ? -1 : base + found;
+  };
+}
+function textEnd(findNul, areaEnd, from, kind, fieldName, filePath, base) {
+  const found = findNul(from);
+  if ((found === -1 ? areaEnd : found) - from > MAX_TEXT_BYTES) {
     throw new QvdCorruptedError(`${kind} exceeds maximum length`, {
       field: fieldName,
       maxLength: MAX_TEXT_BYTES,
@@ -2751,58 +2786,59 @@ function textEnd(symbolBuffer, from, kind, fieldName, filePath) {
   if (found === -1) {
     throw new QvdCorruptedError(`${kind} not null-terminated`, {
       field: fieldName,
-      pointer: bufferLength,
-      bufferSize: bufferLength,
+      pointer: base + from,
+      areaEnd: base + areaEnd,
       file: filePath,
       stage: "parseSymbolTable"
     });
   }
   return found;
 }
-function overflow(message, pointer, bufferLength, fieldName, filePath) {
+function overflow(message, pointer, areaEnd, fieldName, filePath, base) {
   throw new QvdCorruptedError(message, {
     field: fieldName,
-    pointer,
-    bufferSize: bufferLength,
+    pointer: base + pointer,
+    areaEnd: base + areaEnd,
     file: filePath,
     stage: "parseSymbolTable"
   });
 }
-function parseFieldSymbols(symbolBuffer, start, end, keep, fieldName, filePath) {
-  const bufferLength = symbolBuffer.length;
+function parseFieldSymbols(symbolBuffer, start, end, symbolCount, keep, fieldName, filePath, search = TEXT_SEARCH, base = 0) {
+  const area = symbolBuffer.subarray(0, end);
+  const findNul = nulFinder(area, search);
   const numbers = [];
   const texts = [];
   let pointer = start;
   while (pointer < end) {
-    const typeByte = symbolBuffer[pointer++];
+    const typeByte = area[pointer++];
     const decode = keep === null || keep.has(numbers.length);
     let number = null;
     let text = null;
     switch (typeByte) {
       case 1: {
+        if (pointer + 4 > end) {
+          overflow("Buffer overflow reading integer symbol", pointer, end, fieldName, filePath, base);
+        }
         if (decode) {
-          if (pointer + 4 > bufferLength) {
-            overflow("Buffer overflow reading integer symbol", pointer, bufferLength, fieldName, filePath);
-          }
-          number = symbolBuffer.readInt32LE(pointer);
+          number = area.readInt32LE(pointer);
         }
         pointer += 4;
         break;
       }
       case 2: {
+        if (pointer + 8 > end) {
+          overflow("Buffer overflow reading double symbol", pointer, end, fieldName, filePath, base);
+        }
         if (decode) {
-          if (pointer + 8 > bufferLength) {
-            overflow("Buffer overflow reading double symbol", pointer, bufferLength, fieldName, filePath);
-          }
-          number = symbolBuffer.readDoubleLE(pointer);
+          number = area.readDoubleLE(pointer);
         }
         pointer += 8;
         break;
       }
       case 4: {
-        const terminator = textEnd(symbolBuffer, pointer, "String symbol", fieldName, filePath);
+        const terminator = textEnd(findNul, end, pointer, "String symbol", fieldName, filePath, base);
         if (decode) {
-          text = symbolBuffer.toString("utf8", pointer, terminator);
+          text = area.toString("utf8", pointer, terminator);
         }
         pointer = terminator + 1;
         break;
@@ -2810,14 +2846,22 @@ function parseFieldSymbols(symbolBuffer, start, end, keep, fieldName, filePath)
       case 5:
       case 6: {
         const numberBytes = typeByte === 5 ? 4 : 8;
-        if (pointer + numberBytes > bufferLength) {
-          const read = !decode ? "dual symbol" : typeByte === 5 ? "dual integer symbol" : "dual double symbol";
-          overflow(`Buffer overflow reading ${read}`, pointer, bufferLength, fieldName, filePath);
+        if (pointer + numberBytes > end) {
+          const read = typeByte === 5 ? "dual integer symbol" : "dual double symbol";
+          overflow(`Buffer overflow reading ${read}`, pointer, end, fieldName, filePath, base);
         }
-        const terminator = textEnd(symbolBuffer, pointer + numberBytes, "Dual string symbol", fieldName, filePath);
+        const terminator = textEnd(
+          findNul,
+          end,
+          pointer + numberBytes,
+          "Dual string symbol",
+          fieldName,
+          filePath,
+          base
+        );
         if (decode) {
-          number = typeByte === 5 ? symbolBuffer.readInt32LE(pointer) : symbolBuffer.readDoubleLE(pointer);
-          text = symbolBuffer.toString("utf8", pointer + numberBytes, terminator);
+          number = typeByte === 5 ? area.readInt32LE(pointer) : area.readDoubleLE(pointer);
+          text = area.toString("utf8", pointer + numberBytes, terminator);
         }
         pointer = terminator + 1;
         break;
@@ -2825,7 +2869,7 @@ function parseFieldSymbols(symbolBuffer, start, end, keep, fieldName, filePath)
       default: {
         throw new QvdParseError("Unknown symbol type byte", {
           typeByte: typeByte.toString(16),
-          offset: pointer - 1,
+          offset: base + pointer - 1,
           file: filePath,
           stage: "parseSymbolTable"
         });
@@ -2834,16 +2878,28 @@ function parseFieldSymbols(symbolBuffer, start, end, keep, fieldName, filePath)
     numbers.push(number);
     texts.push(text);
   }
+  assert4(pointer === end, `The symbols of ${fieldName} were walked to byte ${pointer} of an area ending at ${end}.`);
+  if (numbers.length !== symbolCount) {
+    throw new QvdCorruptedError("Symbol count mismatch", {
+      field: fieldName,
+      symbolCount: numbers.length,
+      noOfSymbols: symbolCount,
+      file: filePath,
+      stage: "parseSymbolTable"
+    });
+  }
   return { numbers, texts };
 }
-function countFieldSymbols(symbolBuffer, start, end, fieldName, filePath) {
-  return parseFieldSymbols(symbolBuffer, start, end, DECODE_NOTHING, fieldName, filePath).numbers.length;
+function countFieldSymbols(symbolBuffer, start, end, symbolCount, fieldName, filePath, base = 0) {
+  return parseFieldSymbols(symbolBuffer, start, end, symbolCount, DECODE_NOTHING, fieldName, filePath, void 0, base).numbers.length;
 }
-var MAX_TEXT_BYTES, DECODE_NOTHING;
+var MAX_TEXT_BYTES, TEXT_SEARCH, DECODE_NOTHING;
 var init_symbolParser = __esm({
   "src/util/symbolParser.js"() {
     init_QvdErrors();
     MAX_TEXT_BYTES = 1048576;
+    TEXT_SEARCH = Object.freeze({ reach: 2 ** 31 - 1, rebaseAfter: 2 ** 30 });
+    __name(nulFinder, "nulFinder");
     __name(textEnd, "textEnd");
     __name(overflow, "overflow");
     __name(parseFieldSymbols, "parseFieldSymbols");
@@ -3387,7 +3443,7 @@ async function parseHeaderXml(text, file, stage) {
   }
   return parsed;
 }
-var MAX_HEADER_SIZE, READ_CHUNK_SIZE, ANALYSIS_SLICE_ROWS, COUNT_SYMBOLS_PAST, QvdFileReader;
+var MAX_HEADER_SIZE, READ_CHUNK_SIZE, ANALYSIS_SLICE_ROWS, SLICE_BYTES, COUNT_SYMBOLS_PAST, QvdFileReader;
 var init_QvdFileReader = __esm({
   "src/QvdFileReader.js"() {
     init_QvdDataFrame();
@@ -3405,6 +3461,7 @@ var init_QvdFileReader = __esm({
     MAX_HEADER_SIZE = 16 * 1024 * 1024;
     READ_CHUNK_SIZE = 512 * 1024 * 1024;
     ANALYSIS_SLICE_ROWS = 65536;
+    SLICE_BYTES = 16 * 1024 * 1024;
     COUNT_SYMBOLS_PAST = 65536;
     __name(chunksFrom, "chunksFrom");
     __name(parseHeaderXml, "parseHeaderXml");
@@ -3436,6 +3493,10 @@ var init_QvdFileReader = __esm({
        *   above which a lazy load switches to the two-pass filtering path. The default of 50MB is
        *   the point where the extra analysis pass pays for itself; lower it to use filtering on
        *   smaller files, raise it to keep the simpler single-pass read for longer.
+       * @param {number} [options.sliceBytes=16777216] The most bytes of records a read holds at a time. An
+       *   option rather than a constant for the reason `symbolFilteringThreshold` is one: so that a test can
+       *   cross the boundaries between slices in a small file. There is no other reason to change it, and it
+       *   is not one of the options a read through `QvdDataFrame` or `QvdColumnTable` passes on.
        * @param {Array<string>|null} [options.fields] Field names to read, in the order they should
        *   appear. Null reads every field, in file order. An unknown or repeated name is refused.
        * @param {'number'|'text'|'both'} [options.duals='number'] What a dual symbol - a number with the
@@ -3460,6 +3521,7 @@ var init_QvdFileReader = __esm({
           allowedDir,
           memorySafetyFactor = 0.8,
           symbolFilteringThreshold = 50 * 1024 * 1024,
+          sliceBytes = SLICE_BYTES,
           materialisesRows = true,
           fields = null,
           duals,
@@ -3475,6 +3537,14 @@ var init_QvdFileReader = __esm({
         this._coerceNumericStrings = normaliseCoerceNumericStrings(coerceNumericStrings, this._path);
         this._memorySafetyFactor = memorySafetyFactor;
         this._symbolFilteringThreshold = symbolFilteringThreshold;
+        if (!Number.isSafeInteger(sliceBytes) || sliceBytes <= 0) {
+          throw new QvdValidationError("sliceBytes must be a positive integer", {
+            provided: sliceBytes,
+            type: typeof sliceBytes,
+            file: this._path
+          });
+        }
+        this._sliceBytes = sliceBytes;
         if (onProgress !== void 0 && typeof onProgress !== "function") {
           throw new QvdValidationError("onProgress must be a function", {
             provided: onProgress,
@@ -3492,7 +3562,11 @@ var init_QvdFileReader = __esm({
         this._requestedFields = fields === void 0 ? null : fields;
         this._onProgress = onProgress;
         this._signal = signal;
-        this._buffer = null;
+        this._headerBuffer = null;
+        this._handle = null;
+        this._failed = null;
+        this._reading = false;
+        this._symbolAreas = null;
         this._headerOffset = null;
         this._symbolTableOffset = null;
         this._indexTableOffset = null;
@@ -3503,7 +3577,6 @@ var init_QvdFileReader = __esm({
         this._symbolTable = null;
         this._indexColumns = null;
         this._rowsDecoded = 0;
-        this._bufferFirstRow = 0;
         this._fileSize = null;
         this._headerMatchesFile = false;
       }
@@ -3542,54 +3615,137 @@ var init_QvdFileReader = __esm({
         }
       }
       /**
-       * Reads the binary data of the QVD file.
-       *
-       * A windowed read - anything with `offset`, `limit` or `maxRows` - reads only the bytes it
-       * needs, rather than the file. Measured on `chicago_taxi_rides_2016_01.qvd`, 1,705,805 rows
-       * over 20 fields: the last thousand rows take 19 ms against 636 ms for the whole file.
-       *
-       * The saving is in the index table and the rows, not in the symbol table, which is read in
-       * full whatever the window because a stored index in any row can address any symbol. So the
-       * gain scales with how much of the file is rows: on a file whose bytes are mostly distinct
-       * values there is very little to save, which is what `symbolFilteringThreshold` and the
-       * two-pass path exist for.
-       *
-       * Algorithm for a windowed read:
-       * 1. Read the file a chunk at a time until the XML header delimiter is found
-       * 2. Parse header to determine symbol table and index table locations
-       * 3. Calculate bytes needed: header + full symbol table + partial index table
-       * 4. Read only those calculated bytes, by position
-       * 5. Rest of parsing proceeds normally with limited data
-       *
-       * WHY THIS APPROACH:
-       * - Symbol table must be fully loaded (contains all unique values)
-       * - Index table can be partially loaded (only rows we need)
-       * - Reading chunks to find the header is efficient for unknown header sizes
-       * - Direct byte-range reading for remaining data is fastest
+       * Opens the file and reads its header, and for a read of rows checks that the read can be made.
+       *
+       * Nothing past the header is read here. The selected fields' symbols and the records are read by position
+       * as they are parsed - see `_symbolAreaOf` and `_forEachSlice` - so no read holds the file in one buffer
+       * (#122). A read of rows therefore leaves the file open, and whatever started the read closes it with
+       * `_closeFile` once the last record it needs is decoded; a header-only read closes it here.
+       *
+       * A windowed read - anything with `offset`, `limit` or `maxRows` - reads the header, the symbols of the
+       * fields it selects, and the window's records, and no byte between. Measured on
+       * `chicago_taxi_rides_2016_01.qvd`, 1,705,805 rows over 20 fields: the last thousand rows take 19 ms
+       * against 636 ms for the whole file. A selected field's area is read in full whatever the window,
+       * because a stored index in any row can address any of that field's symbols; the areas of the fields
+       * `fields` leaves out are not read at all. So a window's gain scales with how much of the file is
+       * rows: on a file whose bytes are mostly distinct values of the fields it reads there is very little
+       * to save, which is what `symbolFilteringThreshold` and the two-pass path exist for.
        *
        * All of it goes through one handle, opened once, on the file the containment check approved. See
        * `chunksFrom` and `openChecked` for why a read no longer opens the path more than once.
        *
-       * A window with a non-zero `offset` reads two ranges rather than one: the header and symbol
-       * table from the front of the file, and the window's records from wherever they sit. The bytes
-       * between are never read, which is what makes `{offset: 1_700_000, limit: 100}` on the taxi
-       * fixture a 0.4MB read rather than a 38MB one.
-       *
        * @param {QvdRowWindow} window The rows to read.
-       * @param {boolean} [headerOnly=false] Stop once the XML header has been read, leaving the
-       *   symbol and index tables on disk. This is the metadata-only path: the header is a few
-       *   kilobytes whatever the file's size, so reading a schema costs the same for a 40MB file as
-       *   for a 40GB one.
+       * @param {boolean} [headerOnly=false] Stop once the XML header has been read, and close the file. This
+       *   is the metadata-only path: the header is a few kilobytes whatever the file's size, so reading a
+       *   schema costs the same for a 40MB file as for a 40GB one.
        * @param {{rows: number, perChunk: number}|null} [liveRows=null] Rows held at one instant when
        *   that is fewer than the window covers - see `_prepare`.
        * @private
        */
       async _readData(window = { offset: 0, limit: null }, headerOnly = false, liveRows = null) {
+        assert4(this._reading, "A read opens the QVD file only once it has started, through _startRead.");
+        this._symbolTable = null;
+        this._indexColumns = null;
+        this._rowsDecoded = 0;
         this._throwIfAborted();
         this._emitProgress("read", 0, 1);
         const failed = rethrowAsIoError(this._path, "read");
         const handle = await openChecked(checkPath(this._path, this._allowedDir), "read", failed);
-        await closeAfter(handle, failed, () => this._readFrom(handle, window, headerOnly, liveRows, failed));
+        if (headerOnly) {
+          await closeAfter(handle, failed, () => this._readFrom(handle, window, true, liveRows, failed));
+          return;
+        }
+        this._handle = handle;
+        this._failed = failed;
+        try {
+          await this._readFrom(handle, window, false, liveRows, failed);
+        } catch (error) {
+          await this._closeFile(true);
+          throw error;
+        }
+      }
+      /**
+       * Starts a read on this reader, refusing it while another is under way.
+       *
+       * A read of rows holds the file, and what it has read of it, on the reader until it ends. A second read
+       * started meanwhile - `load()` while an iteration is suspended, say - would take over that state and
+       * leave the first read's file open. Reads one after another are fine. Called before a read takes charge
+       * of closing the file, so that refusing the second read cannot close the first one's.
+       *
+       * The first thing every read does, and synchronous: the flag is set before the read's first `await`, so
+       * two reads started together - `Promise.all([reader.load(), reader.load()])` - cannot both pass. The check
+       * used to be of the handle, which is set only once the file has opened, and both did: the second read's
+       * handle replaced the first's, which was never closed, and the first read to finish closed the file the
+       * other was still reading.
+       *
+       * @throws {QvdValidationError} If a read is under way.
+       * @private
+       */
+      _startRead() {
+        if (this._reading) {
+          throw new QvdValidationError("The reader is already reading this file: finish that read first", {
+            file: this._path
+          });
+        }
+        this._reading = true;
+      }
+      /**
+       * Ends the read `_startRead` began: closes its file, if it still holds one, and lets the next read start.
+       *
+       * @param {boolean} failing Whether the read is already throwing - see `_closeFile`.
+       * @private
+       */
+      async _endRead(failing) {
+        try {
+          await this._closeFile(failing);
+        } finally {
+          this._reading = false;
+        }
+      }
+      /**
+       * Closes the file a read of rows opened, and drops what it had read of it.
+       *
+       * The rule `closeAfter` follows: a close that fails is reported only when the read succeeded, so it can
+       * never replace the error that says what went wrong. After a successful read it is the only news.
+       *
+       * @param {boolean} failing Whether the read is already throwing.
+       * @private
+       */
+      async _closeFile(failing) {
+        const handle = this._handle;
+        const failed = this._failed;
+        this._handle = null;
+        this._failed = null;
+        this._symbolAreas = null;
+        if (handle === null || failed === null) {
+          return;
+        }
+        if (failing) {
+          await handle.close().catch(() => {
+          });
+          return;
+        }
+        await handle.close().catch(failed);
+      }
+      /**
+       * Runs a read, the only one under way on this reader, and closes its file when it ends, however it ends.
+       *
+       * @template T
+       * @param {() => Promise<T>} read The read, from opening the file to its last record.
+       * @return {Promise<T>} What it returned.
+       * @private
+       */
+      async _closingAfter(read) {
+        this._startRead();
+        let result;
+        try {
+          result = await read();
+        } catch (error) {
+          await this._endRead(true);
+          throw error;
+        }
+        await this._endRead(false);
+        return result;
       }
       /**
        * Reads what `_readData` was asked for, through the handle it opened.
@@ -3651,50 +3807,57 @@ var init_QvdFileReader = __esm({
         const recordSize = headerInteger(headerObj["QvdTableHeader"]["RecordByteSize"]);
         const totalRows = headerInteger(headerObj["QvdTableHeader"]["NoOfRecords"]);
         if (headerOnly) {
-          this._buffer = headerBuffer.subarray(0, headerEndIndex);
+          this._headerBuffer = headerBuffer.subarray(0, headerEndIndex);
           this._emitProgress("read", 1, 1);
           return;
         }
-        const columnCount = selectFields(headerFields, this._requestedFields, this._path).length;
+        this._headerBuffer = headerBuffer.subarray(0, headerEndIndex);
+        const selected = selectFields(headerFields, this._requestedFields, this._path);
+        const columnCount = selected.length;
+        const areaBytes = selected.map((field) => headerInteger(field["Length"]));
+        const symbolBytes = areaBytes.every((bytes) => Number.isSafeInteger(bytes) && bytes >= 0) ? Math.min(
+          symbolTableLength,
+          areaBytes.reduce((sum, bytes) => sum + bytes, 0)
+        ) : symbolTableLength;
         const headerNumbersUsable = [symbolTableLength, recordSize, totalRows].every(
           (value) => Number.isSafeInteger(value) && value >= 0
         );
+        const { size: fileSize } = await handle.stat().catch(failed);
+        this._fileSize = fileSize;
+        this._headerMatchesFile = false;
         if (headerNumbersUsable) {
-          const { size: fileSize2 } = await handle.stat().catch(failed);
-          this._fileSize = fileSize2;
-          this._headerMatchesFile = headerEndIndex + symbolTableLength + totalRows * recordSize <= fileSize2;
+          this._headerMatchesFile = headerEndIndex + symbolTableLength + totalRows * recordSize <= fileSize;
         }
         const resolved = headerNumbersUsable ? resolveWindow(window, totalRows) : { offset: 0, limit: 0 };
         const windowRows = resolved.limit;
         if (headerNumbersUsable && this._headerMatchesFile) {
           validateMemoryAvailability(
-            symbolTableLength,
+            symbolBytes,
             windowRows,
             totalRows,
             this._path,
             this._memorySafetyFactor,
             columnCount,
             this._materialisesRows,
-            liveRows
+            liveRows,
+            this._bytesHeld(
+              symbolBytes,
+              windowRows,
+              recordSize,
+              liveRows,
+              this._analysisWouldRun(window, resolved, totalRows, symbolTableLength)
+            )
           );
         }
         if (window.offset === 0 && window.limit === null) {
-          this._buffer = await handle.readFile().catch(failed);
-          this._fileSize = this._buffer.length;
-          this._bufferFirstRow = 0;
           this._emitProgress("read", 1, 1);
           return;
         }
         const rowsToLoad = windowRows;
-        validateSymbolTableSizeEarly(symbolTableLength, this._path);
+        validateSymbolTableSizeEarly(symbolBytes, this._path);
         validateRecordSize(recordSize, this._path, "readData");
         validateRecordCount(totalRows, this._path, "readData");
-        const skippedIndexBytes = resolved.offset * recordSize;
-        const indexTableBytesToRead = rowsToLoad * recordSize;
-        const totalBytesToRead = indexTableOffset + indexTableBytesToRead;
-        const fileBytesRequired = indexTableOffset + skippedIndexBytes + indexTableBytesToRead;
-        const { size: fileSize } = await handle.stat().catch(failed);
-        this._fileSize = fileSize;
+        const fileBytesRequired = indexTableOffset + (resolved.offset + rowsToLoad) * recordSize;
         if (fileBytesRequired > fileSize) {
           throw new QvdCorruptedError("The file is shorter than its header claims.", {
             file: this._path,
@@ -3703,47 +3866,35 @@ var init_QvdFileReader = __esm({
             stage: "readData"
           });
         }
-        this._buffer = Buffer.alloc(totalBytesToRead);
-        await this._readRange(handle, 0, indexTableOffset, 0, fileSize, totalBytesToRead);
-        if (indexTableBytesToRead > 0) {
-          await this._readRange(
-            handle,
-            indexTableOffset,
-            indexTableBytesToRead,
-            indexTableOffset + skippedIndexBytes,
-            fileSize,
-            fileBytesRequired
-          );
-        }
-        this._bufferFirstRow = resolved.offset;
         this._emitProgress("read", 1, 1);
       }
       /**
-       * Reads one byte range of the file into the buffer.
+       * Reads one byte range of the open file into a buffer.
        *
        * Read in bounded chunks, checking bytesRead each time. A single fs.read call with a length of
        * 2^31 or more does not throw - it trips a C++ assertion and aborts the whole process, which no
        * try/catch can intercept.
        *
-       * @param {import('fs/promises').FileHandle} fd The open file.
-       * @param {number} bufferOffset Where in the buffer to write.
+       * @param {Buffer} target The buffer to read into.
+       * @param {number} targetOffset Where in it to write.
        * @param {number} byteCount How many bytes to read.
        * @param {number} filePosition Where in the file to read from.
-       * @param {number} fileSize The file's size, for the error.
-       * @param {number} requiredBytes Bytes the whole read needs, for the error.
+       * @param {number} requiredBytes How far into the file the read has to reach, for the error.
+       * @throws {QvdCorruptedError} If the file ends before the range does.
        * @private
        */
-      async _readRange(fd, bufferOffset, byteCount, filePosition, fileSize, requiredBytes) {
-        assert3(this._buffer, "The read buffer has not been allocated.");
-        const failed = rethrowAsIoError(this._path, "read");
+      async _readAt(target, targetOffset, byteCount, filePosition, requiredBytes) {
+        assert4(this._handle && this._failed, "The QVD file is not open.");
+        const handle = this._handle;
+        const failed = this._failed;
         let done = 0;
         while (done < byteCount) {
           const length = Math.min(READ_CHUNK_SIZE, byteCount - done);
-          const { bytesRead } = await fd.read(this._buffer, bufferOffset + done, length, filePosition + done).catch(failed);
+          const { bytesRead } = await handle.read(target, targetOffset + done, length, filePosition + done).catch(failed);
           if (bytesRead === 0) {
             throw new QvdCorruptedError("Unexpected end of file while reading QVD data.", {
               file: this._path,
-              fileSize,
+              fileSize: this._fileSize,
               // Two numbers, because they stopped being the same one when a window began reading two
               // ranges: `bytesRead` is how much of this range arrived, `filePosition` is where in the
               // file it gave up. Reporting the position under the name of the count made a windowed
@@ -3758,12 +3909,262 @@ var init_QvdFileReader = __esm({
           done += bytesRead;
         }
       }
+      /**
+       * Bytes of the file a read holds outside the heap while it works, beside the codes the guard counts for
+       * itself: the symbol areas it reads, and the one buffer its records come through.
+       *
+       * The areas are counted whole, although the read lets each range go once its fields are parsed, because
+       * two ranges are both live when a field of one is parsed between two fields of the other - the order the
+       * caller asked for the fields decides it, so the sum is what holds in every order. The slice is what
+       * `_forEachSlice` will allocate: `sliceBytes` unless the records are fewer.
+       *
+       * @param {number} symbolBytes Bytes of symbols the read will read.
+       * @param {number} rows Records it will read.
+       * @param {number} recordSize Bytes per record.
+       * @return {number} Bytes.
+       * @private
+       */
+      _bytesHeldBy(symbolBytes, rows, recordSize) {
+        const records = Number.isSafeInteger(rows) && Number.isSafeInteger(recordSize) ? rows * recordSize : 0;
+        return symbolBytes + Math.min(this._sliceBytes, Math.max(0, records));
+      }
+      /**
+       * What a read holds in bytes of the file, for the memory guard: what it holds now, and what a read
+       * following either piece of advice a refusal can carry would hold instead.
+       *
+       * The two knobs are not the same knob, which is why there are two functions rather than one. A smaller
+       * `limit` is a smaller window, so every record the read touches is one of fewer - the symbol-usage pass
+       * included, since it reads the window. A smaller `chunkSize` leaves the window exactly where it is and
+       * only changes how much of it is decoded at a time, so a read with that pass still ahead of it holds the
+       * window's slice however small the chunk. Priced with `forRows`, such a chunk was charged for the records
+       * of one chunk and then held sixteen megabytes more than that.
+       *
+       * @param {number} symbolBytes Bytes of symbols the read will read.
+       * @param {number} windowRows Rows the read covers.
+       * @param {number} recordSize Bytes per record.
+       * @param {{rows: number, perChunk: number}|null} liveRows Rows held at one instant - see `_prepare`.
+       * @param {boolean} analysisAhead Whether the symbol-usage pass has still to run.
+       * @return {{held: number, forRows: (rows: number) => number, forChunk: (rows: number) => number}} What
+       *   this read holds, what a read of so many rows would hold, and what one reading so many rows a chunk
+       *   would hold.
+       * @private
+       */
+      _bytesHeld(symbolBytes, windowRows, recordSize, liveRows, analysisAhead) {
+        return {
+          held: this._bytesHeldBy(symbolBytes, this._recordsAtOnce(windowRows, liveRows, analysisAhead), recordSize),
+          // A window of so many rows reads so many records at a time, and the pass that reads it ahead of the
+          // decode reads the same rows, so the buffer is sized from the rows either way.
+          forRows: /* @__PURE__ */ __name((rows) => this._bytesHeldBy(symbolBytes, rows, recordSize), "forRows"),
+          // A chunk of so many rows, over this read's window - which is what `chunkSize` changes and what it
+          // leaves alone. `_recordsAtOnce` is what answers that, given a chunk size as the rows held at once.
+          forChunk: /* @__PURE__ */ __name((rows) => this._bytesHeldBy(symbolBytes, this._recordsAtOnce(windowRows, { rows, perChunk: 1 }, analysisAhead), recordSize), "forChunk")
+        };
+      }
+      /**
+       * Whether a read takes the symbol-usage pass, which reads the window's records before the symbol table
+       * is parsed and so before the first chunk is built.
+       *
+       * The one statement of the condition. `_prepare` asks it to decide, and `_readData` asks it before the
+       * header has been parsed, to know what to charge the memory guard: a read with the pass ahead of it
+       * holds a whole slice of records, and a read without it holds only what it reads at a time. Said in two
+       * places, the two would drift and a read would be charged for one path and take the other - which fails
+       * open for a chunked read, and that is the direction the guard exists to prevent.
+       *
+       * Any window that does not cover the whole file is a candidate, which includes one bounded by its offset
+       * rather than by its limit. Covering every row rules it out, however the window was spelled -
+       * `{offset: 0, limit: n}` over all n rows, or an `iterate` of them. Such a read needs every symbol any
+       * row uses, which is what `estimateMemoryUsage` assumes for a full read as well, so the pass has nothing
+       * to filter. It is not free: since the records are read as they are decoded rather than held in one
+       * buffer, the pass reads the window's records and the decode then reads them again. A window that really
+       * is a window pays that for the symbols it saves parsing; a window that is a full read in disguise paid
+       * it for nothing.
+       *
+       * The threshold is an option rather than a constant so this path can be exercised with a small fixture:
+       * it is the most intricate code in the reader, and the only files large enough to reach the 50MB default
+       * are ones no repository should be carrying around. It measures the whole table rather than the areas a
+       * read selects, because what the pass saves is parsing work across the table.
+       *
+       * @param {QvdRowWindow} window The window as the caller spelled it.
+       * @param {{offset: number, limit: number}} resolved Where it lands in this file.
+       * @param {number} totalRows Rows the file declares.
+       * @param {number} symbolTableLength The symbol table's declared length.
+       * @return {boolean} Whether the pass will run.
+       * @private
+       */
+      _analysisWouldRun(window, resolved, totalRows, symbolTableLength) {
+        return resolved.limit < totalRows && (window.limit !== null || window.offset > 0) && symbolTableLength > this._symbolFilteringThreshold;
+      }
+      /**
+       * Records a read holds at one time, which is what its record buffer is sized from.
+       *
+       * A slice holds `sliceBytes` of records, or every record the read has left to read when that is fewer -
+       * so what it costs depends on how many a read asks for at a time, not on how many it covers. An
+       * iteration asks for a chunk: `iterate({limit: 20_000_000, chunkSize: 1000})` reads a thousand records at
+       * a time however many its window covers, and charging it a full slice would refuse it for 16 MiB it never
+       * allocates. The symbol-usage pass is the exception, because it reads the whole window in slices of its
+       * own before the first chunk is built, so a read that still has that pass ahead of it is charged for it.
+       *
+       * @param {number} windowRows Rows the read covers.
+       * @param {{rows: number, perChunk: number}|null} liveRows Rows held at one instant - see `_prepare`.
+       * @param {boolean} analysisAhead Whether the symbol-usage pass has still to run.
+       * @return {number} Records read at one time.
+       * @private
+       */
+      _recordsAtOnce(windowRows, liveRows, analysisAhead) {
+        const chunkRows = liveRows === null ? windowRows : Math.max(1, Math.floor(liveRows.rows / Math.max(1, liveRows.perChunk)));
+        return analysisAhead ? Math.max(windowRows, chunkRows) : chunkRows;
+      }
+      /**
+       * The symbol table's length, as much of it as the file holds: what the header declares, cut short where
+       * the file ends. Known before a byte of the table is read, so everything that can refuse the table is
+       * checked on this, before the table is allocated.
+       *
+       * A file that ends inside its symbol table is measured to where it ends, and the fields whose areas it cut
+       * short are refused as `Symbol data extends beyond buffer` when their metadata is checked - what a
+       * whole-file read has always said of such a file. A window has refused it already, before reading anything.
+       *
+       * @return {number} Bytes.
+       * @private
+       */
+      _symbolTableLength() {
+        assert4(
+          this._symbolTableOffset !== null && this._indexTableOffset !== null && this._fileSize !== null,
+          "The QVD file header has not been parsed before its symbol table was measured."
+        );
+        const declared = this._indexTableOffset - this._symbolTableOffset;
+        return Math.max(0, Math.min(declared, this._fileSize - this._symbolTableOffset));
+      }
+      /**
+       * Where each selected field's symbols are, as ranges of the symbol table this read will read.
+       *
+       * A field's `Offset` and `Length` say exactly where its symbols are, so a read of some of a file's fields
+       * has no reason to read the areas of the rest (#122). Qlik writes the areas one after another in field
+       * order, so ranges that touch are merged: a read of every field is one range, and so is a read of fields
+       * that happen to be neighbours. A read of one field of twenty reads that field's area alone.
+       *
+       * Built once per read, from the fields the read selected, and each field's metadata is checked as it is
+       * added - a range is arithmetic on `Offset` and `Length`, and those have to be inside the table first.
+       * `_parseSymbolTable` checks every field of the file, selected or not, before it parses any.
+       *
+       * @return {{ranges: Array<{start: number, end: number, fields: number, buffer: Buffer|null}>,
+       *   byField: Map<any, {range: {start: number, end: number, fields: number, buffer: Buffer|null},
+       *   start: number, end: number}>}} The ranges, and where in its range each field's area sits.
+       * @private
+       */
+      _symbolAreaPlan() {
+        if (this._symbolAreas !== null) {
+          return this._symbolAreas;
+        }
+        assert4(this._selectedFields, "The QVD file fields have not been resolved before their symbols were read.");
+        const tableLength = this._symbolTableLength();
+        const areas = this._selectedFields.map((field) => {
+          validateFieldMetadata(field, tableLength, this._path);
+          const start = headerInteger(field["Offset"]);
+          return { field, start, end: start + headerInteger(field["Length"]) };
+        });
+        const ranges = [];
+        const byField = /* @__PURE__ */ new Map();
+        for (const area of [...areas].sort((a, b) => a.start - b.start)) {
+          const last = ranges.at(-1);
+          const range = last !== void 0 && area.start <= last.end ? last : { start: area.start, end: area.end, fields: 0, buffer: null };
+          if (range !== last) {
+            ranges.push(range);
+          }
+          range.end = Math.max(range.end, area.end);
+          range.fields += 1;
+          byField.set(area.field, { range, start: area.start, end: area.end });
+        }
+        this._symbolAreas = { ranges, byField };
+        return this._symbolAreas;
+      }
+      /**
+       * One field's symbols, as bytes: the range that holds them, read from the open file the first time a field
+       * of that range needs it.
+       *
+       * @param {any} field The field, one this read selected.
+       * @return {Promise<{buffer: Buffer, start: number, end: number, base: number}>} Its area, as a range of
+       *   `buffer`, with where that buffer starts in the symbol table - what an error adds back to say where a
+       *   damaged symbol is in the file, rather than where it is in the bytes this read happened to read.
+       * @throws {QvdValidationError} If the range is larger than half the heap.
+       * @private
+       */
+      async _symbolAreaOf(field) {
+        assert4(
+          this._header && this._symbolTableOffset !== null,
+          "The QVD file header has not been parsed before its symbols were read."
+        );
+        const area = this._symbolAreaPlan().byField.get(field);
+        assert4(area, "A field this read did not select has no symbol area.");
+        const { range } = area;
+        if (range.buffer === null) {
+          const length = range.end - range.start;
+          validateSymbolTableSize(length, this._path, headerInteger(this._header["QvdTableHeader"]["NoOfRecords"]));
+          const buffer = Buffer.alloc(length);
+          const from = this._symbolTableOffset + range.start;
+          await this._readAt(buffer, 0, length, from, from + length);
+          range.buffer = buffer;
+        }
+        return { buffer: range.buffer, start: area.start - range.start, end: area.end - range.start, base: range.start };
+      }
+      /**
+       * Lets go of a field's symbols once they are parsed, and of the bytes of its range once every field in it
+       * has been.
+       *
+       * Every text is copied out of the bytes as it is decoded, so what the read keeps is the values. A read of
+       * one field of a file whose other fields are large therefore holds that field's bytes and no others.
+       *
+       * @param {any} field The field whose symbols are parsed.
+       * @private
+       */
+      _releaseSymbolArea(field) {
+        const area = this._symbolAreaPlan().byField.get(field);
+        assert4(area, "A field this read did not select has no symbol area.");
+        area.range.fields -= 1;
+        if (area.range.fields === 0) {
+          area.range.buffer = null;
+        }
+      }
+      /**
+       * Reads records from the open file a slice at a time, and hands each slice to `visit`.
+       *
+       * One buffer of at most `sliceBytes` holds a slice, and is reused for the next one, so a read of any
+       * number of records holds that much of them and no more. Cancellation is checked before each slice.
+       *
+       * @param {number} firstRow The file row of the first record.
+       * @param {number} rowCount How many records.
+       * @param {number} recordSize Bytes per record.
+       * @param {(slice: Buffer, done: number, count: number) => void|Promise<void>} visit Called with each
+       *   slice's records, how many records came before it, and how many it holds.
+       * @private
+       */
+      async _forEachSlice(firstRow, rowCount, recordSize, visit) {
+        if (rowCount === 0) {
+          return;
+        }
+        assert4(this._indexTableOffset !== null, "The QVD file header has not been parsed before its records were read.");
+        const sliceRows = Math.max(1, Math.min(rowCount, Math.floor(this._sliceBytes / Math.max(1, recordSize))));
+        const slice = Buffer.alloc(sliceRows * recordSize);
+        const requiredBytes = this._indexTableOffset + (firstRow + rowCount) * recordSize;
+        for (let done = 0; done < rowCount; done += sliceRows) {
+          this._throwIfAborted();
+          const count = Math.min(sliceRows, rowCount - done);
+          const records = slice.subarray(0, count * recordSize);
+          await this._readAt(
+            records,
+            0,
+            records.length,
+            this._indexTableOffset + (firstRow + done) * recordSize,
+            requiredBytes
+          );
+          await visit(records, done, count);
+        }
+      }
       /**
        * Parses the XML header of the QVD file. This method is part of the parsing process
        * and should not be called directly.
        */
       async _parseHeader() {
-        if (!this._buffer) {
+        if (!this._headerBuffer) {
           throw new QvdCorruptedError(
             "The QVD file has not been loaded in the proper order or has not been loaded at all.",
             {
@@ -3774,7 +4175,7 @@ var init_QvdFileReader = __esm({
         }
         const HEADER_DELIMITER = "\r\n\0";
         const headerBeginIndex = 0;
-        const headerDelimiterIndex = this._buffer.indexOf(HEADER_DELIMITER, headerBeginIndex);
+        const headerDelimiterIndex = this._headerBuffer.indexOf(HEADER_DELIMITER, headerBeginIndex);
         if (headerDelimiterIndex === -1) {
           throw new QvdCorruptedError(
             "The XML header section does not exist or is not properly delimited from the binary data.",
@@ -3785,7 +4186,7 @@ var init_QvdFileReader = __esm({
           );
         }
         const headerEndIndex = headerDelimiterIndex + HEADER_DELIMITER.length;
-        const headerBuffer = this._buffer.subarray(headerBeginIndex, headerEndIndex);
+        const headerBuffer = this._headerBuffer.subarray(headerBeginIndex, headerEndIndex);
         this._fieldBitMetadataValidated = false;
         this._header = await parseHeaderXml(headerBuffer.toString(), this._path, "parseHeader");
         const fieldList = validateHeaderStructure(this._header, this._path, "parseHeader");
@@ -3807,12 +4208,12 @@ var init_QvdFileReader = __esm({
        * @param {QvdRowWindow} window The rows of interest, as file row indices.
        * @param {string} stage Stage name for any error raised here.
        * @return {{fields: Array<any>, recordSize: number, totalRows: number, rowsToLoad: number,
-       *   indexBuffer: Buffer, firstRow: number}} The record geometry. `indexBuffer` starts at the
-       *   window's first record, file row `firstRow`, so the decoder always counts from zero.
+       *   firstRow: number}} The record geometry: the window's `rowsToLoad` records start at file row
+       *   `firstRow`, and `_forEachSlice` reads them.
        * @private
        */
       _planIndexTable(window, stage) {
-        if (!this._buffer || !this._header || !this._indexTableOffset || !this._selectedFields || !this._allFields) {
+        if (!this._handle || !this._header || !this._indexTableOffset || !this._selectedFields || !this._allFields) {
           throw new QvdCorruptedError(
             "The QVD file has not been loaded in the proper order or has not been loaded at all.",
             {
@@ -3827,22 +4228,18 @@ var init_QvdFileReader = __esm({
         const totalRows = headerInteger(this._header["QvdTableHeader"]["NoOfRecords"]);
         const indexTableLength = headerInteger(this._header["QvdTableHeader"]["Length"]);
         const { offset: firstRow, limit: rowsToLoad } = resolveWindow(window, totalRows);
+        assert4(this._fileSize !== null, "The QVD file has not been measured before its records were planned.");
         validateIndexTableMetadata(
           recordSize,
           totalRows,
           indexTableLength,
           this._indexTableOffset,
-          this._buffer.length,
+          this._fileSize,
           rowsToLoad,
           this._path,
           this._fileSize,
           firstRow,
-          this._bufferFirstRow
-        );
-        const bufferRecordStart = (firstRow - this._bufferFirstRow) * recordSize;
-        const indexBuffer = this._buffer.subarray(
-          this._indexTableOffset + bufferRecordStart,
-          this._indexTableOffset + bufferRecordStart + rowsToLoad * recordSize
+          0
         );
         if (!this._fieldBitMetadataValidated) {
           for (const field of allFields) {
@@ -3851,11 +4248,12 @@ var init_QvdFileReader = __esm({
           validateBitFields(allFields, this._path);
           this._fieldBitMetadataValidated = true;
         }
-        assert3(
-          rowsToLoad === 0 || recordSize === 0 || Math.floor(indexBuffer.length / recordSize) >= rowsToLoad,
-          `The index table holds ${Math.floor(indexBuffer.length / (recordSize || 1))} whole records but ${rowsToLoad} were validated as present.`
+        const windowEnd = this._indexTableOffset + (firstRow + rowsToLoad) * recordSize;
+        assert4(
+          rowsToLoad === 0 || recordSize === 0 || windowEnd <= this._fileSize,
+          `The window's records end at byte ${windowEnd} of a file of ${this._fileSize}, but ${rowsToLoad} were validated as present.`
         );
-        return { fields, recordSize, totalRows, rowsToLoad, indexBuffer, firstRow };
+        return { fields, recordSize, totalRows, rowsToLoad, firstRow };
       }
       /**
        * Analyzes the index table to determine which symbols are actually needed.
@@ -3871,48 +4269,58 @@ var init_QvdFileReader = __esm({
        * @private
        */
       async _analyzeIndexTableSymbolUsage(window) {
-        const { fields, recordSize, rowsToLoad, indexBuffer } = this._planIndexTable(window, "analyzeIndexTableSymbolUsage");
+        const { fields, recordSize, rowsToLoad, firstRow } = this._planIndexTable(window, "analyzeIndexTableSymbolUsage");
         const symbolUsage = [];
         const sliceRows = Math.min(rowsToLoad, ANALYSIS_SLICE_ROWS);
         const column = new Int32Array(sliceRows);
-        fields.forEach((field, position) => {
-          this._throwIfAborted();
+        const state = fields.map((field) => {
           const needed = /* @__PURE__ */ new Set();
-          symbolUsage[position] = needed;
-          const bitOffset = headerInteger(field["BitOffset"]);
-          const bitWidth = headerInteger(field["BitWidth"]);
-          const bias = headerInteger(field["Bias"]);
+          symbolUsage.push(needed);
           const length = headerInteger(field["Length"]);
-          let indexLimit = Number.isSafeInteger(length) && length >= 0 ? Math.ceil(length / 2) : Infinity;
-          let counted = false;
-          for (let first = 0; first < rowsToLoad; first += sliceRows) {
-            const count = Math.min(sliceRows, rowsToLoad - first);
-            decodeIndexColumn(
-              first === 0 ? indexBuffer : indexBuffer.subarray(first * recordSize),
-              recordSize,
-              count,
-              bitOffset,
-              bitWidth,
-              bias,
-              column
-            );
-            for (let row = 0; row < count; row++) {
-              if (column[row] >= 0 && column[row] < indexLimit) {
-                needed.add(column[row]);
+          return {
+            field,
+            needed,
+            bitOffset: headerInteger(field["BitOffset"]),
+            bitWidth: headerInteger(field["BitWidth"]),
+            bias: headerInteger(field["Bias"]),
+            indexLimit: Number.isSafeInteger(length) && length >= 0 ? Math.ceil(length / 2) : Infinity,
+            counted: false
+          };
+        });
+        await this._forEachSlice(firstRow, rowsToLoad, recordSize, async (records, done, recordCount) => {
+          for (let first = 0; first < recordCount; first += sliceRows) {
+            const count = Math.min(sliceRows, recordCount - first);
+            for (const field of state) {
+              decodeIndexColumn(
+                first === 0 ? records : records.subarray(first * recordSize),
+                recordSize,
+                count,
+                field.bitOffset,
+                field.bitWidth,
+                field.bias,
+                column
+              );
+              for (let row = 0; row < count; row++) {
+                if (column[row] >= 0 && column[row] < field.indexLimit) {
+                  field.needed.add(column[row]);
+                }
               }
-            }
-            if (!counted && needed.size > COUNT_SYMBOLS_PAST) {
-              counted = true;
-              indexLimit = Math.min(indexLimit, this._countFieldSymbols(field));
-              for (const index of needed) {
-                if (index >= indexLimit) {
-                  needed.delete(index);
+              if (!field.counted && field.needed.size > COUNT_SYMBOLS_PAST) {
+                field.counted = true;
+                field.indexLimit = Math.min(field.indexLimit, await this._countFieldSymbols(field.field));
+                for (const index of field.needed) {
+                  if (index >= field.indexLimit) {
+                    field.needed.delete(index);
+                  }
                 }
               }
             }
           }
-          this._emitProgress("symbol-analysis", position + 1, fields.length);
+          this._emitProgress("symbol-analysis", done + recordCount, rowsToLoad);
         });
+        if (rowsToLoad === 0) {
+          this._emitProgress("symbol-analysis", 0, 0);
+        }
         return symbolUsage;
       }
       /**
@@ -3920,28 +4328,27 @@ var init_QvdFileReader = __esm({
        *
        * The count is `countFieldSymbols`, the parse itself told to decode nothing, so it is the count
        * `_parseSymbolTable` will produce and `_parseIndexTable` will check against. The field's area is
-       * validated first, as `_parseSymbolTable` would, so a damaged `Offset` or `Length` is reported the
-       * same way wherever it is met.
+       * validated before it is read, by `_symbolAreaPlan`, so a damaged `Offset`, `Length` or `NoOfSymbols` is
+       * reported the same way wherever it is met. Its bytes are kept for the parse that follows. The walk checks the count against `NoOfSymbols` as the
+       * parse does, so a field whose count is wrong is refused here, before the pass keeps anything on the
+       * strength of it.
        *
        * @param {any} field The field's header.
-       * @return {number} Its symbols.
-       * @throws {QvdCorruptedError} If the area is not inside the symbol table, or a symbol runs past it.
+       * @return {Promise<number>} Its symbols.
+       * @throws {QvdCorruptedError} If the area is not inside the symbol table, a symbol runs past it, or it
+       *   holds a different number of symbols from its `NoOfSymbols`.
        * @private
        */
-      _countFieldSymbols(field) {
-        assert3(
-          this._buffer && this._symbolTableOffset && this._indexTableOffset,
-          "The QVD file has not been read before its symbols were counted."
-        );
-        const symbolBuffer = this._buffer.subarray(this._symbolTableOffset, this._indexTableOffset);
-        validateFieldMetadata(field, symbolBuffer.length, this._path);
-        const offset = headerInteger(field["Offset"]);
+      async _countFieldSymbols(field) {
+        const area = await this._symbolAreaOf(field);
         return countFieldSymbols(
-          symbolBuffer,
-          offset,
-          offset + headerInteger(field["Length"]),
+          area.buffer,
+          area.start,
+          area.end,
+          headerInteger(field["NoOfSymbols"]),
           field["FieldName"],
-          this._path
+          this._path,
+          area.base
         );
       }
       /**
@@ -3961,7 +4368,7 @@ var init_QvdFileReader = __esm({
        *   that is fewer than the window covers - see `_prepare`.
        */
       async _parseSymbolTable(symbolsToKeep = null, rowsToLoad = 0, liveRows = null) {
-        if (!this._buffer || !this._header || !this._symbolTableOffset || !this._indexTableOffset || !this._selectedFields || !this._allFields) {
+        if (!this._handle || !this._header || !this._symbolTableOffset || !this._indexTableOffset || !this._selectedFields || !this._allFields) {
           throw new QvdCorruptedError(
             "The QVD file has not been loaded in the proper order or has not been loaded at all.",
             {
@@ -3972,44 +4379,55 @@ var init_QvdFileReader = __esm({
         }
         const allFields = this._allFields;
         const fields = this._selectedFields;
-        const symbolBuffer = this._buffer.subarray(this._symbolTableOffset, this._indexTableOffset);
-        const symbolTableSize = symbolBuffer.length;
+        const symbolTableSize = this._symbolTableLength();
+        const plan = this._symbolAreaPlan();
+        const symbolBytes = plan.ranges.reduce((sum, range) => sum + (range.end - range.start), 0);
         const totalRows = headerInteger(this._header["QvdTableHeader"]["NoOfRecords"]);
-        validateSymbolTableSize(symbolTableSize, this._path, totalRows);
+        const recordSize = headerInteger(this._header["QvdTableHeader"]["RecordByteSize"]);
+        validateSymbolTableSize(symbolBytes, this._path, totalRows);
         if (this._headerMatchesFile) {
           validateMemoryAvailability(
-            symbolTableSize,
+            symbolBytes,
             rowsToLoad,
             totalRows,
             this._path,
             this._memorySafetyFactor,
             fields.length,
             this._materialisesRows,
-            liveRows
+            liveRows,
+            this._bytesHeld(symbolBytes, rowsToLoad, recordSize, liveRows, false)
           );
         }
-        warnLargeSymbolTable(symbolTableSize, rowsToLoad, totalRows, fields.length, this._materialisesRows);
+        warnLargeSymbolTable(symbolBytes, rowsToLoad, totalRows, fields.length, this._materialisesRows);
         for (const field of allFields) {
-          validateFieldMetadata(field, symbolBuffer.length, this._path);
+          validateFieldMetadata(field, symbolTableSize, this._path);
         }
         validateSymbolAreas(allFields, this._path);
-        this._symbolTable = fields.map((field, position) => {
+        const symbolTable = [];
+        for (const [position, field] of fields.entries()) {
           this._throwIfAborted();
-          const symbolsOffset = headerInteger(field["Offset"]);
-          const symbolsLength = headerInteger(field["Length"]);
-          const symbols = parseFieldSymbols(
-            symbolBuffer,
-            symbolsOffset,
-            symbolsOffset + symbolsLength,
-            // By position, matching how `_analyzeIndexTableSymbolUsage` built it. Both walk
-            // `this._selectedFields`, so position is the one key that cannot collide.
-            symbolsToKeep ? symbolsToKeep[position] : null,
-            field["FieldName"],
-            this._path
+          const area = await this._symbolAreaOf(field);
+          symbolTable.push(
+            parseFieldSymbols(
+              area.buffer,
+              area.start,
+              area.end,
+              // Checked against the symbols the area holds, which is the one check that sees a terminator
+              // damaged in the middle of it (#124).
+              headerInteger(field["NoOfSymbols"]),
+              // By position, matching how `_analyzeIndexTableSymbolUsage` built it. Both walk
+              // `this._selectedFields`, so position is the one key that cannot collide.
+              symbolsToKeep ? symbolsToKeep[position] : null,
+              field["FieldName"],
+              this._path,
+              void 0,
+              area.base
+            )
           );
+          this._releaseSymbolArea(field);
           this._emitProgress("symbol-table", position + 1, fields.length);
-          return symbols;
-        });
+        }
+        this._symbolTable = symbolTable;
       }
       /**
        * Parses the bit stuffed index table of the QVD file. This method is part of the parsing process
@@ -4036,27 +4454,46 @@ var init_QvdFileReader = __esm({
        * straight to the caller. Rows outside the window are not decoded, so they are not checked.
        *
        * @param {QvdRowWindow} window The rows to decode.
+       * @param {number} [progressBase=0] Rows decoded before this call, so that progress over a chunked
+       *   iteration counts the whole window rather than restarting at every chunk - what `_buildRows` takes
+       *   for the same reason.
+       * @param {number|null} [progressTotal=null] Rows the whole window covers, or null for this call's own.
+       * @param {Array<Int32Array>|null} [into=null] Arrays to decode into, one per selected field and at least
+       *   `limit` long, for a caller that decodes chunk after chunk and keeps none of them. Null allocates.
        * @throws {QvdCorruptedError} If an index in the window addresses neither a symbol nor NULL.
        */
-      async _parseIndexTable(window) {
-        const { fields, recordSize, rowsToLoad, indexBuffer, firstRow } = this._planIndexTable(window, "parseIndexTable");
-        assert3(this._symbolTable, "The QVD file symbol table has not been parsed.");
+      async _parseIndexTable(window, progressBase = 0, progressTotal = null, into = null) {
+        const { fields, recordSize, rowsToLoad, firstRow } = this._planIndexTable(window, "parseIndexTable");
+        const decodedBefore = progressBase;
+        const decodedTotal = progressTotal === null ? rowsToLoad : progressTotal;
+        assert4(this._symbolTable, "The QVD file symbol table has not been parsed.");
         const symbolTable = this._symbolTable;
-        const columns = fields.map((field, position) => {
-          this._throwIfAborted();
-          const column = decodeIndexColumn(
-            indexBuffer,
-            recordSize,
-            rowsToLoad,
-            headerInteger(field["BitOffset"]),
-            headerInteger(field["BitWidth"]),
-            headerInteger(field["Bias"]),
-            new Int32Array(rowsToLoad),
-            { symbolCount: symbolTable[position].numbers.length, field: field["FieldName"], file: this._path, firstRow }
-          );
-          this._emitProgress("index-table", position + 1, fields.length);
-          return column;
+        const decoders = fields.map((field, position) => ({
+          bitOffset: headerInteger(field["BitOffset"]),
+          bitWidth: headerInteger(field["BitWidth"]),
+          bias: headerInteger(field["Bias"]),
+          symbolCount: symbolTable[position].numbers.length,
+          name: field["FieldName"]
+        }));
+        const columns = into === null ? fields.map(() => new Int32Array(rowsToLoad)) : into.map((codes) => codes.subarray(0, rowsToLoad));
+        await this._forEachSlice(firstRow, rowsToLoad, recordSize, (records, done, count) => {
+          decoders.forEach((decoder, position) => {
+            decodeIndexColumn(
+              records,
+              recordSize,
+              count,
+              decoder.bitOffset,
+              decoder.bitWidth,
+              decoder.bias,
+              columns[position].subarray(done, done + count),
+              { symbolCount: decoder.symbolCount, field: decoder.name, file: this._path, firstRow: firstRow + done }
+            );
+          });
+          this._emitProgress("index-table", decodedBefore + done + count, decodedTotal);
         });
+        if (rowsToLoad === 0) {
+          this._emitProgress("index-table", decodedBefore, decodedTotal);
+        }
         this._indexColumns = columns;
         this._rowsDecoded = rowsToLoad;
       }
@@ -4075,31 +4512,33 @@ var init_QvdFileReader = __esm({
        * @return {Promise<import('./QvdDataFrame.js').QvdFileMetadata>} The file's schema and header.
        */
       async loadMetadata() {
-        await this._readData({ offset: 0, limit: null }, true);
-        this._emitProgress("header", 0, 1);
-        await this._parseHeader();
-        this._emitProgress("header", 1, 1);
-        this._throwIfAborted();
-        assert3(this._header && this._allFields, "The QVD file header has not been parsed.");
-        const header = this._header["QvdTableHeader"];
-        const columns = this._allFields.map((field) => field["FieldName"]);
-        const rowCount = headerInteger(header["NoOfRecords"]);
-        validateRecordCount(rowCount, this._path, "readMetadata");
-        const shape = new QvdDataFrame([], columns, header, {
-          symbolTableBytes: headerInteger(header["Offset"]),
-          totalRows: rowCount,
-          rowsLoaded: 0,
-          symbolFiltering: false,
-          symbolsKept: null
+        return await this._closingAfter(async () => {
+          await this._readData({ offset: 0, limit: null }, true);
+          this._emitProgress("header", 0, 1);
+          await this._parseHeader();
+          this._emitProgress("header", 1, 1);
+          this._throwIfAborted();
+          assert4(this._header && this._allFields, "The QVD file header has not been parsed.");
+          const header = this._header["QvdTableHeader"];
+          const columns = this._allFields.map((field) => field["FieldName"]);
+          const rowCount = headerInteger(header["NoOfRecords"]);
+          validateRecordCount(rowCount, this._path, "readMetadata");
+          const shape = new QvdDataFrame([], columns, header, {
+            symbolTableBytes: headerInteger(header["Offset"]),
+            totalRows: rowCount,
+            rowsLoaded: 0,
+            symbolFiltering: false,
+            symbolsKept: null
+          });
+          return {
+            columns,
+            rowCount,
+            columnCount: columns.length,
+            fields: columns.map((name) => shape.getFieldMetadata(name)),
+            fileMetadata: shape.fileMetadata,
+            metadata: header
+          };
         });
-        return {
-          columns,
-          rowCount,
-          columnCount: columns.length,
-          fields: columns.map((name) => shape.getFieldMetadata(name)),
-          fileMetadata: shape.fileMetadata,
-          metadata: header
-        };
       }
       /**
        * Loads the QVD file into memory and parses it.
@@ -4114,19 +4553,21 @@ var init_QvdFileReader = __esm({
        */
       async load(window = null) {
         const rows = normaliseWindow(window, this._path);
-        const prepared = await this._prepare(rows);
-        await this._parseIndexTable({ offset: prepared.offset, limit: prepared.rowsAvailable });
-        const data = this._buildRows(prepared.resolvedByField, 0, prepared.rowsAvailable);
-        return new QvdDataFrame(
-          data,
-          prepared.columns,
-          prepared.metadata,
-          {
-            ...prepared.loadStats,
-            rowsLoaded: data.length
-          },
-          prepared.storedSymbols
-        );
+        return await this._closingAfter(async () => {
+          const prepared = await this._prepare(rows);
+          await this._parseIndexTable({ offset: prepared.offset, limit: prepared.rowsAvailable });
+          const data = this._buildRows(prepared.resolvedByField, 0, prepared.rowsAvailable);
+          return new QvdDataFrame(
+            data,
+            prepared.columns,
+            prepared.metadata,
+            {
+              ...prepared.loadStats,
+              rowsLoaded: data.length
+            },
+            prepared.storedSymbols
+          );
+        });
       }
       /**
        * Reads the file as columns, without ever materialising rows.
@@ -4145,19 +4586,21 @@ var init_QvdFileReader = __esm({
        */
       async loadColumnar(window = null) {
         const rows = normaliseWindow(window, this._path);
-        const prepared = await this._prepare(rows, null, true);
-        await this._parseIndexTable({ offset: prepared.offset, limit: prepared.rowsAvailable });
-        const { QvdColumnTable: QvdColumnTable2 } = await Promise.resolve().then(() => (init_QvdColumnTable(), QvdColumnTable_exports));
-        assert3(this._indexColumns, "The QVD file index table has not been parsed.");
-        return new QvdColumnTable2({
-          columns: prepared.columns,
-          codesByField: this._indexColumns,
-          symbolsByField: prepared.resolvedByField,
-          halvesByField: prepared.halvesByField,
-          rowCount: this._rowsDecoded,
-          metadata: prepared.metadata,
-          storedSymbols: prepared.storedSymbols,
-          loadStats: { ...prepared.loadStats, rowsLoaded: this._rowsDecoded }
+        return await this._closingAfter(async () => {
+          const prepared = await this._prepare(rows, null, true);
+          await this._parseIndexTable({ offset: prepared.offset, limit: prepared.rowsAvailable });
+          const { QvdColumnTable: QvdColumnTable2 } = await Promise.resolve().then(() => (init_QvdColumnTable(), QvdColumnTable_exports));
+          assert4(this._indexColumns, "The QVD file index table has not been parsed.");
+          return new QvdColumnTable2({
+            columns: prepared.columns,
+            codesByField: this._indexColumns,
+            symbolsByField: prepared.resolvedByField,
+            halvesByField: prepared.halvesByField,
+            rowCount: this._rowsDecoded,
+            metadata: prepared.metadata,
+            storedSymbols: prepared.storedSymbols,
+            loadStats: { ...prepared.loadStats, rowsLoaded: this._rowsDecoded }
+          });
         });
       }
       /**
@@ -4195,28 +4638,38 @@ var init_QvdFileReader = __esm({
         }
         const liveRows = { rows: chunkSize * 2, perChunk: 2 };
         const rows = normaliseWindow(window, this._path);
-        const prepared = await this._prepare(rows, liveRows);
-        if (prepared.rowsAvailable === 0) {
-          this._planIndexTable({ offset: prepared.offset, limit: 0 }, "parseIndexTable");
-          return;
-        }
-        for (let done = 0; done < prepared.rowsAvailable; done += chunkSize) {
-          this._throwIfAborted();
-          const count = Math.min(chunkSize, prepared.rowsAvailable - done);
-          const offset = prepared.offset + done;
-          await this._parseIndexTable({ offset, limit: count });
-          const data = this._buildRows(prepared.resolvedByField, done, prepared.rowsAvailable);
-          yield new QvdDataFrame(
-            data,
-            prepared.columns,
-            prepared.metadata,
-            {
-              ...prepared.loadStats,
-              offset,
-              rowsLoaded: data.length
-            },
-            prepared.storedSymbols
-          );
+        this._startRead();
+        let failing = false;
+        try {
+          const prepared = await this._prepare(rows, liveRows);
+          if (prepared.rowsAvailable === 0) {
+            this._planIndexTable({ offset: prepared.offset, limit: 0 }, "parseIndexTable");
+            return;
+          }
+          const codes = prepared.columns.map(() => new Int32Array(Math.min(chunkSize, prepared.rowsAvailable)));
+          for (let done = 0; done < prepared.rowsAvailable; done += chunkSize) {
+            this._throwIfAborted();
+            const count = Math.min(chunkSize, prepared.rowsAvailable - done);
+            const offset = prepared.offset + done;
+            await this._parseIndexTable({ offset, limit: count }, done, prepared.rowsAvailable, codes);
+            const data = this._buildRows(prepared.resolvedByField, done, prepared.rowsAvailable);
+            yield new QvdDataFrame(
+              data,
+              prepared.columns,
+              prepared.metadata,
+              {
+                ...prepared.loadStats,
+                offset,
+                rowsLoaded: data.length
+              },
+              prepared.storedSymbols
+            );
+          }
+        } catch (error) {
+          failing = true;
+          throw error;
+        } finally {
+          await this._endRead(failing);
         }
       }
       /**
@@ -4250,23 +4703,21 @@ var init_QvdFileReader = __esm({
         await this._parseHeader();
         this._emitProgress("header", 1, 1);
         this._throwIfAborted();
-        assert3(this._header, "The QVD file header has not been parsed.");
+        assert4(this._header, "The QVD file header has not been parsed.");
         const totalRows = headerInteger(this._header["QvdTableHeader"]["NoOfRecords"]);
         const symbolTableLength = headerInteger(this._header["QvdTableHeader"]["Offset"]);
         const resolved = resolveWindow(window, totalRows);
         const rowsAvailable = resolved.limit;
         let symbolsToKeep = null;
         let symbolsKept = null;
-        if (window.limit !== null || window.offset > 0) {
-          if (symbolTableLength > this._symbolFilteringThreshold) {
-            symbolsToKeep = await this._analyzeIndexTableSymbolUsage({ offset: resolved.offset, limit: rowsAvailable });
-            symbolsKept = symbolsToKeep.reduce((sum, set) => sum + set.size, 0);
-          }
+        if (this._analysisWouldRun(window, resolved, totalRows, symbolTableLength)) {
+          symbolsToKeep = await this._analyzeIndexTableSymbolUsage({ offset: resolved.offset, limit: rowsAvailable });
+          symbolsKept = symbolsToKeep.reduce((sum, set) => sum + set.size, 0);
         }
         await this._parseSymbolTable(symbolsToKeep, rowsAvailable, liveRows);
-        assert3(this._symbolTable, "The QVD file symbol table has not been parsed.");
+        assert4(this._symbolTable, "The QVD file symbol table has not been parsed.");
         this._throwIfAborted();
-        assert3(this._selectedFields, "The QVD file fields have not been resolved.");
+        assert4(this._selectedFields, "The QVD file fields have not been resolved.");
         const resolvedByField = [];
         const halvesByField = [];
         const entries = [];
@@ -4327,7 +4778,7 @@ var init_QvdFileReader = __esm({
        * @private
        */
       _buildRows(resolvedByField, progressBase, progressTotal) {
-        assert3(this._indexColumns, "The QVD file index table has not been parsed.");
+        assert4(this._indexColumns, "The QVD file index table has not been parsed.");
         const indexColumns = this._indexColumns;
         const fieldCount = indexColumns.length;
         const rowCount = this._rowsDecoded;
@@ -5016,12 +5467,16 @@ var init_QvdDataFrame = __esm({
       /**
        * Reads a QVD file in chunks, as an async generator of data frames.
        *
-       * The file is opened, read and parsed once; only the index decode and the row building happen
-       * per chunk, so what this bounds is row materialisation - the part that actually dominates a
-       * large read's heap. It is **not** constant-memory reading of an arbitrarily large file: the
-       * symbol table is parsed in full whatever the chunk size, because a stored index in the last
-       * chunk can address the first symbol. On a high-cardinality file that table is the bulk of the
-       * cost, and `readMetadata` is the only read that avoids it.
+       * The file is opened once and its symbol table parsed once. Each chunk's records are read from the
+       * file when that chunk is built, so what this holds is the symbol table and two chunks of rows,
+       * whatever the size of the file: a 20 GB QVD iterates in the memory its symbol table needs. That
+       * table is still parsed in full whatever the chunk size, because a stored index in the last chunk
+       * can address the first symbol. On a high-cardinality file that table is the bulk of the cost, and
+       * `readMetadata` is the only read that avoids it.
+       *
+       * The file stays open until the iteration ends. Running it to the end closes it, and so do
+       * `break` or a throw inside `for await` and a call to `return()` on the iterator; an iterator
+       * abandoned part-way without any of those holds the file until it is garbage-collected.
        *
        * ```js
        * for await (const chunk of QvdDataFrame.iterate('big.qvd', {chunkSize: 50_000})) {