vfs: scope-purge loader caches on deregister

Replace the global loader-cache flush in deregisterVFS with a
scope-purge that only drops entries owned by the unmounting VFS.
Per-layer ownership is determined two ways:

- For CJS-style filename-keyed caches (Module._cache,
  Module._pathCache, the CJS stat cache, the helpers.js realpath
  cache, and the package.json caches) entries are filtered with
  `vfs.shouldHandle(filename)`. __filename stays a clean absolute
  path so user code that does `path.dirname(__filename)` or similar
  is unaffected.

- For the ESM cascaded loader's loadCache, entries are tagged at
  resolve time: when finalizeResolution() detects the resolved
  path is VFS-owned (via the new loaderGetLayerForPath hook), it
  appends `?vfs-layer=<id>` to the URL. The tag surfaces in
  `import.meta.url`, matching the cache-busting pattern used by
  HMR tooling. On deregister, entries whose URL carries the tag
  for the unmounting layer are deleted.

Multi-mount setups no longer pay the cross-VFS cache-warmup
penalty when a single VFS unmounts, and ESM modules loaded from a
VFS become reachable for purge instead of leaking forever in the
cascaded loader.

New helpers exposed for VFS:
- cjs/loader.js: clearStatCacheForVFS
- helpers.js: purgeRealpathCacheForVFS, loaderGetLayerForPath
- package_json_reader.js: purgePackageJSONCacheForVFS

Adds test-vfs-scoped-cache-purge covering both the multi-mount
isolation and the import.meta.url tag visibility.

Refs: #63653
Signed-off-by: Matteo Collina <hello@matteocollina.com>

Author: mcollina

doc/api/vfs.md

@@ -184,6 +184,39 @@ added: REPLACEME
 The current mount-point path as an absolute string, or `null` when
 the VFS is not mounted.
 
+### `vfs.layerId`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {number}
+
+A per-process monotonically increasing identifier assigned at
+construction. The id is stable across `mount()` / `unmount()` cycles
+for the lifetime of the instance, and is independent of the order in
+which VFS layers are mounted.
+
+The layer id is the building block for cache scoping (see
+[Module loader integration][]):
+
+* it surfaces in `import.meta.url` for ES modules loaded from this
+  VFS, as a `?vfs-layer=<id>` search parameter, so that the cascaded
+  loader's caches can be scoped per VFS;
+* it appears in the `NODE_DEBUG=vfs` output for `register` and
+  `deregister` events;
+* it appears in the `ERR_INVALID_STATE` error message thrown when two
+  VFS instances try to mount at overlapping prefixes.
+
+```cjs
+const vfs = require('node:vfs');
+
+const a = vfs.create();
+const b = vfs.create();
+console.log(a.layerId); // e.g. 0
+console.log(b.layerId); // a.layerId + 1
+```
+
 ### `vfs.provider`
 
 <!-- YAML
@@ -272,6 +305,69 @@ The promise namespace mirrors `fs.promises` and includes `readFile`,
 `access`, `rm`, `truncate`, `link`, `mkdtemp`, `chmod`, `chown`, `lchown`,
 `utimes`, `lutimes`, `open`, `lchmod`, and `watch`.
 
+## Module loader integration
+
+Once a `VirtualFileSystem` is mounted, paths under the mount prefix
+participate in module resolution and loading. Both
+`require()` / `require.resolve()` (CommonJS) and `import` /
+`import.meta.resolve()` (ECMAScript modules) consult the VFS through
+the same toggleable hooks that `node:fs` uses, so files served from
+the VFS are first-class modules: `package.json` is honoured,
+extensionless files are sniffed for Wasm vs. JavaScript, conditional
+`exports` / `imports` work, and so on.
+
+```cjs
+const vfs = require('node:vfs');
+
+const myVfs = vfs.create();
+myVfs.mkdirSync('/lib');
+myVfs.writeFileSync('/lib/greet.js', 'module.exports = () => "hi";');
+myVfs.writeFileSync(
+  '/lib/package.json', '{"main": "./greet.js"}');
+myVfs.mount('/virtual');
+
+const greet = require('/virtual/lib');
+console.log(greet()); // 'hi'
+
+myVfs.unmount();
+```
+
+### Cache scoping and `import.meta.url`
+
+Module loaders maintain caches that survive the lifetime of any
+single VFS. To keep entries from leaking once a VFS is unmounted
+without invalidating unrelated real-fs imports, two mechanisms are
+combined:
+
+* **CommonJS caches** (`require.cache`, the internal stat and
+  realpath caches, and the `package.json` caches) are filtered on
+  `unmount()`: entries whose absolute filename would be claimed by
+  the VFS going away are deleted. `__filename` and `module.filename`
+  are unchanged - they remain plain absolute paths.
+
+* **ECMAScript module URLs** are tagged at resolve time. When the
+  resolver determines that a path belongs to a mounted VFS, it
+  appends `?vfs-layer=<id>` (where `<id>` is the owning instance's
+  [`vfs.layerId`][]) to the resolved URL. The tag therefore appears
+  in `import.meta.url` and in cache keys, and on `unmount()` the
+  cascaded loader's caches drop just the entries that carry the tag
+  for the unmounting layer.
+
+```mjs
+// inside /virtual/lib/greet.mjs after the VFS above is mounted
+console.log(import.meta.url);
+// e.g. 'file:///virtual/lib/greet.mjs?vfs-layer=0'
+```
+
+User code that compares `import.meta.url` literally should account
+for the search parameter; use `new URL(import.meta.url).pathname` or
+`fileURLToPath()` to obtain the underlying path.
+
+Mounting and unmounting do not invalidate ESM modules that are
+already executing. As with any other module-system teardown,
+unmounting a VFS while the import graph below it is still loading is
+the caller's responsibility to avoid.
+
 ## Class: `VirtualProvider`
 
 <!-- YAML
@@ -395,11 +491,13 @@ fields use synthetic but stable values:
 * Times default to the moment the entry was created/last modified.
 
 [Explicit Resource Management]: https://github.com/tc39/proposal-explicit-resource-management
+[Module loader integration]: #module-loader-integration
 [`MemoryProvider`]: #class-memoryprovider
 [`VirtualFileSystem`]: #class-virtualfilesystem
 [`VirtualProvider`]: #class-virtualprovider
 [`fs.BigIntStats`]: fs.md#class-fsbigintstats
 [`fs.Stats`]: fs.md#class-fsstats
 [`node:fs`]: fs.md
+[`vfs.layerId`]: #vfslayerid
 [`vfs.mount(prefix)`]: #vfsmountprefix
 [`vfs.unmount()`]: #vfsunmount

lib/internal/modules/cjs/loader.js

@@ -114,6 +114,7 @@ const kFormat = Symbol('kFormat');
 // Set first due to cycle with ESM loader functions.
 module.exports = {
   clearStatCache,
+  clearStatCacheForVFS,
   kModuleSource,
   kModuleExport,
   kModuleExportNames,
@@ -296,6 +297,22 @@ function clearStatCache() {
   }
 }
 
+/**
+ * Drop only the stat-cache entries owned by the given VFS instance.
+ * Real-fs entries and entries owned by other VFSes are untouched.
+ * @param {{shouldHandle: (path: string) => boolean}} vfs
+ */
+function clearStatCacheForVFS(vfs) {
+  if (statCache === null) {
+    return;
+  }
+  for (const filename of statCache.keys()) {
+    if (vfs.shouldHandle(filename)) {
+      statCache.delete(filename);
+    }
+  }
+}
+
 let _stat = stat;
 ObjectDefineProperty(Module, '_stat', {
   __proto__: null,

lib/internal/modules/esm/resolve.js

@@ -45,7 +45,12 @@ const {
 const { defaultGetFormatWithoutErrors } = require('internal/modules/esm/get_format');
 const { getConditionsSet } = require('internal/modules/esm/utils');
 const packageJsonReader = require('internal/modules/package_json_reader');
-const { loaderLegacyMainResolve, loaderStat, toRealPath } = require('internal/modules/helpers');
+const {
+  loaderGetLayerForPath,
+  loaderLegacyMainResolve,
+  loaderStat,
+  toRealPath,
+} = require('internal/modules/helpers');
 
 /**
  * @typedef {import('internal/modules/esm/package_config.js').PackageConfig} PackageConfig
@@ -282,6 +287,21 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
     resolved.hash = hash;
   }
 
+  // If the resolved path is owned by an installed VFS layer, append a
+  // `vfs-layer=N` search param so cache entries are tagged with the
+  // owning layer. On deregister, entries matching the unmounted layer
+  // can be scope-purged without touching unrelated real-fs imports.
+  // The tag is surfaced in `import.meta.url`, matching the
+  // cache-busting pattern used by HMR tooling.
+  const layerId = loaderGetLayerForPath(path);
+  if (layerId !== undefined) {
+    if (resolved.search) {
+      resolved.search += `&vfs-layer=${layerId}`;
+    } else {
+      resolved.search = `?vfs-layer=${layerId}`;
+    }
+  }
+
   return resolved;
 }
 

lib/internal/modules/helpers.js

@@ -65,6 +65,7 @@ let _loaderReadFile = null;
 let _loaderRealpath = null;
 let _loaderLegacyMainResolve = null;
 let _loaderGetFormatOfExtensionlessFile = null;
+let _loaderGetLayerForPath = null;
 
 /**
  * Set override functions for the module loader's fs operations.
@@ -78,6 +79,22 @@ function setLoaderFsOverrides(overrides = kEmptyObject) {
   _loaderRealpath = overrides.realpath ?? null;
   _loaderLegacyMainResolve = overrides.legacyMainResolve ?? null;
   _loaderGetFormatOfExtensionlessFile = overrides.getFormatOfExtensionlessFile ?? null;
+  _loaderGetLayerForPath = overrides.getLayerForPath ?? null;
+}
+
+/**
+ * If `filename` is owned by an installed VFS layer, returns that layer's
+ * monotonically increasing id; otherwise returns `undefined`. Used by the
+ * ESM resolver to tag resolved URLs so cache entries can be scope-purged
+ * on VFS deregister without touching unrelated real-fs imports.
+ * @param {string} filename Absolute path
+ * @returns {number|undefined}
+ */
+function loaderGetLayerForPath(filename) {
+  if (_loaderGetLayerForPath !== null) {
+    return _loaderGetLayerForPath(filename);
+  }
+  return undefined;
 }
 
 /**
@@ -179,6 +196,19 @@ function clearRealpathCache() {
   realpathCache.clear();
 }
 
+/**
+ * Drop only realpath-cache entries owned by the given VFS instance.
+ * Entries for unrelated paths are untouched.
+ * @param {{shouldHandle: (path: string) => boolean}} vfs
+ */
+function purgeRealpathCacheForVFS(vfs) {
+  for (const key of realpathCache.keys()) {
+    if (vfs.shouldHandle(key)) {
+      realpathCache.delete(key);
+    }
+  }
+}
+
 /**
  * Wrapper for modulesBinding.readPackageJSON that supports VFS toggle.
  * @param {string} jsonPath
@@ -680,6 +710,7 @@ module.exports = {
   addBuiltinLibsToObject,
   assertBufferSource,
   clearRealpathCache,
+  purgeRealpathCacheForVFS,
   constants,
   enableCompileCache,
   flushCompileCache,
@@ -689,6 +720,7 @@ module.exports = {
   getCompileCacheDir,
   initializeCjsConditions,
   loaderGetFormatOfExtensionlessFile,
+  loaderGetLayerForPath,
   loaderGetNearestParentPackageJSON,
   loaderGetPackageScopeConfig,
   loaderGetPackageType,

lib/internal/modules/package_json_reader.js

@@ -367,6 +367,24 @@ function clearPackageJSONCache() {
   deserializedPackageJSONCache.clear();
 }
 
+/**
+ * Drop only package.json-cache entries owned by the given VFS instance.
+ * Real-fs entries and other-VFS entries are untouched.
+ * @param {{shouldHandle: (path: string) => boolean}} vfs
+ */
+function purgePackageJSONCacheForVFS(vfs) {
+  for (const key of moduleToParentPackageJSONCache.keys()) {
+    if (vfs.shouldHandle(key)) {
+      moduleToParentPackageJSONCache.delete(key);
+    }
+  }
+  for (const key of deserializedPackageJSONCache.keys()) {
+    if (typeof key === 'string' && vfs.shouldHandle(key)) {
+      deserializedPackageJSONCache.delete(key);
+    }
+  }
+}
+
 module.exports = {
   read,
   getNearestParentPackageJSON,
@@ -375,4 +393,5 @@ module.exports = {
   getPackageJSONURL,
   findPackageJSON,
   clearPackageJSONCache,
+  purgePackageJSONCacheForVFS,
 };