@harperfast/harper 5.2.9 → 5.3.0-alpha.1

package/components/ApplicationScope.ts

@@ -1,4 +1,5 @@
 import type { Resources } from '../resources/Resources.ts';
+import type { BranchDatabase } from '../resources/databases.ts';
 import { type Server } from '../server/Server.ts';
 import { forComponent } from '../utility/logging/harper_logger.ts';
 import { scopedImport } from '../security/jsLoader.ts';
@@ -28,6 +29,13 @@ export class ApplicationScope {
 	allowedPath?: string;
 	runtimeRoot?: string;
 	config: any;
+	/**
+	 * Private forks of the databases this application declared, keyed by the LOGICAL name its code
+	 * uses (`data`). Present only for a branched application; `getHarperExports` reads it to build
+	 * the scoped `databases` binding, and an unbranched scope leaves it undefined so that binding
+	 * stays the process-wide singleton by identity.
+	 */
+	branches?: Map<string, BranchDatabase>;
 	moduleCache: any; // used by the loader to retain a cache of modules, type is an internal detail of the loader
 	#runtimeModules: RuntimeModuleTracker;
 	constructor(name: string, resources: Resources, server: Server, isInternal = false) {

package/components/EntryHandler.ts

@@ -4,17 +4,20 @@ import { createHash } from 'node:crypto';
 import type { Stats } from 'node:fs';
 import { EventEmitter } from 'node:events';
 import { Component, FileAndURLPathConfig } from './Component.ts';
-import chokidar, { FSWatcher, FSWatcherEventMap } from 'chokidar';
-import { join } from 'node:path';
+import { FSWatcher, FSWatcherEventMap } from 'chokidar';
+import { isAbsolute, join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { FilesOption } from './deriveGlobOptions.ts';
 import { deriveURLPath } from './deriveURLPath.ts';
 import { isMatch } from 'micromatch';
 import {
 	DIRECTORY_POLLING_FALLBACK_OPTIONS,
+	claimLostNativeWatchError,
+	guardedWatch,
 	isWatcherExhaustionError,
 	warnWatcherFallback,
 } from '../utility/watcherFallback.ts';
+import { resolveWatchTarget } from '../utility/watchPath.ts';
 
 export interface BaseEntry {
 	stats?: Stats;
@@ -391,6 +394,11 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 	}
 
 	#handleWatcherError(error: unknown): void {
+		// A lost native watch handle (the watched tree was deleted or replaced) is
+		// benign and not actionable by a consumer. chokidar's non-persistent branch
+		// never routes it here today — installLostNativeWatchGuard() catches it at
+		// the process instead — but the polling branch and a fixed chokidar would.
+		if (claimLostNativeWatchError(error)) return;
 		if (isWatcherExhaustionError(error)) {
 			// Swallow every exhaustion error — chokidar can emit several before the
 			// failed native watcher closes, and we don't want a flurry of ENOSPC to
@@ -536,45 +544,57 @@ export class EntryHandler extends EventEmitter<EntryHandlerEventMap> {
 			readFailures: new Map(),
 		};
 
-		const allowedBases = this.#component.patternBases.map((base) => join(this.#component.directory, base));
+		// `ignored` receives absolute paths built from `cwd`, so its bases must come from the same
+		// directory spelling. Event paths are relative to `cwd`, so reads below stay on `this.directory`.
+		const watchTarget = resolveWatchTarget(this.#component.directory);
+		if (watchTarget.mustPoll) this.#usingPolling = true;
+		const watchDirectory = watchTarget.path;
+		const normalizedDirectory = watchDirectory.replace(/\\/g, '/');
+		const normalizedBases = this.#component.patternBases.map((base) => join(watchDirectory, base).replace(/\\/g, '/'));
+
+		// chokidar resolves a relative pattern base against `cwd`, but an absolute one reaches the
+		// native watch as spelled, bypassing the canonicalized `cwd` above.
+		let watchPattern = this.#component.commonPatternBase;
+		if (isAbsolute(watchPattern)) {
+			const patternTarget = resolveWatchTarget(watchPattern);
+			if (patternTarget.mustPoll) this.#usingPolling = true;
+			watchPattern = patternTarget.path;
+		}
 
 		this.#openCount++;
-		const watcher = (this.#watcher = chokidar
-			.watch(this.#component.commonPatternBase, {
-				cwd: this.#component.directory,
-				persistent: false,
-				followSymlinks: false,
-				...(this.#usingPolling ? DIRECTORY_POLLING_FALLBACK_OPTIONS : {}),
-				ignored: (path) => {
-					const normalizedPath = path.replace(/\\/g, '/');
-					const normalizedBases = allowedBases.map((base) => base.replace(/\\/g, '/'));
-					const normalizedDirectory = this.#component.directory.replace(/\\/g, '/');
-
-					// Determine the path relative to the component directory. Leading '/' is preserved
-					// (or empty when the path *is* the component directory) so the regex anchors below
-					// can use `(?:^|/)` to match the first segment without false positives on names
-					// that merely contain the same substring (e.g. `mynode_modules`, `notgit`).
-					const relativePath = normalizedPath.startsWith(normalizedDirectory)
-						? normalizedPath.slice(normalizedDirectory.length)
-						: normalizedPath;
-
-					// Skip node_modules at any depth. This allows plugins loaded from node_modules
-					// to still watch their own component files while ignoring their dependencies.
-					if (/(?:^|\/)node_modules(?:\/|$)/.test(relativePath)) return true;
-
-					// Skip transient package manager and VCS artifacts. Without these, an in-place
-					// `npm install` during a component deploy writes log files and atomic-rename
-					// temp directories that fire change events and drive an auto-reload restart
-					// storm — see harper#488.
-					if (/(?:^|\/)\.git(?:\/|$)/.test(relativePath)) return true;
-					if (/(?:^|\/)\.tmp-/.test(relativePath)) return true;
-					if (/(?:^|\/)(?:npm-debug|yarn-error|yarn-debug|pnpm-debug)\.log(?:\/|$)/.test(relativePath)) return true;
-
-					return (
-						normalizedPath !== normalizedDirectory && normalizedBases.every((base) => !normalizedPath.startsWith(base))
-					);
-				},
-			})
+		const watcher = (this.#watcher = guardedWatch(watchPattern, {
+			cwd: watchDirectory,
+			persistent: false,
+			followSymlinks: false,
+			...(this.#usingPolling ? DIRECTORY_POLLING_FALLBACK_OPTIONS : {}),
+			ignored: (path) => {
+				const normalizedPath = path.replace(/\\/g, '/');
+
+				// Determine the path relative to the component directory. Leading '/' is preserved
+				// (or empty when the path *is* the component directory) so the regex anchors below
+				// can use `(?:^|/)` to match the first segment without false positives on names
+				// that merely contain the same substring (e.g. `mynode_modules`, `notgit`).
+				const relativePath = normalizedPath.startsWith(normalizedDirectory)
+					? normalizedPath.slice(normalizedDirectory.length)
+					: normalizedPath;
+
+				// Skip node_modules at any depth. This allows plugins loaded from node_modules
+				// to still watch their own component files while ignoring their dependencies.
+				if (/(?:^|\/)node_modules(?:\/|$)/.test(relativePath)) return true;
+
+				// Skip transient package manager and VCS artifacts. Without these, an in-place
+				// `npm install` during a component deploy writes log files and atomic-rename
+				// temp directories that fire change events and drive an auto-reload restart
+				// storm — see harper#488.
+				if (/(?:^|\/)\.git(?:\/|$)/.test(relativePath)) return true;
+				if (/(?:^|\/)\.tmp-/.test(relativePath)) return true;
+				if (/(?:^|\/)(?:npm-debug|yarn-error|yarn-debug|pnpm-debug)\.log(?:\/|$)/.test(relativePath)) return true;
+
+				return (
+					normalizedPath !== normalizedDirectory && normalizedBases.every((base) => !normalizedPath.startsWith(base))
+				);
+			},
+		})
 			.on('all', (...args) => this.#handleAll(generation, ...args))
 			.on('error', (error) => {
 				if (generation === this.#watchGeneration) this.#handleWatcherError(error);

package/components/OptionsWatcher.ts

@@ -2,12 +2,22 @@ import { type Logger } from '../utility/logging/logger.ts';
 import { loggerWithTag } from '../utility/logging/harper_logger.ts';
 import { EventEmitter, once } from 'events';
 import yaml from 'yaml';
-import chokidar, { type FSWatcher } from 'chokidar';
+import { type FSWatcher } from 'chokidar';
 import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
 import { isDeepStrictEqual } from 'util';
 import { DEFAULT_CONFIG } from './DEFAULT_CONFIG.ts';
 import { cloneDeep } from 'lodash';
-import { POLLING_FALLBACK_OPTIONS, isWatcherExhaustionError, warnWatcherFallback } from '../utility/watcherFallback.ts';
+import {
+	POLLING_FALLBACK_OPTIONS,
+	PartialReadRetry,
+	claimLostNativeWatchError,
+	guardedWatch,
+	isPartialReadError,
+	isWatcherExhaustionError,
+	warnWatcherFallback,
+} from '../utility/watcherFallback.ts';
+import { resolveWatchTarget } from '../utility/watchPath.ts';
 import { overlayRootEnvConfig, isRootConfigFilename } from '../config/harperConfigEnvVars.ts';
 
 export interface Config {
@@ -84,6 +94,7 @@ export class CannotSetPropertyError extends Error {
  */
 export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 	#filePath: string;
+	#watchPath: string;
 	#watcher!: FSWatcher;
 	#scopedConfig?: ConfigValue;
 	#rootConfig?: Config;
@@ -94,18 +105,22 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 	#closed: boolean;
 	#openCount: number = 0;
 	#pendingReads: Set<Promise<void>> = new Set();
+	#partialRead: PartialReadRetry;
 	ready: Promise<any[]>;
 
 	constructor(name: string, filePath: string, logger?: Logger, isRootConfig?: boolean) {
 		super();
 		this.#name = name;
 		this.#filePath = filePath;
+		const watchTarget = resolveWatchTarget(filePath);
+		this.#watchPath = watchTarget.path;
+		this.#partialRead = new PartialReadRetry(filePath);
 		// Root-config watchers must see runtime env config (HARPER_SET_CONFIG et al.)
 		// even when it hasn't been flushed to disk yet — see #handleChange (#1618).
 		// Application scopes watch their own config.yaml and are never overlaid.
 		this.#isRootConfig = isRootConfig ?? isRootConfigFilename(filePath);
 		this.#logger = logger || loggerWithTag(name);
-		this.#usingPolling = false;
+		this.#usingPolling = watchTarget.mustPoll;
 		this.#closed = false;
 		this.ready = once(this, 'ready');
 		this.#openWatcher();
@@ -113,11 +128,10 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 
 	#openWatcher() {
 		this.#openCount++;
-		this.#watcher = chokidar
-			.watch(this.#filePath, {
-				persistent: false,
-				...(this.#usingPolling ? POLLING_FALLBACK_OPTIONS : {}),
-			})
+		this.#watcher = guardedWatch(this.#watchPath, {
+			persistent: false,
+			...(this.#usingPolling ? POLLING_FALLBACK_OPTIONS : {}),
+		})
 			.on('add', this.#handleChange.bind(this))
 			.on('change', this.#handleChange.bind(this))
 			.on('error', this.#handleError.bind(this))
@@ -125,73 +139,127 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 			.on('ready', this.#handleChange.bind(this));
 	}
 
+	// Root config only: see the descriptor-lifetime invariant on atomicWriteFile (DESIGN.md).
 	#handleChange() {
+		if (this.#isRootConfig) {
+			this.#applyRead(() => readFileSync(this.#filePath, 'utf-8'));
+			return;
+		}
 		const read: Promise<void> = readFile(this.#filePath, 'utf-8')
-			.then((contents) => {
-				let parsed = yaml.parse(contents);
-				// The on-disk root config is not guaranteed to include runtime env config at
-				// boot: the file flush races component loading, so a scope's boot-time reads
-				// (e.g. an `enabled` gate in handleApplication) could observe pre-env values
-				// the componentLoader itself never saw. Ask the config layer to overlay env
-				// config onto EVERY root-config read so scope.options matches the resolved
-				// view (#1618). Non-root scopes and the no-env-vars case are untouched
-				// (overlayRootEnvConfig is a no-op there).
-				if (this.#isRootConfig) parsed = overlayRootEnvConfig(parsed);
-				this.#rootConfig = parsed && typeof parsed === 'object' ? parsed : undefined;
-				// If the extension is in the config file
-				if (this.#rootConfig && this.#name in this.#rootConfig) {
-					// If a config object does not exist
-					if (!this.#scopedConfig) {
-						// set it
-						this.#scopedConfig = this.#rootConfig[this.#name];
-						// and emit a ready event
-						this.emit('ready', this.#scopedConfig);
-					} else {
-						// Otherwise, merge the new config with the old config
-						this.#merge(this.#rootConfig[this.#name], this.#scopedConfig);
-					}
-				} else {
-					// Otherwise, if the extension is not in the config file
-					// This means the plugin was removed from the config file
-					if (this.#scopedConfig) {
-						// and a config exists, remove it
-						this.#scopedConfig = undefined;
-						this.emit('remove');
-					}
-					// Otherwise do nothing - the user may add the config back in later
-				}
-			})
-			.catch((error) => {
-				// If the config file does not exist
-				if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-					// A readFile ENOENT here is the install window (file not written yet) or a
-					// transient read race — NOT a real deletion, which chokidar routes to
-					// `#handleUnlink`. Env config is file-independent, so when it provides this
-					// scope the missing file must not discard it (#1618). When it does not, fall
-					// through to the original ENOENT handling with #rootConfig untouched, so a
-					// first boot still emits `ready` (not `remove`, which nothing consumes at
-					// boot → `ready` would hang forever).
-					if (this.#applyEnvOnlyConfig()) return;
-					// And a config already exists, reset it to the default
-					if (this.#rootConfig) {
-						this.#resetConfig();
-						this.emit('remove');
-					} else {
-						// Otherwise, if no config exists, then just set to default and emit ready
-						this.#resetConfig();
-						this.emit('ready');
-					}
-					return;
-				}
-				this.emit('error', error);
-			})
+			.then((contents) => this.#applyRead(() => contents))
+			.catch((error) => this.#recoverOrReport(error))
 			.finally(() => {
 				this.#pendingReads.delete(read);
 			});
 		this.#pendingReads.add(read);
 	}
 
+	#applyRead(read: () => string) {
+		let parsed;
+		try {
+			parsed = yaml.parse(read());
+		} catch (error) {
+			// A read or parse that fails while the file is being replaced is the same event as an
+			// incomplete one, and #handleReadError's ENOENT arm would answer it with a `remove`
+			// that restarts the scope. Re-read first; only an exhausted budget means it is real.
+			this.#recoverOrReport(error);
+			return;
+		}
+		// Tested on the file's own parse, before any env overlay: `''`, `'\n'` and a truncated
+		// document all parse to null, and an env-configured deployment would otherwise overlay
+		// one into a valid-looking object and adopt it. A file that is still unusable once the
+		// budget is spent is taken at face value, so emptying one still reaches `remove`.
+		if (!parsed || typeof parsed !== 'object') {
+			if (this.#partialRead.schedule(() => this.#handleChange())) return;
+			this.#partialRead.gaveUp();
+		} else {
+			this.#partialRead.settled();
+		}
+		try {
+			this.#applyParsed(this.#overlayEnvConfig(parsed));
+		} catch (error) {
+			// Applying is past the point where an incomplete file could explain a failure, so a
+			// listener's throw keeps the error route rather than being retried.
+			this.emit('error', error);
+		}
+	}
+
+	#recoverOrReport(error: unknown) {
+		if (!isPartialReadError(error)) return this.#handleReadError(error);
+		if (this.#partialRead.schedule(() => this.#handleChange())) return;
+		// Same give-up as the unusable-parse case, so the budget is restored for the repair: the
+		// write that fixes the file can itself be read mid-write. The error still takes the
+		// scope's own route.
+		this.#partialRead.gaveUp(error);
+		this.#handleReadError(error);
+	}
+
+	#overlayEnvConfig(parsed: unknown) {
+		// The on-disk root config is not guaranteed to include runtime env config at
+		// boot: the file flush races component loading, so a scope's boot-time reads
+		// (e.g. an `enabled` gate in handleApplication) could observe pre-env values
+		// the componentLoader itself never saw. Ask the config layer to overlay env
+		// config onto EVERY root-config read so scope.options matches the resolved
+		// view (#1618). Non-root scopes and the no-env-vars case are untouched
+		// (overlayRootEnvConfig is a no-op there).
+		return this.#isRootConfig ? overlayRootEnvConfig(parsed) : parsed;
+	}
+
+	#applyParsed(parsed: unknown) {
+		this.#rootConfig = parsed && typeof parsed === 'object' ? (parsed as Config) : undefined;
+		// If the extension is in the config file
+		if (this.#rootConfig && this.#name in this.#rootConfig) {
+			// If a config object does not exist
+			if (!this.#scopedConfig) {
+				// set it
+				this.#scopedConfig = this.#rootConfig[this.#name];
+				// and emit a ready event
+				this.emit('ready', this.#scopedConfig);
+			} else {
+				// Otherwise, merge the new config with the old config
+				this.#merge(this.#rootConfig[this.#name], this.#scopedConfig);
+			}
+		} else {
+			// Otherwise, if the extension is not in the config file
+			// This means the plugin was removed from the config file
+			if (this.#scopedConfig) {
+				// and a config exists, remove it
+				this.#scopedConfig = undefined;
+				this.emit('remove');
+			}
+			// Otherwise do nothing - the user may add the config back in later
+		}
+	}
+
+	#handleReadError(error: unknown) {
+		// If the config file does not exist
+		if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+			// A readFile ENOENT here is the install window (file not written yet) or a
+			// transient read race — NOT a real deletion, which chokidar routes to
+			// `#handleUnlink`. Env config is file-independent, so when it provides this
+			// scope the missing file must not discard it (#1618). When it does not, fall
+			// through to the original ENOENT handling with #rootConfig untouched, so a
+			// first boot still emits `ready` (not `remove`, which nothing consumes at
+			// boot → `ready` would hang forever).
+			if (this.#applyEnvOnlyConfig()) return;
+			// And a config already exists, reset it to the default
+			if (this.#rootConfig) {
+				this.#resetConfig();
+				this.emit('remove');
+			} else {
+				// Otherwise, if no config exists, then just set to default and emit ready
+				this.#resetConfig();
+				this.emit('ready');
+			}
+			return;
+		}
+		this.emit('error', error);
+	}
+
 	#handleError(error: unknown) {
+		// See EntryHandler.#handleWatcherError: a lost native watch handle is benign
+		// and must not be surfaced to consumers as a config-watch failure.
+		if (claimLostNativeWatchError(error)) return;
 		if (isWatcherExhaustionError(error)) {
 			// Swallow every exhaustion error — chokidar can emit several before the
 			// failed native watcher closes, and we don't want a flurry of ENOSPC to
@@ -199,18 +267,17 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 			if (!this.#usingPolling) {
 				warnWatcherFallback(this.#filePath);
 				this.#usingPolling = true;
-				// Close the failed native watcher and reopen with polling. Guard
-				// against reopen-after-close: the caller may have invoked close()
-				// while this teardown was in flight. The .catch is required because
-				// `finally` would re-raise a teardown rejection as an unhandled one.
-				this.#watcher
-					.close()
+				// Start close() from a microtask, not directly here, so a synchronous throw
+				// can't escape this 'error' listener as an uncaught exception.
+				Promise.resolve()
+					.then(() => this.#watcher.close())
 					.catch(() => {
 						// Teardown errors on an already-failed watcher are not actionable.
 					})
-					.finally(() => {
+					.then(() => {
 						if (!this.#closed) this.#openWatcher();
-					});
+					})
+					.catch((error) => this.#logger.error?.(`Could not reopen the ${this.#filePath} watch on polling:`, error));
 			}
 			return;
 		}
@@ -385,6 +452,14 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 		this.emit('change', keys, value, this.#scopedConfig);
 	}
 
+	// Test-only: run the change handler directly, since the read's timing relative to its caller
+	// is the behaviour under test and a chokidar event cannot be observed at that granularity.
+	// Resolves once the read has landed, which for the root config has already happened.
+	_handleChangeForTests(): Promise<unknown> {
+		this.#handleChange();
+		return Promise.allSettled([...this.#pendingReads]);
+	}
+
 	// Test-only: simulate the underlying chokidar watcher emitting an error.
 	// Exposed so the polling-fallback path can be exercised without triggering a
 	// real ENOSPC/EMFILE on the host.
@@ -411,6 +486,7 @@ export class OptionsWatcher extends EventEmitter<OptionsWatcherEventMap> {
 	 */
 	close(): Promise<this> {
 		this.#closed = true;
+		this.#partialRead.cancel();
 		const pendingReads = [...this.#pendingReads];
 		const watcherClose = Promise.resolve(this.#watcher.close()).catch(() => {});
 

package/components/RuntimeModuleTracker.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { lstatSync, readFileSync, readlinkSync } from 'node:fs';
+import { lstatSync, readFileSync, readlinkSync, realpathSync } from 'node:fs';
 import { lstat, readFile, readlink } from 'node:fs/promises';
 import { createRequire, Module } from 'node:module';
 import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
@@ -43,7 +43,7 @@ export class RuntimeModuleTracker {
 	recordModule(moduleUrl: string, source: Source): void {
 		const modulePath = this.#localPath(moduleUrl);
 		if (!modulePath) return;
-		if (!this.#modules.has(modulePath)) this.#modules.set(modulePath, digest(source));
+		if (!this.#modules.has(modulePath)) this.#modules.set(modulePath, moduleDigest(modulePath, source));
 		if (this.#deployInFlight) this.#loadedDuringDeploy = true;
 	}
 
@@ -78,7 +78,7 @@ export class RuntimeModuleTracker {
 			const changed = await Promise.all(
 				modules.slice(start, start + MODULE_COMPARE_CONCURRENCY).map(async ([modulePath, previousDigest]) => {
 					try {
-						return digest(await readFile(modulePath)) !== previousDigest;
+						return moduleDigest(modulePath, await readFile(modulePath)) !== previousDigest;
 					} catch {
 						return true;
 					}
@@ -138,8 +138,21 @@ function higherPriorityResolutionCandidates(
 	const candidates = [...new Set(RESOLUTION_EXTENSIONS.map((extension) => basePath + extension))];
 	candidates.push(resolve(basePath, 'package.json'));
 	for (const extension of RESOLUTION_EXTENSIONS.slice(1)) candidates.push(resolve(basePath, `index${extension}`));
-	const resolvedIndex = candidates.indexOf(resolvedPath);
-	if (resolvedIndex === -1) return;
+	let resolvedIndex = candidates.indexOf(resolvedPath);
+	if (resolvedIndex === -1) {
+		let canonicalResolvedPath = resolvedPath;
+		try {
+			canonicalResolvedPath = realpathSync(resolvedPath);
+		} catch {}
+		resolvedIndex = candidates.findIndex((candidate) => {
+			try {
+				return realpathSync(candidate) === canonicalResolvedPath;
+			} catch {
+				return false;
+			}
+		});
+	}
+	if (resolvedIndex === -1) return candidates.slice(0, RESOLUTION_EXTENSIONS.length + 1);
 	return candidates.slice(0, resolvedIndex);
 }
 
@@ -149,7 +162,7 @@ function candidateState(path: string): string {
 		if (stats.isSymbolicLink()) return `link:${readlinkSync(path)}`;
 		if (stats.isDirectory()) return 'directory';
 		if (!stats.isFile()) return 'other';
-		return path.endsWith('package.json') ? `file:${digest(readFileSync(path))}` : 'file';
+		return path.endsWith('package.json') ? `file:${moduleDigest(path, readFileSync(path))}` : 'file';
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';
 		return `error:${(error as NodeJS.ErrnoException).code ?? 'unknown'}`;
@@ -162,7 +175,7 @@ async function candidateStateAsync(path: string): Promise<string> {
 		if (stats.isSymbolicLink()) return `link:${await readlink(path)}`;
 		if (stats.isDirectory()) return 'directory';
 		if (!stats.isFile()) return 'other';
-		return path.endsWith('package.json') ? `file:${digest(await readFile(path))}` : 'file';
+		return path.endsWith('package.json') ? `file:${moduleDigest(path, await readFile(path))}` : 'file';
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'missing';
 		return `error:${(error as NodeJS.ErrnoException).code ?? 'unknown'}`;
@@ -187,3 +200,21 @@ function invalidateResolutionCache(specifier: string, referrerPath: string, prev
 function digest(source: Source): string {
 	return createHash('sha256').update(source).digest('base64');
 }
+
+function moduleDigest(path: string, source: Source): string {
+	if (path.endsWith('package.json')) {
+		try {
+			return digest(JSON.stringify(canonicalizeJSON(JSON.parse(source.toString()))));
+		} catch {}
+	}
+	return digest(source);
+}
+
+function canonicalizeJSON(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(canonicalizeJSON);
+	if (!value || typeof value !== 'object') return value;
+	const canonical: Record<string, unknown> = Object.create(null);
+	for (const key of Object.keys(value).sort())
+		canonical[key] = canonicalizeJSON((value as Record<string, unknown>)[key]);
+	return canonical;
+}

package/components/Scope.ts

@@ -1,7 +1,7 @@
 import { type Logger } from '../utility/logging/logger.ts';
 import { loggerWithTag } from '../utility/logging/harper_logger.ts';
 import { EventEmitter, once } from 'node:events';
-import { databaseEventsEmitter, table } from '../resources/databases.ts';
+import { databaseEventsEmitter, scopedTableFactory } from '../resources/databases.ts';
 import { server, type Server } from '../server/Server.ts';
 import { EntryHandler, type EntryHandlerEventMap, type onEntryEventHandler } from './EntryHandler.ts';
 import { OptionsWatcher, OptionsWatcherEventMap } from './OptionsWatcher.ts';
@@ -241,7 +241,7 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 
 	ensureTable<TableResourceType = unknown>(options: any): TableResourceType {
 		options.origin = this.#origin;
-		return table<TableResourceType>(options);
+		return scopedTableFactory(this.applicationScope?.branches)<TableResourceType>(options);
 	}
 
 	#handleOptionsWatcherReady(): void {
@@ -461,33 +461,55 @@ export class Scope extends EventEmitter<ScopeEventsMap> {
 			targetEntryHandler: EntryHandler,
 			entryEventHandler: onEntryEventHandler
 		): onEntryEventHandler => {
-			const pendingOperations = new Set<Promise<void>>();
+			// Retained until the drain below reports them: an operation dropped as it settles is invisible
+			// to that drain, so a handler rejecting before `ready` would report nothing at all.
+			let initialOperations: Promise<void>[] | null = [];
 
 			const wrapped: onEntryEventHandler = (entry) => {
-				const result = entryEventHandler(entry);
+				let result;
+				try {
+					result = entryEventHandler(entry);
+				} catch (error) {
+					// A synchronous throw is the same failure as a rejection. Left to propagate, EntryHandler
+					// catches it for its own reporting and the initial load completes as if nothing failed.
+					result = Promise.reject(error);
+				}
 				if (result instanceof Promise) {
-					const tracked = result
-						.catch((error) => {
-							this.#logger.error?.('Error in async entry handler:', error);
+					const tracked = result.catch((error) => {
+						this.#logger.error?.('Error in async entry handler:', error);
+						try {
 							this.#handleError(error);
-							throw error;
-						})
-						.finally(() => pendingOperations.delete(tracked));
-					pendingOperations.add(tracked);
+						} catch (reportingError) {
+							// Reporting must not replace the failure it is reporting.
+							this.#logger.error?.('Error reporting an entry handler failure:', reportingError);
+						}
+						throw error;
+					});
+					// Nothing awaits `tracked` until the drain, which leaves an early rejection unhandled.
+					tracked.catch(() => {});
+					initialOperations?.push(tracked);
 				}
 			};
 
-			// When the entry handler's initial scan completes, wait for all pending async operations
+			// When the entry handler's initial scan completes, wait for all of its async operations
 			const initialLoadPromise = once(targetEntryHandler, 'ready').then(async () => {
-				if (pendingOperations.size > 0) {
-					await Promise.all(pendingOperations);
+				const operations = initialOperations ?? [];
+				initialOperations = null;
+				// Drained, not fail-fast: the loader holds the plugin-wide load lock until this settles, so a
+				// first failure reported while a sibling still runs would let the next application in.
+				for (const result of await Promise.allSettled(operations)) {
+					if (result.status === 'rejected') throw result.reason;
 				}
 				targetEntryHandler.emit('initialLoadComplete');
 			});
 
 			// Track this promise so the component loader can await it
 			this.#pendingInitialLoads.add(initialLoadPromise);
-			initialLoadPromise.finally(() => this.#pendingInitialLoads.delete(initialLoadPromise));
+			// Two-branch cleanup, not `.finally`: its derivative would reject with nobody left to handle it.
+			const forgetInitialLoad = () => {
+				this.#pendingInitialLoads.delete(initialLoadPromise);
+			};
+			initialLoadPromise.then(forgetInitialLoad, forgetInitialLoad);
 
 			return wrapped;
 		};