qvdjs 0.10.1 → 1.0.0

package/dist/index.js

@@ -5,9 +5,11 @@ import xml2 from 'xml2js';
 import assert2 from 'assert';
 import os from 'os';
 import v8 from 'v8';
+import { types } from 'util';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -17,10 +19,14 @@ var __export = (target, all) => {
 };
 
 // src/QvdErrors.js
-var QvdError, QvdParseError, QvdValidationError, QvdIOError, QvdCorruptedError, QvdSecurityError;
+var ERROR_NAMES, QvdError, QvdParseError, QvdValidationError, QvdIOError, QvdCorruptedError, QvdSecurityError;
 var init_QvdErrors = __esm({
   "src/QvdErrors.js"() {
+    ERROR_NAMES = /* @__PURE__ */ new Map();
     QvdError = class extends Error {
+      static {
+        __name(this, "QvdError");
+      }
       /**
        * Constructs a new QVD error.
        *
@@ -30,13 +36,16 @@ var init_QvdErrors = __esm({
        */
       constructor(message, code, context = {}) {
         super(message);
-        this.name = this.constructor.name;
+        this.name = ERROR_NAMES.get(new.target) ?? new.target.name;
         this.code = code;
         this.context = context;
         Error.captureStackTrace(this, this.constructor);
       }
     };
     QvdParseError = class extends QvdError {
+      static {
+        __name(this, "QvdParseError");
+      }
       /**
        * Constructs a new QVD parse error.
        *
@@ -48,6 +57,9 @@ var init_QvdErrors = __esm({
       }
     };
     QvdValidationError = class extends QvdError {
+      static {
+        __name(this, "QvdValidationError");
+      }
       /**
        * Constructs a new QVD validation error.
        *
@@ -59,6 +71,9 @@ var init_QvdErrors = __esm({
       }
     };
     QvdIOError = class extends QvdError {
+      static {
+        __name(this, "QvdIOError");
+      }
       /**
        * Constructs a new QVD IO error.
        *
@@ -70,6 +85,9 @@ var init_QvdErrors = __esm({
       }
     };
     QvdCorruptedError = class extends QvdError {
+      static {
+        __name(this, "QvdCorruptedError");
+      }
       /**
        * Constructs a new QVD corrupted error.
        *
@@ -81,6 +99,9 @@ var init_QvdErrors = __esm({
       }
     };
     QvdSecurityError = class extends QvdError {
+      static {
+        __name(this, "QvdSecurityError");
+      }
       /**
        * Constructs a new QVD security error.
        *
@@ -91,163 +112,591 @@ var init_QvdErrors = __esm({
         super(message, "QVD_SECURITY_ERROR", context);
       }
     };
+    ERROR_NAMES.set(QvdError, "QvdError");
+    ERROR_NAMES.set(QvdParseError, "QvdParseError");
+    ERROR_NAMES.set(QvdValidationError, "QvdValidationError");
+    ERROR_NAMES.set(QvdIOError, "QvdIOError");
+    ERROR_NAMES.set(QvdCorruptedError, "QvdCorruptedError");
+    ERROR_NAMES.set(QvdSecurityError, "QvdSecurityError");
   }
 });
 
-// src/QvdSymbol.js
-var QvdSymbol;
-var init_QvdSymbol = __esm({
-  "src/QvdSymbol.js"() {
+// src/util/cellRules.js
+function asDual(value) {
+  if (value === null || typeof value !== "object") {
+    return null;
+  }
+  try {
+    if (value[DUAL_BRAND] === true) {
+      return value;
+    }
+    if (!isPlainObject(value)) {
+      return null;
+    }
+    const keys = Object.keys(value);
+    return keys.length === 2 && (keys[0] === "number" && keys[1] === "text" || keys[0] === "text" && keys[1] === "number") ? value : null;
+  } catch {
+    return null;
+  }
+}
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || Object.getPrototypeOf(prototype) === null;
+}
+function isNumericText(text) {
+  return text.trim() !== "" && Number.isFinite(Number(text));
+}
+function isStoredAsInt(value) {
+  return Number.isInteger(value) && value >= INT32_MIN && value <= INT32_MAX;
+}
+function numberProblem(value) {
+  if (typeof value !== "number") {
+    return `is ${describeType(value)}, not a number`;
+  }
+  return Number.isFinite(value) ? null : `is ${String(value)}`;
+}
+function textProblem(value) {
+  if (typeof value !== "string") {
+    return { reason: "type" };
+  }
+  const position = value.indexOf(NUL);
+  if (position !== -1) {
+    return { reason: "nul", position };
+  }
+  return value.isWellFormed() ? null : { reason: "surrogate", position: unpairedSurrogateIndex(value) };
+}
+function unpairedSurrogateIndex(value) {
+  for (let index = 0; index < value.length; index++) {
+    const unit = value.charCodeAt(index);
+    if (unit < 55296 || unit > 57343) {
+      continue;
+    }
+    const next = value.charCodeAt(index + 1);
+    if (unit <= 56319 && next >= 56320 && next <= 57343) {
+      index++;
+      continue;
+    }
+    return index;
+  }
+  return -1;
+}
+function checkNumber(value, subject, context) {
+  if (numberProblem(value) === null) {
+    return;
+  }
+  if (subject === null && typeof value === "number") {
+    throw new QvdValidationError("NaN and Infinity cannot be stored in a QVD field", {
+      ...context,
+      provided: String(value)
+    });
+  }
+  throw new QvdValidationError(`${subject ?? "A number"} must be a finite number; got ${describeType(value)}`, {
+    ...context,
+    type: typeof value
+  });
+}
+function checkText(value, subject, context) {
+  const problem = textProblem(value);
+  if (problem === null) {
+    return;
+  }
+  if (problem.reason === "type") {
+    throw new QvdValidationError(`${subject} must be a string; got ${describeType(value)}`, {
+      ...context,
+      type: typeof value
+    });
+  }
+  if (problem.reason === "surrogate") {
+    throw new QvdValidationError(`${subject} cannot contain an unpaired surrogate`, {
+      ...context,
+      position: problem.position
+    });
+  }
+  throw new QvdValidationError(`${subject} cannot contain a NUL character`, { ...context, position: problem.position });
+}
+function constructorName(value) {
+  try {
+    const name = value.constructor?.name;
+    return typeof name === "string" && name !== "" ? name : null;
+  } catch {
+    return null;
+  }
+}
+function describeType(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? "a number" : String(value);
+  }
+  if (typeof value === "undefined") {
+    return "undefined";
+  }
+  if (typeof value !== "object") {
+    return `a ${typeof value}`;
+  }
+  let name;
+  try {
+    if (Array.isArray(value)) {
+      return "an array";
+    }
+    name = constructorName(value) ?? Object.prototype.toString.call(value).slice(8, -1);
+    if (name === "Object") {
+      if (!isPlainObject(value)) {
+        return "an object whose prototype is not Object.prototype";
+      }
+      const keys = Object.keys(value);
+      if (keys.length === 0) {
+        return "a plain object";
+      }
+      return `a plain object with keys ${keys.slice(0, 5).join(", ")}${keys.length > 5 ? ", ..." : ""}`;
+    }
+  } catch {
+    return "an object";
+  }
+  return `${/^[aeio]/i.test(name) ? "an" : "a"} ${name}`;
+}
+var INT32_MIN, INT32_MAX, NUL, DUAL_BRAND;
+var init_cellRules = __esm({
+  "src/util/cellRules.js"() {
     init_QvdErrors();
-    QvdSymbol = class _QvdSymbol {
-      /**
-       * Constructs a new QVD symbol.
-       *
-       * @param {number|null} intValue The integer value.
-       * @param {number|null} doubleValue The double value.
-       * @param {string|null} stringValue The string value.
-       */
-      constructor(intValue, doubleValue, stringValue) {
-        this._intValue = intValue;
-        this._doubleValue = doubleValue;
-        this._stringValue = stringValue;
+    INT32_MIN = -2147483648;
+    INT32_MAX = 2147483647;
+    NUL = String.fromCharCode(0);
+    DUAL_BRAND = /* @__PURE__ */ Symbol.for("qvdjs.QvdDual");
+    __name(asDual, "asDual");
+    __name(isPlainObject, "isPlainObject");
+    __name(isNumericText, "isNumericText");
+    __name(isStoredAsInt, "isStoredAsInt");
+    __name(numberProblem, "numberProblem");
+    __name(textProblem, "textProblem");
+    __name(unpairedSurrogateIndex, "unpairedSurrogateIndex");
+    __name(checkNumber, "checkNumber");
+    __name(checkText, "checkText");
+    __name(constructorName, "constructorName");
+    __name(describeType, "describeType");
+  }
+});
+
+// src/util/symbolBytes.js
+function kindOf(number, text) {
+  if (number === null) {
+    return 4;
+  }
+  if (isStoredAsInt(number)) {
+    return text === null ? 1 : 5;
+  }
+  return text === null ? 2 : 6;
+}
+function symbolByteLength(kind, number, text) {
+  const numberBytes = kind === 1 || kind === 5 ? 4 : kind === 2 || kind === 6 ? 8 : 0;
+  const textBytes = kind >= 4 ? Buffer.byteLength(text, "utf8") + 1 : 0;
+  return 1 + numberBytes + textBytes;
+}
+function writeSymbol(buffer, offset, kind, number, text) {
+  buffer[offset++] = kind;
+  if (kind === 1 || kind === 5) {
+    offset = buffer.writeInt32LE(number, offset);
+  } else if (kind === 2 || kind === 6) {
+    offset = buffer.writeDoubleLE(number, offset);
+  }
+  if (kind >= 4) {
+    offset += buffer.write(text, offset, "utf8");
+    buffer[offset++] = 0;
+  }
+  return offset;
+}
+var init_symbolBytes = __esm({
+  "src/util/symbolBytes.js"() {
+    init_cellRules();
+    __name(kindOf, "kindOf");
+    __name(symbolByteLength, "symbolByteLength");
+    __name(writeSymbol, "writeSymbol");
+  }
+});
+
+// src/QvdDual.js
+function defineHalves(target, number, text) {
+  Object.defineProperties(target, {
+    number: { value: number, enumerable: true },
+    text: { value: text, enumerable: true }
+  });
+  Object.freeze(target);
+}
+function dualFromSymbol(number, text) {
+  const dual = Object.create(QvdDual.prototype);
+  defineHalves(dual, number, text);
+  return dual;
+}
+var QvdDual;
+var init_QvdDual = __esm({
+  "src/QvdDual.js"() {
+    init_cellRules();
+    QvdDual = class {
+      static {
+        __name(this, "QvdDual");
       }
       /**
-       * Returns the integer value of this symbol.
+       * Constructs a dual value.
+       *
+       * The storage kind is not chosen here. The writer derives it from the number, as Qlik does: an
+       * integer inside the int32 range is stored as a dual int, anything else as a dual double.
        *
-       * @return {number|null} The integer value.
+       * @param {number} number The numeric half. Must be a finite number.
+       * @param {string} text The text half. Must be a string with no NUL and no unpaired surrogate.
+       * @throws {QvdValidationError} If either half cannot be stored in a QVD. The message names the half.
        */
-      get intValue() {
-        return this._intValue;
+      constructor(number, text) {
+        checkNumber(number, "The number of a dual value", { half: "number" });
+        checkText(text, "The text of a dual value", { half: "text" });
+        defineHalves(this, number, text);
       }
       /**
-       * Returns the double value of this symbol.
+       * Refuses every implicit conversion. See the class comment for why neither half is a safe answer.
        *
-       * @return {number|null} The double value.
+       * The hint JavaScript passes is not used: `'number'`, `'string'` and `'default'` say which
+       * conversion ran, not which half the caller meant, and the fix is the same for all three.
+       *
+       * @return {never}
+       * @throws {TypeError} Always.
        */
-      get doubleValue() {
-        return this._doubleValue;
+      [Symbol.toPrimitive]() {
+        throw new TypeError(
+          `A QvdDual holds two values, ${this.number} and ${JSON.stringify(this.text)}; use .number or .text`
+        );
       }
       /**
-       * Returns the string value of this symbol.
+       * Both halves, so `JSON.stringify` loses neither - and produces the shape the writer accepts back.
        *
-       * @return {string|null} The string value.
+       * @return {{number: number, text: string}} The dual as a plain object.
        */
-      get stringValue() {
-        return this._stringValue;
+      toJSON() {
+        return { number: this.number, text: this.text };
       }
       /**
-       * Retrieves the primary value of this symbol. The primary value is descriptive raw value.
-       * It is either the string value, the integer value or the double value, prioritized in this order.
+       * How Node's `util.inspect` and `console.log` show a dual.
        *
-       * @return {number|string|null} The primary value.
+       * @return {string} For example `QvdDual(4.5, "4.50")`.
        */
-      toPrimaryValue() {
-        if (null != this._stringValue) {
-          return this._stringValue;
-        } else if (null != this._intValue) {
-          return this._intValue;
-        } else if (null != this._doubleValue) {
-          return this._doubleValue;
-        } else {
-          return null;
-        }
+      [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+        return `QvdDual(${this.number}, ${JSON.stringify(this.text)})`;
       }
-      /**
-       * Converts the symbol to its byte representation.
-       *
-       * @return {Buffer} The byte representation of the symbol.
-       */
-      toByteRepresentation() {
-        if (this._intValue !== null && this._stringValue !== null) {
-          const intBuffer = Buffer.alloc(4);
-          intBuffer.writeInt32LE(this._intValue);
-          const stringBuffer = Buffer.concat([Buffer.from(this._stringValue, "utf-8"), Buffer.from([0])]);
-          return Buffer.concat([Buffer.from([5]), intBuffer, stringBuffer]);
-        } else if (this._doubleValue !== null && this._stringValue !== null) {
-          const floatBuffer = Buffer.alloc(8);
-          floatBuffer.writeDoubleLE(this._doubleValue);
-          const stringBuffer = Buffer.concat([Buffer.from(this._stringValue, "utf-8"), Buffer.from([0])]);
-          return Buffer.concat([Buffer.from([6]), floatBuffer, stringBuffer]);
-        } else if (this._intValue !== null) {
-          const buffer = Buffer.alloc(4);
-          buffer.writeInt32LE(this._intValue);
-          return Buffer.concat([Buffer.from([1]), buffer]);
-        } else if (this._doubleValue !== null) {
-          const buffer = Buffer.alloc(8);
-          buffer.writeDoubleLE(this._doubleValue);
-          return Buffer.concat([Buffer.from([2]), buffer]);
-        } else if (this._stringValue !== null) {
-          const buffer = Buffer.concat([Buffer.from(this._stringValue, "utf-8"), Buffer.from([0])]);
-          return Buffer.concat([Buffer.from([4]), buffer]);
-        } else {
-          throw new QvdValidationError("The symbol does not contain any value.", {
-            intValue: this._intValue,
-            doubleValue: this._doubleValue,
-            stringValue: this._stringValue
-          });
-        }
+      /** @return {string} `'QvdDual'`, for `Object.prototype.toString`. */
+      get [Symbol.toStringTag]() {
+        return "QvdDual";
       }
       /**
-       * Checks if this symbol is equal to another symbol.
+       * Whether a value is a dual cell: a `QvdDual` from any copy of this library, or a plain object whose
+       * own enumerable keys are exactly `number` and `text`, which is what a clone of one becomes.
        *
-       * @param {*} value The object to compare with.
-       * @return {boolean} True if the objects are equal, false otherwise.
-       */
-      equals(value) {
-        if (!(value instanceof _QvdSymbol)) {
-          return false;
-        }
-        return this._intValue === value.intValue && this._doubleValue === value.doubleValue && this._stringValue === value.stringValue;
-      }
-      /**
-       * Constructs a pure integer value symbol.
+       * Recognition only. The halves are checked when the value is written.
        *
-       * @param {number} intValue The integer value.
-       * @return {QvdSymbol} The constructed value symbol.
+       * @param {any} value Any value.
+       * @return {boolean} True for a dual cell.
        */
-      static fromIntValue(intValue) {
-        return new _QvdSymbol(intValue, null, null);
+      static isDual(value) {
+        return asDual(value) !== null;
       }
-      /**
-       * Constructs a pure double value symbol.
-       *
-       * @param {number} doubleValue The double value.
-       * @return {QvdSymbol} The constructed value symbol.
-       */
-      static fromDoubleValue(doubleValue) {
-        return new _QvdSymbol(null, doubleValue, null);
+    };
+    Object.defineProperty(QvdDual.prototype, DUAL_BRAND, { value: true });
+    __name(defineHalves, "defineHalves");
+    __name(dualFromSymbol, "dualFromSymbol");
+  }
+});
+
+// src/util/readOptions.js
+function requireRowCount(value, name, filePath) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new QvdValidationError(`${name} must be a non-negative integer`, {
+      option: name,
+      provided: value,
+      type: typeof value,
+      file: filePath
+    });
+  }
+  return value;
+}
+function normaliseWindow(window, filePath) {
+  if (window === null || window === void 0) {
+    return { offset: 0, limit: null };
+  }
+  if (typeof window === "number") {
+    return { offset: 0, limit: requireRowCount(window, "maxRows", filePath) };
+  }
+  if (typeof window !== "object" || Array.isArray(window)) {
+    throw new QvdValidationError("The row window must be a number, null, or an {offset, limit} object", {
+      provided: window,
+      type: typeof window,
+      file: filePath
+    });
+  }
+  const { offset, limit, maxRows } = window;
+  const limitGiven = limit !== void 0 && limit !== null;
+  const maxRowsGiven = maxRows !== void 0 && maxRows !== null;
+  if (limitGiven && maxRowsGiven) {
+    throw new QvdValidationError("maxRows and limit are two names for the same option; pass one of them, not both", {
+      maxRows,
+      limit,
+      file: filePath
+    });
+  }
+  return {
+    offset: offset === void 0 || offset === null ? 0 : requireRowCount(offset, "offset", filePath),
+    limit: limitGiven ? requireRowCount(limit, "limit", filePath) : maxRowsGiven ? requireRowCount(maxRows, "maxRows", filePath) : null
+  };
+}
+function resolveWindow(window, totalRows) {
+  const rows = Number.isSafeInteger(totalRows) && totalRows > 0 ? totalRows : 0;
+  const offset = Math.min(window.offset, rows);
+  return {
+    offset,
+    limit: Math.max(0, Math.min(window.limit === null ? Infinity : window.limit, rows - offset))
+  };
+}
+function selectFields(fields, requested, filePath) {
+  if (requested === null || requested === void 0) {
+    return fields;
+  }
+  if (!Array.isArray(requested)) {
+    throw new QvdValidationError("fields must be an array of field names", {
+      provided: requested,
+      type: typeof requested,
+      file: filePath
+    });
+  }
+  const available = fields.map((field) => field["FieldName"]);
+  if (requested.length === 0) {
+    throw new QvdValidationError("fields must name at least one field", {
+      availableColumns: available,
+      file: filePath
+    });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return requested.map((name) => {
+    if (typeof name !== "string") {
+      throw new QvdValidationError("Field names must be strings", {
+        provided: name,
+        type: typeof name,
+        availableColumns: available,
+        file: filePath
+      });
+    }
+    if (seen.has(name)) {
+      throw new QvdValidationError(`Field '${name}' is listed twice`, {
+        column: name,
+        fields: requested,
+        file: filePath
+      });
+    }
+    seen.add(name);
+    const index = available.indexOf(name);
+    if (index === -1) {
+      throw new QvdValidationError(`Column '${name}' does not exist`, {
+        column: name,
+        availableColumns: available,
+        file: filePath
+      });
+    }
+    return fields[index];
+  });
+}
+function normaliseDuals(value, filePath) {
+  if (value === void 0 || value === null) {
+    return "number";
+  }
+  if (!DUAL_MODES.includes(value)) {
+    throw new QvdValidationError(`duals must be one of ${DUAL_MODES.map((mode) => `'${mode}'`).join(", ")}`, {
+      option: "duals",
+      provided: value,
+      file: filePath
+    });
+  }
+  return value;
+}
+function normaliseCoerceNumericStrings(value, filePath) {
+  if (value === void 0 || value === null) {
+    return false;
+  }
+  if (typeof value !== "boolean") {
+    throw new QvdValidationError("coerceNumericStrings must be true or false", {
+      option: "coerceNumericStrings",
+      provided: value,
+      type: typeof value,
+      file: filePath
+    });
+  }
+  return value;
+}
+function readerOptionsFrom(options) {
+  return {
+    allowedDir: options.allowedDir,
+    memorySafetyFactor: options.memorySafetyFactor,
+    symbolFilteringThreshold: options.symbolFilteringThreshold,
+    fields: options.fields === void 0 ? null : options.fields,
+    duals: options.duals,
+    coerceNumericStrings: options.coerceNumericStrings,
+    onProgress: options.onProgress,
+    signal: options.signal
+  };
+}
+function metadataOptionsFrom(options) {
+  return {
+    allowedDir: options.allowedDir,
+    onProgress: options.onProgress,
+    signal: options.signal
+  };
+}
+function windowFrom(options) {
+  return { offset: options.offset, limit: options.limit, maxRows: options.maxRows };
+}
+var DUAL_MODES;
+var init_readOptions = __esm({
+  "src/util/readOptions.js"() {
+    init_QvdErrors();
+    __name(requireRowCount, "requireRowCount");
+    __name(normaliseWindow, "normaliseWindow");
+    __name(resolveWindow, "resolveWindow");
+    __name(selectFields, "selectFields");
+    DUAL_MODES = Object.freeze(["number", "text", "both"]);
+    __name(normaliseDuals, "normaliseDuals");
+    __name(normaliseCoerceNumericStrings, "normaliseCoerceNumericStrings");
+    __name(readerOptionsFrom, "readerOptionsFrom");
+    __name(metadataOptionsFrom, "metadataOptionsFrom");
+    __name(windowFrom, "windowFrom");
+  }
+});
+
+// src/util/storedSymbols.js
+function trustStoredSymbols(entries) {
+  const record = Object.freeze(entries);
+  trusted.add(record);
+  return record;
+}
+function attachStoredSymbols(metadata, record) {
+  if (metadata !== null && typeof metadata === "object" && Object.isExtensible(metadata)) {
+    Object.defineProperty(metadata, STORED_SYMBOLS, { value: record, enumerable: false, configurable: true });
+  }
+}
+function refuse(message, context) {
+  throw new QvdValidationError(message, context);
+}
+function normaliseStoredSymbols(record) {
+  if (record === null || record === void 0) {
+    return null;
+  }
+  if (typeof record === "object" && trusted.has(record)) {
+    return record;
+  }
+  if (!Array.isArray(record)) {
+    refuse(`storedSymbols must be an array of field entries; got ${describeType(record)}`, {
+      option: "storedSymbols",
+      type: typeof record
+    });
+  }
+  const fields = /* @__PURE__ */ new Set();
+  const entries = record.map((entry, index) => {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry) || typeof entry.field !== "string") {
+      refuse("Each storedSymbols entry must be an object with a string field name", { entry: index });
+    }
+    const { field, values, numbers, texts } = entry;
+    if (fields.has(field)) {
+      refuse(`storedSymbols lists field '${field}' twice`, { field, entry: index });
+    }
+    fields.add(field);
+    if (!Array.isArray(values) || !Array.isArray(numbers) || !Array.isArray(texts) || values.length !== numbers.length || values.length !== texts.length) {
+      refuse(`The values, numbers and texts of the storedSymbols entry for '${field}' must be arrays of one length`, {
+        field,
+        entry: index
+      });
+    }
+    for (let symbol = 0; symbol < values.length; symbol++) {
+      const value = values[symbol];
+      const number = numbers[symbol];
+      const text = texts[symbol];
+      const context = { field, symbol };
+      if (typeof value !== "number" && typeof value !== "string") {
+        refuse(`A stored symbol's value must be a number or a string; got ${describeType(value)}`, {
+          ...context,
+          type: typeof value
+        });
       }
-      /**
-       * Constructs a pure string value symbol.
-       *
-       * @param {string} stringValue The string value.
-       * @return {QvdSymbol} The constructed value symbol.
-       */
-      static fromStringValue(stringValue) {
-        return new _QvdSymbol(null, null, stringValue);
+      if (number !== null) {
+        checkNumber(number, "A stored symbol's number", context);
       }
-      /**
-       * Constructs a dual value symbol from an integer and a string value.
-       *
-       * @param {number} intValue The integer value.
-       * @param {string} stringValue The string value.
-       * @return {QvdSymbol} The constructed value symbol.
-       */
-      static fromDualIntValue(intValue, stringValue) {
-        return new _QvdSymbol(intValue, null, stringValue);
+      if (text !== null) {
+        checkText(text, "A stored symbol's text", context);
       }
-      /**
-       * Constructs a dual value symbol from a double and a string value.
-       *
-       * @param {number} doubleValue The double value.
-       * @param {string} stringValue The string value.
-       * @return {QvdSymbol} The constructed value symbol.
-       */
-      static fromDualDoubleValue(doubleValue, stringValue) {
-        return new _QvdSymbol(null, doubleValue, stringValue);
+      const consistent = number !== null && text !== null ? sameValueZero(value, number) || value === text : number === null && text !== null ? value === text || typeof value === "number" && Number.isFinite(value) : number !== null && sameValueZero(value, number);
+      if (!consistent) {
+        refuse(
+          number === null && text === null ? "A stored symbol needs a number or a text" : "A stored symbol's value must be its number or its text",
+          { ...context, value, number, text }
+        );
       }
-    };
+    }
+    return Object.freeze({
+      field,
+      values: Object.freeze(values.slice()),
+      numbers: Object.freeze(numbers.slice()),
+      texts: Object.freeze(texts.slice())
+    });
+  });
+  return trustStoredSymbols(entries);
+}
+function narrowStoredSymbols(record, columns) {
+  if (record === null) {
+    return null;
+  }
+  const kept = record.filter((entry) => columns.includes(entry.field));
+  return kept.length === record.length ? record : trustStoredSymbols(kept);
+}
+function storedSymbolsEntry(record, field) {
+  if (record === null) {
+    return null;
+  }
+  return record.find((entry) => entry.field === field) ?? null;
+}
+function firstTextByValue(entry) {
+  const byValue = /* @__PURE__ */ new Map();
+  for (let index = entry.values.length - 1; index >= 0; index--) {
+    const text = entry.texts[index];
+    if (text !== null) {
+      byValue.set(entry.values[index], text);
+    }
+  }
+  return byValue;
+}
+function storedTextOf(entry, value) {
+  let byValue = firstTexts.get(entry);
+  if (byValue === void 0) {
+    byValue = firstTextByValue(entry);
+    firstTexts.set(entry, byValue);
+  }
+  return byValue.get(value) ?? null;
+}
+function sameValueZero(a, b) {
+  return a === b || a !== a && b !== b;
+}
+var STORED_SYMBOLS, trusted, firstTexts;
+var init_storedSymbols = __esm({
+  "src/util/storedSymbols.js"() {
+    init_QvdErrors();
+    init_cellRules();
+    STORED_SYMBOLS = /* @__PURE__ */ Symbol.for("qvdjs.storedSymbols");
+    trusted = /* @__PURE__ */ new WeakSet();
+    __name(trustStoredSymbols, "trustStoredSymbols");
+    __name(attachStoredSymbols, "attachStoredSymbols");
+    __name(refuse, "refuse");
+    __name(normaliseStoredSymbols, "normaliseStoredSymbols");
+    __name(narrowStoredSymbols, "narrowStoredSymbols");
+    __name(storedSymbolsEntry, "storedSymbolsEntry");
+    firstTexts = /* @__PURE__ */ new WeakMap();
+    __name(firstTextByValue, "firstTextByValue");
+    __name(storedTextOf, "storedTextOf");
+    __name(sameValueZero, "sameValueZero");
   }
 });
 function isWithinDirectoryLexically(resolvedBaseDir, resolvedPath) {
@@ -352,6 +801,10 @@ function validatePath(filePath, allowedDir) {
 var init_validatePath = __esm({
   "src/util/validatePath.js"() {
     init_QvdErrors();
+    __name(isWithinDirectoryLexically, "isWithinDirectoryLexically");
+    __name(resolveDeepestExisting, "resolveDeepestExisting");
+    __name(isWithinDirectoryOnDisk, "isWithinDirectoryOnDisk");
+    __name(validatePath, "validatePath");
   }
 });
 
@@ -401,6 +854,9 @@ var init_bitUtils = __esm({
   "src/util/bitUtils.js"() {
     MAX_BIT_WIDTH = 31;
     POW2 = Array.from({ length: 41 }, (_, exponent) => 2 ** exponent);
+    __name(fieldGeometry, "fieldGeometry");
+    __name(decodeIndexColumn, "decodeIndexColumn");
+    __name(writeBitField, "writeBitField");
   }
 });
 
@@ -409,14 +865,310 @@ var QvdFileWriter_exports = {};
 __export(QvdFileWriter_exports, {
   QvdFileWriter: () => QvdFileWriter
 });
-var QvdFileWriter;
+function notXmlIndex(value) {
+  for (let index = 0; index < value.length; index++) {
+    const unit = value.charCodeAt(index);
+    if (unit < 32 && unit !== 9 && unit !== 10 && unit !== 13 || unit === 65534 || unit === 65535) {
+      return index;
+    }
+  }
+  return -1;
+}
+function checkHeaderText(value, subject, context) {
+  checkText(value, subject, context);
+  const position = notXmlIndex(value);
+  if (position !== -1) {
+    const code = value.charCodeAt(position).toString(16).toUpperCase().padStart(4, "0");
+    throw new QvdValidationError(`${subject} cannot contain U+${code}, which XML cannot hold`, { ...context, position });
+  }
+}
+function checkHeaderTexts(value, property, owner, context) {
+  if (typeof value === "string") {
+    checkHeaderText(value, `The ${property} of ${owner}`, { ...context, property });
+  } else if (Array.isArray(value)) {
+    value.forEach((item, index) => checkHeaderTexts(item, `${property}[${index}]`, owner, context));
+  } else if (value !== null && typeof value === "object") {
+    for (const [key, item] of Object.entries(value)) {
+      checkHeaderTexts(item, `${property}.${key}`, owner, context);
+    }
+  }
+}
+function validateColumnNames(columns, filePath) {
+  const seen = /* @__PURE__ */ new Set();
+  columns.forEach((name, index) => {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new QvdValidationError("Field names must be non-empty strings", {
+        column: index,
+        provided: name,
+        type: typeof name,
+        file: filePath,
+        stage: "buildSymbolTable"
+      });
+    }
+    checkHeaderText(name, "A field name", { column: index, provided: name, file: filePath, stage: "buildSymbolTable" });
+    if (seen.has(name)) {
+      throw new QvdValidationError(`Field '${name}' appears twice`, {
+        column: name,
+        columnIndex: index,
+        file: filePath,
+        stage: "buildSymbolTable"
+      });
+    }
+    seen.add(name);
+  });
+}
+function refuseCell(value, column, row, filePath) {
+  let resemblesDual = false;
+  try {
+    resemblesDual = value !== null && typeof value === "object" && ("number" in value || "text" in value || "intValue" in value && "stringValue" in value);
+  } catch {
+  }
+  throw new QvdValidationError(
+    `A QVD field holds numbers, strings, dual values and NULL; ${describeType(value)} cannot be written. Convert it first - a Date to new QvdDual(dateToQlikSerial(date), text), the serial and the text Qlik shows, which is how Qlik stores a date; a boolean to -1 and 0, as a Qlik comparison stores it.` + (resemblesDual ? " A dual value is a QvdDual, or an object whose only keys are number and text." : ""),
+    {
+      column,
+      row,
+      type: typeof value,
+      constructor: constructorName(value) ?? void 0,
+      file: filePath,
+      stage: "buildSymbolTable"
+    }
+  );
+}
+function valuesAreNumbers(entry) {
+  const { values, numbers } = entry;
+  for (let index = 0; index < values.length; index++) {
+    if (!sameValueZero(values[index], numbers[index])) {
+      return false;
+    }
+  }
+  return true;
+}
+function newSlot(column, key, text) {
+  const slot = column.keys.length;
+  column.keys.push(key);
+  column.texts.push(text);
+  if (typeof key === "number") {
+    column.facts.hasNumber = true;
+    if (!Number.isInteger(key)) column.facts.hasFraction = true;
+  } else {
+    column.facts.hasNonNumber = true;
+  }
+  return slot;
+}
+function slotFor(column, key, text) {
+  let slot = column.byKey.get(key);
+  if (slot === void 0) {
+    slot = newSlot(column, key, text);
+    column.byKey.set(key, slot);
+  } else if (text !== null && column.texts[slot] === null && typeof key === "number") {
+    column.texts[slot] = text;
+  }
+  return slot;
+}
+function standsForSeveral(indices, numbers, texts) {
+  let number = null;
+  let string = null;
+  for (const index of indices) {
+    if (numbers[index] !== null) {
+      if (number === null) {
+        number = numbers[index];
+      } else if (!sameValueZero(number, numbers[index])) {
+        return true;
+      }
+    } else if (string === null) {
+      string = texts[index];
+    } else if (string !== texts[index]) {
+      return true;
+    }
+  }
+  return number !== null && string !== null;
+}
+function ambiguousAsUncoercedText(entry) {
+  const { values, numbers, texts } = entry;
+  for (let index = 0; index < values.length; index++) {
+    if (typeof values[index] === "number" && numbers[index] !== null && texts[index] !== null) {
+      if (!isNumericText(texts[index])) {
+        return false;
+      }
+    }
+  }
+  const byShown = /* @__PURE__ */ new Map();
+  for (let index = 0; index < values.length; index++) {
+    const shown = texts[index] ?? numbers[index];
+    const indices = byShown.get(shown);
+    if (indices === void 0) {
+      byShown.set(shown, [index]);
+    } else {
+      indices.push(index);
+    }
+  }
+  for (const indices of byShown.values()) {
+    if (indices.length > 1 && standsForSeveral(indices, numbers, texts)) {
+      return true;
+    }
+  }
+  return false;
+}
+function unambiguousWithoutDuals(column) {
+  const { numbers, texts } = column.entry;
+  for (const found of column.byValue.values()) {
+    if (typeof found !== "number") {
+      const kept = found.filter((index) => numbers[index] === null || texts[index] === null);
+      if (kept.length > 1 && standsForSeveral(kept, numbers, texts)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+function ambiguityRemedy(column) {
+  const { values, numbers, texts } = column.entry;
+  let coerced = false;
+  let other = false;
+  for (const [value, found] of column.byValue) {
+    if (typeof found !== "number" && standsForSeveral(found, numbers, texts)) {
+      if (typeof value === "number") {
+        coerced = true;
+      } else {
+        other = true;
+      }
+    }
+  }
+  if (!coerced) {
+    return "Read the field with {duals: 'both'}, or write QvdDual cells.";
+  }
+  if (!other && !ambiguousAsUncoercedText(column.entry)) {
+    return "Read the field without {coerceNumericStrings: true}.";
+  }
+  if (unambiguousWithoutDuals(column)) {
+    return "Read the field with {duals: 'both'}.";
+  }
+  return values.some((value, index) => typeof value === "string" && numbers[index] !== null) ? "Read the field with {duals: 'both'} and without {coerceNumericStrings: true}." : "Read the field without {coerceNumericStrings: true}, and with {duals: 'both'} as well if it was read with {duals: 'text'}.";
+}
+function slotForCell(column, value, row, filePath) {
+  if (column.byCell === column.byKey) {
+    return newSlot(column, value, column.textByNumber === null ? null : column.textByNumber.get(value) ?? null);
+  }
+  const found = column.byValue.get(value);
+  if (found === void 0) {
+    return slotFor(column, value, null);
+  }
+  const { numbers, texts } = column.entry;
+  const indices = typeof found === "number" ? [found] : found;
+  if (standsForSeveral(indices, numbers, texts)) {
+    const stored = [];
+    for (const index of indices) {
+      if (!stored.some((pair) => sameValueZero(pair.number, numbers[index]) && pair.text === texts[index])) {
+        stored.push({ number: numbers[index], text: texts[index] });
+      }
+    }
+    throw new QvdValidationError(
+      `The value ${JSON.stringify(value)} in field '${column.name}' (row ${row}) was read from ${stored.length} different stored values, so writing it back would have to guess which one. ${ambiguityRemedy(column)}`,
+      { column: column.name, row, value, stored, file: filePath, stage: "buildSymbolTable" }
+    );
+  }
+  let number = null;
+  let numberText = null;
+  for (const index of indices) {
+    if (numbers[index] === null) {
+      return slotFor(column, texts[index], null);
+    }
+    number ??= numbers[index];
+    numberText ??= texts[index];
+  }
+  return slotFor(column, number, numberText);
+}
+function slotForObject(column, value, row, filePath) {
+  const dual = asDual(value);
+  if (dual === null) {
+    refuseCell(value, column.name, row, filePath);
+  }
+  const { number, text } = dual;
+  if (numberProblem(number) !== null) {
+    checkNumber(number, "The number of a dual value", {
+      column: column.name,
+      row,
+      half: "number",
+      file: filePath,
+      stage: "buildSymbolTable"
+    });
+  }
+  if (textProblem(text) !== null) {
+    checkText(text, "The text of a dual value", {
+      column: column.name,
+      row,
+      half: "text",
+      file: filePath,
+      stage: "buildSymbolTable"
+    });
+  }
+  const slot = slotFor(column, number, text);
+  if (column.byObject.size < OBJECT_MEMO_BASE + 2 * column.keys.length) {
+    column.byObject.set(value, slot);
+  }
+  return slot;
+}
+function pruneContradictedTags(tags, facts) {
+  if (tags === null || typeof tags !== "object" || tags.String === void 0 || facts === void 0) {
+    return tags || {};
+  }
+  const list = Array.isArray(tags.String) ? tags.String : [tags.String];
+  const kept = list.filter((tag) => {
+    if (facts.hasNonNumber && NUMERIC_TAGS.has(tag)) return false;
+    if (facts.hasFraction && WHOLE_NUMBER_TAGS.has(tag)) return false;
+    if (facts.hasNumber && TEXT_TAGS.has(tag)) return false;
+    return true;
+  });
+  if (kept.length === list.length) {
+    return tags;
+  }
+  return kept.length === 0 ? {} : { ...tags, String: kept };
+}
+function resetContradictedNumberFormat(numberFormat, facts) {
+  if (!numberFormat) {
+    return { ...UNKNOWN_NUMBER_FORMAT };
+  }
+  if (facts !== void 0 && !facts.hasNumber && facts.hasNonNumber && NUMERIC_FORMATS.has(numberFormat.Type)) {
+    return { ...UNKNOWN_NUMBER_FORMAT };
+  }
+  return numberFormat;
+}
+var OBJECT_MEMO_BASE, NUMERIC_TAGS, TEXT_TAGS, WHOLE_NUMBER_TAGS, NUMERIC_FORMATS, UNKNOWN_NUMBER_FORMAT, QvdFileWriter;
 var init_QvdFileWriter = __esm({
   "src/QvdFileWriter.js"() {
-    init_QvdSymbol();
     init_QvdErrors();
     init_validatePath();
     init_bitUtils();
-    QvdFileWriter = class _QvdFileWriter {
+    init_cellRules();
+    init_symbolBytes();
+    init_storedSymbols();
+    __name(notXmlIndex, "notXmlIndex");
+    __name(checkHeaderText, "checkHeaderText");
+    __name(checkHeaderTexts, "checkHeaderTexts");
+    __name(validateColumnNames, "validateColumnNames");
+    __name(refuseCell, "refuseCell");
+    OBJECT_MEMO_BASE = 64;
+    __name(valuesAreNumbers, "valuesAreNumbers");
+    __name(newSlot, "newSlot");
+    __name(slotFor, "slotFor");
+    __name(standsForSeveral, "standsForSeveral");
+    __name(ambiguousAsUncoercedText, "ambiguousAsUncoercedText");
+    __name(unambiguousWithoutDuals, "unambiguousWithoutDuals");
+    __name(ambiguityRemedy, "ambiguityRemedy");
+    __name(slotForCell, "slotForCell");
+    __name(slotForObject, "slotForObject");
+    NUMERIC_TAGS = /* @__PURE__ */ new Set(["$numeric", "$integer", "$date", "$time", "$timestamp"]);
+    TEXT_TAGS = /* @__PURE__ */ new Set(["$text", "$ascii"]);
+    WHOLE_NUMBER_TAGS = /* @__PURE__ */ new Set(["$integer", "$date"]);
+    NUMERIC_FORMATS = /* @__PURE__ */ new Set(["INTEGER", "REAL", "FIX", "MONEY", "DATE", "TIME", "TIMESTAMP", "INTERVAL"]);
+    UNKNOWN_NUMBER_FORMAT = Object.freeze({ Type: "UNKNOWN", nDec: "0", UseThou: "0", Fmt: "", Dec: "", Thou: "" });
+    __name(pruneContradictedTags, "pruneContradictedTags");
+    __name(resetContradictedNumberFormat, "resetContradictedNumberFormat");
+    QvdFileWriter = class {
+      static {
+        __name(this, "QvdFileWriter");
+      }
       /**
        * Constructs a new QVD file writer.
        *
@@ -437,7 +1189,8 @@ var init_QvdFileWriter = __esm({
         this._onProgress = onProgress;
         this._header = null;
         this._symbolBuffer = null;
-        this._symbolTable = null;
+        this._symbolCounts = null;
+        this._symbolFacts = null;
         this._symbolTableMetadata = null;
         this._indexBuffer = null;
         this._symbolIndexByValue = null;
@@ -548,19 +1301,12 @@ var init_QvdFileWriter = __esm({
                   BitOffset: this._indexTableMetadata?.[index][0],
                   BitWidth: this._indexTableMetadata?.[index][1],
                   Bias: this._indexTableMetadata?.[index][2],
-                  NoOfSymbols: this._symbolTable?.[index].length,
+                  NoOfSymbols: this._symbolCounts?.[index],
                   Offset: this._symbolTableMetadata?.[index][0],
                   Length: this._symbolTableMetadata?.[index][1],
                   Comment: existingField?.Comment || "",
-                  NumberFormat: existingField?.NumberFormat || {
-                    Type: "UNKNOWN",
-                    nDec: "0",
-                    UseThou: "0",
-                    Fmt: "",
-                    Dec: "",
-                    Thou: ""
-                  },
-                  Tags: existingField?.Tags || {}
+                  NumberFormat: resetContradictedNumberFormat(existingField?.NumberFormat, this._symbolFacts?.[index]),
+                  Tags: pruneContradictedTags(existingField?.Tags, this._symbolFacts?.[index])
                 };
               })
             },
@@ -570,6 +1316,19 @@ var init_QvdFileWriter = __esm({
             Length: this._indexBuffer?.length
           }
         };
+        const { Fields, ...table } = xmlObject.QvdTableHeader;
+        for (const [property, value] of Object.entries(table)) {
+          checkHeaderTexts(value, property, "the table", { file: this._path, stage: "buildHeader" });
+        }
+        for (const { FieldName, ...field } of Fields.QvdFieldHeader) {
+          for (const [property, value] of Object.entries(field)) {
+            checkHeaderTexts(value, property, `field '${FieldName}'`, {
+              column: FieldName,
+              file: this._path,
+              stage: "buildHeader"
+            });
+          }
+        }
         const builder = new xml2.Builder({
           renderOpts: {
             pretty: true,
@@ -583,25 +1342,49 @@ var init_QvdFileWriter = __esm({
       /**
        * Builds the symbol table of the QVD file.
        *
-       * PERFORMANCE OPTIMIZATION: This method uses a single-pass algorithm to build
-       * symbol tables for all columns simultaneously. This reduces time complexity from
-       * O(n×m×s) to O(n×m) where n=rows, m=columns, s=symbols per column.
+       * One pass over the rows finds each column's distinct values in the order they first appear,
+       * which is the order Qlik lists symbols in, and checks each distinct value once. A second pass per
+       * column encodes them: every symbol is sized first, then written into one buffer of exactly that
+       * size.
+       *
+       * What each value is stored as:
+       *
+       * | Cell | Symbol |
+       * | --- | --- |
+       * | `null`, `undefined`, a hole, a missing cell | none - the field's `Bias` records NULL |
+       * | an integer from -2147483648 to 2147483647, -0 included | pure int, type 1 |
+       * | any other finite number | pure double, type 2 |
+       * | a string | pure string, type 4 |
+       * | a dual - a `QvdDual`, or an object whose only keys are `number` and `text` | dual int or dual double, type 5 or 6, by the number |
+       * | a number or a string the frame's `storedSymbols` records | the symbol it was read from |
+       *
+       * A number is a pure number, with no text. It used to be written as a dual whose text was
+       * `String(value)`, which was wrong twice over: it invented text the caller never supplied, and a
+       * file Qlik wrote with pure numbers came back out of a read and a write with every one of them
+       * turned into a dual. The kind follows `isStoredAsInt`, which is the rule Qlik's own files follow.
+       * A string is never parsed, so `'7'` and `7` in one column are two symbols. It is stored as its
+       * UTF-8 bytes, or refused where those bytes would not give it back: a NUL ends a stored text, and
+       * an unpaired surrogate has no UTF-8 encoding at all.
+       *
+       * A column holds one symbol per number, as a Qlik field does. Several duals with one number are one
+       * symbol with the first text in row order, and a plain number with the same number as a dual joins
+       * the dual, in either order - so no text a caller supplied is lost to a plain number that came
+       * first. A string is not a number, so a string equal to a dual's text is a symbol of its own.
        *
-       * Algorithm:
-       * 1. Initialize a Set for each column to collect unique values
-       * 2. Single pass through all data rows, adding values to corresponding Sets
-       * 3. Convert Sets to arrays and create QvdSymbol instances
-       * 4. Serialize symbols to binary format and update metadata
+       * A frame read from a file shows one half of some symbols: a dual read as its number or its text, a
+       * string read as a number. Its record says what each such cell stands for, so the frame writes back
+       * the symbols it was read from - the dual's text, Qlik's exact double, the string `'007'` - whichever
+       * rows the cells were moved to. A cell the record maps to more than one stored value is refused.
        *
-       * This approach provides:
-       * - 80-90% performance improvement for large datasets (100K+ rows)
-       * - Better cache locality (process all columns in one data traversal)
-       * - Lower memory pressure (no intermediate arrays per column)
+       * The complexity claim is the one to trust here: O(rows x columns) for the pass, and O(symbols)
+       * for the encoding. The "80-90% improvement" this comment once carried is not reproducible in this
+       * repository; `benchmarks/` measures what the writer costs now, which is the useful number.
        *
        * @private
        */
       _buildSymbolTable() {
-        this._symbolTable = [];
+        this._symbolCounts = [];
+        this._symbolFacts = [];
         this._symbolTableMetadata = [];
         this._symbolIndexByValue = [];
         if (this._df.columns.length === 0) {
@@ -614,33 +1397,144 @@ var init_QvdFileWriter = __esm({
         const data = this._df.data;
         const numColumns = columns.length;
         const numRows = data.length;
+        validateColumnNames(columns, this._path);
+        const record = normaliseStoredSymbols(this._df.storedSymbols);
         this._emitProgress("symbol-table", 0, numColumns);
-        const indexByValue = columns.map(() => /* @__PURE__ */ new Map());
+        const state = columns.map((name) => {
+          const entry = record === null ? null : record.find((candidate) => candidate.field === name) ?? null;
+          const byKey = /* @__PURE__ */ new Map();
+          let byValue = null;
+          let textByNumber = null;
+          if (entry !== null && valuesAreNumbers(entry)) {
+            textByNumber = firstTextByValue(entry);
+          } else if (entry !== null) {
+            byValue = /* @__PURE__ */ new Map();
+            for (let index = 0; index < entry.values.length; index++) {
+              const found = byValue.get(entry.values[index]);
+              if (found === void 0) {
+                byValue.set(entry.values[index], index);
+              } else if (typeof found === "number") {
+                byValue.set(entry.values[index], [found, index]);
+              } else {
+                found.push(index);
+              }
+            }
+          }
+          return {
+            name,
+            keys: [],
+            texts: [],
+            byKey,
+            // A cell is its own key without a record entry, and with one whose values are their numbers, so
+            // one Map serves both. On a field of distinct duals that is a map entry per symbol fewer.
+            byCell: entry === null || textByNumber !== null ? byKey : /* @__PURE__ */ new Map(),
+            byObject: /* @__PURE__ */ new Map(),
+            entry,
+            textByNumber,
+            byValue,
+            facts: { hasNumber: false, hasNonNumber: false, hasFraction: false }
+          };
+        });
+        const byCells = state.map((column) => column.byCell);
+        const byObjects = state.map((column) => column.byObject);
         const containsNull = columns.map(() => false);
         for (let row = 0; row < numRows; row++) {
           const values = data[row];
+          if (values !== null && values !== void 0 && !Array.isArray(values)) {
+            throw new QvdValidationError("Each row must be an array of values", {
+              row,
+              type: typeof values,
+              file: this._path,
+              stage: "buildSymbolTable"
+            });
+          }
+          if (values !== null && values !== void 0 && values.length > numColumns) {
+            throw new QvdValidationError(`Row ${row} has ${values.length} values but there are ${numColumns} fields`, {
+              row,
+              values: values.length,
+              fields: numColumns,
+              file: this._path,
+              stage: "buildSymbolTable"
+            });
+          }
           for (let column = 0; column < numColumns; column++) {
             const value = values?.[column];
             if (value === null || value === void 0) {
               containsNull[column] = true;
               continue;
             }
-            const map = indexByValue[column];
-            if (!map.has(value)) {
-              map.set(value, map.size);
+            if (typeof value === "object") {
+              if (!byObjects[column].has(value)) {
+                slotForObject(state[column], value, row, this._path);
+              }
+              continue;
+            }
+            if (byCells[column].has(value)) {
+              continue;
+            }
+            if (typeof value === "number") {
+              if (numberProblem(value) !== null) {
+                checkNumber(value, null, { column: columns[column], row, file: this._path, stage: "buildSymbolTable" });
+              }
+            } else if (typeof value === "string") {
+              if (textProblem(value) !== null) {
+                checkText(value, "A string value", {
+                  column: columns[column],
+                  row,
+                  file: this._path,
+                  stage: "buildSymbolTable"
+                });
+              }
+            } else {
+              refuseCell(value, columns[column], row, this._path);
             }
+            byCells[column].set(value, slotForCell(state[column], value, row, this._path));
           }
         }
         const columnBuffers = [];
         let symbolsOffset = 0;
         for (let column = 0; column < numColumns; column++) {
-          const symbols = Array.from(indexByValue[column].keys(), (value) => _QvdFileWriter._convertRawToSymbol(value));
-          const columnBuffer = Buffer.concat(symbols.map((symbol) => symbol.toByteRepresentation()));
+          const { keys, texts } = state[column];
+          const kinds = new Uint8Array(keys.length);
+          let byteLength = 0;
+          for (let slot = 0; slot < keys.length; slot++) {
+            const key = keys[slot];
+            const text = texts[slot];
+            if (typeof key === "number") {
+              if (numberProblem(key) !== null) {
+                checkNumber(key, null, { column: columns[column], file: this._path, stage: "buildSymbolTable" });
+              }
+              if (text !== null && textProblem(text) !== null) {
+                checkText(text, "The text of a dual value", {
+                  column: columns[column],
+                  file: this._path,
+                  stage: "buildSymbolTable"
+                });
+              }
+              kinds[slot] = kindOf(key, text);
+              byteLength += symbolByteLength(kinds[slot], key, text);
+            } else {
+              kinds[slot] = kindOf(null, key);
+              byteLength += symbolByteLength(kinds[slot], null, key);
+            }
+          }
+          const columnBuffer = Buffer.allocUnsafe(byteLength);
+          let offset = 0;
+          for (let slot = 0; slot < keys.length; slot++) {
+            const key = keys[slot];
+            offset = typeof key === "number" ? writeSymbol(columnBuffer, offset, kinds[slot], key, texts[slot]) : writeSymbol(columnBuffer, offset, kinds[slot], null, key);
+          }
+          assert2(offset === byteLength, "A column was encoded into a different number of bytes than it was sized for.");
           columnBuffers.push(columnBuffer);
-          this._symbolTableMetadata?.push([symbolsOffset, columnBuffer.length, containsNull[column]]);
-          this._symbolTable?.push(symbols);
-          this._symbolIndexByValue.push(indexByValue[column]);
-          symbolsOffset += columnBuffer.length;
+          this._symbolTableMetadata?.push([symbolsOffset, byteLength, containsNull[column]]);
+          this._symbolCounts?.push(keys.length);
+          this._symbolFacts?.push(state[column].facts);
+          this._symbolIndexByValue?.push({
+            byCell: state[column].byCell,
+            byKey: state[column].byKey,
+            byObject: state[column].byObject
+          });
+          symbolsOffset += byteLength;
           this._emitProgress("symbol-table", column + 1, numColumns);
         }
         this._symbolBuffer = Buffer.concat(columnBuffers);
@@ -669,7 +1563,7 @@ var init_QvdFileWriter = __esm({
        * @private
        */
       _buildIndexTable() {
-        assert2(this._symbolTable, "The QVD file symbol table has not been built.");
+        assert2(this._symbolCounts, "The QVD file symbol table has not been built.");
         assert2(this._symbolTableMetadata, "The QVD file symbol table metadata has not been built.");
         assert2(this._symbolIndexByValue, "The QVD file symbol index has not been built.");
         this._indexTableMetadata = [];
@@ -683,20 +1577,24 @@ var init_QvdFileWriter = __esm({
         let totalBits = 0;
         for (let column = 0; column < numColumns; column++) {
           const fieldContainsNull = this._symbolTableMetadata[column][2];
-          const symbolCount = this._symbolTable[column].length;
+          const symbolCount = this._symbolCounts[column];
           const nullShift = fieldContainsNull ? 2 : 0;
           const maxStoredIndex = symbolCount === 0 ? 0 : symbolCount - 1 + nullShift;
           const bitWidth = maxStoredIndex === 0 ? 0 : 32 - Math.clz32(maxStoredIndex);
-          for (const index of this._symbolIndexByValue[column].values()) {
-            if (index + nullShift > maxStoredIndex) {
-              throw new QvdValidationError("The symbol table and the index table are out of sync", {
-                field: columns[column],
-                storedIndex: index + nullShift,
-                maxStoredIndex,
-                symbolCount,
-                file: this._path,
-                stage: "buildIndexTable"
-              });
+          const lookup = this._symbolIndexByValue[column];
+          const maps = lookup.byCell === lookup.byKey ? [lookup.byKey, lookup.byObject] : Object.values(lookup);
+          for (const map of maps) {
+            for (const index of map.values()) {
+              if (index + nullShift > maxStoredIndex) {
+                throw new QvdValidationError("The symbol table and the index table are out of sync", {
+                  field: columns[column],
+                  storedIndex: index + nullShift,
+                  maxStoredIndex,
+                  symbolCount,
+                  file: this._path,
+                  stage: "buildIndexTable"
+                });
+              }
             }
           }
           layout.push({ geometry: fieldGeometry(totalBits, bitWidth), nullShift });
@@ -707,6 +1605,9 @@ var init_QvdFileWriter = __esm({
         this._recordByteSize = recordByteSize;
         this._indexBuffer = Buffer.alloc(numRows * recordByteSize);
         const progressInterval = Math.max(1, Math.floor(numRows / 100));
+        const byCells = this._symbolIndexByValue.map((lookup) => lookup.byCell);
+        const byKeys = this._symbolIndexByValue.map((lookup) => lookup.byKey);
+        const byObjects = this._symbolIndexByValue.map((lookup) => lookup.byObject);
         for (let row = 0, recordBase = 0; row < numRows; row++, recordBase += recordByteSize) {
           const values = data[row];
           for (let column = 0; column < numColumns; column++) {
@@ -714,7 +1615,7 @@ var init_QvdFileWriter = __esm({
             if (value === null || value === void 0) {
               continue;
             }
-            const index = this._symbolIndexByValue[column].get(value);
+            const index = typeof value === "object" ? byObjects[column].get(value) ?? byKeys[column].get(value.number) : byCells[column].get(value);
             if (index === void 0) {
               throw new QvdValidationError("A value is missing from the symbol table", {
                 field: columns[column],
@@ -731,29 +1632,6 @@ var init_QvdFileWriter = __esm({
         }
         this._symbolIndexByValue = null;
       }
-      /**
-       * Converts a raw value/literal to a QVD symbol.
-       *
-       * @param {any} raw The raw value/literal to convert.
-       * @return {QvdSymbol|null} The converted QVD symbol.
-       */
-      static _convertRawToSymbol(raw) {
-        if (raw === null || raw === void 0) {
-          return null;
-        }
-        const INT32_MIN = -2147483648;
-        const INT32_MAX = 2147483647;
-        const isInteger = typeof raw === "number" && Number.isInteger(raw);
-        const isFloat = typeof raw === "number" && !Number.isInteger(raw);
-        const isWithinInt32Range = typeof raw === "number" && raw >= INT32_MIN && raw <= INT32_MAX;
-        if (isInteger && isWithinInt32Range) {
-          return QvdSymbol.fromDualIntValue(raw, raw.toString());
-        } else if (isFloat || isInteger && !isWithinInt32Range) {
-          return QvdSymbol.fromDualDoubleValue(raw, raw.toString());
-        } else {
-          return QvdSymbol.fromStringValue(raw);
-        }
-      }
       /**
        * Persists the data frame to a QVD file.
        */
@@ -807,11 +1685,12 @@ function estimateRowMemory(rows, columnCount) {
   }
   return BASE_BYTES + rows * (ROW_BASE_BYTES + PER_CELL_BYTES * columnCount);
 }
-function estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true) {
+function estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true, rowsLive = null) {
   const FULL_PARSE_OVERHEAD = 6;
   const MINIMAL_OVERHEAD = 0.01;
   const rowsToLoad = maxRows === null || maxRows >= totalRows ? totalRows : maxRows;
-  const rowMemory = materialisesRows ? estimateRowMemory(rowsToLoad, columnCount) : BASE_BYTES;
+  const liveRows = rowsLive === null ? rowsToLoad : Math.min(rowsLive, rowsToLoad);
+  const rowMemory = materialisesRows ? estimateRowMemory(liveRows, columnCount) : BASE_BYTES;
   if (maxRows === null || maxRows >= totalRows) {
     return symbolTableSize * FULL_PARSE_OVERHEAD + rowMemory;
   }
@@ -821,18 +1700,44 @@ function estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount =
   const skippedSymbolsMemory = symbolTableSize * (1 - symbolPercentage) * MINIMAL_OVERHEAD;
   return keptSymbolsMemory + skippedSymbolsMemory + rowMemory;
 }
-function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, materialisesRows = true) {
-  if (estimateMemoryUsage(symbolTableSize, totalRows, totalRows, columnCount, materialisesRows) <= budget) {
+function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, materialisesRows = true, includeExternal = false) {
+  const costOf = /* @__PURE__ */ __name((rows) => estimateMemoryUsage(symbolTableSize, rows, totalRows, columnCount, materialisesRows) + (includeExternal ? estimateExternalMemory(Math.min(rows, totalRows), columnCount) : 0), "costOf");
+  if (costOf(totalRows) <= budget) {
     return totalRows;
   }
-  if (estimateMemoryUsage(symbolTableSize, 0, totalRows, columnCount, materialisesRows) > budget) {
+  if (costOf(0) > budget) {
     return 0;
   }
   let low = 0;
   let high = totalRows;
   while (high - low > 1) {
     const mid = Math.floor((low + high) / 2);
-    if (estimateMemoryUsage(symbolTableSize, mid, totalRows, columnCount, materialisesRows) <= budget) {
+    if (costOf(mid) <= budget) {
+      low = mid;
+    } else {
+      high = mid;
+    }
+  }
+  return low;
+}
+function recommendedChunkFor(budget, symbolTableSize, windowRows, totalRows, columnCount, liveRowsPerChunk = 1, includeExternal = false) {
+  const covered = windowRows === null || windowRows >= totalRows ? totalRows : windowRows;
+  const fits = /* @__PURE__ */ __name((chunk) => {
+    const live = Math.min(chunk * liveRowsPerChunk, covered);
+    const cost = estimateMemoryUsage(symbolTableSize, windowRows, totalRows, columnCount, true, chunk * liveRowsPerChunk) + (includeExternal ? estimateExternalMemory(live, columnCount) : 0);
+    return cost <= budget;
+  }, "fits");
+  if (fits(covered)) {
+    return covered;
+  }
+  if (!fits(1)) {
+    return 0;
+  }
+  let low = 1;
+  let high = covered;
+  while (high - low > 1) {
+    const mid = Math.floor((low + high) / 2);
+    if (fits(mid)) {
       low = mid;
     } else {
       high = mid;
@@ -840,7 +1745,7 @@ function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, mat
   }
   return low;
 }
-function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePath, safetyFactor = 0.8, columnCount = 0, materialisesRows = true) {
+function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePath, safetyFactor = 0.8, columnCount = 0, materialisesRows = true, live = null) {
   if (typeof safetyFactor !== "number" || safetyFactor < 0 || safetyFactor > 1) {
     throw new QvdValidationError("safetyFactor must be a number between 0.0 and 1.0", { safetyFactor });
   }
@@ -849,12 +1754,16 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
   }
   const budget = getMemoryBudget();
   const rowsToLoad = maxRows === null || maxRows >= totalRows ? totalRows : maxRows;
-  const heapMemory = estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount, materialisesRows);
-  const externalMemory = estimateExternalMemory(rowsToLoad, columnCount);
+  const rowsLive = live === null ? null : live.rows;
+  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 bounded = budget.candidates.map((candidate) => {
     const heapOnly = candidate.source === "V8 heap limit";
     return {
       ...candidate,
+      heapOnly,
       needs: heapOnly ? heapMemory : heapMemory + externalMemory,
       allowed: candidate.bytes * safetyFactor,
       bounds: heapOnly ? "the V8 heap" : "the whole process"
@@ -870,12 +1779,14 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
   const estimatedMemory = binding ? binding.needs : heapMemory;
   const maxAllowedMemory = binding ? binding.allowed : budget.bytes * safetyFactor;
   if (binding) {
+    const includeExternal = !binding.heapOnly;
     const recommendedMaxRows = recommendedRowsFor(
       maxAllowedMemory,
       symbolTableSize,
       totalRows,
       columnCount,
-      materialisesRows
+      materialisesRows,
+      includeExternal
     );
     const sizeMB = Math.round(symbolTableSize / 1024 / 1024);
     const estimatedMB = Math.round(estimatedMemory / 1024 / 1024);
@@ -887,15 +1798,27 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
     const limitingScope = binding.bounds;
     const budgetBreakdown = budget.candidates.map((candidate) => `${candidate.source} ${Math.round(candidate.bytes / 1024 / 1024)}MB`).join(", ");
     const observedBreakdown = budget.observed.map((entry) => `${entry.source} ${Math.round(entry.bytes / 1024 / 1024)}MB`).join(", ");
-    const nothingFits = recommendedMaxRows === 0;
     const containerBound = binding.source === "container memory limit";
+    const chunked = rowsLive !== null;
+    const recommendedChunk = chunked ? recommendedChunkFor(
+      maxAllowedMemory,
+      symbolTableSize,
+      maxRows,
+      totalRows,
+      columnCount,
+      liveRowsPerChunk,
+      includeExternal
+    ) : 0;
+    const knob = chunked ? "chunkSize" : "limit";
+    const recommendedValue = chunked ? recommendedChunk : recommendedMaxRows;
+    const nothingFits = recommendedValue === 0;
     let advice;
     if (nothingFits) {
-      advice = `No row count fits this budget - the symbol table alone exceeds it, so maxRows cannot help. ` + (containerBound ? `Raise the container's memory limit.` : `Raise the heap with --max-old-space-size, or raise memorySafetyFactor.`);
+      advice = `No row count fits this budget - the symbol table alone exceeds it, so ${knob} cannot help. ` + (containerBound ? `Raise the container's memory limit.` : `Raise the heap with --max-old-space-size, or raise memorySafetyFactor.`);
     } else if (containerBound) {
-      advice = `The binding limit is the container's, so raising --max-old-space-size would let V8 grow past it and be killed by the OOM killer instead. Set it below the container limit, raise the limit, or load fewer rows with maxRows (recommended: ${recommendedMaxRows.toLocaleString()} rows or less).`;
+      advice = `The binding limit is the container's, so raising --max-old-space-size would let V8 grow past it and be killed by the OOM killer instead. Set it below the container limit, raise the limit, or hold fewer rows with ${knob} (recommended: ${formatCount(recommendedValue)} rows or less).`;
     } else {
-      advice = `Try loading fewer rows using the maxRows parameter (recommended: ${recommendedMaxRows.toLocaleString()} rows or less), or raise the heap with --max-old-space-size.`;
+      advice = `Try holding fewer rows using the ${knob} parameter (recommended: ${formatCount(recommendedValue)} rows or less), or raise the heap with --max-old-space-size.`;
     }
     throw new QvdValidationError(
       `Insufficient memory to load file safely. Symbol table: ${sizeMB}MB, Estimated memory needed: ${estimatedMB}MB, Available: ${availableMB}MB (limited by ${limitingFactor}, which bounds ${limitingScope}; considered: ${budgetBreakdown}; observed but not used: ${observedBreakdown}). ` + advice,
@@ -915,32 +1838,55 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
         columnCount,
         totalRows,
         maxRows,
-        recommendedMaxRows
+        recommendedMaxRows,
+        // Only present when a chunk size is what overflowed, so a caller cannot mistake one
+        // recommendation for the other.
+        ...chunked ? { rowsLive, recommendedChunkSize: recommendedChunk } : {}
       }
     );
   }
 }
+function formatCount(value) {
+  return value.toLocaleString("en-US");
+}
 function warnLargeSymbolTable(symbolTableSize, maxRows, totalRows, columnCount = 0, materialisesRows = true) {
   const LARGE_SYMBOL_TABLE_WARNING = usableOldSpaceLimit() * 0.125;
-  if (symbolTableSize > LARGE_SYMBOL_TABLE_WARNING && (maxRows === null || maxRows >= totalRows)) {
-    const sizeMB = Math.round(symbolTableSize / 1024 / 1024);
-    const estimatedMemory = estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount, materialisesRows);
-    const estimatedMB = Math.round(estimatedMemory / 1024 / 1024);
-    const warnMB = Math.round(LARGE_SYMBOL_TABLE_WARNING / 1024 / 1024);
-    console.warn(
-      `\u26A0\uFE0F  Large symbol table detected (${sizeMB}MB > ${warnMB}MB threshold). Loading all ${totalRows.toLocaleString()} rows will use ~${estimatedMB}MB RAM. Consider using the maxRows parameter for better performance and lower memory usage.`
-    );
+  if (symbolTableSize <= LARGE_SYMBOL_TABLE_WARNING) {
+    return;
+  }
+  const rowsToLoad = maxRows === null || maxRows >= totalRows ? totalRows : maxRows;
+  const estimatedMemory = estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount, materialisesRows);
+  if (estimatedMemory <= LARGE_SYMBOL_TABLE_WARNING) {
+    return;
   }
+  const sizeMB = Math.round(symbolTableSize / 1024 / 1024);
+  const estimatedMB = Math.round(estimatedMemory / 1024 / 1024);
+  const warnMB = Math.round(LARGE_SYMBOL_TABLE_WARNING / 1024 / 1024);
+  console.warn(
+    `\u26A0\uFE0F  Large symbol table detected (${sizeMB}MB > ${warnMB}MB threshold). This read materialises ${formatCount(rowsToLoad)} of ${formatCount(totalRows)} rows and will use ~${estimatedMB}MB RAM. Reading fewer rows - with limit, maxRows, or a narrower offset window - lowers the row cost, though the symbol table is read in full either way.`
+  );
 }
 var HEAP_LIMIT_OVERSTATEMENT_BYTES, MINIMUM_BUDGET_BYTES, BASE_BYTES, ROW_BASE_BYTES, PER_CELL_BYTES;
 var init_memoryUtils = __esm({
   "src/util/memoryUtils.js"() {
     init_QvdErrors();
+    __name(getHeapLimit, "getHeapLimit");
+    __name(heapLimitIsMeaningful, "heapLimitIsMeaningful");
+    __name(getMemoryBudget, "getMemoryBudget");
     HEAP_LIMIT_OVERSTATEMENT_BYTES = 192 * 1024 * 1024;
     MINIMUM_BUDGET_BYTES = 64 * 1024 * 1024;
+    __name(usableOldSpaceLimit, "usableOldSpaceLimit");
     BASE_BYTES = 16 * 1024 * 1024;
     ROW_BASE_BYTES = 72;
     PER_CELL_BYTES = 8;
+    __name(estimateExternalMemory, "estimateExternalMemory");
+    __name(estimateRowMemory, "estimateRowMemory");
+    __name(estimateMemoryUsage, "estimateMemoryUsage");
+    __name(recommendedRowsFor, "recommendedRowsFor");
+    __name(recommendedChunkFor, "recommendedChunkFor");
+    __name(validateMemoryAvailability, "validateMemoryAvailability");
+    __name(formatCount, "formatCount");
+    __name(warnLargeSymbolTable, "warnLargeSymbolTable");
   }
 });
 
@@ -971,7 +1917,7 @@ function validateSymbolTableSizeEarly(symbolTableLength, filePath) {
     const maxMB = Math.round(MAX_SYMBOL_TABLE_SIZE / 1024 / 1024);
     const heapMB = Math.round(heapLimit / 1024 / 1024);
     throw new QvdValidationError(
-      `Symbol table too large (${sizeMB}MB exceeds ${maxMB}MB limit for lazy loading). This QVD file contains extremely high-cardinality fields. Limit scales with heap size (current: ${heapMB}MB, limit: 12.5% = ${maxMB}MB). Consider: (1) loading the full file without maxRows, (2) increasing heap size with --max-old-space-size, or (3) aggregating high-cardinality fields.`,
+      `Symbol table too large (${sizeMB}MB exceeds ${maxMB}MB limit for lazy loading). This QVD file contains extremely high-cardinality fields. Limit scales with heap size (current: ${heapMB}MB, limit: 12.5% = ${maxMB}MB). Consider: (1) loading the full file without a row window - maxRows, limit or offset - since the symbol table is read in full either way, (2) increasing heap size with --max-old-space-size, or (3) aggregating high-cardinality fields.`,
       {
         file: filePath,
         symbolTableSize: symbolTableLength,
@@ -1045,7 +1991,7 @@ function validateRecordCount(totalRows, filePath, stage = "parseIndexTable") {
     });
   }
 }
-function validateIndexTableMetadata(recordSize, totalRows, indexTableLength, indexTableOffset, bufferLength, rowsToLoad, filePath, fileSize = null) {
+function validateIndexTableMetadata(recordSize, totalRows, indexTableLength, indexTableOffset, bufferLength, rowsToLoad, filePath, fileSize = null, windowFirstRow = 0, bufferFirstRow = 0) {
   if (isNaN(recordSize) || !Number.isSafeInteger(recordSize) || recordSize < 0) {
     throw new QvdCorruptedError("Invalid record byte size", {
       recordSize,
@@ -1107,23 +2053,28 @@ function validateIndexTableMetadata(recordSize, totalRows, indexTableLength, ind
     }
   }
   const requiredIndexBytes = rowsToLoad * recordSize;
-  if (indexTableOffset + requiredIndexBytes > bufferLength) {
+  const bufferRecordStart = (windowFirstRow - bufferFirstRow) * recordSize;
+  if (indexTableOffset + bufferRecordStart + requiredIndexBytes > bufferLength) {
     throw new QvdCorruptedError("Index table truncated", {
       indexTableOffset,
       requiredBytes: requiredIndexBytes,
-      availableBytes: Math.max(0, bufferLength - indexTableOffset),
+      availableBytes: Math.max(0, bufferLength - indexTableOffset - bufferRecordStart),
       rowsToLoad,
+      windowFirstRow,
+      bufferFirstRow,
       recordSize,
       bufferSize: bufferLength,
       file: filePath,
       stage: "parseIndexTable"
     });
   }
-  if (indexTableLength < requiredIndexBytes) {
+  const requiredTableBytes = (windowFirstRow + rowsToLoad) * recordSize;
+  if (indexTableLength < requiredTableBytes) {
     throw new QvdCorruptedError("Index table length smaller than required", {
       indexTableLength,
-      requiredBytes: requiredIndexBytes,
+      requiredBytes: requiredTableBytes,
       rowsToLoad,
+      windowFirstRow,
       recordSize,
       file: filePath,
       stage: "parseIndexTable"
@@ -1184,262 +2135,235 @@ var init_validationUtils = __esm({
     init_QvdErrors();
     init_memoryUtils();
     init_bitUtils();
+    __name(validateHeaderStructure, "validateHeaderStructure");
+    __name(validateSymbolTableSizeEarly, "validateSymbolTableSizeEarly");
+    __name(validateSymbolTableSize, "validateSymbolTableSize");
+    __name(validateFieldMetadata, "validateFieldMetadata");
+    __name(validateRecordCount, "validateRecordCount");
+    __name(validateIndexTableMetadata, "validateIndexTableMetadata");
+    __name(validateFieldBitMetadata, "validateFieldBitMetadata");
   }
 });
 
 // src/util/symbolParser.js
-function parseIntegerSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath) {
-  if (pointer + 4 > bufferLength) {
-    throw new QvdCorruptedError("Buffer overflow reading integer symbol", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      file: filePath,
-      stage: "parseSymbolTable"
-    });
-  }
-  const byteData = new Int32Array(symbolBuffer.subarray(pointer, pointer + 4));
-  const value = Buffer.from(byteData).readIntLE(0, byteData.length);
-  return { symbol: QvdSymbol.fromIntValue(value), bytesRead: 4 };
-}
-function parseDoubleSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath) {
-  if (pointer + 8 > bufferLength) {
-    throw new QvdCorruptedError("Buffer overflow reading double symbol", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      file: filePath,
-      stage: "parseSymbolTable"
-    });
-  }
-  const byteData = new Int32Array(symbolBuffer.subarray(pointer, pointer + 8));
-  const value = Buffer.from(byteData).readDoubleLE(0);
-  return { symbol: QvdSymbol.fromDoubleValue(value), bytesRead: 8 };
-}
-function parseStringSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath) {
-  const startPointer = pointer;
-  const maxStringLength = 1048576;
-  let stringLength = 0;
-  while (pointer < bufferLength && symbolBuffer[pointer] !== 0) {
-    if (stringLength >= maxStringLength) {
-      throw new QvdCorruptedError("String symbol exceeds maximum length", {
-        field: fieldName,
-        maxLength: maxStringLength,
-        file: filePath,
-        stage: "parseSymbolTable"
-      });
-    }
-    pointer++;
-    stringLength++;
-  }
-  if (pointer >= bufferLength) {
-    throw new QvdCorruptedError("String symbol not null-terminated", {
+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) {
+    throw new QvdCorruptedError(`${kind} exceeds maximum length`, {
       field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
+      maxLength: MAX_TEXT_BYTES,
       file: filePath,
       stage: "parseSymbolTable"
     });
   }
-  const value = symbolBuffer.subarray(startPointer, pointer).toString("utf-8");
-  return { symbol: QvdSymbol.fromStringValue(value), bytesRead: pointer - startPointer + 1 };
-}
-function skipStringSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath) {
-  const startPointer = pointer;
-  const maxStringLength = 1048576;
-  let stringLength = 0;
-  while (pointer < bufferLength && symbolBuffer[pointer] !== 0) {
-    if (stringLength >= maxStringLength) {
-      throw new QvdCorruptedError("String symbol exceeds maximum length", {
-        field: fieldName,
-        maxLength: maxStringLength,
-        file: filePath,
-        stage: "parseSymbolTable"
-      });
-    }
-    pointer++;
-    stringLength++;
-  }
-  if (pointer >= bufferLength) {
-    throw new QvdCorruptedError("String symbol not null-terminated", {
+  if (found === -1) {
+    throw new QvdCorruptedError(`${kind} not null-terminated`, {
       field: fieldName,
-      pointer,
+      pointer: bufferLength,
       bufferSize: bufferLength,
       file: filePath,
       stage: "parseSymbolTable"
     });
   }
-  return pointer - startPointer + 1;
+  return found;
 }
-function parseDualIntegerSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath) {
-  if (pointer + 4 > bufferLength) {
-    throw new QvdCorruptedError("Buffer overflow reading dual integer symbol", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      file: filePath,
-      stage: "parseSymbolTable"
-    });
-  }
-  const intByteData = new Int32Array(symbolBuffer.subarray(pointer, pointer + 4));
-  const intValue = Buffer.from(intByteData).readIntLE(0, intByteData.length);
-  pointer += 4;
-  const stringStart = pointer;
-  const maxStringLength = 1048576;
-  let stringLength = 0;
-  while (pointer < bufferLength && symbolBuffer[pointer] !== 0) {
-    if (stringLength >= maxStringLength) {
-      throw new QvdCorruptedError("Dual string symbol exceeds maximum length", {
-        field: fieldName,
-        maxLength: maxStringLength,
-        file: filePath,
-        stage: "parseSymbolTable"
-      });
-    }
-    pointer++;
-    stringLength++;
-  }
-  if (pointer >= bufferLength) {
-    throw new QvdCorruptedError("Dual string symbol not null-terminated", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      file: filePath,
-      stage: "parseSymbolTable"
-    });
-  }
-  const stringValue = symbolBuffer.subarray(stringStart, pointer).toString("utf-8");
-  return { symbol: QvdSymbol.fromDualIntValue(intValue, stringValue), bytesRead: pointer - (stringStart - 4) + 1 };
+function overflow(message, pointer, bufferLength, fieldName, filePath) {
+  throw new QvdCorruptedError(message, {
+    field: fieldName,
+    pointer,
+    bufferSize: bufferLength,
+    file: filePath,
+    stage: "parseSymbolTable"
+  });
 }
-function parseDualDoubleSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath) {
-  if (pointer + 8 > bufferLength) {
-    throw new QvdCorruptedError("Buffer overflow reading dual double symbol", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      file: filePath,
-      stage: "parseSymbolTable"
-    });
-  }
-  const doubleByteData = new Int32Array(symbolBuffer.subarray(pointer, pointer + 8));
-  const doubleValue = Buffer.from(doubleByteData).readDoubleLE(0);
-  pointer += 8;
-  const stringStart = pointer;
-  const maxStringLength = 1048576;
-  let stringLength = 0;
-  while (pointer < bufferLength && symbolBuffer[pointer] !== 0) {
-    if (stringLength >= maxStringLength) {
-      throw new QvdCorruptedError("Dual string symbol exceeds maximum length", {
-        field: fieldName,
-        maxLength: maxStringLength,
-        file: filePath,
-        stage: "parseSymbolTable"
-      });
+function parseFieldSymbols(symbolBuffer, start, end, keep, fieldName, filePath) {
+  const bufferLength = symbolBuffer.length;
+  const numbers = [];
+  const texts = [];
+  let pointer = start;
+  while (pointer < end) {
+    const typeByte = symbolBuffer[pointer++];
+    const decode = keep === null || keep.has(numbers.length);
+    let number = null;
+    let text = null;
+    switch (typeByte) {
+      case 1: {
+        if (decode) {
+          if (pointer + 4 > bufferLength) {
+            overflow("Buffer overflow reading integer symbol", pointer, bufferLength, fieldName, filePath);
+          }
+          number = symbolBuffer.readInt32LE(pointer);
+        }
+        pointer += 4;
+        break;
+      }
+      case 2: {
+        if (decode) {
+          if (pointer + 8 > bufferLength) {
+            overflow("Buffer overflow reading double symbol", pointer, bufferLength, fieldName, filePath);
+          }
+          number = symbolBuffer.readDoubleLE(pointer);
+        }
+        pointer += 8;
+        break;
+      }
+      case 4: {
+        const terminator = textEnd(symbolBuffer, pointer, "String symbol", fieldName, filePath);
+        if (decode) {
+          text = symbolBuffer.toString("utf8", pointer, terminator);
+        }
+        pointer = terminator + 1;
+        break;
+      }
+      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);
+        }
+        const terminator = textEnd(symbolBuffer, pointer + numberBytes, "Dual string symbol", fieldName, filePath);
+        if (decode) {
+          number = typeByte === 5 ? symbolBuffer.readInt32LE(pointer) : symbolBuffer.readDoubleLE(pointer);
+          text = symbolBuffer.toString("utf8", pointer + numberBytes, terminator);
+        }
+        pointer = terminator + 1;
+        break;
+      }
+      default: {
+        throw new QvdParseError("Unknown symbol type byte", {
+          typeByte: typeByte.toString(16),
+          offset: pointer - 1,
+          file: filePath,
+          stage: "parseSymbolTable"
+        });
+      }
     }
-    pointer++;
-    stringLength++;
-  }
-  if (pointer >= bufferLength) {
-    throw new QvdCorruptedError("Dual string symbol not null-terminated", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      file: filePath,
-      stage: "parseSymbolTable"
-    });
+    numbers.push(number);
+    texts.push(text);
   }
-  const stringValue = symbolBuffer.subarray(stringStart, pointer).toString("utf-8");
-  return {
-    symbol: QvdSymbol.fromDualDoubleValue(doubleValue, stringValue),
-    bytesRead: pointer - (stringStart - 8) + 1
-  };
+  return { numbers, texts };
 }
-function skipDualSymbol(symbolBuffer, pointer, bufferLength, numericBytes, fieldName, filePath) {
-  if (pointer + numericBytes > bufferLength) {
-    throw new QvdCorruptedError(`Buffer overflow reading dual symbol`, {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      file: filePath,
-      stage: "parseSymbolTable"
-    });
+var MAX_TEXT_BYTES;
+var init_symbolParser = __esm({
+  "src/util/symbolParser.js"() {
+    init_QvdErrors();
+    MAX_TEXT_BYTES = 1048576;
+    __name(textEnd, "textEnd");
+    __name(overflow, "overflow");
+    __name(parseFieldSymbols, "parseFieldSymbols");
   }
-  const startPointer = pointer;
-  pointer += numericBytes;
-  const maxStringLength = 1048576;
-  let stringLength = 0;
-  while (pointer < bufferLength && symbolBuffer[pointer] !== 0) {
-    if (stringLength >= maxStringLength) {
-      throw new QvdCorruptedError("Dual string symbol exceeds maximum length", {
-        field: fieldName,
-        maxLength: maxStringLength,
-        file: filePath,
-        stage: "parseSymbolTable"
-      });
+});
+
+// src/util/resolveSymbols.js
+function resolveFieldSymbols(symbols, field, mode, coerce, wantHalves) {
+  const length = symbols.numbers.length;
+  const values = new Array(length);
+  const entryValues = [];
+  const numbers = [];
+  const texts = [];
+  let pure = 0;
+  let partial = false;
+  for (let index = 0; index < length; index++) {
+    const text = symbols.texts[index];
+    const number = symbols.numbers[index];
+    if (text === null) {
+      values[index] = number === null ? void 0 : number;
+      if (number !== null) pure++;
+      continue;
     }
-    pointer++;
-    stringLength++;
+    if (number === null) {
+      if (coerce && isNumericText(text)) {
+        values[index] = Number(text);
+        entryValues.push(values[index]);
+        numbers.push(null);
+        texts.push(text);
+        partial = true;
+      } else {
+        values[index] = text;
+        pure++;
+      }
+      continue;
+    }
+    partial = true;
+    if (mode === "both") {
+      values[index] = dualFromSymbol(number, text);
+      continue;
+    }
+    values[index] = mode === "number" || coerce && isNumericText(text) ? number : text;
+    entryValues.push(values[index]);
+    numbers.push(number);
+    texts.push(text);
   }
-  if (pointer >= bufferLength) {
-    throw new QvdCorruptedError("Dual string symbol not null-terminated", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      file: filePath,
-      stage: "parseSymbolTable"
+  let entry = null;
+  if (entryValues.length > 0) {
+    entry = pure > 0 && collides(symbols, values, new Set(entryValues)) ? collisionEntry(symbols, field, values, mode) : Object.freeze({
+      field,
+      values: Object.freeze(entryValues),
+      numbers: Object.freeze(numbers),
+      texts: Object.freeze(texts)
     });
   }
-  return pointer - startPointer + 1;
+  return { values, entry, halves: wantHalves && partial ? symbolHalves(symbols) : null };
 }
-function parseSymbol(typeByte, symbolBuffer, pointer, bufferLength, fieldName, filePath, shouldParse) {
-  switch (typeByte) {
-    case 1: {
-      if (shouldParse) {
-        return parseIntegerSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
-      }
-      return { symbol: null, bytesRead: 4 };
+function collides(symbols, values, recorded) {
+  for (let index = 0; index < values.length; index++) {
+    if (!isPure(symbols, index, values[index])) {
+      continue;
     }
-    case 2: {
-      if (shouldParse) {
-        return parseDoubleSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
-      }
-      return { symbol: null, bytesRead: 8 };
-    }
-    case 4: {
-      if (shouldParse) {
-        return parseStringSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
-      }
-      const bytesRead = skipStringSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
-      return { symbol: null, bytesRead };
+    if (recorded.has(values[index])) {
+      return true;
     }
-    case 5: {
-      if (shouldParse) {
-        return parseDualIntegerSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
-      }
-      const bytesRead = skipDualSymbol(symbolBuffer, pointer, bufferLength, 4, fieldName, filePath);
-      return { symbol: null, bytesRead };
+  }
+  return false;
+}
+function isPure(symbols, index, value) {
+  const text = symbols.texts[index];
+  const number = symbols.numbers[index];
+  return text === null ? number !== null : number === null && value === text;
+}
+function collisionEntry(symbols, field, values, mode) {
+  const recorded = /* @__PURE__ */ new Set();
+  const inPassA = values.map((value, index) => {
+    if (symbols.numbers[index] === null && symbols.texts[index] === null || isPure(symbols, index, value)) {
+      return false;
     }
-    case 6: {
-      if (shouldParse) {
-        return parseDualDoubleSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
-      }
-      const bytesRead = skipDualSymbol(symbolBuffer, pointer, bufferLength, 8, fieldName, filePath);
-      return { symbol: null, bytesRead };
+    const recordedHere = !(mode === "both" && symbols.texts[index] !== null && symbols.numbers[index] !== null);
+    if (recordedHere) {
+      recorded.add(values[index]);
     }
-    default: {
-      throw new QvdParseError("Unknown symbol type byte", {
-        typeByte: typeByte.toString(16),
-        offset: pointer - 1,
-        file: filePath,
-        stage: "parseSymbolTable"
-      });
+    return recordedHere;
+  });
+  const entryValues = [];
+  const numbers = [];
+  const texts = [];
+  for (let index = 0; index < values.length; index++) {
+    if (inPassA[index] || isPure(symbols, index, values[index]) && recorded.has(values[index])) {
+      entryValues.push(values[index]);
+      numbers.push(symbols.numbers[index]);
+      texts.push(symbols.texts[index]);
     }
   }
+  return Object.freeze({
+    field,
+    values: Object.freeze(entryValues),
+    numbers: Object.freeze(numbers),
+    texts: Object.freeze(texts)
+  });
 }
-var init_symbolParser = __esm({
-  "src/util/symbolParser.js"() {
-    init_QvdSymbol();
-    init_QvdErrors();
+function symbolHalves(symbols) {
+  return Object.freeze({ texts: Object.freeze(symbols.texts), numbers: Object.freeze(symbols.numbers) });
+}
+var init_resolveSymbols = __esm({
+  "src/util/resolveSymbols.js"() {
+    init_QvdDual();
+    init_cellRules();
+    __name(resolveFieldSymbols, "resolveFieldSymbols");
+    __name(collides, "collides");
+    __name(isPure, "isPure");
+    __name(collisionEntry, "collisionEntry");
+    __name(symbolHalves, "symbolHalves");
   }
 });
 
@@ -1449,20 +2373,49 @@ __export(QvdColumnTable_exports, {
   QvdColumn: () => QvdColumn,
   QvdColumnTable: () => QvdColumnTable
 });
+function numberOf(value, number) {
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string") {
+    return number ?? NaN;
+  }
+  const dual = asDual(value);
+  return dual !== null && typeof dual.number === "number" ? dual.number : NaN;
+}
+function textOf(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  const dual = asDual(value);
+  return dual !== null && typeof dual.text === "string" ? dual.text : null;
+}
 var QvdColumn, QvdColumnTable;
 var init_QvdColumnTable = __esm({
   "src/QvdColumnTable.js"() {
     init_QvdErrors();
+    init_cellRules();
+    init_readOptions();
+    __name(numberOf, "numberOf");
+    __name(textOf, "textOf");
     QvdColumn = class {
+      static {
+        __name(this, "QvdColumn");
+      }
       /**
        * @param {string} name The field name.
        * @param {Int32Array} codes One stored index per row, bias applied. Negative means NULL.
        * @param {Array<any>} symbols The field's distinct values, indexed by code.
+       * @param {SymbolHalves|null} [halves=null] Both halves of each symbol, aligned with `symbols`, for a
+       *   field whose values do not show them all - a dual read as one half, a string read as a number.
+       *   Without them, the halves are derived from the values: a string is its own text, a dual has its
+       *   own, and a number has none.
        */
-      constructor(name, codes, symbols) {
+      constructor(name, codes, symbols, halves = null) {
         this._name = name;
         this._codes = codes;
         this._symbols = symbols;
+        this._halves = halves;
         Object.freeze(this);
       }
       /** @return {string} The field name. */
@@ -1489,6 +2442,9 @@ var init_QvdColumnTable = __esm({
        *
        * One entry per distinct value, not per row: a few thousand entries for a column of millions.
        *
+       * A windowed read that filters the symbol table decodes only the symbols its rows use. Every other
+       * entry is `undefined` - not `null`, which a QVD never stores as a symbol - and no code refers to it.
+       *
        * @return {ReadonlyArray<any>} The dictionary.
        */
       get symbols() {
@@ -1512,6 +2468,42 @@ var init_QvdColumnTable = __esm({
         const code = this._codes[row];
         return code < 0 ? null : this._symbols[code];
       }
+      /**
+       * The text of one row: the text Qlik displays for its value.
+       *
+       * A string is its own text and a dual has its own. A value read as one half of a symbol - a date
+       * read as its serial, a string read as a number - has the text the file stores for it, and a pure
+       * number has none.
+       *
+       * @param {number} row The row index.
+       * @return {string|null} The text, or null for NULL and for a number with no text.
+       * @throws {QvdValidationError} If the row is not an integer within the column.
+       */
+      textAt(row) {
+        if (!Number.isInteger(row) || row < 0 || row >= this._codes.length) {
+          throw new QvdValidationError("Row index out of bounds", {
+            column: this._name,
+            row,
+            length: this._codes.length
+          });
+        }
+        const code = this._codes[row];
+        if (code < 0) {
+          return null;
+        }
+        return this._halves !== null ? this._halves.texts[code] ?? null : textOf(this._symbols[code]);
+      }
+      /**
+       * The text of each distinct value, indexed by the codes, as `textAt` gives it per row.
+       *
+       * @return {ReadonlyArray<string|null>} One text per symbol, null where a symbol has none.
+       */
+      symbolTexts() {
+        if (this._halves !== null) {
+          return this._halves.texts;
+        }
+        return Object.freeze(this._symbols.map(textOf));
+      }
       /**
        * Iterates the column's values without materialising it.
        *
@@ -1555,6 +2547,9 @@ var init_QvdColumnTable = __esm({
        * one. Non-numeric symbols become NaN, which is safe here in a way it is not per row: the
        * codes still distinguish NULL, and a caller that wants the blank back still has `symbols`.
        *
+       * A dual is its number, however it was read: a `QvdDual` gives `.number`, and a date read with
+       * `{duals: 'text'}` gives the serial the file stores for it, not NaN.
+       *
        * Scanning `codes` against this is the fastest way to read a column, because both sides are
        * contiguous typed arrays and the dictionary fits in cache:
        *
@@ -1576,8 +2571,7 @@ var init_QvdColumnTable = __esm({
       numericSymbols() {
         const out = new Float64Array(this._symbols.length);
         for (let index = 0; index < this._symbols.length; index++) {
-          const value = this._symbols[index];
-          out[index] = typeof value === "number" ? value : NaN;
+          out[index] = numberOf(this._symbols[index], this._halves?.numbers[index] ?? null);
         }
         return out;
       }
@@ -1592,7 +2586,8 @@ var init_QvdColumnTable = __esm({
        * @param {Object} [options] Conversion options.
        * @param {'throw'|'nan'} [options.onNonNumeric='throw'] What to do with a value that is not a
        *   number - including NULL. `'throw'` refuses and names the offending row; `'nan'` writes
-       *   NaN, which is the right choice only when the caller knows the column is numeric.
+       *   NaN, which is the right choice only when the caller knows the column is numeric. A dual is a
+       *   number here, as it is to `numericSymbols`.
        * @return {Float64Array} One number per row.
        * @throws {QvdValidationError} If a value is not a number and `onNonNumeric` is `'throw'`.
        */
@@ -1612,6 +2607,11 @@ var init_QvdColumnTable = __esm({
             out[row] = value;
             continue;
           }
+          const number = value === null ? NaN : numberOf(value, this._halves?.numbers[code] ?? null);
+          if (!Number.isNaN(number)) {
+            out[row] = number;
+            continue;
+          }
           if (onNonNumeric === "throw") {
             throw new QvdValidationError("Column holds a value that is not a number", {
               column: this._name,
@@ -1627,29 +2627,57 @@ var init_QvdColumnTable = __esm({
       }
     };
     QvdColumnTable = class {
+      static {
+        __name(this, "QvdColumnTable");
+      }
       /**
        * @param {Object} decoded What the reader decoded.
        * @param {Array<string>} decoded.columns Field names, in file order.
        * @param {Array<Int32Array>} decoded.codesByField One code array per field.
        * @param {Array<Array<any>>} decoded.symbolsByField One dictionary per field.
+       * @param {Array<SymbolHalves|null>} [decoded.halvesByField] Both halves of each symbol, per field,
+       *   or null for a field whose values show them.
        * @param {number} decoded.rowCount Rows decoded.
        * @param {any} decoded.metadata The raw QvdTableHeader.
+       * @param {import('./util/storedSymbols.js').StoredSymbols|null} [decoded.storedSymbols] The
+       *   stored-symbol record, as a data frame of the same read carries it.
        * @param {any} decoded.loadStats Statistics about the read.
        */
-      constructor({ columns, codesByField, symbolsByField, rowCount, metadata, loadStats }) {
+      constructor({ columns, codesByField, symbolsByField, halvesByField, rowCount, metadata, storedSymbols, loadStats }) {
         this._columns = columns;
         this._codesByField = codesByField;
         this._symbolsByField = symbolsByField;
+        this._halvesByField = halvesByField ?? null;
         this._rowCount = rowCount;
         this._metadata = metadata;
+        this._storedSymbols = storedSymbols ?? null;
         this._loadStats = loadStats;
       }
       /**
        * Reads a QVD file as columns.
        *
+       * Takes the same options as `QvdDataFrame.fromQvd`, with the same meanings - one option
+       * vocabulary for both read paths, because they are two answers about the same file rather than
+       * two features. `{offset, limit}` is how a caller pages through a file columnwise; there is no
+       * columnar `iterate()` because there is nothing for it to bound - a columnar read materialises
+       * no rows, which is the memory chunking exists to cap.
+       *
        * @param {string} path The path to the QVD file.
        * @param {Object} [options] Loading options, with the same meanings they have on `fromQvd`.
-       * @param {number|null} [options.maxRows] Maximum rows to decode.
+       * @param {number|null} [options.maxRows] Rows to decode. The older name for `limit`.
+       * @param {number|null} [options.limit] Rows to decode, counting from `offset`.
+       * @param {number} [options.offset] File row to start at.
+       * @param {Array<string>|null} [options.fields] Field names to read, in the order they should
+       *   appear. Unselected fields have their symbols skipped entirely.
+       * @param {'number'|'text'|'both'} [options.duals='number'] What a dual symbol's value is: its
+       *   number, its text, or a frozen `QvdDual` holding both. Whichever it is, `column.textAt` gives the
+       *   text and `numericSymbols` the number. Anything else throws.
+       * @param {boolean} [options.coerceNumericStrings=false] Whether a value that would be a string is a
+       *   number when its text is not blank and `Number(text)` is finite - a string symbol as
+       *   `Number(text)`, a dual read as text as its stored number. `column.textAt` still gives the text.
+       *   Anything but a boolean throws.
+       * @param {Function} [options.onProgress] Progress callback, `{stage, current, total, percent}`.
+       * @param {AbortSignal} [options.signal] Cancels the read.
        * @param {string} [options.allowedDir] Directory the path must resolve inside.
        * @param {number} [options.memorySafetyFactor] Fraction of the memory budget a load may use.
        * @param {number} [options.symbolFilteringThreshold] Symbol table size above which a limited
@@ -1659,15 +2687,13 @@ var init_QvdColumnTable = __esm({
       static async fromQvd(path3, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
         const reader = new QvdFileReader2(path3, {
-          allowedDir: options.allowedDir,
-          memorySafetyFactor: options.memorySafetyFactor,
-          symbolFilteringThreshold: options.symbolFilteringThreshold,
+          ...readerOptionsFrom(options),
           // This read builds no rows, so the memory guard must not charge it for them. A columnar
           // read of the 38MB taxi fixture completes in a 15MB heap; charged the row cost it was
           // refused below a 2GB one.
           materialisesRows: false
         });
-        return await reader.loadColumnar(options.maxRows !== void 0 ? options.maxRows : null);
+        return await reader.loadColumnar(windowFrom(options));
       }
       /** @return {Array<string>} Field names, in file order. */
       get columns() {
@@ -1689,6 +2715,14 @@ var init_QvdColumnTable = __esm({
       get loadStats() {
         return this._loadStats;
       }
+      /**
+       * The stored-symbol record of the read, as `QvdDataFrame.storedSymbols` describes it.
+       *
+       * @return {import('./util/storedSymbols.js').StoredSymbols|null} The record, or null.
+       */
+      get storedSymbols() {
+        return this._storedSymbols;
+      }
       /**
        * One column.
        *
@@ -1704,7 +2738,12 @@ var init_QvdColumnTable = __esm({
             availableColumns: this._columns
           });
         }
-        return new QvdColumn(name, this._codesByField[index], this._symbolsByField[index]);
+        return new QvdColumn(
+          name,
+          this._codesByField[index],
+          this._symbolsByField[index],
+          this._halvesByField?.[index] ?? null
+        );
       }
     };
   }
@@ -1715,7 +2754,17 @@ var QvdFileReader_exports = {};
 __export(QvdFileReader_exports, {
   QvdFileReader: () => QvdFileReader
 });
-var MAX_HEADER_SIZE, READ_CHUNK_SIZE, QvdFileReader;
+function closeReadStream(stream) {
+  if (stream.closed) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    stream.once("close", () => resolve());
+    stream.once("error", () => resolve());
+    stream.destroy();
+  });
+}
+var MAX_HEADER_SIZE, READ_CHUNK_SIZE, ANALYSIS_SLICE_ROWS, QvdFileReader;
 var init_QvdFileReader = __esm({
   "src/QvdFileReader.js"() {
     init_QvdDataFrame();
@@ -1725,9 +2774,17 @@ var init_QvdFileReader = __esm({
     init_memoryUtils();
     init_validationUtils();
     init_symbolParser();
+    init_readOptions();
+    init_resolveSymbols();
+    init_storedSymbols();
     MAX_HEADER_SIZE = 16 * 1024 * 1024;
     READ_CHUNK_SIZE = 512 * 1024 * 1024;
+    ANALYSIS_SLICE_ROWS = 65536;
+    __name(closeReadStream, "closeReadStream");
     QvdFileReader = class {
+      static {
+        __name(this, "QvdFileReader");
+      }
       /**
        * Constructs a new QVD file parser.
        *
@@ -1738,9 +2795,10 @@ var init_QvdFileReader = __esm({
        *   points outside it is rejected. Defaults to the current working directory. To permit
        *   an entire volume, pass its root explicitly ('/' on POSIX, 'C:\\' on Windows); a null or
        *   empty value falls back to the working directory rather than removing the restriction.
-       * @param {number} [options.memorySafetyFactor=0.3] Fraction (0.0-1.0) of the memory budget a
-       *   load may use. The budget is the smallest of the V8 heap limit, any container memory limit,
-       *   and the memory the OS reports as available. Default is 0.3. **Zero disables the memory
+       * @param {number} [options.memorySafetyFactor=0.8] Fraction (0.0-1.0) of the memory budget a
+       *   load may use. The budget is the smaller of the V8 heap limit and any container memory limit;
+       *   what the OS reports as available is recorded for diagnostics and deliberately not allowed to
+       *   bind - see `getMemoryBudget`. Default is 0.8. **Zero disables the memory
        *   check entirely**, which is the escape hatch for runtimes whose limits cannot be measured -
        *   Bun reports its current heap as its heap limit - and for callers who would rather manage
        *   memory themselves than trust the estimate.
@@ -1751,41 +2809,123 @@ 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 {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
+       *   text Qlik displays for it, such as a date - reads as. `'number'` gives its number, which is the
+       *   value Qlik sums, sorts and compares by; `'text'` gives its text; `'both'` gives a frozen
+       *   `QvdDual` holding both halves, shared by every row that holds the symbol. Under `'number'` and
+       *   `'text'` the half a cell does not show is kept in the frame's `storedSymbols`, so a write stores
+       *   the dual again. An int, a double, a string and NULL read the same in every mode. Any other value
+       *   throws a `QvdValidationError`.
+       * @param {boolean} [options.coerceNumericStrings=false] Whether a cell that would read as a string
+       *   reads as a number when its text is not blank and `Number(text)` is finite: a string symbol in
+       *   every `duals` mode, as `Number(text)`, and a dual's text under `duals: 'text'`, as the number the
+       *   dual stores. The text is kept in the frame's `storedSymbols`, so a write stores the string or the
+       *   dual again. Anything but a boolean, `undefined` or null throws a `QvdValidationError`.
+       * @param {Function} [options.onProgress] Called with `{stage, current, total, percent}` as the
+       *   read proceeds - the same shape `QvdFileWriter` emits.
+       * @param {AbortSignal} [options.signal] Cancels the read. When it is aborted the read throws
+       *   `signal.reason`, exactly as `signal.throwIfAborted()` does.
        */
       constructor(filePath, options = {}) {
         const {
           allowedDir,
           memorySafetyFactor = 0.8,
           symbolFilteringThreshold = 50 * 1024 * 1024,
-          materialisesRows = true
+          materialisesRows = true,
+          fields = null,
+          duals,
+          coerceNumericStrings,
+          onProgress,
+          signal
         } = options;
         this._materialisesRows = materialisesRows;
         this._path = validatePath(filePath, allowedDir);
+        this._duals = normaliseDuals(duals, this._path);
+        this._coerceNumericStrings = normaliseCoerceNumericStrings(coerceNumericStrings, this._path);
         this._memorySafetyFactor = memorySafetyFactor;
         this._symbolFilteringThreshold = symbolFilteringThreshold;
+        if (onProgress !== void 0 && typeof onProgress !== "function") {
+          throw new QvdValidationError("onProgress must be a function", {
+            provided: onProgress,
+            type: typeof onProgress,
+            file: this._path
+          });
+        }
+        if (signal !== void 0 && (typeof signal !== "object" || signal === null || typeof signal.aborted !== "boolean")) {
+          throw new QvdValidationError("signal must be an AbortSignal", {
+            provided: signal,
+            type: typeof signal,
+            file: this._path
+          });
+        }
+        this._requestedFields = fields === void 0 ? null : fields;
+        this._onProgress = onProgress;
+        this._signal = signal;
         this._buffer = null;
         this._headerOffset = null;
         this._symbolTableOffset = null;
         this._indexTableOffset = null;
         this._header = null;
+        this._allFields = null;
+        this._selectedFields = null;
+        this._fieldBitMetadataValidated = false;
         this._symbolTable = null;
         this._indexColumns = null;
         this._rowsDecoded = 0;
+        this._bufferFirstRow = 0;
         this._fileSize = null;
         this._headerMatchesFile = false;
       }
+      /**
+       * Emits a progress event if a callback is registered.
+       *
+       * The same shape `QvdFileWriter._emitProgress` emits, deliberately: a caller who has written a
+       * progress bar for a write should not have to write a second one for a read. The stage names
+       * differ because the stages differ, but `symbol-table` and `index-table` mean the same thing on
+       * both sides.
+       *
+       * @param {string} stage The current stage of the read.
+       * @param {number} current The current progress value.
+       * @param {number} total The total progress value.
+       * @private
+       */
+      _emitProgress(stage, current, total) {
+        if (this._onProgress) {
+          const percent = total > 0 ? Math.round(current / total * 100) : 100;
+          this._onProgress({ stage, current, total, percent });
+        }
+      }
+      /**
+       * Throws if the caller has cancelled the read.
+       *
+       * Throws `signal.reason` - a `DOMException` named `AbortError` unless the caller aborted with a
+       * reason of their own. That is what `AbortSignal` means everywhere else in Node, and inventing
+       * a `QvdAbortError` here would make this library's cancellation the one a caller has to special
+       * case.
+       *
+       * @private
+       */
+      _throwIfAborted() {
+        if (this._signal) {
+          this._signal.throwIfAborted();
+        }
+      }
       /**
        * Reads the binary data of the QVD file.
        *
-       * LAZY LOADING OPTIMIZATION: When maxRows is specified, this method implements
-       * true lazy loading by reading only the necessary portions of the file from disk.
+       * 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.
        *
-       * For large files (e.g., 5GB), loading only the first 1000 rows can save significant
-       * memory and time:
-       * - Full load: 5GB in memory, ~30-60s load time
-       * - Lazy load (maxRows=1000): ~1.75-2GB in memory, ~2-5s load time
+       * 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 Lazy Loading:
+       * Algorithm for a windowed read:
        * 1. Stream-read the file until 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
@@ -1798,14 +2938,23 @@ var init_QvdFileReader = __esm({
        * - Streaming for header finding is efficient for unknown header sizes
        * - Direct byte-range reading for remaining data is fastest
        *
-       * @param {number|null} maxRows The maximum number of rows to load. If null, all data is loaded.
+       * 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 {{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(maxRows = null, headerOnly = false) {
+      async _readData(window = { offset: 0, limit: null }, headerOnly = false, liveRows = null) {
+        this._throwIfAborted();
+        this._emitProgress("read", 0, 1);
         const HEADER_DELIMITER = "\r\n\0";
         const CHUNK_SIZE = 64 * 1024;
         const stream = fs.createReadStream(this._path, {
@@ -1847,6 +2996,8 @@ var init_QvdFileReader = __esm({
           if (!isExpectedEarlyClose) {
             throw error;
           }
+        } finally {
+          await closeReadStream(stream);
         }
         if (headerDelimiterIndex === -1) {
           throw new QvdCorruptedError(
@@ -1875,13 +3026,14 @@ var init_QvdFileReader = __esm({
         const totalRows = parseInt(headerObj["QvdTableHeader"]["NoOfRecords"], 10);
         if (headerOnly) {
           this._buffer = headerBuffer.subarray(0, headerEndIndex);
+          this._emitProgress("read", 1, 1);
           return;
         }
         let headerFields = headerObj["QvdTableHeader"]?.["Fields"]?.["QvdFieldHeader"];
         if (headerFields && !Array.isArray(headerFields)) {
           headerFields = [headerFields];
         }
-        const columnCount = Array.isArray(headerFields) ? headerFields.length : 0;
+        const columnCount = Array.isArray(headerFields) ? selectFields(headerFields, this._requestedFields, this._path).length : 0;
         const headerNumbersUsable = [symbolTableLength, recordSize, totalRows].every(
           (value) => Number.isSafeInteger(value) && value >= 0
         );
@@ -1890,23 +3042,28 @@ var init_QvdFileReader = __esm({
           this._fileSize = fileSize;
           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,
-            maxRows,
+            windowRows,
             totalRows,
             this._path,
             this._memorySafetyFactor,
             columnCount,
-            this._materialisesRows
+            this._materialisesRows,
+            liveRows
           );
         }
-        if (maxRows === null) {
+        if (window.offset === 0 && window.limit === null) {
           this._buffer = await fs.promises.readFile(this._path);
           this._fileSize = this._buffer.length;
+          this._bufferFirstRow = 0;
+          this._emitProgress("read", 1, 1);
           return;
         }
-        const rowsToLoad = Math.min(maxRows, totalRows);
+        const rowsToLoad = windowRows;
         validateSymbolTableSizeEarly(symbolTableLength, this._path);
         for (const [name, value] of [
           ["Offset", symbolTableLength],
@@ -1922,39 +3079,78 @@ var init_QvdFileReader = __esm({
             });
           }
         }
+        const skippedIndexBytes = resolved.offset * recordSize;
         const indexTableBytesToRead = rowsToLoad * recordSize;
         const totalBytesToRead = indexTableOffset + indexTableBytesToRead;
+        const fileBytesRequired = indexTableOffset + skippedIndexBytes + indexTableBytesToRead;
         const fd = await fs.promises.open(this._path, "r");
         try {
           const { size: fileSize } = await fd.stat();
           this._fileSize = fileSize;
-          if (totalBytesToRead > fileSize) {
+          if (fileBytesRequired > fileSize) {
             throw new QvdCorruptedError("The file is shorter than its header claims.", {
               file: this._path,
               fileSize,
-              requiredBytes: totalBytesToRead,
+              requiredBytes: fileBytesRequired,
               stage: "readData"
             });
           }
           this._buffer = Buffer.alloc(totalBytesToRead);
-          let position = 0;
-          while (position < totalBytesToRead) {
-            const length = Math.min(READ_CHUNK_SIZE, totalBytesToRead - position);
-            const { bytesRead } = await fd.read(this._buffer, position, length, position);
-            if (bytesRead === 0) {
-              throw new QvdCorruptedError("Unexpected end of file while reading QVD data.", {
-                file: this._path,
-                fileSize,
-                bytesRead: position,
-                requiredBytes: totalBytesToRead,
-                stage: "readData"
-              });
-            }
-            position += bytesRead;
+          await this._readRange(fd, 0, indexTableOffset, 0, fileSize, totalBytesToRead);
+          if (indexTableBytesToRead > 0) {
+            await this._readRange(
+              fd,
+              indexTableOffset,
+              indexTableBytesToRead,
+              indexTableOffset + skippedIndexBytes,
+              fileSize,
+              fileBytesRequired
+            );
           }
+          this._bufferFirstRow = resolved.offset;
         } finally {
           await fd.close();
         }
+        this._emitProgress("read", 1, 1);
+      }
+      /**
+       * Reads one byte range of the file into the 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 {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.
+       * @private
+       */
+      async _readRange(fd, bufferOffset, byteCount, filePosition, fileSize, requiredBytes) {
+        assert2(this._buffer, "The read buffer has not been allocated.");
+        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);
+          if (bytesRead === 0) {
+            throw new QvdCorruptedError("Unexpected end of file while reading QVD data.", {
+              file: this._path,
+              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
+              // read of a truncated file claim tens of megabytes had been read when a few hundred
+              // bytes had.
+              bytesRead: done,
+              filePosition: filePosition + done,
+              requiredBytes,
+              stage: "readData"
+            });
+          }
+          done += bytesRead;
+        }
       }
       /**
        * Parses the XML header of the QVD file. This method is part of the parsing process
@@ -2014,6 +3210,8 @@ var init_QvdFileReader = __esm({
         this._headerOffset = headerBeginIndex;
         this._symbolTableOffset = headerEndIndex;
         this._indexTableOffset = this._symbolTableOffset + parseInt(this._header["QvdTableHeader"]["Offset"], 10);
+        this._allFields = fieldList;
+        this._selectedFields = selectFields(this._allFields, this._requestedFields, this._path);
       }
       /**
        * Establishes the geometry of the index table, and validates it.
@@ -2024,30 +3222,29 @@ var init_QvdFileReader = __esm({
        * about keeping the sign in step with the other one: the two could drift, and #113 is what
        * that looks like when they do. There is one copy now.
        *
-       * @param {number|null} rowLimit Maximum rows of interest, or null for all of them.
+       * @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}} The record geometry.
+       *   indexBuffer: Buffer}} The record geometry. `indexBuffer` starts at the window's first
+       *   record, so the decoder always counts from zero.
        * @private
        */
-      _planIndexTable(rowLimit, stage) {
-        if (!this._buffer || !this._header || !this._indexTableOffset) {
+      _planIndexTable(window, stage) {
+        if (!this._buffer || !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.",
             {
               file: this._path,
               stage
             }
-          );
-        }
-        let fields = this._header["QvdTableHeader"]["Fields"]["QvdFieldHeader"];
-        if (!Array.isArray(fields)) {
-          fields = [fields];
+          );
         }
+        const allFields = this._allFields;
+        const fields = this._selectedFields;
         const recordSize = parseInt(this._header["QvdTableHeader"]["RecordByteSize"], 10);
         const totalRows = parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10);
-        const rowsToLoad = rowLimit !== null ? Math.min(rowLimit, totalRows) : totalRows;
         const indexTableLength = parseInt(this._header["QvdTableHeader"]["Length"], 10);
+        const { offset: firstRow, limit: rowsToLoad } = resolveWindow(window, totalRows);
         validateIndexTableMetadata(
           recordSize,
           totalRows,
@@ -2056,11 +3253,20 @@ var init_QvdFileReader = __esm({
           this._buffer.length,
           rowsToLoad,
           this._path,
-          this._fileSize
+          this._fileSize,
+          firstRow,
+          this._bufferFirstRow
+        );
+        const bufferRecordStart = (firstRow - this._bufferFirstRow) * recordSize;
+        const indexBuffer = this._buffer.subarray(
+          this._indexTableOffset + bufferRecordStart,
+          this._indexTableOffset + bufferRecordStart + rowsToLoad * recordSize
         );
-        const indexBuffer = this._buffer.subarray(this._indexTableOffset, this._indexTableOffset + indexTableLength + 1);
-        for (const field of fields) {
-          validateFieldBitMetadata(field, recordSize, this._path);
+        if (!this._fieldBitMetadataValidated) {
+          for (const field of allFields) {
+            validateFieldBitMetadata(field, recordSize, this._path);
+          }
+          this._fieldBitMetadataValidated = true;
         }
         assert2(
           rowsToLoad === 0 || recordSize === 0 || Math.floor(indexBuffer.length / recordSize) >= rowsToLoad,
@@ -2072,31 +3278,45 @@ var init_QvdFileReader = __esm({
        * Analyzes the index table to determine which symbols are actually needed.
        * This is used for two-pass symbol filtering optimization.
        *
-       * @param {number} maxRows The maximum number of rows to analyze.
-       * @return {Promise<Map<string, Set<number>>>} Map of field names to Set of needed symbol indices.
+       * Only the selected fields are analysed. An unselected field's symbols are never parsed, so
+       * there is nothing for a usage set to filter and decoding its column would be a pass over the
+       * whole window for an answer nobody reads.
+       *
+       * @param {QvdRowWindow} window The rows to analyse.
+       * @return {Promise<Array<Set<number>>>} One set of needed symbol indices per selected field, in
+       *   the same order `_parseSymbolTable` walks them.
        * @private
        */
-      async _analyzeIndexTableSymbolUsage(maxRows) {
-        const { fields, recordSize, rowsToLoad, indexBuffer } = this._planIndexTable(maxRows, "analyzeIndexTableSymbolUsage");
-        const symbolUsage = /* @__PURE__ */ new Map();
-        const column = new Int32Array(rowsToLoad);
-        fields.forEach((field) => {
+      async _analyzeIndexTableSymbolUsage(window) {
+        const { fields, recordSize, rowsToLoad, indexBuffer } = 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 needed = /* @__PURE__ */ new Set();
-          symbolUsage.set(field["FieldName"], needed);
-          decodeIndexColumn(
-            indexBuffer,
-            recordSize,
-            rowsToLoad,
-            parseInt(field["BitOffset"], 10),
-            parseInt(field["BitWidth"], 10),
-            parseInt(field["Bias"], 10),
-            column
-          );
-          for (let row = 0; row < rowsToLoad; row++) {
-            if (column[row] >= 0) {
-              needed.add(column[row]);
+          symbolUsage[position] = needed;
+          const bitOffset = parseInt(field["BitOffset"], 10);
+          const bitWidth = parseInt(field["BitWidth"], 10);
+          const bias = parseInt(field["Bias"], 10);
+          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) {
+                needed.add(column[row]);
+              }
             }
           }
+          this._emitProgress("symbol-analysis", position + 1, fields.length);
         });
         return symbolUsage;
       }
@@ -2104,12 +3324,20 @@ var init_QvdFileReader = __esm({
        * Parses the symbol table of the QVD file. This method is part of the parsing process
        * and should not be called directly.
        *
-       * @param {Map<string, Set<number>>|null} symbolsToKeep Optional map of field names to symbol indices to keep.
-       *   If provided, only these symbols will be parsed (two-pass filtering optimization).
-       * @param {number|null} maxRows Optional maximum number of rows being loaded (for memory estimation).
+       * A field the caller did not select is skipped whole. Its symbol area is neither scanned nor
+       * parsed - the per-field `Offset` and `Length` say exactly where it is, so there is nothing to
+       * walk past - and that is where field selection earns its keep. The index decode is cheap by
+       * comparison; parsing symbols is not.
+       *
+       * @param {Array<Set<number>>|null} symbolsToKeep Optional set of symbol indices to keep per
+       *   selected field, indexed by position. If provided, only these symbols will be parsed
+       *   (two-pass filtering optimization).
+       * @param {number} rowsToLoad Rows the read covers, for memory estimation.
+       * @param {{rows: number, perChunk: number}|null} [liveRows=null] Rows held at one instant when
+       *   that is fewer than the window covers - see `_prepare`.
        */
-      async _parseSymbolTable(symbolsToKeep = null, maxRows = null) {
-        if (!this._buffer || !this._header || !this._symbolTableOffset || !this._indexTableOffset) {
+      async _parseSymbolTable(symbolsToKeep = null, rowsToLoad = 0, liveRows = null) {
+        if (!this._buffer || !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.",
             {
@@ -2118,7 +3346,8 @@ var init_QvdFileReader = __esm({
             }
           );
         }
-        let fields = this._header["QvdTableHeader"]["Fields"]["QvdFieldHeader"];
+        const allFields = this._allFields;
+        const fields = this._selectedFields;
         const symbolBuffer = this._buffer.subarray(this._symbolTableOffset, this._indexTableOffset);
         const symbolTableSize = symbolBuffer.length;
         const totalRows = parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10);
@@ -2126,51 +3355,34 @@ var init_QvdFileReader = __esm({
         if (this._headerMatchesFile) {
           validateMemoryAvailability(
             symbolTableSize,
-            maxRows,
+            rowsToLoad,
             totalRows,
             this._path,
             this._memorySafetyFactor,
-            Array.isArray(fields) ? fields.length : 1,
-            this._materialisesRows
+            fields.length,
+            this._materialisesRows,
+            liveRows
           );
         }
-        warnLargeSymbolTable(
-          symbolTableSize,
-          maxRows,
-          totalRows,
-          Array.isArray(fields) ? fields.length : 1,
-          this._materialisesRows
-        );
-        if (!Array.isArray(fields)) {
-          fields = [fields];
-        }
-        for (const field of fields) {
+        warnLargeSymbolTable(symbolTableSize, rowsToLoad, totalRows, fields.length, this._materialisesRows);
+        for (const field of allFields) {
           validateFieldMetadata(field, symbolBuffer.length, this._path);
         }
-        this._symbolTable = fields.map((field) => {
+        this._symbolTable = fields.map((field, position) => {
+          this._throwIfAborted();
           const symbolsOffset = parseInt(field["Offset"], 10);
           const symbolsLength = parseInt(field["Length"], 10);
-          const fieldName = field["FieldName"];
-          const neededSymbols = symbolsToKeep ? symbolsToKeep.get(fieldName) : null;
-          const filteringEnabled = neededSymbols !== null;
-          const symbols = [];
-          let symbolIndex = 0;
-          for (let pointer = symbolsOffset; pointer < symbolsOffset + symbolsLength; pointer++) {
-            const typeByte = symbolBuffer[pointer++];
-            const shouldKeepSymbol = !filteringEnabled || !!(neededSymbols && neededSymbols.has(symbolIndex));
-            const { symbol, bytesRead } = parseSymbol(
-              typeByte,
-              symbolBuffer,
-              pointer,
-              symbolBuffer.length,
-              fieldName,
-              this._path,
-              shouldKeepSymbol
-            );
-            symbols.push(symbol);
-            pointer += bytesRead - 1;
-            symbolIndex++;
-          }
+          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
+          );
+          this._emitProgress("symbol-table", position + 1, fields.length);
           return symbols;
         });
       }
@@ -2189,13 +3401,18 @@ var init_QvdFileReader = __esm({
        * same for every row, so they are hoisted out of the loop and the inner loop does arithmetic
        * into a typed array and nothing else. Rows are assembled later, once, in `load()`.
        *
-       * @param {number|null} maxRows The maximum number of rows to parse. If null, all rows are parsed.
+       * The window is what makes chunked iteration cheap: `decodeIndexColumn` walks records by
+       * `base += recordSize`, so decoding rows k to k+n is a question of where the buffer slice starts
+       * and how many iterations run. Nothing about the decoder changed to support it.
+       *
+       * @param {QvdRowWindow} window The rows to decode.
        */
-      async _parseIndexTable(maxRows = null) {
-        const { fields, recordSize, rowsToLoad, indexBuffer } = this._planIndexTable(maxRows, "parseIndexTable");
+      async _parseIndexTable(window) {
+        const { fields, recordSize, rowsToLoad, indexBuffer } = this._planIndexTable(window, "parseIndexTable");
         this._rowsDecoded = rowsToLoad;
-        this._indexColumns = fields.map(
-          (field) => decodeIndexColumn(
+        this._indexColumns = fields.map((field, position) => {
+          this._throwIfAborted();
+          const column = decodeIndexColumn(
             indexBuffer,
             recordSize,
             rowsToLoad,
@@ -2203,8 +3420,10 @@ var init_QvdFileReader = __esm({
             parseInt(field["BitWidth"], 10),
             parseInt(field["Bias"], 10),
             new Int32Array(rowsToLoad)
-          )
-        );
+          );
+          this._emitProgress("index-table", position + 1, fields.length);
+          return column;
+        });
       }
       /**
        * Reads the file's schema and header metadata, without touching the symbol or index tables.
@@ -2221,8 +3440,11 @@ var init_QvdFileReader = __esm({
        * @return {Promise<import('./QvdDataFrame.js').QvdFileMetadata>} The file's schema and header.
        */
       async loadMetadata() {
-        await this._readData(null, true);
+        await this._readData({ offset: 0, limit: null }, true);
+        this._emitProgress("header", 0, 1);
         await this._parseHeader();
+        this._emitProgress("header", 1, 1);
+        this._throwIfAborted();
         assert2(this._header, "The QVD file header has not been parsed.");
         const header = this._header["QvdTableHeader"];
         let fields = header["Fields"]?.["QvdFieldHeader"] ?? [];
@@ -2257,137 +3479,337 @@ var init_QvdFileReader = __esm({
       /**
        * Loads the QVD file into memory and parses it.
        *
-       * @param {number|null} maxRows The maximum number of rows to load. If null, all rows are loaded.
-       *   Must be a non-negative integer when given.
-       * @throws {QvdValidationError} If maxRows is neither null nor a non-negative integer.
+       * @param {number|null|{offset?: number, limit?: number|null, maxRows?: number|null}} [window]
+       *   The rows to load. A number or null means what it always meant - the first N rows, or all of
+       *   them - and `{offset, limit}` is the same thing said more precisely, so `5` and
+       *   `{offset: 0, limit: 5}` are one read. `maxRows` is accepted as a second name for `limit`.
+       * @throws {QvdValidationError} If the window is not a non-negative integer, null, or a valid
+       *   `{offset, limit}` object.
        * @return {Promise<QvdDataFrame>} The loaded QVD file.
        */
-      async load(maxRows = null) {
-        const { columns, metadata, loadStats, resolvedByField } = await this._decode(maxRows);
+      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
+        );
+      }
+      /**
+       * Reads the file as columns, without ever materialising rows.
+       *
+       * Shares every step with `load()` up to the point where rows would be built - see `_prepare`.
+       * What it keeps instead is what the decoder already produced: one `Int32Array` of stored
+       * indices per field, and one resolved value per distinct symbol. On the 1.7M x 20 taxi
+       * fixture that is 38.6 MiB against the 352.8 MiB `data` retains, because a column costs four
+       * bytes per row rather than a boxed value per cell, and the symbols are a few thousand
+       * entries shared across every row that uses them.
+       *
+       * @param {number|null|{offset?: number, limit?: number|null, maxRows?: number|null}} [window]
+       *   The rows to decode, in the same spellings `load()` accepts.
+       * @return {Promise<import('./QvdColumnTable.js').QvdColumnTable>} The decoded columns.
+       */
+      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));
         assert2(this._indexColumns, "The QVD file index table has not been parsed.");
-        const indexColumns = this._indexColumns;
-        const fieldCount = indexColumns.length;
-        const data = new Array(this._rowsDecoded);
-        for (let row = 0; row < this._rowsDecoded; row++) {
-          const values = new Array(fieldCount);
-          for (let field = 0; field < fieldCount; field++) {
-            const symbolIndex = indexColumns[field][row];
-            values[field] = symbolIndex < 0 ? null : resolvedByField[field][symbolIndex];
-          }
-          data[row] = values;
-        }
-        loadStats.rowsLoaded = data.length;
-        return new QvdDataFrame(data, columns, metadata, loadStats);
+        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 }
+        });
       }
       /**
-       * Reads and decodes the file, stopping short of building rows.
+       * Yields the window as data frames of at most `chunkSize` rows.
        *
-       * Everything `load()` and `loadColumnar()` have in common, which is everything except the
-       * shape of the answer. Two read paths for one binary format is the drift risk #113 is the
-       * standing example of - a stored index resolved one way here and another way there returns
-       * plausible wrong values and throws nothing - so there is one path, and the two entry points
-       * differ only in what they do with what it returns.
+       * The file is opened, read and parsed **once**; only the index decode and the row building
+       * happen per chunk. That is the whole reason this exists as a method rather than as a loop of
+       * `load({offset, limit})` calls at the call site: the symbol table has to be parsed in full
+       * whatever the chunk size - a stored index in the last chunk can address the first symbol -
+       * and re-parsing it per chunk is what makes the obvious implementation cost more than a plain
+       * load rather than less. PyQvd's chunked read does re-read it, and the comment on #140 records
+       * that as a limitation rather than a design.
        *
-       * @param {number|null} maxRows Maximum rows to decode, or null for all of them.
-       * @return {Promise<{columns: Array<string>, metadata: any, loadStats: any,
-       *   resolvedByField: Array<Array<any>>}>} The decoded file.
-       * @private
+       * What it bounds is row materialisation, which is what actually dominates a large read's heap.
+       * Two chunks of rows are alive at a time, not one - `for await` keeps the yielded frame
+       * reachable while this generator builds the next - which is why `liveRows` below is
+       * `chunkSize * 2`, and why the heap it needs is twice what one chunk suggests.
+       *
+       * A window covering no rows yields nothing at all, rather than one empty frame - so
+       * `for await` over an exhausted offset does nothing, which is what a paging loop wants.
+       *
+       * @param {number|null|{offset?: number, limit?: number|null, maxRows?: number|null}} window
+       *   The rows to cover, in the same spellings `load()` accepts.
+       * @param {number} chunkSize Rows per frame. Must be a positive integer.
+       * @return {AsyncGenerator<QvdDataFrame>} The chunks, in order.
        */
-      async _decode(maxRows = null) {
-        if (maxRows !== null && (typeof maxRows !== "number" || !Number.isInteger(maxRows) || maxRows < 0)) {
-          throw new QvdValidationError("maxRows must be a non-negative integer, or null to load all rows", {
-            provided: maxRows,
-            type: typeof maxRows,
+      async *iterateRows(window, chunkSize) {
+        if (typeof chunkSize !== "number" || !Number.isInteger(chunkSize) || chunkSize <= 0) {
+          throw new QvdValidationError("chunkSize must be a positive integer", {
+            provided: chunkSize,
+            type: typeof chunkSize,
             file: this._path
           });
         }
-        await this._readData(maxRows);
+        const liveRows = { rows: chunkSize * 2, perChunk: 2 };
+        const rows = normaliseWindow(window, this._path);
+        const prepared = await this._prepare(rows, liveRows);
+        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
+          );
+        }
+      }
+      /**
+       * Reads the file and resolves its symbols, stopping short of decoding any rows.
+       *
+       * Everything `load()`, `loadColumnar()` and `iterateRows()` have in common, which is everything
+       * that depends on the file rather than on the window. Two read paths for one binary format is
+       * the drift risk #113 is the standing example of - a stored index resolved one way here and
+       * another way there returns plausible wrong values and throws nothing - so there is one path,
+       * and the entry points differ only in what they do with what it returns and how many rows they
+       * ask for at a time.
+       *
+       * @param {QvdRowWindow} window The rows the read covers.
+       * @param {{rows: number, perChunk: number}|null} [liveRows] Rows held at one instant when that
+       *   is fewer than the window covers, and how many of them one row of the caller's chunk size
+       *   accounts for. Only `iterateRows` passes it; every other read holds what it covers.
+       * @param {boolean} [wantHalves=false] Whether to keep both halves of each symbol of a field whose
+       *   cells do not show them, which only a columnar read has a use for.
+       * @return {Promise<{columns: Array<string>, metadata: any, loadStats: any,
+       *   resolvedByField: Array<Array<any>>,
+       *   halvesByField: Array<import('./util/resolveSymbols.js').SymbolHalves|null>,
+       *   storedSymbols: import('./util/storedSymbols.js').StoredSymbols|null,
+       *   rowsAvailable: number, offset: number}>} The parsed file, with the window as it resolved
+       *   against it.
+       * @private
+       */
+      async _prepare(window, liveRows = null, wantHalves = false) {
+        this._throwIfAborted();
+        await this._readData(window, false, liveRows);
+        this._emitProgress("header", 0, 1);
         await this._parseHeader();
+        this._emitProgress("header", 1, 1);
+        this._throwIfAborted();
+        assert2(this._header, "The QVD file header has not been parsed.");
+        const totalRows = parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10);
+        const symbolTableLength = parseInt(this._header["QvdTableHeader"]["Offset"], 10);
+        const resolved = resolveWindow(window, totalRows);
+        const rowsAvailable = resolved.limit;
         let symbolsToKeep = null;
         let symbolsKept = null;
-        if (maxRows !== null && this._header) {
-          const symbolTableLength = parseInt(this._header["QvdTableHeader"]["Offset"], 10);
+        if (window.limit !== null || window.offset > 0) {
           if (symbolTableLength > this._symbolFilteringThreshold) {
-            symbolsToKeep = await this._analyzeIndexTableSymbolUsage(maxRows);
-            symbolsKept = Array.from(symbolsToKeep.values()).reduce((sum, set) => sum + set.size, 0);
+            symbolsToKeep = await this._analyzeIndexTableSymbolUsage({ offset: resolved.offset, limit: rowsAvailable });
+            symbolsKept = symbolsToKeep.reduce((sum, set) => sum + set.size, 0);
           }
         }
-        await this._parseSymbolTable(symbolsToKeep, maxRows);
-        await this._parseIndexTable(maxRows);
-        assert2(this._header, "The QVD file header has not been parsed.");
+        await this._parseSymbolTable(symbolsToKeep, rowsAvailable, liveRows);
         assert2(this._symbolTable, "The QVD file symbol table has not been parsed.");
-        assert2(this._indexColumns, "The QVD file index table has not been parsed.");
-        const resolvedByField = this._symbolTable.map((symbols) => {
-          const resolved = new Array(symbols.length);
-          for (let index = 0; index < symbols.length; index++) {
-            const value = symbols[index]?.toPrimaryValue();
-            resolved[index] = typeof value === "string" && value.trim() !== "" && !isNaN(Number(value)) ? Number(value) : value;
+        this._throwIfAborted();
+        assert2(this._selectedFields, "The QVD file fields have not been resolved.");
+        const resolvedByField = [];
+        const halvesByField = [];
+        const entries = [];
+        this._symbolTable.forEach((symbols, position) => {
+          const { values, entry, halves } = resolveFieldSymbols(
+            symbols,
+            // @ts-ignore - asserted above
+            this._selectedFields[position]["FieldName"],
+            this._duals,
+            this._coerceNumericStrings,
+            wantHalves
+          );
+          resolvedByField.push(values);
+          halvesByField.push(halves);
+          if (entry !== null) {
+            entries.push(entry);
           }
-          return resolved;
         });
-        let fields = this._header["QvdTableHeader"]["Fields"]["QvdFieldHeader"];
-        if (!Array.isArray(fields)) {
-          fields = [fields];
-        }
-        const columns = fields.map((field) => field["FieldName"]);
+        const columns = this._selectedFields.map((field) => field["FieldName"]);
         const metadata = this._header["QvdTableHeader"];
+        const storedSymbols = entries.length > 0 ? trustStoredSymbols(entries) : null;
+        if (storedSymbols !== null) {
+          attachStoredSymbols(metadata, storedSymbols);
+        }
         const loadStats = {
-          symbolTableBytes: parseInt(this._header["QvdTableHeader"]["Offset"], 10),
-          totalRows: parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10),
-          rowsLoaded: this._rowsDecoded,
+          symbolTableBytes: symbolTableLength,
+          totalRows,
+          rowsLoaded: 0,
+          offset: resolved.offset,
           symbolFiltering: symbolsToKeep !== null,
           symbolsKept
         };
-        return { columns, metadata, loadStats, resolvedByField };
+        return {
+          columns,
+          metadata,
+          loadStats,
+          resolvedByField,
+          halvesByField,
+          storedSymbols,
+          rowsAvailable,
+          offset: resolved.offset
+        };
       }
       /**
-       * Reads the file as columns, without ever materialising rows.
+       * Builds rows from the columns currently decoded.
        *
-       * Shares every step with `load()` up to the point where rows would be built - see `_decode`.
-       * What it keeps instead is what the decoder already produced: one `Int32Array` of stored
-       * indices per field, and one resolved value per distinct symbol. On the 1.7M x 20 taxi
-       * fixture that is 38.6 MiB against the 352.8 MiB `data` retains, because a column costs four
-       * bytes per row rather than a boxed value per cell, and the symbols are a few thousand
-       * entries shared across every row that uses them.
+       * `data` stays eager: of the four ways this library is used - a full read, a preview already
+       * bounded by a limit, writing an array out, and reading metadata - not one is helped by
+       * materialising a row only when it is touched, and a lazy accessor would cost a proxy, a cache
+       * and mutation semantics to serve none of them. A caller who wants columns without paying for
+       * rows uses `QvdColumnTable`, which stops before this loop.
        *
-       * @param {number|null} maxRows The maximum number of rows to decode.
-       * @return {Promise<import('./QvdColumnTable.js').QvdColumnTable>} The decoded columns.
+       * @param {Array<Array<any>>} resolvedByField One resolved value per distinct symbol, per field.
+       * @param {number} progressBase Rows already delivered before this call, so that progress over a
+       *   chunked iteration counts the whole window rather than restarting at every chunk.
+       * @param {number} progressTotal Rows the whole window covers.
+       * @return {Array<Array<any>>} The rows.
+       * @private
        */
-      async loadColumnar(maxRows = null) {
-        const { columns, metadata, loadStats, resolvedByField } = await this._decode(maxRows);
-        const { QvdColumnTable: QvdColumnTable2 } = await Promise.resolve().then(() => (init_QvdColumnTable(), QvdColumnTable_exports));
+      _buildRows(resolvedByField, progressBase, progressTotal) {
         assert2(this._indexColumns, "The QVD file index table has not been parsed.");
-        return new QvdColumnTable2({
-          columns,
-          codesByField: this._indexColumns,
-          symbolsByField: resolvedByField,
-          rowCount: this._rowsDecoded,
-          metadata,
-          loadStats
-        });
+        const indexColumns = this._indexColumns;
+        const fieldCount = indexColumns.length;
+        const rowCount = this._rowsDecoded;
+        const data = new Array(rowCount);
+        const reportInterval = Math.max(1, Math.floor(progressTotal / 100));
+        for (let row = 0; row < rowCount; row++) {
+          const values = new Array(fieldCount);
+          for (let field = 0; field < fieldCount; field++) {
+            const symbolIndex = indexColumns[field][row];
+            values[field] = symbolIndex < 0 ? null : resolvedByField[field][symbolIndex];
+          }
+          data[row] = values;
+          if ((progressBase + row + 1) % reportInterval === 0 || row + 1 === rowCount) {
+            this._throwIfAborted();
+            this._emitProgress("rows", progressBase + row + 1, progressTotal);
+          }
+        }
+        return data;
       }
     };
   }
 });
 
 // src/QvdDataFrame.js
+function defaultFieldHeader(fieldName) {
+  return {
+    FieldName: fieldName,
+    BitOffset: 0,
+    BitWidth: 0,
+    Bias: 0,
+    NoOfSymbols: 0,
+    Offset: 0,
+    Length: 0,
+    Comment: "",
+    NumberFormat: {
+      Type: "UNKNOWN",
+      nDec: "0",
+      UseThou: "0",
+      Fmt: "",
+      Dec: "",
+      Thou: ""
+    },
+    Tags: {}
+  };
+}
+function defaultHeader(columns) {
+  return {
+    QvBuildNo: 50667,
+    CreatorDoc: "",
+    CreateUtcTime: "",
+    SourceCreateUtcTime: "",
+    SourceFileUtcTime: "",
+    SourceFileSize: -1,
+    StaleUtcTime: "",
+    TableName: "",
+    Fields: {
+      QvdFieldHeader: columns.map(defaultFieldHeader)
+    },
+    NoOfRecords: 0,
+    RecordByteSize: 0,
+    Offset: 0,
+    Length: 0,
+    Compression: "",
+    Comment: "",
+    EncryptionInfo: "",
+    TableTags: "",
+    ProfilingData: "",
+    Lineage: {}
+  };
+}
 var QvdDataFrame;
 var init_QvdDataFrame = __esm({
   "src/QvdDataFrame.js"() {
     init_QvdErrors();
+    init_cellRules();
+    init_readOptions();
+    init_storedSymbols();
+    __name(defaultFieldHeader, "defaultFieldHeader");
+    __name(defaultHeader, "defaultHeader");
     QvdDataFrame = class _QvdDataFrame {
+      static {
+        __name(this, "QvdDataFrame");
+      }
       /**
        * Represents the data frame stored inside a QVD file.
+       *
+       * The record is resolved once, here: the fifth argument when given, otherwise the one a read left on
+       * its header object, so `new QvdDataFrame(data, columns, df.metadata)` keeps what `df` would write.
+       * Either is narrowed to `columns`. An entry for a field the frame does not have describes no cell it
+       * holds, and would make the frame's own `toDict()` a dictionary `fromDict` refuses - which is what a
+       * header's record did for a frame built from some of a read's columns.
+       *
        * @param {Array<Array<any>>} data The data of the data frame.
        * @param {Array<string>} columns The columns of the data frame.
        * @param {QvdMetadata|null} metadata The metadata from the QVD file header (optional).
        * @param {QvdLoadStats|null} loadStats Statistics about the read (optional).
+       * @param {QvdStoredSymbols|null} storedSymbols What the frame's cells were read from, where a cell
+       *   shows only one half of its symbol (optional) - see `storedSymbols`.
+       * @throws {QvdValidationError} If the record is malformed.
        */
-      constructor(data, columns, metadata = null, loadStats = null) {
+      constructor(data, columns, metadata = null, loadStats = null, storedSymbols = null) {
         this._data = data;
         this._columns = columns;
         this._metadata = metadata;
+        this._ownsMetadata = false;
         this._loadStats = loadStats;
+        this._storedSymbols = narrowStoredSymbols(
+          normaliseStoredSymbols(
+            // @ts-ignore - a symbol-keyed property the reader defines on the header object
+            storedSymbols ?? (metadata !== null && typeof metadata === "object" ? metadata[STORED_SYMBOLS] : null)
+          ),
+          columns
+        );
       }
       /**
        * Returns the data of the data frame.
@@ -2414,15 +3836,40 @@ var init_QvdDataFrame = __esm({
       get metadata() {
         return this._metadata;
       }
+      /**
+       * What the frame's cells were read from, where a cell shows only one half of its symbol.
+       *
+       * A dual read as its number has a text the cell does not show; one read as its text has a number;
+       * a string read as a number has the text it was spelled with. The record keeps those halves, per
+       * field, keyed by the value the cell holds, so `toQvd` writes the symbols the frame was read from
+       * and `textAt` can return any cell's text. It moves with the frame through `head`, `tail`, `rows`,
+       * `select`, `toDict` and `fromDict`.
+       *
+       * Frozen plain data: `[{field, values, numbers, texts}]`, where a cell holding `values[i]` stands for
+       * the stored symbol (`numbers[i]`, `texts[i]`), a null number meaning a pure string and a null text a
+       * pure number.
+       *
+       * @return {QvdStoredSymbols|null} The record, or null when the frame has none: every cell of the read
+       *   showed its whole symbol, or the frame was built without one. A frame whose columns have no entry
+       *   in the record it was given or found - one from `select`, or one built from some of a read's
+       *   columns and its header - has an empty record rather than null, because a frame given null takes
+       *   the record its header carries, which describes every field of the read.
+       */
+      get storedSymbols() {
+        return this._storedSymbols;
+      }
       /**
        * Returns statistics about the read that produced this data frame.
        *
-       * Only a frame returned by fromQvd() carries these; fromDict(), head() and tail() produce
-       * frames that describe no particular read, and report null rather than a stale figure.
+       * Carried by every frame that came from a file - `fromQvd()`, and each chunk `iterate()` yields,
+       * which is how a chunk reports its `offset`. `fromDict()`, `head()`, `tail()`, `rows()` and
+       * `select()` describe no particular read and report null rather than a stale figure.
        *
        * The main use is confirming that a lazy load actually filtered the symbol table:
        * `symbolFiltering` says whether the two-pass path ran, and `symbolsKept` how many symbols
-       * survived it, which for a small maxRows should be a tiny fraction of the file's total.
+       * survived it. Note that a bounded read does not filter on its own - the two-pass path engages
+       * only above `symbolFilteringThreshold`, so on a file below it this reports false and every
+       * symbol was parsed however few rows were asked for.
        *
        * @return {QvdLoadStats|null} Load statistics, or null if this frame did not come from a file.
        */
@@ -2531,54 +3978,40 @@ var init_QvdDataFrame = __esm({
        * @property {string} [profilingData] - Profiling data
        * @property {Object|string} [lineage] - Lineage
        */
+      /**
+       * The header a metadata setter may change: this frame's own.
+       *
+       * A frame's header can be shared. `head`, `tail`, `rows` and `select` pass theirs on, every chunk
+       * `iterate()` yields holds the same one, and `fromDict` uses the object it is given. So the first
+       * change copies it, and a change made through one frame never reaches another. A frame with no header
+       * gets the one `toQvd` would write for it. The copy keeps the stored-symbol record the header carries,
+       * so `new QvdDataFrame(data, columns, df.metadata)` still writes what `df` would.
+       *
+       * @return {any} The header.
+       */
+      _ownMetadata() {
+        if (!this._metadata) {
+          this._metadata = defaultHeader(this._columns);
+        } else if (!this._ownsMetadata) {
+          const record = this._metadata[STORED_SYMBOLS];
+          this._metadata = structuredClone(this._metadata);
+          if (record) {
+            attachStoredSymbols(this._metadata, record);
+          }
+        }
+        this._ownsMetadata = true;
+        return this._metadata;
+      }
       /**
        * Sets modifiable file-level metadata. Immutable properties related to data storage are ignored.
+       *
+       * The change applies to this frame only, never to a frame it was derived from or shares a header
+       * with.
+       *
        * @param {FileMetadataUpdate} metadata Object containing metadata properties to update.
        */
       setFileMetadata(metadata) {
-        if (!this._metadata) {
-          this._metadata = {
-            QvBuildNo: 50667,
-            CreatorDoc: "",
-            CreateUtcTime: "",
-            SourceCreateUtcTime: "",
-            SourceFileUtcTime: "",
-            SourceFileSize: -1,
-            StaleUtcTime: "",
-            TableName: "",
-            Fields: {
-              QvdFieldHeader: this._columns.map((column) => ({
-                FieldName: column,
-                BitOffset: 0,
-                BitWidth: 0,
-                Bias: 0,
-                NoOfSymbols: 0,
-                Offset: 0,
-                Length: 0,
-                Comment: "",
-                NumberFormat: {
-                  Type: "UNKNOWN",
-                  nDec: "0",
-                  UseThou: "0",
-                  Fmt: "",
-                  Dec: "",
-                  Thou: ""
-                },
-                Tags: {}
-              }))
-            },
-            NoOfRecords: 0,
-            RecordByteSize: 0,
-            Offset: 0,
-            Length: 0,
-            Compression: "",
-            Comment: "",
-            EncryptionInfo: "",
-            TableTags: "",
-            ProfilingData: "",
-            Lineage: {}
-          };
-        }
+        const header = this._ownMetadata();
         const modifiableFields = [
           "qvBuildNo",
           "creatorDoc",
@@ -2613,7 +4046,7 @@ var init_QvdDataFrame = __esm({
         };
         modifiableFields.forEach((field) => {
           if (metadata[field] !== void 0) {
-            this._metadata[fieldMapping[field]] = metadata[field];
+            header[fieldMapping[field]] = metadata[field];
           }
         });
       }
@@ -2626,30 +4059,44 @@ var init_QvdDataFrame = __esm({
       /**
        * Sets modifiable field-level metadata for a specific field.
        * Immutable properties related to data storage (Offset, Length, BitOffset, etc.) are ignored.
+       *
+       * Works on any frame, including one with no header yet - one from `fromDict` - and on a column the
+       * header does not describe. The change applies to this frame only, never to a frame it was derived
+       * from or shares a header with.
+       *
        * @param {string} fieldName The name of the field.
        * @param {FieldMetadataUpdate} metadata Object containing field metadata properties to update.
+       * @throws {QvdValidationError} If the frame has no column of that name.
        */
       setFieldMetadata(fieldName, metadata) {
-        if (!this._metadata || !this._metadata.Fields || !this._metadata.Fields.QvdFieldHeader) {
-          return;
+        if (!this._columns.includes(fieldName)) {
+          throw new QvdValidationError(`Column '${fieldName}' does not exist`, {
+            column: fieldName,
+            availableColumns: this._columns
+          });
         }
-        let fields = this._metadata.Fields.QvdFieldHeader;
+        const header = this._ownMetadata();
+        if (!header.Fields || typeof header.Fields !== "object" || !header.Fields.QvdFieldHeader) {
+          header.Fields = { QvdFieldHeader: [] };
+        }
+        let fields = header.Fields.QvdFieldHeader;
         if (!Array.isArray(fields)) {
           fields = [fields];
-          this._metadata.Fields.QvdFieldHeader = fields;
+          header.Fields.QvdFieldHeader = fields;
         }
-        const fieldIndex = fields.findIndex((f) => f.FieldName === fieldName);
-        if (fieldIndex === -1) {
-          return;
+        let field = fields.find((f) => f.FieldName === fieldName);
+        if (!field) {
+          field = defaultFieldHeader(fieldName);
+          fields.push(field);
         }
         if (metadata.comment !== void 0) {
-          fields[fieldIndex].Comment = metadata.comment;
+          field.Comment = metadata.comment;
         }
         if (metadata.numberFormat !== void 0) {
-          fields[fieldIndex].NumberFormat = metadata.numberFormat;
+          field.NumberFormat = metadata.numberFormat;
         }
         if (metadata.tags !== void 0) {
-          fields[fieldIndex].Tags = metadata.tags;
+          field.Tags = metadata.tags;
         }
       }
       /**
@@ -2666,7 +4113,7 @@ var init_QvdDataFrame = __esm({
             type: typeof n
           });
         }
-        return new _QvdDataFrame(this._data.slice(0, n), this._columns, this._metadata);
+        return new _QvdDataFrame(this._data.slice(0, n), this._columns, this._metadata, null, this._storedSymbols);
       }
       /**
        * Returns the last n rows of the data frame.
@@ -2682,7 +4129,13 @@ var init_QvdDataFrame = __esm({
             type: typeof n
           });
         }
-        return new _QvdDataFrame(n === 0 ? [] : this._data.slice(-n), this._columns, this._metadata);
+        return new _QvdDataFrame(
+          n === 0 ? [] : this._data.slice(-n),
+          this._columns,
+          this._metadata,
+          null,
+          this._storedSymbols
+        );
       }
       /**
        * Returns the selected rows of the data frame.
@@ -2710,7 +4163,9 @@ var init_QvdDataFrame = __esm({
         return new _QvdDataFrame(
           args.map((index) => this._data[index]),
           this._columns,
-          this._metadata
+          this._metadata,
+          null,
+          this._storedSymbols
         );
       }
       /**
@@ -2722,6 +4177,50 @@ var init_QvdDataFrame = __esm({
        * @throws {QvdValidationError} If row is not an integer, out of bounds, or column does not exist.
        */
       at(row, column) {
+        const index = this._cellIndex(row, column);
+        return this._data[row][index];
+      }
+      /**
+       * Returns the text of the value at the specified row and column.
+       *
+       * The text Qlik displays for it: a string cell is its own text, and a dual cell's text is its
+       * `.text`. A number cell's text comes from the frame's `storedSymbols` - the dual it was read from,
+       * or the string it was spelled as - and is null for a number that was stored as a pure number.
+       *
+       * ```js
+       * const df = await QvdDataFrame.fromQvd('stockholm_temp.qvd');
+       * df.at(0, 'date'); // -52593
+       * df.textAt(0, 'date'); // '1756-01-01'
+       * ```
+       *
+       * @param {number} row The index of the row.
+       * @param {string} column The name of the column.
+       * @return {string|null} The text, or null for NULL and for a number with no text.
+       * @throws {QvdValidationError} If row is not an integer, out of bounds, or column does not exist.
+       */
+      textAt(row, column) {
+        const index = this._cellIndex(row, column);
+        const value = this._data[row][index];
+        if (typeof value === "string") {
+          return value;
+        }
+        if (typeof value === "number") {
+          const entry = storedSymbolsEntry(this._storedSymbols, column);
+          return entry === null ? null : storedTextOf(entry, value);
+        }
+        const dual = asDual(value);
+        return dual !== null && typeof dual.text === "string" ? dual.text : null;
+      }
+      /**
+       * Checks a row and a column name, and returns the column's position.
+       *
+       * @param {number} row The index of the row.
+       * @param {string} column The name of the column.
+       * @return {number} The column's position.
+       * @throws {QvdValidationError} If row is not an integer, out of bounds, or column does not exist.
+       * @private
+       */
+      _cellIndex(row, column) {
         if (typeof row !== "number" || !Number.isInteger(row)) {
           throw new QvdValidationError("Row index must be an integer", {
             provided: row,
@@ -2741,7 +4240,7 @@ var init_QvdDataFrame = __esm({
             availableColumns: this._columns
           });
         }
-        return this._data[row][this._columns.indexOf(column)];
+        return this._columns.indexOf(column);
       }
       /**
        * Selects the specified columns from the data frame.
@@ -2762,15 +4261,34 @@ var init_QvdDataFrame = __esm({
         const indices = args.map((arg) => this._columns.indexOf(arg));
         const data = this._data.map((row) => indices.map((index) => row[index]));
         const columns = indices.map((index) => this._columns[index]);
-        return new _QvdDataFrame(data, columns, this._metadata);
+        return new _QvdDataFrame(data, columns, this._metadata, null, this._storedSymbols);
       }
       /**
        * Returns the data frame as a dictionary.
        *
-       * @return {Promise<{columns: Array<string>, data: Array<Array<any>>}>} The data frame as a dictionary.
+       * Everything a frame needs to write the same file again, as plain data: the header, and the
+       * stored-symbol record that says what cells showing one half of a symbol were read from. So
+       * `fromDict(await df.toDict())` writes what `df` writes, and so does a dictionary that went through
+       * `JSON`, `structuredClone` or a worker on the way. The arrays are the frame's own, not copies.
+       *
+       * @return {Promise<QvdDataFrameDict>} The data frame as a dictionary.
        */
       async toDict() {
-        return { columns: this._columns, data: this._data };
+        return this.toJSON();
+      }
+      /**
+       * The same dictionary `toDict` returns, synchronously, so `JSON.stringify(df)` gives something
+       * `fromDict(JSON.parse(...))` can revive.
+       *
+       * @return {QvdDataFrameDict} The data frame as a dictionary.
+       */
+      toJSON() {
+        return {
+          columns: this._columns,
+          data: this._data,
+          metadata: this._metadata,
+          storedSymbols: this._storedSymbols
+        };
       }
       /**
        * Persists the data frame to a QVD file.
@@ -2799,6 +4317,33 @@ var init_QvdDataFrame = __esm({
        * @param {Object} [options] Optional loading options.
        * @param {number|null} [options.maxRows] The maximum number of rows to load. Must be a non-negative
        *   integer; if not specified or null, all rows are loaded. Anything else throws a QvdValidationError.
+       *   This is the older name for `limit`; the two are the same option and passing both throws.
+       * @param {number|null} [options.limit] Rows to read, counting from `offset`. The same number as
+       *   `maxRows`, spelled so that it reads correctly beside an offset.
+       * @param {number} [options.offset=0] File row to start at. An offset past the end of the file
+       *   returns no rows rather than throwing, so a paging loop terminates on its own.
+       * @param {Array<string>|null} [options.fields] Field names to read, in the order they should
+       *   appear in the result. Unselected fields have their symbols skipped entirely rather than
+       *   parsed and discarded. An unknown or repeated name throws.
+       * @param {'number'|'text'|'both'} [options.duals='number'] What a dual symbol - a number with the
+       *   text Qlik displays for it, such as a date, a timestamp or a formatted amount - reads as.
+       *   `'number'` gives its number, the value Qlik sums, sorts and compares by, so a date is its serial.
+       *   `'text'` gives its text. `'both'` gives a frozen `QvdDual` with `.number` and `.text`, whose
+       *   implicit conversions throw. Under `'number'` and `'text'` the other half is kept in
+       *   `storedSymbols`, so `toQvd` writes the dual back, and `textAt` returns any cell's text. An int, a
+       *   double, a string and NULL read the same in every mode: a number, a string and null. Anything else
+       *   throws.
+       * @param {boolean} [options.coerceNumericStrings=false] Whether a cell that would read as a string
+       *   reads as a number when its text is not blank and `Number(text)` is finite. A string symbol then
+       *   reads as `Number(text)`, so `'007'` is 7, in every `duals` mode; a dual read with
+       *   `duals: 'text'` reads as the number it stores. Blank text, and text such as `'8E5597'` whose
+       *   `Number()` is Infinity, stay strings. The text is kept in `storedSymbols`, so `toQvd` writes the
+       *   original string or dual back, and a value that two stored values read as is refused there
+       *   rather than written as either. Anything but a boolean throws.
+       * @param {Function} [options.onProgress] Called with `{stage, current, total, percent}` as the
+       *   read proceeds - the same shape `toQvd`'s callback receives.
+       * @param {AbortSignal} [options.signal] Cancels the read. The rejection is `signal.reason`,
+       *   which is a `DOMException` named `AbortError` unless you aborted with a reason of your own.
        * @param {string} [options.allowedDir] Optional allowed directory path. If provided, the file path
        *   must be within this directory, with symlinks resolved first, so a link inside it that points
        *   outside it is rejected. Defaults to the current working directory. To permit an entire
@@ -2811,17 +4356,64 @@ var init_QvdDataFrame = __esm({
        *   **Zero disables the memory check entirely.**
        * @param {number} [options.symbolFilteringThreshold=52428800] Symbol table size, in bytes, above which
        *   a lazy load switches to the two-pass filtering path. Defaults to 50MB.
-       * @throws {QvdValidationError} If options.maxRows is neither null/undefined nor a non-negative integer.
+       * @throws {QvdValidationError} If a window option is not a non-negative integer, if both
+       *   `maxRows` and `limit` are given, if `fields` names a column the file does not have, if `duals`
+       *   is not one of its modes, or if `coerceNumericStrings` is not a boolean.
        * @return {Promise<QvdDataFrame>} The data frame of the QVD file.
        */
       static async fromQvd(path3, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
-        const readerOptions = {
-          allowedDir: options.allowedDir,
-          memorySafetyFactor: options.memorySafetyFactor,
-          symbolFilteringThreshold: options.symbolFilteringThreshold
-        };
-        return await new QvdFileReader2(path3, readerOptions).load(options.maxRows !== void 0 ? options.maxRows : null);
+        return await new QvdFileReader2(path3, readerOptionsFrom(options)).load(windowFrom(options));
+      }
+      /**
+       * 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.
+       *
+       * ```js
+       * for await (const chunk of QvdDataFrame.iterate('big.qvd', {chunkSize: 50_000})) {
+       *   process(chunk.data);
+       * }
+       * ```
+       *
+       * A window covering no rows yields nothing, so a loop over an exhausted offset simply does not
+       * run its body.
+       *
+       * Every chunk carries the same `storedSymbols`, because the symbol table is parsed once for all of
+       * them, so a chunk written on its own writes the symbols its cells were read from.
+       *
+       * @param {string} path The path to the QVD file.
+       * @param {Object} [options] Reading options, with the meanings they have on `fromQvd`.
+       * @param {number} [options.chunkSize=100000] Rows per frame. Must be a positive integer.
+       * @param {number|null} [options.maxRows] Rows to cover. The older name for `limit`.
+       * @param {number|null} [options.limit] Rows to cover, counting from `offset`.
+       * @param {number} [options.offset=0] File row to start at.
+       * @param {Array<string>|null} [options.fields] Field names to read, in the order they should appear.
+       * @param {'number'|'text'|'both'} [options.duals='number'] What a dual symbol reads as: its number,
+       *   its text, or a frozen `QvdDual` holding both. Anything else throws.
+       * @param {boolean} [options.coerceNumericStrings=false] Whether a cell that would read as a string
+       *   reads as a number when its text is not blank and `Number(text)` is finite - a string symbol as
+       *   `Number(text)`, a dual read as text as its stored number - with the text kept in every chunk's
+       *   `storedSymbols`. Anything but a boolean throws.
+       * @param {Function} [options.onProgress] Called with `{stage, current, total, percent}`; progress
+       *   over the rows counts the whole window, not each chunk.
+       * @param {AbortSignal} [options.signal] Cancels the iteration, rejecting with `signal.reason`.
+       * @param {string} [options.allowedDir] Directory the path must resolve inside.
+       * @param {number} [options.memorySafetyFactor=0.8] Fraction of the memory budget the read may use,
+       *   charged for two chunks of rows rather than the window. Zero disables the check.
+       * @param {number} [options.symbolFilteringThreshold=52428800] Symbol table size above which a
+       *   windowed read switches to two-pass filtering.
+       * @return {AsyncGenerator<QvdDataFrame>} The chunks, in file order.
+       */
+      static async *iterate(path3, options = {}) {
+        const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
+        const reader = new QvdFileReader2(path3, readerOptionsFrom(options));
+        yield* reader.iterateRows(windowFrom(options), options.chunkSize === void 0 ? 1e5 : options.chunkSize);
       }
       /**
        * Reads a QVD file's schema and header metadata, without reading its data.
@@ -2845,17 +4437,28 @@ var init_QvdDataFrame = __esm({
        * @param {Object} [options] Optional reading options.
        * @param {string} [options.allowedDir] Optional allowed directory path, applied exactly as it
        *   is for `fromQvd`.
+       * @param {Function} [options.onProgress] Called with `{stage, current, total, percent}`, as on
+       *   the reads that return data. Only the `read` and `header` stages occur here; there are no
+       *   symbols to parse and no rows to build.
+       * @param {AbortSignal} [options.signal] Cancels the read, rejecting with `signal.reason`.
        * @return {Promise<QvdFileMetadata>} The file's schema and header metadata.
        */
       static async readMetadata(path3, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
-        return await new QvdFileReader2(path3, { allowedDir: options.allowedDir }).loadMetadata();
+        return await new QvdFileReader2(path3, metadataOptionsFrom(options)).loadMetadata();
       }
       /**
        * Constructs a data frame from a dictionary.
        *
-       * @param {{columns: Array<string>, data: Array<Array<any>>}} data The dictionary to construct the data frame from.
+       * Takes what `toDict` returns. `metadata` and `storedSymbols` are optional; with the record, a frame
+       * rebuilt from a read writes the symbols the read found - duals with their texts, strings with their
+       * spelling - even after a trip through `JSON`. The record is checked, so a malformed one is refused
+       * here rather than written.
+       *
+       * @param {QvdDataFrameDict} data The dictionary to construct the data frame from.
        * @return {Promise<QvdDataFrame>} The constructed data frame.
+       * @throws {QvdValidationError} If `columns` or `data` is missing, `metadata` is not a plain object,
+       *   or `storedSymbols` is malformed or names a field that is not one of the columns.
        */
       static async fromDict(data) {
         if (!data.columns) {
@@ -2868,20 +4471,290 @@ var init_QvdDataFrame = __esm({
             data
           });
         }
-        return new _QvdDataFrame(data.data, data.columns);
+        const { metadata = null, storedSymbols = null } = data;
+        if (metadata !== null && !isPlainObject(metadata)) {
+          throw new QvdValidationError(`metadata must be a plain object; got ${describeType(metadata)}`, {
+            type: typeof metadata
+          });
+        }
+        const record = normaliseStoredSymbols(storedSymbols);
+        if (record !== null) {
+          const unknown = record.find((entry) => !data.columns.includes(entry.field));
+          if (unknown !== void 0) {
+            throw new QvdValidationError(`storedSymbols names field '${unknown.field}', which is not one of the columns`, {
+              field: unknown.field,
+              availableColumns: data.columns
+            });
+          }
+        }
+        return new _QvdDataFrame(data.data, data.columns, metadata, null, record);
       }
     };
   }
 });
 
+// src/QvdSymbol.js
+init_QvdErrors();
+init_cellRules();
+init_symbolBytes();
+function checkInteger(value, context) {
+  if (typeof value === "number" && isStoredAsInt(value)) {
+    return;
+  }
+  throw new QvdValidationError(
+    `The integer of a symbol must be an integer from ${INT32_MIN} to ${INT32_MAX}; got ` + (typeof value === "number" ? String(value) : describeType(value)),
+    { ...context, half: "integer", type: typeof value }
+  );
+}
+__name(checkInteger, "checkInteger");
+var QvdSymbol = class _QvdSymbol {
+  static {
+    __name(this, "QvdSymbol");
+  }
+  /**
+   * Constructs a new QVD symbol.
+   *
+   * @param {number|null} intValue The integer value.
+   * @param {number|null} doubleValue The double value.
+   * @param {string|null} stringValue The string value.
+   */
+  constructor(intValue, doubleValue, stringValue) {
+    this._intValue = intValue;
+    this._doubleValue = doubleValue;
+    this._stringValue = stringValue;
+  }
+  /**
+   * Returns the integer value of this symbol.
+   *
+   * @return {number|null} The integer value.
+   */
+  get intValue() {
+    return this._intValue;
+  }
+  /**
+   * Returns the double value of this symbol.
+   *
+   * @return {number|null} The double value.
+   */
+  get doubleValue() {
+    return this._doubleValue;
+  }
+  /**
+   * Returns the string value of this symbol.
+   *
+   * @return {string|null} The string value.
+   */
+  get stringValue() {
+    return this._stringValue;
+  }
+  /**
+   * Retrieves the primary value of this symbol. The primary value is descriptive raw value.
+   * It is either the string value, the integer value or the double value, prioritized in this order.
+   *
+   * @return {number|string|null} The primary value.
+   */
+  toPrimaryValue() {
+    if (null != this._stringValue) {
+      return this._stringValue;
+    } else if (null != this._intValue) {
+      return this._intValue;
+    } else if (null != this._doubleValue) {
+      return this._doubleValue;
+    } else {
+      return null;
+    }
+  }
+  /**
+   * Converts the symbol to its byte representation.
+   *
+   * The kind is the one the symbol carries - an int, a double, a string, or a dual of an int or a
+   * double with its text - so a symbol built with `fromDoubleValue(4)` stays a double. Each half is
+   * checked before a byte is written, because `QvdSymbol`'s constructor checks nothing: an integer
+   * outside int32 used to surface as a bare `RangeError` from `writeInt32LE`, a symbol holding an
+   * integer and a double silently lost the double, a text with a NUL produced a symbol that ends
+   * early, and a text with an unpaired surrogate was written with U+FFFD in its place.
+   *
+   * A half left `undefined` - `new QvdSymbol()`, or `new QvdSymbol(7)` - is absent, as it is to
+   * `toPrimaryValue`. It used to be read as present: `new QvdSymbol(7)` threw a bare `TypeError` from
+   * `Buffer.from`, and `new QvdSymbol(undefined, 4.5, '4.50')` was written as a dual of the integer 0.
+   *
+   * @return {Buffer} The byte representation of the symbol.
+   * @throws {QvdValidationError} If the symbol holds both an integer and a double, holds nothing, or
+   *   holds a half no symbol can store. The message names the half.
+   */
+  toByteRepresentation() {
+    const intValue = this._intValue ?? null;
+    const doubleValue = this._doubleValue ?? null;
+    const stringValue = this._stringValue ?? null;
+    if (intValue !== null && doubleValue !== null) {
+      throw new QvdValidationError("A symbol holds an integer or a double, not both", {
+        intValue,
+        doubleValue
+      });
+    }
+    if (intValue === null && doubleValue === null && stringValue === null) {
+      throw new QvdValidationError("The symbol does not contain any value.", {
+        intValue,
+        doubleValue,
+        stringValue
+      });
+    }
+    if (intValue !== null) {
+      checkInteger(intValue, {});
+    }
+    if (doubleValue !== null) {
+      checkNumber(doubleValue, "The double of a symbol", { half: "double" });
+    }
+    if (stringValue !== null) {
+      checkText(stringValue, "The text of a symbol", { half: "text" });
+    }
+    const number = intValue ?? doubleValue;
+    const kind = number === null ? 4 : (intValue !== null ? 1 : 2) + (stringValue !== null ? 4 : 0);
+    const buffer = Buffer.allocUnsafe(symbolByteLength(kind, number, stringValue));
+    writeSymbol(buffer, 0, kind, number, stringValue);
+    return buffer;
+  }
+  /**
+   * Checks if this symbol is equal to another symbol.
+   *
+   * By shape rather than by class: another value is equal when its `intValue`, `doubleValue` and
+   * `stringValue` are, compared with `===`, whichever copy of this library built it - `instanceof`
+   * answers false for a symbol from the CommonJS build tested by the ESM one. A dual value, a `QvdDual`
+   * or `{number, text}`, is equal to a dual symbol with the same number and text: a dual carries no
+   * storage kind, so either kind matches.
+   *
+   * @param {*} value The object to compare with.
+   * @return {boolean} True if the objects are equal, false otherwise.
+   */
+  equals(value) {
+    if (value === null || typeof value !== "object") {
+      return false;
+    }
+    const intValue = this._intValue ?? null;
+    const doubleValue = this._doubleValue ?? null;
+    const stringValue = this._stringValue ?? null;
+    const dual = asDual(value);
+    if (dual !== null) {
+      return stringValue !== null && stringValue === dual.text && intValue === null !== (doubleValue === null) && (intValue ?? doubleValue) === dual.number;
+    }
+    if (!("intValue" in value && "doubleValue" in value && "stringValue" in value)) {
+      return false;
+    }
+    return intValue === (value.intValue ?? null) && doubleValue === (value.doubleValue ?? null) && stringValue === (value.stringValue ?? null);
+  }
+  /**
+   * Constructs a pure integer value symbol.
+   *
+   * @param {number} intValue The integer value.
+   * @return {QvdSymbol} The constructed value symbol.
+   * @throws {QvdValidationError} If the integer is not an integer inside the int32 range.
+   */
+  static fromIntValue(intValue) {
+    checkInteger(intValue, {});
+    return new _QvdSymbol(intValue, null, null);
+  }
+  /**
+   * Constructs a pure double value symbol.
+   *
+   * @param {number} doubleValue The double value.
+   * @return {QvdSymbol} The constructed value symbol.
+   * @throws {QvdValidationError} If the double is not a finite number.
+   */
+  static fromDoubleValue(doubleValue) {
+    checkNumber(doubleValue, "The double of a symbol", { half: "double" });
+    return new _QvdSymbol(null, doubleValue, null);
+  }
+  /**
+   * Constructs a pure string value symbol.
+   *
+   * @param {string} stringValue The string value.
+   * @return {QvdSymbol} The constructed value symbol.
+   * @throws {QvdValidationError} If the string is not a string, or holds a NUL or an unpaired surrogate.
+   */
+  static fromStringValue(stringValue) {
+    checkText(stringValue, "The text of a symbol", { half: "text" });
+    return new _QvdSymbol(null, null, stringValue);
+  }
+  /**
+   * Constructs a dual value symbol from an integer and a string value.
+   *
+   * @param {number} intValue The integer value.
+   * @param {string} stringValue The string value.
+   * @return {QvdSymbol} The constructed value symbol.
+   * @throws {QvdValidationError} If the integer is not an integer inside the int32 range, or the text
+   *   is not a string, or holds a NUL or an unpaired surrogate.
+   */
+  static fromDualIntValue(intValue, stringValue) {
+    checkInteger(intValue, {});
+    checkText(stringValue, "The text of a symbol", { half: "text" });
+    return new _QvdSymbol(intValue, null, stringValue);
+  }
+  /**
+   * Constructs a dual value symbol from a double and a string value.
+   *
+   * @param {number} doubleValue The double value.
+   * @param {string} stringValue The string value.
+   * @return {QvdSymbol} The constructed value symbol.
+   * @throws {QvdValidationError} If the double is not a finite number, or the text is not a string,
+   *   or holds a NUL or an unpaired surrogate.
+   */
+  static fromDualDoubleValue(doubleValue, stringValue) {
+    checkNumber(doubleValue, "The double of a symbol", { half: "double" });
+    checkText(stringValue, "The text of a symbol", { half: "text" });
+    return new _QvdSymbol(null, doubleValue, stringValue);
+  }
+};
+
+// src/index.js
+init_QvdDual();
+
+// src/util/qlikDate.js
+init_QvdErrors();
+init_cellRules();
+var QLIK_EPOCH_MS = Date.UTC(1899, 11, 30);
+var MS_PER_DAY = 864e5;
+var MAX_DATE_MS = 864e13;
+var MIN_SERIAL = (-MAX_DATE_MS - QLIK_EPOCH_MS) / MS_PER_DAY;
+var MAX_SERIAL = (MAX_DATE_MS - QLIK_EPOCH_MS) / MS_PER_DAY;
+function qlikSerialToDate(serial) {
+  const dual = asDual(serial);
+  const number = dual === null ? serial : dual.number;
+  if (typeof number !== "number" || !Number.isFinite(number)) {
+    throw new QvdValidationError("A Qlik date serial must be a finite number", {
+      provided: describeType(number),
+      type: typeof serial
+    });
+  }
+  const ms = Math.round(QLIK_EPOCH_MS + number * MS_PER_DAY);
+  if (!(Math.abs(ms) <= MAX_DATE_MS)) {
+    throw new QvdValidationError(`A Qlik date serial of ${number} is outside the range a JavaScript Date can hold`, {
+      serial: number,
+      minSerial: MIN_SERIAL,
+      maxSerial: MAX_SERIAL
+    });
+  }
+  return new Date(ms);
+}
+__name(qlikSerialToDate, "qlikSerialToDate");
+function dateToQlikSerial(date) {
+  const ms = types.isDate(date) ? Date.prototype.getTime.call(date) : Number.NaN;
+  if (Number.isNaN(ms)) {
+    throw new QvdValidationError("dateToQlikSerial needs a valid Date", {
+      provided: describeType(date),
+      type: typeof date
+    });
+  }
+  return (ms - QLIK_EPOCH_MS) / MS_PER_DAY;
+}
+__name(dateToQlikSerial, "dateToQlikSerial");
+
 // src/index.js
-init_QvdSymbol();
 init_QvdDataFrame();
 init_QvdColumnTable();
 init_QvdFileReader();
 init_QvdFileWriter();
 init_QvdErrors();
 
-export { QvdColumn, QvdColumnTable, QvdCorruptedError, QvdDataFrame, QvdError, QvdFileReader, QvdFileWriter, QvdIOError, QvdParseError, QvdSecurityError, QvdSymbol, QvdValidationError };
+export { QvdColumn, QvdColumnTable, QvdCorruptedError, QvdDataFrame, QvdDual, QvdError, QvdFileReader, QvdFileWriter, QvdIOError, QvdParseError, QvdSecurityError, QvdSymbol, QvdValidationError, dateToQlikSerial, qlikSerialToDate };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map