@harperfast/harper 5.2.9 → 5.3.0-alpha.1

package/dist/utility/watchPath.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalizeWatchPath = canonicalizeWatchPath;
+exports.resolveWatchTarget = resolveWatchTarget;
+exports._resetForTests = _resetForTests;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const harper_logger_ts_1 = require("./logging/harper_logger.js");
+const watchPathLogger = (0, harper_logger_ts_1.loggerWithTag)('watcher');
+let canonicalizationWarned = false;
+/**
+ * Canonicalize an absolute path before it is handed to a native file watch (`fs.watch`, directly or
+ * through chokidar).
+ *
+ * libuv's Windows fs-event callback rebuilds each event's absolute path, expands it with
+ * `GetLongPathNameW`, and then asserts the expansion still starts with the directory it stored when
+ * the watch was armed. An 8.3 short directory (`C:\Users\RUNNER~1\...`) never survives that
+ * comparison, and the assertion aborts the process rather than failing the watch, so a short path
+ * reaching a native watch takes down the whole server (harper#2234).
+ *
+ * Every Windows path is resolved rather than only the ones that look short: `GetLongPathNameW`'s
+ * documentation is explicit that a short name need not contain a tilde, and NTFS allows an
+ * explicitly assigned one, so any spelling test would leave the abort reachable. `realpathSync` is
+ * not a substitute for the `.native` variant — it resolves symlinks but leaves 8.3 names intact.
+ *
+ * Returns `undefined` when the long form cannot be established, because a path we cannot prove is
+ * expanded is exactly the one that must never reach a native watch.
+ */
+function canonicalizeWatchPath(watchPath, platform = process.platform) {
+    if (platform !== 'win32')
+        return watchPath;
+    try {
+        return node_fs_1.realpathSync.native(watchPath);
+    }
+    catch (error) {
+        if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'ENOENT')
+            return undefined;
+        // libuv stores only the parent directory of a file target and compares only that prefix, so a
+        // leaf that does not exist yet — a config file whose watcher is armed during the install window
+        // — still yields a watch path that cannot trip the assertion.
+        try {
+            return (0, node_path_1.join)(node_fs_1.realpathSync.native((0, node_path_1.dirname)(watchPath)), (0, node_path_1.basename)(watchPath));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * Watch target for a chokidar/`fs.watch` call: the canonical path, or the original path with
+ * `mustPoll`, which callers turn into their polling options. Polling stats the file instead of
+ * arming a native watch, so it cannot reach the abort.
+ */
+function resolveWatchTarget(watchPath) {
+    const canonical = canonicalizeWatchPath(watchPath);
+    if (canonical !== undefined)
+        return { path: canonical, mustPoll: false };
+    if (!canonicalizationWarned) {
+        canonicalizationWarned = true;
+        watchPathLogger.warn?.(`Could not resolve the long-path form of ${watchPath}. Falling back to polling-based watching for ` +
+            'affected watchers, because handing a Windows 8.3 short path to a native watch aborts the process.');
+    }
+    return { path: watchPath, mustPoll: true };
+}
+function _resetForTests() {
+    canonicalizationWarned = false;
+}
+//# sourceMappingURL=watchPath.js.map

package/dist/utility/watchPath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchPath.js","sourceRoot":"","sources":["../../utility/watchPath.ts"],"names":[],"mappings":";;AAyBA,sDAeC;AAOD,gDAWC;AAED,wCAEC;AA9DD,qCAAuC;AACvC,yCAAoD;AACpD,iEAA2D;AAE3D,MAAM,eAAe,GAAG,IAAA,gCAAa,EAAC,SAAS,CAAC,CAAC;AACjD,IAAI,sBAAsB,GAAG,KAAK,CAAC;AAEnC;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,qBAAqB,CAAC,SAAiB,EAAE,WAAmB,OAAO,CAAC,QAAQ;IAC3F,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC;QACJ,OAAO,sBAAY,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC3G,8FAA8F;QAC9F,gGAAgG;QAChG,8DAA8D;QAC9D,IAAI,CAAC;YACJ,OAAO,IAAA,gBAAI,EAAC,sBAAY,CAAC,MAAM,CAAC,IAAA,mBAAO,EAAC,SAAS,CAAC,CAAC,EAAE,IAAA,oBAAQ,EAAC,SAAS,CAAC,CAAC,CAAC;QAC3E,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,SAAS,CAAC;QAClB,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,SAAiB;IACnD,MAAM,SAAS,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;IACnD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACzE,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC7B,sBAAsB,GAAG,IAAI,CAAC;QAC9B,eAAe,CAAC,IAAI,EAAE,CACrB,2CAA2C,SAAS,+CAA+C;YAClG,mGAAmG,CACpG,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED,SAAgB,cAAc;IAC7B,sBAAsB,GAAG,KAAK,CAAC;AAChC,CAAC"}

package/dist/utility/watcherFallback.d.ts

@@ -1,3 +1,4 @@
+import { type ChokidarOptions, type FSWatcher } from 'chokidar';
 /**
  * Returns `true` if the chokidar error indicates the OS-level watcher pool is
  * exhausted (inotify watches on Linux, open file descriptors on macOS/Linux).
@@ -34,3 +35,88 @@ export declare const DIRECTORY_POLLING_FALLBACK_OPTIONS: {
  */
 export declare function warnWatcherFallback(watchedPath: string): void;
 export declare function _resetForTests(): void;
+/**
+ * Returns `true` for the asynchronous "the watched path went away" error raised
+ * by Node's `fs.FSWatcher` — on Windows, `EPERM: operation not permitted, watch`
+ * (errno -4048) when a watched directory is removed or swapped out. Unlike
+ * {@link isWatcherExhaustionError} there is nothing to degrade to: polling a
+ * path that no longer exists only burns CPU.
+ *
+ * All three conditions are load-bearing, because whatever this claims is
+ * swallowed process-wide:
+ *
+ *   - `syscall === 'watch'` is only ever set by fs watch handles.
+ *   - `EPERM` only. An async `ENOENT` from a watch handle has never been
+ *     observed, whereas a *synchronous* one is the ordinary "watch a path that
+ *     isn't there" misconfiguration, which must stay fatal.
+ *   - no `path`. Node populates `path` on the error it throws out of
+ *     `fs.watch()` and leaves it absent on the one it delivers to the handle,
+ *     so without this a raw `fs.watch(missingPath)` reaching the guard would be
+ *     mistaken for a benign lost watch and swallowed.
+ */
+export declare function isLostNativeWatchError(error: unknown): boolean;
+/**
+ * If `error` is a lost native watch error, mark it handled, log it, and report
+ * that it has been claimed. Exported so the per-watcher error routes can give it
+ * the same benign treatment on the day chokidar does deliver it to the wrapper
+ * (its polling and `persistent: true` branches already would).
+ */
+export declare function claimLostNativeWatchError(error: unknown): boolean;
+/**
+ * Idempotently install the process-level listener that supplies the 'error'
+ * handler chokidar omits for non-persistent watchers. Called by
+ * {@link guardedWatch} so no watcher call site can forget it.
+ */
+export declare function installLostNativeWatchGuard(): void;
+/**
+ * `chokidar.watch()` with the lost-native-watch guard installed. Every Harper
+ * chokidar watcher must go through this — a raw `chokidar.watch(..., { persistent: false })`
+ * can take down the thread the first time its path is deleted.
+ */
+export declare function guardedWatch(paths: string | string[], options?: ChokidarOptions): FSWatcher;
+export declare function _lostNativeWatchCountForTests(): number;
+export declare class PartialReadRetry {
+    #private;
+    constructor(filePath: string);
+    /** False once the budget is spent, so the caller can fall back to its own error handling. */
+    schedule(reread: () => void): boolean;
+    /** A usable read arrived, so any re-read still armed for the previous one would duplicate it. */
+    settled(): void;
+    /**
+     * The budget is spent. Distinct from `settled()` in that the report stands — the file has not
+     * recovered, and it is shared with every other watcher of it. The budget itself is restored,
+     * because the next event may be the repair, and that repair can be observed mid-write too.
+     * Returns whether this give-up was the one reported.
+     */
+    gaveUp(error?: unknown): boolean;
+    /** Terminal: the watcher is closing, so nothing may re-arm the re-read or report on it. */
+    cancel(): void;
+}
+/**
+ * ENOENT is excluded not because it cannot be transient, but because it already has an answer:
+ * `OptionsWatcher` routes it to `remove` (env-only fallback at boot, then removal), and
+ * `RootConfigWatcher` keeps its last config rather than tearing down core features on a file
+ * that may just be mid-replace. Re-reading would only delay a decision already made.
+ */
+export declare function isPartialReadError(error: unknown): boolean;
+/**
+ * A watcher that exhausts its re-read budget serves stale config from then on, so the give-up
+ * has to be visible — otherwise the only symptom is a config change that silently did nothing.
+ * Warned once per file: every root-config scope watches the same one and would otherwise report
+ * a single bad file once each, on every event.
+ */
+export declare function warnPartialReadGaveUp(filePath: string, error?: unknown): boolean;
+/**
+ * The kind and position of a failed config read, never its content: a YAML parse error's message
+ * quotes the offending source lines, and these files hold credentials.
+ */
+export declare function describeReadFailure(error: unknown): string;
+/** Test-only: whether a give-up warning for this file is currently suppressed as a duplicate. */
+export declare function isPartialReadWarned(filePath: string): boolean;
+/** Test-only: forget that this file was reported, so a suite can start from a known state. */
+export declare function clearPartialReadWarning(filePath: string): void;
+/**
+ * A listener that throws while applying new config is a bug in that listener, not evidence the
+ * file was half-written — the watcher's own state is already updated, so it keeps going.
+ */
+export declare function warnWatcherListenerError(filePath: string, error: unknown): void;

package/dist/utility/watcherFallback.js

@@ -5,15 +5,31 @@
 // (EMFILE), native chokidar watchers emit an error and stop firing change
 // events. Polling-based watching doesn't consume inotify handles or per-watcher
 // file descriptors, so we fall back to it once and warn — see harper#488.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DIRECTORY_POLLING_FALLBACK_OPTIONS = exports.POLLING_FALLBACK_OPTIONS = void 0;
+exports.PartialReadRetry = exports.DIRECTORY_POLLING_FALLBACK_OPTIONS = exports.POLLING_FALLBACK_OPTIONS = void 0;
 exports.isWatcherExhaustionError = isWatcherExhaustionError;
 exports.warnWatcherFallback = warnWatcherFallback;
 exports._resetForTests = _resetForTests;
+exports.isLostNativeWatchError = isLostNativeWatchError;
+exports.claimLostNativeWatchError = claimLostNativeWatchError;
+exports.installLostNativeWatchGuard = installLostNativeWatchGuard;
+exports.guardedWatch = guardedWatch;
+exports._lostNativeWatchCountForTests = _lostNativeWatchCountForTests;
+exports.isPartialReadError = isPartialReadError;
+exports.warnPartialReadGaveUp = warnPartialReadGaveUp;
+exports.describeReadFailure = describeReadFailure;
+exports.isPartialReadWarned = isPartialReadWarned;
+exports.clearPartialReadWarning = clearPartialReadWarning;
+exports.warnWatcherListenerError = warnWatcherListenerError;
+const chokidar_1 = __importDefault(require("chokidar"));
 const harper_logger_ts_1 = require("./logging/harper_logger.js");
 // One-time process-wide warning so a thundering herd of failing watchers doesn't
 // produce hundreds of identical log lines.
 let exhaustionWarned = false;
+const partialReadWarned = new Set();
 const fallbackLogger = (0, harper_logger_ts_1.loggerWithTag)('watcher');
 /**
  * Returns `true` if the chokidar error indicates the OS-level watcher pool is
@@ -69,5 +85,266 @@ function warnWatcherFallback(watchedPath) {
 // Test-only hook to reset the one-time warning gate between cases.
 function _resetForTests() {
     exhaustionWarned = false;
+    lostNativeWatchCount = 0;
+    lostNativeWatchWarnThreshold = 1;
+    // Also drop the process listener, so a case that installed the guard can't leave one
+    // attached to the test runner's process for every case that follows.
+    process.removeListener('uncaughtException', handleUncaughtException);
+    lostNativeWatchGuardInstalled = false;
+}
+// ---------------------------------------------------------------------------
+// Lost native watch (predominantly Windows)
+// ---------------------------------------------------------------------------
+//
+// Every Harper watcher runs `persistent: false`, which is the one chokidar
+// branch that never attaches an 'error' listener to the underlying Node
+// `fs.FSWatcher` (chokidar `handler.js`, `setFsWatchListener`; still so at
+// 5.0.0). Its `errHandler` covers only a synchronous throw out of `fs.watch()`
+// — the ENOSPC/EMFILE route above. An asynchronous failure is emitted on a
+// handle with no listener, so Node makes it an uncaughtException without it
+// ever reaching chokidar; `.on('error')` on the wrapper we hold cannot see it.
+// The process is therefore the only place it is observable, which is what
+// `installLostNativeWatchGuard()` uses.
+/**
+ * Returns `true` for the asynchronous "the watched path went away" error raised
+ * by Node's `fs.FSWatcher` — on Windows, `EPERM: operation not permitted, watch`
+ * (errno -4048) when a watched directory is removed or swapped out. Unlike
+ * {@link isWatcherExhaustionError} there is nothing to degrade to: polling a
+ * path that no longer exists only burns CPU.
+ *
+ * All three conditions are load-bearing, because whatever this claims is
+ * swallowed process-wide:
+ *
+ *   - `syscall === 'watch'` is only ever set by fs watch handles.
+ *   - `EPERM` only. An async `ENOENT` from a watch handle has never been
+ *     observed, whereas a *synchronous* one is the ordinary "watch a path that
+ *     isn't there" misconfiguration, which must stay fatal.
+ *   - no `path`. Node populates `path` on the error it throws out of
+ *     `fs.watch()` and leaves it absent on the one it delivers to the handle,
+ *     so without this a raw `fs.watch(missingPath)` reaching the guard would be
+ *     mistaken for a benign lost watch and swallowed.
+ */
+function isLostNativeWatchError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const { code, syscall, path } = error;
+    return syscall === 'watch' && code === 'EPERM' && path == null;
+}
+let lostNativeWatchCount = 0;
+let lostNativeWatchWarnThreshold = 1;
+/**
+ * If `error` is a lost native watch error, mark it handled, log it, and report
+ * that it has been claimed. Exported so the per-watcher error routes can give it
+ * the same benign treatment on the day chokidar does deliver it to the wrapper
+ * (its polling and `persistent: true` branches already would).
+ */
+function claimLostNativeWatchError(error) {
+    if (!isLostNativeWatchError(error))
+        return false;
+    const claimed = error;
+    // Counting one instance twice would trip the warn threshold early.
+    if (claimed.isHandled)
+        return true;
+    lostNativeWatchCount++;
+    // The claim is the classification above; the bookkeeping that follows must not be able to
+    // undo it. A frozen error (`isHandled` unassignable) or a throwing logger would otherwise
+    // make a failure just classified as benign fatal — here, or in a caller's 'error' route.
+    try {
+        fallbackLogger.trace?.(`Lost native file watch handle (occurrence ${lostNativeWatchCount}):`, error);
+        // A subsystem that has silently stopped being watched is what an operator needs to see, and
+        // the default level is `warn`, so trace alone would hide every occurrence after the first.
+        // Warning at each decade keeps a delete storm bounded without ever going fully silent.
+        if (lostNativeWatchCount >= lostNativeWatchWarnThreshold) {
+            lostNativeWatchWarnThreshold *= 10;
+            fallbackLogger.warn?.(`A native file watch handle failed asynchronously (EPERM, syscall=watch) and was suppressed to ` +
+                `keep the thread alive; occurrence ${lostNativeWatchCount}. Node reports no path for this error, ` +
+                `so it cannot be attributed to a specific watcher — whatever was watching that path has stopped ` +
+                `reporting changes until it is re-established. On Windows this is usually a watched directory ` +
+                `being deleted or replaced (a component redeploy, a package install, a test teardown). If file ` +
+                `changes stop being picked up somewhere, this is why. Subsequent occurrences log at trace, with ` +
+                `a warning at each tenfold increase.`);
+        }
+        // Last: threadServer.js and socketRouter.ts skip errors already marked handled, so failing
+        // to mark one costs only a duplicate log line.
+        claimed.isHandled = true;
+    }
+    catch {
+        // Marked or not, logged or not, the error stays claimed.
+    }
+    return true;
+}
+let lostNativeWatchGuardInstalled = false;
+function handleUncaughtException(error) {
+    let claimed = false;
+    try {
+        claimed = claimLostNativeWatchError(error);
+    }
+    catch {
+        // Classification is all that can still throw (a property getter that does), and a throw
+        // from inside an 'uncaughtException' listener would replace Node's report with it and
+        // exit 7. An error that cannot be classified is not ours to claim.
+        claimed = false;
+    }
+    if (claimed)
+        return;
+    // Node suppresses its default fatal handling as soon as *any* 'uncaughtException' listener
+    // exists, so being the only listener would turn unrelated crashes into silent hangs.
+    if (process.listenerCount('uncaughtException') > 1)
+        return;
+    process.removeListener('uncaughtException', handleUncaughtException);
+    // A process that somehow survives re-arms on its next guardedWatch() rather than running
+    // unguarded thereafter.
+    lostNativeWatchGuardInstalled = false;
+    // nextTick, not a throw from inside the handler: that keeps Node's report and exit code 1.
+    process.nextTick(() => {
+        throw error;
+    });
+}
+/**
+ * Idempotently install the process-level listener that supplies the 'error'
+ * handler chokidar omits for non-persistent watchers. Called by
+ * {@link guardedWatch} so no watcher call site can forget it.
+ */
+function installLostNativeWatchGuard() {
+    if (lostNativeWatchGuardInstalled)
+        return;
+    lostNativeWatchGuardInstalled = true;
+    // prepend, not append: threadServer.js already has an 'uncaughtException'
+    // listener, and the `isHandled` mark above only suppresses its log line if
+    // this guard runs first.
+    process.prependListener('uncaughtException', handleUncaughtException);
+}
+/**
+ * `chokidar.watch()` with the lost-native-watch guard installed. Every Harper
+ * chokidar watcher must go through this — a raw `chokidar.watch(..., { persistent: false })`
+ * can take down the thread the first time its path is deleted.
+ */
+function guardedWatch(paths, options) {
+    installLostNativeWatchGuard();
+    // Deliberately a property access on the default export rather than a named `watch` import:
+    // unitTests/server/threads/watchDirFallback.test.js drives the reopen-on-exhaustion chain by
+    // swapping `chokidar.default.watch`, and a named import binds past that seam.
+    return chokidar_1.default.watch(paths, options);
+}
+// Test-only: number of lost native watch errors claimed so far.
+function _lostNativeWatchCountForTests() {
+    return lostNativeWatchCount;
+}
+/**
+ * A config file replaced in place (truncate, then write) can be read back empty or
+ * half-written, and chokidar may emit nothing further for that write — so a watcher that
+ * simply drops the unusable read would serve stale config until something else touched the
+ * file. Re-read on a later turn instead, bounded so a genuinely empty or corrupt file cannot
+ * spin. Callers read synchronously, so the descriptor still never outlives a single turn.
+ */
+const PARTIAL_READ_REREAD_DELAY_MS = 20;
+const PARTIAL_READ_MAX_REREADS = 10;
+class PartialReadRetry {
+    #filePath;
+    #timer;
+    #remaining = PARTIAL_READ_MAX_REREADS;
+    #closed = false;
+    constructor(filePath) {
+        this.#filePath = filePath;
+    }
+    /** False once the budget is spent, so the caller can fall back to its own error handling. */
+    schedule(reread) {
+        if (this.#closed)
+            return false;
+        if (this.#timer)
+            return true;
+        if (this.#remaining <= 0)
+            return false;
+        this.#remaining--;
+        this.#timer = setTimeout(() => {
+            this.#timer = undefined;
+            reread();
+        }, PARTIAL_READ_REREAD_DELAY_MS);
+        this.#timer.unref?.();
+        return true;
+    }
+    /** A usable read arrived, so any re-read still armed for the previous one would duplicate it. */
+    settled() {
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#remaining = PARTIAL_READ_MAX_REREADS;
+        // The file recovered, so the next time it breaks is a new incident and has to be reported
+        // again rather than silenced by the warning it emitted weeks ago.
+        partialReadWarned.delete(this.#filePath);
+    }
+    /**
+     * The budget is spent. Distinct from `settled()` in that the report stands — the file has not
+     * recovered, and it is shared with every other watcher of it. The budget itself is restored,
+     * because the next event may be the repair, and that repair can be observed mid-write too.
+     * Returns whether this give-up was the one reported.
+     */
+    gaveUp(error) {
+        if (this.#closed)
+            return false;
+        this.#remaining = PARTIAL_READ_MAX_REREADS;
+        return warnPartialReadGaveUp(this.#filePath, error);
+    }
+    /** Terminal: the watcher is closing, so nothing may re-arm the re-read or report on it. */
+    cancel() {
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#closed = true;
+    }
+}
+exports.PartialReadRetry = PartialReadRetry;
+/**
+ * ENOENT is excluded not because it cannot be transient, but because it already has an answer:
+ * `OptionsWatcher` routes it to `remove` (env-only fallback at boot, then removal), and
+ * `RootConfigWatcher` keeps its last config rather than tearing down core features on a file
+ * that may just be mid-replace. Re-reading would only delay a decision already made.
+ */
+function isPartialReadError(error) {
+    return !(typeof error === 'object' && error !== null && error.code === 'ENOENT');
+}
+/**
+ * A watcher that exhausts its re-read budget serves stale config from then on, so the give-up
+ * has to be visible — otherwise the only symptom is a config change that silently did nothing.
+ * Warned once per file: every root-config scope watches the same one and would otherwise report
+ * a single bad file once each, on every event.
+ */
+function warnPartialReadGaveUp(filePath, error) {
+    if (partialReadWarned.has(filePath))
+        return false;
+    partialReadWarned.add(filePath);
+    // The cause matters to whoever has to fix it: a file that never parses is a typo to correct,
+    // while one that reads empty is a writer that never finished. Report the kind and position
+    // only — a YAML parse error's message quotes the offending source, and this file holds
+    // credentials.
+    const cause = error ? `: ${describeReadFailure(error)}` : ' that were empty or incomplete';
+    fallbackLogger.warn(`Gave up re-reading ${filePath} after ${PARTIAL_READ_MAX_REREADS} unusable reads${cause}`);
+    return true;
+}
+/**
+ * The kind and position of a failed config read, never its content: a YAML parse error's message
+ * quotes the offending source lines, and these files hold credentials.
+ */
+function describeReadFailure(error) {
+    if (typeof error !== 'object' || error === null)
+        return 'unusable';
+    const { name, code, linePos } = error;
+    const at = linePos?.[0] ? ` at line ${linePos[0].line}, column ${linePos[0].col}` : '';
+    return `${code ?? name ?? 'unusable'}${at}`;
+}
+/** Test-only: whether a give-up warning for this file is currently suppressed as a duplicate. */
+function isPartialReadWarned(filePath) {
+    return partialReadWarned.has(filePath);
+}
+/** Test-only: forget that this file was reported, so a suite can start from a known state. */
+function clearPartialReadWarning(filePath) {
+    partialReadWarned.delete(filePath);
+}
+/**
+ * A listener that throws while applying new config is a bug in that listener, not evidence the
+ * file was half-written — the watcher's own state is already updated, so it keeps going.
+ */
+function warnWatcherListenerError(filePath, error) {
+    fallbackLogger.warn(`Error applying a configuration change from ${filePath}`, error);
 }
 //# sourceMappingURL=watcherFallback.js.map

package/dist/utility/watcherFallback.js.map

@@ -1 +1 @@
-{"version":3,"file":"watcherFallback.js","sourceRoot":"","sources":["../../utility/watcherFallback.ts"],"names":[],"mappings":";AAAA,0CAA0C;AAC1C,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,gFAAgF;AAChF,0EAA0E;;;AAc1E,4DAIC;AAiCD,kDAYC;AAGD,wCAEC;AAlED,iEAA2D;AAE3D,iFAAiF;AACjF,2CAA2C;AAC3C,IAAI,gBAAgB,GAAG,KAAK,CAAC;AAE7B,MAAM,cAAc,GAAG,IAAA,gCAAa,EAAC,SAAS,CAAC,CAAC;AAEhD;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,KAAc;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,IAAI,GAAI,KAA2B,CAAC,IAAI,CAAC;IAC/C,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,CAAC;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACU,QAAA,wBAAwB,GAAG;IACvC,UAAU,EAAE,IAAI;IAChB,QAAQ,EAAE,IAAI;IACd,cAAc,EAAE,IAAI;CACX,CAAC;AAEX;;;;;GAKG;AACU,QAAA,kCAAkC,GAAG;IACjD,UAAU,EAAE,IAAI;IAChB,QAAQ,EAAE,IAAI;IACd,cAAc,EAAE,IAAI;CACX,CAAC;AAEX;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,WAAmB;IACtD,IAAI,gBAAgB;QAAE,OAAO;IAC7B,gBAAgB,GAAG,IAAI,CAAC;IACxB,cAAc,CAAC,IAAI,EAAE,CACpB,8CAA8C,WAAW,IAAI;QAC5D,iEAAiE;QACjE,6EAA6E;QAC7E,4CAA4C;QAC5C,+DAA+D;QAC/D,sDAAsD;QACtD,kEAAkE,CACnE,CAAC;AACH,CAAC;AAED,mEAAmE;AACnE,SAAgB,cAAc;IAC7B,gBAAgB,GAAG,KAAK,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"watcherFallback.js","sourceRoot":"","sources":["../../utility/watcherFallback.ts"],"names":[],"mappings":";AAAA,0CAA0C;AAC1C,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,gFAAgF;AAChF,0EAA0E;;;;;;AAgB1E,4DAIC;AAiCD,kDAYC;AAGD,wCAQC;AAmCD,wDAIC;AAWD,8DAiCC;AAiCD,kEAOC;AAOD,oCAMC;AAGD,sEAEC;AAwED,gDAEC;AAQD,sDAUC;AAMD,kDAKC;AAGD,kDAEC;AAGD,0DAEC;AAMD,4DAEC;AAhVD,wDAA0E;AAC1E,iEAA2D;AAE3D,iFAAiF;AACjF,2CAA2C;AAC3C,IAAI,gBAAgB,GAAG,KAAK,CAAC;AAC7B,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;AAE5C,MAAM,cAAc,GAAG,IAAA,gCAAa,EAAC,SAAS,CAAC,CAAC;AAEhD;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,KAAc;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,IAAI,GAAI,KAA2B,CAAC,IAAI,CAAC;IAC/C,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,CAAC;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACU,QAAA,wBAAwB,GAAG;IACvC,UAAU,EAAE,IAAI;IAChB,QAAQ,EAAE,IAAI;IACd,cAAc,EAAE,IAAI;CACX,CAAC;AAEX;;;;;GAKG;AACU,QAAA,kCAAkC,GAAG;IACjD,UAAU,EAAE,IAAI;IAChB,QAAQ,EAAE,IAAI;IACd,cAAc,EAAE,IAAI;CACX,CAAC;AAEX;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,WAAmB;IACtD,IAAI,gBAAgB;QAAE,OAAO;IAC7B,gBAAgB,GAAG,IAAI,CAAC;IACxB,cAAc,CAAC,IAAI,EAAE,CACpB,8CAA8C,WAAW,IAAI;QAC5D,iEAAiE;QACjE,6EAA6E;QAC7E,4CAA4C;QAC5C,+DAA+D;QAC/D,sDAAsD;QACtD,kEAAkE,CACnE,CAAC;AACH,CAAC;AAED,mEAAmE;AACnE,SAAgB,cAAc;IAC7B,gBAAgB,GAAG,KAAK,CAAC;IACzB,oBAAoB,GAAG,CAAC,CAAC;IACzB,4BAA4B,GAAG,CAAC,CAAC;IACjC,qFAAqF;IACrF,qEAAqE;IACrE,OAAO,CAAC,cAAc,CAAC,mBAAmB,EAAE,uBAAuB,CAAC,CAAC;IACrE,6BAA6B,GAAG,KAAK,CAAC;AACvC,CAAC;AAED,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAC9E,EAAE;AACF,2EAA2E;AAC3E,wEAAwE;AACxE,2EAA2E;AAC3E,+EAA+E;AAC/E,2EAA2E;AAC3E,4EAA4E;AAC5E,+EAA+E;AAC/E,0EAA0E;AAC1E,wCAAwC;AAExC;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,sBAAsB,CAAC,KAAc;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,KAA8D,CAAC;IAC/F,OAAO,OAAO,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,IAAI,IAAI,CAAC;AAChE,CAAC;AAED,IAAI,oBAAoB,GAAG,CAAC,CAAC;AAC7B,IAAI,4BAA4B,GAAG,CAAC,CAAC;AAErC;;;;;GAKG;AACH,SAAgB,yBAAyB,CAAC,KAAc;IACvD,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACjD,MAAM,OAAO,GAAG,KAAgC,CAAC;IACjD,mEAAmE;IACnE,IAAI,OAAO,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACnC,oBAAoB,EAAE,CAAC;IACvB,0FAA0F;IAC1F,0FAA0F;IAC1F,yFAAyF;IACzF,IAAI,CAAC;QACJ,cAAc,CAAC,KAAK,EAAE,CAAC,6CAA6C,oBAAoB,IAAI,EAAE,KAAK,CAAC,CAAC;QACrG,4FAA4F;QAC5F,2FAA2F;QAC3F,uFAAuF;QACvF,IAAI,oBAAoB,IAAI,4BAA4B,EAAE,CAAC;YAC1D,4BAA4B,IAAI,EAAE,CAAC;YACnC,cAAc,CAAC,IAAI,EAAE,CACpB,gGAAgG;gBAC/F,qCAAqC,oBAAoB,yCAAyC;gBAClG,iGAAiG;gBACjG,+FAA+F;gBAC/F,gGAAgG;gBAChG,iGAAiG;gBACjG,qCAAqC,CACtC,CAAC;QACH,CAAC;QACD,2FAA2F;QAC3F,+CAA+C;QAC/C,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACR,yDAAyD;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED,IAAI,6BAA6B,GAAG,KAAK,CAAC;AAE1C,SAAS,uBAAuB,CAAC,KAAc;IAC9C,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACJ,OAAO,GAAG,yBAAyB,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACR,wFAAwF;QACxF,sFAAsF;QACtF,mEAAmE;QACnE,OAAO,GAAG,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,OAAO;QAAE,OAAO;IACpB,2FAA2F;IAC3F,qFAAqF;IACrF,IAAI,OAAO,CAAC,aAAa,CAAC,mBAAmB,CAAC,GAAG,CAAC;QAAE,OAAO;IAC3D,OAAO,CAAC,cAAc,CAAC,mBAAmB,EAAE,uBAAuB,CAAC,CAAC;IACrE,yFAAyF;IACzF,wBAAwB;IACxB,6BAA6B,GAAG,KAAK,CAAC;IACtC,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE;QACrB,MAAM,KAAK,CAAC;IACb,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,2BAA2B;IAC1C,IAAI,6BAA6B;QAAE,OAAO;IAC1C,6BAA6B,GAAG,IAAI,CAAC;IACrC,0EAA0E;IAC1E,2EAA2E;IAC3E,yBAAyB;IACzB,OAAO,CAAC,eAAe,CAAC,mBAAmB,EAAE,uBAAuB,CAAC,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAAC,KAAwB,EAAE,OAAyB;IAC/E,2BAA2B,EAAE,CAAC;IAC9B,2FAA2F;IAC3F,6FAA6F;IAC7F,8EAA8E;IAC9E,OAAO,kBAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC;AAED,gEAAgE;AAChE,SAAgB,6BAA6B;IAC5C,OAAO,oBAAoB,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,4BAA4B,GAAG,EAAE,CAAC;AACxC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAEpC,MAAa,gBAAgB;IAC5B,SAAS,CAAS;IAClB,MAAM,CAAiC;IACvC,UAAU,GAAW,wBAAwB,CAAC;IAC9C,OAAO,GAAG,KAAK,CAAC;IAEhB,YAAY,QAAgB;QAC3B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,6FAA6F;IAC7F,QAAQ,CAAC,MAAkB;QAC1B,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC/B,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAC7B,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE;YAC7B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YACxB,MAAM,EAAE,CAAC;QACV,CAAC,EAAE,4BAA4B,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,iGAAiG;IACjG,OAAO;QACN,IAAI,IAAI,CAAC,MAAM;YAAE,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,wBAAwB,CAAC;QAC3C,0FAA0F;QAC1F,kEAAkE;QAClE,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,KAAe;QACrB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,wBAAwB,CAAC;QAC3C,OAAO,qBAAqB,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACrD,CAAC;IAED,2FAA2F;IAC3F,MAAM;QACL,IAAI,IAAI,CAAC,MAAM;YAAE,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACrB,CAAC;CACD;AApDD,4CAoDC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,KAAc;IAChD,OAAO,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAA2B,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;AACzG,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CAAC,QAAgB,EAAE,KAAe;IACtE,IAAI,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAChC,6FAA6F;IAC7F,2FAA2F;IAC3F,uFAAuF;IACvF,eAAe;IACf,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,gCAAgC,CAAC;IAC3F,cAAc,CAAC,IAAI,CAAC,sBAAsB,QAAQ,UAAU,wBAAwB,kBAAkB,KAAK,EAAE,CAAC,CAAC;IAC/G,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,KAAc;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IACnE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAoF,CAAC;IACrH,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,YAAY,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACvF,OAAO,GAAG,IAAI,IAAI,IAAI,IAAI,UAAU,GAAG,EAAE,EAAE,CAAC;AAC7C,CAAC;AAED,iGAAiG;AACjG,SAAgB,mBAAmB,CAAC,QAAgB;IACnD,OAAO,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED,8FAA8F;AAC9F,SAAgB,uBAAuB,CAAC,QAAgB;IACvD,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,QAAgB,EAAE,KAAc;IACxE,cAAc,CAAC,IAAI,CAAC,8CAA8C,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;AACtF,CAAC"}

package/dist/validation/configValidator.d.ts

@@ -1,5 +1,17 @@
 import Joi from 'joi';
+/**
+ * What `deploy_component` writes into a root-config entry, plus the deployment-level keys
+ * componentLoader reads off it — the shape of a `sql` application deployed before the name was
+ * reserved. Closed to new keys: nothing new may take this shape.
+ */
+export declare const LEGACY_SQL_APPLICATION_KEYS: string[];
+export declare function isLegacySqlApplicationEntry(value: unknown): boolean;
 export declare const routeConstraints: Joi.AlternativesSchema<any>;
+/**
+ * Validate a `models:` block on its own — the hot-reload path applies a watched file's block
+ * without the full boot validation, and must enforce the same schema boot does.
+ */
+export declare function validateModelsBlock(models: any): Joi.ValidationResult<any>;
 export declare function configValidator(configJson: any, skipFsValidation?: boolean): Joi.ValidationResult<any>;
 export declare const UDS_PATH_MAX_BYTES: number;
 /**