qvdjs 0.11.0 → 1.0.1

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,298 @@ 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"() {
-    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;
+// 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";
       }
-      /**
-       * Returns the integer value of this symbol.
-       *
-       * @return {number|null} The integer value.
-       */
-      get intValue() {
-        return this._intValue;
+      const keys = Object.keys(value);
+      if (keys.length === 0) {
+        return "a plain object";
       }
-      /**
-       * Returns the double value of this symbol.
-       *
-       * @return {number|null} The double value.
-       */
-      get doubleValue() {
-        return this._doubleValue;
+      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();
+    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 string value of this symbol.
+       * Constructs a dual value.
        *
-       * @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.
+       * 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|string|null} The primary 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.
        */
-      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.
-       *
-       * @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
-          });
-        }
+      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);
       }
       /**
-       * Checks if this symbol is equal to another symbol.
+       * Refuses every implicit conversion. See the class comment for why neither half is a safe answer.
        *
-       * @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.
+       * 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.
        *
-       * @param {number} intValue The integer value.
-       * @return {QvdSymbol} The constructed value symbol.
+       * @return {never}
+       * @throws {TypeError} Always.
        */
-      static fromIntValue(intValue) {
-        return new _QvdSymbol(intValue, null, null);
+      [Symbol.toPrimitive]() {
+        throw new TypeError(
+          `A QvdDual holds two values, ${this.number} and ${JSON.stringify(this.text)}; use .number or .text`
+        );
       }
       /**
-       * Constructs a pure double value symbol.
+       * Both halves, so `JSON.stringify` loses neither - and produces the shape the writer accepts back.
        *
-       * @param {number} doubleValue The double value.
-       * @return {QvdSymbol} The constructed value symbol.
+       * @return {{number: number, text: string}} The dual as a plain object.
        */
-      static fromDoubleValue(doubleValue) {
-        return new _QvdSymbol(null, doubleValue, null);
+      toJSON() {
+        return { number: this.number, text: this.text };
       }
       /**
-       * Constructs a pure string value symbol.
+       * How Node's `util.inspect` and `console.log` show a dual.
        *
-       * @param {string} stringValue The string value.
-       * @return {QvdSymbol} The constructed value symbol.
+       * @return {string} For example `QvdDual(4.5, "4.50")`.
        */
-      static fromStringValue(stringValue) {
-        return new _QvdSymbol(null, null, stringValue);
+      [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+        return `QvdDual(${this.number}, ${JSON.stringify(this.text)})`;
       }
-      /**
-       * 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);
+      /** @return {string} `'QvdDual'`, for `Object.prototype.toString`. */
+      get [Symbol.toStringTag]() {
+        return "QvdDual";
       }
       /**
-       * Constructs a dual value symbol from a double and a string value.
+       * 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.
+       *
+       * Recognition only. The halves are checked when the value is written.
        *
-       * @param {number} doubleValue The double value.
-       * @param {string} stringValue The string value.
-       * @return {QvdSymbol} The constructed value symbol.
+       * @param {any} value Any value.
+       * @return {boolean} True for a dual cell.
        */
-      static fromDualDoubleValue(doubleValue, stringValue) {
-        return new _QvdSymbol(null, doubleValue, stringValue);
+      static isDual(value) {
+        return asDual(value) !== null;
       }
     };
+    Object.defineProperty(QvdDual.prototype, DUAL_BRAND, { value: true });
+    __name(defineHalves, "defineHalves");
+    __name(dualFromSymbol, "dualFromSymbol");
   }
 });
 
@@ -347,12 +503,41 @@ function selectFields(fields, requested, 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
   };
@@ -367,9 +552,151 @@ function metadataOptionsFrom(options) {
 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
+        });
+      }
+      if (number !== null) {
+        checkNumber(number, "A stored symbol's number", context);
+      }
+      if (text !== null) {
+        checkText(text, "A stored symbol's text", context);
+      }
+      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) {
@@ -409,7 +736,7 @@ function resolveDeepestExisting(target) {
 function isWithinDirectoryOnDisk(resolvedBaseDir, resolvedPath) {
   let baseStat;
   try {
-    baseStat = fs.statSync(fs.realpathSync(resolvedBaseDir));
+    baseStat = fs.statSync(fs.realpathSync(resolvedBaseDir), { bigint: true });
   } catch {
     return null;
   }
@@ -420,7 +747,7 @@ function isWithinDirectoryOnDisk(resolvedBaseDir, resolvedPath) {
   for (; ; ) {
     let stat;
     try {
-      stat = fs.statSync(current);
+      stat = fs.statSync(current, { bigint: true });
     } catch {
       return null;
     }
@@ -474,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");
   }
 });
 
@@ -523,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");
   }
 });
 
@@ -531,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.
        *
@@ -559,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;
@@ -670,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])
                 };
               })
             },
@@ -692,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,
@@ -705,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:
        *
-       * 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
+       * | 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 |
        *
-       * 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)
+       * 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.
+       *
+       * 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.
+       *
+       * 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) {
@@ -736,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);
@@ -791,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 = [];
@@ -805,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 });
@@ -829,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++) {
@@ -836,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],
@@ -853,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.
        */
@@ -945,7 +1701,7 @@ function estimateMemoryUsage(symbolTableSize, maxRows, totalRows, columnCount =
   return keptSymbolsMemory + skippedSymbolsMemory + rowMemory;
 }
 function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, materialisesRows = true, includeExternal = false) {
-  const costOf = (rows) => estimateMemoryUsage(symbolTableSize, rows, totalRows, columnCount, materialisesRows) + (includeExternal ? estimateExternalMemory(Math.min(rows, totalRows), columnCount) : 0);
+  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;
   }
@@ -966,11 +1722,11 @@ function recommendedRowsFor(budget, symbolTableSize, totalRows, columnCount, mat
 }
 function recommendedChunkFor(budget, symbolTableSize, windowRows, totalRows, columnCount, liveRowsPerChunk = 1, includeExternal = false) {
   const covered = windowRows === null || windowRows >= totalRows ? totalRows : windowRows;
-  const fits = (chunk) => {
+  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;
   }
@@ -1060,9 +1816,9 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
     if (nothingFits) {
       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 hold fewer rows with ${knob} (recommended: ${recommendedValue.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 holding fewer rows using the ${knob} parameter (recommended: ${recommendedValue.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,
@@ -1090,6 +1846,9 @@ function validateMemoryAvailability(symbolTableSize, maxRows, totalRows, filePat
     );
   }
 }
+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) {
@@ -1104,18 +1863,30 @@ function warnLargeSymbolTable(symbolTableSize, maxRows, totalRows, columnCount =
   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 ${rowsToLoad.toLocaleString()} of ${totalRows.toLocaleString()} 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.`
+    `\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");
   }
 });
 
@@ -1352,274 +2123,247 @@ function validateFieldBitMetadata(field, recordSize, filePath) {
     throw new QvdCorruptedError("Bit field extends beyond record size", {
       field: field["FieldName"],
       bitOffset,
-      bitWidth,
-      recordSizeInBits,
-      file: filePath,
-      stage: "parseIndexTable"
-    });
-  }
-}
-var init_validationUtils = __esm({
-  "src/util/validationUtils.js"() {
-    init_QvdErrors();
-    init_memoryUtils();
-    init_bitUtils();
-  }
-});
-
-// 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", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      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", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
-      file: filePath,
-      stage: "parseSymbolTable"
-    });
-  }
-  return pointer - startPointer + 1;
-}
-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 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"
-      });
-    }
-    pointer++;
-    stringLength++;
-  }
-  if (pointer >= bufferLength) {
-    throw new QvdCorruptedError("Dual string symbol not null-terminated", {
-      field: fieldName,
-      pointer,
-      bufferSize: bufferLength,
+      bitWidth,
+      recordSizeInBits,
       file: filePath,
-      stage: "parseSymbolTable"
+      stage: "parseIndexTable"
     });
   }
-  const stringValue = symbolBuffer.subarray(stringStart, pointer).toString("utf-8");
-  return {
-    symbol: QvdSymbol.fromDualDoubleValue(doubleValue, stringValue),
-    bytesRead: pointer - (stringStart - 8) + 1
-  };
 }
-function skipDualSymbol(symbolBuffer, pointer, bufferLength, numericBytes, fieldName, filePath) {
-  if (pointer + numericBytes > bufferLength) {
-    throw new QvdCorruptedError(`Buffer overflow reading dual symbol`, {
+var init_validationUtils = __esm({
+  "src/util/validationUtils.js"() {
+    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 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 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"
-      });
-    }
-    pointer++;
-    stringLength++;
-  }
-  if (pointer >= bufferLength) {
-    throw new QvdCorruptedError("Dual 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 parseSymbol(typeByte, symbolBuffer, pointer, bufferLength, fieldName, filePath, shouldParse) {
-  switch (typeByte) {
-    case 1: {
-      if (shouldParse) {
-        return parseIntegerSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
+function overflow(message, pointer, bufferLength, fieldName, filePath) {
+  throw new QvdCorruptedError(message, {
+    field: fieldName,
+    pointer,
+    bufferSize: bufferLength,
+    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;
       }
-      return { symbol: null, bytesRead: 4 };
-    }
-    case 2: {
-      if (shouldParse) {
-        return parseDoubleSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
+      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;
       }
-      return { symbol: null, bytesRead: 8 };
-    }
-    case 4: {
-      if (shouldParse) {
-        return parseStringSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
+      case 4: {
+        const terminator = textEnd(symbolBuffer, pointer, "String symbol", fieldName, filePath);
+        if (decode) {
+          text = symbolBuffer.toString("utf8", pointer, terminator);
+        }
+        pointer = terminator + 1;
+        break;
       }
-      const bytesRead = skipStringSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
-      return { symbol: null, bytesRead };
-    }
-    case 5: {
-      if (shouldParse) {
-        return parseDualIntegerSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
+      case 5:
+      case 6: {
+        const numberBytes = typeByte === 5 ? 4 : 8;
+        if (pointer + numberBytes > bufferLength) {
+          const read = !decode ? "dual symbol" : typeByte === 5 ? "dual integer symbol" : "dual double symbol";
+          overflow(`Buffer overflow reading ${read}`, pointer, bufferLength, fieldName, filePath);
+        }
+        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;
       }
-      const bytesRead = skipDualSymbol(symbolBuffer, pointer, bufferLength, 4, fieldName, filePath);
-      return { symbol: null, bytesRead };
-    }
-    case 6: {
-      if (shouldParse) {
-        return parseDualDoubleSymbol(symbolBuffer, pointer, bufferLength, fieldName, filePath);
+      default: {
+        throw new QvdParseError("Unknown symbol type byte", {
+          typeByte: typeByte.toString(16),
+          offset: pointer - 1,
+          file: filePath,
+          stage: "parseSymbolTable"
+        });
       }
-      const bytesRead = skipDualSymbol(symbolBuffer, pointer, bufferLength, 8, fieldName, filePath);
-      return { symbol: null, bytesRead };
-    }
-    default: {
-      throw new QvdParseError("Unknown symbol type byte", {
-        typeByte: typeByte.toString(16),
-        offset: pointer - 1,
-        file: filePath,
-        stage: "parseSymbolTable"
-      });
     }
+    numbers.push(number);
+    texts.push(text);
   }
+  return { numbers, texts };
 }
+var MAX_TEXT_BYTES;
 var init_symbolParser = __esm({
   "src/util/symbolParser.js"() {
-    init_QvdSymbol();
     init_QvdErrors();
+    MAX_TEXT_BYTES = 1048576;
+    __name(textEnd, "textEnd");
+    __name(overflow, "overflow");
+    __name(parseFieldSymbols, "parseFieldSymbols");
+  }
+});
+
+// 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;
+    }
+    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);
+  }
+  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 { values, entry, halves: wantHalves && partial ? symbolHalves(symbols) : null };
+}
+function collides(symbols, values, recorded) {
+  for (let index = 0; index < values.length; index++) {
+    if (!isPure(symbols, index, values[index])) {
+      continue;
+    }
+    if (recorded.has(values[index])) {
+      return true;
+    }
+  }
+  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;
+    }
+    const recordedHere = !(mode === "both" && symbols.texts[index] !== null && symbols.numbers[index] !== null);
+    if (recordedHere) {
+      recorded.add(values[index]);
+    }
+    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)
+  });
+}
+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");
   }
 });
 
@@ -1629,21 +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. */
@@ -1670,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() {
@@ -1693,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.
        *
@@ -1736,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:
        *
@@ -1757,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;
       }
@@ -1773,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'`.
        */
@@ -1793,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,
@@ -1808,21 +2627,30 @@ 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;
       }
       /**
@@ -1841,6 +2669,13 @@ var init_QvdColumnTable = __esm({
        * @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.
@@ -1880,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.
        *
@@ -1895,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
+        );
       }
     };
   }
@@ -1906,6 +2754,16 @@ var QvdFileReader_exports = {};
 __export(QvdFileReader_exports, {
   QvdFileReader: () => 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"() {
@@ -1917,10 +2775,16 @@ var init_QvdFileReader = __esm({
     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.
        *
@@ -1947,6 +2811,18 @@ var init_QvdFileReader = __esm({
        *   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
@@ -1959,11 +2835,15 @@ var init_QvdFileReader = __esm({
           symbolFilteringThreshold = 50 * 1024 * 1024,
           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") {
@@ -2035,15 +2915,17 @@ var init_QvdFileReader = __esm({
       /**
        * 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
@@ -2114,6 +2996,8 @@ var init_QvdFileReader = __esm({
           if (!isExpectedEarlyClose) {
             throw error;
           }
+        } finally {
+          await closeReadStream(stream);
         }
         if (headerDelimiterIndex === -1) {
           throw new QvdCorruptedError(
@@ -2488,27 +3372,16 @@ var init_QvdFileReader = __esm({
           this._throwIfAborted();
           const symbolsOffset = parseInt(field["Offset"], 10);
           const symbolsLength = parseInt(field["Length"], 10);
-          const fieldName = field["FieldName"];
-          const neededSymbols = symbolsToKeep ? symbolsToKeep[position] : 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;
         });
@@ -2619,10 +3492,16 @@ var init_QvdFileReader = __esm({
         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
-        });
+        return new QvdDataFrame(
+          data,
+          prepared.columns,
+          prepared.metadata,
+          {
+            ...prepared.loadStats,
+            rowsLoaded: data.length
+          },
+          prepared.storedSymbols
+        );
       }
       /**
        * Reads the file as columns, without ever materialising rows.
@@ -2640,7 +3519,7 @@ var init_QvdFileReader = __esm({
        */
       async loadColumnar(window = null) {
         const rows = normaliseWindow(window, this._path);
-        const prepared = await this._prepare(rows);
+        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.");
@@ -2648,8 +3527,10 @@ var init_QvdFileReader = __esm({
           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 }
         });
       }
@@ -2694,11 +3575,17 @@ var init_QvdFileReader = __esm({
           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
-          });
+          yield new QvdDataFrame(
+            data,
+            prepared.columns,
+            prepared.metadata,
+            {
+              ...prepared.loadStats,
+              offset,
+              rowsLoaded: data.length
+            },
+            prepared.storedSymbols
+          );
         }
       }
       /**
@@ -2715,12 +3602,17 @@ var init_QvdFileReader = __esm({
        * @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>>, rowsAvailable: number, offset: number}>} The parsed
-       *   file, with the window as it resolved against it.
+       *   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) {
+      async _prepare(window, liveRows = null, wantHalves = false) {
         this._throwIfAborted();
         await this._readData(window, false, liveRows);
         this._emitProgress("header", 0, 1);
@@ -2743,17 +3635,31 @@ var init_QvdFileReader = __esm({
         await this._parseSymbolTable(symbolsToKeep, rowsAvailable, liveRows);
         assert2(this._symbolTable, "The QVD file symbol table has not been parsed.");
         this._throwIfAborted();
-        const resolvedByField = this._symbolTable.map((symbols) => {
-          const resolved2 = new Array(symbols.length);
-          for (let index = 0; index < symbols.length; index++) {
-            const value = symbols[index]?.toPrimaryValue();
-            resolved2[index] = typeof value === "string" && value.trim() !== "" && !isNaN(Number(value)) ? Number(value) : value;
+        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 resolved2;
         });
-        assert2(this._selectedFields, "The QVD file fields have not been resolved.");
         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: symbolTableLength,
           totalRows,
@@ -2762,7 +3668,16 @@ var init_QvdFileReader = __esm({
           symbolFiltering: symbolsToKeep !== null,
           symbolsKept
         };
-        return { columns, metadata, loadStats, resolvedByField, rowsAvailable, offset: resolved.offset };
+        return {
+          columns,
+          metadata,
+          loadStats,
+          resolvedByField,
+          halvesByField,
+          storedSymbols,
+          rowsAvailable,
+          offset: resolved.offset
+        };
       }
       /**
        * Builds rows from the columns currently decoded.
@@ -2806,24 +3721,95 @@ var init_QvdFileReader = __esm({
 });
 
 // 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.
@@ -2850,6 +3836,28 @@ 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.
        *
@@ -2970,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",
@@ -3052,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];
           }
         });
       }
@@ -3065,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;
         }
       }
       /**
@@ -3105,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.
@@ -3121,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.
@@ -3149,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
         );
       }
       /**
@@ -3161,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,
@@ -3180,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.
@@ -3201,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.
@@ -3246,6 +4325,21 @@ var init_QvdDataFrame = __esm({
        * @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`,
@@ -3263,7 +4357,8 @@ var init_QvdDataFrame = __esm({
        * @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 a window option is not a non-negative integer, if both
-       *   `maxRows` and `limit` are given, or if `fields` names a column the file does not have.
+       *   `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 = {}) {
@@ -3289,9 +4384,30 @@ var init_QvdDataFrame = __esm({
        * 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] The same options `fromQvd` takes, plus:
+       * @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 = {}) {
@@ -3334,8 +4450,15 @@ var init_QvdDataFrame = __esm({
       /**
        * 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) {
@@ -3348,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