@harperfast/harper 5.2.10 → 5.3.0-alpha.1

package/utility/watcherFallback.ts

@@ -5,11 +5,13 @@
 // 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.
 
+import chokidar, { type ChokidarOptions, type FSWatcher } from 'chokidar';
 import { loggerWithTag } from './logging/harper_logger.ts';
 
 // 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<string>();
 
 const fallbackLogger = loggerWithTag('watcher');
 
@@ -71,4 +73,272 @@ export function warnWatcherFallback(watchedPath: string): void {
 // Test-only hook to reset the one-time warning gate between cases.
 export function _resetForTests(): void {
 	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.
+ */
+export function isLostNativeWatchError(error: unknown): boolean {
+	if (typeof error !== 'object' || error === null) return false;
+	const { code, syscall, path } = error as { code?: unknown; syscall?: unknown; path?: unknown };
+	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).
+ */
+export function claimLostNativeWatchError(error: unknown): boolean {
+	if (!isLostNativeWatchError(error)) return false;
+	const claimed = error as { isHandled?: boolean };
+	// 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: unknown): void {
+	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.
+ */
+export function installLostNativeWatchGuard(): void {
+	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.
+ */
+export function guardedWatch(paths: string | string[], options?: ChokidarOptions): FSWatcher {
+	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.watch(paths, options);
+}
+
+// Test-only: number of lost native watch errors claimed so far.
+export function _lostNativeWatchCountForTests(): number {
+	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;
+
+export class PartialReadRetry {
+	#filePath: string;
+	#timer?: ReturnType<typeof setTimeout>;
+	#remaining: number = PARTIAL_READ_MAX_REREADS;
+	#closed = false;
+
+	constructor(filePath: string) {
+		this.#filePath = filePath;
+	}
+
+	/** False once the budget is spent, so the caller can fall back to its own error handling. */
+	schedule(reread: () => void): boolean {
+		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?: unknown): boolean {
+		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;
+	}
+}
+
+/**
+ * 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 function isPartialReadError(error: unknown): boolean {
+	return !(typeof error === 'object' && error !== null && (error as { code?: string }).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.
+ */
+export function warnPartialReadGaveUp(filePath: string, error?: unknown): boolean {
+	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.
+ */
+export function describeReadFailure(error: unknown): string {
+	if (typeof error !== 'object' || error === null) return 'unusable';
+	const { name, code, linePos } = error as { name?: string; code?: string; linePos?: { line: number; col: number }[] };
+	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. */
+export function isPartialReadWarned(filePath: string): boolean {
+	return partialReadWarned.has(filePath);
+}
+
+/** Test-only: forget that this file was reported, so a suite can start from a known state. */
+export function clearPartialReadWarning(filePath: string) {
+	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.
+ */
+export function warnWatcherListenerError(filePath: string, error: unknown) {
+	fallbackLogger.warn(`Error applying a configuration change from ${filePath}`, error);
 }

package/validation/configValidator.ts

@@ -10,6 +10,7 @@ import * as hdbLogger from '../utility/logging/harper_logger.ts';
 import * as hdbUtils from '../utility/common_utils.ts';
 import * as hdbTerms from '../utility/hdbTerms.ts';
 import { getDomainSocketPathMaxBytes } from '../utility/domainSocket.ts';
+import { bareHostViolation } from '../utility/nodeIdentity.ts';
 import * as validator from './validationWrapper.ts';
 
 const DEFAULT_LOG_FOLDER = 'log';
@@ -29,6 +30,31 @@ const INVALID_RETENTION_VALUE_MSG =
 const VALID_ROTATION_DURATION_UNITS = ['D', 'd', 'H', 'h', 'M', 'm'];
 const UNDEFINED_OPS_API = 'rootPath config parameter is undefined';
 
+/**
+ * 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 const LEGACY_SQL_APPLICATION_KEYS = [
+	'package',
+	'files',
+	'path',
+	'install',
+	'credentials',
+	'loadComponent',
+	'urlPath',
+	'host',
+	'branchedDatabases',
+	'network',
+	'port',
+	'securePort',
+];
+
+export function isLegacySqlApplicationEntry(value: unknown): boolean {
+	if (typeof value !== 'object' || value === null) return false;
+	return LEGACY_SQL_APPLICATION_KEYS.some((key) => Object.hasOwn(value, key));
+}
+
 // Directory-path validation. The previous `([...]+)+$` nested quantifier
 // backtracked catastrophically (ReDoS), hanging the CLI at 100% CPU on any
 // value with a character outside its allow-list after a run of valid ones — a
@@ -52,6 +78,10 @@ const DIRECTORY_PATH_PATTERN = /^(?!\s*$)[^\x00-\x1f\x7f\x80-\x9f\u2028\u2029]+$
 const portConstraints = Joi.alternatives([number.min(0), string])
 	.optional()
 	.empty(null);
+// node.hostname / replication.hostname must be a bare host, not a URL (utility/nodeIdentity.ts).
+// `Joi.any` (not `string`) so validateBareHost reports a non-string with its own reason.
+const bareHostConstraints = Joi.any().custom(validateBareHost).optional().empty(null);
+const nodeUrlConstraints = string.custom(validateNodeUrl).optional().empty(null);
 // Controlled-flow ("directional") replication fields. A route's `replicates` is either a boolean
 // (full replication on/off) or an object describing per-direction flow; `sends`/`receives` and
 // `sendsTo`/`receivesFrom` are also accepted as top-level route keys (iterateRoutes normalizes both
@@ -102,6 +132,88 @@ export const routeConstraints = Joi.alternatives([
 	array.items(string),
 ]);
 
+// Models — `models:` block opts a deployment into the per-backend registry.
+// Per-backend shape is validated by a discriminated alternative on the
+// `backend` field. Phase 2 (#629) lands ollama; Phase 3 (#630) lands openai.
+//
+// `.unknown(false)` on each known backend's schema turns field-name typos
+// (`bakend: ollama`, `hsot: ...`) into boot-blocking validation errors.
+// Without it, Joi's top-level `allowUnknown: true` propagates and typos
+// silently survive into bootstrap. Unknown backend types (anything not in
+// the `switch` list) fall through to a permissive schema so future Harper
+// versions or third-party components can register their own backends
+// without core schema edits — `bootstrapModels` logs+skips at runtime.
+//
+// `requestTimeoutMs: min(1)` (not `min(0)`) so the meaning is unambiguous:
+// omit the field for "no timeout". `0` would validate but `composeSignal`
+// treats it as "no timeout" via `if (!timeoutMs)`, surprising a test that
+// sets 0 to mean "fail immediately".
+const commonEntryFields = {
+	model: string.optional(),
+	requestTimeoutMs: number.min(1).optional(),
+	// Ordered fallback group — other logical names tried, in order, after this one (#1326).
+	fallback: Joi.array().items(string).optional(),
+};
+const ollamaEntrySchema = Joi.object({
+	backend: string.valid('ollama').required(),
+	host: string.optional(),
+	...commonEntryFields,
+}).unknown(false);
+const openaiEntrySchema = Joi.object({
+	backend: string.valid('openai').required(),
+	// `apiKey` may be a literal secret or a `${ENV_VAR}` placeholder; both
+	// are syntactically strings. `bootstrap.ts` runs `expandEnvVarsDeep`
+	// before construction; the backend rejects unresolved placeholders
+	// with an explicit error pointing at the env-var name.
+	apiKey: string.required(),
+	baseUrl: string.optional(),
+	organization: string.optional(),
+	...commonEntryFields,
+}).unknown(false);
+const anthropicEntrySchema = Joi.object({
+	backend: string.valid('anthropic').required(),
+	// Same secret-handling posture as openai's `apiKey`.
+	apiKey: string.required(),
+	baseUrl: string.optional(),
+	...commonEntryFields,
+}).unknown(false);
+const bedrockEntrySchema = Joi.object({
+	backend: string.valid('bedrock').required(),
+	// AWS credentials resolve via the SDK chain (env / shared file / IAM
+	// roles for service accounts) — no apiKey field. `region` is
+	// effectively required (Bedrock is regional) but the backend can
+	// fall back to AWS_REGION env, so we leave it optional here.
+	region: string.optional(),
+	...commonEntryFields,
+}).unknown(false);
+const unknownBackendEntrySchema = Joi.object({
+	backend: string.required(),
+}).unknown(true);
+const modelEntrySchema = Joi.alternatives().conditional('.backend', {
+	switch: [
+		{ is: 'ollama', then: ollamaEntrySchema },
+		{ is: 'openai', then: openaiEntrySchema },
+		{ is: 'anthropic', then: anthropicEntrySchema },
+		{ is: 'bedrock', then: bedrockEntrySchema },
+	],
+	otherwise: unknownBackendEntrySchema,
+});
+const modelsSchema = Joi.object({
+	embedding: Joi.object().pattern(Joi.string(), modelEntrySchema).optional(),
+	generative: Joi.object().pattern(Joi.string(), modelEntrySchema).optional(),
+});
+
+/**
+ * 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 function validateModelsBlock(models) {
+	// `allowUnknown: true` mirrors the boot path, whose top-level option propagates into this
+	// subtree: a sibling of embedding/generative that boots must not block a reload. Entry-level
+	// strictness is preserved by each backend schema's `.unknown(false)`.
+	return modelsSchema.validate(models, { abortEarly: false, allowUnknown: true, errors: { wrap: { label: "'" } } });
+}
+
 let hdbRoot;
 let skipFsVal = false;
 
@@ -157,76 +269,42 @@ export function configValidator(configJson, skipFsValidation = false) {
 		session: mcpSessionSchema.optional(),
 	});
 
-	// Models — `models:` block opts a deployment into the per-backend registry.
-	// Per-backend shape is validated by a discriminated alternative on the
-	// `backend` field. Phase 2 (#629) lands ollama; Phase 3 (#630) lands openai.
-	//
-	// `.unknown(false)` on each known backend's schema turns field-name typos
-	// (`bakend: ollama`, `hsot: ...`) into boot-blocking validation errors.
-	// Without it, Joi's top-level `allowUnknown: true` propagates and typos
-	// silently survive into bootstrap. Unknown backend types (anything not in
-	// the `switch` list) fall through to a permissive schema so future Harper
-	// versions or third-party components can register their own backends
-	// without core schema edits — `bootstrapModels` logs+skips at runtime.
-	//
-	// `requestTimeoutMs: min(1)` (not `min(0)`) so the meaning is unambiguous:
-	// omit the field for "no timeout". `0` would validate but `composeSignal`
-	// treats it as "no timeout" via `if (!timeoutMs)`, surprising a test that
-	// sets 0 to mean "fail immediately".
-	const commonEntryFields = {
-		model: string.optional(),
-		requestTimeoutMs: number.min(1).optional(),
-		// Ordered fallback group — other logical names tried, in order, after this one (#1326).
-		fallback: Joi.array().items(string).optional(),
-	};
-	const ollamaEntrySchema = Joi.object({
-		backend: string.valid('ollama').required(),
-		host: string.optional(),
-		...commonEntryFields,
-	}).unknown(false);
-	const openaiEntrySchema = Joi.object({
-		backend: string.valid('openai').required(),
-		// `apiKey` may be a literal secret or a `${ENV_VAR}` placeholder; both
-		// are syntactically strings. `bootstrap.ts` runs `expandEnvVarsDeep`
-		// before construction; the backend rejects unresolved placeholders
-		// with an explicit error pointing at the env-var name.
-		apiKey: string.required(),
-		baseUrl: string.optional(),
-		organization: string.optional(),
-		...commonEntryFields,
-	}).unknown(false);
-	const anthropicEntrySchema = Joi.object({
-		backend: string.valid('anthropic').required(),
-		// Same secret-handling posture as openai's `apiKey`.
-		apiKey: string.required(),
-		baseUrl: string.optional(),
-		...commonEntryFields,
-	}).unknown(false);
-	const bedrockEntrySchema = Joi.object({
-		backend: string.valid('bedrock').required(),
-		// AWS credentials resolve via the SDK chain (env / shared file / IAM
-		// roles for service accounts) — no apiKey field. `region` is
-		// effectively required (Bedrock is regional) but the backend can
-		// fall back to AWS_REGION env, so we leave it optional here.
-		region: string.optional(),
-		...commonEntryFields,
-	}).unknown(false);
-	const unknownBackendEntrySchema = Joi.object({
-		backend: string.required(),
-	}).unknown(true);
-	const modelEntrySchema = Joi.alternatives().conditional('.backend', {
-		switch: [
-			{ is: 'ollama', then: ollamaEntrySchema },
-			{ is: 'openai', then: openaiEntrySchema },
-			{ is: 'anthropic', then: anthropicEntrySchema },
-			{ is: 'bedrock', then: bedrockEntrySchema },
-		],
-		otherwise: unknownBackendEntrySchema,
-	});
-	const modelsSchema = Joi.object({
-		embedding: Joi.object().pattern(Joi.string(), modelEntrySchema).optional(),
-		generative: Joi.object().pattern(Joi.string(), modelEntrySchema).optional(),
-	});
+	// `convert: false` — validateConfig() only writes the coerced value back into configDoc for
+	// threads/componentsRoot/logging/storage/operationsApi, not sql, so leaving Joi's default
+	// convert:true on here would accept a quoted `allowFullScan: "true"` and then silently drop
+	// it (getSqlEngineConfig()'s typeof guard rejects the still-unconverted string).
+	const sqlSettingsSchema = Joi.object({
+		engine: string.valid('legacy', 'new', 'auto').optional(),
+		allowFullScan: boolean.optional(),
+		maxSortRows: number.integer().min(1).optional(),
+		maxHashRows: number.integer().min(1).optional(),
+	})
+		.unknown(false)
+		.prefs({ convert: false });
+
+	// An application deployed under the name before it was reserved still boots; validateConfig()
+	// warns to rename it. Selected positively so a typo'd setting is still held to the settings
+	// schema instead of passing as an application.
+	const legacySqlApplicationSchema = Joi.object({
+		engine: Joi.any().forbidden(),
+		allowFullScan: Joi.any().forbidden(),
+		maxSortRows: Joi.any().forbidden(),
+		maxHashRows: Joi.any().forbidden(),
+	})
+		.unknown(true)
+		.messages({
+			'any.unknown': `{#label} cannot be set while 'sql' names a deployed application; redeploy that application under a different name`,
+		});
+	const sqlSchema = Joi.alternatives()
+		.conditional(
+			Joi.object()
+				.or(...LEGACY_SQL_APPLICATION_KEYS)
+				.unknown(true),
+			{ then: legacySqlApplicationSchema, otherwise: sqlSettingsSchema }
+		)
+		// `false`/null is how componentLoader spells a disabled entry, so an operator who had already
+		// turned a pre-reservation `sql` application off keeps booting.
+		.allow(false, null);
 
 	const configSchema = Joi.object({
 		authentication: Joi.alternatives(
@@ -247,8 +325,8 @@ export function configValidator(configJson, skipFsValidation = false) {
 			replicate: boolean.optional(),
 		}),
 		replication: Joi.object({
-			hostname: Joi.alternatives(string, number).optional().empty(null),
-			url: string.optional().empty(null),
+			hostname: bareHostConstraints,
+			url: nodeUrlConstraints,
 			port: portConstraints,
 			securePort: portConstraints,
 			routes: array.optional().empty(null),
@@ -265,6 +343,10 @@ export function configValidator(configJson, skipFsValidation = false) {
 			copyCursorFlushIntervalMs: number.min(1).optional().empty(null),
 			replayTimeout: number.min(1).optional().empty(null),
 		}).optional(),
+		node: Joi.object({
+			hostname: bareHostConstraints,
+			url: string.optional().empty(null),
+		}).optional(),
 		componentsRoot: rootConstraints.optional(),
 		localStudio: Joi.object({
 			enabled: enabledConstraints,
@@ -364,6 +446,30 @@ export function configValidator(configJson, skipFsValidation = false) {
 			writeAsync: boolean.required(),
 			overlappingSync: boolean.optional(),
 			caching: boolean.optional(),
+			blobs: Joi.object({
+				compression: Joi.object()
+					.pattern(
+						// exact content type, 'type/*' wildcard, or the 'default' entry
+						/^([\w.+-]+\/(\*|[\w.+-]+)|default)$/,
+						Joi.alternatives([
+							Joi.valid(false),
+							// .unknown(false) so a typo'd nested field (e.g. `treshold`) is rejected instead of
+							// silently inheriting the top-level validate() allowUnknown:true and falling back to
+							// the default threshold — matching config-root.schema.json.
+							Joi.object({ codec: Joi.valid('deflate').optional(), threshold: number.min(0).optional() }).unknown(
+								false
+							),
+						])
+					)
+					// fail on keys that are not a content type, a 'type/*' wildcard, or 'default' —
+					// a typo'd key would otherwise silently never match anything
+					.unknown(false)
+					.optional(),
+			})
+				// reject a misspelled property directly under storage.blobs (e.g. `compresion:`), which the
+				// top-level validate()'s allowUnknown:true would otherwise accept and silently leave off
+				.unknown(false)
+				.optional(),
 			compression: Joi.alternatives([
 				boolean.optional(),
 				Joi.object({ dictionary: string.optional(), threshold: number.optional() }),
@@ -378,6 +484,7 @@ export function configValidator(configJson, skipFsValidation = false) {
 		}).required(),
 		mcp: mcpSchema.optional(),
 		models: modelsSchema.optional(),
+		sql: sqlSchema.optional(),
 		ignoreScripts: boolean.optional(),
 		tls: Joi.alternatives([Joi.array().items(tlsConstraints), tlsConstraints]),
 	});
@@ -402,6 +509,36 @@ function doesPathExist(pathToCheck) {
 	return `Specified path ${pathToCheck} does not exist.`;
 }
 
+function validateBareHost(value, helpers) {
+	const violation = bareHostViolation(value);
+	if (violation) {
+		return helpers.message(
+			`{{#label}} ${violation}; it must be a bare hostname or IP literal (no scheme, port, or path) because it is this node's identity`
+		);
+	}
+	return value;
+}
+
+// A node URL supplies this node's identity via its host (server/nodeName.ts urlToNodeName), so it
+// must have an authority. A hostless scheme ("mailto:", "data:", "file:") parses but has no host.
+// A node URL supplies this node's identity via its host (server/nodeName.ts urlToNodeName). Only
+// reject the unambiguous mistake: a value written as a real URL (with a "//" authority) that still
+// parses to no host. Everything else is deliberately tolerated, because urlToNodeName skips a value
+// it cannot take a host from and identity falls through to another source — a scheme-less
+// "node1.example.com:9933" even parses as a *scheme*, so it is indistinguishable from "mailto:" here,
+// and rejecting that shape would turn a previously harmless config into a boot failure.
+function validateNodeUrl(value, helpers) {
+	if (!value.includes('//')) return value;
+	let host;
+	try {
+		host = new URL(value).hostname;
+	} catch {
+		return value; // unparseable — skipped at runtime, not worth failing the boot over
+	}
+	if (!host) return helpers.message('{{#label}} must be a URL with a host (e.g. "wss://node1.example.com:9933")');
+	return value;
+}
+
 function validatePath(value, helpers) {
 	Joi.assert(value, string.pattern(DIRECTORY_PATH_PATTERN, 'directory path'));
 

package/validation/installValidator.ts

@@ -5,6 +5,7 @@ const { string, number } = Joi.types();
 import * as fs from 'fs-extra';
 import * as hdbTerms from '../utility/hdbTerms.ts';
 import * as path from 'path';
+import { bareHostViolation } from '../utility/nodeIdentity.ts';
 import * as validator from './validationWrapper.ts';
 
 export default installValidator;
@@ -22,11 +23,25 @@ function installValidator(param) {
 			null
 		),
 		[(hdbTerms.INSTALL_PROMPTS as any).TC_AGREEMENT]: string.valid('yes', 'YES', 'Yes'),
+		// Catch a bad node identity here rather than at first boot. This runs after the v5 migration
+		// copies REPLICATION_HOSTNAME into NODE_HOSTNAME, so an upgrade carrying a URL-ish value is
+		// reported during install with the same reason the config boundary would give (harper#2218).
+		[hdbTerms.INSTALL_PROMPTS.NODE_HOSTNAME]: Joi.custom(validateNodeHostname).allow('null', null),
 	});
 
 	return validator.validateBySchema(param, installSchema);
 }
 
+function validateNodeHostname(value, helpers) {
+	const violation = bareHostViolation(value);
+	if (violation) {
+		return helpers.message(
+			`{{#label}} ${violation}; it must be a bare hostname or IP literal (no scheme, port, or path) because it is this node's identity`
+		);
+	}
+	return value;
+}
+
 function validateRootAvailable(value, helpers) {
 	if (
 		fs.existsSync(path.join(value, 'system/hdb_user/data.mdb')) ||