@deepseek-ai/dsh-hmr 0.2.0-rc.2 → 0.2.1-alpha.2

package/README.i18n.yaml

@@ -21,8 +21,8 @@
   en: 45ee194ad781d603
   zh: b3d7fcd8ed73717c
 /deepseek-ai-dsh-hmr/understand-the-implementation:
-  en: 5c7ff789d5d6b653
-  zh: 46ef96a031ac87bd
+  en: 227c3c99c3c4b597
+  zh: 853b656340cb8bce
 /deepseek-ai-dsh-hmr/model-experience:
   en: 215e7ba838619b7b
   zh: a311da3843709f90
@@ -39,8 +39,8 @@
   en: 89e0624fafd701fb
   zh: 19d36a33c1d9af9d
 /deepseek-ai-dsh-hmr/known-limitations-and-deferred-work:
-  en: 379bc2c72fd9e53e
-  zh: 1fff1e0e676bb161
+  en: 0f46d4df1dab7f3b
+  zh: d172835159a20cce
 /deepseek-ai-dsh-hmr/known-limitations-and-deferred-work/dev-note:
   en: 7972e4b2005ec9a4
   zh: 754c49ec538c164c

package/README.md

@@ -56,7 +56,15 @@ Chokidar options, including polling, retain their existing meaning. Exact config
 
 `watchConfig()` registers an awaited configuration handler. `runExclusive()` serializes configuration changes and Loader updates with automatic reloads and rejects nested transactions. Package installation and removal run outside this queue. HMR does not acquire the package writer lock; manifest notifications reload only when the ordered `dsh.profile.bundles` list changes. Profile and home patch changes also trigger recomposition. File events received during a configuration transaction are processed afterward. Include refreshes and profile reconciliation reach plugins through ordinary Loader entry updates; Loader commits volatile-only changes in place.
 
-App-boot owns profile parsing and patch precedence. HMR reads the launcher’s data-only `profileContext`, registers the profile manifest and both user patch watches during initialization, and waits for application readiness before processing changes. Its disposal closes the watchers and cancels reloads waiting for startup. HMR also owns module-cache replacement and reload scheduling. Configuration watchers start outside the active transaction context so later notifications can enter the queue. No invariant companion is published because the queue and watcher registrations have no independent persisted projection.
+App-boot owns profile parsing and patch precedence. HMR reads the launcher’s data-only `profileContext`, registers the profile manifest and both user patch watches during initialization, and waits for application readiness before processing changes. Its disposal closes the watchers and cancels reloads waiting for startup. Configuration watchers start outside the active transaction context so later notifications can enter the queue.
+
+A changed `package.json` outside `node_modules` expires that package's cached configuration. A configuration-only manifest triggers no module reload; a manifest imported as a JSON module retains dependency-driven reloads, and one in the host dependency graph retains host reloads. Dedicated configuration watches keep their existing ownership. A new package entry takes effect when its Loader entry restarts.
+
+Loader entries retain their raw import results. HMR retains every distinct imported namespace for each entry name and configuration-tree base URL; an uninitialized entry does not overwrite another entry's namespace. HMR matches those objects to cached ModuleJob namespaces instead of resolving entry names again. Names without an imported namespace and `cordis:` builtins keep name-based resolution. Source reloads therefore use the loaded modules after `exports` or `main` changes.
+
+Entries sharing a runtime are replaced together, with each entry receiving the implementation for its own module. Duplicate entries for one module retain their separate plugin instances. On replacement failure, HMR removes partially activated replacements and restores the previous modules and plugin implementations. A successful reload updates every matching entry record, including disabled entries; a failed replacement leaves those records unchanged. Entries that have never loaded remain uninitialized.
+
+[package-manifest.ts](src/package-manifest.ts) owns the Node internal interfaces for package reads, scope, type, and nearest-manifest lookups. Each HMR instance owns its configuration cache and restores its installed hooks on disposal. Manifest invalidation clears the ESM `ResolveCache` and CommonJS `_pathCache`: neither records every consulted manifest, and entries may point outside their package directory. CommonJS loads resolve requests with Node's default resolver before entering the native loader, bypassing old request aliases while preserving evaluated modules. Synchronous resolve hooks receive the resulting filenames. Ordinary module replacement remains HMR's separate operation.
 
 Watched module paths use Node ESM resolution's `realpathSync()` spelling, including Windows short directory names, so file events match the module cache.
 
@@ -86,7 +94,11 @@ Reloading a contributing plugin can change later request prefixes; HMR does not
 <a id="known-limitations-and-deferred-work"></a>
 
 - Module replacement requires Node loader internals. Framework dependency changes call the host-provided `loader.exit()` hook; HMR itself does not restart the process.
-- Replacing installed package versions still requires a restart through Plugin Manager. The browser Client module graph retains its separate browser-side loading mechanism.
+- Replacing installed package versions still requires a restart through Plugin Manager; manifests below `node_modules` keep Node's cached configuration. The browser Client module graph retains its separate browser-side loading mechanism.
+- TSX loaders and ordinary application-created Workers are outside the supported package-cache refresh scope.
+- CommonJS requests must be resolvable by Node's default resolver. Synchronous hooks may postprocess the resulting filenames, as Desktop's Office resolver does; hooks requiring the original request name or introducing virtual requests are unsupported. Builtins retain Node's original loading behavior.
+- Future work: retain package invalidation across HMR disposal and replacement. Restoring the native readers can expose their older cached configuration again.
+- If a shared runtime's replacement modules have different plugin callbacks, an instance without a Loader entry cannot be assigned to one of them. HMR reports an ambiguity error and rolls back the reload.
 - `watchConfig()` resolves when Chokidar reports readiness. On darwin, libuv starts the FSEvents stream afterwards on its own thread, so a write that lands within milliseconds of registration is not reported until the next event in that directory; edits made after startup are unaffected.
 
 ### Dev Note

package/README.zh.md

@@ -56,7 +56,15 @@ Chokidar 选项（包括轮询）保持原有含义。精确配置监听同时
 
 `watchConfig()` 注册会被等待的配置处理器。`runExclusive()` 将配置变更、Loader 更新与自动重载串行化，并拒绝嵌套事务。包安装和删除在该队列之外执行。HMR 不获取包操作写锁；manifest 通知仅在有序的 `dsh.profile.bundles` 列表变化时触发重载。profile 与 home patch 变化也会触发重新组合。配置事务期间收到的文件事件在事务结束后处理。 Include 刷新和 profile 重载都通过普通的 Loader 条目更新到达插件；仅 volatile 变化由 Loader 就地提交。
 
-App-boot 负责 profile 解析和 patch 优先级规则。HMR 读取启动器提供的纯数据 `profileContext`，在初始化时注册 profile manifest 和两份用户 patch 的监听，并等待应用就绪后处理更改。销毁 HMR 时会关闭监听器并取消等待启动的重载。HMR 也负责模块缓存替换和重载调度。配置监听器在当前事务上下文之外启动，使后续通知可以进入队列。不发布 invariant 伴生入口，因为队列和监听注册没有独立的持久投影。
+App-boot 负责 profile 解析和 patch 优先级规则。HMR 读取启动器提供的纯数据 `profileContext`，在初始化时注册 profile manifest 和两份用户 patch 的监听，并等待应用就绪后处理更改。销毁 HMR 时会关闭监听器并取消等待启动的重载。配置监听器在当前事务上下文之外启动，使后续通知可以进入队列。
+
+`node_modules` 之外的 `package.json` 变化使该包的配置缓存失效。仅作为配置的 manifest 不触发模块重载；作为 JSON 模块导入的 manifest 保留依赖驱动重载，位于宿主依赖图中的 manifest 保留宿主重载。专属配置监听保留原有归属。新包入口在 Loader entry 重启时生效。
+
+Loader entry 保留原始导入结果。HMR 为每个 entry 名称与配置树 base URL 保留所有不同的已导入命名空间；尚未初始化的 entry 不会覆盖其他 entry 的命名空间。HMR 将这些对象与缓存中 ModuleJob 的模块命名空间按对象身份匹配，不再重新解析 entry 名称。没有已导入命名空间的名称和 `cordis:` 内置入口仍按名称解析。因此 `exports` 或 `main` 改变后，源码重载仍使用已加载模块。
+
+共享同一运行时的 entry 一起替换，每个 entry 使用其自身模块对应的实现。同一模块的重复 entry 仍保有各自的插件实例。替换失败时，HMR 清理已部分激活的替换实例，并恢复原来的模块和插件实现。重载成功后更新所有匹配的 entry 记录，包括已停用的 entry；替换失败时这些记录保持不变。从未加载过的 entry 仍保持未初始化状态。
+
+[package-manifest.ts](src/package-manifest.ts) 封装 package 读取、scope、type 和最近 manifest 查询所需的 Node internal 接口。每个 HMR 实例拥有自己的配置缓存，销毁时恢复它安装的 hook。manifest 失效会清空 ESM `ResolveCache` 和 CommonJS `_pathCache`：它们都不记录查询过的全部 manifest，入口也可能指向包目录之外。CommonJS 加载先用 Node 默认 resolver 解析请求，再进入原生 loader，绕过旧请求别名并保留已求值模块。同步 resolve hook 收到的是解析后的文件名。普通模块替换仍由 HMR 独立处理。
 
 被监听模块的路径沿用 Node ESM 解析所用的 `realpathSync()` 表示，包括 Windows 短目录名，使文件事件与模块缓存匹配。
 
@@ -86,7 +94,11 @@ App-boot 负责 profile 解析和 patch 优先级规则。HMR 读取启动器提
 <a id="known-limitations-and-deferred-work"></a>
 
 - 模块替换需要 Node loader 内部接口。框架依赖变化调用宿主提供的 `loader.exit()` 钩子；HMR 本身不重启进程。
-- 通过插件管理器替换已安装包版本仍需要重启。浏览器 Client 模块图保留独立的浏览器侧加载机制。
+- 通过插件管理器替换已安装包版本仍需要重启；`node_modules` 之下的 manifest 保留 Node 缓存的配置。浏览器 Client 模块图保留独立的浏览器侧加载机制。
+- TSX loader 和普通应用自行创建的 Worker 不在包缓存刷新支持范围内。
+- CommonJS 请求必须能由 Node 默认 resolver 解析。同步 hook 可以像 Desktop 的 Office resolver 一样处理解析后的文件名；依赖原始请求名或引入虚拟请求的 hook 不受支持。内置模块保留 Node 原有的加载行为。
+- 后续工作：跨 HMR 销毁和替换保留包配置失效状态。恢复原生 reader 后，其旧配置缓存可能重新可见。
+- 如果共享运行时的替换模块具有不同的插件回调，没有 Loader entry 的实例就无法确定应使用哪一个。HMR 会报告歧义错误并回滚此次重载。
 - `watchConfig()` 在 Chokidar 报告就绪时 resolve。darwin 上 libuv 随后才在自己的线程启动 FSEvents 流，因此注册后数毫秒内落地的写入要等到该目录的下一个事件才会被报告；启动之后的编辑不受影响。
 
 ### 开发备注

package/lib/index.js

@@ -1,12 +1,14 @@
-import { createRequire } from "node:module";
+import { createRequire, isBuiltin } from "node:module";
+import assert from "node:assert/strict";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve, sep, toNamespacedPath } from "node:path";
 import { realpath, stat } from "node:fs/promises";
 import { watch } from "chokidar";
 import { Inject, Service } from "@deepseek-ai/cordis";
 import { readFileSync, realpathSync } from "node:fs";
 import { PROFILE_PATCH_FILENAME, readProfileManifest, readProfilePatches, reconcileProfilePatches } from "@deepseek-ai/dsh-app-boot";
 import { codeFrameColumns } from "@babel/code-frame";
+import { isUtf8 } from "node:buffer";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import picomatch from "picomatch";
 import z from "@deepseek-ai/schemastery";
@@ -82,18 +84,24 @@ async function watchConfig(ctx, filename, options, refresh, inTransaction = () =
 	watcher.on("unlink", onChange);
 	const ready = Promise.withResolvers();
 	let pending = true;
+	let disposed = false;
 	watcher.once("ready", () => {
 		pending = false;
 		ready.resolve();
 	});
-	watcher.on("error", (error) => {
+	const onError = (error) => {
+		if (disposed) return;
 		if (pending) {
 			pending = false;
 			ready.reject(error);
 		} else ctx.logger.warn(error);
-	});
+	};
+	watcher.on("error", onError);
 	const dispose = async () => {
-		await watcher.close();
+		disposed = true;
+		const closing = watcher.close();
+		watcher.on("error", onError);
+		await closing;
 		paths.delete(target.filename);
 		if (!inTransaction()) await running;
 	};
@@ -140,6 +148,250 @@ function handleError(ctx, e) {
 	}
 }
 //#endregion
+//#region lib/types/package-manifest.js
+/** Expire Node's cached package configuration for package directories whose manifest changed. */
+/** Snapshot own methods; each disposer restores its method only while its replacement is still installed. */
+function createReplaceHelper(target) {
+	const rawImpl = { ...target };
+	return {
+		rawImpl,
+		replaceMethod(key, replacement) {
+			target[key] = replacement;
+			return () => {
+				if (target[key] === replacement) target[key] = rawImpl[key];
+			};
+		}
+	};
+}
+/** Same lookup as the vendored Loader's `requireInternal`: `--expose-internals` first, then the builtin addon. */
+function requireInternal(id) {
+	const require = createRequire(import.meta.url);
+	if (process.execArgv.includes("--expose-internals")) try {
+		return require(id);
+	} catch (_error) {}
+	try {
+		return require("node-addon-require-builtin").requireBuiltin(id);
+	} catch (_error) {}
+}
+function loadNodeInternals() {
+	const realm = requireInternal("internal/bootstrap/realm");
+	const esm = requireInternal("internal/modules/esm/loader");
+	return {
+		binding: realm.internalBinding("modules"),
+		reader: requireInternal("internal/modules/package_json_reader"),
+		ResolveCache: requireInternal("internal/modules/esm/module_map").ResolveCache,
+		cjs: requireInternal("internal/modules/cjs/loader").Module,
+		esmLoader: esm.getOrInitializeCascadedLoader()
+	};
+}
+/**
+* Read the ESM loader's resolution cache by observing one lookup through its prototype.
+* The prototype method is restored before this returns.
+*/
+function captureEsmResolveCache(native, parentURL) {
+	const prototype = native.ResolveCache.prototype;
+	const original = prototype.get;
+	const seen = /* @__PURE__ */ new Set();
+	prototype.get = function(key, parent) {
+		seen.add(this);
+		return Reflect.apply(original, this, [key, parent]);
+	};
+	try {
+		const loader = native.esmLoader;
+		/* v8 ignore else -- CI coverage runs the Node 24 loader; the Node 22 matrix exercises the v1 signature */
+		if ("getOrCreateModuleJob" in loader) loader.resolveSync(parentURL, {
+			specifier: "node:path",
+			attributes: {}
+		});
+		else loader.resolveSync("node:path", parentURL, {});
+	} finally {
+		prototype.get = original;
+	}
+	return [...seen][0];
+}
+/** Package directories whose manifests are read from disk instead of Node's native cache. */
+var PackageManifests = class {
+	directories = /* @__PURE__ */ new Set();
+	configurations = /* @__PURE__ */ new Map();
+	/** Real directory of each directory a lookup reached; linked consumers name a package by its link path. */
+	realDirectories = /* @__PURE__ */ new Map();
+	native;
+	rawBinding;
+	rawReader;
+	rawCommonJs;
+	restorers = [];
+	/**
+	* Expire cached configuration for one package directory. Loaded modules stay evaluated; later resolutions and
+	* format checks read the manifest on disk.
+	* @param manifest - absolute path of the changed `package.json`.
+	*/
+	invalidate(manifest) {
+		const native = this.installPackageHooks();
+		const directory = dirname(manifest);
+		this.directories.add(directory);
+		this.configurations.clear();
+		this.realDirectories.clear();
+		for (const key of Object.keys(native.cjs._pathCache)) Reflect.deleteProperty(native.cjs._pathCache, key);
+		const cache = captureEsmResolveCache(native, pathToFileURL(directory).href + "/");
+		/* v8 ignore else -- asynchronous loader hooks own a separate cache; loader-thread invalidation is deferred */
+		if (cache !== void 0) Map.prototype.clear.call(cache);
+	}
+	/** Restore every replaced Node method this instance installed. */
+	dispose() {
+		for (const restore of this.restorers.splice(0).reverse()) restore();
+		this.native = void 0;
+		this.realDirectories.clear();
+	}
+	isPathWithinDirectory(path, directory) {
+		return path === directory || path.startsWith(join(directory, sep));
+	}
+	isPathInInvalidatedDirectory(path) {
+		const parent = dirname(path);
+		let real = this.realDirectories.get(parent);
+		if (real === void 0) {
+			try {
+				real = realpathSync(parent);
+			} catch (_error) {
+				real = parent;
+			}
+			this.realDirectories.set(parent, real);
+		}
+		const target = join(real, basename(path));
+		for (const directory of this.directories) if (this.isPathWithinDirectory(target, directory)) return true;
+		return false;
+	}
+	isUrlInInvalidatedDirectory(url) {
+		try {
+			return this.isPathInInvalidatedDirectory(fileURLToPath(url));
+		} catch (_error) {
+			return false;
+		}
+	}
+	installPackageHooks() {
+		if (this.native !== void 0) return this.native;
+		const native = loadNodeInternals();
+		this.native = native;
+		const binding = createReplaceHelper(native.binding);
+		const reader = createReplaceHelper(native.reader);
+		const commonJs = createReplaceHelper(native.cjs);
+		this.rawBinding = binding.rawImpl;
+		this.rawReader = reader.rawImpl;
+		this.rawCommonJs = commonJs.rawImpl;
+		this.restorers.push(binding.replaceMethod("readPackageJSON", this.hookBindingReadPackageJSON.bind(this)), binding.replaceMethod("getPackageScopeConfig", this.hookBindingGetPackageScopeConfig.bind(this)), binding.replaceMethod("getPackageType", this.hookBindingGetPackageType.bind(this)), reader.replaceMethod("getNearestParentPackageJSON", this.hookReaderGetNearestParentPackageJSON.bind(this)), commonJs.replaceMethod("_load", this.hookCommonJsLoad.bind(this)));
+		return native;
+	}
+	hookCommonJsLoad(...[request, parent, isMain, ...options]) {
+		const native = this.installPackageHooks();
+		const filename = request.startsWith("node:") || isBuiltin(request) ? request : native.cjs._resolveFilename(request, parent, isMain);
+		return this.rawCommonJs._load.call(native.cjs, filename, parent, isMain, ...options);
+	}
+	hookBindingReadPackageJSON(path, isEsm, base, specifier) {
+		return this.isPathInInvalidatedDirectory(path) ? this.readCachedPackageConfig(path, isEsm && base !== void 0 ? {
+			base,
+			specifier
+		} : void 0)?.serialized : this.rawBinding.readPackageJSON(path, isEsm, base, specifier);
+	}
+	hookBindingGetPackageScopeConfig(url) {
+		if (!this.isUrlInInvalidatedDirectory(url)) return this.rawBinding.getPackageScopeConfig(url);
+		const found = this.findNearestPackageConfig(fileURLToPath(url), true);
+		if (typeof found === "string") return this.rawBinding.getPackageScopeConfig(pathToFileURL(found).href);
+		return found.configuration?.serialized ?? found.path;
+	}
+	hookBindingGetPackageType(url) {
+		if (!this.isUrlInInvalidatedDirectory(url)) return this.rawBinding.getPackageType(url);
+		const found = this.findNearestPackageConfig(fileURLToPath(url), true);
+		return typeof found === "string" ? this.rawBinding.getPackageType(pathToFileURL(found).href) : found.configuration?.data.type;
+	}
+	hookReaderGetNearestParentPackageJSON(path) {
+		if (!this.isPathInInvalidatedDirectory(path)) return this.rawReader.getNearestParentPackageJSON(path);
+		const found = this.findNearestPackageConfig(path, false);
+		if (typeof found === "string") return this.rawReader.getNearestParentPackageJSON(found);
+		if (found.configuration === void 0) return this.rawReader.getNearestParentPackageJSON(path);
+		return {
+			data: found.configuration.data,
+			exists: true,
+			path: found.path
+		};
+	}
+	readCachedPackageConfig(path, context) {
+		if (!this.configurations.has(path)) this.configurations.set(path, this.readPackageConfigFromDisk(path, context));
+		return this.configurations.get(path);
+	}
+	/** A string names the first manifest outside the invalidated directories; Node answers for it. */
+	findNearestPackageConfig(path, includeRoot) {
+		let directory = dirname(path);
+		while (true) {
+			const manifest = join(directory, "package.json");
+			const parent = dirname(directory);
+			if (basename(directory) === "node_modules" || !includeRoot && parent === directory) return { path: manifest };
+			if (!this.isPathInInvalidatedDirectory(manifest)) return manifest;
+			const configuration = this.readCachedPackageConfig(manifest);
+			if (configuration !== void 0) return {
+				path: toNamespacedPath(manifest),
+				configuration
+			};
+			/* v8 ignore next -- root-scope queries run in an isolated child to contain non-termination */
+			if (parent === directory) return { path: manifest };
+			directory = parent;
+		}
+	}
+	/** @param context - optional ESM import details used only when reporting invalid package configuration. */
+	readPackageConfigFromDisk(path, context) {
+		let bytes;
+		try {
+			bytes = readFileSync(path);
+		} catch (_error) {
+			return;
+		}
+		const throwInvalidPackageConfig = () => {
+			const base = context?.base;
+			const importing = base === void 0 ? "" : ` while importing "${context?.specifier}" from ${base.startsWith("file:") ? fileURLToPath(base) : base}`;
+			throw Object.assign(/* @__PURE__ */ new Error(`Invalid package config ${toNamespacedPath(path)}${importing}.`), { code: "ERR_INVALID_PACKAGE_CONFIG" });
+		};
+		if (!isUtf8(bytes)) return throwInvalidPackageConfig();
+		const source = bytes.toString("utf8");
+		let parsed;
+		try {
+			parsed = JSON.parse(source.charCodeAt(0) === 65279 ? source.slice(1) : source);
+		} catch (_error) {
+			return throwInvalidPackageConfig();
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return throwInvalidPackageConfig();
+		const fields = parsed;
+		if (fields.name !== void 0 && typeof fields.name !== "string") return throwInvalidPackageConfig();
+		if (fields.type !== void 0 && typeof fields.type !== "string") return throwInvalidPackageConfig();
+		for (const key of [
+			"name",
+			"type",
+			"exports",
+			"imports"
+		]) {
+			const value = fields[key];
+			if (typeof value === "string" && !value.isWellFormed()) return throwInvalidPackageConfig();
+		}
+		const normalizePackageJsonField = (value) => value !== null && (typeof value === "string" || typeof value === "object") ? value : void 0;
+		const data = {
+			...typeof fields.name === "string" ? { name: fields.name } : {},
+			...typeof fields.main === "string" && fields.main.isWellFormed() ? { main: fields.main } : {},
+			type: fields.type === "module" || fields.type === "commonjs" ? fields.type : "none",
+			exports: normalizePackageJsonField(fields.exports),
+			imports: normalizePackageJsonField(fields.imports)
+		};
+		const serializePackageJsonField = (value) => value === void 0 ? void 0 : typeof value === "string" ? value : JSON.stringify(value);
+		return {
+			data,
+			serialized: [
+				data.name,
+				data.main,
+				data.type,
+				serializePackageJsonField(data.imports),
+				serializePackageJsonField(data.exports),
+				toNamespacedPath(path)
+			]
+		};
+	}
+};
+//#endregion
 //#region lib/types/index.js
 /** Serialized module and profile-configuration reloads. */
 var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
@@ -206,6 +458,107 @@ async function loadDependencies(job, ignored = /* @__PURE__ */ new Set()) {
 	await traverse(job);
 	return dependencies;
 }
+/** Entry names with distinct namespaces; iteration falls back to undefined only for names without a loaded namespace. */
+var EntryNamespaces = class {
+	internal;
+	moduleUrls;
+	names = /* @__PURE__ */ new Map();
+	constructor(internal, moduleUrls) {
+		this.internal = internal;
+		this.moduleUrls = moduleUrls;
+	}
+	static getModuleUrls(internal) {
+		const moduleUrls = /* @__PURE__ */ new Map();
+		for (const url of internal.loadCache.keys()) {
+			const job = internal.loadCache.get(url);
+			if (!job?.module) continue;
+			try {
+				moduleUrls.set(job.module.getNamespace(), url);
+			} catch (_error) {}
+		}
+		return moduleUrls;
+	}
+	add(name, moduleNamespace) {
+		const namespaces = this.names.get(name) ?? /* @__PURE__ */ new Set();
+		namespaces.add(moduleNamespace);
+		this.names.set(name, namespaces);
+		return this;
+	}
+	*[Symbol.iterator]() {
+		for (const [name, namespaces] of this.names) for (const moduleNamespace of namespaces) {
+			if (moduleNamespace === void 0 && namespaces.size > 1) continue;
+			yield [name, moduleNamespace];
+		}
+	}
+	async resolve(name, baseUrl, moduleNamespace) {
+		if (moduleNamespace === void 0 || name.startsWith("cordis:")) switch (this.internal.version) {
+			case "v1": return await this.internal.resolve(name, baseUrl, {});
+			case "v2": return this.internal.resolveSync(baseUrl, {
+				specifier: name,
+				attributes: {}
+			});
+		}
+		const url = this.moduleUrls.get(moduleNamespace);
+		if (url === void 0) throw new Error(`HMR cannot locate the loaded module for ${name} from ${baseUrl}`);
+		return { url };
+	}
+};
+/** Entry modules belonging to one runtime, keyed by their original namespaces across replacement. */
+var ReloadModules = class ReloadModules {
+	modules = /* @__PURE__ */ new Map();
+	static include(reloads, plugin, job, runtime) {
+		let info = reloads.get(plugin);
+		if (info === void 0 && runtime) info = [...reloads.values()].find((info) => info.runtime === runtime);
+		if (info === void 0) return false;
+		info.modules.add(job, plugin);
+		return true;
+	}
+	add(job, plugin) {
+		assert(job.module, `HMR pending module is missing: ${job.url}`);
+		const moduleNamespace = job.module.getNamespace();
+		this.modules.set(moduleNamespace, {
+			filename: job.url,
+			moduleNamespace,
+			plugin
+		});
+		return this;
+	}
+	async importRemaining(loader, getOuterStack, primary) {
+		const replacements = new ReloadModules();
+		for (const [originalNamespace, { filename }] of this.modules) {
+			if (filename === primary.filename) {
+				replacements.modules.set(originalNamespace, primary);
+				continue;
+			}
+			const moduleNamespace = await loader.import(filename, getOuterStack);
+			const plugin = loader.unwrapExports(moduleNamespace);
+			replacements.modules.set(originalNamespace, {
+				filename,
+				moduleNamespace,
+				plugin
+			});
+		}
+		return replacements;
+	}
+	*getActiveImplementations(ctx, plugin, fibers) {
+		const callbacks = new Set([...this.modules.values()].map((value) => ctx.registry.resolve(value.plugin)));
+		const implementations = fibers.map((previousFiber) => {
+			if (previousFiber.entry === void 0) return [previousFiber, plugin];
+			const replacement = this.modules.get(previousFiber.moduleNamespace);
+			const implementation = replacement ? replacement.plugin : ctx.loader.unwrapExports(previousFiber.moduleNamespace);
+			callbacks.add(ctx.registry.resolve(implementation));
+			return [previousFiber, implementation];
+		});
+		for (const [previousFiber, implementation] of implementations) {
+			if (previousFiber.fiber.parent.fiber.uid === null) continue;
+			if (previousFiber.entry === void 0 && callbacks.size > 1) throw new Error("HMR replacement is ambiguous for a plugin instance without a Loader entry");
+			yield [previousFiber, implementation];
+		}
+	}
+	updateEntries(loader) {
+		for (const [originalNamespace, { moduleNamespace }] of this.modules) for (const entry of loader.entries()) if (entry.moduleNamespace === originalNamespace) entry.moduleNamespace = moduleNamespace;
+	}
+};
 /** Hot reload service with Cordis-compatible module configuration and events. */
 let Hmr = (() => {
 	let _classDecorators = [Inject("loader"), Inject("timer")];
@@ -272,6 +625,7 @@ let Hmr = (() => {
 		applicationReady = Promise.resolve(true);
 		closing = false;
 		configPaths = /* @__PURE__ */ new Set();
+		manifests = new PackageManifests();
 		/** Serialize a caller-owned mutation with all automatic reload paths.
 		* @param operation Work that must not overlap module or configuration replacement.
 		* @returns The operation result after its asynchronous work completes.
@@ -318,23 +672,12 @@ let Hmr = (() => {
 			this.internal = this.ctx.loader.internal;
 			this.baseDir = fileURLToPath(new URL(config.base || ".", ctx.baseUrl));
 		}
-		/**
-		* Resolve a module specifier to a URL, compatible with Node 22-24.
-		*/
-		async _resolve(specifier, parentURL, attrs) {
-			switch (this.internal.version) {
-				case "v1": return await this.internal.resolve(specifier, parentURL, attrs);
-				case "v2": return this.internal.resolveSync(parentURL, {
-					specifier,
-					attributes: attrs
-				});
-			}
-		}
 		async *[Service.init]() {
 			yield async () => {
 				this.closing = true;
 				await this.watcher?.close();
 				if (!this.executing.getStore()) await this.operations;
+				this.manifests.dispose();
 			};
 			const profile = this.ownerContext.get("profileContext");
 			if (profile !== void 0) {
@@ -402,15 +745,18 @@ let Hmr = (() => {
 						const filename = canonicalPath(resolve(watchBaseDir, path));
 						const configuredFilename = resolve(this.baseDir, path);
 						if (this.configPaths.has(filename) || this.configPaths.has(configuredFilename)) continue;
+						const isManifest = basename(filename) === "package.json" && !filename.includes(`${sep}node_modules${sep}`);
+						if (isManifest) this.manifests.invalidate(filename);
 						const url = pathToFileURL(filename).href;
 						if (this.externals.has(url)) {
 							fullReload = true;
 							continue;
 						}
-						if (this.internal.loadCache.has(url)) {
+						if (this.internal.loadCache.has(url) || this.internal.loadCache.has(url, "json")) {
 							this.stashed.add(url);
 							continue;
 						}
+						if (isManifest) continue;
 						const include = [...loader.entries()].map((entry) => entry.subtree).find((tree) => tree?.filename === filename || tree?.filename === configuredFilename);
 						if (include !== void 0) includes.add(include);
 						else this.ctx.emit("hmr/change", url);
@@ -517,16 +863,17 @@ let Hmr = (() => {
 			await this.analyzeChanges();
 			const pending = /* @__PURE__ */ new Map();
 			const reloads = /* @__PURE__ */ new Map();
+			const moduleUrls = EntryNamespaces.getModuleUrls(this.internal);
 			const nameMap = /* @__PURE__ */ new Map();
 			for (const entry of this.ctx.loader.entries()) {
 				const baseUrl = entry.parent.tree.ctx.baseUrl;
 				if (baseUrl === void 0) throw new Error("HMR entry tree has no base URL");
-				const names = nameMap.get(baseUrl) ?? /* @__PURE__ */ new Set();
-				names.add(entry.options.name);
+				const names = nameMap.get(baseUrl) ?? new EntryNamespaces(this.internal, moduleUrls);
+				names.add(entry.options.name, entry.moduleNamespace);
 				nameMap.set(baseUrl, names);
 			}
-			for (const [baseUrl, names] of nameMap) for (const name of names) try {
-				const { url } = await this._resolve(name, baseUrl, {});
+			for (const [baseUrl, names] of nameMap) for (const [name, moduleNamespace] of names) try {
+				const { url } = await names.resolve(name, baseUrl, moduleNamespace);
 				if (this.declined.has(url)) continue;
 				const job = this.internal.loadCache.get(url);
 				const plugin = this.ctx.loader.unwrapExports(job?.module?.getNamespace());
@@ -540,13 +887,21 @@ let Hmr = (() => {
 				this.declined.delete(job.url);
 				const dependencies = [...await loadDependencies(job, this.declined)];
 				this.declined.add(job.url);
+				if (dependencies.length === 0) {
+					pending.delete(job);
+					continue;
+				}
 				if (!dependencies.some((dep) => this.accepted.has(dep))) continue;
 				dependencies.forEach((dep) => this.accepted.add(dep));
+				const runtime = this.ctx.registry.get(plugin);
+				if (ReloadModules.include(reloads, plugin, job, runtime)) continue;
 				reloads.set(plugin, {
 					filename: job.url,
-					runtime: this.ctx.registry.get(plugin)
+					runtime,
+					modules: new ReloadModules().add(job, plugin)
 				});
 			}
+			for (const [job, plugin] of pending) if (ReloadModules.include(reloads, plugin, job, this.ctx.registry.get(plugin))) this.accepted.add(job.url);
 			/**
 			* Clear module caches for all accepted files before re-importing.
 			*
@@ -590,17 +945,26 @@ let Hmr = (() => {
 					return {
 						fiber,
 						entry,
-						config: entry === void 0 ? fiber._config : entry.options.config
+						config: entry === void 0 ? fiber._config : entry.options.config,
+						moduleNamespace: entry?.moduleNamespace
 					};
 				})
 			}));
 			const attempts = [];
 			try {
 				for (const generation of generations) {
-					const replacement = this.ctx.loader.unwrapExports(await this.ctx.loader.import(generation.filename, this.getOuterStack));
+					const moduleNamespace = await this.ctx.loader.import(generation.filename, this.getOuterStack);
+					const replacement = this.ctx.loader.unwrapExports(moduleNamespace);
+					const replacements = await generation.modules.importRemaining(this.ctx.loader, this.getOuterStack, {
+						filename: generation.filename,
+						moduleNamespace,
+						plugin: replacement
+					});
 					attempts.push({
 						...generation,
-						replacement
+						replacement,
+						replacements,
+						activated: []
 					});
 				}
 			} catch (e) {
@@ -608,11 +972,9 @@ let Hmr = (() => {
 				rollback();
 				throw e;
 			}
-			const reload = async (plugin, fibers) => {
-				const activated = [];
-				for (const previousFiber of fibers) {
-					if (previousFiber.fiber.parent.fiber.uid === null) continue;
-					const fiber = previousFiber.fiber.parent.registry.plugin(plugin, previousFiber.config, this.getOuterStack).ctx.fiber;
+			const reload = async (plugin, fibers, replacements = new ReloadModules(), activated = []) => {
+				for (const [previousFiber, implementation] of replacements.getActiveImplementations(this.ctx, plugin, fibers)) {
+					const fiber = previousFiber.fiber.parent.registry.plugin(implementation, previousFiber.config, this.getOuterStack).ctx.fiber;
 					if (previousFiber.entry !== void 0) {
 						fiber.entry = previousFiber.entry;
 						previousFiber.entry.fiber = fiber;
@@ -623,7 +985,7 @@ let Hmr = (() => {
 			};
 			const removed = /* @__PURE__ */ new Set();
 			try {
-				for (const { previous: plugin, replacement, filename, runtime, fibers } of attempts) {
+				for (const { previous: plugin, replacement, filename, runtime, fibers, replacements, activated } of attempts) {
 					if (!runtime) continue;
 					const path = relative(this.baseDir, fileURLToPath(filename));
 					removed.add(plugin);
@@ -635,7 +997,7 @@ let Hmr = (() => {
 						this.ctx.logger.warn(err);
 					}
 					try {
-						await reload(replacement, fibers);
+						await reload(replacement, fibers, replacements, activated);
 						this.ctx.logger.info("reload plugin at %C", path);
 					} catch (err) {
 						this.ctx.logger.warn("failed to reload plugin at %C", path);
@@ -645,12 +1007,14 @@ let Hmr = (() => {
 				}
 			} catch (error) {
 				rollback();
-				for (const { previous: plugin, replacement, fibers } of attempts) {
+				for (const { previous: plugin, fibers, activated } of attempts) {
 					if (!removed.has(plugin)) continue;
 					try {
-						const replacementFibers = [...this.ctx.registry.get(replacement)?.fibers ?? []];
-						this.ctx.registry.delete(replacement);
-						await Promise.allSettled(replacementFibers.map((fiber) => fiber.await()));
+						for (const { runtime } of activated) if (runtime && this.ctx.registry.get(runtime.callback) === runtime) {
+							const replacementFibers = [...runtime.fibers];
+							this.ctx.registry.delete(runtime.callback);
+							await Promise.allSettled(replacementFibers.map((fiber) => fiber.await()));
+						}
 						await reload(plugin, fibers);
 					} catch (err) {
 						this.ctx.logger.warn(err);
@@ -659,6 +1023,7 @@ let Hmr = (() => {
 				throw error;
 			}
 			await this.ctx.loader.await();
+			for (const { replacements } of attempts) replacements.updateEntries(this.ctx.loader);
 			this.ctx.emit("hmr/reload", reloads);
 			this.stashed = /* @__PURE__ */ new Set();
 		}

package/lib/types/index.d.ts

@@ -1,4 +1,5 @@
-import { Context, Service, type Plugin } from '@deepseek-ai/cordis';
+import { Context, Service, type Fiber, type Plugin } from '@deepseek-ai/cordis';
+import type { ModuleJob } from '@deepseek-ai/cordis-plugin-loader';
 import { type ChokidarOptions } from 'chokidar';
 import z from '@deepseek-ai/schemastery';
 declare module '@deepseek-ai/cordis' {
@@ -33,8 +34,30 @@ export interface HmrConfig extends ChokidarOptions {
 /** Module location and runtime retained during a replacement. */
 export interface Reload {
     filename: string;
+    /** Original namespaces and URLs of all entry modules participating in this runtime replacement. */
+    modules: ReloadModules;
     runtime?: Plugin.Runtime | undefined;
 }
+type ReloadFiber = {
+    fiber: Fiber;
+    entry: Fiber['entry'];
+    config: unknown;
+    moduleNamespace: unknown;
+};
+type ReloadModule = {
+    filename: string;
+    moduleNamespace: unknown;
+    plugin: Plugin;
+};
+/** Entry modules belonging to one runtime, keyed by their original namespaces across replacement. */
+declare class ReloadModules {
+    private readonly modules;
+    static include(reloads: ReadonlyMap<Plugin, Reload>, plugin: Plugin, job: ModuleJob, runtime: Plugin.Runtime | undefined): boolean;
+    add(job: ModuleJob, plugin: Plugin): this;
+    importRemaining(loader: Context['loader'], getOuterStack: () => string[], primary: ReloadModule): Promise<ReloadModules>;
+    getActiveImplementations(ctx: Context, plugin: Plugin, fibers: readonly ReloadFiber[]): Generator<[ReloadFiber, Plugin]>;
+    updateEntries(loader: Context['loader']): void;
+}
 /** Hot reload service with Cordis-compatible module configuration and events. */
 declare class Hmr extends Service {
     config: HmrConfig;
@@ -67,6 +90,7 @@ declare class Hmr extends Service {
     private applicationReady;
     private closing;
     private readonly configPaths;
+    private readonly manifests;
     /** Serialize a caller-owned mutation with all automatic reload paths.
      * @param operation Work that must not overlap module or configuration replacement.
      * @returns The operation result after its asynchronous work completes.
@@ -80,10 +104,6 @@ declare class Hmr extends Service {
      */
     watchConfig(filename: string, refresh: () => Promise<void>): Promise<() => Promise<void>>;
     constructor(ctx: Context, config: HmrConfig);
-    /**
-     * Resolve a module specifier to a URL, compatible with Node 22-24.
-     */
-    private _resolve;
     [Service.init](): AsyncGenerator<() => Promise<void>, void, unknown>;
     /** Omit internal HMR frames from module import diagnostics.
      * @returns The preserved outer stack frames.

package/lib/types/package-manifest.d.ts

@@ -0,0 +1,35 @@
+/** Package directories whose manifests are read from disk instead of Node's native cache. */
+export declare class PackageManifests {
+    private readonly directories;
+    private readonly configurations;
+    /** Real directory of each directory a lookup reached; linked consumers name a package by its link path. */
+    private readonly realDirectories;
+    private native;
+    private rawBinding;
+    private rawReader;
+    private rawCommonJs;
+    private readonly restorers;
+    /**
+     * Expire cached configuration for one package directory. Loaded modules stay evaluated; later resolutions and
+     * format checks read the manifest on disk.
+     * @param manifest - absolute path of the changed `package.json`.
+     */
+    invalidate(manifest: string): void;
+    /** Restore every replaced Node method this instance installed. */
+    dispose(): void;
+    private isPathWithinDirectory;
+    private isPathInInvalidatedDirectory;
+    private isUrlInInvalidatedDirectory;
+    private installPackageHooks;
+    private hookCommonJsLoad;
+    private hookBindingReadPackageJSON;
+    private hookBindingGetPackageScopeConfig;
+    private hookBindingGetPackageType;
+    private hookReaderGetNearestParentPackageJSON;
+    private readCachedPackageConfig;
+    /** A string names the first manifest outside the invalidated directories; Node answers for it. */
+    private findNearestPackageConfig;
+    /** @param context - optional ESM import details used only when reporting invalid package configuration. */
+    private readPackageConfigFromDisk;
+}
+//# sourceMappingURL=package-manifest.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-hmr",
   "description": "Coordinated module and profile configuration hot reload",
-  "version": "0.2.0-rc.2",
+  "version": "0.2.1-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -28,29 +28,30 @@
   "author": "Shigma <shigma10826@gmail.com>",
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis-plugin-timer": "~1.1.6",
-    "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
-    "@deepseek-ai/cordis-plugin-include": "~1.0.9",
-    "@deepseek-ai/dsh-app-boot": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-cmdline": "0.2.0-rc.2"
+    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.1",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.1",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.10-alpha.1",
+    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-cmdline": "0.2.1-alpha.2"
   },
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
     "chokidar": "^4.0.3",
-    "picomatch": "^4.0.3",
-    "@deepseek-ai/schemastery": "~3.18.4"
+    "node-addon-require-builtin": "^0.1.9",
+    "picomatch": "^4.0.7",
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.1"
   },
   "devDependencies": {
     "@types/babel__code-frame": "^7.27.0",
-    "@types/picomatch": "^3.0.2",
-    "esbuild": "^0.28.1",
-    "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
-    "@deepseek-ai/cordis-plugin-include": "~1.0.9",
-    "@deepseek-ai/dsh-app-boot": "0.2.0-rc.2",
-    "@deepseek-ai/cordis-plugin-timer": "~1.1.6",
-    "@deepseek-ai/dsh-atomic-write": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-cmdline": "0.2.0-rc.2"
+    "@types/picomatch": "^4.0.3",
+    "esbuild": "^0.28.2",
+    "@deepseek-ai/cordis-plugin-timer": "~1.1.7-alpha.1",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.6-alpha.1",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.10-alpha.1",
+    "@deepseek-ai/dsh-app-boot": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-cmdline": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-atomic-write": "0.2.1-alpha.2"
   }
 }