nodejs/node
Input boundaries are argv/env (parsed into `EnvironmentOptions` by `src/node_options.cc` and read from JS via `getOptionValue()`), the file system, sockets, and the SEA blob embedded in the binary. Options are the master state: essentially every JS feature branch keys off `getOptionValue('--flag')`, and options are re-read after deserialization by `refreshRuntimeOptions()`. The heaviest transform in this tree is the VFS path router, which reroutes `node:fs` calls and module-loader fs calls whose resolved path falls under a reserved mount prefix, before those calls reach the native `fs` binding. State owners are the `Environment` object on the C++ side and, on the JS side, module-level singletons: `vfsState.handlers` in `internal/fs/utils.js`, the `loaderOverrides` map in `internal/modules/helpers.js`, the `providers` array in `provider_registry.js`, and `Module._cache`/`_pathCache` in the CJS loader.
- CLI/NODE_OPTIONS parsing populates `EnvironmentOptions` fields declared in `src/node_options.h` (`vfs_mounts`, `experimental_vfs`, `vfs_load`, `allow_fs_vfs`) which JS then reads through `internal/options`'s `getOptionValue()`.
- `refreshRuntimeOptions()` is the first call inside `prepareExecution()`, re-reading options after snapshot deserialization so a snapshotted heap does not carry stale build-time option values.
- Every VFS mount is assigned a numeric layer id and is served at `${os.devNull}/vfs/<id>`; because `os.devNull` is a character device (`/dev/null`, `\\.\NUL`) it can have no children, so path ownership is decidable from the string alone without touching the disk.
- `getLayerIdFromPath()` parses the layer id with a hand-rolled digit scan over char codes 47/92 (`/`, `\`) rather than splitting — a deliberate hot-path optimisation since it runs on candidate fs calls.
- Dispatch into the VFS is a single null-check per fs function: `lib/fs.js` reads `vfsState.handlers` and, if non-null, calls the handler and routes the returned promise through `vfsResult()`/`vfsVoid()` to the error-first callback; when no VFS is mounted the field is `null` and overhead is one comparison.
- `setVfsHandlers()` is the only writer of `vfsState.handlers` and is imported by `internal/vfs/setup.js`, making that file the single install point for fs interception.
- Module resolution is redirected separately from `fs`: `internal/modules/helpers.js` wraps each native loader method and consults a `loaderOverrides` map installed by `setLoaderOverrides()`, with a `hasLoaderOverrides` boolean short-circuit when the map is empty.
- `internal/modules/run_main.js` deliberately calls loader methods through `loaderMethods` rather than the `modules` binding directly, precisely so a mounted VFS can override them and a worker entry point can live inside one.
- Unmounting must invalidate loader state: `cleanForVfsPrefix()` walks `Module._cache`, `Module._pathCache`, `statCache`, `realpathCache`, and the package.json caches, deleting entries under a mount prefix — by value for `_pathCache`, whose keys are `request\0parent` tokens.
- The provider selection pipeline is source-sniffing, not extension-based: `canHandle()` for `zip` attempts `ZipFile.openSync()` (which locates the end-of-central-directory record) and stashes the opened archive in `pendingZipFile` so `create()` does not reopen it; `dir` falls back to `stats.isDirectory()`.
- Permission denials feed a diagnostics channel: `Permission::is_scope_granted` calls `Publish()` on failure, which emits `{scope, resource, dropped}` on a per-scope channel and guards against recursion with a `publishing_` flag so a subscriber's own checks cannot re-enter.
- `normalizeReference()` in the JS permission layer canonicalises input across three representations — `URL` (converted with `fileURLToPath` only for `fs.*` scopes), `Uint8Array` (passed through raw so non-UTF-8 paths are not mangled), and validated strings.
- SEA data flows binary→memory: `WriteSingleExecutableBlob` serialises the asset map with a length-prefixed count, and the reader rebuilds an `unordered_map<string_view, string_view>` pointing into the still-mapped blob rather than copying.
- Worker threads receive their entry through the message port (`LOAD_SCRIPT` in `internal/worker/io`), not argv, and call `finishVfsMounts()` themselves so mounts are re-created per thread rather than shared.