@harperfast/harper 5.2.9 → 5.3.0-alpha.1

package/utility/environment/systemInformation.ts

@@ -517,6 +517,7 @@ const rocksDBDatabaseLevelStats = new Set<string>([
 	'numberKeysWritten',
 	'numberReseeksIteration',
 	'numRunningFlushes',
+	'numSnapshots',
 	'oldestSnapshotTime',
 	'stallMicros',
 	'txnOverheadMutexOldCommitMap',
@@ -547,6 +548,12 @@ type RocksDBStats = {
 	numberKeysWritten: number;
 	numberReseeksIteration: number;
 	numRunningFlushes: number;
+	// Live RocksDB snapshots for this database. In-flight reads legitimately hold one, so what
+	// matters is a count that stays nonzero while nothing is reading: obsolete versions behind the
+	// oldest snapshot cannot be discarded for as long as it is held (#2107). oldestSnapshotTime
+	// alone can't show accrual — it stops moving once the oldest snapshot is pinned.
+	// Optional: rocksdb-js 2.7.1 does not yet report rocksdb.num-snapshots.
+	numSnapshots?: number;
 	oldestSnapshotTime: number;
 	stallMicros: number;
 	txnOverheadMutexOldCommitMap: number;

package/utility/errors/commonErrors.ts

@@ -132,6 +132,8 @@ const OPERATION_AUTH_ERROR_MSGS = {
 	OP_IS_SU_ONLY: (op) => `Operation '${op}' is restricted to 'super_user' roles`,
 	OP_NOT_FOUND: (op) => `Operation '${op}' not found`,
 	OP_NOT_IN_OPERATIONS: (op) => `Operation '${op}' is not permitted for this role's operations configuration`,
+	PUT_WITH_ATTRIBUTE_PERMS: (schema, table) =>
+		`'put' is not permitted for a role with attribute permissions on '${schema}.${table}', because replacing a record removes the attributes the request omits and those removals cannot be checked against attribute permissions. Use 'update' or 'upsert' to merge, or a REST PUT, which restores attributes the role may not update.`,
 	OPERATIONS_MUST_BE_ARRAY: "Permission 'operations' must be an array of operation names or group names",
 	INVALID_OPERATIONS_OP: (op) =>
 		`Invalid operations value '${op}'. Must be a valid operation name or group (e.g. 'read_only').`,
@@ -234,6 +236,8 @@ const CUSTOM_FUNCTIONS_ERROR_MSGS = {
 	NO_FILE: 'File does not exist',
 	BAD_FILE_NAME: 'File name can only contain alphanumeric, dash and underscore characters',
 	BAD_PROJECT_NAME: 'Project name can only contain alphanumeric, dash and underscores characters',
+	RESERVED_PROJECT_NAME: (project: string) =>
+		`Component name '${project}' is reserved for Harper's '${project}' configuration section; deploy under a different name`,
 	BAD_PACKAGE: 'Packaged project must be base64-encoded tar file of project directory',
 	DROP_FUNCTION: 'Error dropping custom function, check the log for more details',
 	ADD_FUNCTION: 'Error adding custom function project, check the log for more details',

package/utility/errors/hdbError.ts

@@ -85,6 +85,35 @@ export class IndexRebuildingError extends ServerError {
 	}
 }
 
+/**
+ * Thrown when a write transaction's commit kept losing write-intent conflicts past its queue-time
+ * budget (`storage.maxTransactionQueueTime`, or the transaction's own larger `timeoutBudget`) and
+ * Harper abandoned it rather than let the request wait on an intent holder that may never release
+ * (issue #2450). `retryable` is false when part of the transaction already landed durably — the
+ * caller must not replay a request whose earlier store committed.
+ */
+export class TransactionCommitConflictTimeoutError extends ServerError {
+	code: string;
+	retryable: boolean;
+	constructor(message: string, retryable: boolean) {
+		super(message, 503);
+		this.name = 'TransactionCommitConflictTimeoutError';
+		this.code = 'TRANSACTION_COMMIT_CONFLICT_TIMEOUT';
+		this.retryable = retryable;
+	}
+}
+
+export class UpdateAttributesLockTimeoutError extends ServerError {
+	code: string;
+	retryable: boolean;
+	constructor(message: string) {
+		super(message, 503);
+		this.name = 'UpdateAttributesLockTimeoutError';
+		this.code = 'UPDATE_ATTRIBUTES_LOCK_TIMEOUT';
+		this.retryable = true;
+	}
+}
+
 /** One structured validation failure. `path` is dot-scoped (`body.price`, `query.sort`, `params.id`). */
 export interface ValidationIssue {
 	/** Where the failure occurred, e.g. `body.price`, `query.expand`, `params.id`. */

package/utility/hdbTerms.ts

@@ -155,6 +155,9 @@ export const MAX_SET_TIMEOUT_MS = 2147483647;
 /** Harper File Permissions Mode */
 export const HDB_FILE_PERMISSIONS = 0o700;
 
+/** Smallest `threads.maxHeapMemory` (MB) a worker thread is accepted on — see server/threads/threadHeapMemory.ts */
+export const MIN_THREAD_HEAP_MEMORY_MB = 64;
+
 /** Database directory */
 export const DATABASES_DIR_NAME = 'database';
 /** Suffix for in-progress LMDB→RocksDB migration staging directories: excluded from database
@@ -211,6 +214,8 @@ export const SYSTEM_TABLE_NAMES = {
 	DEPLOYMENT_TABLE_NAME: 'hdb_deployment',
 	AGENT_SESSION_TABLE_NAME: 'hdb_agent_session',
 	SECRET_TABLE_NAME: 'hdb_secret',
+	OIDC_TRUST_TABLE_NAME: 'hdb_oidc_trust',
+	OIDC_TOKEN_USE_TABLE_NAME: 'hdb_oidc_token_use',
 } as const;
 
 /** Hash attribute for the system info table */
@@ -245,6 +250,7 @@ export const OPERATIONS_ENUM = {
 	INSERT: 'insert',
 	UPDATE: 'update',
 	UPSERT: 'upsert',
+	PUT: 'put',
 	SEARCH_BY_CONDITIONS: 'search_by_conditions',
 	SEARCH_BY_HASH: 'search_by_hash',
 	SEARCH_BY_ID: 'search_by_id',
@@ -348,6 +354,10 @@ export const OPERATIONS_ENUM = {
 	LIST_SECRETS: 'list_secrets',
 	DELETE_SECRET: 'delete_secret',
 	GET_SECRETS_PUBLIC_KEY: 'get_secrets_public_key',
+	ADD_OIDC_TRUST: 'add_oidc_trust',
+	LIST_OIDC_TRUST: 'list_oidc_trust',
+	DROP_OIDC_TRUST: 'drop_oidc_trust',
+	EXCHANGE_OIDC_TOKEN: 'exchange_oidc_token',
 	GET_DEPLOYMENT_PAYLOAD: 'get_deployment_payload',
 	DELETE_DEPLOYMENT_PAYLOAD: 'delete_deployment_payload',
 	AGENT_PROMPT: 'agent_prompt',
@@ -683,9 +693,11 @@ export const CONFIG_PARAMS = {
 	STORAGE_MAXTRANSACTIONOPENTIME: 'storage_maxTransactionOpenTime',
 	STORAGE_MAX_READ_TRANSACTION_OPEN_TIME: 'storage_maxReadTransactionOpenTime',
 	STORAGE_DEBUGLONGTRANSACTIONS: 'storage_debugLongTransactions',
+	STORAGE_LONGTRANSACTIONREPORTTHRESHOLD: 'storage_longTransactionReportThreshold',
 	STORAGE_PATH: 'storage_path',
 	STORAGE_BACKUPPATH: 'storage_backupPath',
 	STORAGE_BLOBPATHS: 'storage_blobPaths',
+	STORAGE_BLOBS_COMPRESSION: 'storage_blobs_compression',
 	STORAGE_BLOBCLEANUPSPEED: 'storage_blobCleanupSpeed',
 	STORAGE_BLOBREADTIMEOUT: 'storage_blobReadTimeout',
 	STORAGE_BLOBRETENTION: 'storage_blobRetention',
@@ -730,6 +742,10 @@ export const CONFIG_PARAMS = {
 	CLONED: 'cloned',
 	NODE_HOSTNAME: 'node_hostname',
 	NODE_URL: 'node_url',
+	SQL_ENGINE: 'sql_engine',
+	SQL_ALLOWFULLSCAN: 'sql_allowFullScan',
+	SQL_MAXSORTROWS: 'sql_maxSortRows',
+	SQL_MAXHASHROWS: 'sql_maxHashRows',
 } as const;
 
 /**
@@ -926,6 +942,7 @@ export const JWT_ENUM = {
 export const ITC_EVENT_TYPES = {
 	SHUTDOWN: 'shutdown',
 	CHILD_STARTED: 'child_started',
+	CHILD_STARTUP_PHASE: 'child_startup_phase',
 	CHILD_STOPPED: 'child_stopped',
 	SCHEMA: 'schema',
 	USER: 'user',

package/utility/logging/harper_logger.ts

@@ -100,25 +100,48 @@ let hdbProperties;
 
 let rootConfig;
 
-function updateLogger(logger: any, logOptions: any, name?: string) {
-	logger.rotation = logOptions.rotation;
+// `mainLoggerRef` defaults to the module's private `mainLogger` singleton (the real production
+// behavior) but can be overridden by callers (currently just tests) so the inheritance decision
+// below can be exercised against a throwaway logger without reaching into module-private state.
+export function updateLogger(logger: any, logOptions: any, name?: string, mainLoggerRef: any = mainLogger) {
+	// Fall back to the main logger's rotation (like level/path below) so an external/component
+	// logger with no rotation block of its own inherits maxSize/interval/etc rather than losing
+	// rotation entirely (#1877). Excluded when `logger` IS mainLoggerRef: the fallback would just
+	// reassign mainLogger.rotation to itself, making it impossible to ever clear main's rotation.
+	const inheritedRotation = logOptions.rotation ?? (logger === mainLoggerRef ? undefined : mainLoggerRef?.rotation);
+	if (inheritedRotation && inheritedRotation === mainLoggerRef?.rotation) {
+		// This logger has no rotation block of its own and is inheriting main's wholesale — but
+		// inheriting `rotation.path` too would point this logger's archives at wherever main
+		// archives to. If this logger's file lives on a different filesystem/volume than that
+		// directory, the rotator's fs.rename() there fails with EXDEV and the tick error leaks
+		// (contained in logRotator.ts) without ever rotating this log. Strip the inherited path so
+		// rotation instead defaults beside this logger's own path (logRotator's own <log dir>/rotated
+		// fallback); an explicit `rotation.path` in this logger's own config still wins, since that
+		// goes through `logOptions.rotation` above, not this fallback. Clone rather than mutate:
+		// `inheritedRotation` is the literal object shared by mainLogger.rotation and every other
+		// component that inherited it.
+		const { path: _inheritedPath, ...rotationWithoutPath } = inheritedRotation;
+		logger.rotation = rotationWithoutPath;
+	} else {
+		logger.rotation = inheritedRotation;
+	}
 	let path = logOptions.path;
 	if (path) {
 		if (!logOptions.root) logOptions.root = pathModule.dirname(path);
 	} else if (logOptions.root) {
 		path = join(logOptions.root, logName);
 	} else {
-		path = mainLogger.path;
+		path = mainLoggerRef.path;
 		if (!logOptions.root) logOptions.root = pathModule.dirname(path);
 	}
 	if (path) logger.path = path;
 	else console.error('No path for logger', logOptions);
-	logger.level = LOG_LEVEL_HIERARCHY[logOptions.level] ?? mainLogger?.level ?? LOG_LEVEL_HIERARCHY.info;
+	logger.level = LOG_LEVEL_HIERARCHY[logOptions.level] ?? mainLoggerRef?.level ?? LOG_LEVEL_HIERARCHY.info;
 	updateConditional(logger);
 	logger.logToStdstreams = logOptions.stdStreams ?? false;
 	// if there is a configured tag or if a component is logging to default/main log path, use the component name as the tag
 	// to differentiate it
-	logger.tag = logOptions.tag ?? ((mainLogger.path === logger.path || externalLogger.path === logger.path) && name);
+	logger.tag = logOptions.tag ?? ((mainLoggerRef.path === logger.path || externalLogger.path === logger.path) && name);
 }
 // creates a logger where the methods are only defined if they are within the log level.
 // Using this conditional logger means that every method call must be optional like log.trace?.('message),
@@ -145,7 +168,7 @@ function resolveLogPath(configPath: string, rootPath: string) {
 async function updateLogSettings() {
 	if (!rootConfig) {
 		// set up the initial watcher
-		rootConfig = new RootConfigWatcher();
+		rootConfig = getSharedRootConfigWatcher();
 		// wait for it to be ready
 		await rootConfig.ready;
 		// TODO: Any way to differentiate changes that we can and can't handle?
@@ -383,8 +406,20 @@ module.exports = {
 	disableStdio,
 	isStdioBrokenError,
 	externalLogger,
+	updateLogger,
 };
 
+// Writes past the stdio guard installed by installStdioGuard, which would otherwise route the
+// text back into the file logger this is the fallback for, and swallows a broken pipe - there is
+// nowhere left to report it.
+function writeToStdioDirectly(stream, text) {
+	try {
+		nativeStdWrite.call(stream, text);
+	} catch {
+		// stdio is gone too
+	}
+}
+
 // A bare no-op would read as permanent backpressure to a pipe()'d source; this drains and
 // discards instead.
 function noopWrite(_chunk?: any, encoding?: any, callback?: any) {
@@ -510,10 +545,17 @@ export function initLogSettings(forceInit = false) {
 
 			logLevel = logLevel === undefined ? defaultLevel : logLevel;
 
-			mainLogger = createLogger({ level: logLevel });
+			// createLogger shadows the module-level `logToStdstreams` with this option, so omitting it
+			// drops every log written before a config exists rather than routing it to the streams.
+			mainLogger = createLogger({ level: logLevel, stdStreams: logToStdstreams });
 			// setup the external logger
 			externalLogger = mainLogger.forComponent('external');
 			externalLogger.tag = null; // don't tag by default
+			// The streams are this branch's only sink, so it needs the same EPIPE/EIO listeners the
+			// configured path installs below: `harper install | head -1` closes the reader, and the
+			// async error would otherwise land on a stream with none and take the install down. The
+			// guard's write override is inert here, because `log_to_file` is false.
+			stdioLogging();
 			return;
 		}
 
@@ -727,6 +769,8 @@ export function createLogger(options: any = {} as any) {
 	return logger;
 }
 const LOG_TIME_USAGE_THRESHOLD = 100;
+// How long to write straight to stdio after the log file refuses an append.
+const APPEND_RETRY_COOLDOWN = 5000;
 /**
  * Get the file logger for the given path. If it doesn't exist, create it.
  * @param path
@@ -735,7 +779,7 @@ const LOG_TIME_USAGE_THRESHOLD = 100;
  */
 function getFileLogger(path, rotation, isExternalInstance) {
 	let logger = fileLoggers.get(path);
-	let logFD, loggedFDError, logTimer;
+	let logFD, loggedFDError, loggedAppendError, logTimer, retryAppendAfter;
 	let logBuffer;
 	let logTimeUsage = 0;
 	if (!logger) {
@@ -788,14 +832,37 @@ function getFileLogger(path, rotation, isExternalInstance) {
 	// this is called on a timer, and will write the log buffer to the file
 	function logQueuedData(entry?: any) {
 		openLogFile(undefined);
-		if (logFD) {
+		const payload = logBuffer ? logBuffer.join('') : entry;
+		// A file that just refused a write will refuse the next one too, and every attempt costs a
+		// failed syscall plus a thrown error on whatever path is logging - which, on a full volume,
+		// is the request path at full rate. Go straight to stdio until the cooldown expires.
+		if (logFD && !(retryAppendAfter > performance.now())) {
 			let startTime = performance.now();
-			fs.appendFileSync(logFD, logBuffer ? logBuffer.join('') : entry);
+			try {
+				fs.appendFileSync(logFD, payload);
+				// Both cleared, so a volume that fills again months later reports itself again
+				retryAppendAfter = undefined;
+				loggedAppendError = false;
+			} catch (error) {
+				retryAppendAfter = performance.now() + APPEND_RETRY_COOLDOWN;
+				// A log write must never take the process down: on an exhausted volume this throws from
+				// both inline and timer call sites, making every log statement a crash point (#847).
+				// The fallback goes through nativeStdWrite rather than console because
+				// installStdioGuard routes console output back into this same file logger when
+				// logging.file and logging.console are both on, which would recurse until the stack blew.
+				if (!loggedAppendError) {
+					loggedAppendError = true;
+					writeToStdioDirectly(process.stderr, `Harper cannot write to its log file: ${error}\n`);
+				}
+				writeToStdioDirectly(process.stdout, payload);
+				logBuffer = null;
+				return;
+			}
 			let endTime = performance.now();
 			// determine if we are using more than about two percent of processing time for log writes recently, and if so, we
 			// will start buffering
 			logTimeUsage = Math.max(endTime, logTimeUsage) + (endTime - startTime) * 50;
-		} else if (!loggedFDError) console.log(logBuffer ? logBuffer.join('') : entry);
+		} else writeToStdioDirectly(process.stdout, payload);
 		if (logBuffer) logBuffer = null;
 	}
 
@@ -815,8 +882,13 @@ function getFileLogger(path, rotation, isExternalInstance) {
 			} catch (error) {
 				if (error.code === 'ENOENT' && !isRetry) {
 					// if the directory doesn't exist, create it
-					fs.mkdirpSync(pathModule.dirname(path));
-					return openLogFile(true);
+					try {
+						fs.mkdirpSync(pathModule.dirname(path));
+						return openLogFile(true);
+					} catch (mkdirError) {
+						// creating the log directory can fail for the same reason the log write can
+						error = mkdirError;
+					}
 				}
 				if (!loggedFDError) {
 					loggedFDError = true;
@@ -1811,7 +1883,7 @@ export function AuthAuditLog(
 	this.path = path;
 }
 // we have to load this at the end to avoid circular dependencies problems
-import { RootConfigWatcher } from '../../config/RootConfigWatcher.ts';
+import { getSharedRootConfigWatcher } from '../../config/RootConfigWatcher.ts';
 
 export const getLogFilePath = () => logFilePath;
 export const forComponent = (name: string, isExternal?: boolean) => mainLogger.forComponent(name, isExternal);
@@ -1846,4 +1918,5 @@ export default {
 	errorForLog,
 	inspectForLog,
 	isErrorLike,
+	updateLogger,
 };

package/utility/logging/logRotator.ts

@@ -6,6 +6,7 @@ import { promisify } from 'util';
 import { pipeline } from 'stream';
 const pipe = promisify(pipeline);
 import * as path from 'path';
+import { createHash } from 'crypto';
 import * as envMgr from '../environment/environmentManager.ts';
 envMgr.initSync();
 import hdbLogger from './harper_logger.ts';
@@ -67,62 +68,71 @@ function logRotator({ logger, maxSize, interval, retention, enabled, path: rotat
 	let lastRotationTime = Date.now();
 	hdbLogger.trace('Log rotate enabled, maxSize:', maxSize, 'interval:', interval);
 	const setIntervalId = setInterval(async () => {
-		// A missing/relocated active log file only invalidates the rotation checks below — retention cleanup
-		// must still run. So skip the individual check on ENOENT rather than returning from the whole tick.
-		if (maxBytes) {
-			let fileStats;
-			try {
-				fileStats = await fsProm.stat(logger.path);
-			} catch (err) {
-				// If the log file doesn't exist, skip the size-based rotation check
-				if (err.code !== 'ENOENT') throw err;
-			}
-
-			if (fileStats && fileStats.size >= maxBytes) {
+		// The tick is async but setInterval doesn't await it, so any error that escapes this callback
+		// becomes an unhandled rejection rather than surfacing anywhere useful — and since it isn't
+		// caught, it also skips the retention cleanup below. Contain everything here and report via
+		// the logger instead, so one bad tick (e.g. an unexpected fs error) never kills rotation for
+		// the rest of the process's life.
+		try {
+			// A missing/relocated active log file only invalidates the rotation checks below — retention cleanup
+			// must still run. So skip the individual check on ENOENT rather than returning from the whole tick.
+			if (maxBytes) {
+				let fileStats;
 				try {
-					lastRotatedLogPath = await moveLogFile(logger.path, rotatedLogDir, logger);
+					fileStats = await fsProm.stat(logger.path);
 				} catch (err) {
-					// If the log file doesn't exist, skip rotation
+					// If the log file doesn't exist, skip the size-based rotation check
 					if (err.code !== 'ENOENT') throw err;
 				}
-			}
-		}
 
-		if (maxInterval) {
-			const minSinceLastRotate = Date.now() - lastRotationTime;
-			if (minSinceLastRotate >= maxInterval) {
-				try {
-					lastRotatedLogPath = await moveLogFile(logger.path, rotatedLogDir, logger);
-					lastRotationTime = Date.now();
-				} catch (err) {
-					// If the log file doesn't exist, skip rotation
-					if (err.code !== 'ENOENT') throw err;
+				if (fileStats && fileStats.size >= maxBytes) {
+					try {
+						lastRotatedLogPath = await moveLogFile(logger.path, rotatedLogDir, logger);
+					} catch (err) {
+						// If the log file doesn't exist, skip rotation
+						if (err.code !== 'ENOENT') throw err;
+					}
 				}
 			}
-		}
-		if (retention || reclamationPriority) {
-			// remove old logs after retention time
-			// adjust retention time if there is a reclamation priority in place
-			const retentionMs = convertToMS(retention ?? '1M') / (1 + reclamationPriority);
-			reclamationPriority = 0; // reset it after use
-			let files;
-			try {
-				files = await fsProm.readdir(rotatedLogDir);
-			} catch (err) {
-				// The rotated log dir may not exist yet (nothing rotated so far); nothing to clean up
-				if (err.code !== 'ENOENT') hdbLogger.error('Error reading rotated log directory', rotatedLogDir, err);
-				files = [];
+
+			if (maxInterval) {
+				const minSinceLastRotate = Date.now() - lastRotationTime;
+				if (minSinceLastRotate >= maxInterval) {
+					try {
+						lastRotatedLogPath = await moveLogFile(logger.path, rotatedLogDir, logger);
+						lastRotationTime = Date.now();
+					} catch (err) {
+						// If the log file doesn't exist, skip rotation
+						if (err.code !== 'ENOENT') throw err;
+					}
+				}
 			}
-			for (const file of files) {
+			if (retention || reclamationPriority) {
+				// remove old logs after retention time
+				// adjust retention time if there is a reclamation priority in place
+				const retentionMs = convertToMS(retention ?? '1M') / (1 + reclamationPriority);
+				reclamationPriority = 0; // reset it after use
+				let files;
 				try {
-					const fileStats = await fsProm.stat(path.join(rotatedLogDir, file));
-					if (Date.now() - fileStats.mtimeMs > retentionMs) {
-						await fsProm.unlink(path.join(rotatedLogDir, file));
-					}
+					files = await fsProm.readdir(rotatedLogDir);
 				} catch (err) {
-					hdbLogger.error('Error trying to remove log', file, err);
+					// The rotated log dir may not exist yet (nothing rotated so far); nothing to clean up
+					if (err.code !== 'ENOENT') hdbLogger.error('Error reading rotated log directory', rotatedLogDir, err);
+					files = [];
+				}
+				for (const file of files) {
+					try {
+						const fileStats = await fsProm.stat(path.join(rotatedLogDir, file));
+						if (Date.now() - fileStats.mtimeMs > retentionMs) {
+							await fsProm.unlink(path.join(rotatedLogDir, file));
+						}
+					} catch (err) {
+						hdbLogger.error('Error trying to remove log', file, err);
+					}
 				}
 			}
+		} catch (err) {
+			hdbLogger.error('Error during log rotation audit tick for', logger.path, err);
 		}
 	}, auditInterval ?? LOG_AUDIT_INTERVAL).unref();
 	return {
@@ -135,11 +145,28 @@ function logRotator({ logger, maxSize, interval, retention, enabled, path: rotat
 	};
 }
 
+// Monotonically increasing across every rotation in this process, regardless of which logger/source
+// triggered it — combined with the pid, this guarantees two archive names can never collide even if
+// two rotations for two different sources race concurrently within the same audit-interval tick.
+let rotationSequence = 0;
+
 async function moveLogFile(logPath: string, rotatedLogPath: string, logger?: any) {
 	const compress = envMgr.get(CONFIG_PARAMS.LOGGING_ROTATION_COMPRESS);
+	// Name the archive after its source log (hdb, external, a component name, ...), not a fixed
+	// "HDB" literal — external/component loggers can now inherit rotation from the main logger
+	// (#1877) and default to the same rotated directory as it, so distinct sources rotating in
+	// the same audit tick must not collide on the same timestamp-only filename. A basename alone
+	// is not enough either: two distinct source paths can share a basename (e.g. `/logs/a/hdb.log`
+	// and `/logs/b/hdb.log`), so a hash of the full resolved source path plus a pid+sequence suffix
+	// give every archive a name POSIX rename() can never clobber, even under a same-millisecond race.
+	const sourceName = path.basename(logPath, path.extname(logPath)) || 'HDB';
+	// sha256, not sha1: this only needs a stable identifier, not cryptographic strength, but a FIPS-mode
+	// OpenSSL provider disables sha1 and throws synchronously, which would crash every rotation tick.
+	const sourceId = createHash('sha256').update(path.resolve(logPath)).digest('hex').slice(0, 8);
+	const uniqueSuffix = `${process.pid}-${rotationSequence++}`;
 	let fullRotateLogPath = path.join(
 		rotatedLogPath,
-		`HDB-${new Date(Date.now()).toISOString().replaceAll(':', '-')}.log`
+		`${sourceName}-${sourceId}-${new Date(Date.now()).toISOString().replaceAll(':', '-')}-${uniqueSuffix}.log`
 	);
 	// Move log file to rotated log path first (if we crash
 	// during compression, we don't want to restart the compression with a new file)

package/utility/nodeIdentity.ts

@@ -0,0 +1,45 @@
+import { isIP } from 'node:net';
+
+/**
+ * A node's identity — node.hostname, and the replication.hostname / certificate it falls back to —
+ * must be a bare hostname or IP literal, not a URL: it becomes the certificate common name and the
+ * host replication advertises and dials, so a scheme/port/path/non-string corrupts both (harper#2218,
+ * where "ws://http://host:9926:9925" resolves to host "http"). Returns a reason clause when `value`
+ * is not a bare host, else undefined. An empty string is "unset" (a caller's cue to fall back), not a
+ * violation.
+ */
+export function bareHostViolation(value: unknown): string | undefined {
+	if (typeof value !== 'string') return `must be a string, but is a ${value === null ? 'null' : typeof value}`;
+	if (value === '') return undefined;
+	// The identity is stored unbracketed (bracketing belongs to URL construction). Reject a bracketed
+	// form so it is never cached — otherwise net.isIP fails on it and the certificate SAN is mistyped
+	// as DNS rather than IP, and the same node's identity string would differ by source.
+	if (value.includes('[') || value.includes(']'))
+		return 'must be an unbracketed IPv6 literal (e.g. "::1", not "[::1]")';
+	// A zone id ("fe80::1%eth0") passes net.isIP but has no valid URL authority, so exclude it here.
+	if (isIP(value) && !value.includes('%')) return undefined; // a bare IPv4/IPv6 literal is a valid identity
+	if (value.includes('://')) return 'must not include a URL scheme';
+	let url;
+	try {
+		// Parse under a special scheme so the host grammar matches the ws:// replication URLs that
+		// consume this value — a host this accepts is one the consumer accepts (a non-special scheme is
+		// more lenient and would pass e.g. "node%20" or "0x7f.1"). A port or path makes url.hostname
+		// differ from the input and is caught by the round-trip check below.
+		url = new URL(`https://${value}`);
+	} catch {
+		return 'is not a valid hostname';
+	}
+	// Report the port before the round-trip check: the parser strips a default port for the scheme it
+	// was given (":443" under https), which would otherwise surface as a vaguer "is not a bare hostname".
+	if (url.port || (url.hostname && value.slice(url.hostname.length).startsWith(':'))) {
+		return 'must not include a port';
+	}
+	if (url.username || url.password) return 'must not include credentials';
+	if (url.search) return 'must not include a query string';
+	if (url.hash) return 'must not include a fragment';
+	if (url.pathname && url.pathname !== '/') return 'must not include a path';
+	// The host must survive parsing unchanged (compared case-insensitively, since URL lowercases it);
+	// anything that does not round-trip carried extra syntax and is not a bare host.
+	if (url.hostname.toLowerCase() !== value.toLowerCase()) return 'is not a bare hostname';
+	return undefined;
+}

package/utility/npmUtilities.ts

@@ -12,7 +12,7 @@ import harperLogger from './logging/harper_logger.ts';
 
 import { CONFIG_PARAMS } from './hdbTerms.ts';
 import { getConfigPath } from '../config/configUtils.ts';
-import { nonInteractiveSpawn } from '../components/Application.ts';
+import { nonInteractiveSpawn, packageManagerInstallArguments } from '../components/Application.ts';
 import { withComponentPreparationLock } from '../components/componentPreparationLock.ts';
 import { isThreadRunning } from '../server/threads/manageThreads.js';
 
@@ -26,18 +26,19 @@ export async function installModules(req: any) {
 		'install_node_modules is deprecated. Dependencies are automatically installed on' +
 		' deploy, and install_node_modules can lead to inconsistent behavior';
 	harperLogger.warn(deprecationWarning, req.projects);
-	const validation = modulesValidator(req);
+	const { error: validation, value: validatedRequest } = modulesValidator(req);
 	if (validation) {
 		throw handleHDBError(validation, validation.message, HTTP_STATUS_CODES.BAD_REQUEST);
 	}
 
-	let { projects, dryRun } = req;
+	const { projects, dry_run: dryRun } = validatedRequest;
 
 	const componentsRootDirPath = getConfigPath(CONFIG_PARAMS.COMPONENTSROOT);
 
 	const responseObject: any = {};
 
-	const args = ['install', '--force', '--omit=dev', '--json'];
+	// `allowInstallScripts` is true because this operation has always run a project's install lifecycle
+	const args = [...packageManagerInstallArguments('npm', true, true), '--json'];
 	if (dryRun) args.push('--dry-run');
 
 	for (const project of projects) {
@@ -91,15 +92,16 @@ function parseNPMStdErr(stderr: string) {
 }
 
 /**
- * Validator for both installModules & auditModules
+ * Validator for installModules
  * @param {Object} req
- * @returns {*}
  */
 function modulesValidator(req: any) {
+	// `dryRun` was the only spelling that worked before dry_run was honored; keep it accepted, but
+	// reject a request that carries both rather than picking a winner
 	const funcSchema = Joi.object({
 		projects: Joi.array().min(1).items(Joi.string()).required(),
 		dry_run: Joi.boolean().default(false),
-	});
+	}).rename('dryRun', 'dry_run', { ignoreUndefined: true });
 
-	return validator.validateBySchema(req, funcSchema);
+	return validator.validateAndConvertBySchema(req, funcSchema);
 }

package/utility/operationPermissions.ts

@@ -69,6 +69,7 @@ export const OPERATION_PERMISSION_GROUPS = {
 		OPERATIONS_ENUM.INSERT,
 		OPERATIONS_ENUM.UPDATE,
 		OPERATIONS_ENUM.UPSERT,
+		OPERATIONS_ENUM.PUT,
 		OPERATIONS_ENUM.DELETE,
 		// Bulk load
 		OPERATIONS_ENUM.CSV_DATA_LOAD,
@@ -97,6 +98,11 @@ const validGroups: Set<string> = new Set(Object.keys(OPERATION_PERMISSION_GROUPS
 // permission) whose names may fall outside OPERATIONS_ENUM. Tracked so they're grantable in a
 // role's `operations` allowlist (add_role/alter_role/impersonation validate against this set too).
 const dynamicallyRegisteredOps: Set<string> = new Set();
+// The same, for ops registered on a WORKER and mirrored here by the OPERATION_REGISTERED bridge.
+// Deliberately a separate set: the two threads can register the same name independently (a hot
+// deploy can add a `startOnMainThread` component while the worker offering that name is retiring),
+// so worker-lifecycle cleanup must not be able to revoke a mark this thread made itself.
+const workerRegisteredOps: Set<string> = new Set();
 
 /**
  * Mark a dynamically-registered operation name as a valid target for role `operations` grants.
@@ -115,13 +121,24 @@ export function unregisterGrantableOperation(name: string): void {
 	dynamicallyRegisteredOps.delete(name);
 }
 
+export function registerWorkerGrantableOperation(name: string): void {
+	workerRegisteredOps.add(name);
+}
+
+export function unregisterWorkerGrantableOperation(name: string): void {
+	workerRegisteredOps.delete(name);
+}
+
 /**
  * Validates that every entry in an operations array is a known operation name or group name.
  * Returns the first invalid entry, or null if all entries are valid.
  */
 export function validateOperations(operations: readonly unknown[]): string | null {
 	for (const op of operations) {
-		if (typeof op !== 'string' || (!validOps.has(op) && !validGroups.has(op) && !dynamicallyRegisteredOps.has(op))) {
+		if (
+			typeof op !== 'string' ||
+			(!validOps.has(op) && !validGroups.has(op) && !dynamicallyRegisteredOps.has(op) && !workerRegisteredOps.has(op))
+		) {
 			return String(op);
 		}
 	}