@exodus/stasis-core 1.0.0-beta.8 → 1.0.0-rc.0

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/hooks.js CHANGED
@@ -8,6 +8,7 @@ import assert from 'node:assert/strict'
8
8
 
9
9
  import { State } from './state.js'
10
10
  import { installFsHooks } from './fs.js'
11
+ import { inScope } from './state-util.js'
11
12
  import { NATIVE_BUILD_FORMATS, NODE_FORMATS, RESOURCE_FORMATS, SOURCE_LANGUAGE_FORMATS, STAT_FORMATS, erasedTypeScriptFormat, nestedMap } from './util.js'
12
13
 
13
14
  // Snapshot off the namespace so `--fs` can't redirect stasis's own capture/shard reads.
@@ -15,7 +16,6 @@ const { mkdtempSync, opendirSync, readFileSync, renameSync, rmSync, statSync, wr
15
16
 
16
17
  const CJS_FORMATS = new Set(['commonjs', 'commonjs-typescript'])
17
18
 
18
- // The trust gate's refusal for a bundle-served file whose attested format Node can't execute, by kind.
19
19
  function refuseNonNodeFormat(format, url) {
20
20
  if (SOURCE_LANGUAGE_FORMATS.has(format)) {
21
21
  throw new Error(`[stasis] cannot execute a '${format}' bundle: ${format} bundles are produced for external analysis, not for 'stasis run --bundle=load' (${url})`)
@@ -32,6 +32,9 @@ function refuseNonNodeFormat(format, url) {
32
32
  if (format === 'directory') {
33
33
  throw new Error(`[stasis] cannot import a directory listing ('directory'): a captured fs.readdirSync result is not executable JavaScript. Read it with fs.readdirSync instead (${url})`)
34
34
  }
35
+ if (format === undefined) {
36
+ throw new Error(`[stasis] cannot execute '${url}': the bundle carries it with no format, as it carries the code Metro builds from source, which is for Metro, not Node`)
37
+ }
35
38
  if (STAT_FORMATS.has(format)) {
36
39
  throw new Error(`[stasis] cannot import '${url}': the bundle carries only a payload-free stat record ('${format}', an fs.lstatSync/statSync capture attesting existence and kind) -- not the file's content. Capture a run that reads or imports it to bundle its bytes.`)
37
40
  }
@@ -53,21 +56,26 @@ const TRAILING_SAME_LINE = /(?:[ \t]|\/\*(?:[^*\n\r\u2028\u2029]|\*(?!\/))*\*\/)
53
56
  // A directive string followed by one of these heads a multi-line expression, not a directive (ASI gotcha).
54
57
  const EXPR_CONTINUATION = new Set(['.', '[', '(', '`', '+', '-', '*', '/', '%', ',', '?', ':', '=', '<', '>', '&', '|', '^'])
55
58
  const KEYWORD_CONTINUATION = /(?:instanceof|in)\b/uy
56
- function skipSticky(re, source, i) {
59
+ function matchEnd(re, source, i) {
57
60
  re.lastIndex = i
58
- re.exec(source)
59
- return re.lastIndex
61
+ return re.test(source) ? re.lastIndex : -1
60
62
  }
61
63
  function newStatementAfterBreak(source, pos) {
62
- const afterBreak = skipSticky(WS_COMMENTS, source, pos)
64
+ const afterBreak = matchEnd(WS_COMMENTS, source, pos)
63
65
  if (afterBreak >= source.length) return true
64
66
  if (EXPR_CONTINUATION.has(source[afterBreak])) return false
65
- KEYWORD_CONTINUATION.lastIndex = afterBreak
66
- return !KEYWORD_CONTINUATION.test(source)
67
+ return matchEnd(KEYWORD_CONTINUATION, source, afterBreak) === -1
68
+ }
69
+ function endsDirective(source, pos) {
70
+ const c = source[pos]
71
+ if (c === undefined || c === ';' || c === '}') return true
72
+ if (c === '/' && source[pos + 1] === '/') return true
73
+ // A `/*` here spans a newline: like a line break it can end the directive.
74
+ if (c === '/' && source[pos + 1] === '*') return newStatementAfterBreak(source, pos)
75
+ return (c === '\n' || c === '\r' || c === '\u2028' || c === '\u2029') && newStatementAfterBreak(source, pos)
67
76
  }
68
77
 
69
- // Insert CJS_REQUIRE_REPAIR AFTER the Directive Prologue with a leading ';', so a `'use strict'`
70
- // stays strict and a leading string EXPRESSION isn't split mid-expression.
78
+ // AFTER the Directive Prologue, with a leading ';': a `'use strict'` stays strict, a leading string EXPRESSION whole.
71
79
  function repairCjsRequire(source) {
72
80
  if (typeof source !== 'string') return source
73
81
  let i = 0
@@ -76,20 +84,8 @@ function repairCjsRequire(source) {
76
84
  i = nl === -1 ? source.length : nl + 1
77
85
  }
78
86
  for (;;) {
79
- const afterWs = skipSticky(WS_COMMENTS, source, i)
80
- STRING_LITERAL.lastIndex = afterWs
81
- if (STRING_LITERAL.exec(source) === null) break
82
- const afterStr = STRING_LITERAL.lastIndex
83
- const afterTrail = skipSticky(TRAILING_SAME_LINE, source, afterStr)
84
- const c = source[afterTrail]
85
- let isDirective
86
- if (c === undefined || c === ';' || c === '}') isDirective = true
87
- else if (c === '/' && source[afterTrail + 1] === '/') isDirective = true
88
- // A `/*` here is a newline-spanning block comment: like a line break it can end the directive.
89
- else if (c === '/' && source[afterTrail + 1] === '*') isDirective = newStatementAfterBreak(source, afterTrail)
90
- else if (c === '\n' || c === '\r' || c === '\u2028' || c === '\u2029') isDirective = newStatementAfterBreak(source, afterTrail)
91
- else isDirective = false
92
- if (!isDirective) break
87
+ const afterStr = matchEnd(STRING_LITERAL, source, matchEnd(WS_COMMENTS, source, i))
88
+ if (afterStr === -1 || !endsDirective(source, matchEnd(TRAILING_SAME_LINE, source, afterStr))) break
93
89
  i = afterStr
94
90
  }
95
91
  return `${source.slice(0, i)};${CJS_REQUIRE_REPAIR}${source.slice(i)}`
@@ -100,57 +96,33 @@ let state
100
96
  let createdShardDir
101
97
  let createdShardPub
102
98
  let createdShardPubId
103
- // True once artifacts are written; the load hook asserts on it so a late first load can't ship unattested.
99
+ // Latched once artifacts are written, so a late first load can't ship unattested.
104
100
  let saved = false
105
- // Serialized shard text a child last wrote, so a second flush skips an identical re-write.
106
101
  let lastShardWritten
107
- // Set when stasis's own capture/verification rejects something; when set, nothing is written.
102
+ // Set when stasis's own capture/verification rejects something: then nothing is written.
108
103
  let aborted = false
109
104
  // >0 while Node's loader reads a module's source; the --fs hook skips reads taken then.
110
105
  let loadingModule = 0
111
- // True until the first non-builtin load hook fires (entry detection).
112
106
  let entryUnseen = true
113
- // True until the first parent-less resolution -- the CLI entry. Extra preloads (`stasis run
114
- // --import tsx`) resolve against a DIRECTORY parent (the cwd URL, '/'-terminated -- never a
115
- // loadable module) and load BEFORE it: they are runner infrastructure like stasis's own loader.
116
- // Capturing them would misfile the first preload as the entry (initState from ITS package root)
117
- // and pollute the artifact with toolchain files; gating them would break --bundle=load (the
118
- // preload itself must keep loading from disk). Any OTHER pre-entry parent (an [eval] wrapper's
119
- // import) falls through to the normal path and fails closed on assert.ok(state), like a run
120
- // without preloads.
107
+ // Until the CLI entry resolves, preloads (`--import tsx`) resolve from a DIRECTORY parent: runner infrastructure,
108
+ // neither captured (it would misfile the entry) nor gated (a preload loads from disk under --bundle=load).
121
109
  let entryUnresolved = true
122
- // The runner-infrastructure module graph: every URL the preload phase resolved or loaded, plus
123
- // its post-entry descendants (a transformer lazy-loading a plugin). Members pass both hooks
124
- // through unobserved -- but NOT unforgotten:
125
- // - infraSources stashes each infra load's raw {source, format} and infraEdges its outgoing
126
- // resolutions, so that when the APP graph reaches an infra module (its load hook can never
127
- // re-fire -- the module instance is cached) it is PROMOTED into the capture with the exact
128
- // bytes that executed, its own edges replayed transitively. Without promotion the artifact
129
- // would ship a dangling edge and a frozen replay would never verify the file.
130
- // - under --bundle=load, an app edge landing on an infra URL means the cached disk-loaded
131
- // instance shadows the attested bundle bytes: allowed only when they are identical.
110
+ // The infrastructure graph passes both hooks unobserved; its loads and edges are kept for when the app reaches it.
132
111
  const infraUrls = new Set()
133
112
  const infraSources = new Map()
134
113
  const infraEdges = new Map()
135
- // URLs the bundle=load load hook actually served, so the CJS shim can detect a require() that
136
- // executed an attested file from DISK instead (a transplanted require.extensions handler, e.g.
137
- // tsx's '.ts' pipeline, reads and compiles the file itself -- the load hook never fires).
114
+ // So the CJS shim detects an attested file a transplanted require.extensions handler (tsx's) ran from DISK.
138
115
  const servedFromBundle = new Set()
139
116
 
140
- // EXODUS_STASIS_PID = the root stasis's pid; on mismatch we're a child and must not write the
141
- // bundle/lockfile (root owns the artifact; a 2nd writer races). A forked child also relaxes assertEntry.
117
+ // A child (pid mismatch) must not write the artifacts: the root owns them, and a 2nd writer races.
142
118
  const OWN_PID = String(process.pid)
143
- if (!process.env.EXODUS_STASIS_PID) process.env.EXODUS_STASIS_PID = OWN_PID
119
+ process.env.EXODUS_STASIS_PID ||= OWN_PID
144
120
  const isChildProcess = process.env.EXODUS_STASIS_PID !== OWN_PID
145
121
  const forkedChild = isChildProcess && process.channel !== undefined
146
122
 
147
123
  // stasis-core's own package root, so State's backfill captures edges loaded before our hooks registered.
148
124
  const PRELOAD_ROOT = (() => {
149
- try {
150
- return dirname(findPackageJSON(import.meta.url))
151
- } catch {
152
- return undefined
153
- }
125
+ try { return dirname(findPackageJSON(import.meta.url)) } catch { return undefined }
154
126
  })()
155
127
 
156
128
  // A capture step whose rejection must never be written, even if user code swallows the throw.
@@ -163,7 +135,6 @@ function recording(fn) {
163
135
  }
164
136
  }
165
137
 
166
- // nextLoad with `loadingModule` held, so the --fs hook skips the loader's own read of the source.
167
138
  function loadCounted(nextLoad, url, context) {
168
139
  loadingModule++
169
140
  try {
@@ -174,13 +145,12 @@ function loadCounted(nextLoad, url, context) {
174
145
  }
175
146
 
176
147
  const toBuffer = (source) => (Buffer.isBuffer(source) ? source : Buffer.from(source))
148
+ // Node's CJS loader may return source=null and read the file from disk itself.
149
+ const sourceOrDisk = (source, url) => source ?? readFileSync(fileURLToPath(url))
177
150
 
178
- // Child-process capture forwarding (shards), opt-in via --child-process: a capturing child writes a
179
- // signed per-pid shard the root verifies against its own public key before merging. Trust rests on
180
- // that signature, not the dir being secret; shards carry NO bytes (the root re-reads from disk).
181
-
151
+ // --child-process: trust rests on a shard's signature under a key the root minted; shards carry NO bytes.
182
152
  function shardForwardingEnabled() {
183
- return Boolean(state) && state.config.childProcess && (state.config.writeLockfile || state.config.writeBundle)
153
+ return state.config.childProcess && (state.config.writeLockfile || state.config.writeBundle)
184
154
  }
185
155
 
186
156
  function clearShardEnv() {
@@ -194,13 +164,11 @@ function removeShardDir() {
194
164
  }
195
165
 
196
166
  function writeChildShard() {
197
- if (!shardForwardingEnabled()) return
198
167
  const dir = process.env.EXODUS_STASIS_SHARD_DIR
199
168
  const keyB64 = process.env.EXODUS_STASIS_SHARD_KEY
200
169
  if (!dir || !keyB64) return
201
170
  try {
202
- // Sign the exact snapshot string, never a re-stringify, so verify is independent of JSON key
203
- // order; temp + rename so the merge never reads a half-written shard.
171
+ // Sign the exact string, never a re-stringify; temp + rename so the merge never reads half a shard.
204
172
  const shard = state.shardSnapshot()
205
173
  if (shard === lastShardWritten) return
206
174
  const privateKey = createPrivateKey({ key: Buffer.from(keyB64, 'base64'), format: 'der', type: 'pkcs8' })
@@ -211,26 +179,22 @@ function writeChildShard() {
211
179
  writeFileSync(tmpPath, JSON.stringify({ shard, signature }))
212
180
  renameSync(tmpPath, join(dir, `${pubId}-${unique}.json`))
213
181
  lastShardWritten = shard
214
- } catch {
215
- // Best-effort: a child that can't snapshot/sign/write just doesn't contribute.
216
- }
182
+ } catch { /* best-effort: a child that can't snapshot/sign/write just doesn't contribute */ }
217
183
  }
218
184
 
219
- // Cap shard count + size so a hostile/runaway set can't OOM the root.
185
+ // So a hostile/runaway shard set can't OOM the root.
220
186
  const MAX_SHARDS = 4096
221
187
  const MAX_SHARD_BYTES = 64 * 1024 * 1024
222
188
 
223
- // Merge children's shards from `dir`: verify each envelope against our own PUBLIC key, not one from
224
- // the filename. opendir streams the listing so memory stays bounded.
189
+ // Verified against our own PUBLIC key, not one from the filename; opendir keeps memory bounded.
225
190
  function mergeChildShards(dir) {
226
191
  let handle
227
192
  try { handle = opendirSync(dir) } catch { return }
228
193
  const prefix = `${createdShardPubId}-`
229
194
  let count = 0
230
195
  try {
231
- let dirent
232
- while ((dirent = handle.readSync()) !== null) {
233
- const name = dirent.name
196
+ for (let dirent = handle.readSync(); dirent !== null; dirent = handle.readSync()) {
197
+ const { name } = dirent
234
198
  if (!name.startsWith(prefix) || !name.endsWith('.json')) continue
235
199
  if (++count > MAX_SHARDS) break
236
200
  const path = join(dir, name)
@@ -240,91 +204,73 @@ function mergeChildShards(dir) {
240
204
  if (typeof shard !== 'string' || typeof signature !== 'string') continue
241
205
  if (!verify(null, Buffer.from(shard), createdShardPub, Buffer.from(signature, 'base64url'))) continue
242
206
  state.mergeShard(shard)
243
- } catch {
244
- // A malformed/partial shard is skipped; the rest merge.
245
- }
207
+ } catch { /* a malformed/partial shard is skipped */ }
246
208
  }
247
209
  } finally {
248
210
  try { handle.closeSync() } catch { /* best-effort */ }
249
211
  }
250
212
  }
251
213
 
252
- // Install the --fs reader patches. Must run AFTER stasis's own fs snapshots so they never redirect
253
- // stasis's own reads.
254
- function installFsHooksFromConfig() {
255
- const fsMode = state.config.fs
256
- if (!fsMode) return
257
- installFsHooks({
258
- async: fsMode === 'async',
259
- getState: () => state,
260
- isLoadingModule: () => loadingModule > 0,
261
- // Warn on the first taint so the silent discard (reads succeed, exit 0, no artifact) has a clue.
262
- markAborted: (err) => {
263
- if (!aborted) console.warn(`[stasis] --fs: capture aborted, no bundle/lockfile will be written -- ${err?.message ?? err}`)
264
- aborted = true
265
- },
266
- })
267
- }
268
-
269
214
  function initState(root) {
270
215
  state = new State(root, { preload: true, preloadRoot: PRELOAD_ROOT })
271
216
 
272
- installFsHooksFromConfig()
217
+ // AFTER stasis's own fs snapshots, so they never redirect its own reads.
218
+ if (state.config.fs) {
219
+ installFsHooks({
220
+ async: state.config.fs === 'async',
221
+ getState: () => state,
222
+ isLoadingModule: () => loadingModule > 0,
223
+ // Warned, else the discard is silent: reads succeed, exit 0, no artifact.
224
+ markAborted: (err) => {
225
+ if (!aborted) console.warn(`[stasis] --fs: capture aborted, no bundle/lockfile will be written -- ${err?.message ?? err}`)
226
+ aborted = true
227
+ },
228
+ })
229
+ }
273
230
 
274
- // Root + opt-in only, before any child can fork: ALWAYS mint our own dir (OS tmpdir, mkdtemp 0700)
275
- // and keypair, overwriting any inherited/attacker-set env, so we merge only shards we can verify.
231
+ // ALWAYS mint our own dir and keypair, overwriting any inherited/attacker-set env: we merge only what we verify.
276
232
  if (!isChildProcess && shardForwardingEnabled()) {
277
233
  try {
278
234
  const { publicKey, privateKey } = generateKeyPairSync('ed25519')
279
235
  createdShardDir = mkdtempSync(join(tmpdir(), 'stasis-shard-'))
280
236
  createdShardPub = publicKey
281
- createdShardPubId = publicKey.export({ format: 'jwk' }).x // base64url(raw public key)
237
+ createdShardPubId = publicKey.export({ format: 'jwk' }).x
282
238
  process.env.EXODUS_STASIS_SHARD_DIR = createdShardDir
283
239
  // Rides process.env so every transitive descendant inherits; do NOT scrub it downstream.
284
240
  process.env.EXODUS_STASIS_SHARD_KEY = privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64')
285
241
  } catch {
286
- // Best-effort: clear any inherited (possibly attacker-set) dir/key so descendants don't fall
287
- // back to a channel we never minted.
242
+ // Descendants must not fall back to an inherited channel we never minted.
288
243
  removeShardDir()
289
244
  createdShardDir = createdShardPub = createdShardPubId = undefined
290
245
  clearShardEnv()
291
246
  }
292
247
  } else if (!isChildProcess) {
293
- // Non-capturing root: shed any inherited (possibly attacker-set) shard env.
294
248
  clearShardEnv()
295
249
  }
296
250
 
297
- // Persist on exit unless `aborted` -- deliberately NOT gated on exit code, so a clean capture
298
- // exiting non-zero still persists. Must stay fully synchronous for `exit` to host it.
251
+ // NOT gated on exit code: a clean capture exiting non-zero still persists. Fully synchronous for `exit`.
299
252
  const save = () => {
300
- const writing = state.config.writeLockfile || state.config.writeBundle
301
- // A child forwards a shard instead of writing the artifact (root owns it; a 2nd writer races).
302
253
  if (isChildProcess) {
303
- if (writing && !aborted) writeChildShard()
254
+ if (shardForwardingEnabled() && !aborted) writeChildShard()
304
255
  return
305
256
  }
306
257
  try {
307
258
  if (aborted) return
308
259
  if (createdShardDir) mergeChildShards(createdShardDir)
309
- // write() self-gates the artifact writes, but also VERIFIES in read-only frozen modes, so it
310
- // must run in every mode.
260
+ // In every mode: write() also VERIFIES in read-only frozen modes.
311
261
  state.write()
312
- // Latch only in write modes: a read-only run persists nothing, so a later first load (e.g. a
313
- // require() from another exit handler) is still attested and must not trip the load hook.
314
- if (writing) saved = true
262
+ // A read-only run persists nothing, so a later first load (another exit handler's) is still attested.
263
+ if (state.config.writeLockfile || state.config.writeBundle) saved = true
315
264
  } finally {
316
265
  removeShardDir()
317
266
  }
318
267
  }
319
268
 
320
- // `exit` alone, NOT the beforeExit/exit pair: it runs after every beforeExit handler, so one flush
321
- // there sees strictly more. A process that never reaches `exit` writes nothing.
269
+ // `exit` alone: it runs after every beforeExit handler, so one flush there sees strictly more.
322
270
  process.on('exit', save)
323
271
 
324
- // config.shardSignalFlush (opt-in): flush the shard when a capturing CHILD is ended by SIGTERM
325
- // (jest-worker's forceExit bypasses `exit`), then re-deliver the signal -- unless user code owns
326
- // SIGTERM, then only flush. `userOwnedSigterm` is snapshotted at registration: a `once` that
327
- // already ran is invisible to listenerCount. Must fit forceExit's 500ms window.
272
+ // jest-worker's forceExit bypasses `exit` (500ms window). SIGTERM is re-delivered unless user code owns it,
273
+ // snapshotted now: a `once` that already ran is invisible to listenerCount.
328
274
  if (isChildProcess && shardForwardingEnabled() && state.config.shardSignalFlush) {
329
275
  const userOwnedSigterm = process.listenerCount('SIGTERM') > 0
330
276
  process.once('SIGTERM', () => {
@@ -337,7 +283,6 @@ function initState(root) {
337
283
  }
338
284
  }
339
285
 
340
- // Init from the package root of `url` (the entry), exactly as its live load would.
341
286
  function initStateFromPackage(url) {
342
287
  const pkg = findPackageJSON(url)
343
288
  assert.equal(basename(pkg), 'package.json')
@@ -347,49 +292,34 @@ function initStateFromPackage(url) {
347
292
  function load(url, context, nextLoad) {
348
293
  assert.equal(typeof url, 'string')
349
294
 
350
- // Runner-infrastructure passthrough (see entryUnresolved): a preload's module graph loads
351
- // before the entry (or lazily after, from an infra parent). Stash the raw result so a later
352
- // app-graph edge can promote the module with the exact bytes that executed.
353
- if ((entryUnresolved || infraUrls.has(url)) && !url.startsWith('node:')) {
354
- infraUrls.add(url)
355
- const result = loadCounted(nextLoad, url, context)
356
- if (!infraSources.has(url)) infraSources.set(url, { source: result.source, format: result.format })
357
- return result
358
- }
359
-
360
295
  if (url.startsWith('node:')) {
361
296
  const result = nextLoad(url, context)
362
297
  assert.equal(result.format, 'builtin')
363
298
  return result
364
299
  }
365
300
 
301
+ // Stashed so a later app edge can promote the module with the exact bytes that executed.
302
+ if (entryUnresolved || infraUrls.has(url)) {
303
+ infraUrls.add(url)
304
+ const result = loadCounted(nextLoad, url, context)
305
+ if (!infraSources.has(url)) infraSources.set(url, { source: result.source, format: result.format })
306
+ return result
307
+ }
308
+
366
309
  if (state?.config.loadBundle) {
367
- // node_modules scope serves only nm deps; gate on inNodeModules(), not a raw substring (symlinks).
368
- if (!state.config.full && !state.inNodeModules(url)) return nextLoad(url, context)
310
+ if (!inScope(state, url)) return nextLoad(url, context)
369
311
  const { source, format } = state.getFile(url)
370
- // Cross-check format only when the resolve chain set it; the formats map is itself attested
371
- // against the lockfile at construction. A transforming preload (`stasis run --import tsx`)
372
- // legitimately asks for an attested '-typescript' file as its post-erasure family -- serve
373
- // the chain's view then (the transformer above us turns the raw source into it).
374
- let serveFormat = format
375
- if (context.format != null) {
376
- if (context.format === erasedTypeScriptFormat(format)) serveFormat = context.format
377
- else assert.equal(format, context.format)
378
- }
379
- // Trust gate: only serve a file whose attested format Node can execute; everything else fails closed.
312
+ // A transforming preload (`--import tsx`) asks for a '-typescript' file as its post-erasure family.
313
+ if (context.format != null && context.format !== erasedTypeScriptFormat(format)) assert.equal(format, context.format)
380
314
  if (!NODE_FORMATS.has(format)) refuseNonNodeFormat(format, url)
381
315
  servedFromBundle.add(url)
382
- // node:59666: a load-hook-supplied CJS source gets a re-invented require() missing .cache/.extensions.
383
- return { source: CJS_FORMATS.has(format) ? repairCjsRequire(source) : source, format: serveFormat, shortCircuit: true }
316
+ return { source: CJS_FORMATS.has(format) ? repairCjsRequire(source) : source, format: context.format ?? format, shortCircuit: true }
384
317
  }
385
318
 
386
319
  const result = loadCounted(nextLoad, url, context)
387
- let { source } = result
388
320
  const { format } = result
389
321
  assert.notEqual(format, 'builtin')
390
-
391
- // Node's CJS loader may return source=null and read from disk itself; capture it for the bundle
392
- if (source == null && format === 'commonjs') source = readFileSync(fileURLToPath(url))
322
+ const source = format === 'commonjs' ? sourceOrDisk(result.source, url) : result.source
393
323
 
394
324
  const isEntry = entryUnseen
395
325
  entryUnseen = false
@@ -401,67 +331,49 @@ function load(url, context, nextLoad) {
401
331
  return result
402
332
  }
403
333
 
404
- // Fold a runner-infrastructure module into the capture: an app-graph edge reached a module the
405
- // preload phase already executed, so its load hook can never re-fire (the instance is cached) and
406
- // skipping it would ship a dangling edge a frozen replay never verifies. addFile re-verifies the
407
- // stashed bytes against disk (and against the lockfile/bundle in frozen modes), and the module's
408
- // own remembered resolutions replay transitively so its dependencies aren't dangling either.
334
+ // The app reached a module a preload executed, whose load hook can't re-fire: else a dangling edge ships.
409
335
  function promoteInfraUrl(url, { isEntry = false } = {}) {
410
336
  if (!infraUrls.delete(url)) return
411
337
  const stashed = infraSources.get(url)
338
+ if (stashed === undefined) return
412
339
  infraSources.delete(url)
413
- // Same disk fallback as the live load path: Node's CJS loader may return source=null.
414
- const source = stashed?.source ?? readFileSync(fileURLToPath(url))
415
- recording(() => state.addFile(url, { source, format: stashed?.format ?? undefined, isEntry }))
340
+ const source = sourceOrDisk(stashed.source, url)
341
+ recording(() => state.addFile(url, { source, format: stashed.format ?? undefined, isEntry }))
416
342
  const edges = infraEdges.get(url)
417
343
  infraEdges.delete(url)
418
344
  for (const [specifier, edge] of edges ?? []) {
419
345
  recording(() => state.addImport(url, specifier, edge.url, edge.context))
420
- if (infraSources.has(edge.url)) promoteInfraUrl(edge.url)
421
- else infraUrls.delete(edge.url) // resolved but never loaded: a live load would capture it
346
+ promoteInfraUrl(edge.url)
422
347
  }
423
348
  }
424
349
 
425
- // Under --bundle=load, an app edge landing on a module the preload phase already loaded means the
426
- // CACHED disk-loaded instance shadows whatever the hooks would serve from the bundle: allowed
427
- // only when the executed bytes and the attested bytes are identical, else fail closed.
350
+ // A preload's CACHED disk-loaded instance shadows what the hooks would serve: allowed only for identical bytes.
428
351
  function assertInfraMatchesBundle(url) {
429
352
  if (!infraUrls.has(url)) return
430
353
  const stashed = infraSources.get(url)
431
354
  if (stashed === undefined) { infraUrls.delete(url); return } // resolved but never loaded: the hooks will serve it
432
- const executed = toBuffer(stashed.source ?? readFileSync(fileURLToPath(url)))
355
+ const executed = toBuffer(sourceOrDisk(stashed.source, url))
433
356
  if (!executed.equals(toBuffer(state.getFile(url).source))) {
434
- throw new Error(
435
- `[stasis] cannot serve '${url}' from the bundle: a preload already executed it from disk ` +
436
- `before the entry, and those bytes differ from the attested ones -- refusing the divergent ` +
437
- `cached instance`
438
- )
357
+ throw new Error(`[stasis] cannot serve '${url}' from the bundle: a preload already executed it from disk ` +
358
+ 'before the entry, and those bytes differ from the attested ones -- refusing the divergent cached instance')
439
359
  }
440
360
  }
441
361
 
442
362
  function resolve(specifier, context, nextResolve) {
443
- // Runner-infrastructure passthrough (see entryUnresolved): a preload's graph resolves from a
444
- // DIRECTORY parent (the cwd URL Node uses for each `--import` specifier -- a directory is never
445
- // a loadable module, so this cannot shadow an app parent) or from a module already tracked as
446
- // infrastructure. The first parent-less resolution is still the entry, and any other pre-entry
447
- // parent (an [eval] wrapper's import) falls through to fail closed below. Each passed-through
448
- // edge is remembered -- not recorded -- so promoteInfraUrl can replay it if the app graph
449
- // reaches this module later.
450
- const infraParent = context.parentURL !== undefined
451
- && (infraUrls.has(context.parentURL) || (entryUnresolved && context.parentURL.endsWith('/')))
452
- if (infraParent) {
363
+ const { parentURL, conditions, importAttributes } = context
364
+ // A DIRECTORY parent can't shadow an app parent; any other pre-entry parent ([eval]'s import) fails closed below.
365
+ if (parentURL !== undefined && (infraUrls.has(parentURL) || (entryUnresolved && parentURL.endsWith('/')))) {
453
366
  const res = nextResolve(specifier)
454
367
  if (!res.url.startsWith('node:')) {
455
368
  infraUrls.add(res.url)
456
- if (infraUrls.has(context.parentURL)) {
457
- // Last-write-wins per specifier, like observeResolution: only the final target can be the
458
- // one a cached instance pins.
459
- nestedMap(infraEdges, context.parentURL).set(specifier, { url: res.url, context: { conditions: context.conditions, format: res.format, importAttributes: context.importAttributes } })
369
+ if (infraUrls.has(parentURL)) {
370
+ // Last-write-wins: only the final target can be the one a cached instance pins.
371
+ nestedMap(infraEdges, parentURL).set(specifier, { url: res.url, context: { conditions, format: res.format, importAttributes } })
460
372
  }
461
373
  }
462
374
  return res
463
375
  }
464
- if (entryUnresolved && !context.parentURL) entryUnresolved = false
376
+ if (entryUnresolved && !parentURL) entryUnresolved = false
465
377
 
466
378
  if (isBuiltin(specifier)) {
467
379
  const res = nextResolve(specifier)
@@ -469,37 +381,31 @@ function resolve(specifier, context, nextResolve) {
469
381
  return res
470
382
  }
471
383
 
472
- if (context.importAttributes !== undefined) {
384
+ if (importAttributes !== undefined) {
473
385
  const expectedAttrs = Object.create(null) // saving not supported yet; enforce expected attrs
474
- if (extname(specifier) === '.json' && context.importAttributes?.type) expectedAttrs.type = 'json'
475
- assert.deepStrictEqual(context.importAttributes, expectedAttrs)
386
+ if (extname(specifier) === '.json' && importAttributes?.type) expectedAttrs.type = 'json'
387
+ assert.deepStrictEqual(importAttributes, expectedAttrs)
476
388
  }
477
389
 
478
- const { parentURL, conditions, importAttributes } = context
479
-
480
390
  // Full-scope load serves the entry from the bundle, so state must exist before nextResolve.
481
391
  if (!state && !parentURL && process.env.EXODUS_STASIS_BUNDLE === 'load'
482
- && process.env.EXODUS_STASIS_SCOPE !== 'node_modules') {
483
- initState(process.cwd())
484
- }
392
+ && process.env.EXODUS_STASIS_SCOPE !== 'node_modules') initState(process.cwd())
485
393
 
486
394
  if (state?.config.loadBundle) {
487
- // nm scope defers non-nm parents to Node's resolver; gate on inNodeModules() to cover symlinks.
395
+ // inNodeModules(), not a raw substring: a symlinked workspace source is read from disk.
488
396
  if (!state.config.full && !(parentURL && state.inNodeModules(parentURL))) return nextResolve(specifier)
489
- // A bare specifier with a parent resolves from the recorded import map; otherwise skip
490
- // nextResolve so the entry needn't be on disk.
397
+ // The entry skips nextResolve, so it needn't be on disk.
398
+ let url
399
+ let format
491
400
  if (parentURL && !specifier.startsWith('file:')) {
492
- const { url, format } = state.getImport(parentURL, specifier, { conditions, importAttributes })
493
- // Friendlier error at resolve time; the load gate is the load-bearing one.
494
- if (format != null && !NODE_FORMATS.has(format)) refuseNonNodeFormat(format, url)
495
- assertInfraMatchesBundle(url)
496
- return { url, format, importAttributes: undefined, shortCircuit: true }
401
+ ({ url, format } = state.getImport(parentURL, specifier, { conditions, importAttributes }))
402
+ } else {
403
+ url = specifier.startsWith('file:') ? specifier : pathToFileURL(resolvePath(process.cwd(), specifier)).toString()
404
+ // A forked child's main module isn't a declared CLI entry (getFile still fails closed).
405
+ if (!parentURL && state.config.full && !forkedChild) state.assertEntry(url)
406
+ format = state.getFormat(url)
497
407
  }
498
- const url = specifier.startsWith('file:') ? specifier : pathToFileURL(resolvePath(process.cwd(), specifier)).toString()
499
- // A forked child's main module isn't a declared CLI entry, so skip assertEntry (getFile still
500
- // fails closed on anything unattested).
501
- if (!parentURL && state.config.full && !forkedChild) state.assertEntry(url)
502
- const format = state.getFormat(url)
408
+ // Friendlier error at resolve time; the load gate is the load-bearing one.
503
409
  if (format != null && !NODE_FORMATS.has(format)) refuseNonNodeFormat(format, url)
504
410
  assertInfraMatchesBundle(url)
505
411
  return { url, format, importAttributes: undefined, shortCircuit: true }
@@ -510,8 +416,6 @@ function resolve(specifier, context, nextResolve) {
510
416
 
511
417
  assert.equal(res.importAttributes, undefined) // unsupported yet
512
418
  if (parentURL) assert.ok(state)
513
- // The app graph reached a module the preload phase already loaded: fold it (and transitively
514
- // its own graph) into the capture, since its load hook can never re-fire.
515
419
  if (infraUrls.has(url)) {
516
420
  if (infraSources.has(url)) {
517
421
  // The ENTRY itself was preloaded (a wrapper importing the app): init from its package root.
@@ -520,27 +424,25 @@ function resolve(specifier, context, nextResolve) {
520
424
  if (isEntry) entryUnseen = false
521
425
  promoteInfraUrl(url, { isEntry })
522
426
  } else {
523
- // Resolved during the preload phase but never loaded: the app's own load will capture it.
427
+ // Never loaded: the app's own load will capture it.
524
428
  infraUrls.delete(url)
525
429
  }
526
430
  }
527
- // Parent-less = the entry: recorded via addFile/promotion above, never as an edge (addImport
528
- // requires a parent, and state can exist here after an entry promotion).
431
+ // The entry is recorded by addFile/promotion, never as an edge.
529
432
  if (state && parentURL) recording(() => state.addImport(parentURL, specifier, url, { conditions, format, importAttributes }))
530
433
  return res
531
434
  }
532
435
 
533
436
  let installed = false
534
437
 
535
- // Exported so plugins.js can detect "under the stasis loader" before the lazy initState fires.
438
+ // So plugins.js can detect the loader before the lazy initState fires.
536
439
  export function isLoaderInstalled() {
537
440
  return installed
538
441
  }
539
442
 
540
- // For plugins.js when a plugin constructor runs ahead of the load hook.
443
+ // For a plugin constructor run ahead of the load hook.
541
444
  export function ensureStateForLoader() {
542
- if (state) return
543
- initState(process.cwd())
445
+ if (!state) initState(process.cwd())
544
446
  }
545
447
 
546
448
  // Separate from the --import entry points so a host can compose setup before the hooks register.
@@ -549,11 +451,10 @@ export function install() {
549
451
  installed = true
550
452
  registerHooks({ load, resolve })
551
453
  patchCjsResolution()
552
- // The --fs reader patches are deferred to initState (their mode may come from stasis.config.json).
454
+ // The --fs patches wait for initState: their mode may come from stasis.config.json.
553
455
  }
554
456
 
555
- // registerHooks doesn't intercept the require() the ESM->CJS translator builds for a CJS module (it
556
- // resolves through Module._resolveFilename against disk), so shim that to resolve from the import map.
457
+ // registerHooks doesn't intercept the require() the ESM->CJS translator builds, which resolves against disk.
557
458
  function patchCjsResolution() {
558
459
  const original = Module._resolveFilename
559
460
  Module._resolveFilename = function (request, parent, ...rest) {
@@ -561,20 +462,19 @@ function patchCjsResolution() {
561
462
  if (loadMode && typeof request === 'string' && !isBuiltin(request)) {
562
463
  if (typeof parent?.filename === 'string') {
563
464
  const parentURL = pathToFileURL(parent.filename).toString()
564
- if (state.config.full || state.inNodeModules(parentURL)) {
565
- const resolved = state.resolveBundled(parentURL, request)
465
+ if (inScope(state, parentURL)) {
466
+ // For require(), whose target settles a divergent edge.
467
+ const resolved = state.resolveBundled(parentURL, request, { conditions: ['require'] })
566
468
  if (resolved !== undefined) {
567
469
  assertInfraMatchesBundle(pathToFileURL(resolved).toString())
568
470
  return resolved
569
471
  }
570
472
  }
571
473
  } else if (isAbsolute(request)) {
572
- // NO parent, absolute request: Node's ESM<->CJS interop re-enters the CJS loader with hooks
573
- // SKIPPED, so this shim is the only interception point. hasFsFileContent (not a dir/stat
574
- // record) keeps a listing or payload-free stat from hijacking resolution. Node 24.14-24.17
575
- // re-resolve here every commonjs-sync eval; the no-parent shape survives on >=24.18 too.
474
+ // Node's ESM<->CJS interop re-enters the CJS loader with hooks SKIPPED (every commonjs-sync eval on
475
+ // 24.14-24.17), so only this shim intercepts. hasFsFileContent: a listing or stat record never resolves.
576
476
  const url = pathToFileURL(request).toString()
577
- if ((state.config.full || state.inNodeModules(url)) && state.hasFsFileContent(url)) {
477
+ if (inScope(state, url) && state.hasFsFileContent(url)) {
578
478
  assertInfraMatchesBundle(url)
579
479
  return resolvePath(request)
580
480
  }
@@ -588,12 +488,8 @@ function patchCjsResolution() {
588
488
  return resolved
589
489
  }
590
490
 
591
- // Module._load's cache fast path can skip _resolveFilename, so a second require() of the same
592
- // target goes unrecorded: force it through the PROPERTY (our shim) to observe the edge. This is
593
- // also the one spot that sees every ACTUAL CJS execution, hook-served or not, so it anchors the
594
- // executed-file reconciliation for transplanted require.extensions handlers (a transforming
595
- // preload's CJS pipeline, e.g. `--import tsx` compiling .ts, reads and compiles files itself --
596
- // the load hook chain never fires for them).
491
+ // Module._load's cache fast path can skip _resolveFilename. It also sees every ACTUAL CJS execution, so it
492
+ // catches transplanted require.extensions handlers (`--import tsx` compiling .ts) the load hooks never see.
597
493
  const originalLoad = Module._load
598
494
  Module._load = function (request, parent, ...rest) {
599
495
  let resolvedUrl
@@ -603,23 +499,15 @@ function patchCjsResolution() {
603
499
  if (typeof resolved === 'string' && isAbsolute(resolved)) resolvedUrl = pathToFileURL(resolved).toString()
604
500
  }
605
501
  if (resolvedUrl !== undefined && !state.config.loadBundle) {
606
- // A require() executes its target: remember it so write() can attest/verify anything the
607
- // load hook never saw, and fold in a module the preload phase already executed.
608
502
  state.observeExecution(resolvedUrl)
609
- if (infraSources.has(resolvedUrl)) promoteInfraUrl(resolvedUrl)
610
- else infraUrls.delete(resolvedUrl)
503
+ promoteInfraUrl(resolvedUrl)
611
504
  }
612
505
  const result = originalLoad.call(this, request, parent, ...rest)
613
- // Under --bundle=load, an attested source the load hook never served just executed from DISK
614
- // (a transplanted require.extensions handler bypasses the hook chain): fail closed -- after
615
- // the fact, but before anything can trust the run.
506
+ // An attested source the load hook never served ran from DISK: fail closed, before anything trusts the run.
616
507
  if (resolvedUrl !== undefined && state.config.loadBundle
617
508
  && !servedFromBundle.has(resolvedUrl) && state.isBundledSource(resolvedUrl)) {
618
- throw new Error(
619
- `[stasis] '${resolvedUrl}' executed from disk, bypassing the attested bundle -- a ` +
620
- `require() pipeline transplanted by a preload (e.g. tsx compiling CJS TypeScript) ` +
621
- `cannot serve bundle bytes and is refused under --bundle=load`
622
- )
509
+ throw new Error(`[stasis] '${resolvedUrl}' executed from disk, bypassing the attested bundle -- a require() pipeline ` +
510
+ 'transplanted by a preload (e.g. tsx compiling CJS TypeScript) cannot serve bundle bytes and is refused under --bundle=load')
623
511
  }
624
512
  return result
625
513
  }