@exodus/stasis-core 1.0.0-beta.4 → 1.0.0-beta.6

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/state.js CHANGED
@@ -3,51 +3,74 @@ import { isUtf8 } from 'node:buffer'
3
3
  import * as fs from 'node:fs'
4
4
  import { join, resolve, relative, basename, dirname, extname, isAbsolute } from 'node:path'
5
5
  import { fileURLToPath, pathToFileURL } from 'node:url'
6
- import { findPackageJSON } from 'node:module'
7
6
  import { brotliCompressSync, brotliDecompressSync } from 'node:zlib'
8
7
 
9
8
  import { Config } from './config.js'
10
- import { Bundle } from './bundle.js'
9
+ import { Bundle, mergeRepo } from './bundle.js'
11
10
  import { Lockfile } from './lockfile.js'
12
11
  import { parseShard, serializeShard } from './shard.js'
13
12
  import { canonicalizePath, sha512integrity, readFileSyncMaybe, noupsert } from './state-util.js'
14
13
  import { brotliOptions } from './brotli.js'
15
- import { CODE_EXTENSIONS, canObserveExecuteBits, classifyFormat, fileMapToObject, hasNodeModulesSegment, isBinaryPlist, isStatFormat, moduleFileKey, narrowExecutable, objectToMaps, observeExecutable, pathExt, reconcileFormat, sortPaths, splitNodeModulesPath } from './util.js'
16
- import { readModuleManifest } from './bundle-util.js'
14
+ import { CODE_EXTENSIONS, canObserveExecuteBits, classifyFormat, erasedTypeScriptFormat, fileMapToObject, hasNodeModulesSegment, isBinaryPlist, isNativeArtifact, isPathWithin, isStatFormat, moduleFileKey, moduleInfo, narrowExecutable, nestedMap, objectToMaps, observeExecutable, pathExt, reconcileFormat, relativeEscapes, reposAgree, sameRepo, sortPaths, splitNodeModulesPath } from './util.js'
15
+ import { detectRepo, packageJSONStat, packageJSONText, packageRepo, readModuleManifest } from './bundle-util.js'
16
+ import { diskHost } from './host.js'
17
17
  import corePackage from './package.cjs'
18
18
 
19
19
  // Destructure off the namespace: captures the real fns at eval time, so writes survive --mock's
20
20
  // syncBuiltinESMExports() remock of node:fs.
21
- const { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } = fs
21
+ const { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } = fs
22
22
 
23
23
  const FILE_CONFIG = 'stasis.config.json'
24
24
  const FILE_LOCK = 'stasis.lock.json'
25
25
  const FILE_CODE = 'stasis.code.br'
26
26
 
27
- function readPackageJSON(pkgAbsolute) {
28
- const buf = readFileSync(pkgAbsolute)
29
- assert.ok(isUtf8(buf))
30
- return JSON.parse(buf.toString())
31
- }
32
-
33
27
  // Via src/package.cjs: a bundler-safe re-export of package.json.
34
28
  const VERSION = corePackage.version
35
29
 
36
30
  const CAN_OBSERVE_EXECUTE_BITS = canObserveExecuteBits()
37
31
 
32
+ const invalidPackageConfig = (pkgAbsolute, cause) => Object.assign(
33
+ cause === undefined ? new Error(`Invalid package config ${pkgAbsolute}.`) : new Error(`Invalid package config ${pkgAbsolute}.`, { cause }),
34
+ { code: 'ERR_INVALID_PACKAGE_CONFIG' })
35
+
36
+ // A package.json's fields; one that is no JSON object is refused as Node refuses it.
37
+ function readPackageJSON(host, pkgAbsolute) {
38
+ const buf = host.readFile(pkgAbsolute)
39
+ assert.ok(isUtf8(buf))
40
+ let json
41
+ try {
42
+ json = JSON.parse(packageJSONText(buf))
43
+ } catch (cause) {
44
+ throw invalidPackageConfig(pkgAbsolute, cause)
45
+ }
46
+ if (json === null || typeof json !== 'object' || Array.isArray(json)) throw invalidPackageConfig(pkgAbsolute)
47
+ return json
48
+ }
49
+
38
50
  // A weak 'stat:*' yields to a real format; two real formats or a stat kind flip are fatal.
39
51
  function upsertFormat(map, file, format) {
40
52
  const currentFormat = map.get(file)
41
53
  map.set(file, currentFormat === undefined ? format : reconcileFormat(format, currentFormat, file))
42
54
  }
43
55
 
44
- // TODO: stricter format validation
56
+ // Loader formats the extension alone decides; `.js`/`.ts` follow the nearest package `type`.
57
+ const EXT_FORMATS = { __proto__: null, '.json': 'json', '.mjs': 'module', '.cjs': 'commonjs', '.mts': 'module-typescript', '.cts': 'commonjs-typescript' }
58
+ // With no `type`, Node decides .js/.ts by syntax detection: either variant is possible, the first is the default.
59
+ const UNTYPED_VARIANTS = { __proto__: null, '.js': ['commonjs', 'module'], '.ts': ['commonjs-typescript', 'module-typescript'] }
60
+
61
+ // Nested package.json files known to disagree with their package root's name/version because of
62
+ // upstream packaging, exempt from #locateModule's consistency check. Matched as a segment-aligned
63
+ // suffix of the project-relative path, so hoisted, nested and .pnpm-store copies all match.
64
+ // Maintained list: add only a confirmed upstream false positive, with its reason.
65
+ const INCONSISTENT_PACKAGE_JSON_EXCEPTIONS = [
66
+ 'node_modules/@redis/client/dist/package.json', // stale build-time copy
67
+ ]
68
+ const isInconsistentPackageJsonException = (file) =>
69
+ INCONSISTENT_PACKAGE_JSON_EXCEPTIONS.some((suffix) => file === suffix || file.endsWith(`/${suffix}`))
45
70
 
46
71
  // On globalThis via `Symbol.for` so the registry is shared across duplicate stasis-core copies.
47
72
  const STATES_KEY = Symbol.for('@exodus/stasis-core/states')
48
- function liveStates() {
49
- return (globalThis[STATES_KEY] ??= new Set())
50
- }
73
+ const liveStates = () => (globalThis[STATES_KEY] ??= new Set())
51
74
 
52
75
  export class State {
53
76
  hashes = new Map()
@@ -63,25 +86,23 @@ export class State {
63
86
  config
64
87
  root
65
88
  #parent
66
-
67
89
  #isPreload = false
90
+ #host
68
91
 
69
- // Claimed write-target paths (canonicalized -> label), for cross-State collision detection.
92
+ // Claimed write-target paths (canonicalized -> label), for cross-State collision detection; a
93
+ // State built with `claim: false`, which never writes (a static build), claims none.
94
+ #claim
70
95
  #claims = new Map()
71
96
 
72
97
  // WRITE-mode sidecars: lockfile CONTRIBUTORS (#mergedImports/#mergedFormats union theirs in).
73
98
  #sidecars = new Set()
74
-
75
99
  // LOAD-mode sidecars: read-only, NOT lockfile contributors (getFs*Family serves bytes from them).
76
100
  #readSidecars = new Set()
77
101
 
78
- // Lockfile-attested resolutions (conditions -> parent -> specifier -> file), or null; may be a
79
- // superset of what a run observes, so kept apart from this.imports.
102
+ // Lockfile-attested resolutions (conditions -> parent -> specifier -> file) and loader formats
103
+ // (file -> format), or null; may be supersets of what a run observes, so kept apart from the live maps.
80
104
  #lockImports = null
81
-
82
- // Lockfile-attested loader formats (file -> format), or null; kept apart from this.formats.
83
105
  #lockFormats = null
84
-
85
106
  // Loaded a lockfile at construction: #mergeBundleMetadata cross-checks bundle metadata against
86
107
  // it instead of absorbing it as source of truth.
87
108
  #lockfileLoaded = false
@@ -108,6 +129,17 @@ export class State {
108
129
  // shim: require.resolve()/CJS require()s bypassing the resolve hook.
109
130
  #observedResolutions = new Map()
110
131
 
132
+ // Files a require() actually EXECUTED (from the Module._load shim) -- unlike a resolve-only
133
+ // edge, an executed file with no captured bytes is a hole in the attestation, so write()
134
+ // backfills it from disk (a transplanted require.extensions handler, e.g. a transforming
135
+ // preload's CJS TypeScript pipeline, loads files without ever hitting the load hook).
136
+ #executedFiles = new Set()
137
+
138
+ // Files whose BYTES this run captured via addFile. Distinct from this.hashes, which also
139
+ // absorbs lockfile-seeded entries: #backfillExecutedFiles must key on "observed this run", or
140
+ // a frozen/add run would skip verifying an executed file merely because a hash is on record.
141
+ #filesCapturedThisRun = new Set()
142
+
111
143
  // Node's require-condition set, from the first require()-context addImport;
112
144
  // #backfillObservedResolutions keys native edges under it so the lockfile is Node-version-stable.
113
145
  #requireConditions = null
@@ -121,14 +153,25 @@ export class State {
121
153
  #lastUnifiedBundle = null
122
154
  #lastCodeBundle = null
123
155
  #lastResourcesBundle = null
156
+ // Lazy `{ value: detectRepo(this.root, this.#host) }`.
157
+ #detectedRepoCache
158
+ // Half ('code' | 'resources') -> `repo` of the bundle absorbed there for adding to.
159
+ #absorbedRepos = new Map()
124
160
 
125
- // Options: `preload` (the unique preload State) and `parent` (run as a sidecar sharing the
126
- // parent's hashes/entries/modules, with its own sources/formats/imports/resources and bundle).
127
- // All other keys forward to Config.
161
+ // Memoized #canonicalUncached (per URL, State-lifetime): a realpathSync per node_modules URL, and
162
+ // hot callers repeat relentlessly. Sound only because the tree holds still mid-run; the cached
163
+ // result is shared -- never mutate it.
164
+ #canonicalCache = new Map()
165
+
166
+ // Options: `preload` (the unique preload State), `parent` (run as a sidecar sharing the parent's
167
+ // hashes/entries/modules, with its own sources/formats/imports/resources and bundle) and
168
+ // `skipDiscovery` (a caller-populated in-memory State, NO filesystem discovery; read-only modes
169
+ // only). All other keys forward to Config.
128
170
  constructor(root, options = {}) {
129
- // skipDiscovery: caller-populated in-memory State, NO filesystem discovery; read-only modes only.
130
- const { preload: isPreload = false, parent: parentState, preloadRoot, skipDiscovery = false, ...configOptions } = options
131
- this.config = new Config(configOptions)
171
+ const { preload: isPreload = false, parent: parentState, preloadRoot, skipDiscovery = false, host = diskHost, env = process.env, claim = true, ...configOptions } = options
172
+ this.config = new Config({ ...configOptions, env, host })
173
+ this.#host = host
174
+ this.#claim = claim
132
175
  if (isPreload) assert.ok(!State.preload, 'Only one preload Stasis instance is supported')
133
176
  assert.ok(!(isPreload && parentState), 'preload and parent are mutually exclusive')
134
177
  this.#isPreload = isPreload
@@ -153,16 +196,13 @@ export class State {
153
196
  assert.ok(this.config.bundleFile, 'sidecar State requires bundleFile')
154
197
  // Only writing States claim, so two write-intent States can't silently target the same file.
155
198
  if (this.config.writeBundle) {
156
- this.#claimWritePath(`sidecar bundleFile '${this.config.bundleFile}'`, this.config.bundleFile)
157
- if (this.config.resourcesBundleFile) {
158
- this.#claimWritePath(`sidecar resourcesBundleFile '${this.config.resourcesBundleFile}'`,
159
- this.config.resourcesBundleFile)
160
- }
199
+ this.#claimWritePath('bundleFile', 'sidecar ')
200
+ this.#claimWritePath('resourcesBundleFile', 'sidecar ')
161
201
  }
162
202
  // frozenBundle MUST go through this branch too -- it has its own attestation snapshot to build.
163
- if (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) {
203
+ if (this.config.bundle) {
164
204
  const sourcesPath = this.config.bundleFile
165
- const sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
205
+ const sources = this.#readMaybe(sourcesPath)
166
206
  if (sources && !this.config.replaceBundle) {
167
207
  const bundle = Bundle.parse(brotliDecompressSync(sources).toString('utf-8'))
168
208
  // v0 bundle has no per-file formats or import map -- serving one via a sidecar widens trust.
@@ -170,32 +210,11 @@ export class State {
170
210
  `stasis sidecar requires a v1 bundle; ${sourcesPath} is v${bundle.version}. ` +
171
211
  `Re-bundle with the current stasis or \`bundle=replace\` against a v0-free starting point.`)
172
212
  assert.equal(bundle.config.scope, this.config.scope)
173
- // Cross-check against the parent's lockfile, or absorb if none (shared hashes/entries/
213
+ // Cross-checked against the parent's lockfile, or absorbed if none (shared hashes/entries/
174
214
  // modules mean those writes propagate to the parent).
175
- this.#mergeBundleMetadata(bundle, { lockfileLoaded: this.#lockfileLoaded })
176
- for (const [file, content] of bundle.sources) {
177
- if (Bundle.isResourceFormat(bundle.formats.get(file))) this.resources.set(file, content)
178
- else this.sources.set(file, content)
179
- }
180
- this.formats = bundle.formats
181
- this.imports = bundle.imports
182
- this.#absorbExecutable(bundle)
183
- this.#seedReasonFromBundle(bundle)
184
- if (this.config.frozenBundle) {
185
- this.#bundleSources = new Set(this.sources.keys())
186
- this.#bundleResources = new Set(this.resources.keys())
187
- this.#bundleImports = objectToMaps(fileMapToObject(bundle.imports))
188
- this.#bundleFormats = new Map(bundle.formats)
189
- }
190
- }
191
-
192
- if (this.config.resourcesBundleFile) {
193
- const resourcesPath = this.config.resourcesBundleFile
194
- const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
195
- if (resourcesData && !this.config.replaceBundle) {
196
- this.#absorbResourcesBundle(resourcesData, { lockfileLoaded: this.#lockfileLoaded, resourcesPath })
197
- }
215
+ this.#absorbCodeBundle(bundle, this.#lockfileLoaded)
198
216
  }
217
+ this.#absorbResourcesBundleFile(this.#lockfileLoaded)
199
218
  }
200
219
  if (this.config.frozenBundle) {
201
220
  assert.ok(this.#bundleSources !== null, 'No bundle, but attempting to run in frozen bundle mode')
@@ -204,7 +223,7 @@ export class State {
204
223
  // join neither registry (--fs neither captures nor serves in frozen-bundle mode).
205
224
  if (this.config.writeBundle) parentState.registerSidecar(this)
206
225
  else if (this.config.loadBundle) parentState.registerReadSidecar(this)
207
- liveStates().add(this)
226
+ if (this.#claims.size > 0) liveStates().add(this)
208
227
  return
209
228
  }
210
229
 
@@ -212,32 +231,24 @@ export class State {
212
231
  assert.ok(!this.config.frozen && !this.config.frozenBundle && !this.config.writeBundle && !this.config.writeLockfile,
213
232
  'skipDiscovery is read-only: incompatible with frozen and write (add/replace) lock/bundle modes')
214
233
  this.root = resolve(root)
215
- if (preloadRoot !== undefined) {
216
- assert.equal(typeof preloadRoot, 'string', 'preloadRoot must be a string')
217
- this.#preloadRoot = preloadRoot
218
- }
219
- liveStates().add(this)
234
+ this.#setPreloadRoot(preloadRoot)
235
+ if (isPreload) liveStates().add(this)
220
236
  return
221
237
  }
222
238
 
239
+ // Capture and load MUST agree on where the upward walk stops (PROJECT_CWD/.git/
240
+ // pnpm-workspace.yaml), else they commit different roots and fail "outside the project root".
223
241
  const potentialRoots = []
224
- let cursor = root
225
- while (cursor) {
226
- if (existsSync(join(cursor, 'package.json'))) {
242
+ for (let cursor = root; cursor; cursor = dirname(cursor)) {
243
+ // One there that can't be read is refused, not walked past to a root above (packageJSONStat).
244
+ if (packageJSONStat(this.#host, join(cursor, 'package.json')) !== null) {
227
245
  potentialRoots.push(cursor)
228
- } else if (
229
- existsSync(join(cursor, FILE_CONFIG)) ||
230
- existsSync(join(cursor, FILE_LOCK)) ||
231
- existsSync(join(cursor, FILE_CODE))) {
246
+ } else if ([FILE_CONFIG, FILE_LOCK, FILE_CODE].some((file) => this.#exists(join(cursor, file)))) {
232
247
  throw new Error('Unexpected stasis config without package.json')
233
248
  }
234
-
235
- if (cursor === process.env.PROJECT_CWD) break // e.g. yarn sets this
236
- if (existsSync(join(cursor, '.git'))) break
237
- if (existsSync(join(cursor, 'pnpm-workspace.yaml'))) break
238
- const parent = dirname(cursor)
239
- if (!parent || parent === cursor) break
240
- cursor = parent
249
+ if (cursor === env.PROJECT_CWD) break // e.g. yarn sets this
250
+ if (this.#exists(join(cursor, '.git')) || this.#exists(join(cursor, 'pnpm-workspace.yaml'))) break
251
+ if (dirname(cursor) === cursor) break
241
252
  }
242
253
 
243
254
  // default root is top-level package.json, to opt-in to per-dir create stasis.config.json
@@ -254,57 +265,45 @@ export class State {
254
265
  // root. A config-only bundleFile is NOT suppressed (its dir already carries the config signal).
255
266
  const explicitBundlePath = this.config.bundleFile
256
267
  for (const rootDir of potentialRoots) {
257
- const config = readFileSyncMaybe(rootDir, FILE_CONFIG, 'utf-8')
258
- const lockProbe = explicitLockPath ? null : readFileSyncMaybe(rootDir, FILE_LOCK, 'utf-8')
259
- let sourcesPath = this.config.bundleFile || join(rootDir, FILE_CODE)
260
- let sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
261
- // Root-SELECTION signal: only the DEFAULT <rootDir>/stasis.code.br counts (see
262
- // explicitBundlePath); an explicit bundleFile is still loaded via `sources`.
263
- const bundleProbe = explicitBundlePath ? null : sources
264
- if (config !== null || lockProbe !== null || bundleProbe !== null) {
265
- if (loaded) throw new Error('Stasis config already loaded')
266
- loaded = true
267
- this.root = rootDir
268
-
269
- if (config) {
270
- this.config.loadConfig(config)
271
- // stasis.config.json may set a `bundleFile` the probe couldn't see -- re-resolve and re-read.
272
- const configuredPath = this.config.bundleFile || join(rootDir, FILE_CODE)
273
- if (configuredPath !== sourcesPath) {
274
- sourcesPath = configuredPath
275
- sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
276
- }
268
+ const config = readFileSyncMaybe(rootDir, FILE_CONFIG, 'utf-8', this.#host)
269
+ const lockProbe = explicitLockPath ? null : readFileSyncMaybe(rootDir, FILE_LOCK, 'utf-8', this.#host)
270
+ let sourcesPath = explicitBundlePath || join(rootDir, FILE_CODE)
271
+ let sources = this.#readMaybe(sourcesPath)
272
+ // Root-SELECTION signals: a config, a lockfile, or only the DEFAULT <rootDir>/stasis.code.br
273
+ // (see explicitBundlePath; an explicit bundleFile is still loaded via `sources`).
274
+ if (config === null && lockProbe === null && (explicitBundlePath || sources === null)) continue
275
+ if (loaded) throw new Error('Stasis config already loaded')
276
+ loaded = true
277
+ this.root = rootDir
278
+
279
+ if (config) {
280
+ this.config.loadConfig(config)
281
+ // stasis.config.json may set a `bundleFile` the probe couldn't see -- re-resolve and re-read.
282
+ const configuredPath = this.config.bundleFile || join(rootDir, FILE_CODE)
283
+ if (configuredPath !== sourcesPath) {
284
+ sourcesPath = configuredPath
285
+ sources = this.#readMaybe(sourcesPath)
277
286
  }
287
+ }
278
288
 
279
- const lock = explicitLockPath
280
- ? readFileSyncMaybe(dirname(explicitLockPath), basename(explicitLockPath), 'utf-8')
281
- : lockProbe
282
- const lockPath = explicitLockPath || join(rootDir, FILE_LOCK)
283
-
284
- lockfileLoaded = this.#absorbLockfile(lock, lockPath)
285
- this.#loadBundleArtifacts(sources, sourcesPath, lockfileLoaded)
289
+ const lock = explicitLockPath ? this.#readMaybe(explicitLockPath, 'utf-8') : lockProbe
290
+ lockfileLoaded = this.#absorbLockfile(lock, explicitLockPath || join(rootDir, FILE_LOCK))
291
+ this.#loadBundleArtifacts(sources, sourcesPath, lockfileLoaded)
286
292
 
287
- // Innermost matching rootDir wins (per-dir opt-in); without this break an outer root
288
- // re-detects a rootDir-independent bundleFile and trips `loaded`.
289
- break
290
- }
293
+ // Innermost matching rootDir wins (per-dir opt-in); without this break an outer root
294
+ // re-detects a rootDir-independent bundleFile and trips `loaded`.
295
+ break
291
296
  }
292
297
 
293
298
  // Explicit lockfile but no discovery indicator: the loop never ran, so absorb here against
294
299
  // `this.root` (outermost) so the run still has attestation.
295
300
  if (!loaded && explicitLockPath) {
296
- const lock = readFileSyncMaybe(dirname(explicitLockPath), basename(explicitLockPath), 'utf-8')
297
- lockfileLoaded = this.#absorbLockfile(lock, explicitLockPath)
301
+ lockfileLoaded = this.#absorbLockfile(this.#readMaybe(explicitLockPath, 'utf-8'), explicitLockPath)
298
302
  }
299
303
 
300
304
  // Explicit bundleFile suppressed as a root signal above: load against `this.root` (outermost).
301
- // Capture and load MUST agree on where the upward walk stops (PROJECT_CWD/.git/
302
- // pnpm-workspace.yaml), else they commit different roots and fail "outside the project root".
303
305
  if (!loaded && (explicitBundlePath || this.config.resourcesBundleFile)) {
304
- const sources = explicitBundlePath
305
- ? readFileSyncMaybe(dirname(explicitBundlePath), basename(explicitBundlePath))
306
- : null
307
- this.#loadBundleArtifacts(sources, explicitBundlePath, lockfileLoaded)
306
+ this.#loadBundleArtifacts(explicitBundlePath ? this.#readMaybe(explicitBundlePath) : null, explicitBundlePath, lockfileLoaded)
308
307
  }
309
308
 
310
309
  // Post-loop: with no stasis files the loop never runs, and a frozen run must fail closed.
@@ -312,22 +311,31 @@ export class State {
312
311
  if (this.config.frozenBundle) assert.ok(this.#bundleSources !== null, 'No bundle, but attempting to run in frozen bundle mode')
313
312
 
314
313
  // Claim write targets so no other live State (any copy) silently targets the same file.
315
- if (this.config.writeBundle && this.config.bundleFile) {
316
- this.#claimWritePath(`bundleFile '${this.config.bundleFile}'`, this.config.bundleFile)
317
- }
318
- if (this.config.writeBundle && this.config.resourcesBundleFile) {
319
- this.#claimWritePath(`resourcesBundleFile '${this.config.resourcesBundleFile}'`, this.config.resourcesBundleFile)
320
- }
321
- if (this.config.writeLockfile && this.config.lockFile) {
322
- this.#claimWritePath(`lockFile '${this.config.lockFile}'`, this.config.lockFile)
314
+ if (this.config.writeBundle) {
315
+ this.#claimWritePath('bundleFile')
316
+ this.#claimWritePath('resourcesBundleFile')
323
317
  }
318
+ if (this.config.writeLockfile) this.#claimWritePath('lockFile')
324
319
 
325
- if (preloadRoot !== undefined) {
326
- assert.equal(typeof preloadRoot, 'string', 'preloadRoot must be a string')
327
- this.#preloadRoot = preloadRoot
328
- }
320
+ this.#setPreloadRoot(preloadRoot)
321
+
322
+ // The registry answers for the preload and for write claims; any other State stays out of it.
323
+ if (isPreload || this.#claims.size > 0) liveStates().add(this)
324
+ }
325
+
326
+ #exists(p) {
327
+ return this.#host.stat(p) !== null
328
+ }
329
329
 
330
- liveStates().add(this)
330
+ // The file at `path` through the host, or null when there is none.
331
+ #readMaybe(path, encoding) {
332
+ return readFileSyncMaybe(dirname(path), basename(path), encoding, this.#host)
333
+ }
334
+
335
+ #setPreloadRoot(preloadRoot) {
336
+ if (preloadRoot === undefined) return
337
+ assert.equal(typeof preloadRoot, 'string', 'preloadRoot must be a string')
338
+ this.#preloadRoot = preloadRoot
331
339
  }
332
340
 
333
341
  // Absorb a lockfile's attestation; returns whether it was actually absorbed. Lockfile.parse
@@ -348,9 +356,7 @@ export class State {
348
356
  if (includeSources) this.entries = lockfile.entries
349
357
 
350
358
  for (const [dir, { files }] of this.modules) {
351
- for (const [name, hash] of Object.entries(files)) {
352
- noupsert(this.hashes, join(dir, name), hash)
353
- }
359
+ for (const [name, hash] of Object.entries(files)) noupsert(this.hashes, join(dir, name), hash)
354
360
  }
355
361
  this.#lockImports = lockfile.imports
356
362
  this.#lockFormats = lockfile.formats
@@ -361,29 +367,33 @@ export class State {
361
367
  return true
362
368
  }
363
369
 
370
+ // An on-disk bundle is read in under add/load/frozen; replace starts over.
371
+ get #absorbsBundles() {
372
+ return this.config.bundle && !this.config.replaceBundle
373
+ }
374
+
364
375
  // Gate and load the bundle artifacts for a committed root; `sources` may be null (no bundle, or
365
376
  // resources-only).
366
377
  #loadBundleArtifacts(sources, sourcesPath, lockfileLoaded) {
367
- if (sources && !this.config.writeBundle && !this.config.loadBundle && !this.config.ignoreBundle && !this.config.frozenBundle) {
378
+ if (sources && this.config.bundleMode === 'none') {
368
379
  throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
369
380
  }
370
381
  // A frozen bundle is self-attesting, so it needs no sibling lockfile and is exempt here.
371
382
  if (sources && !lockfileLoaded && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
372
383
  throw new Error('stasis.lock.json missing, can not use sources')
373
384
  }
374
- if (sources && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
375
- this.#absorbCodeBundle(sources, sourcesPath, lockfileLoaded)
376
- }
377
- if (this.config.resourcesBundleFile) {
378
- const resourcesPath = this.config.resourcesBundleFile
379
- const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
380
- if (resourcesData && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
381
- this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
382
- }
383
- }
385
+ if (sources && this.#absorbsBundles) this.#loadCodeBundle(sources, sourcesPath, lockfileLoaded)
386
+ this.#absorbResourcesBundleFile(lockfileLoaded)
384
387
  }
385
388
 
386
- #absorbCodeBundle(sources, sourcesPath, lockfileLoaded) {
389
+ // The resources half of a split layout, when configured and present on disk.
390
+ #absorbResourcesBundleFile(lockfileLoaded) {
391
+ const resourcesPath = this.config.resourcesBundleFile
392
+ const resourcesData = resourcesPath ? this.#readMaybe(resourcesPath) : null
393
+ if (resourcesData && this.#absorbsBundles) this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
394
+ }
395
+
396
+ #loadCodeBundle(sources, sourcesPath, lockfileLoaded) {
387
397
  const bundle = Bundle.parse(brotliDecompressSync(sources).toString('utf-8'))
388
398
  // Bundle.parse accepts v0 for offline tooling; the runtime refuses it -- v0 has no per-file
389
399
  // formats or import map, so serving one widens the trust boundary.
@@ -397,6 +407,12 @@ export class State {
397
407
  assert.ok(!this.config.full || bundle.entries.size > 0 || !bundle.hasCode,
398
408
  `${sourcesPath}: a full-scope bundle carrying code must declare an entry to run ` +
399
409
  `(an add-only attestation has none; run a bundle built by \`stasis bundle\`/\`stasis run\`)`)
410
+ this.#absorbCodeBundle(bundle, lockfileLoaded)
411
+ }
412
+
413
+ // Take a parsed code bundle (unified, or the code half) as the live maps, cross-checked against
414
+ // the loaded lockfile, and snapshot it when it is the frozen attestation.
415
+ #absorbCodeBundle(bundle, lockfileLoaded) {
400
416
  this.#mergeBundleMetadata(bundle, { lockfileLoaded })
401
417
  for (const [file, content] of bundle.sources) {
402
418
  if (Bundle.isResourceFormat(bundle.formats.get(file))) this.resources.set(file, content)
@@ -406,6 +422,7 @@ export class State {
406
422
  this.imports = bundle.imports
407
423
  this.#absorbExecutable(bundle)
408
424
  this.#seedReasonFromBundle(bundle)
425
+ this.#absorbRepo('code', bundle)
409
426
  if (this.config.frozenBundle) {
410
427
  // Snapshot before addFile/addImport mutate the live maps; imports is deep-cloned because
411
428
  // this.imports shares bundle.imports's nested Maps.
@@ -421,18 +438,21 @@ export class State {
421
438
  #mergeBundleMetadata(bundle, { lockfileLoaded }) {
422
439
  if (lockfileLoaded) {
423
440
  if (bundle.entries.size > 0) {
424
- assert.deepStrictEqual(
425
- [...bundle.entries].toSorted(),
426
- [...this.entries].toSorted(),
427
- 'bundle/lockfile entries mismatch'
428
- )
441
+ assert.deepStrictEqual([...bundle.entries].toSorted(), [...this.entries].toSorted(), 'bundle/lockfile entries mismatch')
429
442
  }
430
443
  for (const [dir, info] of bundle.modules) {
431
444
  if (!info.name) continue // workspace bucket or fallback: no inferable name
432
445
  assert.ok(this.modules.has(dir), `bundle module ${dir} missing in lockfile`)
433
446
  const lockModule = this.modules.get(dir)
434
447
  assert.equal(info.name, lockModule.name)
435
- if (info.version) assert.equal(info.version, lockModule.version)
448
+ // Strict, absent included: every absorb site requires a v1 bundle, so a missing version is
449
+ // a real workspace identity (or a stripped field), never v0 partial metadata -- a
450
+ // version-less bundle bucket must not dodge the lockfile consistency check.
451
+ assert.equal(info.version, lockModule.version, `bundle module ${dir} version mismatch with lockfile`)
452
+ assert.ok(reposAgree(info.repo, lockModule.repo), `bundle module ${dir} repo mismatch with lockfile`)
453
+ // A lockfile from before the field records none: the bundle's then holds the package.json
454
+ // read and the other half of a split bundle to it.
455
+ if (lockModule.repo === undefined && info.repo !== undefined) this.modules.set(dir, moduleInfo({ ...lockModule, repo: info.repo }))
436
456
  for (const rel of Object.keys(info.files)) {
437
457
  assert.ok(Object.hasOwn(lockModule.files, rel), `bundle file ${dir}/${rel} missing in lockfile`)
438
458
  }
@@ -470,16 +490,18 @@ export class State {
470
490
  // Mutate in place: this.entries may be shared by reference with a sidecar's parent.
471
491
  for (const e of bundle.entries) this.entries.add(e)
472
492
  for (const [dir, info] of bundle.modules) {
473
- if (!info.name || !info.version) continue // partial metadata
474
- if (this.modules.has(dir)) {
493
+ // Skip v0 partial metadata (nameless workspace buckets, version-less node_modules
494
+ // buckets); a v1 workspace bucket may omit version, so its identity is absorbed anyway.
495
+ if (!info.name || (!info.version && hasNodeModulesSegment(dir))) continue
496
+ const existing = this.modules.get(dir)
497
+ if (existing === undefined) {
498
+ this.modules.set(dir, moduleInfo({ ...info, files: Object.create(null) }))
499
+ } else {
475
500
  // A dir may be added twice (code + resource entries), and both must agree.
476
- const existing = this.modules.get(dir)
477
501
  assert.equal(info.name, existing.name, `bundle ${dir} name mismatch`)
478
502
  assert.equal(info.version, existing.version, `bundle ${dir} version mismatch`)
479
- } else {
480
- this.modules.set(dir, info.ecosystem === undefined
481
- ? { name: info.name, version: info.version, files: Object.create(null) }
482
- : { name: info.name, version: info.version, ecosystem: info.ecosystem, files: Object.create(null) })
503
+ assert.ok(reposAgree(info.repo, existing.repo), `bundle ${dir} repo mismatch`)
504
+ if (existing.repo === undefined && info.repo !== undefined) this.modules.set(dir, moduleInfo({ ...existing, repo: info.repo }))
483
505
  }
484
506
  }
485
507
  }
@@ -501,9 +523,7 @@ export class State {
501
523
  `resources bundle ${resourcesPath} declares non-resource format='${format}' for ${file}`)
502
524
  }
503
525
  this.#mergeBundleMetadata(bundle, { lockfileLoaded })
504
- for (const [file, content] of bundle.sources) {
505
- this.resources.set(file, content)
506
- }
526
+ for (const [file, content] of bundle.sources) this.resources.set(file, content)
507
527
  // Union formats: the two halves' file sets must be disjoint.
508
528
  for (const [file, format] of bundle.formats) {
509
529
  const existing = this.formats.get(file)
@@ -513,13 +533,14 @@ export class State {
513
533
  }
514
534
  this.#absorbExecutable(bundle)
515
535
  this.#seedReasonFromBundle(bundle)
536
+ this.#absorbRepo('resources', bundle)
516
537
  if (this.config.frozenBundle) {
517
538
  // Extend the frozen snapshot, init lazily: resources-only deployments are legal, so
518
539
  // bundleFile may not have populated these.
519
- if (this.#bundleResources === null) this.#bundleResources = new Set()
520
- if (this.#bundleFormats === null) this.#bundleFormats = new Map()
521
- if (this.#bundleImports === null) this.#bundleImports = objectToMaps(fileMapToObject(this.imports))
522
- if (this.#bundleSources === null) this.#bundleSources = new Set(this.sources.keys())
540
+ this.#bundleResources ??= new Set()
541
+ this.#bundleFormats ??= new Map()
542
+ this.#bundleImports ??= objectToMaps(fileMapToObject(this.imports))
543
+ this.#bundleSources ??= new Set(this.sources.keys())
523
544
  for (const f of bundle.sources.keys()) this.#bundleResources.add(f)
524
545
  for (const [f, fmt] of bundle.formats) this.#bundleFormats.set(f, fmt)
525
546
  }
@@ -564,7 +585,7 @@ export class State {
564
585
  }
565
586
 
566
587
  assertEntry(url) {
567
- // No entry attestation to check against (lock=none/ignore, fresh build) -- #absorbCodeBundle
588
+ // No entry attestation to check against (lock=none/ignore, fresh build) -- #loadCodeBundle
568
589
  // already refuses a runnable code bundle that declares none.
569
590
  if (this.entries.size === 0) return
570
591
  const file = this.#canonicalFile(url)
@@ -587,13 +608,15 @@ export class State {
587
608
  }
588
609
 
589
610
  // Refuse a path another live State (ANY copy) already claims; canonicalized so `./x`/`x`/symlinks
590
- // compare equal.
591
- #claimWritePath(label, value) {
592
- if (!value) return
593
- const canonical = canonicalizePath(value)
611
+ // compare equal. `key` names the config option; nothing is claimed when it is unset.
612
+ #claimWritePath(key, prefix = '') {
613
+ const value = this.config[key]
614
+ if (!value || !this.#claim) return
615
+ const label = `${prefix}${key} '${value}'`
616
+ const canonical = canonicalizePath(value, this.#host)
594
617
  for (const other of liveStates()) {
595
618
  const owner = other.claimedWritePathLabel(canonical)
596
- assert.ok(owner === undefined, `${label} '${value}' is already claimed by ${owner} of another live State`)
619
+ assert.ok(owner === undefined, `${label} is already claimed by ${owner} of another live State`)
597
620
  }
598
621
  this.#claims.set(canonical, label)
599
622
  }
@@ -634,16 +657,11 @@ export class State {
634
657
  relative(absolute) {
635
658
  assert.ok(absolute)
636
659
  const file = relative(this.root, absolute)
637
- assert.ok(!file.startsWith('..'))
660
+ assert.ok(!relativeEscapes(file))
638
661
  // The project root is keyed '.', never '' -- mixing the two desyncs write from read.
639
662
  return file === '' ? '.' : file
640
663
  }
641
664
 
642
- // Memoized #canonicalUncached (per URL, State-lifetime): a realpathSync per node_modules URL, and
643
- // hot callers repeat relentlessly. Sound only because the tree holds still mid-run; the cached
644
- // result is shared -- never mutate it.
645
- #canonicalCache = new Map()
646
-
647
665
  #canonical(url) {
648
666
  let result = this.#canonicalCache.get(url)
649
667
  if (result === undefined) {
@@ -658,16 +676,16 @@ export class State {
658
676
  #canonicalUncached(url) {
659
677
  const absolute = this.absolute(url)
660
678
  const file = relative(this.root, absolute)
661
- if (file.startsWith('..') || !splitNodeModulesPath(file)) return { url, absolute }
679
+ if (relativeEscapes(file) || !splitNodeModulesPath(file)) return { url, absolute }
662
680
  let real
663
681
  try {
664
- real = realpathSync(absolute)
682
+ real = this.#host.realpath(absolute)
665
683
  } catch {
666
684
  return { url, absolute }
667
685
  }
668
686
  if (real === absolute) return { url, absolute }
669
687
  const realFile = relative(this.root, real)
670
- if (realFile.startsWith('..') || splitNodeModulesPath(realFile)) return { url, absolute }
688
+ if (relativeEscapes(realFile) || splitNodeModulesPath(realFile)) return { url, absolute }
671
689
  return { url: pathToFileURL(real).toString(), absolute: real }
672
690
  }
673
691
 
@@ -675,29 +693,31 @@ export class State {
675
693
  return this.relative(this.#canonical(url).absolute)
676
694
  }
677
695
 
678
- // True when `url` resolves (through any workspace symlink) into node_modules -- not a raw
679
- // `/node_modules/` substring test, so a symlinked workspace source is read from disk.
680
- inNodeModules(url) {
681
- let file
696
+ // #canonicalFile, or undefined for a URL outside the project root (the shims then pass through).
697
+ #canonicalFileMaybe(url) {
682
698
  try {
683
- file = this.#canonicalFile(url)
699
+ return this.#canonicalFile(url)
684
700
  } catch {
685
- return false
701
+ return undefined
686
702
  }
687
- return splitNodeModulesPath(file) !== null
703
+ }
704
+
705
+ // True when `url` resolves (through any workspace symlink) into node_modules -- not a raw
706
+ // `/node_modules/` substring test, so a symlinked workspace source is read from disk.
707
+ inNodeModules(url) {
708
+ const file = this.#canonicalFileMaybe(url)
709
+ return file !== undefined && splitNodeModulesPath(file) !== null
688
710
  }
689
711
 
690
712
  // Nearest package.json at or above a directory (findPackageJSON is unreliable for a directory
691
- // URL, see #locateModule). Bounded by the project root.
713
+ // URL, see #locateModule), refusing one there that can't be read as findPackageJSON does
714
+ // (packageJSONStat). Bounded by the project root.
692
715
  #nearestPackageJsonFor(dirAbsolute) {
693
- let dir = dirAbsolute
694
- while (true) {
716
+ for (let dir = dirAbsolute; ; dir = dirname(dir)) {
695
717
  const candidate = join(dir, 'package.json')
696
- if (existsSync(candidate)) return candidate
697
- if (dir === this.root) break // checked the root's package.json; never escape root
698
- const parent = dirname(dir)
699
- if (parent === dir) break
700
- dir = parent
718
+ if (packageJSONStat(this.#host, candidate)?.isFile()) return candidate
719
+ // The root's package.json was just checked; never escape root.
720
+ if (dir === this.root || dirname(dir) === dir) break
701
721
  }
702
722
  // Unreachable: state.root is resolved to a dir that has package.json.
703
723
  assert.fail(`no package.json at or above directory ${this.relative(dirAbsolute)}`)
@@ -707,53 +727,48 @@ export class State {
707
727
  // ourselves -- Node's findPackageJSON is unreliable for a directory URL (EISDIR, or the parent's).
708
728
  #locateModule(url, { directory = false } = {}) {
709
729
  // Canonicalize first: a linked-in workspace source is recorded under its real path (a source).
710
- const canonical = this.#canonical(url)
711
- url = canonical.url
712
- const absolute = canonical.absolute
713
- assert.ok(existsSync(absolute))
730
+ const { absolute } = this.#canonical(url)
731
+ assert.ok(this.#host.stat(absolute) !== null)
714
732
  const file = this.relative(absolute)
715
733
 
716
- const closestPkgAbsolute = directory ? this.#nearestPackageJsonFor(absolute) : findPackageJSON(url)
717
- const closestPkg = readPackageJSON(closestPkgAbsolute)
734
+ const closestPkgAbsolute = directory ? this.#nearestPackageJsonFor(absolute) : this.#host.findPackageJSON(absolute)
735
+ const closestPkg = readPackageJSON(this.#host, closestPkgAbsolute)
718
736
 
719
737
  const closestType = closestPkg.type
720
738
  assert.ok(closestType === undefined || closestType === 'module' || closestType === 'commonjs')
721
739
 
722
740
  // findPackageJSON may land on a `{"type":"module"}` sub-bucket marker lacking name/version.
723
741
  const nmRoot = splitNodeModulesPath(file)?.dir
724
- let pkgAbsolute, name, version
742
+ let pkgAbsolute, name, version, repo
725
743
  if (nmRoot) {
726
744
  pkgAbsolute = resolve(this.root, nmRoot, 'package.json')
727
- const rootPkg = pkgAbsolute === closestPkgAbsolute ? closestPkg : readPackageJSON(pkgAbsolute)
745
+ const rootPkg = pkgAbsolute === closestPkgAbsolute ? closestPkg : readPackageJSON(this.#host, pkgAbsolute)
728
746
  ;({ name, version } = rootPkg)
747
+ repo = packageRepo(rootPkg)
729
748
  assert.ok(name, `Missing name in ${this.relative(pkgAbsolute)}`)
730
749
  assert.ok(version, `Missing version in ${this.relative(pkgAbsolute)}`)
731
- if (closestPkgAbsolute !== pkgAbsolute) {
750
+ if (closestPkgAbsolute !== pkgAbsolute && !isInconsistentPackageJsonException(this.relative(closestPkgAbsolute))) {
732
751
  const message = `Inconsistent data between ${this.relative(closestPkgAbsolute)} and ${this.relative(pkgAbsolute)}`
733
- if (closestPkg.name !== undefined && closestPkg.name !== name) {
734
- // Allow fake module-name subpaths: the real module owns the prefix (npm wouldn't publish this).
735
- assert.ok(closestPkg.name.startsWith(`${name}/`), message)
736
- }
737
-
752
+ // Allow fake module-name subpaths: the real module owns the prefix (npm wouldn't publish this).
753
+ if (closestPkg.name !== undefined && closestPkg.name !== name) assert.ok(closestPkg.name.startsWith(`${name}/`), message)
738
754
  if (closestPkg.version !== undefined) assert.equal(closestPkg.version, version, message)
739
755
  }
740
756
  } else {
741
757
  pkgAbsolute = closestPkgAbsolute
742
758
  let json = closestPkg
743
- while (true) {
744
- if (json.name !== undefined && json.version !== undefined) {
745
- ;({ name, version } = json)
746
- break
747
- }
759
+ // A workspace package outside node_modules may omit version (private/unpublished): the
760
+ // name alone claims the bucket. node_modules buckets (above) still require both.
761
+ while (json.name === undefined) {
748
762
  assert.ok(Object.keys(json).every((k) => k === 'type'))
749
- const next = findPackageJSON('..', pathToFileURL(pkgAbsolute))
750
- assert.ok(
751
- next && !relative(this.root, next).startsWith('..'),
752
- `No package.json with name+version found for ${file}`
753
- )
754
- pkgAbsolute = next
755
- json = readPackageJSON(pkgAbsolute)
763
+ const dir = dirname(pkgAbsolute)
764
+ assert.ok(dir !== this.root && isPathWithin(this.root, dir), `No package.json with a name found for ${file}`)
765
+ pkgAbsolute = this.#nearestPackageJsonFor(dirname(dir))
766
+ json = readPackageJSON(this.#host, pkgAbsolute)
756
767
  }
768
+ name = json.name
769
+ // A literal `"version": null` folds to undefined here too: the parsers normalize the same
770
+ // way, and recording null verbatim would split identity on the next run's re-read.
771
+ version = json.version ?? undefined
757
772
  }
758
773
  const pkg = this.relative(pkgAbsolute)
759
774
  assert.ok(pkg === 'package.json' || pkg.endsWith('/package.json'))
@@ -762,13 +777,25 @@ export class State {
762
777
  if (nmRoot) assert.equal(dir, nmRoot)
763
778
  if (!this.modules.has(dir)) {
764
779
  // Tag node_modules buckets `npm`; workspace/top-level buckets carry no ecosystem.
765
- this.modules.set(dir, nmRoot
766
- ? { name, version, ecosystem: 'npm', files: Object.create(null) }
767
- : { name, version, files: Object.create(null) })
780
+ this.modules.set(dir, moduleInfo({ name, version, ecosystem: nmRoot ? 'npm' : undefined, repo, files: Object.create(null) }))
768
781
  }
769
782
  const module = this.modules.get(dir)
770
- assert.equal(module.name, name)
771
- assert.equal(module.version, version)
783
+ if (module.name !== name || module.version !== version) {
784
+ // Message built only on failure: addFile is hot, and the mismatch is a migration/drift event.
785
+ const hint = (module.version == null) === (version == null) ? '' :
786
+ ' -- an artifact from an older stasis may record a placeholder version for a workspace ' +
787
+ 'package without one; regenerate it (lock=replace / bundle=replace)'
788
+ assert.fail(`module identity mismatch for '${dir}': artifact records ` +
789
+ `'${module.name}@${module.version ?? '(none)'}', package.json has '${name}@${version ?? '(none)'}'${hint}`)
790
+ }
791
+ // A dependency's repo is its package.json's, held to the artifact's record as its identity is; an
792
+ // artifact from an older stasis records none, and gets it.
793
+ if (module.repo === undefined) {
794
+ if (repo !== undefined) this.modules.set(dir, moduleInfo({ ...module, repo }))
795
+ } else if (repo === undefined || !sameRepo(module.repo, repo)) {
796
+ assert.fail(`module repo mismatch for '${dir}': artifact records ${JSON.stringify(module.repo)}, ` +
797
+ `package.json names ${repo === undefined ? 'no GitHub repository' : JSON.stringify(repo)}`)
798
+ }
772
799
 
773
800
  return { absolute, file, dir, module, closestType }
774
801
  }
@@ -792,38 +819,33 @@ export class State {
792
819
  // actual format instead of conflicting with 'stat:*'.
793
820
  if (isStatFormat(this.formats.get(file))) this.formats.delete(file)
794
821
 
795
- if (asResource && CODE_EXTENSIONS.has(extname(file).slice(1).toLowerCase())) {
822
+ const ext = extname(file)
823
+ if (asResource && CODE_EXTENSIONS.has(ext.slice(1).toLowerCase())) {
796
824
  throw new Error(`addFile: a code file can't be recorded as a resource: ${file}`)
797
825
  }
798
826
 
799
827
  if (!asResource && inferFormat) {
800
- const extToFormat = {
801
- __proto__: null,
802
- '.json': 'json',
803
- '.mjs': 'module',
804
- '.cjs': 'commonjs',
805
- '.mts': 'module-typescript',
806
- '.cts': 'commonjs-typescript',
807
- }
808
- if (closestType !== undefined) {
809
- extToFormat['.js'] = closestType
810
- extToFormat['.ts'] = `${closestType}-typescript`
811
- }
812
- const inferredFormat = extToFormat[extname(file)]
828
+ const inferredFormat = EXT_FORMATS[ext] ??
829
+ (closestType === undefined ? undefined : ext === '.js' ? closestType : ext === '.ts' ? `${closestType}-typescript` : undefined)
813
830
  if (inferredFormat !== undefined) {
831
+ // A transforming preload (`stasis run --import tsx`) loads a TypeScript file as its
832
+ // post-erasure family ('module-typescript' arrives as 'module'): attest the on-disk
833
+ // format, not the transformer's runtime view. Anything else must still match exactly.
834
+ if (format != null && format === erasedTypeScriptFormat(inferredFormat)) format = inferredFormat
814
835
  if (format != null) assert.equal(format, inferredFormat)
815
836
  else format = inferredFormat
816
837
  } else if (format == null) {
817
- // No `type`: Node decides .js/.ts by syntax detection, so reuse an extension-appropriate
818
- // format already recorded this session (the loader's call, or the parent's for a sidecar)
819
- // rather than re-defaulting to commonjs and mis-attesting.
820
- const variants = {
821
- __proto__: null,
822
- '.js': ['commonjs', 'module'],
823
- '.ts': ['commonjs-typescript', 'module-typescript'],
824
- }[extname(file)]
838
+ // No `type`: reuse an extension-appropriate format already recorded this session (the
839
+ // loader's call, or the parent's for a sidecar) rather than re-defaulting to commonjs and mis-attesting.
840
+ const variants = UNTYPED_VARIANTS[ext]
825
841
  const known = this.formats.get(file) ?? this.#parent?.formats.get(file)
826
842
  format = variants?.includes(known) ? known : variants?.[0]
843
+ } else if (ext === '.ts' && (format === 'commonjs' || format === 'module')) {
844
+ // No `type`, but a transforming preload reported this .ts as its post-erasure family:
845
+ // attest the on-disk '-typescript' variant, keeping same-stack replays self-consistent.
846
+ // Stacks can still honestly disagree about a no-`type` .ts (tsx defaults to commonjs,
847
+ // Node syntax-detects) -- that rightly surfaces as a format flip, not silently here.
848
+ format = `${format}-typescript`
827
849
  }
828
850
  }
829
851
 
@@ -831,14 +853,17 @@ export class State {
831
853
  if (typeof source === 'string') {
832
854
  assert.ok(source.isWellFormed())
833
855
  } else {
834
- if (source === undefined || source === null) { source = readFileSync(absolute); sourceFromDisk = true }
856
+ if (source == null) {
857
+ source = this.#host.readFile(absolute)
858
+ sourceFromDisk = true
859
+ }
835
860
  assert.ok(Buffer.isBuffer(source))
836
861
  if (!asResource) assert.ok(isUtf8(source), `File is not UTF-8: ${file}`)
837
862
  }
838
863
 
839
864
  const buf = typeof source === 'string' ? Buffer.from(source) : source
840
865
  // Verify a CALLER-PROVIDED source against disk; tautological when we read it ourselves.
841
- if (!sourceFromDisk) assert.deepStrictEqual(readFileSync(absolute), buf)
866
+ if (!sourceFromDisk) assert.deepStrictEqual(this.#host.readFile(absolute), buf)
842
867
 
843
868
  if (asResource) {
844
869
  const derived = isUtf8(buf) ? 'resource' : 'resource:base64'
@@ -849,9 +874,11 @@ export class State {
849
874
  if (isEntry) this.entries.add(file)
850
875
  const integrity = sha512integrity(source)
851
876
  noupsert(this.hashes, file, integrity)
877
+ this.#filesCapturedThisRun.add(file)
852
878
  if (this.config.childProcess) this.#observed.add(file) // only a child's shardSnapshot reads it; skip when the channel is off
879
+ // Provenance for the bundle's `reason` field (null = the caller attributes it, see includePackageJson).
853
880
  if (this.config.bundle && reason !== null) {
854
- this.#recordReason(reason, file) // provenance for the bundle's `reason` field (null = caller derives attribution itself, see includePackageJson)
881
+ this.#recordReason(reason, file)
855
882
  // Track HOW 'run' saw this file so #bundleReason can drop files run merely fs-READ post-plugin.
856
883
  if (reason === 'run') {
857
884
  if (!fsRead) this.#runImported.add(file)
@@ -859,7 +886,7 @@ export class State {
859
886
  }
860
887
  }
861
888
  const rel = relative(dir, file)
862
- assert.ok(!rel.startsWith('..'))
889
+ assert.ok(!relativeEscapes(rel))
863
890
 
864
891
  const inAttestedZone = hasNodeModulesSegment(dir) || this.config.full
865
892
  if (this.config.frozen && inAttestedZone) {
@@ -895,12 +922,8 @@ export class State {
895
922
  assert.equal(module.files[rel], integrity)
896
923
 
897
924
  if (this.config.bundle) {
898
- if (asResource) {
899
- const content = format === 'resource:base64' ? buf.toString('base64') : buf.toString('utf8')
900
- noupsert(this.resources, file, content)
901
- } else {
902
- noupsert(this.sources, file, typeof source === 'string' ? source : source.toString())
903
- }
925
+ if (asResource) noupsert(this.resources, file, buf.toString(format === 'resource:base64' ? 'base64' : 'utf8'))
926
+ else noupsert(this.sources, file, typeof source === 'string' ? source : source.toString())
904
927
  }
905
928
 
906
929
  if (format) noupsert(this.formats, file, format)
@@ -913,18 +936,14 @@ export class State {
913
936
  // A record touches only this State; a REFUTATION must reach the whole family, else
914
937
  // #mergedExecutable's union resurrects the bit from a sibling's seeded entry.
915
938
  #recordExecutable(file, absolute) {
916
- const executable = observeExecutable(absolute)
939
+ const executable = observeExecutable(absolute, this.#host)
917
940
  if (executable === true) {
918
941
  this.executable.add(file)
919
942
  return
920
943
  }
921
944
  if (executable !== false || !CAN_OBSERVE_EXECUTE_BITS) return
922
- const root = this.#parent ?? this
923
- if (root.executable.size === 0 && root.sidecars().size === 0) {
924
- this.executable.delete(file)
925
- return
926
- }
927
945
  this.executable.delete(file)
946
+ const root = this.#parent ?? this
928
947
  root.executable.delete(file)
929
948
  for (const sidecar of root.sidecars()) sidecar.executable.delete(file)
930
949
  }
@@ -942,17 +961,13 @@ export class State {
942
961
  assert.ok(Buffer.isBuffer(source), 'addFsFile requires a Buffer source')
943
962
  const path = fileURLToPath(url)
944
963
  const format = classifyFormat(path, { content: source })
945
- if (format === undefined || isBinaryPlist(path, source)) {
946
- if (this.config.resources.has(pathExt(path) || basename(path).toLowerCase())) {
947
- this.addFile(url, { source, resource: true, fsRead: true })
948
- return
949
- }
950
- throw new Error(
951
- `addFsFile: ${path} is neither code nor a declared resource; ` +
952
- `add its extension or filename to the resources allowlist or stop reading it`
953
- )
964
+ if (format !== undefined && !isBinaryPlist(path, source)) {
965
+ this.addFile(url, { source, format: format ?? undefined, inferFormat: false, fsRead: true })
966
+ } else if (this.config.resources.has(pathExt(path) || basename(path).toLowerCase())) {
967
+ this.addFile(url, { source, resource: true, fsRead: true })
968
+ } else {
969
+ throw new Error(`addFsFile: ${path} is neither code nor a declared resource; add its extension or filename to the resources allowlist or stop reading it`)
954
970
  }
955
- this.addFile(url, { source, format: format ?? undefined, inferFormat: false, fsRead: true })
956
971
  }
957
972
 
958
973
  // Record an `fs.readdirSync` capture: the listing is SORTED for reproducibility and stored as a
@@ -970,7 +985,7 @@ export class State {
970
985
  if (this.config.childProcess) this.#observed.add(file) // only a child's shardSnapshot reads it; skip when the channel is off
971
986
  if (this.config.bundle) this.#recordReason('run', file)
972
987
  const rel = relative(dir, file)
973
- assert.ok(!rel.startsWith('..'))
988
+ assert.ok(!relativeEscapes(rel))
974
989
 
975
990
  const inAttestedZone = hasNodeModulesSegment(dir) || this.config.full
976
991
  if (this.config.frozen && inAttestedZone) {
@@ -1011,20 +1026,15 @@ export class State {
1011
1026
  // Serve an `fs.readFileSync` from the bundle: raw bytes, or undefined when uncaptured (the hook
1012
1027
  // falls back to disk) or a captured directory. Served by presence, not format.
1013
1028
  getFsFile(url) {
1014
- let file
1015
- try { file = this.#canonicalFile(url) } catch { return undefined }
1016
- if (this.formats.get(file) === 'directory') return undefined
1017
- if (!this.sources.has(file) && !this.resources.has(file)) return undefined
1029
+ if (!this.hasFsFileContent(url)) return undefined
1018
1030
  const { source } = this.getFile(url)
1019
1031
  return Buffer.isBuffer(source) ? source : Buffer.from(source, 'utf8')
1020
1032
  }
1021
1033
 
1022
1034
  getFsDir(url) {
1023
- let file
1024
- try { file = this.#canonicalFile(url) } catch { return undefined }
1025
- if (this.formats.get(file) !== 'directory') return undefined
1026
- const { source } = this.getFile(url)
1027
- const names = JSON.parse(source)
1035
+ const file = this.#canonicalFileMaybe(url)
1036
+ if (file === undefined || this.formats.get(file) !== 'directory') return undefined
1037
+ const names = JSON.parse(this.getFile(url).source)
1028
1038
  assert.ok(Array.isArray(names), `corrupt directory listing for ${file}`)
1029
1039
  return names
1030
1040
  }
@@ -1034,12 +1044,8 @@ export class State {
1034
1044
  if (this.#impliedDirIndex) return this.#impliedDirIndex
1035
1045
  const dirs = new Set(['.'])
1036
1046
  const add = (key) => {
1037
- let prefix = ''
1038
1047
  const parts = key.split('/')
1039
- for (let i = 0; i < parts.length - 1; i++) {
1040
- prefix = prefix === '' ? parts[i] : `${prefix}/${parts[i]}`
1041
- dirs.add(prefix)
1042
- }
1048
+ for (let i = 1; i < parts.length; i++) dirs.add(parts.slice(0, i).join('/'))
1043
1049
  }
1044
1050
  for (const key of this.sources.keys()) add(key)
1045
1051
  for (const key of this.resources.keys()) add(key)
@@ -1053,23 +1059,19 @@ export class State {
1053
1059
  // shim falls back to disk). Order matters: 'directory' first, content before stat records, implied
1054
1060
  // dirs last. NB: 'file' means "recorded", NOT "bytes serveable" (use hasFsFileContent).
1055
1061
  getFsStat(url) {
1056
- let file
1057
- try { file = this.#canonicalFile(url) } catch { return undefined }
1062
+ const file = this.#canonicalFileMaybe(url)
1063
+ if (file === undefined) return undefined
1058
1064
  const format = this.formats.get(file)
1059
1065
  if (format === 'directory') return 'directory'
1060
- if (this.sources.has(file) || this.resources.has(file)) return 'file'
1061
- if (format === 'stat:file') return 'file'
1062
- if (format === 'stat:directory') return 'directory'
1063
- if (this.#impliedDirs().has(file)) return 'directory'
1066
+ if (this.sources.has(file) || this.resources.has(file) || format === 'stat:file') return 'file'
1067
+ if (format === 'stat:directory' || this.#impliedDirs().has(file)) return 'directory'
1064
1068
  return undefined
1065
1069
  }
1066
1070
 
1067
1071
  // True when the bundle carries actual BYTE content for `url` (not a directory/stat-only record).
1068
1072
  hasFsFileContent(url) {
1069
- let file
1070
- try { file = this.#canonicalFile(url) } catch { return false }
1071
- if (this.formats.get(file) === 'directory') return false
1072
- return this.sources.has(file) || this.resources.has(file)
1073
+ const file = this.#canonicalFileMaybe(url)
1074
+ return file !== undefined && this.formats.get(file) !== 'directory' && (this.sources.has(file) || this.resources.has(file))
1073
1075
  }
1074
1076
 
1075
1077
  // --fs <-> bundler-plugin coordination: CAPTURE skips a read a write-mode sidecar already attests,
@@ -1081,27 +1083,28 @@ export class State {
1081
1083
  return false
1082
1084
  }
1083
1085
 
1084
- // getFs* variants that also consult load-mode sidecars (this State first). Only #readSidecars --
1085
- // write-mode sidecars only capture.
1086
- getFsFileFamily(url) {
1087
- const own = this.getFsFile(url)
1086
+ // getFs* over this State first, then its load-mode sidecars. Only #readSidecars -- write-mode
1087
+ // sidecars only capture.
1088
+ #fromFamily(method, url) {
1089
+ const own = this[method](url)
1088
1090
  if (own !== undefined) return own
1089
- for (const s of this.#readSidecars) { const v = s.getFsFile(url); if (v !== undefined) return v }
1091
+ for (const s of this.#readSidecars) {
1092
+ const v = s[method](url)
1093
+ if (v !== undefined) return v
1094
+ }
1090
1095
  return undefined
1091
1096
  }
1092
1097
 
1098
+ getFsFileFamily(url) {
1099
+ return this.#fromFamily('getFsFile', url)
1100
+ }
1101
+
1093
1102
  getFsStatFamily(url) {
1094
- const own = this.getFsStat(url)
1095
- if (own !== undefined) return own
1096
- for (const s of this.#readSidecars) { const v = s.getFsStat(url); if (v !== undefined) return v }
1097
- return undefined
1103
+ return this.#fromFamily('getFsStat', url)
1098
1104
  }
1099
1105
 
1100
1106
  getFsDirFamily(url) {
1101
- const own = this.getFsDir(url)
1102
- if (own !== undefined) return own
1103
- for (const s of this.#readSidecars) { const v = s.getFsDir(url); if (v !== undefined) return v }
1104
- return undefined
1107
+ return this.#fromFamily('getFsDir', url)
1105
1108
  }
1106
1109
 
1107
1110
  getFile(url) {
@@ -1163,7 +1166,7 @@ export class State {
1163
1166
  const path = specifier.startsWith('file:') ? fileURLToPath(specifier) : specifier
1164
1167
  if (!isAbsolute(path)) return specifier
1165
1168
  const fromRoot = relative(this.root, path)
1166
- if (fromRoot === '' || fromRoot.startsWith('..')) return specifier // outside the project root
1169
+ if (fromRoot === '' || relativeEscapes(fromRoot)) return specifier // outside the project root
1167
1170
  const rel = relative(dirname(fileURLToPath(parentURL)), path)
1168
1171
  return rel.startsWith('.') ? rel : `./${rel}`
1169
1172
  }
@@ -1191,11 +1194,7 @@ export class State {
1191
1194
  this.#assertAttestedResolution(this.#bundleImports, key, parent, specifier, file, { what: 'observed', source: 'frozen bundle', tolerateUnknown })
1192
1195
  }
1193
1196
 
1194
- if (!this.imports.has(key)) this.imports.set(key, new Map())
1195
- const imports = this.imports.get(key)
1196
- if (!imports.has(parent)) imports.set(parent, new Map())
1197
- const specifiers = imports.get(parent)
1198
- noupsert(specifiers, specifier, file)
1197
+ noupsert(nestedMap(nestedMap(this.imports, key), parent), specifier, file)
1199
1198
  // upsertFormat, not noupsert: a real format must replace a weak 'stat:*' record from an --fs stat.
1200
1199
  if (format) upsertFormat(this.formats, file, format)
1201
1200
  }
@@ -1209,42 +1208,33 @@ export class State {
1209
1208
  // Static bundles store edges under '*' (Node's condition set is unpredictable); the runtime
1210
1209
  // loader records precise conditions, so the specific lookup wins.
1211
1210
  let file = this.imports.get(key)?.get(parent)?.get(specifier)
1212
- if (file === undefined && key !== '*') {
1213
- file = this.imports.get('*')?.get(parent)?.get(specifier)
1214
- }
1211
+ if (file === undefined && key !== '*') file = this.imports.get('*')?.get(parent)?.get(specifier)
1215
1212
  if (file === undefined) {
1216
1213
  // The edge may be recorded under a DIFFERENT conditions bucket -- resolveBundled scans every bucket.
1217
1214
  if (this.config.loadBundle) {
1218
1215
  const abs = this.resolveBundled(parentURL, specifier)
1219
- if (abs !== undefined) {
1220
- const f = relative(this.root, abs)
1221
- return { url: pathToFileURL(abs).toString(), format: this.#loaderFormat(f) }
1222
- }
1216
+ if (abs !== undefined) return { url: pathToFileURL(abs).toString(), format: this.#loaderFormat(relative(this.root, abs)) }
1223
1217
  }
1224
1218
  // Node's ERR_MODULE_NOT_FOUND shape, not a bare assert: dynamic-import callers guard on that
1225
1219
  // code, which ERR_ASSERTION escapes.
1226
- const err = new Error(`Cannot find module '${specifier}' imported from ${parent}`)
1227
- err.code = 'ERR_MODULE_NOT_FOUND'
1228
- throw err
1220
+ throw Object.assign(new Error(`Cannot find module '${specifier}' imported from ${parent}`), { code: 'ERR_MODULE_NOT_FOUND' })
1229
1221
  }
1230
1222
  // A --metro per-platform edge is a { platform: file } Map; plain bundle=load has no platform
1231
1223
  // context to pick one, so fail closed rather than feed a Map where a path is expected.
1232
1224
  if (typeof file !== 'string') {
1233
- const err = new Error(`Resolution of '${specifier}' from ${parent} is platform-specific (a --metro multi-platform bundle); it can't be loaded by plain node, build a single-platform bundle to load`)
1234
- err.code = 'ERR_STASIS_PLATFORM_SPECIFIC'
1235
- throw err
1225
+ throw Object.assign(
1226
+ new Error(`Resolution of '${specifier}' from ${parent} is platform-specific (a --metro multi-platform bundle); it can't be loaded by plain node, build a single-platform bundle to load`),
1227
+ { code: 'ERR_STASIS_PLATFORM_SPECIFIC' })
1236
1228
  }
1237
- const url = pathToFileURL(resolve(this.root, file)).toString()
1238
- const format = this.#loaderFormat(file)
1239
- return { url, format }
1229
+ return { url: pathToFileURL(resolve(this.root, file)).toString(), format: this.#loaderFormat(file) }
1240
1230
  }
1241
1231
 
1242
1232
  // Resolve a CJS require() target to a bundled absolute path, or undefined to defer to Node (the
1243
1233
  // hooks.js CJS shim needs this: registerHooks can't intercept Module._resolveFilename). Matches
1244
1234
  // under ANY conditions bucket, since native require gives none; divergent buckets -> defer.
1245
1235
  resolveBundled(parentURL, specifier) {
1246
- let parent
1247
- try { parent = this.#canonicalFile(parentURL) } catch { return undefined }
1236
+ const parent = this.#canonicalFileMaybe(parentURL)
1237
+ if (parent === undefined) return undefined
1248
1238
  const spec = this.#canonicalSpecifier(parentURL, specifier)
1249
1239
  const matches = new Set()
1250
1240
  for (const [, byParent] of this.imports) {
@@ -1254,8 +1244,7 @@ export class State {
1254
1244
  if (matches.size !== 1) return undefined
1255
1245
  const [only] = matches
1256
1246
  // Per-platform { platform: file } Map (--metro) has no single path: defer to native, not resolve()'s TypeError.
1257
- if (typeof only !== 'string') return undefined
1258
- return resolve(this.root, only)
1247
+ return typeof only === 'string' ? resolve(this.root, only) : undefined
1259
1248
  }
1260
1249
 
1261
1250
  // Union of lockfile-attested and live resolutions, so a partial lock=add run extends without
@@ -1264,14 +1253,10 @@ export class State {
1264
1253
  const merged = new Map()
1265
1254
  const mergeIn = (imports) => {
1266
1255
  for (const [conditions, byParent] of imports) {
1267
- if (!merged.has(conditions)) merged.set(conditions, new Map())
1268
- const mergedParents = merged.get(conditions)
1256
+ const mergedParents = nestedMap(merged, conditions)
1269
1257
  for (const [parent, specifiers] of byParent) {
1270
- if (!mergedParents.has(parent)) mergedParents.set(parent, new Map())
1271
- const mergedSpecifiers = mergedParents.get(parent)
1272
- for (const [specifier, file] of specifiers) {
1273
- noupsert(mergedSpecifiers, specifier, file)
1274
- }
1258
+ const mergedSpecifiers = nestedMap(mergedParents, parent)
1259
+ for (const [specifier, file] of specifiers) noupsert(mergedSpecifiers, specifier, file)
1275
1260
  }
1276
1261
  }
1277
1262
  }
@@ -1285,8 +1270,7 @@ export class State {
1285
1270
  // Union of lockfile-attested and observed formats (+ sidecars'), append-only like #mergedImports,
1286
1271
  // except that a weak 'stat:*' is UPGRADED by real content; two real formats stay fatal.
1287
1272
  #mergedFormats() {
1288
- const merged = new Map()
1289
- if (this.#lockFormats) for (const [file, format] of this.#lockFormats) merged.set(file, format)
1273
+ const merged = new Map(this.#lockFormats ?? [])
1290
1274
  for (const [file, format] of this.formats) upsertFormat(merged, file, format)
1291
1275
  for (const sidecar of this.#sidecars) {
1292
1276
  for (const [file, format] of sidecar.formats) upsertFormat(merged, file, format)
@@ -1314,7 +1298,7 @@ export class State {
1314
1298
  return narrowExecutable(this.executable, { modules, formats, scope: this.config.scope })
1315
1299
  }
1316
1300
 
1317
- get lockData() {
1301
+ get lockfile() {
1318
1302
  const formats = this.#mergedFormats()
1319
1303
  return new Lockfile({
1320
1304
  config: this.config.values,
@@ -1323,7 +1307,11 @@ export class State {
1323
1307
  imports: this.#mergedImports(),
1324
1308
  formats,
1325
1309
  executable: this.#mergedExecutable(formats),
1326
- }).serialize()
1310
+ })
1311
+ }
1312
+
1313
+ get lockData() {
1314
+ return this.lockfile.serialize()
1327
1315
  }
1328
1316
 
1329
1317
  // Pair each module's recorded file list with content from perFile, dropping modules with none.
@@ -1332,15 +1320,10 @@ export class State {
1332
1320
  for (const [dir, info] of this.modules) {
1333
1321
  const files = {}
1334
1322
  for (const rel of Object.keys(info.files)) {
1335
- const file = moduleFileKey(dir, rel)
1336
- const content = perFile.get(file)
1323
+ const content = perFile.get(moduleFileKey(dir, rel))
1337
1324
  if (content !== undefined) files[rel] = content
1338
1325
  }
1339
- if (Object.keys(files).length > 0) {
1340
- modules.set(dir, info.ecosystem === undefined
1341
- ? { name: info.name, version: info.version, files }
1342
- : { name: info.name, version: info.version, ecosystem: info.ecosystem, files })
1343
- }
1326
+ if (Object.keys(files).length > 0) modules.set(dir, moduleInfo({ ...info, files }))
1344
1327
  }
1345
1328
  return modules
1346
1329
  }
@@ -1358,7 +1341,7 @@ export class State {
1358
1341
  }
1359
1342
 
1360
1343
  // Seed `reason` from an absorbed on-disk bundle so a bundle=add re-run preserves other consumers'
1361
- // attribution. Called from every absorb site, including the sidecar's inlined one.
1344
+ // attribution. Called from every absorb site, including the sidecar's.
1362
1345
  #seedReasonFromBundle(bundle) {
1363
1346
  if (!this.config.writeBundle || bundle.reason === undefined) return
1364
1347
  for (const [consumer, files] of Object.entries(bundle.reason)) {
@@ -1373,8 +1356,7 @@ export class State {
1373
1356
  // A file run merely fs-READ post-plugin that a plugin also bundles is the plugin's, not run's.
1374
1357
  const pluginFiles = new Set()
1375
1358
  for (const [who, recorded] of this.#reasonFiles) {
1376
- if (who === 'run') continue
1377
- for (const file of recorded) pluginFiles.add(file)
1359
+ if (who !== 'run') for (const file of recorded) pluginFiles.add(file)
1378
1360
  }
1379
1361
  const runOverclaims = (file) =>
1380
1362
  this.#fsReadPostPlugin.has(file) && !this.#runImported.has(file) && pluginFiles.has(file)
@@ -1384,13 +1366,11 @@ export class State {
1384
1366
  // Sort keys and file lists: the JSON must be byte-reproducible regardless of record order, else
1385
1367
  // #emitBundle's compare-and-skip sees spurious diffs.
1386
1368
  for (const who of [...this.#reasonFiles.keys()].toSorted()) {
1387
- const files = []
1388
- for (const file of this.#reasonFiles.get(who)) {
1389
- if (!inBundle.has(file)) continue
1390
- if (who === 'run' && runOverclaims(file)) continue
1391
- files.push(file)
1369
+ const files = [...this.#reasonFiles.get(who)].filter((file) => inBundle.has(file) && !(who === 'run' && runOverclaims(file)))
1370
+ if (files.length > 0) {
1371
+ reason[who] = files.toSorted(sortPaths)
1372
+ consumers += 1
1392
1373
  }
1393
- if (files.length > 0) { reason[who] = files.toSorted(sortPaths); consumers += 1 }
1394
1374
  }
1395
1375
  return consumers > 1 ? reason : undefined
1396
1376
  }
@@ -1403,104 +1383,126 @@ export class State {
1403
1383
  let out = null // copy-on-write: clone only when an entry must be dropped
1404
1384
  for (const [file, format] of this.formats) {
1405
1385
  if (isStatFormat(format) && merged.get(file) !== format) {
1406
- if (out === null) out = new Map(this.formats)
1386
+ out ??= new Map(this.formats)
1407
1387
  out.delete(file)
1408
1388
  }
1409
1389
  }
1410
1390
  return out ?? this.formats
1411
1391
  }
1412
1392
 
1413
- get sourceBundle() {
1414
- // One bundle holds code + resources, with `formats` tagging which; the key sets must be
1415
- // disjoint, asserted so an overlap fails locally rather than silently.
1416
- const contents = new Map(this.sources)
1417
- for (const [file, content] of this.resources) {
1418
- assert.ok(!contents.has(file), `state invariant: file ${file} in both sources and resources`)
1419
- contents.set(file, content)
1420
- }
1393
+ #absorbRepo(half, bundle) {
1394
+ this.#absorbedRepos.set(half, this.#absorbedRepos.has(half) ? mergeRepo(this.#absorbedRepos.get(half), bundle.repo) : bundle.repo)
1395
+ }
1396
+
1397
+ get #detectedRepo() {
1398
+ return (this.#detectedRepoCache ??= { value: detectRepo(this.root, this.#host) }).value
1399
+ }
1400
+
1401
+ // `repo` to write for a half: detected, merged with that half's absorbed one when adding to it.
1402
+ #repoFor(half) {
1403
+ if (!this.#absorbedRepos.has(half)) return this.#detectedRepo
1404
+ const absorbed = this.#absorbedRepos.get(half)
1405
+ return absorbed && mergeRepo(absorbed, this.#detectedRepo)
1406
+ }
1407
+
1408
+ // One bundle artifact over `contents` (file -> stored content) with the `formats` it declares;
1409
+ // the code side carries entries/imports, the resources half none.
1410
+ #bundle(half, contents, formats, { entries = this.entries, imports = this.imports } = {}) {
1421
1411
  const modules = this.#bundleModules(contents)
1422
- const formats = this.#formatsForBundle()
1423
1412
  return new Bundle({
1424
1413
  config: this.config.values,
1425
- entries: this.entries,
1414
+ entries,
1426
1415
  modules,
1427
1416
  formats,
1428
- imports: this.imports,
1417
+ imports,
1429
1418
  executable: this.#bundleExecutable(modules, formats),
1430
1419
  reason: this.#bundleReason(contents.keys()),
1420
+ repo: this.#repoFor(half),
1431
1421
  })
1432
1422
  }
1433
1423
 
1424
+ get sourceBundle() {
1425
+ // One bundle holds code + resources, with `formats` tagging which; the key sets must be
1426
+ // disjoint, asserted so an overlap fails locally rather than silently.
1427
+ const contents = new Map(this.sources)
1428
+ for (const [file, content] of this.resources) {
1429
+ assert.ok(!contents.has(file), `state invariant: file ${file} in both sources and resources`)
1430
+ contents.set(file, content)
1431
+ }
1432
+ return this.#bundle('code', contents, this.#formatsForBundle())
1433
+ }
1434
+
1434
1435
  get sourceData() {
1435
1436
  return this.sourceBundle.serialize()
1436
1437
  }
1437
1438
 
1438
1439
  // Split-bundle counterparts to sourceBundle/sourceData: the code half owns entries/imports + code
1439
- // formats, the resources half owns resource formats + bytes. Both declare per-dir module identity
1440
- // so each file verifies alone.
1440
+ // formats (stat records too: they aren't resource formats, so the resources half's shape check
1441
+ // would reject them), the resources half owns resource formats + bytes. Both declare per-dir
1442
+ // module identity so each file verifies alone.
1441
1443
  get codeBundle() {
1442
- // Stat records ride the code half -- they aren't resource formats, so the resources half's shape
1443
- // check would reject them.
1444
- const codeFormats = new Map()
1445
- for (const [file, format] of this.#formatsForBundle()) {
1446
- if (!Bundle.isResourceFormat(format)) codeFormats.set(file, format)
1447
- }
1448
- const modules = this.#bundleModules(this.sources)
1449
- return new Bundle({
1450
- config: this.config.values,
1451
- entries: this.entries,
1452
- modules,
1453
- formats: codeFormats,
1454
- imports: this.imports,
1455
- executable: this.#bundleExecutable(modules, codeFormats),
1456
- reason: this.#bundleReason(this.sources.keys()),
1457
- })
1444
+ const codeFormats = new Map([...this.#formatsForBundle()].filter(([, format]) => !Bundle.isResourceFormat(format)))
1445
+ return this.#bundle('code', this.sources, codeFormats)
1458
1446
  }
1459
1447
 
1460
1448
  get resourcesBundle() {
1461
- const resourceFormats = new Map()
1462
- for (const [file, format] of this.formats) {
1463
- if (Bundle.isResourceFormat(format)) resourceFormats.set(file, format)
1464
- }
1465
- const modules = this.#bundleModules(this.resources)
1466
- return new Bundle({
1467
- config: this.config.values,
1468
- // Resources bundle carries no entries/imports (Bundle.parse waives the entries requirement when no code).
1469
- entries: new Set(),
1470
- modules,
1471
- formats: resourceFormats,
1472
- imports: new Map(),
1473
- executable: this.#bundleExecutable(modules, resourceFormats),
1474
- reason: this.#bundleReason(this.resources.keys()),
1475
- })
1449
+ const resourceFormats = new Map([...this.formats].filter(([, format]) => Bundle.isResourceFormat(format)))
1450
+ // No entries/imports (Bundle.parse waives the entries requirement when no code).
1451
+ return this.#bundle('resources', this.resources, resourceFormats, { entries: new Set(), imports: new Map() })
1476
1452
  }
1477
1453
 
1478
1454
  // Record a native resolution verbatim (last-write-wins per parent+specifier);
1479
1455
  // #backfillObservedResolutions decides at write() which to add.
1480
1456
  observeResolution(parentURL, specifier, resolvedURL) {
1481
- let byParent = this.#observedResolutions.get(parentURL)
1482
- if (byParent === undefined) this.#observedResolutions.set(parentURL, (byParent = new Map()))
1483
- byParent.set(specifier, resolvedURL)
1457
+ nestedMap(this.#observedResolutions, parentURL).set(specifier, resolvedURL)
1458
+ }
1459
+
1460
+ // Record that a require() executed `url` (from the Module._load shim). Out-of-root targets are
1461
+ // skipped like #backfillObservedResolutions' -- the live hooks correctly ignore them too.
1462
+ observeExecution(url) {
1463
+ const file = this.#canonicalFileMaybe(url)
1464
+ if (file !== undefined) this.#executedFiles.add(file)
1465
+ }
1466
+
1467
+ // Whether the bundle carries source bytes for `url` (the hooks' bundle-bypass reconciliation).
1468
+ isBundledSource(url) {
1469
+ const file = this.#canonicalFileMaybe(url)
1470
+ return file !== undefined && this.sources.has(file)
1471
+ }
1472
+
1473
+ // Attest every executed-but-never-captured file from disk. A resolve-only edge stays byte-less
1474
+ // by design (see #backfillBeforeWrite), but an EXECUTED file the load hook never saw is a hole:
1475
+ // leaving it silent would ship an artifact that misses code the run provably evaluated, and a
1476
+ // frozen replay would never verify it. addFile re-checks bytes against the lockfile/bundle in
1477
+ // frozen modes, so tampering still fails the run -- at write time, but loudly.
1478
+ #backfillExecutedFiles() {
1479
+ for (const file of this.#executedFiles) {
1480
+ // "Captured this run", NOT this.hashes: a lockfile-seeded hash must still be VERIFIED
1481
+ // against disk here when the run executed the file without the load hook observing it.
1482
+ if (this.#filesCapturedThisRun.has(file)) continue
1483
+ // A require()d native addon never passes the load hook and is deliberately not captured
1484
+ // (non-deterministic across installs, like the rest of NATIVE_ARTIFACT_EXTS).
1485
+ if (isNativeArtifact(file)) continue
1486
+ const url = pathToFileURL(resolve(this.root, file)).toString()
1487
+ if (!this.config.full && !this.inNodeModules(url)) continue
1488
+ this.addFile(url, { reason: 'run' })
1489
+ }
1484
1490
  }
1485
1491
 
1486
1492
  // Backfill edges the live resolve hook never observed (require.resolve()/native CJS require()).
1487
1493
  // The resolution is attested but its bytes are NOT seeded -- that would widen trust to everything
1488
1494
  // that merely resolves. Skips out-of-scope targets and dedups across all condition buckets.
1489
1495
  #backfillObservedResolutions() {
1490
- if (this.#observedResolutions.size === 0) return
1491
1496
  for (const [parentURL, specs] of this.#observedResolutions) {
1492
- let parent
1493
- try { parent = this.#canonicalFile(parentURL) } catch { continue }
1497
+ const parent = this.#canonicalFileMaybe(parentURL)
1498
+ if (parent === undefined) continue
1494
1499
  for (const [specifier, resolvedURL] of specs) {
1495
- let file
1496
- try { file = this.#canonicalFile(resolvedURL) } catch { continue }
1500
+ const file = this.#canonicalFileMaybe(resolvedURL)
1501
+ if (file === undefined) continue
1497
1502
  const bundled = this.sources.has(file) || this.resources.has(file)
1498
1503
  if (!bundled && !this.config.full && !this.inNodeModules(resolvedURL)) continue
1499
1504
  const spec = this.#canonicalSpecifier(parentURL, specifier)
1500
- let recorded = false
1501
- for (const [, byParent] of this.imports) {
1502
- if (byParent.get(parent)?.get(spec) !== undefined) { recorded = true; break }
1503
- }
1505
+ const recorded = this.imports.values().some((byParent) => byParent.get(parent)?.get(spec) !== undefined)
1504
1506
  if (!recorded) this.addImport(parentURL, specifier, resolvedURL, { conditions: this.#requireConditions ?? '*' })
1505
1507
  }
1506
1508
  }
@@ -1512,12 +1514,12 @@ export class State {
1512
1514
  // reference across sidecars).
1513
1515
  includePackageJson() {
1514
1516
  // Gather first: addFile mutates this.modules, so don't addFile while iterating it.
1515
- const realRoot = realpathSync(this.root)
1517
+ const realRoot = this.#host.realpath(this.root)
1516
1518
  const toAdd = []
1517
1519
  for (const [dir, module] of this.modules) {
1518
1520
  const rel = moduleFileKey(dir, 'package.json')
1519
1521
  if (this.sources.has(rel) || this.resources.has(rel)) continue // already in this bundle
1520
- const buf = readModuleManifest({ baseDir: this.root, realBase: realRoot, rel })
1522
+ const buf = readModuleManifest({ baseDir: this.root, realBase: realRoot, rel, host: this.#host })
1521
1523
  if (!buf) continue
1522
1524
  // Only carry a manifest whose on-disk identity still matches the bundled bucket: under
1523
1525
  // bundle=add a dep may have drifted, and addFile -> #locateModule would crash on it.
@@ -1529,10 +1531,7 @@ export class State {
1529
1531
  // unattributed file can't be sorted by provenance downstream. Derived BEFORE the adds below,
1530
1532
  // so one fold's manifest can't count as another bucket's consumer evidence.
1531
1533
  const files = Object.keys(module.files)
1532
- const consumers = []
1533
- for (const [who, recorded] of this.#reasonFiles) {
1534
- if (files.some((f) => recorded.has(moduleFileKey(dir, f)))) consumers.push(who)
1535
- }
1534
+ const consumers = [...this.#reasonFiles].filter(([, recorded]) => files.some((f) => recorded.has(moduleFileKey(dir, f)))).map(([who]) => who)
1536
1535
  toAdd.push({ rel, buf, consumers })
1537
1536
  }
1538
1537
  for (const { rel, buf, consumers } of toAdd) {
@@ -1545,11 +1544,12 @@ export class State {
1545
1544
  // BEFORE the stasis-core BFS: a resolve-only edge to a stasis-core submodule is added only here,
1546
1545
  // and the BFS must see it to seed the file's bytes, else the bundle ships a dangling edge.
1547
1546
  this.#backfillObservedResolutions()
1547
+ this.#backfillExecutedFiles()
1548
1548
  this.#backfillBeforeWrite()
1549
1549
  // AFTER the backfills, so buckets they create are covered too.
1550
1550
  if (this.config.writeBundle && this.config.packageJSON) this.includePackageJson()
1551
- // Sidecars never write the lockfile (parent owns it); they only emit their bundle.
1552
1551
 
1552
+ // Sidecars never write the lockfile (parent owns it); they only emit their bundle.
1553
1553
  if (this.config.writeLockfile && !this.#parent) {
1554
1554
  const lockText = this.lockData
1555
1555
  if (lockText !== this.#lastLockData) {
@@ -1563,15 +1563,10 @@ export class State {
1563
1563
  const sourcesPath = this.config.bundleFile || join(this.root, FILE_CODE)
1564
1564
  if (this.config.resourcesBundleFile) {
1565
1565
  // hasContent gates each half so an empty one is dropped under bundle=replace.
1566
- this.#lastCodeBundle = this.#emitBundle(
1567
- sourcesPath, this.sources.size > 0, this.#lastCodeBundle, () => this.codeBundle.serialize())
1568
- this.#lastResourcesBundle = this.#emitBundle(
1569
- this.config.resourcesBundleFile, this.resources.size > 0, this.#lastResourcesBundle,
1570
- () => this.resourcesBundle.serialize())
1566
+ this.#lastCodeBundle = this.#emitBundle(sourcesPath, this.sources.size > 0, this.#lastCodeBundle, () => this.codeBundle.serialize())
1567
+ this.#lastResourcesBundle = this.#emitBundle(this.config.resourcesBundleFile, this.resources.size > 0, this.#lastResourcesBundle, () => this.resourcesBundle.serialize())
1571
1568
  } else {
1572
- this.#lastUnifiedBundle = this.#emitBundle(
1573
- sourcesPath, this.sources.size > 0 || this.resources.size > 0, this.#lastUnifiedBundle,
1574
- () => this.sourceData)
1569
+ this.#lastUnifiedBundle = this.#emitBundle(sourcesPath, this.sources.size > 0 || this.resources.size > 0, this.#lastUnifiedBundle, () => this.sourceData)
1575
1570
  }
1576
1571
  }
1577
1572
  }
@@ -1580,6 +1575,7 @@ export class State {
1580
1575
  // omitted -- the root re-reads bytes from disk.
1581
1576
  shardSnapshot() {
1582
1577
  this.#backfillObservedResolutions()
1578
+ this.#backfillExecutedFiles()
1583
1579
  this.#backfillBeforeWrite()
1584
1580
  // Only what THIS process observed, never the seeded baseline (shard-size bloat). Entries are
1585
1581
  // dropped: a child's "entry" is its fork target, not a root's.
@@ -1593,12 +1589,9 @@ export class State {
1593
1589
  // Only edges whose PARENT was observed, dropping the bundle-seeded ones the root already attests.
1594
1590
  const imports = new Map()
1595
1591
  for (const [conditions, byParent] of this.imports) {
1596
- let kept
1597
1592
  for (const parent of this.#observed) {
1598
1593
  const specs = byParent.get(parent)
1599
- if (specs === undefined) continue
1600
- if (kept === undefined) imports.set(conditions, (kept = new Map()))
1601
- kept.set(parent, specs)
1594
+ if (specs !== undefined) nestedMap(imports, conditions).set(parent, specs)
1602
1595
  }
1603
1596
  }
1604
1597
  return serializeShard({ scope: this.config.scope, files, formats, imports })
@@ -1621,8 +1614,7 @@ export class State {
1621
1614
  }
1622
1615
  let real
1623
1616
  try { real = realpathSync(absolute) } catch { return false }
1624
- const rel = relative(realRoot, real)
1625
- return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))
1617
+ return isPathWithin(realRoot, real)
1626
1618
  }
1627
1619
  // Files first, then edges. Merged files are NEVER marked entries -- a child's "entry" is its
1628
1620
  // fork-target main, not a root entry.
@@ -1636,17 +1628,13 @@ export class State {
1636
1628
  this.#recordExecutable(file, absolute)
1637
1629
  // Skip a file the root already attests (the byte re-read dominates merge cost), EXCEPT to
1638
1630
  // carry a concrete format the root LACKS, else a later frozen run rejects the unattested format.
1639
- if (this.hashes.has(file)) {
1640
- const shardFormat = shard.formats.get(file)
1641
- if (shardFormat === undefined || (this.formats.get(file) ?? this.#lockFormats?.get(file)) !== undefined) continue
1642
- }
1643
- const url = pathToFileURL(absolute).toString()
1644
1631
  const format = shard.formats.get(file)
1632
+ if (this.hashes.has(file) && (format === undefined || (this.formats.get(file) ?? this.#lockFormats?.get(file)) !== undefined)) continue
1633
+ const url = pathToFileURL(absolute).toString()
1645
1634
  try {
1646
1635
  if (format === 'directory') {
1647
1636
  // Range-check FIRST so a child-forged `..` key can't make us list it.
1648
- const relFromRoot = relative(this.root, absolute)
1649
- if (relFromRoot.startsWith('..') || isAbsolute(relFromRoot)) continue
1637
+ if (!isPathWithin(this.root, absolute)) continue
1650
1638
  this.addFsDir(url, readdirSync(absolute))
1651
1639
  } else if (format === 'resource' || format === 'resource:base64') {
1652
1640
  // Let addFile re-derive the exact resource tag from the re-read bytes rather than trusting
@@ -1670,17 +1658,15 @@ export class State {
1670
1658
  for (const [file, format] of shard.formats) {
1671
1659
  if (!isStatFormat(format)) continue
1672
1660
  const absolute = resolve(this.root, file)
1673
- const relFromRoot = relative(this.root, absolute)
1674
- if (relFromRoot.startsWith('..') || isAbsolute(relFromRoot)) continue
1661
+ if (!isPathWithin(this.root, absolute)) continue
1675
1662
  try {
1676
1663
  // statSync, NOT lstatSync: the child's capture followed symlinks, so this reproduces the kind
1677
1664
  // a legitimate shard carries where lstatSync would report the link and drop it.
1678
1665
  const stats = statSync(absolute)
1679
1666
  const kind = stats.isDirectory() ? 'directory' : stats.isFile() ? 'file' : null
1680
- if (kind === null) continue
1681
1667
  // statSync follows links: a symlink pointing OUT must not attest an external kind under an
1682
1668
  // in-root key.
1683
- if (!realContained(absolute)) continue
1669
+ if (kind === null || !realContained(absolute)) continue
1684
1670
  this.addFsStat(pathToFileURL(absolute).toString(), kind)
1685
1671
  } catch {
1686
1672
  // Gone/dangling, or a kind conflict with the root's capture: skip.
@@ -1697,15 +1683,12 @@ export class State {
1697
1683
  try { importAttributes = JSON.parse(conditions.slice(withAt + ' (with: '.length, -1)) } catch { /* leave undefined */ }
1698
1684
  }
1699
1685
  const cond = condStr === '*' ? '*' : condStr.split(', ')
1700
- for (const [parent, specs] of byParent) {
1701
- const parentURL = pathToFileURL(resolve(this.root, parent)).toString()
1702
- for (const [specifier, file] of specs) {
1686
+ for (const [parent, specs] of byParent) {
1687
+ const parentURL = pathToFileURL(resolve(this.root, parent)).toString()
1688
+ for (const [specifier, file] of specs) {
1703
1689
  const url = pathToFileURL(resolve(this.root, file)).toString()
1704
- try {
1705
- this.addImport(parentURL, specifier, url, { conditions: cond, importAttributes })
1706
- } catch {
1707
- // Same best-effort stance as addFile above.
1708
- }
1690
+ // Same best-effort stance as addFile above.
1691
+ try { this.addImport(parentURL, specifier, url, { conditions: cond, importAttributes }) } catch { /* skipped */ }
1709
1692
  }
1710
1693
  }
1711
1694
  }
@@ -1722,9 +1705,8 @@ export class State {
1722
1705
  if (text !== lastText) {
1723
1706
  mkdirSync(dirname(path), { recursive: true })
1724
1707
  writeFileSync(path, brotliCompressSync(text, brotliOptions(this.config.brotliQuality)))
1725
- return text
1726
1708
  }
1727
- return lastText
1709
+ return text
1728
1710
  }
1729
1711
 
1730
1712
  get parent() {
@@ -1746,9 +1728,7 @@ export class State {
1746
1728
  if (stasisCoreMissing.length === 0) return
1747
1729
 
1748
1730
  const preloadRel = this.#preloadRoot ? relative(this.root, this.#preloadRoot) : null
1749
- const canBackfill = preloadRel !== null && !preloadRel.startsWith('..')
1750
-
1751
- assert.ok(canBackfill,
1731
+ assert.ok(preloadRel !== null && !relativeEscapes(preloadRel),
1752
1732
  `state.write() has imports referencing un-captured stasis-core files but no usable preloadRoot ` +
1753
1733
  `(preloadRoot=${this.#preloadRoot ?? 'unset'}). The live load hook missed an in-scope target -- ` +
1754
1734
  `investigate rather than silently patch: ${stasisCoreMissing.slice(0, 3).join(', ')}`)
@@ -1766,11 +1746,7 @@ export class State {
1766
1746
 
1767
1747
  // Seeded from the missing files + every stasis-core file already in sources, to walk their
1768
1748
  // transitive imports too.
1769
- const queue = [...stasisCoreMissing]
1770
- for (const file of this.sources.keys()) {
1771
- if (isStasisCoreFile(file)) queue.push(file)
1772
- }
1773
-
1749
+ const queue = [...stasisCoreMissing, ...[...this.sources.keys()].filter(isStasisCoreFile)]
1774
1750
  const processed = new Set()
1775
1751
  while (queue.length > 0) {
1776
1752
  const file = queue.shift()
@@ -1785,8 +1761,7 @@ export class State {
1785
1761
  const targetAbsolute = fileURLToPath(targetURL)
1786
1762
  let targetFile
1787
1763
  try { targetFile = this.relative(targetAbsolute) } catch { return }
1788
- if (!isStasisCoreFile(targetFile)) return
1789
- if (!existsSync(targetAbsolute)) return
1764
+ if (!isStasisCoreFile(targetFile) || !existsSync(targetAbsolute)) return
1790
1765
  queue.push(targetFile)
1791
1766
  this.addImport(baseURL, specifier, targetURL, { conditions: PRELOAD_CONDITIONS })
1792
1767
  }
@@ -1804,8 +1779,7 @@ export class State {
1804
1779
  for (const [, byParent] of this.imports) {
1805
1780
  for (const [, specifiers] of byParent) {
1806
1781
  for (const [, file] of specifiers) {
1807
- if (typeof file !== 'string') continue
1808
- if (missing.has(file)) continue
1782
+ if (typeof file !== 'string' || missing.has(file)) continue
1809
1783
  if (this.hashes.has(file) || this.sources.has(file) || this.resources.has(file)) continue
1810
1784
  const url = pathToFileURL(resolve(this.root, file)).toString()
1811
1785
  if (!this.config.full && !this.inNodeModules(url)) continue
@@ -1820,4 +1794,3 @@ export class State {
1820
1794
  // Backfillable stasis-core paths. Anchored against `/${file}` so a project-root file merely ending
1821
1795
  // in `@exodus/stasis-core/...` isn't matched.
1822
1796
  const STASIS_CORE_FILE_RE = /\/@exodus\/stasis-core\/(?:src\/[a-zA-Z-]+\.c?js|package\.json)$/
1823
-