@exodus/stasis-core 1.0.0-beta.2 → 1.0.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/fs.js CHANGED
@@ -1,124 +1,21 @@
1
- // `stasis run --fs=sync|async` (EXODUS_STASIS_FS, or "fs" in stasis.config.json): monkey-patch
2
- // the filesystem readers
3
- // fs.readFileSync, fs.readdirSync, fs.lstatSync, fs.statSync so that, alongside the
4
- // module graph the loader hooks already capture, a program's explicit file/directory
5
- // reads -- and the KIND (file vs directory) of the paths it lstat/stats -- are
6
- // recorded into the bundle (bundle=add|replace) and served back from it
7
- // (bundle=load). Alongside the readers, the existence/canonical-path PROBES existsSync /
8
- // accessSync / realpathSync are served (load mode) so a tool that checks a file before
9
- // reading it finds a bundle-only file -- see the existsSync/accessSync/realpathSync bullet.
10
- //
11
- // MODE:
12
- // - `=sync` patches only the sync readers above (the default; `--fs` bare == sync).
13
- // - `=async` additionally patches their async counterparts -- the callback forms
14
- // fs.readFile/readdir/lstat/stat and the promise forms fs.promises.* (the latter
15
- // IS node:fs/promises, the same object, so syncBuiltinESMExports() covers ESM
16
- // `import ... from 'node:fs/promises'` too). Each async wrapper shares the exact
17
- // capture/serve logic of its sync sibling; only the I/O plumbing differs. The async
18
- // probe forms (fs.access / fs.realpath and the fs.promises.* forms) are added here too.
19
- //
20
- // SCOPE, deliberately narrow:
21
- // - The four readers above, plus the existence/canonical-path probes existsSync /
22
- // accessSync / realpathSync (and, under =async, fs.access / fs.realpath and the
23
- // fs.promises forms). Other fs (fs.opendir, streams, fs.cp, watchers, the deprecated
24
- // callback fs.exists, ...) is NOT touched, in either mode. Notably fs.readlink is left
25
- // unserved: enhanced-resolve probes it per path-segment but treats a read error as
26
- // "not a symlink" and continues, so an absent recorded file still resolves correctly --
27
- // leaving it unserved costs nothing for the absent-config case (same ancestor-symlink
28
- // limitation as realpathSync's lexical fallback below).
29
- // - readdirSync: only the single-argument form `readdirSync(path)`. Any options
30
- // (encoding, withFileTypes, recursive) fall through untouched -- Dirent objects
31
- // and recursive listings aren't modelled.
32
- // - readFileSync: the optional second argument (an `encoding` string, or an
33
- // options object with `encoding`) is honoured; the raw bytes are what we
34
- // capture/serve and `encoding` is applied on the way out.
35
- // - lstatSync / statSync: single-argument form, captured AND served -- but ONLY the
36
- // path's kind, i.e. the type getters isFile()/isDirectory(); full Stats fields are
37
- // never attested. CAPTURE (bundle=add|replace): the real call runs first, so the
38
- // caller always gets the genuine Stats (and genuine errors); the observed kind is
39
- // then recorded as a PAYLOAD-FREE stat record ('stat:file'/'stat:directory' in
40
- // `formats` -- no bytes, no hash), so a stat-ONLY path -- never read, readdir'd,
41
- // or imported -- still answers at load. A path that is neither a regular file nor
42
- // a directory (a symlink under lstat, a socket, a FIFO, ...) isn't modelled and
43
- // records nothing. SERVE (bundle=load): for a recorded path they return a
44
- // Stats-like object whose isFile()/isDirectory() come
45
- // from the bundle (the common existence check); every other member is the real
46
- // stat while the file is still on disk, and a benign synthetic default (0 / epoch
47
- // / file-or-dir mode) once it's gone -- so fs wrappers that read more than
48
- // isFile()/isDirectory() (graceful-fs reads stats.uid/gid) keep working under
49
- // bundle=load instead of re-throwing ENOENT. A skipped
50
- // source-map sidecar is reported absent in both modes (next bullet). statSync vs
51
- // lstatSync differ only in symlink following, which matters for the real-call
52
- // paths (passthrough, capture, present-on-disk serve) -- each uses its own real
53
- // implementation, and a stat of an in-root symlink records the TARGET's kind
54
- // under the requested path (keyed exactly like a byte read of that path would
55
- // be) while an lstat of one records nothing.
56
- // - existsSync / accessSync / realpathSync (+ their async/promise forms under =async):
57
- // existence/canonical-path PROBES, serve-only and bundle=load only. A path the bundle
58
- // records answers existent / accessible (read-only: F_OK/R_OK, while W_OK/X_OK defer) /
59
- // its-path even once it's gone from disk; an
60
- // unrecorded path (and all of capture mode, where the file is on disk) defers to the
61
- // real call. This is what lets a tool that gates file loading on a SEPARATE existence
62
- // check find a file whose bytes live only in the bundle, instead of forcing an on-disk
63
- // stub: @babel/core, for one, guards config loading with fs.existsSync(babel.config.js)
64
- // (and realpath-canonicalizes the path) BEFORE it require()s the file -- so without
65
- // serving the probe, a bundled-but-absent babel.config.js reads as missing and Babel
66
- // silently runs with no config (an empty on-disk babel.config.js "works" only because
67
- // its existence passes the probe; its bytes are then served from the bundle by the
68
- // module loader). Because these are serve-only (never captured), a file that is ONLY
69
- // existence-probed -- never read or imported -- isn't recorded, so its probe falls
70
- // through to disk on load; babel.config.js is fine because it is also require()d, hence
71
- // recorded. (An lstatSync/statSync of a path, by contrast, DOES record its kind -- see
72
- // the lstat/stat bullet above -- after which these probes answer from that stat record
73
- // too, since they consult the same getFsStatFamily.) realpathSync returns the real (symlink-resolved) path while the file is on
74
- // disk, and falls back to the LEXICALLY-resolved request path once it's bundle-only (a
75
- // symlink in a surviving ancestor dir is not re-resolved -- moot for the absent-config
76
- // case, but a canonicalize-then-compare under a symlinked ancestor could diverge between
77
- // capture and load). Its `.native` variant is covered too.
78
- // - Source-map sidecars (`*.map`): build-time debug artifacts that never affect a
79
- // program's output, yet tools read them unconditionally -- regardless of any
80
- // "sourcemaps off" setting (e.g. @babel/core's normalizeFile reads a file's sibling
81
- // `.js.map` to chain an INPUT source map no matter the bundler's devtool, and skips
82
- // it when absent). Under --fs every in-root `*.map` is therefore treated as
83
- // NON-EXISTENT -- never captured, never served, ENOENT to the reader -- in BOTH
84
- // capture and load (returning ENOENT at capture too is what keeps a captured build
85
- // byte-identical to a hermetic replay). Opt in by adding `map` to the resources
86
- // allowlist; then it's captured/served like any other declared resource.
87
- // - Only paths inside the project root -- whose REAL path (symlinks resolved)
88
- // also stays inside the root -- are captured/served; anything else (a system
89
- // path, a symlink escaping the root, an fd, a non-file URL) falls through to
90
- // the real call and is NOT attested.
91
- //
92
- // Mechanism mirrors the @exodus/stasis tooling package's src/mock.js: reach the
93
- // mutable CJS `node:fs` object through createRequire, snapshot the real functions
94
- // at module-eval time (BEFORE install() patches anything, so stasis's own snapshots
95
- // and these stay real), then on install replace the readers and
96
- // syncBuiltinESMExports() so user code's later ESM `import { readFileSync } from
97
- // 'node:fs'` sees the patched binding too. (Unlike mock.js it assigns directly
98
- // rather than via node:test's MockTracker -- no test-time restore is needed.) State
99
- // is read lazily per call (it's created when the entry loads), and decode/lookup
100
- // reuse State's getFs* / addFs* methods.
1
+ // `stasis run --fs=sync|async`: monkey-patch the fs readers (readFileSync/readdirSync/lstat/stat
2
+ // + existence/realpath probes; under =async their callback + fs.promises counterparts) to capture a
3
+ // program's explicit reads into the bundle (bundle=add|replace) or serve them from it (bundle=load).
4
+ // SECURITY INVARIANT: only paths whose REAL path (symlinks resolved) stays inside the project root are
5
+ // captured/served; anything else falls through to the real fs and is never attested.
101
6
 
102
7
  import { createRequire, syncBuiltinESMExports } from 'node:module'
103
8
  import { isAbsolute, relative, resolve } from 'node:path'
104
9
  import { fileURLToPath, pathToFileURL } from 'node:url'
105
10
 
106
- // The genuine sync source reader (snapshotted before any --fs patch). Lives in
107
- // state-util.js so there's a single source of truth shared with the bundler plugins;
108
- // see that module for why it must not be a patched `node:fs` named import.
109
11
  import { realReadFileSync } from './state-util.js'
12
+ import { isDotEnvFile, isStasisArtifactName } from './util.js'
110
13
 
111
14
  const require = createRequire(import.meta.url)
112
15
  const fs = require('node:fs')
113
16
 
114
- // Snapshot the real functions now, while they're still the genuine builtins. The
115
- // hooks below call THESE (never the patched `fs.*`), so there is no recursion,
116
- // capture always sees real bytes, and the patched lstatSync/statSync/realpathSync fall
117
- // back to the real impls here. realRealpathSync also backs realRootOf/realContained, whose
118
- // containment checks must stay on the genuine builtin even after realpathSync is patched.
119
- // (The sync source reader, realReadFileSync, is imported from state-util.js above -- the
120
- // single source of truth shared with the bundler plugins; only the dir/stat/realpath
121
- // readers are snapshotted here, since only the --fs hook needs them.)
17
+ // Snapshot the real fns while still genuine builtins; the hooks call THESE, never patched `fs.*`, so
18
+ // there's no recursion and capture/containment always see real bytes/paths.
122
19
  const realReaddirSync = fs.readdirSync
123
20
  const realLstatSync = fs.lstatSync
124
21
  const realStatSync = fs.statSync
@@ -127,11 +24,7 @@ const realRealpathSyncNative = fs.realpathSync.native
127
24
  const realExistsSync = fs.existsSync
128
25
  const realAccessSync = fs.accessSync
129
26
 
130
- // Async counterparts, snapshotted for `--fs=async`. Callback forms off `fs`, promise
131
- // forms off `fs.promises` (which IS node:fs/promises -- same object, so patching it +
132
- // syncBuiltinESMExports() also covers `import ... from 'node:fs/promises'`). The
133
- // bundleStats shim still falls back to the SYNC real stat (a Stats field read is
134
- // synchronous), so no async stat snapshot is needed.
27
+ // Async counterparts, snapshotted for `--fs=async`. fs.promises IS node:fs/promises (same object).
135
28
  const realReadFile = fs.readFile
136
29
  const realReaddir = fs.readdir
137
30
  const realLstat = fs.lstat
@@ -141,49 +34,33 @@ const realReaddirP = fs.promises.readdir
141
34
  const realLstatP = fs.promises.lstat
142
35
  const realStatP = fs.promises.stat
143
36
 
144
- // Async access/realpath probe counterparts, snapshotted for `--fs=async`. The legacy callback
145
- // fs.exists is deliberately not REASSIGNED (it's deprecated, and wrapping it would clobber its
146
- // util.promisify.custom) -- but note it STILL answers from the bundle under --fs=async, because
147
- // Node implements fs.exists by delegating to the (now-patched) fs.access; under --fs=sync it
148
- // falls through to disk like every other async API. That's the desirable direction (consistent
149
- // with existsSync), so leaving it unwrapped is fine. There is no fs.promises.exists. realpath's
150
- // `.native` variant is snapshotted too.
37
+ // The legacy callback fs.exists is deliberately NOT reassigned (wrapping would clobber its
38
+ // util.promisify.custom); it still answers via the patched fs.access.
151
39
  const realAccess = fs.access
152
40
  const realAccessP = fs.promises.access
153
41
  const realRealpath = fs.realpath
154
42
  const realRealpathNative = fs.realpath.native
155
43
  const realRealpathP = fs.promises.realpath
156
44
 
157
- // True iff an access() mode requests ONLY read-class bits (existence F_OK / readable R_OK) --
158
- // nothing implying mutation or execution. The bundle serves files read-only, so only such a
159
- // request is answered from it; a W_OK/X_OK request is deferred to the real fs (which gives the
160
- // truthful answer: ENOENT for a bundle-only file, real perms for an on-disk one). Phrased as an
161
- // allowlist -- "no bits outside READ_ACCESS" -- rather than a `& (W_OK|X_OK) === 0` denylist, so
162
- // an out-of-range/garbage mode (e.g. 8) also defers to the real fs and gets its faithful
163
- // ERR_OUT_OF_RANGE instead of slipping through. `| 0` coerces the default `undefined` to F_OK.
45
+ // The bundle serves read-only, so only an F_OK/R_OK-only mode may be answered from it; allowlist form
46
+ // so a W_OK/X_OK or out-of-range mode defers to the real fs.
164
47
  const READ_ACCESS = fs.constants.F_OK | fs.constants.R_OK
165
48
  const isReadOnlyAccessMode = (mode) => ((mode | 0) & ~READ_ACCESS) === 0
166
49
 
167
- // Resolve a path argument to an absolute filesystem path, or null when it's
168
- // something we don't capture (an integer fd, or a non-file URL). Strings/Buffers
169
- // are resolved against cwd exactly like fs does; a trailing slash on a directory is
170
- // dropped by resolve(), keeping the file: URL we build in agreement with State's
171
- // pathToFileURL round-trip.
50
+ // Resolve a path argument to an absolute path, or null for what we don't capture (fd, non-file URL).
172
51
  function toAbsPath(path) {
173
52
  if (typeof path === 'string') return resolve(path)
174
53
  if (Buffer.isBuffer(path)) return resolve(path.toString())
175
54
  if (path instanceof URL) return path.protocol === 'file:' ? fileURLToPath(path) : null
176
- return null // integer fd or unknown
55
+ return null
177
56
  }
178
57
 
179
- // True when `abs` is the project root or lives beneath it. Out-of-root reads (system
180
- // files, parent escapes) are left entirely to the real implementation.
58
+ // True when `abs` is the project root or lives beneath it -- lexical only (see realContained).
181
59
  function withinRoot(root, abs) {
182
60
  const rel = relative(root, abs)
183
61
  return !rel.startsWith('..') && !isAbsolute(rel)
184
62
  }
185
63
 
186
- // Memoized real path of the project root, for the symlink-containment check below.
187
64
  let realRootCache
188
65
  function realRootOf(root) {
189
66
  if (realRootCache?.root !== root) {
@@ -194,13 +71,8 @@ function realRootOf(root) {
194
71
  return realRootCache.real
195
72
  }
196
73
 
197
- // Capture-side containment: the path's REAL location (all symlinks resolved) must
198
- // stay inside the project root's real path. `withinRoot` is lexical only, so a
199
- // symlink inside the tree pointing OUT (`src/peek -> /etc`) would otherwise be read
200
- // and its bytes/listing attested as if in-root -- pulling external content into the
201
- // closed, signed bundle. An escaping (or vanished) path returns false: the hook
202
- // then leaves it to the real fs and records nothing. Only used while capturing; the
203
- // path exists (we just read it).
74
+ // Capture-side containment: the path's REAL location must stay inside root's real path, else an
75
+ // in-tree symlink pointing OUT would pull external content into the signed bundle.
204
76
  function realContained(root, abs) {
205
77
  let real
206
78
  try { real = realRealpathSync(abs) } catch { return false }
@@ -208,50 +80,28 @@ function realContained(root, abs) {
208
80
  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))
209
81
  }
210
82
 
211
- // Apply readFileSync's second argument to raw bytes: a string encoding, or an
212
- // options object's `encoding`. No encoding yields the Buffer; anything else is
213
- // handed to Buffer.toString, which decodes a known encoding and throws
214
- // ERR_UNKNOWN_ENCODING for an unknown one -- matching fs's contract, including
215
- // that an invalid encoding like 'buffer' throws rather than returning the Buffer.
83
+ // At the project root, drop stasis's own artifacts from the RECORDED listing so it doesn't depend on
84
+ // whether an earlier run left them behind; the program still receives the true on-disk `names`.
85
+ function dirCaptureNames(root, abs, names) {
86
+ if (relative(root, abs) !== '') return names
87
+ return names.filter((name) => !isStasisArtifactName(name))
88
+ }
89
+
90
+ // Apply readFileSync's encoding arg to raw bytes; Buffer.toString matches fs's ERR_UNKNOWN_ENCODING.
216
91
  function decode(buf, options) {
217
92
  const encoding = typeof options === 'string' ? options : options?.encoding
218
93
  if (encoding == null) return buf
219
94
  return buf.toString(encoding)
220
95
  }
221
96
 
222
- // realpathSync/realpath honour an `encoding` arg exactly like fs: 'buffer' yields a Buffer,
223
- // anything else (incl. the default 'utf8') a string. Used for the synthetic answer returned
224
- // when a bundle-served path is gone from disk -- the real realpath would ENOENT there.
97
+ // Honour realpath's `encoding` arg for the synthetic answer when a bundle-served path is gone from disk.
225
98
  function encodeRealpath(abs, options) {
226
99
  const encoding = typeof options === 'string' ? options : options?.encoding
227
100
  return encoding === 'buffer' ? Buffer.from(abs) : abs
228
101
  }
229
102
 
230
- // Source-map sidecars (`*.map`) are build-time debug artifacts that never affect a
231
- // program's emitted output, yet tools read them opportunistically and INDEPENDENTLY of
232
- // any "sourcemaps off" setting -- @babel/core's normalizeFile, for one, reads a
233
- // transformed file's sibling `.js.map` to chain an INPUT source map no matter the
234
- // bundler's devtool, and simply skips it (try/catch) when the file is absent. Under --fs
235
- // we therefore treat such a map as NON-EXISTENT: never captured (so a stray map read
236
- // can't abort a capture or bloat the lockfile/bundle) and never served, handing the
237
- // reader a faithful ENOENT in BOTH capture and load. Returning ENOENT at CAPTURE too --
238
- // not just load -- keeps a captured build byte-identical to a hermetic replay.
239
- //
240
- // NOT gated on bundle mode: --fs capture writes the lockfile (hashes, via addFile) as
241
- // well as the bundle, so the skip must be identical whether or not a bundle is written
242
- // -- lockfile attestation can't depend on bundle mode. (The hook only runs under --fs,
243
- // which always has a bundle mode, so no explicit mode check is needed.)
244
- //
245
- // Two opt-outs keep this from hiding a map a user genuinely wants:
246
- // - `map` in the resources allowlist -> captured + served as a normal resource
247
- // (classifyExtension tags `.map` 'resource' once `map` is allowed).
248
- // - at load, a map the bundle actually CARRIES is served regardless of the load run's
249
- // resources flag -- bundle membership wins, exactly like every other recorded
250
- // resource, so a map captured under `--resources=map` still loads even if the load
251
- // run forgets the flag (getFsStatFamily returns undefined for a map that was skipped, so the
252
- // common "never captured" case still falls through to the ENOENT below).
253
- // Uses getFsStatFamily, matching the serve paths: a map a bundler-plugin sidecar carries
254
- // counts as carried by the family, not just by main.
103
+ // Source-map sidecars (`*.map`) are NON-EXISTENT under --fs (faithful ENOENT in both modes, so a
104
+ // captured build replays byte-identically). Opt out via `map` in resources, or bundle membership.
255
105
  function isSkippedSourceMap(state, abs) {
256
106
  if (!abs.toLowerCase().endsWith('.map')) return false
257
107
  if (state.config.resources?.has('map')) return false
@@ -259,9 +109,19 @@ function isSkippedSourceMap(state, abs) {
259
109
  return true
260
110
  }
261
111
 
262
- // A faithful Node-shaped ENOENT, so a skipped source map is indistinguishable from a
263
- // genuinely absent file to the caller (code/errno/syscall/path all set, exactly what a
264
- // real failed open/stat throws). Callers like @babel/core catch it and carry on.
112
+ // `.env`/`.env.*` are NON-EXISTENT under --fs so an automated capture can never bake a secret in. No
113
+ // resources opt-in: the ONE way one serves at load is membership (an explicit `stasis add .env`).
114
+ function isSkippedEnvFile(state, abs) {
115
+ if (!isDotEnvFile(abs)) return false
116
+ if (state.config.loadBundle && state.getFsStatFamily(pathToFileURL(abs).toString()) !== undefined) return false
117
+ return true
118
+ }
119
+
120
+ function isSkippedFsPath(state, abs) {
121
+ return isSkippedSourceMap(state, abs) || isSkippedEnvFile(state, abs)
122
+ }
123
+
124
+ // A faithful Node-shaped ENOENT, indistinguishable from a real absent file.
265
125
  function enoent(syscall, path) {
266
126
  const p = typeof path === 'string' ? path : Buffer.isBuffer(path) ? path.toString() : String(path)
267
127
  const err = new Error(`ENOENT: no such file or directory, ${syscall} '${p}'`)
@@ -272,19 +132,12 @@ function enoent(syscall, path) {
272
132
  return err
273
133
  }
274
134
 
275
- // File-type bits, so code that derives the kind from stats.mode (rather than the
276
- // is*() methods) still sees file-vs-directory for an absent bundle-served path.
135
+ // File-type bits, so code reading stats.mode (not the is*() methods) still sees file-vs-dir.
277
136
  const S_IFREG = 0o100000
278
137
  const S_IFDIR = 0o040000
279
138
 
280
- // Benign fs.Stats-shaped record for a recorded path whose bytes are served from the
281
- // bundle but is GONE from disk. isFile/isDirectory come from the bundle; the rest are
282
- // neutral defaults (zeros, epoch Dates, file/dir mode bits) -- never a throw. This is
283
- // what lets fs wrappers that read more than isFile()/isDirectory() off the returned
284
- // Stats keep working under bundle=load: graceful-fs's statFixSync, for instance,
285
- // reads stats.uid/gid, which would otherwise re-trigger the very ENOENT the bundle
286
- // exists to paper over. The other is*() are false -- the shim models only files and
287
- // directories.
139
+ // Neutral fs.Stats-shaped record for a bundle-served path gone from disk; never throws, so wrappers
140
+ // reading uid/gid etc. keep working.
288
141
  function syntheticStat(isDir) {
289
142
  const epoch = new Date(0)
290
143
  return {
@@ -297,32 +150,16 @@ function syntheticStat(isDir) {
297
150
  }
298
151
  }
299
152
 
300
- // A Stats-like object for a bundle-served path (bundle=load). isFile()/isDirectory()
301
- // always answer from the bundle's record (the point of the shim -- available even
302
- // when the file is absent from disk). Every other member comes from the REAL stat
303
- // while the file is still on disk (faithful metadata); once it's gone -- the
304
- // bundle-load case -- realStatFn throws and we fall back to syntheticStat's benign
305
- // defaults instead of forwarding the ENOENT. Built as a Proxy so this covers the
306
- // full Stats surface (methods AND numeric/Date fields) without enumerating it.
307
- //
308
- // `then` is short-circuited to undefined: a real fs.Stats is never thenable, but the
309
- // lazy resolution would otherwise forward the `then` probe that `await`/Promise
310
- // resolution performs to realStatFn -- which THROWS for an absent file, making a
311
- // bundle-served Stats an accidental rejecting thenable (`await lstatSync(x)` would
312
- // reject with ENOENT for exactly the absent-from-disk case the shim exists to serve).
313
- // Returning undefined keeps it non-thenable in both the present and absent cases.
314
- //
315
- // Read-only: there is no `set` trap, so a write to a field (a wrapper normalising
316
- // e.g. stats.uid) lands on the override target, not on `data`, and isn't reflected
317
- // back on read. No real consumer needs mutate-then-read here -- graceful-fs only
318
- // writes uid/gid when they're < 0, which the synthetic 0 (and modern Node) never hit.
153
+ // A Stats-like Proxy for a bundle-served path: isFile()/isDirectory() answer from the bundle, other
154
+ // members from the REAL stat while on disk, else syntheticStat. `then` is short-circuited so a
155
+ // bundle-served Stats is never an accidental (rejecting) thenable under `await`.
319
156
  function bundleStats(realStatFn, statPath, isDir) {
320
- let data // real fs.Stats, or the synthetic fallback -- resolved once, on demand
157
+ let data
321
158
  const overrides = { isFile: () => !isDir, isDirectory: () => isDir }
322
159
  return new Proxy(overrides, {
323
160
  get(target, prop) {
324
161
  if (prop === 'isFile' || prop === 'isDirectory') return target[prop]
325
- if (prop === 'then') return undefined // never an (accidentally rejecting) thenable
162
+ if (prop === 'then') return undefined
326
163
  if (data === undefined) {
327
164
  try { data = realStatFn(statPath) } catch { data = syntheticStat(isDir) }
328
165
  }
@@ -335,7 +172,7 @@ function bundleStats(realStatFn, statPath, isDir) {
335
172
  let installed = false
336
173
 
337
174
  export function installFsHooks({ async: patchAsync, getState, markAborted, isLoadingModule }) {
338
- if (installed) return // idempotent: install() is the sole caller, but guard anyway
175
+ if (installed) return
339
176
  installed = true
340
177
 
341
178
  fs.readFileSync = function readFileSync(path, options) {
@@ -343,30 +180,15 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
343
180
  if (state) {
344
181
  const abs = toAbsPath(path)
345
182
  if (abs !== null && withinRoot(state.root, abs)) {
346
- // Source-map sidecars are absent in both modes (see isSkippedSourceMap) -- before
347
- // any serve/capture so a `.js.map` is neither read from the bundle nor recorded.
348
- if (isSkippedSourceMap(state, abs)) throw enoent('open', path)
183
+ if (isSkippedFsPath(state, abs)) throw enoent('open', path)
349
184
  const url = pathToFileURL(abs).toString()
350
185
  if (state.config.loadBundle) {
351
- // Serve the captured bytes (consulting sidecar bundles too -- a bundler-plugin
352
- // sidecar may carry it). A path no family bundle recorded (or one recorded as a
353
- // directory) returns undefined and falls back to disk.
354
186
  const buf = state.getFsFileFamily(url)
355
187
  if (buf !== undefined) return decode(buf, options)
356
188
  } else if (state.config.writeBundle && !isLoadingModule()) {
357
- // (Skip while Node's loader is reading a module's source -- that's captured
358
- // as code by the load hook, not a program fs read.) Read once via the real
359
- // reader (faithful errors on the user's original path), record, and hand
360
- // the user the same bytes. A capture conflict (the file read twice with
361
- // diverging bytes) taints the run so nothing inconsistent is written; the
362
- // user's read still succeeds. A path whose real location escapes the root
363
- // (in-tree symlink) is read but NOT recorded -- its content isn't in-bundle
364
- // and must not be attested.
365
189
  const buf = realReadFileSync(path)
366
- // Skip a read a bundler-plugin sidecar already attests (the module graph webpack
367
- // reads through inputFileSystem) -- recording it here would duplicate the graph
368
- // into this (main) bundle. Reads no sidecar owns (the plugin's manual non-JS
369
- // file reads, etc.) ARE recorded here.
190
+ // A path whose real location escapes root (in-tree symlink) is read but NOT recorded, and
191
+ // neither is a read a bundler-plugin sidecar already attests.
370
192
  if (realContained(state.root, abs) && !state.attestedBySidecar(url)) {
371
193
  try { state.addFsFile(url, buf) } catch (err) { markAborted(err) }
372
194
  }
@@ -379,8 +201,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
379
201
 
380
202
  fs.readdirSync = function readdirSync(path, options) {
381
203
  const state = getState()
382
- // Single-argument form only: any options (encoding/withFileTypes/recursive)
383
- // are out of scope and pass straight through.
204
+ // Single-argument form only; any options pass straight through.
384
205
  if (state && options == null) {
385
206
  const abs = toAbsPath(path)
386
207
  if (abs !== null && withinRoot(state.root, abs)) {
@@ -389,14 +210,10 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
389
210
  const names = state.getFsDirFamily(url)
390
211
  if (names !== undefined) return names // sorted at capture time
391
212
  } else if (state.config.writeBundle && !isLoadingModule()) {
392
- // (Node's loader doesn't readdir to load a module, but skip during a load
393
- // window anyway, symmetric with readFileSync.)
394
- const names = realReaddirSync(path) // string[] (single-arg)
395
- // As in readFileSync: skip recording a directory whose real path escapes
396
- // the root (an in-tree symlink to outside), so an external listing is
397
- // never baked into the bundle/lockfile.
213
+ const names = realReaddirSync(path)
214
+ // As in readFileSync: a dir whose real path escapes root is not recorded.
398
215
  if (realContained(state.root, abs)) {
399
- try { state.addFsDir(url, names) } catch (err) { markAborted(err) }
216
+ try { state.addFsDir(url, dirCaptureNames(state.root, abs, names)) } catch (err) { markAborted(err) }
400
217
  }
401
218
  return names
402
219
  }
@@ -405,17 +222,8 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
405
222
  return realReaddirSync(path, options)
406
223
  }
407
224
 
408
- // Capture-side stat recording, shared by the sync/async lstat/stat wrappers: record
409
- // the path's KIND (file vs directory) as a payload-free stat record (state.addFsStat),
410
- // so the type getters -- lstatSync(x).isFile()/.isDirectory(), the common existence-
411
- // and-kind check -- of a stat-ONLY path answer from the bundle at load. Only those two
412
- // kinds are modelled (the serve shim's contract); a symlink (under lstat), socket,
413
- // FIFO, or device records nothing. The caller has already received (or will receive)
414
- // the REAL Stats -- recording never alters what the program sees. Guards mirror the
415
- // byte readers: a path whose real location escapes the root (in-tree symlink pointing
416
- // out) is not attested, a file whose bytes a write-mode sidecar already carries is
417
- // skipped, and a recording conflict (a kind flip mid-run) taints the capture via
418
- // markAborted so nothing inconsistent is written.
225
+ // Shared capture-side stat recording: record the path's KIND as a payload-free stat record so a
226
+ // stat-ONLY path's type getters answer at load. Only file and dir are modelled.
419
227
  const captureStat = (state, abs, stats) => {
420
228
  const isDir = stats.isDirectory()
421
229
  if (!isDir && !stats.isFile()) return
@@ -426,21 +234,15 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
426
234
 
427
235
  fs.lstatSync = function lstatSync(path, options) {
428
236
  const state = getState()
429
- // Single-argument form. Serve (bundle=load) the bundle-backed type getters for a
430
- // recorded path; capture (bundle=add|replace) the observed kind via captureStat,
431
- // handing the caller the REAL Stats (and real errors, e.g. ENOENT) untouched.
432
- // A skipped source-map sidecar is reported absent in both modes.
237
+ // Single-arg form only; capture still hands the caller the REAL Stats/errors.
433
238
  if (state && options == null) {
434
239
  const abs = toAbsPath(path)
435
240
  if (abs !== null && withinRoot(state.root, abs)) {
436
- if (isSkippedSourceMap(state, abs)) throw enoent('lstat', path)
241
+ if (isSkippedFsPath(state, abs)) throw enoent('lstat', path)
437
242
  if (state.config.loadBundle) {
438
243
  const kind = state.getFsStatFamily(pathToFileURL(abs).toString())
439
244
  if (kind !== undefined) return bundleStats(realLstatSync, path, kind === 'directory')
440
245
  } else if (state.config.writeBundle && !isLoadingModule()) {
441
- // (Node's loader stats module paths through internal bindings, not this
442
- // public API, but skip during a load window anyway, symmetric with
443
- // readFileSync/readdirSync.)
444
246
  const stats = realLstatSync(path)
445
247
  captureStat(state, abs, stats)
446
248
  return stats
@@ -450,19 +252,14 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
450
252
  return realLstatSync(path, options)
451
253
  }
452
254
 
453
- // statSync mirrors lstatSync exactly; the only difference is symlink following,
454
- // which is moot for a bundle-served path (there is no link to follow once the
455
- // bytes come from the bundle) but matters for the passthrough/present-on-disk
456
- // case AND for capture -- a statSync of an in-root symlink records the TARGET's
457
- // kind (keyed at the requested path, like a byte read of it), while an lstatSync
458
- // of it records nothing (a symlink isn't modelled) -- so each uses its own real
459
- // implementation.
255
+ // Mirrors lstatSync but follows symlinks, so it must use the real statSync: an in-root symlink
256
+ // records the TARGET's kind here, nothing under lstatSync.
460
257
  fs.statSync = function statSync(path, options) {
461
258
  const state = getState()
462
259
  if (state && options == null) {
463
260
  const abs = toAbsPath(path)
464
261
  if (abs !== null && withinRoot(state.root, abs)) {
465
- if (isSkippedSourceMap(state, abs)) throw enoent('stat', path)
262
+ if (isSkippedFsPath(state, abs)) throw enoent('stat', path)
466
263
  if (state.config.loadBundle) {
467
264
  const kind = state.getFsStatFamily(pathToFileURL(abs).toString())
468
265
  if (kind !== undefined) return bundleStats(realStatSync, path, kind === 'directory')
@@ -476,24 +273,14 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
476
273
  return realStatSync(path, options)
477
274
  }
478
275
 
479
- // existsSync / accessSync / realpathSync: existence + canonical-path PROBES, distinct
480
- // from the byte readers above. A build tool may check a file's existence (and realpath)
481
- // on a channel that never reads its bytes -- @babel/core guards config loading with
482
- // fs.existsSync(babel.config.js) and canonicalizes the path with realpath BEFORE it
483
- // require()s the file. Under bundle=load the bytes come from the bundle (via the module
484
- // loader, or readFileSync above), but without serving these probes too the file still has
485
- // to exist on disk or the tool concludes it is absent and silently skips it. Serve-only,
486
- // like lstat/stat: a recorded path answers from getFsStatFamily (so a file a bundler-plugin
487
- // sidecar carries answers here too, matching the byte/stat readers -- a check-then-read tool
488
- // sees it); everything else -- and all of capture mode, where the file is on disk -- falls
489
- // through to the real call. A skipped source-map sidecar is reported absent in both modes,
490
- // matching readFileSync/statSync.
276
+ // existsSync/accessSync/realpathSync: existence + canonical-path PROBES, serve-only (bundle=load) --
277
+ // a tool may probe before reading bytes (@babel/core does); capture mode and unrecorded paths defer.
491
278
  fs.existsSync = function existsSync(path) {
492
279
  const state = getState()
493
280
  if (state) {
494
281
  const abs = toAbsPath(path)
495
282
  if (abs !== null && withinRoot(state.root, abs)) {
496
- if (isSkippedSourceMap(state, abs)) return false
283
+ if (isSkippedFsPath(state, abs)) return false
497
284
  if (state.config.loadBundle && state.getFsStatFamily(pathToFileURL(abs).toString()) !== undefined) return true
498
285
  }
499
286
  }
@@ -505,11 +292,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
505
292
  if (state) {
506
293
  const abs = toAbsPath(path)
507
294
  if (abs !== null && withinRoot(state.root, abs)) {
508
- if (isSkippedSourceMap(state, abs)) throw enoent('access', path)
509
- // The bundle serves files READ-ONLY: a carried path satisfies an existence/read probe
510
- // (F_OK / R_OK -- what build tools check), but a write/exec probe (W_OK / X_OK) is not
511
- // ours to grant, so it falls through to the real fs (which reports a bundle-only,
512
- // absent-on-disk file as not writable). Unrecorded paths and capture mode also defer.
295
+ if (isSkippedFsPath(state, abs)) throw enoent('access', path)
513
296
  if (state.config.loadBundle && isReadOnlyAccessMode(mode) &&
514
297
  state.getFsStatFamily(pathToFileURL(abs).toString()) !== undefined) {
515
298
  return undefined
@@ -519,16 +302,14 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
519
302
  return realAccessSync(path, mode)
520
303
  }
521
304
 
522
- // realpathSync carries a `.native` variant (enhanced-resolve and some tools call it);
523
- // both share this serve logic. Try the real realpath first so a path still on disk gets
524
- // true symlink resolution; fall back to the lexically-resolved abs once it's gone
525
- // (bundle-served) -- ancestor symlinks aren't re-resolved in that fallback.
305
+ // Try the real realpath first (true symlink resolution while on disk), fall back to the lexical abs
306
+ // once gone (ancestor symlinks not re-resolved then).
526
307
  const servedRealpathSync = (realFn) => function realpathSync(path, options) {
527
308
  const state = getState()
528
309
  if (state) {
529
310
  const abs = toAbsPath(path)
530
311
  if (abs !== null && withinRoot(state.root, abs)) {
531
- if (isSkippedSourceMap(state, abs)) throw enoent('realpath', path)
312
+ if (isSkippedFsPath(state, abs)) throw enoent('realpath', path)
532
313
  if (state.config.loadBundle && state.getFsStatFamily(pathToFileURL(abs).toString()) !== undefined) {
533
314
  try { return realFn(path, options) } catch { return encodeRealpath(abs, options) }
534
315
  }
@@ -539,35 +320,24 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
539
320
  fs.realpathSync = servedRealpathSync(realRealpathSync)
540
321
  fs.realpathSync.native = servedRealpathSync(realRealpathSyncNative)
541
322
 
542
- // --fs=async: the async counterparts. Each shares its sync sibling's capture/serve
543
- // logic via fsTarget(); only the I/O plumbing (callback / promise) differs. A served
544
- // callback is deferred (queueMicrotask) so a bundle hit never fires it synchronously,
545
- // preserving fs's "the callback is always async" contract. fs.promises.* IS
546
- // node:fs/promises (same object), so syncBuiltinESMExports() below propagates these
547
- // to ESM `import ... from 'node:fs/promises'` as well.
323
+ // --fs=async counterparts; a served callback is deferred (queueMicrotask) to preserve fs's
324
+ // always-async contract.
548
325
  if (patchAsync) {
549
- // Classify a path exactly as the sync readers do: serve from the bundle
550
- // (loadBundle), capture into it (writeBundle, outside a module-load window), or
551
- // pass through (null) for out-of-root / fd / non-file-URL / no-state.
326
+ // Classify a path as the sync readers do: 'serve', 'capture', 'absent', or null (pass through).
552
327
  const fsTarget = (path) => {
553
328
  const state = getState()
554
329
  if (!state) return null
555
330
  const abs = toAbsPath(path)
556
331
  if (abs === null || !withinRoot(state.root, abs)) return null
557
- // Source-map sidecars are absent in both modes (see isSkippedSourceMap); 'absent'
558
- // makes the read/stat wrappers below hand back ENOENT instead of serving/capturing.
559
- if (isSkippedSourceMap(state, abs)) return { mode: 'absent', abs }
332
+ if (isSkippedFsPath(state, abs)) return { mode: 'absent', abs }
560
333
  const url = pathToFileURL(abs).toString()
561
334
  if (state.config.loadBundle) return { mode: 'serve', state, url, abs }
562
335
  if (state.config.writeBundle && !isLoadingModule()) return { mode: 'capture', state, url, abs }
563
336
  return null
564
337
  }
565
338
 
566
- // Decode bytes for a callback reader, routing a decode error (e.g. an invalid
567
- // encoding like 'buffer') to the callback -- exactly as fs.readFile does. Without
568
- // this the throw escapes the deferred/real-reader callback as an UNCAUGHT exception
569
- // and crashes the process (the sync path is fine: there the throw is the caller's
570
- // to catch). The promise readers don't need it -- a throw there rejects the promise.
339
+ // Route a decode error to the callback (as fs.readFile does); a throw from a deferred callback
340
+ // would escape as an uncaught exception and crash the process.
571
341
  const decodeToCb = (cb, buf, options) => {
572
342
  let out
573
343
  try { out = decode(buf, options) } catch (err) { cb(err); return }
@@ -585,7 +355,6 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
585
355
  } else if (t?.mode === 'capture') {
586
356
  realReadFile(path, (err, buf) => {
587
357
  if (err) return cb(err)
588
- // Skip what a sidecar already attests (see readFileSync); record only the rest.
589
358
  if (realContained(t.state.root, t.abs) && !t.state.attestedBySidecar(t.url)) { try { t.state.addFsFile(t.url, buf) } catch (e) { markAborted(e) } }
590
359
  decodeToCb(cb, buf, opts)
591
360
  })
@@ -602,20 +371,16 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
602
371
  if (buf !== undefined) return decode(buf, options)
603
372
  } else if (t?.mode === 'capture') {
604
373
  const buf = await realReadFileP(path)
605
- // Skip what a sidecar already attests (see readFileSync); record only the rest.
606
374
  if (realContained(t.state.root, t.abs) && !t.state.attestedBySidecar(t.url)) { try { t.state.addFsFile(t.url, buf) } catch (e) { markAborted(e) } }
607
375
  return decode(buf, options)
608
376
  }
609
377
  return realReadFileP(path, options)
610
378
  }
611
379
 
612
- // Single-argument form only (options === the callback / undefined), like readdirSync.
613
380
  fs.readdir = function readdir(path, options, callback) {
614
381
  const cb = typeof options === 'function' ? options : callback
615
- // "single-argument" form: fn(path, cb) OR fn(path, null/undefined, cb). graceful-fs
616
- // normalises readdir(path, cb) to readdir(path, null, cb), so a null options must
617
- // count as "no options" -- otherwise its reads never hit the bundle (the exact
618
- // gap that made --fs=async fail for enhanced-resolve's async file system).
382
+ // Single-arg form only, and a null options must count as "no options" (graceful-fs normalises to
383
+ // that), else its reads never hit the bundle.
619
384
  const t = ((options == null || typeof options === 'function') && typeof cb === 'function') ? fsTarget(path) : null
620
385
  if (t?.mode === 'serve') {
621
386
  const names = t.state.getFsDirFamily(t.url)
@@ -623,7 +388,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
623
388
  } else if (t?.mode === 'capture') {
624
389
  realReaddir(path, (err, names) => {
625
390
  if (err) return cb(err)
626
- if (realContained(t.state.root, t.abs)) { try { t.state.addFsDir(t.url, names) } catch (e) { markAborted(e) } }
391
+ if (realContained(t.state.root, t.abs)) { try { t.state.addFsDir(t.url, dirCaptureNames(t.state.root, t.abs, names)) } catch (e) { markAborted(e) } }
627
392
  cb(null, names)
628
393
  })
629
394
  return
@@ -638,22 +403,15 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
638
403
  if (names !== undefined) return names
639
404
  } else if (t?.mode === 'capture') {
640
405
  const names = await realReaddirP(path)
641
- if (realContained(t.state.root, t.abs)) { try { t.state.addFsDir(t.url, names) } catch (e) { markAborted(e) } }
406
+ if (realContained(t.state.root, t.abs)) { try { t.state.addFsDir(t.url, dirCaptureNames(t.state.root, t.abs, names)) } catch (e) { markAborted(e) } }
642
407
  return names
643
408
  }
644
409
  return realReaddirP(path, options)
645
410
  }
646
411
 
647
- // lstat/stat capture and serve exactly like their sync siblings: serve the
648
- // bundle-backed type getters, or record the real call's observed kind via
649
- // captureStat while handing the caller the real Stats. bundleStats's field
650
- // fallback is synchronous, so it uses the sync real stat.
412
+ // lstat/stat mirror their sync siblings; bundleStats's field fallback stays sync.
651
413
  fs.lstat = function lstat(path, options, callback) {
652
414
  const cb = typeof options === 'function' ? options : callback
653
- // "single-argument" form: fn(path, cb) OR fn(path, null/undefined, cb). graceful-fs
654
- // normalises readdir(path, cb) to readdir(path, null, cb), so a null options must
655
- // count as "no options" -- otherwise its reads never hit the bundle (the exact
656
- // gap that made --fs=async fail for enhanced-resolve's async file system).
657
415
  const t = ((options == null || typeof options === 'function') && typeof cb === 'function') ? fsTarget(path) : null
658
416
  if (t?.mode === 'absent') { queueMicrotask(() => cb(enoent('lstat', path))); return }
659
417
  if (t?.mode === 'serve') {
@@ -661,7 +419,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
661
419
  if (kind !== undefined) { queueMicrotask(() => cb(null, bundleStats(realLstatSync, path, kind === 'directory'))); return }
662
420
  } else if (t?.mode === 'capture') {
663
421
  realLstat(path, (err, stats) => {
664
- if (err) return cb(err) // faithful error on the user's original path; nothing recorded
422
+ if (err) return cb(err)
665
423
  captureStat(t.state, t.abs, stats)
666
424
  cb(null, stats)
667
425
  })
@@ -672,10 +430,6 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
672
430
 
673
431
  fs.stat = function stat(path, options, callback) {
674
432
  const cb = typeof options === 'function' ? options : callback
675
- // "single-argument" form: fn(path, cb) OR fn(path, null/undefined, cb). graceful-fs
676
- // normalises readdir(path, cb) to readdir(path, null, cb), so a null options must
677
- // count as "no options" -- otherwise its reads never hit the bundle (the exact
678
- // gap that made --fs=async fail for enhanced-resolve's async file system).
679
433
  const t = ((options == null || typeof options === 'function') && typeof cb === 'function') ? fsTarget(path) : null
680
434
  if (t?.mode === 'absent') { queueMicrotask(() => cb(enoent('stat', path))); return }
681
435
  if (t?.mode === 'serve') {
@@ -720,12 +474,8 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
720
474
  return realStatP(path, options)
721
475
  }
722
476
 
723
- // Access + realpath probes, async forms (serve-only, mirroring the sync siblings and
724
- // reusing fsTarget: 'serve' answers from the bundle when the path is recorded, 'absent'
725
- // is a skipped source map, and capture / unrecorded paths fall through to the real call).
726
477
  fs.access = function access(path, mode, callback) {
727
478
  const cb = typeof mode === 'function' ? mode : callback
728
- // Read-only serve: a W_OK/X_OK probe is deferred to the real fs (see accessSync).
729
479
  const accessMode = typeof mode === 'function' ? undefined : mode
730
480
  const t = typeof cb === 'function' ? fsTarget(path) : null
731
481
  if (t?.mode === 'absent') { queueMicrotask(() => cb(enoent('access', path))); return }
@@ -738,7 +488,6 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
738
488
  fs.promises.access = async function access(path, mode) {
739
489
  const t = fsTarget(path)
740
490
  if (t?.mode === 'absent') throw enoent('access', path)
741
- // Read-only serve: a W_OK/X_OK probe is deferred to the real fs (see accessSync).
742
491
  if (t?.mode === 'serve' && isReadOnlyAccessMode(mode) && t.state.getFsStatFamily(t.url) !== undefined) return undefined
743
492
  return realAccessP(path, mode)
744
493
  }
@@ -749,7 +498,6 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
749
498
  const t = typeof cb === 'function' ? fsTarget(path) : null
750
499
  if (t?.mode === 'absent') { queueMicrotask(() => cb(enoent('realpath', path))); return }
751
500
  if (t?.mode === 'serve' && t.state.getFsStatFamily(t.url) !== undefined) {
752
- // Real first (symlink resolution while present); lexically-resolved abs once gone.
753
501
  realFn(path, opts, (err, resolved) => (err ? cb(null, encodeRealpath(t.abs, opts)) : cb(null, resolved)))
754
502
  return
755
503
  }
@@ -768,16 +516,7 @@ export function installFsHooks({ async: patchAsync, getState, markAborted, isLoa
768
516
  }
769
517
  }
770
518
 
771
- // Refresh the node:fs (and node:fs/promises) ESM wrappers so user-code destructured/namespace
772
- // ESM imports resolve to the patched functions. This repoints a LIVE `import { existsSync }
773
- // from 'node:fs'` binding regardless of whether the module evaluated before or after this.
774
- // INVARIANT: stasis's own run-graph modules must stay on the genuine builtin, so the ones in
775
- // the run graph (state.js, state-util.js, util.js) snapshot fs at module-eval via
776
- // `const { ... } = fs` and are immune. The bundler plugins (webpack.js / metro.js) DO use live
777
- // `import { existsSync }`, but they never reach it in load mode (apply()/#run route away from
778
- // the capture path), and capture-mode probes are byte-for-byte transparent; the CLI
779
- // subcommands/loaders/launcher (prune, scan, bundle, extract, the language loaders, the bins)
780
- // run in processes where installFsHooks never fires. A NEW stasis module that needs real fs
781
- // under --fs must snapshot (`const { x } = fs`), not live-import.
519
+ // Refresh the node:fs (+ node:fs/promises) ESM wrappers so user-code live imports see the patched fns.
520
+ // INVARIANT: a stasis module needing the real fs must snapshot it (`const { ... } = fs`), never live-import.
782
521
  syncBuiltinESMExports()
783
522
  }