@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/dist/config/configUtils.js

@@ -38,7 +38,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolvePath = resolvePath;
 exports.getConfigPath = getConfigPath;
+exports.isStorageExhausted = isStorageExhausted;
+exports.persistConfigDuringBoot = persistConfigDuringBoot;
 exports.atomicWriteFile = atomicWriteFile;
+exports.renameWithRetry = renameWithRetry;
 exports.createConfigFile = createConfigFile;
 exports.getDefaultConfig = getDefaultConfig;
 exports.getConfigValue = getConfigValue;
@@ -62,9 +65,11 @@ const hdbTerms = __importStar(require("../utility/hdbTerms.js"));
 const hdbUtils = __importStar(require("../utility/common_utils.js"));
 const harper_logger_ts_1 = __importDefault(require("../utility/logging/harper_logger.js"));
 const configValidator_ts_1 = require("../validation/configValidator.js");
+const componentNames_ts_1 = require("../utility/componentNames.js");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const yaml_1 = __importDefault(require("yaml"));
 const path_1 = __importDefault(require("path"));
+const node_os_1 = require("node:os");
 const node_worker_threads_1 = require("node:worker_threads");
 const node_crypto_1 = require("node:crypto");
 const is_number_1 = __importDefault(require("is-number"));
@@ -84,6 +89,7 @@ const packageUtils_js_1 = require("../utility/packageUtils.js");
 const env = __importStar(require("../utility/environment/environmentManager.js"));
 const harperConfigEnvVars_ts_1 = require("./harperConfigEnvVars.js");
 const componentEnvPrepass_ts_1 = require("./componentEnvPrepass.js");
+const threadHeapMemory_ts_1 = require("../server/threads/threadHeapMemory.js");
 const { DATABASES_PARAM_CONFIG, CONFIG_PARAMS, CONFIG_PARAM_MAP } = hdbTerms;
 const UNINIT_GET_CONFIG_ERR = 'Unable to get config value because config is uninitialized';
 const CONFIG_INIT_MSG = 'Config successfully initialized';
@@ -140,56 +146,154 @@ function getConfigPath(param) {
         return value;
     return path_1.default.resolve(rootPath, value);
 }
-// Write atomically via temp file + rename so readers don't observe a truncated/empty file.
-// Temp path includes randomness so two worker threads in the same process (same pid) writing
-// in the same millisecond can't collide on the temp name and then race the rename.
-//
+// Write atomically via a randomized temp file + rename so readers do not observe partial content
+// and concurrent workers, which share process.pid, do not collide on a temp path.
 // Windows has no POSIX-style "replace an open file" semantics: rename() fails with
-// EPERM/EACCES if another thread/process has the destination momentarily open for read.
-// Every worker thread runs its own RootConfigWatcher (chokidar), so a write on one thread
-// routinely races a hot-reload read on another; Windows Defender / AV real-time scanning can
-// hold a similar transient handle. Retry with exponential backoff to ride out the race -
-// callers are synchronous, so the wait is a synchronous sleep rather than an async one.
-// The budget must outlast a single AV real-time scan pass (seconds, not hundreds of ms):
-// the previous ~910ms budget was exhausted twice in a row by the same test on a CI runner
-// (harper#2036), so the worst case is now ~3.6s.
-const RENAME_RETRY_MAX_ATTEMPTS = 12;
+// EPERM/EACCES/EBUSY while another worker or AV holds the destination open. Root config watchers use
+// readConfigFileSync so this blocking retry cannot wait on a read owned by its own worker.
+// The budget is the wall-clock window of the 12-attempt schedule it replaced
+// (10+20+40+80+160+320+500*6), so it stays a deadline rather than an attempt count without
+// widening the stall: this loop blocks the calling worker's event loop, and `set_configuration`
+// reaches it from a live request thread.
+const RENAME_RETRY_BUDGET_MS = 3_630;
+// Secondary guard only: stops a degenerate zero-delay option set from spinning the whole budget.
+const RENAME_RETRY_MAX_ATTEMPTS = 25;
 const RENAME_RETRY_INITIAL_DELAY_MS = 10;
 const RENAME_RETRY_MAX_DELAY_MS = 500;
-// Never notified; exists only so Atomics.wait can time out (a synchronous, CPU-idle sleep).
+// Never notified; Atomics.wait uses this only as a CPU-idle synchronous sleep.
 const renameRetrySleepBuffer = new Int32Array(new SharedArrayBuffer(4));
-function atomicWriteFile(filePath, content, { maxRetries = RENAME_RETRY_MAX_ATTEMPTS, initialDelayMs = RENAME_RETRY_INITIAL_DELAY_MS, maxDelayMs = RENAME_RETRY_MAX_DELAY_MS, } = {}) {
+// Classified by code alone rather than gated to win32 like the read side: `process.platform` does
+// not answer whether this filesystem can replace an open file — WSL drvfs, CIFS/SMB and Docker
+// Desktop bind mounts all report `linux` and return these codes transiently.
+function isRetryableRenameError(code) {
+    return code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+}
+function validateRenameRetryOptions({ retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs }) {
+    const invalidOption = !Number.isFinite(retryBudgetMs) ||
+        retryBudgetMs < 0 ||
+        (!Number.isFinite(maxRetries) && maxRetries !== Infinity) ||
+        maxRetries < 0 ||
+        !Number.isFinite(initialDelayMs) ||
+        initialDelayMs < 0 ||
+        !Number.isFinite(maxDelayMs) ||
+        maxDelayMs < 0;
+    if (invalidOption) {
+        throw new RangeError('rename retry options must be non-negative numbers');
+    }
+}
+// Linux has no libuv mapping for EDQUOT, so a quota-exhausted write surfaces as
+// `Unknown system error -122` with an unusable `code`; the numeric errno is the portable signal
+// (EDQUOT is 122 on Linux, 69 on macOS).
+const STORAGE_EXHAUSTED_CODES = new Set(['ENOSPC', 'EDQUOT']);
+// EDQUOT is absent from os.constants.errno on platforms without quotas, so filter before negating:
+// -undefined is NaN, which would sit in the set matching nothing and reading as a bug.
+const STORAGE_EXHAUSTED_ERRNOS = new Set([node_os_1.constants.errno.ENOSPC, node_os_1.constants.errno.EDQUOT].filter((errno) => errno !== undefined).map((errno) => -errno));
+function isStorageExhausted(error) {
+    return STORAGE_EXHAUSTED_CODES.has(error?.code) || STORAGE_EXHAUSTED_ERRNOS.has(error?.errno);
+}
+// Boot-path persistence of derived config is best-effort: on an exhausted volume a fatal write here
+// is an un-breakable restart loop, because freeing space needs a started process (#847).
+function persistConfigDuringBoot(artifactPath, write) {
+    try {
+        write();
+        return true;
+    }
+    catch (error) {
+        if (!isStorageExhausted(error))
+            throw error;
+        harper_logger_ts_1.default.error(`Storage exhausted (${error.code ?? error.errno}) writing ${artifactPath}; continuing startup with the in-memory configuration. The file on disk is unchanged - free space on the Harper volume to restore config persistence.`);
+        return false;
+    }
+}
+// Returns true when the file was written, false when an unchanged write was skipped.
+function atomicWriteFile(filePath, content, { retryBudgetMs = RENAME_RETRY_BUDGET_MS, maxRetries = RENAME_RETRY_MAX_ATTEMPTS, initialDelayMs = RENAME_RETRY_INITIAL_DELAY_MS, maxDelayMs = RENAME_RETRY_MAX_DELAY_MS, skipIfUnchanged = false, } = {}) {
+    // Before the temp write, so an option set that can never rename leaves no file behind.
+    validateRenameRetryOptions({ retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs });
+    // Opt-in: skipping means no mtime bump, so no watcher event. Only callers that re-derive the
+    // same file every boot want that.
+    if (skipIfUnchanged && matchesFileContent(filePath, content))
+        return false;
     const tempPath = `${filePath}.${process.pid}.${node_worker_threads_1.threadId}.${(0, node_crypto_1.randomBytes)(4).toString('hex')}.tmp`;
-    fs_extra_1.default.writeFileSync(tempPath, content);
+    try {
+        fs_extra_1.default.writeFileSync(tempPath, content);
+    }
+    catch (err) {
+        // The open succeeds before the write runs out of room, leaving the temp file behind.
+        removeTempFile(tempPath);
+        throw err;
+    }
+    try {
+        renameWithRetry(tempPath, filePath, { retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs });
+    }
+    catch (err) {
+        // The temp name carries fresh randomness on every call, so a spent budget would otherwise
+        // leave a file nothing else will ever collect.
+        removeTempFile(tempPath);
+        throw err;
+    }
+    return true;
+}
+function renameWithRetry(fromPath, toPath, { retryBudgetMs = RENAME_RETRY_BUDGET_MS, maxRetries = RENAME_RETRY_MAX_ATTEMPTS, initialDelayMs = RENAME_RETRY_INITIAL_DELAY_MS, maxDelayMs = RENAME_RETRY_MAX_DELAY_MS, } = {}) {
+    validateRenameRetryOptions({ retryBudgetMs, maxRetries, initialDelayMs, maxDelayMs });
     let retries = maxRetries;
     let delayMs = initialDelayMs;
+    let retryDeadline;
+    let finalAttempt = false;
+    let attempts = 0;
+    const startedAt = performance.now();
     while (true) {
         try {
-            fs_extra_1.default.renameSync(tempPath, filePath);
-            break;
+            attempts++;
+            fs_extra_1.default.renameSync(fromPath, toPath);
+            return;
         }
         catch (err) {
-            if (retries > 0 && (err.code === 'EPERM' || err.code === 'EACCES')) {
+            if (!finalAttempt && retries > 0 && isRetryableRenameError(err.code)) {
                 retries--;
-                // Sleep synchronously (all call sites are sync) to allow the holder to close the
-                // file. Atomics.wait yields the thread to the OS instead of spinning the CPU,
-                // which is what makes a multi-second worst-case budget affordable.
-                if (delayMs > 0)
-                    Atomics.wait(renameRetrySleepBuffer, 0, 0, delayMs);
-                delayMs = Math.min(delayMs * 2, maxDelayMs);
-                continue;
-            }
-            // if it fails we should clean up the tmp file
-            try {
-                fs_extra_1.default.unlinkSync(tempPath);
+                if (retryDeadline === undefined) {
+                    retryDeadline = performance.now() + retryBudgetMs;
+                }
+                const remainingBudgetMs = retryDeadline - performance.now();
+                if (remainingBudgetMs > 0) {
+                    // Sleep synchronously (all call sites are sync) to allow the holder to close the
+                    // file. Atomics.wait yields the thread to the OS instead of spinning the CPU,
+                    // which is what makes a multi-second worst-case budget affordable.
+                    const sleepMs = Math.min(delayMs, remainingBudgetMs);
+                    finalAttempt = sleepMs === remainingBudgetMs;
+                    if (sleepMs > 0)
+                        Atomics.wait(renameRetrySleepBuffer, 0, 0, sleepMs);
+                    delayMs = Math.min(Math.max(delayMs * 2, RENAME_RETRY_INITIAL_DELAY_MS), maxDelayMs);
+                    continue;
+                }
             }
-            catch {
-                // ignore cleanup errors
+            // Whether the budget was spent or the code was never retryable is the difference
+            // between a holder that never released and a one-off failure, and neither survives on
+            // the rethrown error.
+            if (isRetryableRenameError(err.code)) {
+                harper_logger_ts_1.default.warn(`Could not replace ${toPath}: ${err.code} after ${attempts} attempts over ${Math.round(performance.now() - startedAt)}ms`);
             }
             throw err;
         }
     }
 }
+function removeTempFile(tempPath) {
+    try {
+        fs_extra_1.default.unlinkSync(tempPath);
+    }
+    catch {
+        // ignore cleanup errors
+    }
+}
+function matchesFileContent(filePath, content) {
+    if (typeof content !== 'string')
+        return false;
+    try {
+        return fs_extra_1.default.readFileSync(filePath, 'utf8') === content;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Builds the Harper config file using user inputs and default values from defaultConfig.yaml
  * @param args - any args that the user provided.
@@ -200,7 +304,7 @@ function createConfigFile(args, skipFsValidation = false) {
     // Loop through the user inputted args. Match them to a parameter in the default config file and update value.
     let schemasArgs;
     for (const arg in args) {
-        let configParam = CONFIG_PARAM_MAP[arg.toLowerCase()];
+        let configParam = lookupConfigParam(arg);
         // Schemas config args are handled differently, so if they exist set them to var that will be used by setSchemasConfig
         if (configParam === CONFIG_PARAMS.DATABASES) {
             if (Array.isArray(args[arg])) {
@@ -213,7 +317,7 @@ function createConfigFile(args, skipFsValidation = false) {
             }
             continue;
         }
-        if (!configParam && (arg.endsWith('_package') || arg.endsWith('_port'))) {
+        if (!configParam && isSuffixEscapedParam(arg)) {
             configParam = arg;
         }
         if (configParam !== undefined) {
@@ -306,7 +410,7 @@ function getDefaultConfig(param) {
         const configDoc = parseYamlDoc(DEFAULT_CONFIG_FILE_PATH);
         flatDefaultConfigObj = flattenConfig(configDoc.toJSON());
     }
-    const paramMap = CONFIG_PARAM_MAP[param.toLowerCase()];
+    const paramMap = lookupConfigParam(param);
     if (paramMap === undefined)
         return undefined;
     return flatDefaultConfigObj[paramMap.toLowerCase()];
@@ -327,7 +431,7 @@ function getConfigValue(param) {
         harper_logger_ts_1.default.trace(UNINIT_GET_CONFIG_ERR);
         return undefined;
     }
-    const paramMap = CONFIG_PARAM_MAP[param.toLowerCase()];
+    const paramMap = lookupConfigParam(param);
     if (paramMap === undefined)
         return undefined;
     return flatConfigObj[paramMap.toLowerCase()];
@@ -377,7 +481,11 @@ function ensureConfigKeysPresent(keys) {
     }
     if (added.length === 0)
         return [];
-    atomicWriteFile(configFilePath, String(configDoc));
+    // Worker threads re-read the config from disk and never run this backfill, so a key that only
+    // exists in this thread's memory activates nowhere that serves requests: report nothing when the
+    // write was refused rather than logging an activation the request path did not get.
+    if (!persistConfigDuringBoot(configFilePath, () => atomicWriteFile(configFilePath, String(configDoc))))
+        return [];
     // Mirror the additions into the already-memoized config so a built-in gated on the new key
     // activates on the CURRENT boot: componentLoader reads the root config from getConfigObj(),
     // which is cached early in boot — before an upgrade backfill runs — so a file-only write would
@@ -566,7 +674,7 @@ function checkForUpdatedConfig(configDoc, configFilePath) {
         if (configDoc.errors?.length > 0) {
             throw (0, hdbError_ts_1.handleHDBError)(new Error(), `Error parsing harperdb-config.yaml ${configDoc.errors}`, commonErrors_ts_1.HTTP_STATUS_CODES.INTERNAL_SERVER_ERROR);
         }
-        atomicWriteFile(configFilePath, String(configDoc));
+        persistConfigDuringBoot(configFilePath, () => atomicWriteFile(configFilePath, String(configDoc)));
     }
 }
 /**
@@ -636,6 +744,8 @@ function validateConfig(configDoc, skipFsValidation = false) {
     const domainSocketWarning = (0, configValidator_ts_1.getDomainSocketPathLengthWarning)(validation.value.rootPath, domainSocket);
     if (domainSocketWarning)
         harper_logger_ts_1.default.warn(domainSocketWarning);
+    if ((0, configValidator_ts_1.isLegacySqlApplicationEntry)(configJson.sql))
+        harper_logger_ts_1.default.warn("The root config entry 'sql' is an application, but 'sql' now configures Harper's SQL engine. Redeploy that application under a different name and remove the 'sql' entry; until then the SQL engine settings cannot be configured.");
 }
 /**
  * Updates the in memory flattened config object. Does not update the config file.
@@ -648,7 +758,7 @@ function updateConfigObject(param, value) {
         // This is here to allow unit tests to work when HDB is not installed.
         flatConfigObj = {};
     }
-    const configObjKey = CONFIG_PARAM_MAP[param.toLowerCase()];
+    const configObjKey = lookupConfigParam(param);
     if (configObjKey === undefined) {
         harper_logger_ts_1.default.trace(`Unable to update config object because config param '${param}' does not exist`);
         return;
@@ -691,6 +801,69 @@ function updateConfigObject(param, value) {
             node[leaf] = value;
     }
 }
+/**
+ * Canonical config param for an arg name, or `undefined` when the name is not a config param.
+ * `Object.hasOwn` because a bare lookup resolves inherited names: `constructor` yields an
+ * `Object.prototype` member that then fails `.split('_')` or `.toLowerCase()`.
+ */
+function lookupConfigParam(arg) {
+    if (typeof arg !== 'string')
+        return undefined;
+    const name = arg.toLowerCase();
+    return Object.hasOwn(CONFIG_PARAM_MAP, name) ? CONFIG_PARAM_MAP[name] : undefined;
+}
+const COMPONENT_PARAM_SUFFIXES = ['_package', '_port'];
+function suffixEscapedComponentName(arg) {
+    if (typeof arg !== 'string')
+        return undefined;
+    const suffix = COMPONENT_PARAM_SUFFIXES.find((candidate) => arg.endsWith(candidate));
+    if (suffix === undefined)
+        return undefined;
+    const component = arg.slice(0, -suffix.length);
+    return component === '' ? undefined : component;
+}
+/**
+ * Component entries (`my-component_package`, `my-component_port`) are operator-named, so they
+ * cannot be enumerated in CONFIG_PARAM_MAP and bypass it. This escape is the one way to write a
+ * root component entry without going through deploy_component, so a reserved name is excluded.
+ */
+function isSuffixEscapedParam(arg) {
+    const component = suffixEscapedComponentName(arg);
+    return component !== undefined && !(0, componentNames_ts_1.isReservedComponentName)(component);
+}
+function findReservedComponentParams(args) {
+    const reserved = [];
+    for (const arg in args) {
+        if (!Object.hasOwn(args, arg))
+            continue;
+        const component = suffixEscapedComponentName(arg);
+        if (component !== undefined && (0, componentNames_ts_1.isReservedComponentName)(component))
+            reserved.push(arg);
+    }
+    return reserved;
+}
+const MAX_REPORTED_UNRECOGNIZED = 10;
+/**
+ * Render unrecognized names for an error that also reaches the operations log: control characters
+ * are stripped so a name containing a newline cannot forge a log line, and the list is capped so a
+ * body carrying thousands of unknown keys cannot produce an unbounded message.
+ */
+function describeUnrecognized(names) {
+    const shown = names
+        .slice(0, MAX_REPORTED_UNRECOGNIZED)
+        // eslint-disable-next-line no-control-regex
+        .map((name) => name.replace(/[\u0000-\u001f\u007f]/g, '?'));
+    const remaining = names.length - shown.length;
+    return remaining > 0 ? `${shown.join(', ')} (and ${remaining} more)` : shown.join(', ');
+}
+function findUnrecognizedParams(args) {
+    let unrecognized;
+    for (const arg in args) {
+        if (lookupConfigParam(arg) === undefined && !isSuffixEscapedParam(arg))
+            (unrecognized ??= []).push(arg);
+    }
+    return unrecognized ?? [];
+}
 /**
  * Updates and validates a config value in config file. Can also create a backup of config before updating.
  * @param param - the config value to update
@@ -741,7 +914,7 @@ function updateConfigValue(param, value, parsedArgs = undefined, createBackup =
             configParam = param;
         }
         else {
-            configParam = CONFIG_PARAM_MAP[param.toLowerCase()];
+            configParam = lookupConfigParam(param);
             if (configParam === undefined) {
                 throw (0, hdbError_ts_1.handleHDBError)(new Error(), `Unable to update config, unrecognized config parameter: ${param}`, commonErrors_ts_1.HTTP_STATUS_CODES.BAD_REQUEST, undefined, undefined, true);
             }
@@ -753,7 +926,7 @@ function updateConfigValue(param, value, parsedArgs = undefined, createBackup =
     else {
         // Loop through the user inputted args. Match them to a parameter in the default config file and update value.
         for (const arg in parsedArgs) {
-            let configParam = CONFIG_PARAM_MAP[arg.toLowerCase()];
+            let configParam = lookupConfigParam(arg);
             // If setting http.securePort to the same value as http.port, set http.port to null to avoid clashing ports
             if (configParam === CONFIG_PARAMS.HTTP_SECUREPORT &&
                 parsedArgs[arg] === flatConfigObj[CONFIG_PARAMS.HTTP_PORT]?.toString()) {
@@ -777,7 +950,7 @@ function updateConfigValue(param, value, parsedArgs = undefined, createBackup =
                     configDoc.setIn(['threads', 'count'], threadCount);
                 }
             }
-            if (!configParam && (arg.endsWith('_package') || arg.endsWith('_port'))) {
+            if (!configParam && isSuffixEscapedParam(arg)) {
                 configParam = arg;
             }
             if (configParam !== undefined) {
@@ -947,14 +1120,49 @@ function getConfiguration() {
     const configDoc = parseYamlDoc(configFilePath);
     return configDoc.toJSON();
 }
+// `set_configuration` is the one config writer that also fans out (`replicated: true`), so a value
+// accepted here lands on every peer at once and the next rolling restart takes the whole cluster
+// down together (harper-pro#558). Boot-time writers are deliberately not gated the same way: config
+// that already exists has to stay bootable, so it is recovered at the point of use instead
+// (server/threads/threadHeapMemory.ts).
+function assertThreadHeapMemoryStartable(configFields) {
+    for (const field in configFields) {
+        const configParam = CONFIG_PARAM_MAP[field.toLowerCase()];
+        let configured;
+        if (configParam === CONFIG_PARAMS.THREADS_MAXHEAPMEMORY)
+            configured = configFields[field];
+        else if (configParam === CONFIG_PARAMS.THREADS)
+            configured = readSectionHeapMemory(configFields[field]);
+        else
+            continue;
+        const value = castConfigValue(CONFIG_PARAMS.THREADS_MAXHEAPMEMORY, configured);
+        if (typeof value !== 'number' || (0, threadHeapMemory_ts_1.isStartableThreadHeapMemory)(value))
+            continue;
+        throw (0, hdbError_ts_1.handleHDBError)(new Error(), commonErrors_ts_1.HDB_ERROR_MSGS.CONFIG_VALIDATION(`'threads.maxHeapMemory' must be greater than or equal to ${hdbTerms.MIN_THREAD_HEAP_MEMORY_MB}`), commonErrors_ts_1.HTTP_STATUS_CODES.BAD_REQUEST, undefined, undefined, true);
+    }
+}
+// A whole `threads` section reaches the same config key, and `threads` canonicalizes to itself
+// rather than to `threads_count`. It arrives either as an object or as the JSON string
+// castConfigValue parses, and flattenConfig lowercases every key on the way back out, so the nested
+// name has to be matched the same way the top-level one is.
+function readSectionHeapMemory(section) {
+    const parsed = castConfigValue(CONFIG_PARAMS.THREADS, section);
+    if (!hdbUtils.isObject(parsed))
+        return undefined;
+    for (const key in parsed)
+        if (key.toLowerCase() === 'maxheapmemory')
+            return parsed[key];
+}
 /**
  * Set Configuration - this function sets new configuration
  * @param setConfigJson
 
  */
 async function setConfiguration(setConfigJson) {
+    // `hdb_auth_header` is the 4.x spelling of `hdbAuthHeader`, and `impersonate` is a generic
+    // operation-body field (server/operationsServer.ts): control fields, never config params.
     // eslint-disable-next-line no-unused-vars
-    const { operation, hdb_user, hdbAuthHeader, replicated, ...configFields } = setConfigJson;
+    const { operation, hdb_user, hdbAuthHeader, hdb_auth_header, impersonate, replicated, ...configFields } = setConfigJson;
     // Operation-control field, not a config param: enforce boolean (matching other
     // `replicated` surfaces, e.g. analyticsValidator) before any local write so a
     // malformed value like the string "false" — which is truthy — can't apply config
@@ -962,6 +1170,18 @@ async function setConfiguration(setConfigJson) {
     if (replicated !== undefined && typeof replicated !== 'boolean') {
         throw (0, hdbError_ts_1.handleHDBError)(new Error(), `'replicated' must be a boolean`, commonErrors_ts_1.HTTP_STATUS_CODES.BAD_REQUEST, undefined, undefined, true);
     }
+    const reservedComponentParams = findReservedComponentParams(configFields);
+    if (reservedComponentParams.length > 0) {
+        throw (0, hdbError_ts_1.handleHDBError)(new Error(), `Unable to update config, cannot configure a component whose name is reserved for Harper's own configuration section: ${describeUnrecognized(reservedComponentParams)}`, commonErrors_ts_1.HTTP_STATUS_CODES.BAD_REQUEST, undefined, undefined, true);
+    }
+    // Before any local write: the writer skips names it cannot resolve, so a request mixing
+    // recognized and unrecognized names would otherwise apply the recognized half and still report
+    // success.
+    const unrecognized = findUnrecognizedParams(configFields);
+    if (unrecognized.length > 0) {
+        throw (0, hdbError_ts_1.handleHDBError)(new Error(), `Unable to update config, unrecognized config parameter${unrecognized.length > 1 ? 's' : ''}: ${describeUnrecognized(unrecognized)}`, commonErrors_ts_1.HTTP_STATUS_CODES.BAD_REQUEST, undefined, undefined, true);
+    }
+    assertThreadHeapMemoryStartable(configFields);
     try {
         updateConfigValue(undefined, undefined, configFields, true);
         if (replicated) {
@@ -1043,9 +1263,16 @@ function applyRuntimeEnvVarConfig(configDoc, configFilePath, options = {}) {
         return;
     // Convert to JSON for processing
     const configObj = configDoc.toJSON();
+    let saveEnvConfigState;
+    let confirmEnvConfigState;
+    let commitEnvConfigState;
     try {
         // Apply env vars with source tracking and drift detection
-        (0, harperConfigEnvVars_ts_1.applyRuntimeEnvConfig)(configObj, rootPath, options);
+        ({
+            saveState: saveEnvConfigState,
+            confirmConfigWritten: confirmEnvConfigState,
+            commitState: commitEnvConfigState,
+        } = (0, harperConfigEnvVars_ts_1.prepareRuntimeEnvConfig)(configObj, rootPath, options));
         // If securePort was set to the same value as port, auto-null port to avoid clashing
         if (configObj.http?.port && configObj.http?.port === configObj.http?.securePort) {
             configObj.http.port = null;
@@ -1067,17 +1294,47 @@ function applyRuntimeEnvVarConfig(configDoc, configFilePath, options = {}) {
         harper_logger_ts_1.default.error(`Failed to apply runtime env config: ${error.message}`);
         throw error;
     }
-    // We're done here if no config file to write to
+    // Install has no config file yet and no process to keep alive, so its snapshot write stays
+    // mandatory - an install that never recorded originals should fail, not proceed.
     if (!configFilePath) {
+        commitEnvConfigState();
         return;
     }
+    // Every worker thread runs initConfig and derives the same merged config, so letting them all
+    // persist it means N threads racing over one pair of files for a result they already agree on.
+    // The main thread owns the on-disk copy; a worker runs on the in-memory one.
+    if (!node_worker_threads_1.isMainThread)
+        return;
     // Persist changes to file
     try {
         if (configDoc.errors?.length > 0) {
             throw (0, hdbError_ts_1.handleHDBError)(new Error(), `Error parsing harperdb-config.yaml: ${configDoc.errors}`, commonErrors_ts_1.HTTP_STATUS_CODES.INTERNAL_SERVER_ERROR);
         }
-        atomicWriteFile(configFilePath, String(configDoc));
-        harper_logger_ts_1.default.debug('Config file updated with runtime env var values');
+        // Stage, write the file, promote by rename: the confirmed state is the only record of the
+        // file's pre-env values, so no write an exhausted volume can refuse may stand between it and
+        // disk. See DESIGN.md, boot-path config persistence.
+        let stateStaged = false;
+        if (persistConfigDuringBoot(`${rootPath} env config state`, () => (stateStaged = saveEnvConfigState()))) {
+            let configPersisted = false;
+            let configRewritten = false;
+            try {
+                configPersisted = persistConfigDuringBoot(configFilePath, () => {
+                    configRewritten = atomicWriteFile(configFilePath, String(configDoc), { skipIfUnchanged: true });
+                });
+            }
+            finally {
+                if (!configPersisted && stateStaged)
+                    (0, harperConfigEnvVars_ts_1.discardConfigState)(rootPath);
+            }
+            if (configPersisted) {
+                if (stateStaged)
+                    confirmEnvConfigState();
+                // Distinguished, because this is the line that answers "did something rewrite my config?"
+                harper_logger_ts_1.default.debug(configRewritten
+                    ? 'Config file updated with runtime env var values'
+                    : 'Config file already matched the runtime env var values');
+            }
+        }
     }
     catch (error) {
         harper_logger_ts_1.default.error(`Failed to write config file after applying runtime env vars: ${error.message}`);