qvdjs 1.0.1 → 2.0.1

package/dist/index.js

@@ -1,8 +1,9 @@
-import fs from 'fs';
-import path from 'path';
-import crypto from 'crypto';
+import fs2 from 'fs';
+import path2 from 'path';
+import assert3 from 'assert';
+import crypto2 from 'crypto';
+import { setTimeout } from 'timers/promises';
 import xml2 from 'xml2js';
-import assert2 from 'assert';
 import os from 'os';
 import v8 from 'v8';
 import { types } from 'util';
@@ -33,9 +34,11 @@ var init_QvdErrors = __esm({
        * @param {string} message The error message.
        * @param {string} code The error code.
        * @param {Object} [context={}] Additional context about the error.
+       * @param {{cause?: unknown}} [options] Passed on to `Error`, so a `cause` becomes `error.cause`: the
+       *   error this one reports, such as the operating system's refusal behind a `QvdIOError`.
        */
-      constructor(message, code, context = {}) {
-        super(message);
+      constructor(message, code, context = {}, options = void 0) {
+        super(message, options);
         this.name = ERROR_NAMES.get(new.target) ?? new.target.name;
         this.code = code;
         this.context = context;
@@ -51,9 +54,10 @@ var init_QvdErrors = __esm({
        *
        * @param {string} message The error message.
        * @param {Object} [context={}] Additional context about the error.
+       * @param {{cause?: unknown}} [options] Passed on to `Error`; a `cause` becomes `error.cause`.
        */
-      constructor(message, context = {}) {
-        super(message, "QVD_PARSE_ERROR", context);
+      constructor(message, context = {}, options = void 0) {
+        super(message, "QVD_PARSE_ERROR", context, options);
       }
     };
     QvdValidationError = class extends QvdError {
@@ -65,9 +69,10 @@ var init_QvdErrors = __esm({
        *
        * @param {string} message The error message.
        * @param {Object} [context={}] Additional context about the error.
+       * @param {{cause?: unknown}} [options] Passed on to `Error`; a `cause` becomes `error.cause`.
        */
-      constructor(message, context = {}) {
-        super(message, "QVD_VALIDATION_ERROR", context);
+      constructor(message, context = {}, options = void 0) {
+        super(message, "QVD_VALIDATION_ERROR", context, options);
       }
     };
     QvdIOError = class extends QvdError {
@@ -79,9 +84,10 @@ var init_QvdErrors = __esm({
        *
        * @param {string} message The error message.
        * @param {Object} [context={}] Additional context about the error.
+       * @param {{cause?: unknown}} [options] Passed on to `Error`; a `cause` becomes `error.cause`.
        */
-      constructor(message, context = {}) {
-        super(message, "QVD_IO_ERROR", context);
+      constructor(message, context = {}, options = void 0) {
+        super(message, "QVD_IO_ERROR", context, options);
       }
     };
     QvdCorruptedError = class extends QvdError {
@@ -93,9 +99,10 @@ var init_QvdErrors = __esm({
        *
        * @param {string} message The error message.
        * @param {Object} [context={}] Additional context about the error.
+       * @param {{cause?: unknown}} [options] Passed on to `Error`; a `cause` becomes `error.cause`.
        */
-      constructor(message, context = {}) {
-        super(message, "QVD_CORRUPTED_ERROR", context);
+      constructor(message, context = {}, options = void 0) {
+        super(message, "QVD_CORRUPTED_ERROR", context, options);
       }
     };
     QvdSecurityError = class extends QvdError {
@@ -107,9 +114,10 @@ var init_QvdErrors = __esm({
        *
        * @param {string} message The error message.
        * @param {Object} [context={}] Additional context about the error.
+       * @param {{cause?: unknown}} [options] Passed on to `Error`; a `cause` becomes `error.cause`.
        */
-      constructor(message, context = {}) {
-        super(message, "QVD_SECURITY_ERROR", context);
+      constructor(message, context = {}, options = void 0) {
+        super(message, "QVD_SECURITY_ERROR", context, options);
       }
     };
     ERROR_NAMES.set(QvdError, "QvdError");
@@ -407,6 +415,28 @@ var init_QvdDual = __esm({
   }
 });
 
+// src/util/optionTypes.js
+function booleanOption(value, { option, file, whenUnset }) {
+  if (value === void 0 || value === null) {
+    return whenUnset;
+  }
+  if (typeof value !== "boolean") {
+    throw new QvdValidationError(`${option} must be true or false`, {
+      option,
+      provided: value,
+      type: typeof value,
+      file
+    });
+  }
+  return value;
+}
+var init_optionTypes = __esm({
+  "src/util/optionTypes.js"() {
+    init_QvdErrors();
+    __name(booleanOption, "booleanOption");
+  }
+});
+
 // src/util/readOptions.js
 function requireRowCount(value, name, filePath) {
   if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
@@ -517,18 +547,7 @@ function normaliseDuals(value, 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;
+  return booleanOption(value, { option: "coerceNumericStrings", file: filePath, whenUnset: false });
 }
 function readerOptionsFrom(options) {
   return {
@@ -556,6 +575,7 @@ var DUAL_MODES;
 var init_readOptions = __esm({
   "src/util/readOptions.js"() {
     init_QvdErrors();
+    init_optionTypes();
     __name(requireRowCount, "requireRowCount");
     __name(normaliseWindow, "normaliseWindow");
     __name(resolveWindow, "resolveWindow");
@@ -699,24 +719,64 @@ var init_storedSymbols = __esm({
     __name(sameValueZero, "sameValueZero");
   }
 });
+function readDanglingLink(target) {
+  let link;
+  try {
+    link = fs2.lstatSync(target);
+  } catch {
+    return NOT_A_LINK;
+  }
+  if (!link.isSymbolicLink()) {
+    return NOT_A_LINK;
+  }
+  let destination;
+  try {
+    destination = fs2.readlinkSync(target);
+  } catch {
+    return UNREADABLE_LINK;
+  }
+  if (path2.isAbsolute(destination)) {
+    return destination;
+  }
+  try {
+    return path2.resolve(fs2.realpathSync(path2.dirname(target)), destination);
+  } catch {
+    return UNREADABLE_LINK;
+  }
+}
+var MAX_LINK_HOPS, NOT_A_LINK, UNREADABLE_LINK;
+var init_linkTarget = __esm({
+  "src/util/linkTarget.js"() {
+    MAX_LINK_HOPS = 40;
+    NOT_A_LINK = /* @__PURE__ */ Symbol("not a link");
+    UNREADABLE_LINK = /* @__PURE__ */ Symbol("unreadable link");
+    __name(readDanglingLink, "readDanglingLink");
+  }
+});
 function isWithinDirectoryLexically(resolvedBaseDir, resolvedPath) {
   const isCaseInsensitiveFS = process.platform === "win32";
   const base = isCaseInsensitiveFS ? resolvedBaseDir.toLowerCase() : resolvedBaseDir;
   const target = isCaseInsensitiveFS ? resolvedPath.toLowerCase() : resolvedPath;
-  const relative = path.relative(base, target);
+  const relative = path2.relative(base, target);
   if (relative === "") {
     return true;
   }
-  if (path.isAbsolute(relative)) {
+  if (path2.isAbsolute(relative)) {
     return false;
   }
-  return relative !== ".." && !relative.startsWith(`..${path.sep}`);
+  return relative !== ".." && !relative.startsWith(`..${path2.sep}`);
 }
 function resolveDeepestExisting(target) {
   let current = target;
+  let farEnd = target;
+  let walkedUp = false;
+  let followedWhileClimbing = false;
+  let hops = 0;
   for (; ; ) {
     try {
-      return fs.realpathSync(current);
+      const deepest = fs2.realpathSync(current);
+      const canonicalFarEnd = walkedUp && !followedWhileClimbing ? path2.join(deepest, path2.relative(current, farEnd)) : farEnd;
+      return { deepest, exists: !walkedUp, farEnd: canonicalFarEnd };
     } catch (error) {
       const code = (
         /** @type {{code?: string}} */
@@ -725,10 +785,27 @@ function resolveDeepestExisting(target) {
       if (code !== "ENOENT" && code !== "ENOTDIR") {
         return null;
       }
-      const parent = path.dirname(current);
+      const followed = readDanglingLink(current);
+      if (followed === UNREADABLE_LINK) {
+        return REFUSED;
+      }
+      if (followed !== NOT_A_LINK) {
+        if (++hops > MAX_LINK_HOPS) {
+          return REFUSED;
+        }
+        current = followed;
+        if (walkedUp) {
+          followedWhileClimbing = true;
+        } else {
+          farEnd = followed;
+        }
+        continue;
+      }
+      const parent = path2.dirname(current);
       if (parent === current) {
         return null;
       }
+      walkedUp = true;
       current = parent;
     }
   }
@@ -736,32 +813,42 @@ function resolveDeepestExisting(target) {
 function isWithinDirectoryOnDisk(resolvedBaseDir, resolvedPath) {
   let baseStat;
   try {
-    baseStat = fs.statSync(fs.realpathSync(resolvedBaseDir), { bigint: true });
+    baseStat = fs2.statSync(fs2.realpathSync(resolvedBaseDir), { bigint: true });
   } catch {
     return null;
   }
-  let current = resolveDeepestExisting(resolvedPath);
-  if (current === null) {
+  const found = resolveDeepestExisting(resolvedPath);
+  if (found === REFUSED) {
+    return { contained: false, target: resolvedPath, stats: null };
+  }
+  if (found === null) {
     return null;
   }
-  for (; ; ) {
+  const target = found.exists ? found.deepest : found.farEnd;
+  let stats = null;
+  let current = found.deepest;
+  for (let first = true; ; first = false) {
+    const ownIdentity = first && found.exists;
     let stat;
     try {
-      stat = fs.statSync(current, { bigint: true });
+      stat = ownIdentity ? fs2.lstatSync(current, { bigint: true }) : fs2.statSync(current, { bigint: true });
     } catch {
       return null;
     }
+    if (ownIdentity) {
+      stats = stat;
+    }
     if (stat.dev === baseStat.dev && stat.ino === baseStat.ino) {
-      return true;
+      return { contained: true, target, stats };
     }
-    const parent = path.dirname(current);
+    const parent = path2.dirname(current);
     if (parent === current) {
-      return false;
+      return { contained: false, target, stats };
     }
     current = parent;
   }
 }
-function validatePath(filePath, allowedDir) {
+function checkPath(filePath, allowedDir) {
   if (typeof filePath !== "string" || filePath.length === 0) {
     throw new QvdValidationError("filePath must be a non-empty string", {
       provided: filePath,
@@ -780,11 +867,11 @@ function validatePath(filePath, allowedDir) {
       reason: "null_byte"
     });
   }
-  const resolvedPath = path.resolve(filePath);
+  const resolvedPath = path2.resolve(filePath);
   const baseDir = allowedDir || process.cwd();
-  const resolvedBaseDir = path.resolve(baseDir);
+  const resolvedBaseDir = path2.resolve(baseDir);
   const onDisk = isWithinDirectoryOnDisk(resolvedBaseDir, resolvedPath);
-  const contained = onDisk === null ? isWithinDirectoryLexically(resolvedBaseDir, resolvedPath) : onDisk;
+  const contained = onDisk === null ? isWithinDirectoryLexically(resolvedBaseDir, resolvedPath) : onDisk.contained;
   if (!contained) {
     throw new QvdSecurityError("Path traversal detected: Access denied", {
       path: filePath,
@@ -796,15 +883,197 @@ function validatePath(filePath, allowedDir) {
       check: onDisk === null ? "lexical" : "filesystem"
     });
   }
-  return resolvedPath;
+  if (onDisk === null) {
+    return { path: resolvedPath, base: resolvedBaseDir, target: resolvedPath, stats: null, onDisk: false };
+  }
+  return { path: resolvedPath, base: resolvedBaseDir, target: onDisk.target, stats: onDisk.stats, onDisk: true };
 }
+var REFUSED;
 var init_validatePath = __esm({
   "src/util/validatePath.js"() {
     init_QvdErrors();
+    init_linkTarget();
     __name(isWithinDirectoryLexically, "isWithinDirectoryLexically");
+    REFUSED = /* @__PURE__ */ Symbol("refused");
     __name(resolveDeepestExisting, "resolveDeepestExisting");
     __name(isWithinDirectoryOnDisk, "isWithinDirectoryOnDisk");
-    __name(validatePath, "validatePath");
+    __name(checkPath, "checkPath");
+  }
+});
+
+// src/util/ioErrors.js
+function isSystemError(error) {
+  const candidate = (
+    /** @type {{code?: unknown, syscall?: unknown}|null} */
+    error
+  );
+  return candidate !== null && typeof candidate === "object" && typeof candidate.syscall === "string" && typeof candidate.code === "string";
+}
+function asIoError(error, file, direction) {
+  if (!isSystemError(error)) {
+    return error;
+  }
+  const { message, syscall, code } = (
+    /** @type {{message: string, syscall: string, code: string}} */
+    error
+  );
+  return new QvdIOError(
+    `Could not ${direction} the QVD file: ${message}`,
+    { file, operation: syscall, code },
+    { cause: error }
+  );
+}
+function rethrowAsIoError(file, direction) {
+  return (error) => {
+    throw asIoError(error, file, direction);
+  };
+}
+async function closeAfter(handle, failed, use) {
+  let result;
+  try {
+    result = await use();
+  } catch (error) {
+    await handle.close().catch(() => {
+    });
+    throw error;
+  }
+  await handle.close().catch(failed);
+  return result;
+}
+var init_ioErrors = __esm({
+  "src/util/ioErrors.js"() {
+    init_QvdErrors();
+    __name(isSystemError, "isSystemError");
+    __name(asIoError, "asIoError");
+    __name(rethrowAsIoError, "rethrowAsIoError");
+    __name(closeAfter, "closeAfter");
+  }
+});
+function changedAfterCheck(checked, change) {
+  return new QvdSecurityError(`Path traversal detected: ${DESCRIPTIONS[change]}`, {
+    path: checked.path,
+    resolvedPath: checked.target,
+    allowedDir: checked.base,
+    reason: "changed_after_check",
+    change
+  });
+}
+async function openChecked(checked, purpose, failed, { nofollow = NOFOLLOW } = {}) {
+  assert3(purpose === "read" || checked.stats !== null, "A rewrite in place is of a file that exists.");
+  const noFollow = checked.onDisk ? nofollow : 0;
+  const flags = (purpose === "rewrite" ? O_WRONLY : O_RDONLY) | noFollow;
+  let handle;
+  try {
+    handle = await fs2.promises.open(checked.target, flags);
+  } catch (error) {
+    const { code } = (
+      /** @type {{code?: string}} */
+      error ?? {}
+    );
+    if (checked.onDisk && noFollow !== 0 && code !== void 0 && BECAME_A_LINK.has(code)) {
+      throw changedAfterCheck(checked, "became_a_symlink");
+    }
+    return failed(error);
+  }
+  const stats = checked.stats;
+  if (stats === null) {
+    if (checked.onDisk) {
+      await handle.close().catch(() => {
+      });
+      throw changedAfterCheck(checked, "appeared");
+    }
+    return handle;
+  }
+  try {
+    const opened = await handle.stat({ bigint: true }).catch(failed);
+    if (opened.dev !== stats.dev || opened.ino !== stats.ino) {
+      throw changedAfterCheck(checked, "replaced");
+    }
+    if (purpose === "rewrite" && stats.isFile()) {
+      await handle.truncate(0).catch(failed);
+    }
+  } catch (error) {
+    await handle.close().catch(() => {
+    });
+    throw error;
+  }
+  return handle;
+}
+var NOFOLLOW, O_RDONLY, O_WRONLY, BECAME_A_LINK, DESCRIPTIONS;
+var init_openChecked = __esm({
+  "src/util/openChecked.js"() {
+    init_QvdErrors();
+    NOFOLLOW = fs2.constants.O_NOFOLLOW ?? 0;
+    ({ O_RDONLY, O_WRONLY } = fs2.constants);
+    BECAME_A_LINK = /* @__PURE__ */ new Set(["ELOOP", "EMLINK"]);
+    DESCRIPTIONS = {
+      became_a_symlink: "the file became a symbolic link after it was checked",
+      replaced: "the file was replaced by a different one after it was checked",
+      appeared: "a file appeared at the path after it was checked"
+    };
+    __name(changedAfterCheck, "changedAfterCheck");
+    __name(openChecked, "openChecked");
+  }
+});
+function firstBytesOf(name, budget) {
+  if (Buffer.byteLength(name) <= budget) {
+    return name;
+  }
+  let kept = "";
+  let bytes = 0;
+  for (const character of name) {
+    const size = Buffer.byteLength(character);
+    if (bytes + size > budget) {
+      break;
+    }
+    kept += character;
+    bytes += size;
+  }
+  return kept;
+}
+function temporaryPathFor(target) {
+  const marks = `.qvdjs-${crypto2.randomBytes(8).toString("hex")}.tmp`;
+  const name = `${firstBytesOf(path2.basename(target), MAX_NAME_BYTES - marks.length)}${marks}`;
+  return path2.join(path2.dirname(target), name);
+}
+async function retrying(call, { platform = process.platform, delays = RETRY_DELAYS } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await call();
+    } catch (error) {
+      const { code } = (
+        /** @type {{code?: string}} */
+        error ?? {}
+      );
+      if (platform !== "win32" || attempt >= delays.length || code === void 0 || !IN_USE.has(code)) {
+        throw error;
+      }
+      await setTimeout(delays[attempt]);
+    }
+  }
+}
+function renameOver(from, to, options) {
+  return retrying(() => fs2.promises.rename(from, to), options);
+}
+async function removeTemporary(file, options) {
+  try {
+    await retrying(() => fs2.promises.rm(file, { force: true }), options);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var MAX_NAME_BYTES, IN_USE, RETRY_DELAYS;
+var init_replaceFile = __esm({
+  "src/util/replaceFile.js"() {
+    MAX_NAME_BYTES = 255;
+    __name(firstBytesOf, "firstBytesOf");
+    __name(temporaryPathFor, "temporaryPathFor");
+    IN_USE = /* @__PURE__ */ new Set(["EPERM", "EACCES", "EBUSY"]);
+    RETRY_DELAYS = [10, 20, 40, 80, 160, 320];
+    __name(retrying, "retrying");
+    __name(renameOver, "renameOver");
+    __name(removeTemporary, "removeTemporary");
   }
 });
 
@@ -817,8 +1086,12 @@ function fieldGeometry(bitOffset, bitWidth) {
     byteCount: bitWidth === 0 ? 0 : shift + bitWidth + 7 >>> 3
   };
 }
-function decodeIndexColumn(buffer, recordSize, rowCount, bitOffset, bitWidth, bias, out) {
+function decodeIndexColumn(buffer, recordSize, rowCount, bitOffset, bitWidth, bias, out, bounds = null) {
+  const symbolCount = bounds === null ? Infinity : bounds.symbolCount;
   if (bitWidth === 0) {
+    if (bounds !== null && rowCount > 0 && bias >= symbolCount) {
+      refuse2(bounds, 0, bias, bias);
+    }
     out.fill(bias, 0, rowCount);
     return out;
   }
@@ -832,10 +1105,25 @@ function decodeIndexColumn(buffer, recordSize, rowCount, bitOffset, bitWidth, bi
     if (byteCount > 2) acc += buffer[base + 2] * 65536;
     if (byteCount > 3) acc += buffer[base + 3] * 16777216;
     if (byteCount > 4) acc += buffer[base + 4] * 4294967296;
-    out[row] = Math.floor(acc / divisor) % modulus + bias;
+    const index = Math.floor(acc / divisor) % modulus + bias;
+    if ((index >= symbolCount || index < 0 && index !== bias) && bounds !== null) {
+      refuse2(bounds, row, index, bias);
+    }
+    out[row] = index;
   }
   return out;
 }
+function refuse2(bounds, row, index, bias) {
+  throw new QvdCorruptedError("Symbol index out of range", {
+    field: bounds.field,
+    row: bounds.firstRow + row,
+    symbolIndex: index,
+    symbolCount: bounds.symbolCount,
+    bias,
+    file: bounds.file,
+    stage: "parseIndexTable"
+  });
+}
 function writeBitField(buffer, recordBase, geometry, value) {
   const { byteStart, shift, byteCount } = geometry;
   if (byteCount === 0) {
@@ -852,10 +1140,12 @@ function writeBitField(buffer, recordBase, geometry, value) {
 var MAX_BIT_WIDTH, POW2;
 var init_bitUtils = __esm({
   "src/util/bitUtils.js"() {
+    init_QvdErrors();
     MAX_BIT_WIDTH = 31;
     POW2 = Array.from({ length: 41 }, (_, exponent) => 2 ** exponent);
     __name(fieldGeometry, "fieldGeometry");
     __name(decodeIndexColumn, "decodeIndexColumn");
+    __name(refuse2, "refuse");
     __name(writeBitField, "writeBitField");
   }
 });
@@ -1134,11 +1424,15 @@ function resetContradictedNumberFormat(numberFormat, facts) {
   }
   return numberFormat;
 }
-var OBJECT_MEMO_BASE, NUMERIC_TAGS, TEXT_TAGS, WHOLE_NUMBER_TAGS, NUMERIC_FORMATS, UNKNOWN_NUMBER_FORMAT, QvdFileWriter;
+var OBJECT_MEMO_BASE, NUMERIC_TAGS, TEXT_TAGS, WHOLE_NUMBER_TAGS, NUMERIC_FORMATS, UNKNOWN_NUMBER_FORMAT, WRITE_CHUNK_SIZE, QvdFileWriter;
 var init_QvdFileWriter = __esm({
   "src/QvdFileWriter.js"() {
     init_QvdErrors();
     init_validatePath();
+    init_ioErrors();
+    init_openChecked();
+    init_replaceFile();
+    init_optionTypes();
     init_bitUtils();
     init_cellRules();
     init_symbolBytes();
@@ -1165,6 +1459,7 @@ var init_QvdFileWriter = __esm({
     UNKNOWN_NUMBER_FORMAT = Object.freeze({ Type: "UNKNOWN", nDec: "0", UseThou: "0", Fmt: "", Dec: "", Thou: "" });
     __name(pruneContradictedTags, "pruneContradictedTags");
     __name(resetContradictedNumberFormat, "resetContradictedNumberFormat");
+    WRITE_CHUNK_SIZE = 512 * 1024 * 1024;
     QvdFileWriter = class {
       static {
         __name(this, "QvdFileWriter");
@@ -1181,10 +1476,30 @@ var init_QvdFileWriter = __esm({
        *   an entire volume, pass its root explicitly ('/' on POSIX, 'C:\\' on Windows); a null or
        *   empty value falls back to the working directory rather than removing the restriction.
        * @param {Function} [options.onProgress] Optional progress callback function.
+       * @param {boolean} [options.atomic=true] Whether to replace the destination rather than rewrite it:
+       *   the file is built beside it under a temporary name and renamed over it, so a failure leaves the
+       *   previous file exactly as it was and nothing ever reads a part-written one. False rewrites the
+       *   destination in place, which is what every version before 2.0.0 did: that keeps the file's
+       *   identity - hard links, its owner, permissions set on the file itself - needs no room for two
+       *   copies at once and no permission to create files in the directory, and destroys the previous
+       *   file the moment the write begins. A file that does not exist yet is renamed into place either
+       *   way, since there is nothing to rewrite - see `_destination`.
+       * @param {boolean} [options.fsync=true] Whether to wait for the file's contents to reach the disk
+       *   before the write is finished. It is what carries an atomic write's promise through a power
+       *   loss - the contents are on the disk before anything is renamed, so a crash leaves the previous
+       *   file or the new one and never a damaged one - and it is the only thing that reports a failing
+       *   disk's deferred error rather than losing it. The rename itself is not flushed, so a crash just
+       *   after the call can still lose the replacement, or a file that did not exist before. False
+       *   resolves as soon as the operating system has accepted the bytes, which is faster and is what
+       *   every version before 2.0.0 did.
        */
       constructor(filePath, df, options = {}) {
-        const { allowedDir, onProgress } = options;
-        this._path = validatePath(filePath, allowedDir);
+        const { allowedDir, onProgress, atomic, fsync } = options;
+        const checked = checkPath(filePath, allowedDir);
+        this._path = checked.path;
+        this._allowedDir = checked.base;
+        this._atomic = booleanOption(atomic, { option: "atomic", file: this._path, whenUnset: true });
+        this._fsync = booleanOption(fsync, { option: "fsync", file: this._path, whenUnset: true });
         this._df = df;
         this._onProgress = onProgress;
         this._header = null;
@@ -1220,22 +1535,168 @@ var init_QvdFileWriter = __esm({
        * Writes the data to the QVD file.
        */
       async _writeData() {
-        assert2(this._header, "The QVD file header has not been parsed.");
-        assert2(this._symbolBuffer, "The QVD file symbol table has not been parsed.");
-        assert2(this._indexBuffer, "The QVD file index table has not been parsed.");
+        assert3(this._header, "The QVD file header has not been parsed.");
+        assert3(this._symbolBuffer, "The QVD file symbol table has not been parsed.");
+        assert3(this._indexBuffer, "The QVD file index table has not been parsed.");
         this._emitProgress("write", 0, 1);
         const headerBuffer = Buffer.concat([Buffer.from(this._header, "utf-8"), Buffer.from([0])]);
-        let fd;
+        const failed = rethrowAsIoError(this._path, "write");
+        const destination = this._destination();
+        if (destination.replace) {
+          await this._replaceFile(destination, headerBuffer, failed);
+        } else {
+          await this._writeInPlace(destination, headerBuffer, failed);
+        }
+        this._emitProgress("write", 1, 1);
+      }
+      /**
+       * What is at the destination, and therefore how it is to be written.
+       *
+       * Decided by one containment check, made now - immediately before anything is opened - and by
+       * nothing else: the file that check approved is the file written, in either mode, and what the
+       * check found there is what decides how.
+       *
+       * It used to stat and resolve the path again for itself, after the check. That second resolution
+       * was #247 in the atomic write: a destination swapped for a symlink after the check was followed by
+       * it, so the temporary file was built beside a file outside allowedDir and renamed over it. A check
+       * reports where it went, so nothing here has to go there again.
+       *
+       * @return {{checked: import('./util/validatePath.js').CheckedPath, path: string,
+       *   existing: import('fs').BigIntStats|null, replace: boolean, sync: boolean}} The check, the file it
+       *   approved, what was there, whether to replace it rather than rewrite it, and whether to flush it.
+       * @private
+       */
+      _destination() {
+        const checked = checkPath(this._path, this._allowedDir);
+        const existing = checked.stats;
+        const special = existing !== null && !existing.isFile();
+        const replace = (this._atomic || existing === null) && !special;
+        return {
+          checked,
+          path: checked.target,
+          existing,
+          replace,
+          sync: this._fsync && !special
+        };
+      }
+      /**
+       * Rewrites the destination where it stands - the way every version before 2.0.0 wrote.
+       *
+       * The file is emptied as the write begins, so from there until the last byte is written there is no
+       * previous version left: a failure part-way through leaves a stub that no read of its rows survives,
+       * and anything reading the path meanwhile sees however much of the new file has arrived.
+       *
+       * It is emptied by `openChecked` rather than by opening with `'w'`, and later than `'w'` would: once
+       * the descriptor is known to be the file the check approved. `'w'` empties whatever the open reaches,
+       * which is what let #247 truncate a file outside allowedDir through a symlink swapped in after the
+       * check. The file that results is the same.
+       *
+       * @param {{checked: import('./util/validatePath.js').CheckedPath, sync: boolean}} destination Where
+       *   to write, from `_destination`.
+       * @param {Buffer} headerBuffer The header and its terminator.
+       * @param {(error: unknown) => never} failed The write's `rethrowAsIoError` handler.
+       * @private
+       */
+      async _writeInPlace(destination, headerBuffer, failed) {
+        const fd = await openChecked(destination.checked, "rewrite", failed);
+        await closeAfter(fd, failed, async () => {
+          await this._writeParts(fd, headerBuffer, failed);
+          if (destination.sync) {
+            await fd.sync().catch(failed);
+          }
+        });
+      }
+      /**
+       * Builds the file beside the destination and renames it over it.
+       *
+       * Nothing touches the destination until the rename, which either replaces it or leaves it as it was,
+       * so a write that fails at any step - a full disk, a process killed, an error from the disk itself -
+       * costs the temporary file and nothing else. A reader of the path gets the previous file or the new
+       * one, never a part of either, which is the other half of what the old behaviour could not promise.
+       *
+       * @param {{path: string, existing: import('fs').BigIntStats|null, sync: boolean}} destination Where to
+       *   write, from `_destination`.
+       * @param {Buffer} headerBuffer The header and its terminator.
+       * @param {(error: unknown) => never} failed The write's `rethrowAsIoError` handler.
+       * @private
+       */
+      async _replaceFile(destination, headerBuffer, failed) {
+        const temporary = temporaryPathFor(destination.path);
+        const mode = destination.existing === null ? void 0 : 384;
+        const fd = await fs2.promises.open(temporary, "wx", mode).catch(failed);
         try {
-          fd = await fs.promises.open(this._path, "w");
-          await fd.write(headerBuffer, 0, headerBuffer.length, 0);
-          await fd.write(this._symbolBuffer, 0, this._symbolBuffer.length, headerBuffer.length);
-          await fd.write(this._indexBuffer, 0, this._indexBuffer.length, headerBuffer.length + this._symbolBuffer.length);
-          this._emitProgress("write", 1, 1);
-        } finally {
-          if (fd) {
-            await fd.close();
+          await closeAfter(fd, failed, async () => {
+            await this._writeParts(fd, headerBuffer, failed);
+            if (destination.existing !== null && process.platform !== "win32") {
+              await fd.chmod(Number(destination.existing.mode) & 511).catch(failed);
+            }
+            if (destination.sync) {
+              await fd.sync().catch(failed);
+            }
+          });
+          await renameOver(temporary, destination.path).catch(failed);
+        } catch (error) {
+          const removed = await removeTemporary(temporary);
+          const context = (
+            /** @type {{context?: Record<string, unknown>}} */
+            error?.context
+          );
+          if (!removed && context !== null && typeof context === "object" && Object.isExtensible(context)) {
+            context.temporaryFile = temporary;
           }
+          throw error;
+        }
+      }
+      /**
+       * Writes the three parts of a QVD, in their order, into an open file.
+       *
+       * @param {import('fs/promises').FileHandle} fd The open file.
+       * @param {Buffer} headerBuffer The header and its terminator.
+       * @param {(error: unknown) => never} failed The write's `rethrowAsIoError` handler.
+       * @private
+       */
+      async _writeParts(fd, headerBuffer, failed) {
+        await this._writeRange(fd, headerBuffer, 0, failed);
+        await this._writeRange(fd, this._symbolBuffer, headerBuffer.length, failed);
+        await this._writeRange(fd, this._indexBuffer, headerBuffer.length + this._symbolBuffer.length, failed);
+      }
+      /**
+       * Writes the whole of one buffer into the file, starting at `filePosition`.
+       *
+       * A write can resolve having written less than it was given, and that is all a disk that fills
+       * part-way through one says. libuv retries a short write(2) itself, and when the retry fails it
+       * returns the bytes that did land instead of the error - `uv__fs_write_all` in its `src/unix/fs.c`,
+       * and `fs__write` on Windows does the same - so Node resolves with a short `bytesWritten` and never
+       * rejects. Taking that for the whole write is how `toQvd()` resolved on a full disk and left a
+       * truncated file: the index table, the last of the three writes, stopped part-way, and no later call
+       * asked the disk again.
+       *
+       * So the rest is written until there is none, and it is the next call that reports the failure: the
+       * disk refuses it outright, and that rejection is a QvdIOError with the system's code, ENOSPC, like
+       * any other refused write. A write that stores nothing and reports nothing would repeat forever, so
+       * it is a failure too, the one QvdIOError with no system code to carry.
+       *
+       * In bounded chunks as well, because Node refuses a single write of 2 GiB or more.
+       *
+       * @param {import('fs/promises').FileHandle} fd The open file.
+       * @param {Buffer} buffer What to write.
+       * @param {number} filePosition Where in the file it starts.
+       * @param {(error: unknown) => never} failed The write's `rethrowAsIoError` handler, which every call
+       *   goes through.
+       * @private
+       */
+      async _writeRange(fd, buffer, filePosition, failed) {
+        let done = 0;
+        while (done < buffer.length) {
+          const length = Math.min(WRITE_CHUNK_SIZE, buffer.length - done);
+          const { bytesWritten } = await fd.write(buffer, done, length, filePosition + done).catch(failed);
+          if (!(bytesWritten > 0)) {
+            throw new QvdIOError(
+              `Could not write the QVD file: nothing was written at byte ${filePosition + done}, and the operating system reported no error.`,
+              { file: this._path, operation: "write", filePosition: filePosition + done }
+            );
+          }
+          done += bytesWritten;
         }
       }
       /**
@@ -1247,13 +1708,13 @@ var init_QvdFileWriter = __esm({
         const existingMetadata = this._df.metadata;
         const baseMetadata = existingMetadata ? {
           QvBuildNo: existingMetadata.QvBuildNo || 50667,
-          CreatorDoc: existingMetadata.CreatorDoc || crypto.randomUUID(),
+          CreatorDoc: existingMetadata.CreatorDoc || crypto2.randomUUID(),
           CreateUtcTime: existingMetadata.CreateUtcTime || creationDate,
           SourceCreateUtcTime: existingMetadata.SourceCreateUtcTime || "",
           SourceFileUtcTime: existingMetadata.SourceFileUtcTime || "",
           SourceFileSize: existingMetadata.SourceFileSize || -1,
           StaleUtcTime: existingMetadata.StaleUtcTime || "",
-          TableName: existingMetadata.TableName || path.basename(this._path, path.extname(this._path)),
+          TableName: existingMetadata.TableName || path2.basename(this._path, path2.extname(this._path)),
           Compression: existingMetadata.Compression || "",
           Comment: existingMetadata.Comment || "",
           EncryptionInfo: existingMetadata.EncryptionInfo || "",
@@ -1267,13 +1728,13 @@ var init_QvdFileWriter = __esm({
           }
         } : {
           QvBuildNo: 50667,
-          CreatorDoc: crypto.randomUUID(),
+          CreatorDoc: crypto2.randomUUID(),
           CreateUtcTime: creationDate,
           SourceCreateUtcTime: "",
           SourceFileUtcTime: "",
           SourceFileSize: -1,
           StaleUtcTime: "",
-          TableName: path.basename(this._path, path.extname(this._path)),
+          TableName: path2.basename(this._path, path2.extname(this._path)),
           Compression: "",
           Comment: "",
           EncryptionInfo: "",
@@ -1524,7 +1985,7 @@ var init_QvdFileWriter = __esm({
             const key = keys[slot];
             offset = typeof key === "number" ? writeSymbol(columnBuffer, offset, kinds[slot], key, texts[slot]) : writeSymbol(columnBuffer, offset, kinds[slot], null, key);
           }
-          assert2(offset === byteLength, "A column was encoded into a different number of bytes than it was sized for.");
+          assert3(offset === byteLength, "A column was encoded into a different number of bytes than it was sized for.");
           columnBuffers.push(columnBuffer);
           this._symbolTableMetadata?.push([symbolsOffset, byteLength, containsNull[column]]);
           this._symbolCounts?.push(keys.length);
@@ -1563,9 +2024,9 @@ var init_QvdFileWriter = __esm({
        * @private
        */
       _buildIndexTable() {
-        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.");
+        assert3(this._symbolCounts, "The QVD file symbol table has not been built.");
+        assert3(this._symbolTableMetadata, "The QVD file symbol table metadata has not been built.");
+        assert3(this._symbolIndexByValue, "The QVD file symbol index has not been built.");
         this._indexTableMetadata = [];
         const columns = this._df.columns;
         const data = this._df.data;
@@ -2118,6 +2579,15 @@ function validateFieldBitMetadata(field, recordSize, filePath) {
       stage: "parseIndexTable"
     });
   }
+  if (bias < -2147483648 || bias + 2 ** bitWidth - 1 > 2 ** 31 - 1) {
+    throw new QvdCorruptedError("Bias out of range", {
+      field: field["FieldName"],
+      bias,
+      bitWidth,
+      file: filePath,
+      stage: "parseIndexTable"
+    });
+  }
   const recordSizeInBits = recordSize * 8;
   if (bitOffset + bitWidth > recordSizeInBits) {
     throw new QvdCorruptedError("Bit field extends beyond record size", {
@@ -2245,7 +2715,10 @@ function parseFieldSymbols(symbolBuffer, start, end, keep, fieldName, filePath)
   }
   return { numbers, texts };
 }
-var MAX_TEXT_BYTES;
+function countFieldSymbols(symbolBuffer, start, end, fieldName, filePath) {
+  return parseFieldSymbols(symbolBuffer, start, end, DECODE_NOTHING, fieldName, filePath).numbers.length;
+}
+var MAX_TEXT_BYTES, DECODE_NOTHING;
 var init_symbolParser = __esm({
   "src/util/symbolParser.js"() {
     init_QvdErrors();
@@ -2253,6 +2726,8 @@ var init_symbolParser = __esm({
     __name(textEnd, "textEnd");
     __name(overflow, "overflow");
     __name(parseFieldSymbols, "parseFieldSymbols");
+    DECODE_NOTHING = /* @__PURE__ */ new Set();
+    __name(countFieldSymbols, "countFieldSymbols");
   }
 });
 
@@ -2684,9 +3159,9 @@ var init_QvdColumnTable = __esm({
        *   read switches to two-pass filtering.
        * @return {Promise<QvdColumnTable>} The file, as columns.
        */
-      static async fromQvd(path3, options = {}) {
+      static async fromQvd(path5, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
-        const reader = new QvdFileReader2(path3, {
+        const reader = new QvdFileReader2(path5, {
           ...readerOptionsFrom(options),
           // This read builds no rows, so the memory guard must not charge it for them. A columnar
           // read of the 38MB taxi fixture completes in a 15MB heap; charged the row cost it was
@@ -2754,22 +3229,26 @@ 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();
-  });
+async function* chunksFrom(handle, chunkSize, failed) {
+  let position = 0;
+  for (; ; ) {
+    const buffer = Buffer.alloc(chunkSize);
+    const { bytesRead } = await handle.read(buffer, 0, chunkSize, position).catch(failed);
+    if (bytesRead === 0) {
+      return;
+    }
+    yield bytesRead === chunkSize ? buffer : Buffer.from(buffer.subarray(0, bytesRead));
+    position += bytesRead;
+  }
 }
-var MAX_HEADER_SIZE, READ_CHUNK_SIZE, ANALYSIS_SLICE_ROWS, QvdFileReader;
+var MAX_HEADER_SIZE, READ_CHUNK_SIZE, ANALYSIS_SLICE_ROWS, COUNT_SYMBOLS_PAST, QvdFileReader;
 var init_QvdFileReader = __esm({
   "src/QvdFileReader.js"() {
     init_QvdDataFrame();
     init_QvdErrors();
     init_validatePath();
+    init_openChecked();
+    init_ioErrors();
     init_bitUtils();
     init_memoryUtils();
     init_validationUtils();
@@ -2780,7 +3259,8 @@ var init_QvdFileReader = __esm({
     MAX_HEADER_SIZE = 16 * 1024 * 1024;
     READ_CHUNK_SIZE = 512 * 1024 * 1024;
     ANALYSIS_SLICE_ROWS = 65536;
-    __name(closeReadStream, "closeReadStream");
+    COUNT_SYMBOLS_PAST = 65536;
+    __name(chunksFrom, "chunksFrom");
     QvdFileReader = class {
       static {
         __name(this, "QvdFileReader");
@@ -2841,7 +3321,9 @@ var init_QvdFileReader = __esm({
           signal
         } = options;
         this._materialisesRows = materialisesRows;
-        this._path = validatePath(filePath, allowedDir);
+        const checked = checkPath(filePath, allowedDir);
+        this._path = checked.path;
+        this._allowedDir = checked.base;
         this._duals = normaliseDuals(duals, this._path);
         this._coerceNumericStrings = normaliseCoerceNumericStrings(coerceNumericStrings, this._path);
         this._memorySafetyFactor = memorySafetyFactor;
@@ -2926,18 +3408,21 @@ var init_QvdFileReader = __esm({
        * two-pass path exist for.
        *
        * Algorithm for a windowed read:
-       * 1. Stream-read the file until XML header delimiter is found
+       * 1. Read the file a chunk at a time until the XML header delimiter is found
        * 2. Parse header to determine symbol table and index table locations
        * 3. Calculate bytes needed: header + full symbol table + partial index table
-       * 4. Read only those calculated bytes using fs.open/read
+       * 4. Read only those calculated bytes, by position
        * 5. Rest of parsing proceeds normally with limited data
        *
        * WHY THIS APPROACH:
        * - Symbol table must be fully loaded (contains all unique values)
        * - Index table can be partially loaded (only rows we need)
-       * - Streaming for header finding is efficient for unknown header sizes
+       * - Reading chunks to find the header is efficient for unknown header sizes
        * - Direct byte-range reading for remaining data is fastest
        *
+       * All of it goes through one handle, opened once, on the file the containment check approved. See
+       * `chunksFrom` and `openChecked` for why a read no longer opens the path more than once.
+       *
        * A window with a non-zero `offset` reads two ranges rather than one: the header and symbol
        * table from the front of the file, and the window's records from wherever they sit. The bytes
        * between are never read, which is what makes `{offset: 1_700_000, limit: 100}` on the taxi
@@ -2955,49 +3440,49 @@ var init_QvdFileReader = __esm({
       async _readData(window = { offset: 0, limit: null }, headerOnly = false, liveRows = null) {
         this._throwIfAborted();
         this._emitProgress("read", 0, 1);
+        const failed = rethrowAsIoError(this._path, "read");
+        const handle = await openChecked(checkPath(this._path, this._allowedDir), "read", failed);
+        await closeAfter(handle, failed, () => this._readFrom(handle, window, headerOnly, liveRows, failed));
+      }
+      /**
+       * Reads what `_readData` was asked for, through the handle it opened.
+       *
+       * @param {import('fs/promises').FileHandle} handle The open file.
+       * @param {QvdRowWindow} window The rows to read.
+       * @param {boolean} headerOnly Stop once the XML header has been read.
+       * @param {{rows: number, perChunk: number}|null} liveRows Rows held at one instant - see `_prepare`.
+       * @param {(error: unknown) => never} failed The read's `rethrowAsIoError` handler.
+       * @private
+       */
+      async _readFrom(handle, window, headerOnly, liveRows, failed) {
         const HEADER_DELIMITER = "\r\n\0";
         const CHUNK_SIZE = 64 * 1024;
-        const stream = fs.createReadStream(this._path, {
-          highWaterMark: CHUNK_SIZE
-        });
         const headerChunks = [];
         let headerBytes = 0;
         let tail = Buffer.alloc(0);
         let headerDelimiterIndex = -1;
-        try {
-          for await (const chunk of stream) {
-            const chunkStart = headerBytes;
-            const searchBuffer = tail.length > 0 ? Buffer.concat([tail, chunk]) : chunk;
-            const foundInSearch = searchBuffer.indexOf(HEADER_DELIMITER);
-            headerChunks.push(chunk);
-            headerBytes += chunk.length;
-            if (foundInSearch !== -1) {
-              headerDelimiterIndex = chunkStart - tail.length + foundInSearch;
-              stream.destroy();
-              break;
-            }
-            tail = Buffer.from(searchBuffer.subarray(-(HEADER_DELIMITER.length - 1)));
-            if (headerBytes > MAX_HEADER_SIZE) {
-              stream.destroy();
-              throw new QvdCorruptedError(
-                `The XML header delimiter was not found within the first ${MAX_HEADER_SIZE / (1024 * 1024)}MB of the file.`,
-                {
-                  file: this._path,
-                  bytesSearched: headerBytes,
-                  maxHeaderSize: MAX_HEADER_SIZE,
-                  stage: "readData"
-                }
-              );
-            }
+        for await (const chunk of chunksFrom(handle, CHUNK_SIZE, failed)) {
+          const chunkStart = headerBytes;
+          const searchBuffer = tail.length > 0 ? Buffer.concat([tail, chunk]) : chunk;
+          const foundInSearch = searchBuffer.indexOf(HEADER_DELIMITER);
+          headerChunks.push(chunk);
+          headerBytes += chunk.length;
+          if (foundInSearch !== -1) {
+            headerDelimiterIndex = chunkStart - tail.length + foundInSearch;
+            break;
           }
-        } catch (error) {
-          const isExpectedEarlyClose = headerDelimiterIndex !== -1 && error !== null && typeof error === "object" && /** @type {{code?: unknown}} */
-          error.code === "ERR_STREAM_PREMATURE_CLOSE";
-          if (!isExpectedEarlyClose) {
-            throw error;
+          tail = Buffer.from(searchBuffer.subarray(-(HEADER_DELIMITER.length - 1)));
+          if (headerBytes > MAX_HEADER_SIZE) {
+            throw new QvdCorruptedError(
+              `The XML header delimiter was not found within the first ${MAX_HEADER_SIZE / (1024 * 1024)}MB of the file.`,
+              {
+                file: this._path,
+                bytesSearched: headerBytes,
+                maxHeaderSize: MAX_HEADER_SIZE,
+                stage: "readData"
+              }
+            );
           }
-        } finally {
-          await closeReadStream(stream);
         }
         if (headerDelimiterIndex === -1) {
           throw new QvdCorruptedError(
@@ -3038,9 +3523,9 @@ var init_QvdFileReader = __esm({
           (value) => Number.isSafeInteger(value) && value >= 0
         );
         if (headerNumbersUsable) {
-          const { size: fileSize } = await fs.promises.stat(this._path);
-          this._fileSize = fileSize;
-          this._headerMatchesFile = headerEndIndex + symbolTableLength + totalRows * recordSize <= fileSize;
+          const { size: fileSize2 } = await handle.stat().catch(failed);
+          this._fileSize = fileSize2;
+          this._headerMatchesFile = headerEndIndex + symbolTableLength + totalRows * recordSize <= fileSize2;
         }
         const resolved = headerNumbersUsable ? resolveWindow(window, totalRows) : { offset: 0, limit: 0 };
         const windowRows = resolved.limit;
@@ -3057,7 +3542,7 @@ var init_QvdFileReader = __esm({
           );
         }
         if (window.offset === 0 && window.limit === null) {
-          this._buffer = await fs.promises.readFile(this._path);
+          this._buffer = await handle.readFile().catch(failed);
           this._fileSize = this._buffer.length;
           this._bufferFirstRow = 0;
           this._emitProgress("read", 1, 1);
@@ -3083,34 +3568,29 @@ var init_QvdFileReader = __esm({
         const indexTableBytesToRead = rowsToLoad * recordSize;
         const totalBytesToRead = indexTableOffset + indexTableBytesToRead;
         const fileBytesRequired = indexTableOffset + skippedIndexBytes + indexTableBytesToRead;
-        const fd = await fs.promises.open(this._path, "r");
-        try {
-          const { size: fileSize } = await fd.stat();
-          this._fileSize = fileSize;
-          if (fileBytesRequired > fileSize) {
-            throw new QvdCorruptedError("The file is shorter than its header claims.", {
-              file: this._path,
-              fileSize,
-              requiredBytes: fileBytesRequired,
-              stage: "readData"
-            });
-          }
-          this._buffer = Buffer.alloc(totalBytesToRead);
-          await this._readRange(fd, 0, indexTableOffset, 0, fileSize, totalBytesToRead);
-          if (indexTableBytesToRead > 0) {
-            await this._readRange(
-              fd,
-              indexTableOffset,
-              indexTableBytesToRead,
-              indexTableOffset + skippedIndexBytes,
-              fileSize,
-              fileBytesRequired
-            );
-          }
-          this._bufferFirstRow = resolved.offset;
-        } finally {
-          await fd.close();
+        const { size: fileSize } = await handle.stat().catch(failed);
+        this._fileSize = fileSize;
+        if (fileBytesRequired > fileSize) {
+          throw new QvdCorruptedError("The file is shorter than its header claims.", {
+            file: this._path,
+            fileSize,
+            requiredBytes: fileBytesRequired,
+            stage: "readData"
+          });
         }
+        this._buffer = Buffer.alloc(totalBytesToRead);
+        await this._readRange(handle, 0, indexTableOffset, 0, fileSize, totalBytesToRead);
+        if (indexTableBytesToRead > 0) {
+          await this._readRange(
+            handle,
+            indexTableOffset,
+            indexTableBytesToRead,
+            indexTableOffset + skippedIndexBytes,
+            fileSize,
+            fileBytesRequired
+          );
+        }
+        this._bufferFirstRow = resolved.offset;
         this._emitProgress("read", 1, 1);
       }
       /**
@@ -3129,11 +3609,12 @@ var init_QvdFileReader = __esm({
        * @private
        */
       async _readRange(fd, bufferOffset, byteCount, filePosition, fileSize, requiredBytes) {
-        assert2(this._buffer, "The read buffer has not been allocated.");
+        assert3(this._buffer, "The read buffer has not been allocated.");
+        const failed = rethrowAsIoError(this._path, "read");
         let done = 0;
         while (done < byteCount) {
           const length = Math.min(READ_CHUNK_SIZE, byteCount - done);
-          const { bytesRead } = await fd.read(this._buffer, bufferOffset + done, length, filePosition + done);
+          const { bytesRead } = await fd.read(this._buffer, bufferOffset + done, length, filePosition + done).catch(failed);
           if (bytesRead === 0) {
             throw new QvdCorruptedError("Unexpected end of file while reading QVD data.", {
               file: this._path,
@@ -3180,6 +3661,7 @@ var init_QvdFileReader = __esm({
         }
         const headerEndIndex = headerDelimiterIndex + HEADER_DELIMITER.length;
         const headerBuffer = this._buffer.subarray(headerBeginIndex, headerEndIndex);
+        this._fieldBitMetadataValidated = false;
         this._header = await xml2.parseStringPromise(headerBuffer.toString(), { explicitArray: false });
         if (!this._header) {
           throw new QvdParseError("The XML header could not be parsed.", {
@@ -3225,8 +3707,8 @@ var init_QvdFileReader = __esm({
        * @param {QvdRowWindow} window The rows of interest, as file row indices.
        * @param {string} stage Stage name for any error raised here.
        * @return {{fields: Array<any>, recordSize: number, totalRows: number, rowsToLoad: number,
-       *   indexBuffer: Buffer}} The record geometry. `indexBuffer` starts at the window's first
-       *   record, so the decoder always counts from zero.
+       *   indexBuffer: Buffer, firstRow: number}} The record geometry. `indexBuffer` starts at the
+       *   window's first record, file row `firstRow`, so the decoder always counts from zero.
        * @private
        */
       _planIndexTable(window, stage) {
@@ -3268,11 +3750,11 @@ var init_QvdFileReader = __esm({
           }
           this._fieldBitMetadataValidated = true;
         }
-        assert2(
+        assert3(
           rowsToLoad === 0 || recordSize === 0 || Math.floor(indexBuffer.length / recordSize) >= rowsToLoad,
           `The index table holds ${Math.floor(indexBuffer.length / (recordSize || 1))} whole records but ${rowsToLoad} were validated as present.`
         );
-        return { fields, recordSize, totalRows, rowsToLoad, indexBuffer };
+        return { fields, recordSize, totalRows, rowsToLoad, indexBuffer, firstRow };
       }
       /**
        * Analyzes the index table to determine which symbols are actually needed.
@@ -3299,6 +3781,9 @@ var init_QvdFileReader = __esm({
           const bitOffset = parseInt(field["BitOffset"], 10);
           const bitWidth = parseInt(field["BitWidth"], 10);
           const bias = parseInt(field["Bias"], 10);
+          const length = parseInt(field["Length"], 10);
+          let indexLimit = Number.isSafeInteger(length) && length >= 0 ? Math.ceil(length / 2) : Infinity;
+          let counted = false;
           for (let first = 0; first < rowsToLoad; first += sliceRows) {
             const count = Math.min(sliceRows, rowsToLoad - first);
             decodeIndexColumn(
@@ -3311,15 +3796,53 @@ var init_QvdFileReader = __esm({
               column
             );
             for (let row = 0; row < count; row++) {
-              if (column[row] >= 0) {
+              if (column[row] >= 0 && column[row] < indexLimit) {
                 needed.add(column[row]);
               }
             }
+            if (!counted && needed.size > COUNT_SYMBOLS_PAST) {
+              counted = true;
+              indexLimit = Math.min(indexLimit, this._countFieldSymbols(field));
+              for (const index of needed) {
+                if (index >= indexLimit) {
+                  needed.delete(index);
+                }
+              }
+            }
           }
           this._emitProgress("symbol-analysis", position + 1, fields.length);
         });
         return symbolUsage;
       }
+      /**
+       * How many symbols a field holds, for the symbol-usage pass, which runs before the symbols are parsed.
+       *
+       * The count is `countFieldSymbols`, the parse itself told to decode nothing, so it is the count
+       * `_parseSymbolTable` will produce and `_parseIndexTable` will check against. The field's area is
+       * validated first, as `_parseSymbolTable` would, so a damaged `Offset` or `Length` is reported the
+       * same way wherever it is met.
+       *
+       * @param {any} field The field's header.
+       * @return {number} Its symbols.
+       * @throws {QvdCorruptedError} If the area is not inside the symbol table, or a symbol runs past it.
+       * @private
+       */
+      _countFieldSymbols(field) {
+        assert3(
+          this._buffer && this._symbolTableOffset && this._indexTableOffset,
+          "The QVD file has not been read before its symbols were counted."
+        );
+        const symbolBuffer = this._buffer.subarray(this._symbolTableOffset, this._indexTableOffset);
+        validateFieldMetadata(field, symbolBuffer.length, this._path);
+        const offset = parseInt(field["Offset"], 10);
+        return countFieldSymbols(
+          symbolBuffer,
+          offset,
+          offset + parseInt(field["Length"], 10),
+          field["FieldName"],
+          this._path
+        );
+      }
       /**
        * Parses the symbol table of the QVD file. This method is part of the parsing process
        * and should not be called directly.
@@ -3405,12 +3928,19 @@ var init_QvdFileReader = __esm({
        * `base += recordSize`, so decoding rows k to k+n is a question of where the buffer slice starts
        * and how many iterations run. Nothing about the decoder changed to support it.
        *
+       * Every index is checked as it is decoded. One that addresses neither a symbol of its field nor
+       * NULL throws a `QvdCorruptedError` naming the file row (#125). Here and not where rows or columns
+       * are built, because every read decodes through this method and a columnar read hands its codes
+       * straight to the caller. Rows outside the window are not decoded, so they are not checked.
+       *
        * @param {QvdRowWindow} window The rows to decode.
+       * @throws {QvdCorruptedError} If an index in the window addresses neither a symbol nor NULL.
        */
       async _parseIndexTable(window) {
-        const { fields, recordSize, rowsToLoad, indexBuffer } = this._planIndexTable(window, "parseIndexTable");
-        this._rowsDecoded = rowsToLoad;
-        this._indexColumns = fields.map((field, position) => {
+        const { fields, recordSize, rowsToLoad, indexBuffer, firstRow } = this._planIndexTable(window, "parseIndexTable");
+        assert3(this._symbolTable, "The QVD file symbol table has not been parsed.");
+        const symbolTable = this._symbolTable;
+        const columns = fields.map((field, position) => {
           this._throwIfAborted();
           const column = decodeIndexColumn(
             indexBuffer,
@@ -3419,11 +3949,14 @@ var init_QvdFileReader = __esm({
             parseInt(field["BitOffset"], 10),
             parseInt(field["BitWidth"], 10),
             parseInt(field["Bias"], 10),
-            new Int32Array(rowsToLoad)
+            new Int32Array(rowsToLoad),
+            { symbolCount: symbolTable[position].numbers.length, field: field["FieldName"], file: this._path, firstRow }
           );
           this._emitProgress("index-table", position + 1, fields.length);
           return column;
         });
+        this._indexColumns = columns;
+        this._rowsDecoded = rowsToLoad;
       }
       /**
        * Reads the file's schema and header metadata, without touching the symbol or index tables.
@@ -3445,7 +3978,7 @@ var init_QvdFileReader = __esm({
         await this._parseHeader();
         this._emitProgress("header", 1, 1);
         this._throwIfAborted();
-        assert2(this._header, "The QVD file header has not been parsed.");
+        assert3(this._header, "The QVD file header has not been parsed.");
         const header = this._header["QvdTableHeader"];
         let fields = header["Fields"]?.["QvdFieldHeader"] ?? [];
         if (!Array.isArray(fields)) {
@@ -3509,9 +4042,10 @@ var init_QvdFileReader = __esm({
        * Shares every step with `load()` up to the point where rows would be built - see `_prepare`.
        * What it keeps instead is what the decoder already produced: one `Int32Array` of stored
        * indices per field, and one resolved value per distinct symbol. On the 1.7M x 20 taxi
-       * fixture that is 38.6 MiB against the 352.8 MiB `data` retains, because a column costs four
+       * fixture that is 133 MiB against the 352 MiB `data` retains, because a column costs four
        * bytes per row rather than a boxed value per cell, and the symbols are a few thousand
-       * entries shared across every row that uses them.
+       * entries shared across every row that uses them. The codes' storage lives outside the V8
+       * heap: 3 MiB of the 133 is on it.
        *
        * @param {number|null|{offset?: number, limit?: number|null, maxRows?: number|null}} [window]
        *   The rows to decode, in the same spellings `load()` accepts.
@@ -3522,7 +4056,7 @@ var init_QvdFileReader = __esm({
         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.");
+        assert3(this._indexColumns, "The QVD file index table has not been parsed.");
         return new QvdColumnTable2({
           columns: prepared.columns,
           codesByField: this._indexColumns,
@@ -3551,7 +4085,8 @@ var init_QvdFileReader = __esm({
        * `chunkSize * 2`, and why the heap it needs is twice what one chunk suggests.
        *
        * A window covering no rows yields nothing at all, rather than one empty frame - so
-       * `for await` over an exhausted offset does nothing, which is what a paging loop wants.
+       * `for await` over an exhausted offset does nothing, which is what a paging loop wants. Its header
+       * is still checked, as every read of a file's rows checks it.
        *
        * @param {number|null|{offset?: number, limit?: number|null, maxRows?: number|null}} window
        *   The rows to cover, in the same spellings `load()` accepts.
@@ -3569,6 +4104,10 @@ var init_QvdFileReader = __esm({
         const liveRows = { rows: chunkSize * 2, perChunk: 2 };
         const rows = normaliseWindow(window, this._path);
         const prepared = await this._prepare(rows, liveRows);
+        if (prepared.rowsAvailable === 0) {
+          this._planIndexTable({ offset: prepared.offset, limit: 0 }, "parseIndexTable");
+          return;
+        }
         for (let done = 0; done < prepared.rowsAvailable; done += chunkSize) {
           this._throwIfAborted();
           const count = Math.min(chunkSize, prepared.rowsAvailable - done);
@@ -3619,7 +4158,7 @@ var init_QvdFileReader = __esm({
         await this._parseHeader();
         this._emitProgress("header", 1, 1);
         this._throwIfAborted();
-        assert2(this._header, "The QVD file header has not been parsed.");
+        assert3(this._header, "The QVD file header has not been parsed.");
         const totalRows = parseInt(this._header["QvdTableHeader"]["NoOfRecords"], 10);
         const symbolTableLength = parseInt(this._header["QvdTableHeader"]["Offset"], 10);
         const resolved = resolveWindow(window, totalRows);
@@ -3633,9 +4172,9 @@ var init_QvdFileReader = __esm({
           }
         }
         await this._parseSymbolTable(symbolsToKeep, rowsAvailable, liveRows);
-        assert2(this._symbolTable, "The QVD file symbol table has not been parsed.");
+        assert3(this._symbolTable, "The QVD file symbol table has not been parsed.");
         this._throwIfAborted();
-        assert2(this._selectedFields, "The QVD file fields have not been resolved.");
+        assert3(this._selectedFields, "The QVD file fields have not been resolved.");
         const resolvedByField = [];
         const halvesByField = [];
         const entries = [];
@@ -3696,7 +4235,7 @@ var init_QvdFileReader = __esm({
        * @private
        */
       _buildRows(resolvedByField, progressBase, progressTotal) {
-        assert2(this._indexColumns, "The QVD file index table has not been parsed.");
+        assert3(this._indexColumns, "The QVD file index table has not been parsed.");
         const indexColumns = this._indexColumns;
         const fieldCount = indexColumns.length;
         const rowCount = this._rowsDecoded;
@@ -4301,14 +4840,31 @@ var init_QvdDataFrame = __esm({
        *   volume, pass its root explicitly ('/' on POSIX, 'C:\\' on Windows); a null or empty value falls
        *   back to the working directory rather than removing the restriction.
        * @param {Function} [options.onProgress] Optional progress callback function that receives progress updates during write operations.
+       * @param {boolean} [options.atomic=true] Whether to replace the file rather than rewrite it. The QVD
+       *   is built beside it under a temporary name and renamed over it, so a write that fails leaves the
+       *   previous file exactly as it was, and a reader of the path - a Qlik reload, say - sees the old
+       *   file or the new one and never a part of either. False rewrites the file where it stands, as
+       *   every version before 2.0.0 did: that keeps its identity, including hard links, its owner and
+       *   permissions set on the file itself, and needs neither room for two copies nor permission to
+       *   create files in the directory. It also destroys the previous file as the write begins. A file
+       *   that does not exist yet is renamed into place either way, since there is nothing to rewrite.
+       * @param {boolean} [options.fsync=true] Whether to wait for the contents to reach the disk before
+       *   resolving. It is what carries an atomic write's promise through a power loss - the contents are
+       *   on the disk before anything is renamed, so a crash leaves the previous file or the new one and
+       *   never a damaged one - and what reports a failing disk's deferred error instead of losing it. The
+       *   rename itself is not flushed, so a crash just after the call can still lose the replacement, or
+       *   a file that did not exist before. False resolves once the operating system has accepted the
+       *   bytes, which is faster and is what every version before 2.0.0 did.
        */
-      async toQvd(path3, options = {}) {
+      async toQvd(path5, options = {}) {
         const { QvdFileWriter: QvdFileWriter2 } = await Promise.resolve().then(() => (init_QvdFileWriter(), QvdFileWriter_exports));
         const writerOptions = {
           allowedDir: options.allowedDir,
-          onProgress: options.onProgress
+          onProgress: options.onProgress,
+          atomic: options.atomic,
+          fsync: options.fsync
         };
-        await new QvdFileWriter2(path3, this, writerOptions).save();
+        await new QvdFileWriter2(path5, this, writerOptions).save();
       }
       /**
        * Loads a QVD file and returns its data frame.
@@ -4361,9 +4917,9 @@ var init_QvdDataFrame = __esm({
        *   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 = {}) {
+      static async fromQvd(path5, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
-        return await new QvdFileReader2(path3, readerOptionsFrom(options)).load(windowFrom(options));
+        return await new QvdFileReader2(path5, readerOptionsFrom(options)).load(windowFrom(options));
       }
       /**
        * Reads a QVD file in chunks, as an async generator of data frames.
@@ -4410,9 +4966,9 @@ var init_QvdDataFrame = __esm({
        *   windowed read switches to two-pass filtering.
        * @return {AsyncGenerator<QvdDataFrame>} The chunks, in file order.
        */
-      static async *iterate(path3, options = {}) {
+      static async *iterate(path5, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
-        const reader = new QvdFileReader2(path3, readerOptionsFrom(options));
+        const reader = new QvdFileReader2(path5, readerOptionsFrom(options));
         yield* reader.iterateRows(windowFrom(options), options.chunkSize === void 0 ? 1e5 : options.chunkSize);
       }
       /**
@@ -4443,9 +4999,9 @@ var init_QvdDataFrame = __esm({
        * @param {AbortSignal} [options.signal] Cancels the read, rejecting with `signal.reason`.
        * @return {Promise<QvdFileMetadata>} The file's schema and header metadata.
        */
-      static async readMetadata(path3, options = {}) {
+      static async readMetadata(path5, options = {}) {
         const { QvdFileReader: QvdFileReader2 } = await Promise.resolve().then(() => (init_QvdFileReader(), QvdFileReader_exports));
-        return await new QvdFileReader2(path3, metadataOptionsFrom(options)).loadMetadata();
+        return await new QvdFileReader2(path5, metadataOptionsFrom(options)).loadMetadata();
       }
       /**
        * Constructs a data frame from a dictionary.