@exodus/stasis-core 1.0.0-beta.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/state.js ADDED
@@ -0,0 +1,2375 @@
1
+ import assert from 'node:assert/strict'
2
+ import { isUtf8 } from 'node:buffer'
3
+ import * as fs from 'node:fs'
4
+ import { join, resolve, relative, basename, dirname, extname, isAbsolute } from 'node:path'
5
+ import { fileURLToPath, pathToFileURL } from 'node:url'
6
+ import { findPackageJSON } from 'node:module'
7
+ import { brotliCompressSync, brotliDecompressSync } from 'node:zlib'
8
+
9
+ import { Config } from './config.js'
10
+ import { Bundle } from './bundle.js'
11
+ import { Lockfile } from './lockfile.js'
12
+ import { canonicalizePath, sha512integrity, readFileSyncMaybe, noupsert } from './state-util.js'
13
+ import { brotliOptions } from './brotli.js'
14
+ import { CODE_EXTENSIONS, classifyExtension, fileMapToObject, moduleFileKey, objectToMaps, sortPaths, splitNodeModulesPath } from './util.js'
15
+ import corePackage from './package.cjs'
16
+
17
+ // Object-destructure off the namespace rather than `import { ... } from 'node:fs'`:
18
+ // the destructured `const` captures function values at this module's eval time, so
19
+ // stasis keeps writing through the real fs even after --mock (loaded after us) calls
20
+ // module.syncBuiltinESMExports() to refresh node:fs's ESM wrapper for user code.
21
+ // Direct ESM destructured imports are live bindings and would re-resolve to the
22
+ // mocked names when state.write() fires on beforeExit.
23
+ const { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } = fs
24
+
25
+ const FILE_CONFIG = 'stasis.config.json'
26
+ const FILE_LOCK = 'stasis.lock.json'
27
+ const FILE_CODE = 'stasis.code.br'
28
+
29
+ function readPackageJSON(pkgAbsolute) {
30
+ const buf = readFileSync(pkgAbsolute)
31
+ assert.ok(isUtf8(buf))
32
+ return JSON.parse(buf.toString())
33
+ }
34
+
35
+ // This stasis-core copy's own version, via src/package.cjs (a CommonJS re-export of
36
+ // package.json -- bundler-safe, unlike a runtime fs read or `import ... with`). A child
37
+ // (sidecar) State must EXACTLY match its parent's version (enforced in the constructor's
38
+ // parent branch): a sidecar shares the parent's maps by reference and reads its private
39
+ // fields, so a version skew between two @exodus/stasis-core copies in one process would
40
+ // be unsound.
41
+ const VERSION = corePackage.version
42
+
43
+ // TODO: stricter format validation
44
+
45
+ // Process-wide registry of every live State, kept on globalThis (not a module-local
46
+ // variable) so it is shared across DUPLICATE stasis-core copies in one process -- e.g. a
47
+ // stasis bundle that carries its own stasis-core alongside the outer loader's. A
48
+ // cross-realm `Symbol.for` key makes every state.js copy reach the same Set. Two roles:
49
+ // - the preload (top-level) State is the unique member flagged isPreload, found by
50
+ // State.preload; constructing a second preload (from ANY copy) is rejected, so the
51
+ // "one top-level state" invariant holds process-wide; and
52
+ // - write-target collision detection (#claimWritePath) scans every member's claimed
53
+ // paths, so no two live States write the same lockfile/bundle/resourcesBundle path --
54
+ // across copies, AND whether or not a preload exists.
55
+ const STATES_KEY = Symbol.for('@exodus/stasis-core/states')
56
+ function liveStates() {
57
+ return (globalThis[STATES_KEY] ??= new Set())
58
+ }
59
+
60
+ export class State {
61
+ hashes = new Map()
62
+ entries = new Set()
63
+ sources = new Map()
64
+ resources = new Map()
65
+ formats = new Map()
66
+ modules = new Map()
67
+ imports = new Map()
68
+ config
69
+ root
70
+ #parent
71
+
72
+ // True iff this is THE preload (top-level) State. Exposed via `get isPreload()` so
73
+ // State.preload can find the unique flagged member of the global registry across copies.
74
+ #isPreload = false
75
+
76
+ // This State's claimed write-target paths (canonicalized -> label), for cross-State
77
+ // collision detection. Exposed via `claimedWritePathLabel()` so the global scan in
78
+ // #claimWritePath can consult States from other stasis-core copies.
79
+ #claims = new Map()
80
+
81
+ // For a parent: WRITE-mode sidecar States constructed against it -- the lockfile
82
+ // CONTRIBUTORS. The unified lockfile (built by the parent's lockData via
83
+ // #mergedImports/#mergedFormats) must union the parent's own imports / formats with
84
+ // every sidecar's, otherwise resolution edges and format attestations a sidecar
85
+ // bundler-plugin observed (sidecar.addImport / addFile populate sidecar-local
86
+ // this.imports/this.formats) would never reach the lockfile. Hashes / entries /
87
+ // modules are already shared by reference; this closes the same gap for imports and
88
+ // formats. Also the set attestedBySidecar consults, so --fs skips re-capturing a
89
+ // read the bundler plugin already records here. Unused on sidecars themselves.
90
+ #sidecars = new Set()
91
+
92
+ // For a parent: LOAD-mode sidecar States -- read-only family members, NOT lockfile
93
+ // contributors. A bundler plugin's load-mode sidecar carries the module graph in its
94
+ // bundle; getFs*Family consults this set so a --fs read at load of a graph file the
95
+ // sidecar carries is served from it (the symmetric counterpart to the #sidecars
96
+ // capture-skip). Kept separate from #sidecars precisely so these never enter
97
+ // #mergedImports/#mergedFormats -- a load-mode sidecar contributes no resolution edges
98
+ // or formats (the lockfile's trust-bearing content) to the unified lockfile (the boundary
99
+ // the writeBundle gate on registration enforces; see the constructor and registerReadSidecar).
100
+ #readSidecars = new Set()
101
+
102
+ // Resolutions attested by the loaded lockfile (conditions -> parent ->
103
+ // specifier -> file), or null when no lockfile was loaded / it predates
104
+ // resolution attestation. Kept separate from this.imports (the live
105
+ // observed/bundle-served map): the lockfile may attest a superset of what a
106
+ // given run observes or a given bundle carries.
107
+ #lockImports = null
108
+
109
+ // Loader formats attested by the loaded lockfile (file -> format), or null
110
+ // when none was loaded / it predates format attestation. Like #lockImports,
111
+ // kept apart from this.formats (the live observed/bundle-served map).
112
+ #lockFormats = null
113
+
114
+ // True iff this State (or, for a sidecar, its parent) loaded a lockfile from
115
+ // disk during construction. Drives #mergeBundleMetadata's cross-check-vs-absorb
116
+ // branch: with a lockfile, the bundle's metadata must agree with the lockfile's
117
+ // attestations; without one, the bundle's metadata is absorbed as the source of
118
+ // truth. Sidecars inherit this from the parent at construction time so a sidecar
119
+ // bundle is cross-checked against the parent's lockfile attestation rather than
120
+ // silently trusted.
121
+ #lockfileLoaded = false
122
+
123
+ // Project-relative keys of files/directories THIS process recorded via addFile/addFsDir this
124
+ // run (as opposed to the lockfile baseline seeded at construction). shardSnapshot() forwards
125
+ // only these, so a forked child's shard carries what it observed -- not a re-ship of the whole
126
+ // seeded lockfile.
127
+ #observed = new Set()
128
+ // file -> set of consumers that recorded it, for the bundle's informational `reason` field.
129
+ // Keyed by consumer ('run' for the loader/CLI; a plugin label like 'StasisMetro' for a plugin
130
+ // sharing this State). Populated only when bundling. See #recordReason / #bundleReason.
131
+ #reasonFiles = new Map()
132
+ // Supporting state so the bundle `reason` map's "run" entry stays accurate (see #bundleReason):
133
+ // files run loaded as a MODULE (#runImported), files run merely fs-READ after a plugin attached
134
+ // (#fsReadPostPlugin), and whether a bundler plugin has attached to this State (#pluginAttached).
135
+ #runImported = new Set()
136
+ #fsReadPostPlugin = new Set()
137
+ #pluginAttached = false
138
+
139
+ // Files, resolutions, and formats attested by a frozen bundle (bundle=frozen),
140
+ // or null when no frozen bundle was loaded. A frozen bundle plays the same
141
+ // read-only attestation role a frozen lockfile does, but anchored in the
142
+ // bundle's own bytes -- so bundle=frozen needs no sibling lockfile. The byte
143
+ // check itself is the noupsert of observed disk content into this.sources/
144
+ // this.resources (both pre-seeded from the bundle); these sets/maps close the
145
+ // attested set so a file, resolution, or format the bundle never recorded is
146
+ // rejected. Kept separate from the live this.sources/this.imports/this.formats,
147
+ // which addFile/addImport mutate.
148
+ #bundleSources = null
149
+ #bundleResources = null
150
+ #bundleImports = null
151
+ #bundleFormats = null
152
+
153
+ // Lazily-built set of directory paths IMPLIED by the bundle's recorded entries
154
+ // (files, resources, directory listings): a recorded `node_modules/dep/index.js`
155
+ // proves `node_modules` and `node_modules/dep` exist as directories even though
156
+ // neither was readdir'd. getFsStat consults it so
157
+ // `fs.statSync('node_modules').isDirectory()` succeeds at bundle=load. Built once
158
+ // in load mode, where this.imports / this.sources are immutable after construction.
159
+ #impliedDirIndex = null
160
+
161
+ // Capture-time native resolutions (parent URL -> specifier -> resolved URL)
162
+ // observed via the Module._resolveFilename shim: require.resolve() and any CJS
163
+ // require() that bypasses the resolve hook. write()'s backfill records the edges
164
+ // the hook missed (deduped, in-bundle targets only). Populated only during capture.
165
+ #observedResolutions = new Map()
166
+
167
+ // Node's require-condition set (e.g. ['require', 'node', 'node-addons',
168
+ // 'module-sync'], plus any --conditions), captured the first time addImport sees a
169
+ // require()-context edge. require()/require.resolve() resolve under THESE conditions
170
+ // -- they honor the `require` branch of conditional `exports`, so they're not
171
+ // condition-free -- so #backfillObservedResolutions keys the native
172
+ // (Module._resolveFilename) edges it recovers under this set rather than the
173
+ // wildcard '*'. That matches what the resolve hook records directly (newer Node) and
174
+ // unifies them with the require() bucket, so any capture that does at least one
175
+ // require() (the common case) yields the same lockfile on every Node version. null
176
+ // until observed -- a capture that ONLY require.resolve()s and never require()s
177
+ // leaves it null and backfill falls back to '*' (as before this change), which the
178
+ // getImport/resolveBundled wildcard fallbacks still match.
179
+ #requireConditions = null
180
+
181
+ // Absolute path of a package whose source files were loaded by Node BEFORE
182
+ // our hooks registered (the preload-cached set). Set by the loader's
183
+ // initState to stasis-core's own root; sidecars inherit it from their
184
+ // parent so plugin-driven write()s also backfill internal edges. write()'s
185
+ // backfill statically parses each file under this root and addImports its
186
+ // relative-specifier edges -- recovering the (state.js -> config.js)-shape
187
+ // edges that the live resolve hook never observed.
188
+ #preloadRoot = null
189
+
190
+ // Per-artifact "last serialized" caches: write() compares the freshly serialized
191
+ // JSON text against the cached one for each output (lockfile / unified bundle /
192
+ // split code / split resources) and skips both the brotli step and the writeFileSync
193
+ // when they match. Brotli at quality 11 dominates write cost, and webpack/esbuild
194
+ // watch-mode rebuilds call write() on every rebuild whether or not the captured
195
+ // graph actually changed -- this cache makes those no-ops fast. Persistent across
196
+ // write() calls within one process; null on the first call.
197
+ #lastLockData = null
198
+ #lastUnifiedBundle = null
199
+ #lastCodeBundle = null
200
+ #lastResourcesBundle = null
201
+
202
+ // Options:
203
+ // preload (boolean) -- register as the unique preload State (exposed via State.preload).
204
+ // Only one preload may exist at a time. The stasis loader is the only real caller.
205
+ // parent (State) -- run as a sidecar of this parent. Sidecar shares the parent's
206
+ // hashes/entries/modules (so addFile updates the unified lockfile through them) but
207
+ // manages its own sources/formats/imports/resources and emits its own bundle file.
208
+ // write() on a sidecar skips the lockfile (parent owns it) and only writes its bundle.
209
+ // All other keys forward to Config.
210
+ constructor(root, options = {}) {
211
+ // skipDiscovery: build a caller-populated, in-memory State with NO filesystem discovery -- root is the passed `root` arg, and sources/imports/formats/entries are filled in by the caller after construction (no package.json walk, no on-disk config/lockfile/bundle reads). For artifact-driven tooling like `stasis build`, which serves a parsed bundle (or a lockfile reconstructed + verified in memory) and must not depend on a project's stasis.config.json or read a stray stasis.code.br. Read-only (load/ignore) modes only.
212
+ const { preload: isPreload = false, parent: parentState, preloadRoot, skipDiscovery = false, ...configOptions } = options
213
+ this.config = new Config(configOptions)
214
+ if (isPreload) assert.ok(!State.preload, 'Only one preload Stasis instance is supported')
215
+ assert.ok(!(isPreload && parentState), 'preload and parent are mutually exclusive')
216
+ this.#isPreload = isPreload
217
+
218
+ if (parentState) {
219
+ // A child (sidecar) shares the parent's maps by reference and inherits its lockfile
220
+ // attestation, so the parent MUST be the exact same stasis-core VERSION -- but it
221
+ // need NOT be the same module copy. A bundle that carries its OWN stasis-core (e.g.
222
+ // a webpack script + StasisWebpack run under `stasis run --bundle=load`) has the
223
+ // plugin's copy coordinate with the OUTER loader's preload across the class brand.
224
+ // The exact-version match makes that sound; everything the sidecar reads from the
225
+ // parent goes through the parent's PUBLIC surface (`version`, `sidecarInheritance`,
226
+ // `registerSidecar`, and the shared public maps), never a private field a foreign
227
+ // class brand would deny. A version skew is unsound -- reject it with a clear error.
228
+ assert.equal(parentState.version, VERSION,
229
+ `child State version '${VERSION}' must exactly match parent version '${parentState.version}'`)
230
+ // Sidecar mode: short-circuit the on-disk discovery path. Lockfile data is shared by
231
+ // reference with the parent; only the sidecar's bundleFile (if any) is parsed here.
232
+ this.#parent = parentState
233
+ this.root = parentState.root
234
+ this.hashes = parentState.hashes
235
+ this.entries = parentState.entries
236
+ this.modules = parentState.modules
237
+ // Inherit, via the parent's public sidecarInheritance() so it works across copies:
238
+ // - preloadRoot, so plugin-driven write()s (StasisWebpack / StasisEsbuild done-hook
239
+ // saves) backfill stasis-core's internal edges the same way the parent does;
240
+ // - the lockfile attestation maps, so #mergeBundleMetadata cross-checks the sidecar
241
+ // bundle against the same attestation the parent loaded -- without this a tampered
242
+ // sidecar bundle could redirect a resolution or flip a format (commonjs <->
243
+ // module-typescript) for hash-valid bytes, which the byte check alone misses.
244
+ const inherited = parentState.sidecarInheritance()
245
+ this.#preloadRoot = inherited.preloadRoot
246
+ this.#lockImports = inherited.lockImports
247
+ this.#lockFormats = inherited.lockFormats
248
+ this.#lockfileLoaded = inherited.lockfileLoaded
249
+ assert.ok(this.config.bundleFile, 'sidecar State requires bundleFile')
250
+ // Claim the bundleFile (and resourcesBundleFile under the split layout) against the
251
+ // process-wide registry so two write-intent States anywhere -- whether a sibling
252
+ // sidecar or an independent top-level State (a CLI/env run with a custom
253
+ // lockfile/bundle path) -- can't silently target the same on-disk file
254
+ // (last-write-wins on `beforeExit`). Only writing States claim; read-only modes
255
+ // (load / frozen) may legitimately share a path with the writer that produced the
256
+ // file. The Config's own pairwise cross-path check (config.js:#checkInvariants)
257
+ // already rejects intra-State collisions, so #claimWritePath only fires on
258
+ // cross-State conflicts.
259
+ if (this.config.writeBundle) {
260
+ this.#claimWritePath(`sidecar bundleFile '${this.config.bundleFile}'`, this.config.bundleFile)
261
+ if (this.config.resourcesBundleFile) {
262
+ this.#claimWritePath(`sidecar resourcesBundleFile '${this.config.resourcesBundleFile}'`,
263
+ this.config.resourcesBundleFile)
264
+ }
265
+ }
266
+ // frozenBundle MUST go through this branch alongside write/load -- it has its
267
+ // own attestation snapshot to build, and was previously missed (silently
268
+ // skipping parsing made the post-construction frozen-bundle invariant
269
+ // unreachable on the sidecar path).
270
+ if (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) {
271
+ const sourcesPath = this.config.bundleFile
272
+ const sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
273
+ if (sources && !this.config.replaceBundle) {
274
+ const bundle = Bundle.parse(brotliDecompressSync(sources).toString('utf-8'))
275
+ // Same v0 refusal as the main load path: a v0 bundle has no per-file
276
+ // formats and no import map, so serving / verifying one through a
277
+ // sidecar would silently widen trust.
278
+ assert.equal(bundle.version, Bundle.VERSION,
279
+ `stasis sidecar requires a v1 bundle; ${sourcesPath} is v${bundle.version}. ` +
280
+ `Re-bundle with the current stasis or \`bundle=replace\` against a v0-free starting point.`)
281
+ assert.equal(bundle.config.scope, this.config.scope)
282
+ // Cross-check the sidecar bundle's metadata against the parent's lockfile
283
+ // (or absorb if no lockfile was loaded). hashes/entries/modules are shared
284
+ // with the parent, so #mergeBundleMetadata's writes -- when no lockfile is
285
+ // loaded -- propagate into the unified attestation.
286
+ this.#mergeBundleMetadata(bundle, { lockfileLoaded: this.#lockfileLoaded })
287
+ for (const [file, content] of bundle.sources) {
288
+ if (Bundle.isResourceFormat(bundle.formats.get(file))) this.resources.set(file, content)
289
+ else this.sources.set(file, content)
290
+ }
291
+ this.formats = bundle.formats
292
+ this.imports = bundle.imports
293
+ if (this.config.frozenBundle) {
294
+ // Same snapshot the main path takes -- closes the attested set so
295
+ // addFile/addImport reject anything the bundle didn't carry.
296
+ this.#bundleSources = new Set(this.sources.keys())
297
+ this.#bundleResources = new Set(this.resources.keys())
298
+ this.#bundleImports = objectToMaps(fileMapToObject(bundle.imports))
299
+ this.#bundleFormats = new Map(bundle.formats)
300
+ }
301
+ }
302
+
303
+ // Sidecar split-bundle: same shape as the main path's resources-side load.
304
+ if (this.config.resourcesBundleFile) {
305
+ const resourcesPath = this.config.resourcesBundleFile
306
+ const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
307
+ if (resourcesData && !this.config.replaceBundle) {
308
+ this.#absorbResourcesBundle(resourcesData, { lockfileLoaded: this.#lockfileLoaded, resourcesPath })
309
+ }
310
+ }
311
+ }
312
+ // Mirror the post-discovery invariant from the main path: frozen modes must
313
+ // have actually loaded their attestation, otherwise the run would fail open.
314
+ if (this.config.frozenBundle) {
315
+ assert.ok(this.#bundleSources !== null, 'No bundle, but attempting to run in frozen bundle mode')
316
+ }
317
+ // Register with the parent AFTER every fallible step (v0 refusal, scope
318
+ // equality, #mergeBundleMetadata cross-check, frozenBundle invariant) so a
319
+ // throw never leaves a dead reference in the parent's registries.
320
+ // Write-mode sidecars are lockfile CONTRIBUTORS -- their addImport / addFile
321
+ // observations have to land in the unified lockfile, otherwise a `lock=frozen`
322
+ // re-run rejects them as unattested -- so they join #sidecars (which feeds
323
+ // #mergedImports/#mergedFormats and attestedBySidecar). Load-mode sidecars are
324
+ // CONSUMERS: they must NOT contribute to the parent's lockfile (the bundle has
325
+ // its own integrity story, and under `lock=add` with no prior lockfile a
326
+ // load-mode sidecar would otherwise silently make the bundle's content the
327
+ // lockfile's source of truth), but they DO carry bundle bytes that --fs serves at
328
+ // load, so they join the read-only #readSidecars (consulted by getFs*Family only).
329
+ // Frozen sidecars join neither: --fs neither captures nor serves in frozen-bundle
330
+ // mode (fs.js gates capture on writeBundle and serve on loadBundle), and their
331
+ // lockfile cross-check already happened in #mergeBundleMetadata above.
332
+ if (this.config.writeBundle) parentState.registerSidecar(this)
333
+ else if (this.config.loadBundle) parentState.registerReadSidecar(this)
334
+ liveStates().add(this)
335
+ return
336
+ }
337
+
338
+ // skipDiscovery (see the constructor comment): a caller-populated, in-memory State.
339
+ // Skip the entire filesystem-discovery path -- anchor at the given root, read nothing --
340
+ // and let the caller fill in the maps. Only sound for read-only load/ignore modes:
341
+ // there is no on-disk attestation to load or verify, so frozen modes are rejected.
342
+ if (skipDiscovery) {
343
+ // Read-only by contract: a caller-populated in-memory State has no on-disk baseline,
344
+ // so neither frozen verification (nothing to verify against) nor write modes (nothing
345
+ // discovered to write) are meaningful. `stasis build` uses bundle:'load', lock:'ignore'.
346
+ assert.ok(!this.config.frozen && !this.config.frozenBundle && !this.config.writeBundle && !this.config.writeLockfile,
347
+ 'skipDiscovery is read-only: incompatible with frozen and write (add/replace) lock/bundle modes')
348
+ this.root = resolve(root)
349
+ if (preloadRoot !== undefined) {
350
+ assert.equal(typeof preloadRoot, 'string', 'preloadRoot must be a string')
351
+ this.#preloadRoot = preloadRoot
352
+ }
353
+ liveStates().add(this)
354
+ return
355
+ }
356
+
357
+ // Preload-uniqueness invariant must be checked before construction proceeds; the
358
+ // actual liveStates() registration happens after construction succeeds so a throw in
359
+ // setup can't leave a half-built (and, for a preload, singleton-claiming) State behind.
360
+ const potentialRoots = []
361
+ let cursor = root
362
+ while (cursor) {
363
+ if (existsSync(join(cursor, 'package.json'))) {
364
+ potentialRoots.push(cursor)
365
+ } else if (
366
+ existsSync(join(cursor, FILE_CONFIG)) ||
367
+ existsSync(join(cursor, FILE_LOCK)) ||
368
+ existsSync(join(cursor, FILE_CODE))) {
369
+ throw new Error('Unexpected stasis config without package.json')
370
+ }
371
+
372
+ if (cursor === process.env.PROJECT_CWD) break // e.g. yarn sets this
373
+ if (existsSync(join(cursor, '.git'))) break // don't go higher than the repo root
374
+ if (existsSync(join(cursor, 'pnpm-workspace.yaml'))) break // pnpm workspace root
375
+ const parent = dirname(cursor)
376
+ if (!parent || parent === cursor) break
377
+ cursor = parent
378
+ }
379
+
380
+ // default root is top-level package.json, to opt-in to per-dir create stasis.config.json
381
+ this.root = potentialRoots.at(-1)
382
+
383
+ let loaded = false
384
+ let lockfileLoaded = false
385
+ // When `config.lockFile` is set, the lockfile lives at that explicit path -- not at
386
+ // join(rootDir, FILE_LOCK) for any candidate rootDir. Suppress the per-rootDir read
387
+ // for root-detection (so a stale stasis.lock.json at the project root can't shadow
388
+ // the explicit one), then substitute the explicit content once root-detection has
389
+ // committed to a rootDir below.
390
+ const explicitLockPath = this.config.lockFile
391
+ // A construction-time `bundleFile` (a --bundle-file flag or EXODUS_STASIS_BUNDLE_FILE) is
392
+ // rootDir-INDEPENDENT: reading it yields the same file at every candidate root. So, exactly
393
+ // like explicitLockPath, it must NOT act as a per-rootDir root-detection signal -- if it did,
394
+ // the innermost package.json dir would always match first and win, diverging load's root from
395
+ // the (outer) root the bundle was captured with. Because every bundle key is stored relative
396
+ // to the capture root, that divergence makes every bundled dependency unreachable at load: the
397
+ // load hook throws "outside project root" / "not attested", and Node's ESM->CJS translator --
398
+ // which re-resolves a required dependency through Module._load(absPath, /* no parent */) -- hits
399
+ // native disk resolution for a file the bundle carries but disk (post-prune / never-shipped)
400
+ // does not, i.e. `Cannot find module '<abs node_modules path>'`. Root is instead chosen from
401
+ // rootDir-DEPENDENT signals (stasis.config.json, the default lockfile/bundle at the dir), then
402
+ // the explicit bundle is loaded at the committed root -- or, when nothing else committed, at the
403
+ // outermost root post-loop (mirroring explicitLockPath). A `bundleFile` that comes only from
404
+ // stasis.config.json is NOT suppressed: it lives at a dir already carrying the config signal, so
405
+ // it selects that dir consistently at capture and load alike.
406
+ const explicitBundlePath = this.config.bundleFile
407
+ for (const rootDir of potentialRoots) {
408
+ const config = readFileSyncMaybe(rootDir, FILE_CONFIG, 'utf-8')
409
+ const lockProbe = explicitLockPath ? null : readFileSyncMaybe(rootDir, FILE_LOCK, 'utf-8')
410
+ // Read the bundle at the construction-time bundleFile (a --bundle-file flag or
411
+ // EXODUS_STASIS_BUNDLE_FILE) or, absent that, the default <rootDir>/stasis.code.br -- used
412
+ // to LOAD the bundle once a root is committed. The authoritative path can still change when
413
+ // loadConfig() applies a `bundleFile` from stasis.config.json, so it's re-read below.
414
+ let sourcesPath = this.config.bundleFile || join(rootDir, FILE_CODE)
415
+ let sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
416
+ // Root-SELECTION signal: only the DEFAULT <rootDir>/stasis.code.br counts. An explicit
417
+ // (rootDir-independent) bundleFile is suppressed here (see explicitBundlePath above) so it
418
+ // can't bias selection to the innermost dir; it is still loaded via `sources` once committed.
419
+ const bundleProbe = explicitBundlePath ? null : sources
420
+ if (config !== null || lockProbe !== null || bundleProbe !== null) {
421
+ if (loaded) throw new Error('Stasis config already loaded')
422
+ loaded = true
423
+ this.root = rootDir
424
+
425
+ if (config) {
426
+ this.config.loadConfig(config)
427
+ // stasis.config.json may set `bundleFile`, which the probe above (using the
428
+ // construction-time value) could not see. Re-resolve against the now-authoritative
429
+ // config and re-read, so a config-only bundleFile is honored for load/frozen -- the
430
+ // write side (state.write) already resolves bundleFile after loadConfig. This mirrors
431
+ // the resourcesBundleFile read below, which is naturally post-loadConfig.
432
+ const configuredPath = this.config.bundleFile || join(rootDir, FILE_CODE)
433
+ if (configuredPath !== sourcesPath) {
434
+ sourcesPath = configuredPath
435
+ sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
436
+ }
437
+ }
438
+
439
+ // Resolve the effective lockfile content + path for this run. With an explicit
440
+ // `config.lockFile`, the lockfile is at that exact path (loaded once, not at a
441
+ // per-rootDir probe); without one, fall back to `<rootDir>/stasis.lock.json`.
442
+ const lock = explicitLockPath
443
+ ? readFileSyncMaybe(dirname(explicitLockPath), basename(explicitLockPath), 'utf-8')
444
+ : lockProbe
445
+ const lockPath = explicitLockPath || join(rootDir, FILE_LOCK)
446
+
447
+ if (lock && !this.config.useLockfile && !this.config.ignoreLockfile) {
448
+ throw new Error(`Unexpected ${lockPath} with config.lock = 'none'`)
449
+ }
450
+ if (sources && !this.config.writeBundle && !this.config.loadBundle && !this.config.ignoreBundle && !this.config.frozenBundle) {
451
+ throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
452
+ }
453
+
454
+ // A frozen bundle is self-attesting -- it verifies disk against the bundle's
455
+ // own bytes, so (unlike load/add) it needs no sibling lockfile and is exempt
456
+ // from this "a lockfile is required before a bundle's sources can be trusted"
457
+ // guard. This is what lets bundle=frozen compose with lock=add (bootstrapping a
458
+ // fresh lockfile from the verified run) without a pre-existing lockfile.
459
+ if (sources && !lock && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
460
+ throw new Error('stasis.lock.json missing, can not use sources')
461
+ }
462
+
463
+ if (lock && this.config.useLockfile && !this.config.replaceLockfile) {
464
+ const lockfile = Lockfile.parse(lock)
465
+ if (this.config.frozen) assert.equal(lockfile.config.scope, this.config.scope)
466
+
467
+ const includeSources = lockfile.config.scope === 'full' && this.config.full
468
+ for (const [dir, info] of lockfile.modules) {
469
+ if (!dir.includes('node_modules') && !includeSources) continue
470
+ this.modules.set(dir, info)
471
+ }
472
+ if (includeSources) this.entries = lockfile.entries
473
+
474
+ for (const [dir, { files }] of this.modules) {
475
+ for (const [name, hash] of Object.entries(files)) {
476
+ noupsert(this.hashes, join(dir, name), hash)
477
+ }
478
+ }
479
+ this.#lockImports = lockfile.imports
480
+ this.#lockFormats = lockfile.formats
481
+ // Frozen promises verification, but a lockfile predating resolution
482
+ // or format attestation can only vouch for bytes -- those metadata
483
+ // (from a bundle OR observed on disk) go unchecked until it's
484
+ // regenerated.
485
+ if (this.config.frozen && this.#lockImports === null) {
486
+ console.warn('[stasis] Warning: lockfile does not attest resolutions; they are trusted as-is. Regenerate the lockfile to enable this check.')
487
+ }
488
+ if (this.config.frozen && this.#lockFormats === null) {
489
+ console.warn('[stasis] Warning: lockfile does not attest formats; they are trusted as-is. Regenerate the lockfile to enable this check.')
490
+ }
491
+ lockfileLoaded = true
492
+ this.#lockfileLoaded = true
493
+ }
494
+
495
+ if (sources && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
496
+ this.#absorbCodeBundle(sources, sourcesPath, lockfileLoaded)
497
+ }
498
+
499
+ // Split-bundle layout: when `resourcesBundleFile` is configured, resources
500
+ // live in a separate file. Load it as a standalone Bundle (entries empty,
501
+ // imports empty, formats restricted to resource tags) and union into the
502
+ // state already absorbed from `bundleFile`. The strict-shape asserts catch
503
+ // a writer that accidentally leaked code into the resources file or a
504
+ // tampered file claiming entries/imports it shouldn't have.
505
+ if (this.config.resourcesBundleFile) {
506
+ const resourcesPath = this.config.resourcesBundleFile
507
+ const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
508
+ if (resourcesData && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
509
+ this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
510
+ }
511
+ }
512
+
513
+ // The innermost matching rootDir is authoritative (per-dir opt-in, see above), so stop
514
+ // scanning once committed. An explicit/config `bundleFile` is rootDir-independent: without
515
+ // this break an outer candidate root re-detects the SAME bundle file at its own probe and
516
+ // trips the `loaded` guard above -- which crashed bundle=load/frozen in any nested-package
517
+ // (monorepo) layout where a leaf package sits under an ancestor that also has a package.json.
518
+ break
519
+ }
520
+ }
521
+
522
+ // Explicit lockfile path with no other discovery indicator at any rootDir: the
523
+ // discovery loop never set `loaded`, so the lockfile branch above never ran. Process
524
+ // the explicit lockfile here against the already-resolved `this.root` (outermost
525
+ // package.json) so the run still has its attestation. Inlines the same gates as the
526
+ // in-loop branch -- a future refactor could merge the two by extracting a helper.
527
+ if (!loaded && explicitLockPath) {
528
+ const lock = readFileSyncMaybe(dirname(explicitLockPath), basename(explicitLockPath), 'utf-8')
529
+ if (lock && !this.config.useLockfile && !this.config.ignoreLockfile) {
530
+ throw new Error(`Unexpected ${explicitLockPath} with config.lock = 'none'`)
531
+ }
532
+ if (lock && this.config.useLockfile && !this.config.replaceLockfile) {
533
+ const lockfile = Lockfile.parse(lock)
534
+ if (this.config.frozen) assert.equal(lockfile.config.scope, this.config.scope)
535
+ const includeSources = lockfile.config.scope === 'full' && this.config.full
536
+ for (const [dir, info] of lockfile.modules) {
537
+ if (!dir.includes('node_modules') && !includeSources) continue
538
+ this.modules.set(dir, info)
539
+ }
540
+ if (includeSources) this.entries = lockfile.entries
541
+ for (const [dir, { files }] of this.modules) {
542
+ for (const [name, hash] of Object.entries(files)) {
543
+ noupsert(this.hashes, join(dir, name), hash)
544
+ }
545
+ }
546
+ this.#lockImports = lockfile.imports
547
+ this.#lockFormats = lockfile.formats
548
+ if (this.config.frozen && this.#lockImports === null) {
549
+ console.warn('[stasis] Warning: lockfile does not attest resolutions; they are trusted as-is. Regenerate the lockfile to enable this check.')
550
+ }
551
+ if (this.config.frozen && this.#lockFormats === null) {
552
+ console.warn('[stasis] Warning: lockfile does not attest formats; they are trusted as-is. Regenerate the lockfile to enable this check.')
553
+ }
554
+ lockfileLoaded = true
555
+ this.#lockfileLoaded = true
556
+ }
557
+ }
558
+
559
+ // Explicit (flag/env) bundleFile with no rootDir-dependent indicator at any rootDir: like the
560
+ // explicit lockfile above, it was suppressed as a root-detection signal so it couldn't pull the
561
+ // root down to the innermost package, so the loop never loaded it. Load it here against
562
+ // `this.root` (the outermost package.json) -- the same root capture commits to when no signal
563
+ // exists -- so its capture-root-relative keys line up with how they're looked up. Inlines the
564
+ // same gates as the in-loop bundle branch.
565
+ if (!loaded && explicitBundlePath) {
566
+ const sourcesPath = this.config.bundleFile
567
+ const sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
568
+ if (sources && !this.config.writeBundle && !this.config.loadBundle && !this.config.ignoreBundle && !this.config.frozenBundle) {
569
+ throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
570
+ }
571
+ if (sources && !lockfileLoaded && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
572
+ throw new Error('stasis.lock.json missing, can not use sources')
573
+ }
574
+ if (sources && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
575
+ this.#absorbCodeBundle(sources, sourcesPath, lockfileLoaded)
576
+ }
577
+ // Split-bundle resources: same post-loop treatment (resourcesBundleFile is likewise an
578
+ // explicit, rootDir-independent path). Mirrors the in-loop resources branch.
579
+ if (this.config.resourcesBundleFile) {
580
+ const resourcesPath = this.config.resourcesBundleFile
581
+ const resourcesData = readFileSyncMaybe(dirname(resourcesPath), basename(resourcesPath))
582
+ if (resourcesData && (this.config.writeBundle || this.config.loadBundle || this.config.frozenBundle) && !this.config.replaceBundle) {
583
+ this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
584
+ }
585
+ }
586
+ }
587
+
588
+ // Frozen modes must have actually loaded their attestation. Asserting here --
589
+ // after the discovery loop -- rather than only inside it closes a fail-open: with
590
+ // no stasis files on disk at all the loop body never runs, so a per-rootDir guard
591
+ // would never fire, and in node_modules scope the workspace entry sits outside the
592
+ // attested zone (its bytes/format/resolutions aren't checked), letting it execute
593
+ // unverified. A frozen run with nothing to verify against must fail closed instead.
594
+ if (this.config.frozen) assert.ok(lockfileLoaded, 'No lockfile, but attempting to run in frozen mode')
595
+ if (this.config.frozenBundle) assert.ok(this.#bundleSources !== null, 'No bundle, but attempting to run in frozen bundle mode')
596
+
597
+ // Claim this State's write targets against the process-wide registry (liveStates),
598
+ // so a sidecar OR an independent top-level State -- in this OR another stasis-core
599
+ // copy -- can't silently target the same on-disk file. Load / frozen / no-bundle modes
600
+ // don't claim (they legitimately read what a previous writer produced). lockFile is
601
+ // claimed only by writing top-level States -- sidecars don't write the lockfile, and
602
+ // the explicit path may legitimately point at the parent's under unification. The
603
+ // State itself is added to liveStates() below, AFTER every fallible step (including
604
+ // these claims), so a throw during discovery/parsing/claiming never leaves a dead member.
605
+ if (this.config.writeBundle && this.config.bundleFile) {
606
+ this.#claimWritePath(`bundleFile '${this.config.bundleFile}'`, this.config.bundleFile)
607
+ }
608
+ if (this.config.writeBundle && this.config.resourcesBundleFile) {
609
+ this.#claimWritePath(`resourcesBundleFile '${this.config.resourcesBundleFile}'`, this.config.resourcesBundleFile)
610
+ }
611
+ if (this.config.writeLockfile && this.config.lockFile) {
612
+ this.#claimWritePath(`lockFile '${this.config.lockFile}'`, this.config.lockFile)
613
+ }
614
+
615
+ // preloadRoot is opt-in -- only the runtime loader (hooks.js's initState)
616
+ // sets it, pointing at stasis-core's own package root. Plain top-level
617
+ // States constructed via the CLI / direct API leave it null and skip
618
+ // the internal-edges backfill entirely.
619
+ if (preloadRoot !== undefined) {
620
+ assert.equal(typeof preloadRoot, 'string', 'preloadRoot must be a string')
621
+ this.#preloadRoot = preloadRoot
622
+ }
623
+
624
+ liveStates().add(this)
625
+ }
626
+
627
+ // Absorb a unified code+resource bundle's metadata and payloads into this State. Shared by the
628
+ // discovery loop (a committed rootDir carrying a stasis signal) and the post-loop fallback that
629
+ // loads an explicit (rootDir-independent) bundleFile against the outermost root.
630
+ #absorbCodeBundle(sources, sourcesPath, lockfileLoaded) {
631
+ // One unified bundle carries both code and resources. Split the flat file
632
+ // view into this.sources (code) and this.resources (resource payloads --
633
+ // raw UTF-8 for 'resource', base64 for 'resource:base64') by format.
634
+ const bundle = Bundle.parse(brotliDecompressSync(sources).toString('utf-8'))
635
+ // `Bundle.parse` accepts v0 for offline tooling (`stasis extract`, `diff`,
636
+ // `audit`, `sbom`) -- it has the metadata those commands need. The runtime
637
+ // path is stricter: a v0 bundle has no per-file `formats` attestation
638
+ // (resources can't be distinguished from code, the loader can't pick
639
+ // module-vs-commonjs) and no import map (resolution edges go unchecked),
640
+ // so serving / verifying one under `stasis run` would silently widen the
641
+ // trust boundary. Refuse it explicitly and point at the upgrade path.
642
+ assert.equal(bundle.version, Bundle.VERSION,
643
+ `stasis run requires a v1 bundle; ${sourcesPath} is v${bundle.version}. ` +
644
+ `Re-bundle with the current stasis (\`stasis bundle\`) or \`stasis run --bundle=replace\` ` +
645
+ `against a v0-free starting point to upgrade.`)
646
+ assert.equal(bundle.config.scope, this.config.scope)
647
+ this.#mergeBundleMetadata(bundle, { lockfileLoaded })
648
+ for (const [file, content] of bundle.sources) {
649
+ if (Bundle.isResourceFormat(bundle.formats.get(file))) this.resources.set(file, content)
650
+ else this.sources.set(file, content)
651
+ }
652
+ this.formats = bundle.formats
653
+ this.imports = bundle.imports
654
+ if (this.config.frozenBundle) {
655
+ // Snapshot the attested sets before addFile/addImport mutate the live maps.
656
+ // imports is deep-cloned (this.imports shares bundle.imports's nested Maps,
657
+ // which addImport extends); formats is a flat file->string map, so a shallow
658
+ // copy suffices. Code and resource file sets are tracked separately to match
659
+ // addFile's per-kind frozen-bundle membership check.
660
+ this.#bundleSources = new Set(this.sources.keys())
661
+ this.#bundleResources = new Set(this.resources.keys())
662
+ this.#bundleImports = objectToMaps(fileMapToObject(bundle.imports))
663
+ this.#bundleFormats = new Map(bundle.formats)
664
+ }
665
+ }
666
+
667
+ // Cross-check bundle metadata (entries/modules) with what the lockfile already
668
+ // loaded, or absorb it as the source of truth when no lockfile is present.
669
+ // v0 bundles infer `name` from path for node_modules buckets but carry no
670
+ // version; the workspace "." bucket has no inferable name. We skip entries
671
+ // we can't cross-check (no name with lockfile, or no version when populating
672
+ // state.modules — addFile later asserts strict name+version equality against
673
+ // disk's package.json, which would clash with a null we stashed earlier).
674
+ // Note: the path-inferred name for v0 will disagree with the lockfile when a
675
+ // dep is installed under an alias (`foo: npm:bar` writes `node_modules/foo`
676
+ // with `name: "bar"` in package.json); the strict equality below will fail
677
+ // in that case, which is the right call — the v0 bundle has no way to
678
+ // attest the real package identity, so we refuse to silently mismatch.
679
+ #mergeBundleMetadata(bundle, { lockfileLoaded }) {
680
+ if (lockfileLoaded) {
681
+ if (bundle.entries.size > 0) {
682
+ assert.deepStrictEqual(
683
+ [...bundle.entries].toSorted(),
684
+ [...this.entries].toSorted(),
685
+ 'bundle/lockfile entries mismatch'
686
+ )
687
+ }
688
+ for (const [dir, info] of bundle.modules) {
689
+ if (!info.name) continue // workspace bucket or fallback: no inferable name
690
+ assert.ok(this.modules.has(dir), `bundle module ${dir} missing in lockfile`)
691
+ const lockModule = this.modules.get(dir)
692
+ assert.equal(info.name, lockModule.name)
693
+ if (info.version) assert.equal(info.version, lockModule.version)
694
+ for (const rel of Object.keys(info.files)) {
695
+ assert.ok(Object.hasOwn(lockModule.files, rel), `bundle file ${dir}/${rel} missing in lockfile`)
696
+ }
697
+ }
698
+ // Resolutions: every edge the bundle could serve must land on the file
699
+ // the lockfile attests for that (parent, specifier) -- source hashes
700
+ // alone don't close this hole: a tampered bundle could redirect a
701
+ // specifier to a *different* hash-valid file. Unknown edges are fatal.
702
+ // The lockfile may attest a superset (same stance as the file lists
703
+ // above). Lockfiles that predate resolution attestation
704
+ // (imports === null) skip the check -- regenerate with lock=replace.
705
+ if (this.#lockImports !== null) {
706
+ for (const [conditions, byParent] of bundle.imports) {
707
+ for (const [parent, specifiers] of byParent) {
708
+ for (const [specifier, file] of specifiers) {
709
+ this.#assertAttestedResolution(this.#lockImports, conditions, parent, specifier, file, { what: 'bundle', source: 'lockfile' })
710
+ }
711
+ }
712
+ }
713
+ }
714
+ // Formats: the loader picks module<->commonjs and (for *-typescript)
715
+ // whether Node strips type syntax purely from this map, so a tampered
716
+ // bundle can change how hash-valid bytes parse/run without touching a
717
+ // hash. Every format the bundle declares must match the lockfile's. The
718
+ // bundle's file set is a subset of the lockfile, so an unattested format
719
+ // is fatal here (it can only mean a forged entry).
720
+ if (this.#lockFormats !== null) {
721
+ for (const [file, format] of bundle.formats) {
722
+ this.#assertAttestedFormat(this.#lockFormats, file, format, { what: 'bundle', source: 'lockfile' })
723
+ }
724
+ // Inverse direction: if the lockfile tags a file the bundle carries as a
725
+ // resource, the bundle MUST declare the matching resource format. Without
726
+ // this, a tampered bundle could OMIT the resource tag entirely -- State.load
727
+ // would then see no resource format, route the base64 payload through
728
+ // `this.sources` (the code path), and hand it to the loader. Caught at the
729
+ // loader's NODEJS_FORMATS gate too, but checking here surfaces it as a clean
730
+ // bundle/lockfile mismatch rather than as an opaque "unknown format" later.
731
+ // (We don't extend this to code formats: doing so would mean asserting
732
+ // `formats` is total over `modules`, which is a stronger schema invariant
733
+ // than the historical "format may be missing per file" contract -- and the
734
+ // code-format hole is closed by the loader allowlist anyway.)
735
+ for (const [dir, { files }] of bundle.modules) {
736
+ for (const rel of Object.keys(files)) {
737
+ const file = moduleFileKey(dir, rel)
738
+ const lockFormat = this.#lockFormats.get(file)
739
+ if (!Bundle.isResourceFormat(lockFormat)) continue
740
+ assert.equal(bundle.formats.get(file), lockFormat,
741
+ `bundle file ${file} must declare format='${lockFormat}' to match the lockfile`)
742
+ }
743
+ }
744
+ }
745
+ } else {
746
+ // Mutate in place rather than reassigning -- this.entries may be shared by
747
+ // reference with a sidecar's parent (the unified-lockfile model), and a
748
+ // reassignment would silently fork the shared set.
749
+ for (const e of bundle.entries) this.entries.add(e)
750
+ for (const [dir, info] of bundle.modules) {
751
+ if (!info.name || !info.version) continue // partial metadata
752
+ if (this.modules.has(dir)) {
753
+ // A unified bundle populates `state.modules` from both its code and resource
754
+ // entries; if the same dir is added twice (e.g. legacy duplicated metadata)
755
+ // they must agree on name/version.
756
+ const existing = this.modules.get(dir)
757
+ assert.equal(info.name, existing.name, `bundle ${dir} name mismatch`)
758
+ assert.equal(info.version, existing.version, `bundle ${dir} version mismatch`)
759
+ } else {
760
+ this.modules.set(dir, info.ecosystem === undefined
761
+ ? { name: info.name, version: info.version, files: Object.create(null) }
762
+ : { name: info.name, version: info.version, ecosystem: info.ecosystem, files: Object.create(null) })
763
+ }
764
+ }
765
+ }
766
+ }
767
+
768
+ // Load the resources side of a split-bundle layout: a standalone Bundle file
769
+ // that MUST hold only resource-format files (no entries, no imports, no
770
+ // code-format declarations). Unions into the state already absorbed from
771
+ // `bundleFile`, extending this.resources, this.formats, and -- under
772
+ // frozenBundle -- the attestation snapshots. The shape asserts catch a writer
773
+ // that leaked code into the resources file or a tampered file claiming
774
+ // metadata it shouldn't carry.
775
+ #absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath }) {
776
+ const bundle = Bundle.parse(brotliDecompressSync(resourcesData).toString('utf-8'))
777
+ assert.equal(bundle.version, Bundle.VERSION,
778
+ `stasis run requires a v1 resources bundle; ${resourcesPath} is v${bundle.version}. ` +
779
+ `Re-bundle with the current stasis or \`bundle=replace\` against a v0-free starting point to upgrade.`)
780
+ assert.equal(bundle.config.scope, this.config.scope)
781
+ // Resources file MUST NOT declare resolution edges or entry points -- those
782
+ // belong to the code bundle. A populated map here means the writer mixed
783
+ // halves (or the file was tampered with) and serving it would silently widen
784
+ // trust on the code-bundle side's metadata.
785
+ assert.equal(bundle.imports.size, 0, `resources bundle ${resourcesPath} must have empty imports`)
786
+ assert.equal(bundle.entries.size, 0, `resources bundle ${resourcesPath} must have empty entries`)
787
+ for (const [file, format] of bundle.formats) {
788
+ assert.ok(Bundle.isResourceFormat(format),
789
+ `resources bundle ${resourcesPath} declares non-resource format='${format}' for ${file}`)
790
+ }
791
+ this.#mergeBundleMetadata(bundle, { lockfileLoaded })
792
+ for (const [file, content] of bundle.sources) {
793
+ this.resources.set(file, content)
794
+ }
795
+ // Union formats: conflict-free (bundleFile carries code formats, this one carries
796
+ // resource formats -- the file sets must be disjoint).
797
+ for (const [file, format] of bundle.formats) {
798
+ const existing = this.formats.get(file)
799
+ assert.ok(existing === undefined || existing === format,
800
+ `format conflict for ${file}: bundleFile declares '${existing}', resourcesBundleFile declares '${format}'`)
801
+ this.formats.set(file, format)
802
+ }
803
+ if (this.config.frozenBundle) {
804
+ // Extend the frozen snapshot. bundleFile's path may not have populated these
805
+ // (resources-only deployments are legal -- only the resources file exists),
806
+ // so initialize lazily; #bundleSources may stay null in that case, which the
807
+ // post-discovery invariant check accepts because #bundleResources is set.
808
+ if (this.#bundleResources === null) this.#bundleResources = new Set()
809
+ if (this.#bundleFormats === null) this.#bundleFormats = new Map()
810
+ if (this.#bundleImports === null) this.#bundleImports = objectToMaps(fileMapToObject(this.imports))
811
+ if (this.#bundleSources === null) this.#bundleSources = new Set(this.sources.keys())
812
+ for (const f of bundle.sources.keys()) this.#bundleResources.add(f)
813
+ for (const [f, fmt] of bundle.formats) this.#bundleFormats.set(f, fmt)
814
+ }
815
+ }
816
+
817
+ // Verify one resolution edge against an attestation map (`source`: a loaded
818
+ // lockfile, or a frozen bundle's own recorded imports). The final resolution
819
+ // is what matters, not how the edge is keyed: the conditions key is matched
820
+ // exactly first; on a miss the edge is accepted only when every condition set
821
+ // the attestation records for that (parent, specifier) agrees on the same
822
+ // target -- this lets a static `stasis bundle` artifact (edges under '*')
823
+ // validate against a runtime-generated attestation (precise condition sets),
824
+ // and vice versa, while a claim over a condition-divergent attestation stays
825
+ // fatal: either target would be served under conditions where the other is
826
+ // the attested resolution. Unknown edges are fatal unless the caller opts out
827
+ // (see addImport's node_modules-scope carve-out).
828
+ #assertAttestedResolution(attestation, conditions, parent, specifier, file, { what, source = 'lockfile', tolerateUnknown = false }) {
829
+ const edge = `'${specifier}' from ${parent} (${conditions})`
830
+ let attested = attestation.get(conditions)?.get(parent)?.get(specifier)
831
+ if (attested === undefined) {
832
+ const targets = new Set()
833
+ for (const [, parents] of attestation) {
834
+ const target = parents.get(parent)?.get(specifier)
835
+ if (target !== undefined) targets.add(target)
836
+ }
837
+ if (targets.size === 0 && tolerateUnknown) return
838
+ assert.ok(targets.size > 0, `${what} resolution ${edge} is not attested by the ${source}`)
839
+ assert.ok(targets.size === 1, `${what} resolution ${edge} is attested inconsistently across condition sets in the ${source}`)
840
+ ;[attested] = targets
841
+ }
842
+ // A per-platform edge is a Map<platform, target>; compare it structurally -- a plain
843
+ // assert.equal is reference equality, so two identical Maps (the bundle's edge and the
844
+ // lockfile's) would never match. A flat string edge stays a plain ===; a Map-vs-string
845
+ // (e.g. a per-platform attestation vs a single observed runtime target) is a mismatch.
846
+ const matches = file instanceof Map && attested instanceof Map
847
+ ? file.size === attested.size && [...file].every(([platform, target]) => attested.get(platform) === target)
848
+ : file === attested
849
+ assert.ok(matches, `${what} resolution ${edge} mismatches the ${source}`)
850
+ }
851
+
852
+ // Verify one file's loader format against an attestation map (`source`: a
853
+ // loaded lockfile, or a frozen bundle's own recorded formats). Callers only
854
+ // invoke this for files that must be attested (the attestation is a superset
855
+ // of any bundle, and on the disk path the call is gated to the hash-attested
856
+ // zone), so an unattested file means a forged/extra entry and is fatal.
857
+ #assertAttestedFormat(attestation, file, format, { what, source = 'lockfile' }) {
858
+ const attested = attestation.get(file)
859
+ assert.ok(attested !== undefined, `${what} format for ${file} is not attested by the ${source}`)
860
+ assert.equal(format, attested, `${what} format for ${file} mismatches the ${source}`)
861
+ }
862
+
863
+ assertEntry(url) {
864
+ // Skipped silently when no entries info is available (v0 bundle + lock=none/ignore).
865
+ // v1 bundles in full scope are required to declare at least one entry at parse time,
866
+ // so this fallback only ever triggers for the legacy path.
867
+ if (this.entries.size === 0) return
868
+ const file = this.#canonicalFile(url)
869
+ assert.ok(this.entries.has(file), `Unknown entry point: ${file}`)
870
+ }
871
+
872
+ // The one preload (top-level) State, or undefined. Scans the process-wide registry
873
+ // (shared across stasis-core copies) for the member flagged isPreload.
874
+ static get preload() {
875
+ for (const state of liveStates()) if (state.isPreload) return state
876
+ return undefined
877
+ }
878
+
879
+ // True iff this is THE preload (top-level) State. Public so State.preload can identify
880
+ // it even when this State came from a different stasis-core copy.
881
+ get isPreload() {
882
+ return this.#isPreload
883
+ }
884
+
885
+ // The label under which this State claims `canonical` as a write target, or undefined.
886
+ // Public so #claimWritePath's collision scan can consult a State from another copy.
887
+ claimedWritePathLabel(canonical) {
888
+ return this.#claims.get(canonical)
889
+ }
890
+
891
+ // Claim a write target, refusing a path another live State (in ANY copy) already
892
+ // claims. Canonicalize so `./x` / `x` / symlinks compare equal. Scans the process-wide
893
+ // registry, so collisions are caught across copies and without a preload. Intra-State
894
+ // collisions are caught earlier by Config (#checkInvariants), so this only fires
895
+ // cross-State. The claim is recorded on this instance; it becomes visible to later
896
+ // States once this one is added to liveStates() at the end of construction.
897
+ #claimWritePath(label, value) {
898
+ if (!value) return
899
+ const canonical = canonicalizePath(value)
900
+ for (const other of liveStates()) {
901
+ const owner = other.claimedWritePathLabel(canonical)
902
+ assert.ok(owner === undefined, `${label} '${value}' is already claimed by ${owner} of another live State`)
903
+ }
904
+ this.#claims.set(canonical, label)
905
+ }
906
+
907
+ // This State's stasis-core version. Public so a child (sidecar) can verify it
908
+ // exactly matches its parent's even when the two are different module copies
909
+ // sharing the process-wide registry (see the constructor's parent branch).
910
+ get version() {
911
+ return VERSION
912
+ }
913
+
914
+ // The slice of parent state a child (sidecar) inherits. Exposed as a PUBLIC method
915
+ // (rather than the child reading the parent's private fields) so a sidecar from a
916
+ // different-but-version-matched stasis-core copy -- a bundle carrying its own
917
+ // stasis-core, whose plugin sidecars the outer loader's preload -- can read it across
918
+ // the class brand. Only ever called by the sidecar constructor, after its version
919
+ // assert; the exact-version match guarantees these shapes are compatible.
920
+ sidecarInheritance() {
921
+ return {
922
+ preloadRoot: this.#preloadRoot,
923
+ lockImports: this.#lockImports,
924
+ lockFormats: this.#lockFormats,
925
+ lockfileLoaded: this.#lockfileLoaded,
926
+ }
927
+ }
928
+
929
+ // Register a WRITE-mode child (sidecar) so this parent's unified lockData unions its
930
+ // imports/formats (and attestedBySidecar sees its captures). Public (not a direct
931
+ // `#sidecars.add`) for the same cross-copy reason as sidecarInheritance: the call runs
932
+ // on the parent, touching the parent's own #sidecars, so it works even when the sidecar
933
+ // is a foreign-copy instance.
934
+ registerSidecar(sidecar) {
935
+ this.#sidecars.add(sidecar)
936
+ }
937
+
938
+ // Register a LOAD-mode child as a read-only family member: getFs*Family serves bundle
939
+ // bytes from it (a --fs read at load of a file the sidecar carries) but, unlike
940
+ // registerSidecar, it never enters #mergedImports/#mergedFormats, so a load-mode sidecar
941
+ // contributes no resolution edges or formats (the lockfile's trust-bearing content) to the
942
+ // unified lockfile. Public for the same cross-copy reason as registerSidecar.
943
+ registerReadSidecar(sidecar) {
944
+ this.#readSidecars.add(sidecar)
945
+ }
946
+
947
+ absolute(url) {
948
+ const absolute = fileURLToPath(url)
949
+ assert.equal(pathToFileURL(absolute).toString(), url)
950
+ assert.equal(absolute, resolve(absolute))
951
+ return absolute
952
+ }
953
+
954
+ relative(absolute) {
955
+ assert.ok(absolute)
956
+ const file = relative(this.root, absolute)
957
+ assert.ok(!file.startsWith('..'))
958
+ return file
959
+ }
960
+
961
+ // A file reached under node_modules whose REAL path lies outside any
962
+ // node_modules is a workspace source linked into node_modules (pnpm links a
963
+ // workspace dependency in via a symlink). Canonicalize such a URL to its real
964
+ // path so it is recorded/looked up as a *source*, not a dependency -- and thus
965
+ // excluded from a node_modules-scope bundle. Everything else is returned
966
+ // untouched: plain sources, real dependencies, and node_modules -> node_modules
967
+ // links (e.g. pnpm's `.pnpm` store) keep their original path.
968
+ #canonical(url) {
969
+ const absolute = this.absolute(url)
970
+ const file = relative(this.root, absolute)
971
+ if (file.startsWith('..') || !splitNodeModulesPath(file)) return { url, absolute }
972
+ let real
973
+ try {
974
+ real = realpathSync(absolute)
975
+ } catch {
976
+ return { url, absolute }
977
+ }
978
+ if (real === absolute) return { url, absolute } // not a symlink
979
+ const realFile = relative(this.root, real)
980
+ // Outside the root, or still inside some node_modules (a real dependency,
981
+ // e.g. pnpm's `.pnpm` store): leave the recorded path unchanged.
982
+ if (realFile.startsWith('..') || splitNodeModulesPath(realFile)) return { url, absolute }
983
+ return { url: pathToFileURL(real).toString(), absolute: real }
984
+ }
985
+
986
+ // The canonical project-relative path a URL is recorded/looked up under.
987
+ #canonicalFile(url) {
988
+ return this.relative(this.#canonical(url).absolute)
989
+ }
990
+
991
+ // True when `url` resolves (through any workspace symlink) to a file under
992
+ // node_modules -- i.e. a bundled dependency -- as opposed to a workspace source
993
+ // linked into node_modules (which #canonical records as a source). The loader
994
+ // hooks gate on this rather than a raw `/node_modules/` substring, so a
995
+ // symlinked workspace source is read from disk / resolved by Node instead of
996
+ // being served from a node_modules-scope bundle that deliberately omits it.
997
+ // Tolerant: a URL it can't canonicalize (non-file, outside root) is treated as
998
+ // not-a-dependency, so the hook falls back to Node's default handling.
999
+ inNodeModules(url) {
1000
+ let file
1001
+ try {
1002
+ file = this.#canonicalFile(url)
1003
+ } catch {
1004
+ return false
1005
+ }
1006
+ return splitNodeModulesPath(file) !== null
1007
+ }
1008
+
1009
+ // Nearest package.json at or above a directory, for addFsDir (`stasis run --fs`
1010
+ // readdir captures). Replaces findPackageJSON, which is unreliable for a directory
1011
+ // URL (see #locateModule). Walks up using the real fs (the destructured existsSync
1012
+ // snapshot), bounded by the project root -- which is always an existing-package.json
1013
+ // dir, so an in-root directory always resolves. Returns an absolute package.json path.
1014
+ #nearestPackageJsonFor(dirAbsolute) {
1015
+ let dir = dirAbsolute
1016
+ while (true) {
1017
+ const candidate = join(dir, 'package.json')
1018
+ if (existsSync(candidate)) return candidate
1019
+ if (dir === this.root) break // checked the root's package.json; never escape root
1020
+ const parent = dirname(dir)
1021
+ if (parent === dir) break // filesystem root
1022
+ dir = parent
1023
+ }
1024
+ // Unreachable in practice: state.root is resolved to a dir that has package.json.
1025
+ assert.fail(`no package.json at or above directory ${this.relative(dirAbsolute)}`)
1026
+ }
1027
+
1028
+ // Canonicalize `url` and resolve the package bucket that owns it, registering the
1029
+ // module (name/version, `npm` ecosystem under node_modules) on first sight. Shared
1030
+ // by addFile (code/resource) and addFsDir (directory captures): everything here is
1031
+ // independent of a file's bytes or loader format, so both reuse it. Returns the
1032
+ // canonical absolute path, the project-relative `file`, the bucket `dir`/`module`,
1033
+ // and the nearest package `type` (for addFile's extension inference).
1034
+ //
1035
+ // `directory: true` (addFsDir): the url names a directory, not a file. Node's
1036
+ // findPackageJSON is unreliable for a directory URL -- depending on Node version
1037
+ // it returns the PARENT's package.json, `undefined` (at a bucket root), or even a
1038
+ // `node_modules/` DIRECTORY path, which readPackageJSON would then read as a file
1039
+ // and throw EISDIR. So for a directory we walk up to the nearest package.json
1040
+ // ourselves (#nearestPackageJsonFor), which is correct on every Node version.
1041
+ #locateModule(url, { directory = false } = {}) {
1042
+ // Canonicalize first: a workspace source linked into node_modules is recorded
1043
+ // under its real (non-node_modules) path so it classifies as a source.
1044
+ const canonical = this.#canonical(url)
1045
+ url = canonical.url
1046
+ const absolute = canonical.absolute
1047
+ assert.ok(existsSync(absolute))
1048
+ const file = this.relative(absolute)
1049
+
1050
+ const closestPkgAbsolute = directory ? this.#nearestPackageJsonFor(absolute) : findPackageJSON(url)
1051
+ const closestPkg = readPackageJSON(closestPkgAbsolute)
1052
+
1053
+ const closestType = closestPkg.type
1054
+ assert.ok(closestType === undefined || closestType === 'module' || closestType === 'commonjs')
1055
+
1056
+ // findPackageJSON may land on a `{"type":"module"}`-style sub-bucket
1057
+ // marker that lacks name/version.
1058
+ const nmRoot = splitNodeModulesPath(file)?.dir
1059
+ let pkgAbsolute, name, version
1060
+ if (nmRoot) {
1061
+ pkgAbsolute = resolve(this.root, nmRoot, 'package.json')
1062
+ const rootPkg = pkgAbsolute === closestPkgAbsolute ? closestPkg : readPackageJSON(pkgAbsolute)
1063
+ ;({ name, version } = rootPkg)
1064
+ assert.ok(name, `Missing name in ${this.relative(pkgAbsolute)}`)
1065
+ assert.ok(version, `Missing version in ${this.relative(pkgAbsolute)}`)
1066
+ if (closestPkgAbsolute !== pkgAbsolute) {
1067
+ const message = `Inconsistent data between ${this.relative(closestPkgAbsolute)} and ${this.relative(pkgAbsolute)}`
1068
+ if (closestPkg.name !== undefined && closestPkg.name !== name) {
1069
+ // Allow fake module name subpaths: real module owns the prefix.
1070
+ // Npm publish wouldn't accept this anyway, so it's not a conflict.
1071
+ assert.ok(closestPkg.name.startsWith(`${name}/`), message)
1072
+ }
1073
+
1074
+ if (closestPkg.version !== undefined) assert.equal(closestPkg.version, version, message)
1075
+ }
1076
+ } else {
1077
+ pkgAbsolute = closestPkgAbsolute
1078
+ let json = closestPkg
1079
+ while (true) {
1080
+ if (json.name !== undefined && json.version !== undefined) {
1081
+ ;({ name, version } = json)
1082
+ break
1083
+ }
1084
+ assert.ok(Object.keys(json).every((k) => k === 'type'))
1085
+ const next = findPackageJSON('..', pathToFileURL(pkgAbsolute))
1086
+ assert.ok(
1087
+ next && !relative(this.root, next).startsWith('..'),
1088
+ `No package.json with name+version found for ${file}`
1089
+ )
1090
+ pkgAbsolute = next
1091
+ json = readPackageJSON(pkgAbsolute)
1092
+ }
1093
+ }
1094
+ const pkg = this.relative(pkgAbsolute)
1095
+ assert.ok(pkg === 'package.json' || pkg.endsWith('/package.json'))
1096
+ assert.equal(basename(pkg), 'package.json')
1097
+ const dir = dirname(pkg)
1098
+ if (nmRoot) assert.equal(dir, nmRoot)
1099
+ if (!this.modules.has(dir)) {
1100
+ // node_modules buckets are installed dependencies; tag them with the `npm`
1101
+ // ecosystem so consumers can tell deps from the workspace's own packages
1102
+ // without re-deriving it from the path. Workspace/top-level buckets (the
1103
+ // scope=full `sources`) carry no ecosystem.
1104
+ this.modules.set(dir, nmRoot
1105
+ ? { name, version, ecosystem: 'npm', files: Object.create(null) }
1106
+ : { name, version, files: Object.create(null) })
1107
+ }
1108
+ const module = this.modules.get(dir)
1109
+ assert.equal(module.name, name)
1110
+ assert.equal(module.version, version)
1111
+
1112
+ return { absolute, file, dir, module, closestType }
1113
+ }
1114
+
1115
+ // `resource: true` (alias: legacy `isBinary: true`) marks the file as a resource
1116
+ // rather than code. Its format is then derived from the bytes: 'resource' for valid
1117
+ // UTF-8 (stored raw, human-readable in the bundle) or 'resource:base64' for binary
1118
+ // (base64-encoded). Code files keep their inferred loader format.
1119
+ //
1120
+ // `inferFormat: false` records the bytes WITHOUT inferring or recording any loader
1121
+ // format (an existing recorded format, if any, is left intact). addFsFile uses it
1122
+ // for `.js`/`.ts`, whose module-vs-commonjs is Node's syntax-detection call (not
1123
+ // knowable from bytes): the module loader is the authority, so the fs-read capture
1124
+ // must not impose the legacy `commonjs` default and collide with a `module` the
1125
+ // loader records for the same file when it is both imported and read.
1126
+ addFile(url, { source, format, isEntry, isBinary, resource, inferFormat = true, reason = 'run', fsRead = false } = {}) {
1127
+ const asResource = resource === true || isBinary === true
1128
+ // A resource format must not arrive on the code path: 'resource' /
1129
+ // 'resource:base64' identifies asset payloads, which State stores in
1130
+ // `this.resources` with content-derived encoding (UTF-8 vs base64). A caller
1131
+ // who passes the format string without setting resource:true is asking for
1132
+ // a code file tagged as a resource -- nonsense, and exactly the kind of
1133
+ // accidental misclassification the per-file format design is meant to
1134
+ // catch. The reverse (resource:true with a non-resource format) is rejected
1135
+ // below when the content-derived format is checked against any explicit one.
1136
+ if (!asResource && Bundle.isResourceFormat(format)) {
1137
+ throw new Error(`addFile: format '${format}' requires resource: true`)
1138
+ }
1139
+ // A resource can't be an entry: entries name code loaded by Node (the module
1140
+ // graph's roots), and Bundle.parse / assertEntry validate them as code-shaped
1141
+ // paths. A resource entry would land in this.entries -> codeBundle.entries
1142
+ // (state.js's split-bundle getter), producing a v1 bundle whose entries refer
1143
+ // to files absent from its sources -- structurally valid but semantically
1144
+ // broken, and the kind of misclassification that's silent at capture time and
1145
+ // surfaces opaquely at the loader's NODEJS_FORMATS gate later.
1146
+ if (asResource && isEntry) {
1147
+ throw new Error(`addFile: a resource can't be an entry (resource:true + isEntry:true)`)
1148
+ }
1149
+ // Canonicalize + bucket by the owning package (shared with addFsDir).
1150
+ const { absolute, file, dir, module, closestType } = this.#locateModule(url)
1151
+
1152
+ // A code file can NEVER be recorded as a resource. `resources` -- the only gate
1153
+ // that admits an asset payload -- rejects code extensions outright (see
1154
+ // parseResourcesOption), so a resource:true call for a code extension means a
1155
+ // capture path bypassed that gate. That is exactly how an fs.readFileSync of a
1156
+ // `.jsx` got tagged 'resource', desyncing the unified lockfile (resource) from
1157
+ // the bundle (code) until it surfaced as an opaque format mismatch at load. Fail
1158
+ // at the recording site, where the cause is obvious, instead.
1159
+ if (asResource && CODE_EXTENSIONS.has(extname(file).slice(1).toLowerCase())) {
1160
+ throw new Error(`addFile: a code file can't be recorded as a resource: ${file}`)
1161
+ }
1162
+
1163
+ // Resources don't get a loader format inferred from extension/package type --
1164
+ // their format ('resource' / 'resource:base64') is chosen by content below.
1165
+ // inferFormat:false (addFsFile for .js/.ts) skips inference entirely.
1166
+ if (!asResource && inferFormat) {
1167
+ const extToFormat = {
1168
+ __proto__: null,
1169
+ '.json': 'json',
1170
+ '.mjs': 'module',
1171
+ '.cjs': 'commonjs',
1172
+ '.mts': 'module-typescript',
1173
+ '.cts': 'commonjs-typescript',
1174
+ }
1175
+ if (closestType !== undefined) {
1176
+ extToFormat['.js'] = closestType
1177
+ extToFormat['.ts'] = `${closestType}-typescript`
1178
+ }
1179
+ const inferredFormat = extToFormat[extname(file)]
1180
+ if (inferredFormat !== undefined) {
1181
+ if (format != null) assert.equal(format, inferredFormat)
1182
+ else format = inferredFormat
1183
+ } else if (format == null) {
1184
+ // No `type` in the nearest package.json: Node decides .js/.ts by
1185
+ // module-syntax detection, so either variant is legitimate and the
1186
+ // caller's reported format wins. When no format was provided at all
1187
+ // (e.g. bundler plugins, whose afterResolve/onLoad pass none), defer to
1188
+ // a format already recorded for this file THIS session before falling
1189
+ // back to the legacy commonjs default. The runtime loader records Node's
1190
+ // authoritative module/commonjs choice (hooks.js's load hook), so a
1191
+ // later no-format capture of the same file must KEEP a known `module`
1192
+ // rather than re-default it to commonjs -- which would both mis-attest
1193
+ // the bundle and collide at the noupsert below (and, for a bundler
1194
+ // sidecar whose formats merge into the parent's unified lockfile, at
1195
+ // #mergedFormats). A sidecar's loader records land in the parent's
1196
+ // formats, so consult it too. Only an extension-appropriate code format
1197
+ // is reused; a stale resource tag from a conflicting prior capture falls
1198
+ // through to the default so the conflict still surfaces at noupsert.
1199
+ const variants = {
1200
+ __proto__: null,
1201
+ '.js': ['commonjs', 'module'],
1202
+ '.ts': ['commonjs-typescript', 'module-typescript'],
1203
+ }[extname(file)]
1204
+ const known = this.formats.get(file) ?? this.#parent?.formats.get(file)
1205
+ format = variants?.includes(known) ? known : variants?.[0]
1206
+ }
1207
+ }
1208
+
1209
+ let sourceFromDisk = false
1210
+ if (typeof source === 'string') {
1211
+ assert.ok(source.isWellFormed())
1212
+ } else {
1213
+ if (source === undefined || source === null) { source = readFileSync(absolute); sourceFromDisk = true }
1214
+ assert.ok(Buffer.isBuffer(source))
1215
+ if (!asResource) assert.ok(isUtf8(source), `File is not UTF-8: ${file}`)
1216
+ }
1217
+
1218
+ const buf = typeof source === 'string' ? Buffer.from(source) : source
1219
+ // Verify a CALLER-PROVIDED source against disk (the loader passes the bytes it is about to
1220
+ // execute; this catches a loader serving bytes that differ from the file on disk). When we
1221
+ // just read `source` from disk ourselves, that comparison is against the same read -- it is
1222
+ // tautological -- so skip the redundant second read.
1223
+ if (!sourceFromDisk) assert.deepStrictEqual(readFileSync(absolute), buf)
1224
+
1225
+ // Resource format is content-driven: raw UTF-8 stays 'resource' (don't base64
1226
+ // bytes that are already text); anything else is 'resource:base64'.
1227
+ if (asResource) {
1228
+ const derived = isUtf8(buf) ? 'resource' : 'resource:base64'
1229
+ if (format != null) assert.equal(format, derived, `resource format mismatch for ${file}`)
1230
+ format = derived
1231
+ }
1232
+
1233
+ if (isEntry) this.entries.add(file)
1234
+ const integrity = sha512integrity(source)
1235
+ noupsert(this.hashes, file, integrity)
1236
+ if (this.config.childProcess) this.#observed.add(file) // only a child's shardSnapshot reads it; skip when the channel is off
1237
+ if (this.config.bundle && reason !== null) {
1238
+ this.#recordReason(reason, file) // provenance for the bundle's `reason` field (null = not a consumer observation, e.g. backfill)
1239
+ // Track HOW 'run' saw this file so #bundleReason can drop files run merely fs-READ after a
1240
+ // plugin attached that a plugin actually bundles (e.g. webpack+babel reading app source).
1241
+ if (reason === 'run') {
1242
+ if (!fsRead) this.#runImported.add(file)
1243
+ else if (this.#pluginAttached) this.#fsReadPostPlugin.add(file)
1244
+ }
1245
+ }
1246
+ const rel = relative(dir, file)
1247
+ assert.ok(!rel.startsWith('..'))
1248
+
1249
+ const inAttestedZone = dir.includes('node_modules') || this.config.full
1250
+ if (this.config.frozen && inAttestedZone) {
1251
+ assert.ok(Object.hasOwn(module.files, rel))
1252
+ }
1253
+
1254
+ // Frozen bundle: the observed bytes are checked against the bundle by the
1255
+ // noupsert into this.sources/this.resources below (both pre-seeded from the
1256
+ // bundle); here we close the set, rejecting a file the bundle never recorded
1257
+ // (mirrors the lockfile membership check above, anchored in the bundle). The
1258
+ // scope carve-out matches the lockfile's: node_modules scope doesn't attest
1259
+ // workspace files, so they aren't required to be in the bundle.
1260
+ if (this.config.frozenBundle && inAttestedZone) {
1261
+ const attested = asResource ? this.#bundleResources : this.#bundleSources
1262
+ assert.ok(attested?.has(file), `File not attested by the frozen bundle: ${file}`)
1263
+ }
1264
+
1265
+ // Frozen runs verify the format observed on disk against the attestation, the
1266
+ // way addImport verifies resolutions: the on-disk format is derived from the
1267
+ // file extension + nearest package.json `type`, and `type` is usually not
1268
+ // itself hash-attested, so flipping it recategorizes a hash-valid file
1269
+ // (commonjs<->module, or .js<->module-typescript) with no hash mismatch.
1270
+ // Checked against the lockfile and/or the frozen bundle, each anchored in its
1271
+ // own recorded formats. Gated to the same attested zone as the hash check
1272
+ // above (the node_modules-scope workspace is deliberately unattested, like
1273
+ // its bytes); files with no derived format (binary resources) are skipped via
1274
+ // `format != null`.
1275
+ if (this.config.frozen && this.#lockFormats !== null && format != null && inAttestedZone) {
1276
+ this.#assertAttestedFormat(this.#lockFormats, file, format, { what: 'observed', source: 'lockfile' })
1277
+ }
1278
+ if (this.config.frozenBundle && this.#bundleFormats !== null && format != null && inAttestedZone) {
1279
+ this.#assertAttestedFormat(this.#bundleFormats, file, format, { what: 'observed', source: 'frozen bundle' })
1280
+ }
1281
+
1282
+ // A WRITING lock capture (lock=add) must catch a format flip on already-attested bytes EARLY.
1283
+ // The lockfile baseline lives in #lockFormats -- separate from this.formats -- so addFile's own
1284
+ // noupsert below won't see the clash; it would otherwise surface only later at write(), when
1285
+ // #mergedFormats unions the baseline with the session formats and noupsert throws a bare
1286
+ // `Conflict for <file>` with no cause or remedy. Detect it here and throw a clear, actionable
1287
+ // error instead. (A frozen run rejects it via the format check above; lock=replace discards the
1288
+ // baseline, so #lockFormats is null; and bundle=add seeds the bundle's formats into this.formats,
1289
+ // so a bundle-side flip already conflicts at the noupsert below. Re-attest a genuine change with
1290
+ // --lock=replace / --bundle=replace.)
1291
+ if (this.config.writeLockfile && this.#lockFormats !== null && format != null && inAttestedZone) {
1292
+ const attested = this.#lockFormats.get(file)
1293
+ assert.ok(attested === undefined || attested === format,
1294
+ `format flip for ${file}: lockfile attests '${attested}', observed '${format}' (bytes unchanged) -- re-run with --lock=replace to re-attest`)
1295
+ }
1296
+
1297
+ if (!Object.hasOwn(module.files, rel)) module.files[rel] = integrity
1298
+ assert.equal(module.files[rel], integrity)
1299
+
1300
+ if (this.config.bundle) {
1301
+ if (asResource) {
1302
+ // 'resource' stores the raw UTF-8 string; 'resource:base64' stores base64.
1303
+ const content = format === 'resource:base64' ? buf.toString('base64') : buf.toString('utf8')
1304
+ noupsert(this.resources, file, content)
1305
+ } else {
1306
+ noupsert(this.sources, file, typeof source === 'string' ? source : source.toString())
1307
+ }
1308
+ }
1309
+
1310
+ if (format) noupsert(this.formats, file, format)
1311
+ }
1312
+
1313
+ // Record an `fs.readFileSync` capture (`stasis run --fs`, capture side). `source` is
1314
+ // the raw bytes (a Buffer). Classification is the SAME classifyExtension the bundler
1315
+ // plugins use (against this.config.resources), so the two capture paths can't disagree:
1316
+ // - 'code' (any CODE_EXTENSIONS file) → addFile infers the Node loader format from the
1317
+ // extension. .js/.ts defer it (inferFormat:false): module-vs-commonjs is Node's
1318
+ // syntax-detection call, the loader is the authority, and forcing a default here
1319
+ // would collide (noupsert) with the loader's record when a file is both imported and
1320
+ // fs-read. .jsx/.tsx are code but have no Node loader format, so none is imposed.
1321
+ // addFile asserts the bytes are UTF-8 -- a non-UTF-8 code file is malformed input,
1322
+ // refused there rather than silently re-tagged as a resource.
1323
+ // - 'resource' (an extension in the resources allowlist) → a 'resource'/'resource:base64'
1324
+ // payload, encoding chosen from the bytes.
1325
+ // - 'unknown' (neither code nor an allowlisted resource) → THROW. Recording it as a
1326
+ // resource would silently widen the attested set (the exact desync this guards); the
1327
+ // --fs hook catches the throw, warns, and writes nothing. Declare the extension in
1328
+ // `resources` (the --resources flag / EXODUS_STASIS_RESOURCES / a plugin's resources
1329
+ // option) or stop reading it.
1330
+ // Routing through addFile means a file that is BOTH imported and fs-read lands in one
1331
+ // consistent, deduped entry, hashed and bucketed exactly like every other file.
1332
+ addFsFile(url, source) {
1333
+ assert.ok(Buffer.isBuffer(source), 'addFsFile requires a Buffer source')
1334
+ const path = fileURLToPath(url)
1335
+ const kind = classifyExtension(path, this.config.resources)
1336
+ if (kind === 'resource') {
1337
+ this.addFile(url, { source, resource: true, fsRead: true })
1338
+ return
1339
+ }
1340
+ const ext = extname(path).toLowerCase()
1341
+ if (kind === 'unknown') {
1342
+ throw new Error(
1343
+ `addFsFile: ${path} is neither code nor a declared resource; ` +
1344
+ `add its extension or filename to the resources allowlist or stop reading it`
1345
+ )
1346
+ }
1347
+ this.addFile(url, { source, inferFormat: ext !== '.js' && ext !== '.ts', fsRead: true })
1348
+ }
1349
+
1350
+ // Record an `fs.readdirSync(path)` capture (single-arg form only). The listing is
1351
+ // SORTED so the attested content is reproducible regardless of the OS's directory
1352
+ // order, JSON-serialized, and stored as a 'directory'-format payload -- a
1353
+ // resource-like file whose integrity (sha512 over the JSON text) lands in the
1354
+ // lockfile just like any other content. Buckets/dedups via #locateModule like
1355
+ // addFile; the directory's own project-relative path is the key (a readdir of a
1356
+ // module root keys the listing at the bucket itself -- see moduleFileKey).
1357
+ addFsDir(url, names) {
1358
+ assert.ok(Array.isArray(names) && names.every((n) => typeof n === 'string'),
1359
+ 'addFsDir requires an array of string names')
1360
+ const { file, dir, module } = this.#locateModule(url, { directory: true })
1361
+ const content = JSON.stringify(names.toSorted())
1362
+ const format = 'directory'
1363
+ const integrity = sha512integrity(content)
1364
+ noupsert(this.hashes, file, integrity)
1365
+ if (this.config.childProcess) this.#observed.add(file) // only a child's shardSnapshot reads it; skip when the channel is off
1366
+ // Directory captures come only from the loader's --fs, and a plugin never records a readdir
1367
+ // listing (plugins only addFile), so a directory key is never in #bundleReason's pluginFiles
1368
+ // and can never be dropped from 'run' -- no need to track it in #fsReadPostPlugin.
1369
+ if (this.config.bundle) this.#recordReason('run', file)
1370
+ const rel = relative(dir, file)
1371
+ assert.ok(!rel.startsWith('..'))
1372
+
1373
+ // Frozen attestation, mirroring addFile: in the attested zone the listing must
1374
+ // already be recorded (closed set) and its format/integrity must match.
1375
+ const inAttestedZone = dir.includes('node_modules') || this.config.full
1376
+ if (this.config.frozen && inAttestedZone) {
1377
+ assert.ok(Object.hasOwn(module.files, rel))
1378
+ }
1379
+ if (this.config.frozenBundle && inAttestedZone) {
1380
+ assert.ok(this.#bundleResources?.has(file), `Directory not attested by the frozen bundle: ${file}`)
1381
+ }
1382
+ if (this.config.frozen && this.#lockFormats !== null && inAttestedZone) {
1383
+ this.#assertAttestedFormat(this.#lockFormats, file, format, { what: 'observed', source: 'lockfile' })
1384
+ }
1385
+ if (this.config.frozenBundle && this.#bundleFormats !== null && inAttestedZone) {
1386
+ this.#assertAttestedFormat(this.#bundleFormats, file, format, { what: 'observed', source: 'frozen bundle' })
1387
+ }
1388
+
1389
+ if (!Object.hasOwn(module.files, rel)) module.files[rel] = integrity
1390
+ assert.equal(module.files[rel], integrity)
1391
+ if (this.config.bundle) noupsert(this.resources, file, content)
1392
+ noupsert(this.formats, file, format)
1393
+ }
1394
+
1395
+ // Serve an `fs.readFileSync` from the bundle (`stasis run --fs`, bundle=load).
1396
+ // Returns the raw bytes as a Buffer, or undefined when the path was not captured
1397
+ // (the hook then falls back to a real disk read) or names a captured directory (a
1398
+ // readFileSync of a directory must fail, not return its listing). Decoding and the
1399
+ // lockfile hash check reuse getFile. Note a captured `.js`/`.ts` may have no
1400
+ // recorded format (see addFsFile); it's still served from `this.sources` by
1401
+ // presence -- the format only governs the module loader, not an fs read.
1402
+ getFsFile(url) {
1403
+ let file
1404
+ try { file = this.#canonicalFile(url) } catch { return undefined }
1405
+ if (this.formats.get(file) === 'directory') return undefined
1406
+ if (!this.sources.has(file) && !this.resources.has(file)) return undefined
1407
+ const { source } = this.getFile(url)
1408
+ return Buffer.isBuffer(source) ? source : Buffer.from(source, 'utf8')
1409
+ }
1410
+
1411
+ // Serve an `fs.readdirSync(path)` from the bundle: the sorted listing captured at
1412
+ // build time, or undefined when the path was not captured as a directory (the hook
1413
+ // falls back to a real disk read). Reuses getFile for the hash check.
1414
+ getFsDir(url) {
1415
+ let file
1416
+ try { file = this.#canonicalFile(url) } catch { return undefined }
1417
+ if (this.formats.get(file) !== 'directory') return undefined
1418
+ const { source } = this.getFile(url)
1419
+ const names = JSON.parse(source)
1420
+ assert.ok(Array.isArray(names), `corrupt directory listing for ${file}`)
1421
+ return names
1422
+ }
1423
+
1424
+ // Every ancestor directory implied by the bundle's recorded file/resource/directory
1425
+ // keys. A recorded `node_modules/dep/index.js` implies `node_modules/dep` and
1426
+ // `node_modules` (and the root, ''). Built once; load-mode immutable (see field).
1427
+ #impliedDirs() {
1428
+ if (this.#impliedDirIndex) return this.#impliedDirIndex
1429
+ const dirs = new Set([''])
1430
+ const add = (key) => {
1431
+ let prefix = ''
1432
+ const parts = key.split('/')
1433
+ for (let i = 0; i < parts.length - 1; i++) {
1434
+ prefix = prefix === '' ? parts[i] : `${prefix}/${parts[i]}`
1435
+ dirs.add(prefix)
1436
+ }
1437
+ }
1438
+ for (const key of this.sources.keys()) add(key)
1439
+ for (const key of this.resources.keys()) add(key)
1440
+ this.#impliedDirIndex = dirs
1441
+ return dirs
1442
+ }
1443
+
1444
+ // Classify a captured path for the `fs.lstatSync(x)/statSync(x)` .isFile()/.isDirectory()
1445
+ // shim (`stasis run --fs`, bundle=load): 'directory' for a readdir capture, 'file' for
1446
+ // a readFileSync capture, 'directory' for an ancestor directory implied by a recorded
1447
+ // file (e.g. `node_modules` when the bundle carries `node_modules/dep/index.js`), or
1448
+ // undefined when the path wasn't captured (the shim then falls back to a real on-disk
1449
+ // lstatSync). A directory lives in this.resources too, so the 'directory' format is
1450
+ // checked first; implied dirs are checked last so an explicit file/dir record wins.
1451
+ getFsStat(url) {
1452
+ let file
1453
+ try { file = this.#canonicalFile(url) } catch { return undefined }
1454
+ if (this.formats.get(file) === 'directory') return 'directory'
1455
+ if (this.sources.has(file) || this.resources.has(file)) return 'file'
1456
+ if (this.#impliedDirs().has(file)) return 'directory'
1457
+ return undefined
1458
+ }
1459
+
1460
+ // --fs <-> bundler-plugin coordination. A StasisWebpack/StasisEsbuild/StasisMetro SIDECAR
1461
+ // (its own bundleFile) captures the bundler's MODULE GRAPH into its OWN bundle. But the
1462
+ // bundler also reads every module's source through node:fs (webpack's inputFileSystem is
1463
+ // graceful-fs -> node:fs), which the --fs hook would otherwise RE-record into THIS
1464
+ // (preload/"main") bundle -- copying the whole graph into main and defeating the
1465
+ // bundleFile split. So --fs consults the family in two symmetric ways:
1466
+ // - CAPTURE (write mode): attestedBySidecar SKIPS recording a read a write-mode sidecar
1467
+ // already attests (the graph). Only reads no sidecar owns -- a babel plugin's manual
1468
+ // non-JS file reads, etc. -- are recorded into main.
1469
+ // - LOAD (load mode): getFs*Family SERVES a graph file from a load-mode sidecar's bundle
1470
+ // when main doesn't carry it (a program raw-reading a graph file via --fs at load).
1471
+ // The two paths consult DIFFERENT registries because a sidecar is a contributor XOR a
1472
+ // consumer (its bundle mode is the parent's): write-mode sidecars (#sidecars) feed the
1473
+ // lockfile; load-mode sidecars (#readSidecars) must not. readdir capture has no skip --
1474
+ // bundler plugins record files (addFile), never directory LISTINGS (addFsDir), so a
1475
+ // sidecar never owns a readdir result; a readdir is a genuine program read for main.
1476
+ //
1477
+ // attestedBySidecar consults #sidecars (write-mode contributors) and excludes THIS State
1478
+ // on purpose: a file only this State has stays subject to --fs's own dedup / byte-conflict
1479
+ // detection (addFsFile's noupsert); the skip applies solely to a file a *sidecar* carries.
1480
+ attestedBySidecar(url) {
1481
+ // `=== 'file'` (not merely `!== undefined`): the skip targets a FILE a sidecar carries (the
1482
+ // graph the bundler reads through node:fs). getFsStat also returns 'directory' for an implied
1483
+ // ancestor of a carried file; matching that would over-skip. Inert today (a readFileSync of a
1484
+ // directory throws EISDIR before this is consulted) but `=== 'file'` states the intent exactly.
1485
+ for (const s of this.#sidecars) if (s.getFsStat(url) === 'file') return true
1486
+ return false
1487
+ }
1488
+
1489
+ // getFs* variants that also consult load-mode sidecars (#readSidecars; this State first),
1490
+ // so a file/dir a sidecar carries in its bundle is served by --fs reads at load even when
1491
+ // main doesn't carry it. Only #readSidecars (not #sidecars): write-mode sidecars exist
1492
+ // only during capture, where --fs records rather than serves, so they're never consulted
1493
+ // here -- and they're kept out of the lockfile-contributing path regardless.
1494
+ getFsFileFamily(url) {
1495
+ const own = this.getFsFile(url)
1496
+ if (own !== undefined) return own
1497
+ for (const s of this.#readSidecars) { const v = s.getFsFile(url); if (v !== undefined) return v }
1498
+ return undefined
1499
+ }
1500
+
1501
+ getFsStatFamily(url) {
1502
+ const own = this.getFsStat(url)
1503
+ if (own !== undefined) return own
1504
+ for (const s of this.#readSidecars) { const v = s.getFsStat(url); if (v !== undefined) return v }
1505
+ return undefined
1506
+ }
1507
+
1508
+ getFsDirFamily(url) {
1509
+ const own = this.getFsDir(url)
1510
+ if (own !== undefined) return own
1511
+ // The sidecar loop is inert in practice: bundler plugins record files (addFile), never
1512
+ // directory LISTINGS (addFsDir), so a sidecar's bundle has no `directory` entry and
1513
+ // s.getFsDir always returns undefined. Kept for symmetry with the file/stat families.
1514
+ for (const s of this.#readSidecars) { const v = s.getFsDir(url); if (v !== undefined) return v }
1515
+ return undefined
1516
+ }
1517
+
1518
+ getFile(url) {
1519
+ // #canonicalFile -> relative() throws a bare assertion if the URL is outside
1520
+ // state.root (an absolute path that escapes the project). Wrap it so callers
1521
+ // get a contextual message instead of a stack pointing at relative()'s
1522
+ // assert.ok(!file.startsWith('..')).
1523
+ let file
1524
+ try { file = this.#canonicalFile(url) }
1525
+ catch (cause) { throw new Error(`stasis: file is outside the project root: ${url}`, { cause }) }
1526
+ const format = this.formats.get(file) // might be undefined e.g. for some bundlers
1527
+ // Resources live in this.resources, code in this.sources. Decode per the format:
1528
+ // 'resource:base64' is base64, 'resource' is raw UTF-8, code is raw text.
1529
+ // A missing entry throws with the URL in context so load-mode callers (the
1530
+ // bundler plugins, the run loader) don't have to pre-check existence -- the
1531
+ // single getFile call is the fail-closed gate.
1532
+ let source
1533
+ if (Bundle.isResourceFormat(format)) {
1534
+ source = this.resources.get(file)
1535
+ if (source === undefined) throw new Error(`stasis: file not attested in bundle: ${url}`)
1536
+ if (format === 'resource:base64') source = Buffer.from(source, 'base64')
1537
+ } else {
1538
+ source = this.sources.get(file)
1539
+ if (source === undefined) throw new Error(`stasis: file not attested in bundle: ${url}`)
1540
+ }
1541
+ // Without a lockfile the bundle is self-attesting: hashes would be derived
1542
+ // from the same source bytes we'd then verify, which is a tautology.
1543
+ if (this.config.useLockfile) assert.equal(this.hashes.get(file), sha512integrity(source))
1544
+ return { source, format }
1545
+ }
1546
+
1547
+ getFormat(url) {
1548
+ return this.formats.get(this.#canonicalFile(url))
1549
+ }
1550
+
1551
+ // Different conditions / import attributes can yield different URLs/formats for the same parent+specifier
1552
+ #conditionsKey(conditions, importAttributes) {
1553
+ const cond = conditions === '*' ? '*' : conditions.join(', ')
1554
+ assert.ok(!cond.includes('(') && !cond.includes(')'), 'conditions must not contain "(" or ")"')
1555
+ const attrs = importAttributes ? Object.entries(importAttributes) : []
1556
+ if (attrs.length === 0) return cond
1557
+ const sorted = Object.fromEntries(attrs.toSorted(([a], [b]) => (a < b ? -1 : 1)))
1558
+ return `${cond} (with: ${JSON.stringify(sorted)})`
1559
+ }
1560
+
1561
+ // A require()/import() given an already-resolved ABSOLUTE path arrives at the
1562
+ // resolve hook with that absolute path AS the specifier -- CJS
1563
+ // `require('/repo/node_modules/pkg/index.js')` is the common case (webpack's
1564
+ // loader-runner does `require(loader.path)`). Recorded verbatim, that
1565
+ // machine-specific absolute path becomes a resolution KEY in the lockfile and
1566
+ // bundle: non-portable, and unmatchable on any other machine. Once the target
1567
+ // is confirmed inside the project root, renormalize it to a path relative to
1568
+ // the IMPORTING FILE's directory -- the same shape a hand-written
1569
+ // `require('./x')` / `require('../../pkg/x')` has. The root check is only the
1570
+ // gate; the resulting key may itself contain '../' (going up from the importing
1571
+ // file), which is expected and fine as long as the target stayed inside root.
1572
+ //
1573
+ // Keying against the parent makes the key portable AND collision-free: it is
1574
+ // always '.'-prefixed, so it can never clash with a bare ('pkg') or
1575
+ // root-relative key, and an absolute path naming the same file as a relative
1576
+ // import unifies onto the identical key (same value -> noupsert agrees, no
1577
+ // throw). Bare/relative specifiers and file: URLs (handled separately by the
1578
+ // loader) pass through untouched; an absolute path that escapes the root has no
1579
+ // in-root relative form, so it's left as-is. Applied identically in addImport
1580
+ // (record) and getImport (lookup) so the key written and the key queried agree.
1581
+ #canonicalSpecifier(parentURL, specifier) {
1582
+ if (typeof specifier !== 'string' || !isAbsolute(specifier)) return specifier
1583
+ const fromRoot = relative(this.root, specifier)
1584
+ if (fromRoot === '' || fromRoot.startsWith('..')) return specifier // outside the project root
1585
+ const rel = relative(dirname(fileURLToPath(parentURL)), specifier)
1586
+ return rel.startsWith('.') ? rel : `./${rel}`
1587
+ }
1588
+
1589
+ addImport(parentURL, specifier, url, { conditions = '*', format, importAttributes } = {}) {
1590
+ if (conditions !== '*') assert.ok(Array.isArray(conditions))
1591
+ // Capture Node's require-condition set the first time we see a require()-context
1592
+ // edge: it carries 'require' and never 'import' (the import set carries 'import'
1593
+ // instead). Requiring the absence of 'import' also rejects an import edge a user
1594
+ // forced 'require' onto via --conditions. #backfillObservedResolutions reuses this
1595
+ // set to key native require.resolve() edges accurately instead of '*' (see field doc).
1596
+ if (this.#requireConditions === null && Array.isArray(conditions) &&
1597
+ conditions.includes('require') && !conditions.includes('import')) {
1598
+ this.#requireConditions = conditions
1599
+ }
1600
+ assert.ok(parentURL, 'addImport requires a parent (entries go through addFile)')
1601
+ const parent = this.#canonicalFile(parentURL)
1602
+ const file = this.#canonicalFile(url)
1603
+ specifier = this.#canonicalSpecifier(parentURL, specifier)
1604
+ const key = this.#conditionsKey(conditions, importAttributes)
1605
+
1606
+ // Frozen runs verify resolutions observed from disk against the lockfile,
1607
+ // mirroring the bundle-side check: byte hashes can't see a resolution
1608
+ // redirected to a *different* attested file (e.g. via an unattested
1609
+ // package.json `main` or a symlink). An edge the lockfile attests must
1610
+ // match in every scope. Unknown edges are fatal in full scope (the
1611
+ // attested file set is closed, so the traversed edge set should be too),
1612
+ // but tolerated for workspace parents in node_modules scope -- the
1613
+ // workspace is deliberately unattested there, so changed workspace code
1614
+ // may legitimately introduce new edges, including into pinned packages.
1615
+ const tolerateUnknown = !this.config.full && !parent.includes('node_modules')
1616
+ if (this.config.frozen && this.#lockImports !== null) {
1617
+ this.#assertAttestedResolution(this.#lockImports, key, parent, specifier, file, { what: 'observed', source: 'lockfile', tolerateUnknown })
1618
+ }
1619
+ // A frozen bundle attests resolutions the same way (every v1 bundle carries an
1620
+ // `imports` map, so #bundleImports is never null once one is loaded). Same
1621
+ // redirect protection and node_modules-scope carve-out, anchored in the bundle.
1622
+ if (this.config.frozenBundle && this.#bundleImports !== null) {
1623
+ this.#assertAttestedResolution(this.#bundleImports, key, parent, specifier, file, { what: 'observed', source: 'frozen bundle', tolerateUnknown })
1624
+ }
1625
+
1626
+ if (!this.imports.has(key)) this.imports.set(key, new Map())
1627
+ const imports = this.imports.get(key)
1628
+ if (!imports.has(parent)) imports.set(parent, new Map())
1629
+ const specifiers = imports.get(parent)
1630
+ noupsert(specifiers, specifier, file)
1631
+ if (format) noupsert(this.formats, file, format)
1632
+ }
1633
+
1634
+ getImport(parentURL, specifier, { conditions = '*', importAttributes } = {}) {
1635
+ if (conditions !== '*') assert.ok(Array.isArray(conditions))
1636
+ assert.ok(parentURL, 'getImport requires a parent') // matches addImport; #canonicalSpecifier needs it
1637
+ const parent = this.#canonicalFile(parentURL)
1638
+ specifier = this.#canonicalSpecifier(parentURL, specifier)
1639
+ const key = this.#conditionsKey(conditions, importAttributes)
1640
+ // Statically-built bundles (e.g. `stasis bundle src/entry.js`) resolve edges
1641
+ // offline and store them under the wildcard '*' key, since they can't
1642
+ // predict the exact condition set Node will pass at load time. The runtime
1643
+ // loader always records the precise conditions Node reported, so the
1644
+ // specific lookup wins when a runtime bundle is in play and only static
1645
+ // bundles take the wildcard fallback. Mismatches between the resolved file
1646
+ // for a given (parent, spec) under the two condition sets remain caller
1647
+ // territory -- the static bundle is authoritative for whichever conditions
1648
+ // the static resolver used.
1649
+ let file = this.imports.get(key)?.get(parent)?.get(specifier)
1650
+ if (file === undefined && key !== '*') {
1651
+ file = this.imports.get('*')?.get(parent)?.get(specifier)
1652
+ }
1653
+ if (file === undefined) {
1654
+ // The (key, parent, spec) and '*' lookups missed, but the edge may be recorded
1655
+ // under a DIFFERENT conditions bucket -- e.g. the esbuild plugin asks with
1656
+ // conditions='*' while a Node-loader-captured bundle keyed the edge under
1657
+ // 'require, node, ...'. resolveBundled scans every bucket for the recorded edge.
1658
+ if (this.config.loadBundle) {
1659
+ const abs = this.resolveBundled(parentURL, specifier)
1660
+ if (abs !== undefined) {
1661
+ const f = relative(this.root, abs)
1662
+ return { url: pathToFileURL(abs).toString(), format: this.formats.get(f) }
1663
+ }
1664
+ }
1665
+ // Throw with Node's ERR_MODULE_NOT_FOUND shape rather than asserting:
1666
+ // plain Node's resolver throws this when a bare or relative specifier
1667
+ // can't be found, and ESM dynamic-import callers commonly do
1668
+ // `try { await import(x) } catch (e) { if (e.code !== 'ERR_MODULE_NOT_FOUND') throw e }`.
1669
+ // A bare assertion produced an ERR_ASSERTION code that re-threw out of
1670
+ // those guards.
1671
+ const err = new Error(`Cannot find module '${specifier}' imported from ${parent}`)
1672
+ err.code = 'ERR_MODULE_NOT_FOUND'
1673
+ throw err
1674
+ }
1675
+ // A `stasis bundle --metro` artifact records a { platform: file } Map for an
1676
+ // edge that resolves differently per platform. Plain `stasis run --bundle=load`
1677
+ // has no platform context to pick one, so it can't serve such an edge -- fail
1678
+ // closed with a clear error rather than feeding a Map where a path is expected.
1679
+ if (typeof file !== 'string') {
1680
+ 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`)
1681
+ err.code = 'ERR_STASIS_PLATFORM_SPECIFIC'
1682
+ throw err
1683
+ }
1684
+ const url = pathToFileURL(resolve(this.root, file)).toString()
1685
+ const format = this.formats.get(file) // might be undefined e.g. for some bundlers
1686
+ return { url, format }
1687
+ }
1688
+
1689
+ // Resolve a CommonJS require() target to a bundled file, returning the absolute
1690
+ // path the loader should use (load() then serves its bytes from the bundle), or
1691
+ // undefined to defer to Node's native resolution.
1692
+ //
1693
+ // Node's CommonJS loader resolves require() through Module._resolveFilename, which
1694
+ // registerHooks does NOT intercept. When the ESM->CJS translator runs a CJS module we
1695
+ // served from the bundle (`import chalk from 'chalk'`, chalk being CJS), that module's
1696
+ // nested require()s take this native path and Node resolves them against disk -- so a
1697
+ // bundle is not self-contained for a CJS dependency graph once node_modules is
1698
+ // pruned/absent. The CJS-loader shim in hooks.js consults this to serve them from the
1699
+ // bundle instead.
1700
+ //
1701
+ // Returns the recorded edge for this (parent, specifier) under ANY conditions bucket --
1702
+ // a native require gives no conditions to key on, and divergent targets across buckets
1703
+ // are ambiguous, so we defer. EVERY require() edge is recorded at capture, including the
1704
+ // sibling requires Node's module cache used to hide from the resolve hook (the
1705
+ // Module._load shim in hooks.js observes them) -- so a miss here means the bundle simply
1706
+ // doesn't carry the target (an external), and we defer to Node rather than guess.
1707
+ resolveBundled(parentURL, specifier) {
1708
+ let parent
1709
+ try { parent = this.#canonicalFile(parentURL) } catch { return undefined }
1710
+ const spec = this.#canonicalSpecifier(parentURL, specifier)
1711
+ const matches = new Set()
1712
+ for (const [, byParent] of this.imports) {
1713
+ const file = byParent.get(parent)?.get(spec)
1714
+ if (file !== undefined) matches.add(file)
1715
+ }
1716
+ return matches.size === 1 ? resolve(this.root, [...matches][0]) : undefined
1717
+ }
1718
+
1719
+ // Union of the lockfile-attested resolutions and the live map (observed at
1720
+ // runtime and/or carried over from a loaded bundle), so a partial lock=add
1721
+ // run extends the recorded resolutions without dropping edges it didn't
1722
+ // reach. Conflicting targets for the same edge are fatal (add semantics,
1723
+ // same as hashes).
1724
+ #mergedImports() {
1725
+ const merged = new Map()
1726
+ const mergeIn = (imports) => {
1727
+ for (const [conditions, byParent] of imports) {
1728
+ if (!merged.has(conditions)) merged.set(conditions, new Map())
1729
+ const mergedParents = merged.get(conditions)
1730
+ for (const [parent, specifiers] of byParent) {
1731
+ if (!mergedParents.has(parent)) mergedParents.set(parent, new Map())
1732
+ const mergedSpecifiers = mergedParents.get(parent)
1733
+ for (const [specifier, file] of specifiers) {
1734
+ noupsert(mergedSpecifiers, specifier, file)
1735
+ }
1736
+ }
1737
+ }
1738
+ }
1739
+ if (this.#lockImports) mergeIn(this.#lockImports)
1740
+ mergeIn(this.imports)
1741
+ // Union sidecars' imports too: a bundler-plugin's sidecar records the
1742
+ // webpack-graph edges into its own this.imports, and the lockfile must
1743
+ // attest those edges so a frozen run can verify them.
1744
+ for (const sidecar of this.#sidecars) mergeIn(sidecar.imports)
1745
+ return merged
1746
+ }
1747
+
1748
+ // Union of lockfile-attested and observed/bundle-served formats, same
1749
+ // append-only stance as #mergedImports: conflicting formats for one file are
1750
+ // fatal (noupsert). Sidecars' formats are unioned in for the same reason.
1751
+ #mergedFormats() {
1752
+ const merged = new Map()
1753
+ if (this.#lockFormats) for (const [file, format] of this.#lockFormats) merged.set(file, format)
1754
+ for (const [file, format] of this.formats) noupsert(merged, file, format)
1755
+ for (const sidecar of this.#sidecars) {
1756
+ for (const [file, format] of sidecar.formats) noupsert(merged, file, format)
1757
+ }
1758
+ return merged
1759
+ }
1760
+
1761
+ get lockData() {
1762
+ return new Lockfile({
1763
+ config: this.config.values,
1764
+ entries: this.entries,
1765
+ modules: this.modules,
1766
+ imports: this.#mergedImports(),
1767
+ formats: this.#mergedFormats(),
1768
+ }).serialize()
1769
+ }
1770
+
1771
+ // Pair each module's recorded file list with the corresponding content from
1772
+ // perFile (state.sources for code, state.resources for resources), dropping
1773
+ // modules with no content. Bundle.serialize* then groups them into sources/
1774
+ // modules buckets and writes the lockfile-shaped output.
1775
+ #bundleModules(perFile) {
1776
+ const modules = new Map()
1777
+ for (const [dir, info] of this.modules) {
1778
+ const files = {}
1779
+ for (const rel of Object.keys(info.files)) {
1780
+ const file = moduleFileKey(dir, rel)
1781
+ const content = perFile.get(file)
1782
+ if (content !== undefined) files[rel] = content
1783
+ }
1784
+ if (Object.keys(files).length > 0) {
1785
+ modules.set(dir, info.ecosystem === undefined
1786
+ ? { name: info.name, version: info.version, files }
1787
+ : { name: info.name, version: info.version, ecosystem: info.ecosystem, files })
1788
+ }
1789
+ }
1790
+ return modules
1791
+ }
1792
+
1793
+ // A bundler plugin instance has attached to this State (called from resolvePluginState at the
1794
+ // plugin's construction). Files this run merely fs-READS *after* this point that a plugin also
1795
+ // bundles are the plugin's modules, not run's -- see #bundleReason. Idempotent. Public so it
1796
+ // works across stasis-core copies (the plugin may be a foreign-copy instance), like
1797
+ // registerSidecar / sidecarInheritance.
1798
+ markPluginAttached() {
1799
+ this.#pluginAttached = true
1800
+ }
1801
+
1802
+ // Record which consumer (`reason`) observed `file`, for the bundle's informational `reason` map.
1803
+ #recordReason(reason, file) {
1804
+ let set = this.#reasonFiles.get(reason)
1805
+ if (set === undefined) this.#reasonFiles.set(reason, set = new Set())
1806
+ set.add(file)
1807
+ }
1808
+
1809
+ // Build the bundle's informational `reason` map, restricted to `bundledFiles` (this bundle's own
1810
+ // file set): { consumer: [files] } for each consumer that recorded at least one file in it.
1811
+ // Returned ONLY when more than one consumer contributed -- a single-consumer bundle (plain `run`,
1812
+ // or a standalone plugin) omits it. Never attested; purely for humans / tooling.
1813
+ #bundleReason(bundledFiles) {
1814
+ const inBundle = bundledFiles instanceof Set ? bundledFiles : new Set(bundledFiles)
1815
+ // Files some PLUGIN bundles (any consumer other than 'run'). A file run merely fs-READ (never
1816
+ // imported) after a plugin attached, that a plugin also bundles, is the plugin's module -- e.g.
1817
+ // webpack+babel reading app source through --fs to transform it -- so 'run' must not claim it.
1818
+ const pluginFiles = new Set()
1819
+ for (const [who, recorded] of this.#reasonFiles) {
1820
+ if (who === 'run') continue
1821
+ for (const file of recorded) pluginFiles.add(file)
1822
+ }
1823
+ const runOverclaims = (file) =>
1824
+ this.#fsReadPostPlugin.has(file) && !this.#runImported.has(file) && pluginFiles.has(file)
1825
+
1826
+ const reason = {}
1827
+ let consumers = 0
1828
+ // Sort consumer keys AND each file list, like every other map in the bundle (sortPaths, via
1829
+ // fileMapToObject etc.): the emitted JSON must be byte-reproducible across runs regardless of
1830
+ // loader-vs-plugin record order, else #emitBundle's compare-and-skip would see spurious diffs.
1831
+ for (const who of [...this.#reasonFiles.keys()].toSorted()) {
1832
+ const files = []
1833
+ for (const file of this.#reasonFiles.get(who)) {
1834
+ if (!inBundle.has(file)) continue
1835
+ if (who === 'run' && runOverclaims(file)) continue
1836
+ files.push(file)
1837
+ }
1838
+ if (files.length > 0) { reason[who] = files.toSorted(sortPaths); consumers += 1 }
1839
+ }
1840
+ return consumers > 1 ? reason : undefined
1841
+ }
1842
+
1843
+ get sourceBundle() {
1844
+ // One bundle holds both code and resources; merge the two content maps (their key
1845
+ // sets are disjoint -- a file is either code or a resource) and let `formats` tag
1846
+ // which is which. Resource payloads are already encoded per their format. The
1847
+ // disjointness invariant is enforced upstream in addFile via noupsert on
1848
+ // this.formats (a file's format is either a resource one or not, and cannot
1849
+ // change), so an overlap here would be a real bug -- assert it explicitly at
1850
+ // the merge site so the failure is local, not a silently-clobbered value.
1851
+ const contents = new Map(this.sources)
1852
+ for (const [file, content] of this.resources) {
1853
+ assert.ok(!contents.has(file), `state invariant: file ${file} in both sources and resources`)
1854
+ contents.set(file, content)
1855
+ }
1856
+ return new Bundle({
1857
+ config: this.config.values,
1858
+ entries: this.entries,
1859
+ modules: this.#bundleModules(contents),
1860
+ formats: this.formats,
1861
+ imports: this.imports,
1862
+ reason: this.#bundleReason(contents.keys()),
1863
+ })
1864
+ }
1865
+
1866
+ get sourceData() {
1867
+ return this.sourceBundle.serialize()
1868
+ }
1869
+
1870
+ // Split-bundle counterparts to `sourceBundle` / `sourceData`. Used by `write()`
1871
+ // when `config.resourcesBundleFile` is set so the on-disk layout matches a
1872
+ // bundle=load reader. Each is a standalone v1 Bundle (independently parseable);
1873
+ // metadata is partitioned, not duplicated -- the code half owns entries/imports
1874
+ // and code-format declarations, the resources half owns resource-format
1875
+ // declarations and the resource bytes. Both halves declare their per-dir
1876
+ // module identity (name/version) so each file is verifiable on its own.
1877
+ get codeBundle() {
1878
+ // Resource files don't appear in `this.sources` (addFile routes by format), so
1879
+ // restricting #bundleModules to `this.sources` automatically yields the code-only
1880
+ // view. Formats and modules are filtered to drop resource-only dirs/files.
1881
+ const codeFormats = new Map()
1882
+ for (const [file, format] of this.formats) {
1883
+ if (!Bundle.isResourceFormat(format)) codeFormats.set(file, format)
1884
+ }
1885
+ return new Bundle({
1886
+ config: this.config.values,
1887
+ entries: this.entries,
1888
+ modules: this.#bundleModules(this.sources),
1889
+ formats: codeFormats,
1890
+ imports: this.imports,
1891
+ reason: this.#bundleReason(this.sources.keys()),
1892
+ })
1893
+ }
1894
+
1895
+ get resourcesBundle() {
1896
+ const resourceFormats = new Map()
1897
+ for (const [file, format] of this.formats) {
1898
+ if (Bundle.isResourceFormat(format)) resourceFormats.set(file, format)
1899
+ }
1900
+ return new Bundle({
1901
+ config: this.config.values,
1902
+ // Resources bundle carries no entries / imports -- those belong to the code half.
1903
+ // Bundle.parse accepts an empty entries set when no code is present (the hasCode
1904
+ // check sees only resource-format files and waives the requirement).
1905
+ entries: new Set(),
1906
+ modules: this.#bundleModules(this.resources),
1907
+ formats: resourceFormats,
1908
+ imports: new Map(),
1909
+ reason: this.#bundleReason(this.resources.keys()),
1910
+ })
1911
+ }
1912
+
1913
+ // Record a capture-time native resolution (from the Module._resolveFilename
1914
+ // shim). Stored verbatim; #backfillObservedResolutions decides at write() which
1915
+ // to add. Last-write-wins per (parent, specifier) so duplicates collapse.
1916
+ observeResolution(parentURL, specifier, resolvedURL) {
1917
+ let byParent = this.#observedResolutions.get(parentURL)
1918
+ if (byParent === undefined) this.#observedResolutions.set(parentURL, (byParent = new Map()))
1919
+ byParent.set(specifier, resolvedURL)
1920
+ }
1921
+
1922
+ // Backfill resolution edges the live resolve hook never observed -- require.resolve()
1923
+ // (and CJS require()s that resolve natively) on Node versions where they bypass
1924
+ // the hook. Records BOTH kinds the hook missed:
1925
+ // - under-recorded require()s whose target the bundle carries (Node's module
1926
+ // cache hid the require() from the resolve hook -- another module loaded the
1927
+ // target first), and
1928
+ // - resolve-only edges whose target it does NOT carry: require.resolve() of a
1929
+ // module never loaded in-process (an optional-dependency probe, a forked-
1930
+ // worker child like worker-farm's, a .node addon). The resolution is real and
1931
+ // must be attested so the same require.resolve() returns the same path at
1932
+ // load; the file simply has no bytes -- require.resolve returns a path, load()
1933
+ // never runs for it, so getFile is never asked to serve it.
1934
+ // Guards:
1935
+ // - skip out-of-scope targets (mirroring #collectMissingImportedFiles) so a
1936
+ // node_modules-scope artifact doesn't attest workspace resolutions it isn't
1937
+ // responsible for; an in-bundle target is always in scope, so it's exempt.
1938
+ // (Targets escaping the root throw in #canonicalFile -> caught below.)
1939
+ // - only edges the hook didn't already record (dedup across all condition
1940
+ // buckets), so this never double-records a normal require().
1941
+ // Keyed under the observed require-condition set (#requireConditions) -- require()/
1942
+ // require.resolve() resolve under those conditions, not condition-free -- so a
1943
+ // native-resolve Node (where these edges land here) keys them the same way the
1944
+ // resolve hook keys them directly on newer Node. Any capture that does at least one
1945
+ // require() thus yields the same lockfile on every version; '*' only when the set was
1946
+ // never observed (a capture with no require() at all), which getImport/resolveBundled
1947
+ // still match via their wildcard fallback.
1948
+ #backfillObservedResolutions() {
1949
+ if (this.#observedResolutions.size === 0) return
1950
+ for (const [parentURL, specs] of this.#observedResolutions) {
1951
+ let parent
1952
+ try { parent = this.#canonicalFile(parentURL) } catch { continue }
1953
+ for (const [specifier, resolvedURL] of specs) {
1954
+ let file
1955
+ try { file = this.#canonicalFile(resolvedURL) } catch { continue }
1956
+ const bundled = this.sources.has(file) || this.resources.has(file)
1957
+ if (!bundled && !this.config.full && !this.inNodeModules(resolvedURL)) continue
1958
+ const spec = this.#canonicalSpecifier(parentURL, specifier)
1959
+ let recorded = false
1960
+ for (const [, byParent] of this.imports) {
1961
+ if (byParent.get(parent)?.get(spec) !== undefined) { recorded = true; break }
1962
+ }
1963
+ if (!recorded) this.addImport(parentURL, specifier, resolvedURL, { conditions: this.#requireConditions ?? '*' })
1964
+ }
1965
+ }
1966
+ }
1967
+
1968
+ write() {
1969
+ // Backfill observed (native Module._resolveFilename) resolutions BEFORE the
1970
+ // stasis-core BFS. On Node's native-resolve versions a resolve-only edge to a
1971
+ // stasis-core src/*.js submodule (e.g. require.resolve('@exodus/stasis-core/
1972
+ // prune') of a module never loaded) is added only here; running the BFS first
1973
+ // would compute its missing-set without that edge, never seed the file, and
1974
+ // ship a dangling edge with no bytes -- which a later lock=frozen replay then
1975
+ // rejects. Recording it first lets the BFS capture the bytes, matching what the
1976
+ // resolve-hook path already records in-line on newer Node. Order is otherwise
1977
+ // independent: the BFS doesn't read #observedResolutions, and observe-backfill's
1978
+ // `bundled` check sees files loaded during capture (already in this.sources)
1979
+ // regardless of when the BFS runs.
1980
+ this.#backfillObservedResolutions()
1981
+ this.#backfillBeforeWrite()
1982
+ // writeFileSync(join(this.root, FILE_CONFIG), this.config.json)
1983
+ // Sidecars never write the lockfile -- the parent owns it. They only emit their bundle.
1984
+ // A "sidecar" here is one sharing the parent's lockfile data structures; an independent
1985
+ // State with its own lockFile path (constructed via the no-parent code path) writes its
1986
+ // own lockfile to `config.lockFile` instead of the rootDir default.
1987
+ //
1988
+ // Per-artifact compare-and-skip: each output's serialized text is compared against the
1989
+ // cached previous text and the brotli + writeFileSync are both skipped when they match.
1990
+ // Critical for webpack/esbuild watch-mode rebuilds, where compiler.hooks.done fires on
1991
+ // every rebuild but the captured graph usually doesn't change. Without this, every
1992
+ // rebuild brotli-compresses (quality 11) and rewrites every output.
1993
+
1994
+ if (this.config.writeLockfile && !this.#parent) {
1995
+ const lockText = this.lockData
1996
+ if (lockText !== this.#lastLockData) {
1997
+ const lockPath = this.config.lockFile || join(this.root, FILE_LOCK)
1998
+ mkdirSync(dirname(lockPath), { recursive: true })
1999
+ writeFileSync(lockPath, lockText)
2000
+ this.#lastLockData = lockText
2001
+ }
2002
+ }
2003
+ if (this.config.writeBundle) {
2004
+ const sourcesPath = this.config.bundleFile || join(this.root, FILE_CODE)
2005
+ if (this.config.resourcesBundleFile) {
2006
+ // Split-bundle layout: code-only to bundleFile, resources-only to resourcesBundleFile.
2007
+ // Each is a standalone v1 Bundle (cross-check on load enforces shape). hasContent
2008
+ // gates per half so an empty half (no code / no resources) is dropped under replace
2009
+ // rather than written as an empty bundle -- see #emitBundle. sources/resources size
2010
+ // is the exact emptiness test: a code bundle's entries/imports are non-empty only
2011
+ // when sources are (every entry/edge parent is itself an addFile'd source).
2012
+ this.#lastCodeBundle = this.#emitBundle(
2013
+ sourcesPath, this.sources.size > 0, this.#lastCodeBundle, () => this.codeBundle.serialize())
2014
+ this.#lastResourcesBundle = this.#emitBundle(
2015
+ this.config.resourcesBundleFile, this.resources.size > 0, this.#lastResourcesBundle,
2016
+ () => this.resourcesBundle.serialize())
2017
+ } else {
2018
+ this.#lastUnifiedBundle = this.#emitBundle(
2019
+ sourcesPath, this.sources.size > 0 || this.resources.size > 0, this.#lastUnifiedBundle,
2020
+ () => this.sourceData)
2021
+ }
2022
+ }
2023
+ }
2024
+
2025
+ // Produce the lockfile-shaped snapshot of everything THIS process captured, for a child
2026
+ // process to hand back to the root (which never loaded what only the child loaded -- e.g.
2027
+ // a Metro transform worker loading babel.config.js + its babel preset/plugins). Runs the
2028
+ // same backfills write() runs so observed native (Module._resolveFilename) resolutions and
2029
+ // stasis-core internal edges are materialized first. Content is intentionally omitted: the
2030
+ // snapshot carries project-relative paths + the import graph + formats + entries, and the
2031
+ // root re-reads each file's bytes from disk when it replays via mergeShard().
2032
+ shardSnapshot() {
2033
+ this.#backfillObservedResolutions()
2034
+ this.#backfillBeforeWrite()
2035
+ // Forward ONLY what THIS process observed this run -- not the baseline it seeded at construction.
2036
+ // On a lock=add re-run the root seeds the same lockfile baseline (and a BUNDLE run seeds the
2037
+ // whole bundle graph), so re-shipping it would bloat every worker's shard (toward
2038
+ // MAX_SHARD_BYTES, past which mergeChildShards silently drops it) and make the root re-merge it
2039
+ // once per worker. #observed holds the files addFile/addFsDir recorded this run; modules, formats
2040
+ // AND imports are all filtered to it below. (Lockfile-seeded edges/formats live in
2041
+ // #lockImports/#lockFormats, but a bundle load seeds this.imports/this.formats DIRECTLY -- so we
2042
+ // filter explicitly rather than rely on which map holds the baseline.) Entries are dropped:
2043
+ // mergeShard never marks a merged file as an entry, and this.entries is itself seeded.
2044
+ const modules = new Map()
2045
+ for (const [dir, info] of this.modules) {
2046
+ const files = {}
2047
+ for (const rel of Object.keys(info.files)) {
2048
+ if (this.#observed.has(moduleFileKey(dir, rel))) files[rel] = info.files[rel]
2049
+ }
2050
+ if (Object.keys(files).length === 0) continue
2051
+ modules.set(dir, info.ecosystem === undefined
2052
+ ? { name: info.name, version: info.version, files }
2053
+ : { name: info.name, version: info.version, ecosystem: info.ecosystem, files })
2054
+ }
2055
+ // formats: only observed files. imports: only edges whose PARENT was observed -- a child adds an
2056
+ // edge solely from a file it loaded (addImport's parent is addFile'd -> in #observed), so its
2057
+ // session edges are kept while bundle-seeded edges (parent never loaded here) are dropped; the
2058
+ // root already attests those from its own seed, so dropping them loses nothing.
2059
+ const formats = new Map()
2060
+ for (const file of this.#observed) {
2061
+ const fmt = this.formats.get(file)
2062
+ if (fmt !== undefined) formats.set(file, fmt)
2063
+ }
2064
+ const imports = new Map()
2065
+ for (const [conditions, byParent] of this.imports) {
2066
+ let kept
2067
+ for (const [parent, specs] of byParent) {
2068
+ if (!this.#observed.has(parent)) continue
2069
+ if (kept === undefined) { kept = new Map(); imports.set(conditions, kept) }
2070
+ kept.set(parent, specs)
2071
+ }
2072
+ }
2073
+ return new Lockfile({
2074
+ config: this.config.values,
2075
+ entries: new Set(),
2076
+ modules,
2077
+ imports,
2078
+ formats,
2079
+ }).serialize()
2080
+ }
2081
+
2082
+ // Merge a child process's shardSnapshot() (a serialized lockfile) into this State, as if
2083
+ // this process had loaded/read those files itself: replay each file (addFile for code +
2084
+ // `--fs` resources, addFsDir for `--fs` directory captures -- re-reading bytes/listings from
2085
+ // disk to hash + classify) and addImport each recorded edge. This is how the root attests files and
2086
+ // edges that ONLY a forked child observed -- the child runs the loader and captures into
2087
+ // its own State but is blocked from writing, so without this its observations are lost.
2088
+ // Project-relative paths are shared across the process tree (same root); URLs are
2089
+ // reconstructed via resolve(this.root, file). Best-effort per record: a path gone from disk
2090
+ // (a transient temp module) or rejected by addFile/addImport (out of this run's scope) is
2091
+ // skipped rather than aborting the whole merge -- the root's own capture stays intact.
2092
+ mergeShard(lockText) {
2093
+ const lf = Lockfile.parse(lockText)
2094
+ // A shard must describe the SAME scope as this root (children inherit scope via env, so they
2095
+ // always agree). Defense-in-depth: a cross-scope shard is already signature-rejected upstream,
2096
+ // but a mismatch here would mean a malformed/foreign shard -- refuse it rather than merge.
2097
+ assert.equal(lf.config.scope, this.config.scope, `shard scope "${lf.config.scope}" != root scope "${this.config.scope}"`)
2098
+ // Files first (so addFile records bytes/format/module identity), then edges. Merged files
2099
+ // are NEVER marked entries: a forked child's "entry" is its fork-target main (e.g. a Metro
2100
+ // worker's bootstrap), not a declared entry of the ROOT build -- recording it as one would
2101
+ // corrupt the root's entries list. The child's lf.entries is therefore ignored here.
2102
+ for (const [dir, info] of lf.modules) {
2103
+ for (const rel of Object.keys(info.files)) {
2104
+ // moduleFileKey is the exact inverse of how the child bucketed the path -- in particular
2105
+ // it yields `dir` (no trailing slash) for a directory captured AT a bucket root (rel==='').
2106
+ const file = moduleFileKey(dir, rel)
2107
+ // Skip a file the root already attests -- its seeded lockfile baseline or its own capture
2108
+ // this run. A child only needs to contribute what the root didn't observe; re-reading an
2109
+ // already-recorded file from disk (per worker shard) is the dominant merge cost, and since
2110
+ // this loop adds to this.hashes, identical toolchain files from later workers skip too.
2111
+ // EXCEPTION: still carry a concrete code format the root LACKS. If the root fs-READ this
2112
+ // `.js`/`.ts` (addFsFile records the hash but NO format) while the child IMPORTED it as
2113
+ // `module`, dropping the format here would leave the lockfile format-less and make a later
2114
+ // frozen run -- where the file loads as a module -- reject the now-unattested format. Fall
2115
+ // through so addFile records (and validates) the format; the byte re-read is the only cost.
2116
+ if (this.hashes.has(file)) {
2117
+ const shardFormat = lf.formats?.get(file)
2118
+ if (shardFormat === undefined || (this.formats.get(file) ?? this.#lockFormats?.get(file)) !== undefined) continue
2119
+ }
2120
+ const absolute = resolve(this.root, file)
2121
+ const url = pathToFileURL(absolute).toString()
2122
+ const format = lf.formats?.get(file)
2123
+ try {
2124
+ if (format === 'directory') {
2125
+ // A child's `fs.readdirSync` capture (`--fs`): replay as a directory listing (addFile
2126
+ // rejects a directory). Re-read the listing from disk so the root's hash is
2127
+ // authoritative -- the same disk-is-truth stance as the byte re-reads below. Range-check
2128
+ // the path FIRST: addFsDir would reject a traversal, but only AFTER readdirSync already
2129
+ // ran on the forged out-of-root path, so a child-forged `..` key can't make us list it.
2130
+ const relFromRoot = relative(this.root, absolute)
2131
+ if (relFromRoot.startsWith('..') || isAbsolute(relFromRoot)) continue
2132
+ this.addFsDir(url, readdirSync(absolute))
2133
+ } else if (format === 'resource' || format === 'resource:base64') {
2134
+ // A child's `fs.readFileSync` capture of an asset: addFile needs resource:true for a
2135
+ // resource format. The exact 'resource' vs 'resource:base64' tag is content-derived, so
2136
+ // addFile re-derives it from the re-read bytes -- we don't pass it (and risk a spurious
2137
+ // mismatch), we just mark it a resource.
2138
+ this.addFile(url, { resource: true })
2139
+ } else if (format === undefined) {
2140
+ // Code file the child recorded with NO format -- it fs-READ a `.js`/`.ts` (or
2141
+ // `.jsx`/`.tsx`), where addFsFile defers module-vs-commonjs to the loader rather than
2142
+ // imposing one (Node's syntax-detection call). Replay the same way (inferFormat:false):
2143
+ // record the bytes but impose no format, so we don't bake in the legacy commonjs
2144
+ // default and collide -- at the frozen format check, or noupsert -- with the `module`
2145
+ // the loader records when that file is later imported. (Babel reading a worker's source
2146
+ // `.js` to transform it is exactly this case under `--fs --child-process`.)
2147
+ this.addFile(url, { inferFormat: false })
2148
+ } else {
2149
+ // Code file with a concrete loader format the child recorded (it imported the file, or
2150
+ // fs-read an unambiguous `.mjs`/`.cjs`/`.json`). Carry it: without it, a child-only ESM
2151
+ // `.js`/`.ts` under a no-`type` package would re-default to commonjs, and the subsequent
2152
+ // frozen run -- where the child re-loads it as module -- would reject the mismatch.
2153
+ // addFile still asserts the format agrees with an explicit package.json `type` when one
2154
+ // exists, so this can't smuggle a wrong format.
2155
+ this.addFile(url, { format })
2156
+ }
2157
+ } catch {
2158
+ // A file the child loaded but that's gone/unreadable here, or that addFile rejects
2159
+ // (e.g. an out-of-scope path under a different scope): skip it. The edge replay below
2160
+ // tolerates the resulting gap the same way.
2161
+ }
2162
+ }
2163
+ }
2164
+ if (lf.imports) {
2165
+ for (const [conditions, byParent] of lf.imports) {
2166
+ // Reverse #conditionsKey: '*' stays '*'; otherwise the key is a ', '-joined condition
2167
+ // list, optionally suffixed ' (with: {json})' for import attributes. Toolchain edges
2168
+ // (CJS require) carry no attributes; parse them when present so attributed edges merge
2169
+ // under the same key the child recorded.
2170
+ let condStr = conditions
2171
+ let importAttributes
2172
+ const withAt = conditions.indexOf(' (with: ')
2173
+ if (withAt !== -1) {
2174
+ condStr = conditions.slice(0, withAt)
2175
+ try { importAttributes = JSON.parse(conditions.slice(withAt + ' (with: '.length, -1)) } catch { /* leave undefined */ }
2176
+ }
2177
+ const cond = condStr === '*' ? '*' : condStr.split(', ')
2178
+ for (const [parent, specs] of byParent) {
2179
+ const parentURL = pathToFileURL(resolve(this.root, parent)).toString()
2180
+ for (const [specifier, file] of specs) {
2181
+ const url = pathToFileURL(resolve(this.root, file)).toString()
2182
+ try {
2183
+ this.addImport(parentURL, specifier, url, { conditions: cond, importAttributes })
2184
+ } catch {
2185
+ // Same best-effort stance as addFile above.
2186
+ }
2187
+ }
2188
+ }
2189
+ }
2190
+ }
2191
+ }
2192
+
2193
+ // Emit one bundle artifact, returning its new "last serialized" cache value.
2194
+ // - empty (hasContent === false) under bundle=replace: this run carries nothing for
2195
+ // this artifact, so DELETE any file at `path` rather than write an empty bundle. A
2196
+ // `bundle=replace` run is authoritative -- it deliberately ignores the prior on-disk
2197
+ // bundle (the constructor skips loading it), so a stale file the run didn't produce
2198
+ // must not survive as the "old one". Returning null resets the cache so a later
2199
+ // non-empty write() (watch-mode rebuild) re-emits the file.
2200
+ // - otherwise (has content, OR empty under add): serialize and write, skipping the
2201
+ // brotli + writeFileSync when the text is byte-identical to the last write (the
2202
+ // watch-mode compare-and-skip this cache exists for). add keeps emitting an empty
2203
+ // bundle so the file always exists -- only replace prunes a not-written artifact.
2204
+ #emitBundle(path, hasContent, lastText, serialize) {
2205
+ if (!hasContent && this.config.replaceBundle) {
2206
+ rmSync(path, { force: true })
2207
+ return null
2208
+ }
2209
+ const text = serialize()
2210
+ if (text !== lastText) {
2211
+ mkdirSync(dirname(path), { recursive: true })
2212
+ writeFileSync(path, brotliCompressSync(text, brotliOptions()))
2213
+ return text
2214
+ }
2215
+ return lastText
2216
+ }
2217
+
2218
+ get parent() {
2219
+ return this.#parent
2220
+ }
2221
+
2222
+ // Capture stasis-core's own files + internal edges that the live hooks missed.
2223
+ // When app code (or a bundler plugin) imports a stasis-core module, Node had
2224
+ // it cached from preload-time -- BEFORE install() registered our hooks -- so
2225
+ // the resolve hook records the edge but the load hook never fires, leaving
2226
+ // addFile / addImport blind to the file's bytes AND its outgoing edges. This
2227
+ // BFS, scoped strictly to the `<root>/.../@exodus/stasis-core/src/<name>.js`
2228
+ // shape, walks the graph starting from missing imports targets + already-
2229
+ // captured stasis-core files: for each, addFile (asserting the shape),
2230
+ // statically scans for relative-`.js` specifiers, resolves them, and
2231
+ // addImports each edge. The strict shape allowlist + existsSync gate filter
2232
+ // out comment-noise like a `require('../../pkg/x')` sitting in a JSDoc block.
2233
+ //
2234
+ // Called from write() so every State variant (preload via beforeExit/exit;
2235
+ // sidecar / independent plugin States via compiler.hooks.done) gets the
2236
+ // same coverage.
2237
+ #backfillBeforeWrite() {
2238
+ // List what the live hooks missed first. An empty list means there's
2239
+ // nothing to do -- either the live hooks captured everything (the common
2240
+ // case for non-preload runs and for plugin-driven States that don't
2241
+ // touch preload-cached modules), or we're a State variant that doesn't
2242
+ // observe imports at all.
2243
+ const missing = this.#collectMissingImportedFiles()
2244
+ if (missing.size === 0) return
2245
+
2246
+ const isStasisCoreFile = (file) => STASIS_CORE_FILE_RE.test(`/${file}`)
2247
+
2248
+ // Split the uncaptured targets. stasis-core's own preload-cached files are the
2249
+ // one case we both can and must reconstruct -- bytes AND transitive edges (the
2250
+ // BFS below). Everything else uncaptured is a resolution we attest WITHOUT
2251
+ // bundling: require.resolve() of a module never loaded in-process (an optional-
2252
+ // dependency probe, a forked-worker child like worker-farm's), or a file Node
2253
+ // can't serve from a bundle anyway (a .node addon). Those edges stay in
2254
+ // this.imports -- the user needs the resolution pinned even though the bytes are
2255
+ // absent -- and we do nothing further with them here. The load-time getFile
2256
+ // gate, not this capture-time pass, enforces the trust boundary: an actual load
2257
+ // of un-bundled bytes still fails closed there, while require.resolve (which
2258
+ // never loads) is served the attested path.
2259
+ const stasisCoreMissing = [...missing].filter((file) => isStasisCoreFile(file))
2260
+ if (stasisCoreMissing.length === 0) return
2261
+
2262
+ const preloadRel = this.#preloadRoot ? relative(this.root, this.#preloadRoot) : null
2263
+ const canBackfill = preloadRel !== null && !preloadRel.startsWith('..')
2264
+
2265
+ // We have stasis-core files to reconstruct but no usable preloadRoot (no loader
2266
+ // present, or stasis-core is a workspace sibling not under state.root): nothing
2267
+ // this method can do, and a stasis-core source going uncaptured IS a real gap --
2268
+ // the bundle would be missing part of its own runtime. Fail loud rather than
2269
+ // silently ship it.
2270
+ assert.ok(canBackfill,
2271
+ `state.write() has imports referencing un-captured stasis-core files but no usable preloadRoot ` +
2272
+ `(preloadRoot=${this.#preloadRoot ?? 'unset'}). The live load hook missed an in-scope target -- ` +
2273
+ `investigate rather than silently patch: ${stasisCoreMissing.slice(0, 3).join(', ')}`)
2274
+
2275
+ const PRELOAD_CONDITIONS = ['node', 'import', 'module-sync', 'node-addons']
2276
+ const stasisAddFile = (file) => {
2277
+ // Tight invariant: every backfilled file MUST match the stasis-core
2278
+ // source-file shape. The caller pre-filters via isStasisCoreFile, but
2279
+ // asserting here keeps the contract local and catches any future code
2280
+ // path that forgets.
2281
+ assert.ok(isStasisCoreFile(file),
2282
+ `state.write() backfill refused: '${file}' is not a stasis-core source file ` +
2283
+ `(expected '.../@exodus/stasis-core/src/<name>.js')`)
2284
+ this.addFile(pathToFileURL(resolve(this.root, file)).toString(), { reason: null }) // backfill is a write-time self-containment step, not a consumer observation -- don't attribute it
2285
+ }
2286
+
2287
+ // BFS through stasis-core's module graph. Seed:
2288
+ // (a) the missing stasis-core files -- user-code -> stasis-core edges the
2289
+ // live load hook missed because Node's module cache short-circuited it.
2290
+ // (b) every stasis-core file already in sources -- a static `stasis
2291
+ // bundle` pass may have pulled one in via the live hook; we still
2292
+ // need to walk its transitive imports.
2293
+ //
2294
+ // For each queued file: addFile if not yet captured, then scan its
2295
+ // source for relative-`.js` specifiers, validate the resolved target,
2296
+ // addImport the edge, and queue the target. The single addFile site
2297
+ // covers seeds AND transitive targets -- a queued target gets addFile'd
2298
+ // on its next pop, no separate inner addFile call needed. BFS converges
2299
+ // because the matching file set is finite and `processed` dedups.
2300
+ const queue = [...stasisCoreMissing]
2301
+ for (const file of this.sources.keys()) {
2302
+ if (isStasisCoreFile(file)) queue.push(file)
2303
+ }
2304
+
2305
+ const processed = new Set()
2306
+ while (queue.length > 0) {
2307
+ const file = queue.shift()
2308
+ if (processed.has(file)) continue
2309
+ processed.add(file)
2310
+ if (!this.sources.has(file) && !this.resources.has(file)) stasisAddFile(file)
2311
+ const source = this.sources.get(file)
2312
+ if (typeof source !== 'string') continue
2313
+ const baseURL = pathToFileURL(resolve(this.root, file)).toString()
2314
+ const recordEdge = (specifier) => {
2315
+ const targetURL = new URL(specifier, baseURL).toString()
2316
+ const targetAbsolute = fileURLToPath(targetURL)
2317
+ let targetFile
2318
+ try { targetFile = this.relative(targetAbsolute) } catch { return }
2319
+ if (!isStasisCoreFile(targetFile)) return
2320
+ if (!existsSync(targetAbsolute)) return
2321
+ queue.push(targetFile)
2322
+ this.addImport(baseURL, specifier, targetURL, { conditions: PRELOAD_CONDITIONS })
2323
+ }
2324
+ // (1) ESM `from './<name>.js'|'.cjs'\n` -- stasis-core's source import shape
2325
+ // (`import ... from` / `export ... from`, single-quoted, basename without `.`).
2326
+ // Tight enough to ignore JSDoc / template-literal false positives, narrow enough
2327
+ // to reject parent-relative (`../`), subpath (`./dir/file.js`), or extensionless.
2328
+ // The `.cjs` arm covers state.js -> ./package.cjs (the version re-export shim).
2329
+ for (const m of source.matchAll(/ from '(\.\/[a-zA-Z-]+\.c?js)'\n/g)) recordEdge(m[1])
2330
+ // (2) CJS `require('../package.json')` -- the single CommonJS shim
2331
+ // (src/package.cjs) re-exporting stasis-core's own package.json so state.js can
2332
+ // read its version. Matched exactly (not a general require/`../` relaxation) to
2333
+ // stay as tight as the ESM arm.
2334
+ for (const m of source.matchAll(/require\('(\.\.\/package\.json)'\)/g)) recordEdge(m[1])
2335
+ }
2336
+ }
2337
+
2338
+ // Project-relative files referenced by `this.imports` that the live hooks
2339
+ // didn't capture into this.sources / this.resources, restricted to the
2340
+ // in-scope set (full: everything under state.root; nm: only node_modules).
2341
+ // Out-of-scope files are NOT included -- the live hooks correctly skip them
2342
+ // (workspace files under nm-scope), and including them would force the
2343
+ // backfill caller to wave away false alarms.
2344
+ #collectMissingImportedFiles() {
2345
+ const missing = new Set()
2346
+ for (const [, byParent] of this.imports) {
2347
+ for (const [, specifiers] of byParent) {
2348
+ for (const [, file] of specifiers) {
2349
+ if (typeof file !== 'string') continue
2350
+ if (missing.has(file)) continue
2351
+ // Union of three "captured" signals: hashes (addFile ran -- present
2352
+ // under any lock mode), sources/resources (bundle pre-seeded -- present
2353
+ // under bundle=load even without a lockfile). Any one suffices; a
2354
+ // file in NONE of them is the actual missing-from-capture case.
2355
+ if (this.hashes.has(file) || this.sources.has(file) || this.resources.has(file)) continue
2356
+ const url = pathToFileURL(resolve(this.root, file)).toString()
2357
+ if (!this.config.full && !this.inNodeModules(url)) continue
2358
+ missing.add(file)
2359
+ }
2360
+ }
2361
+ }
2362
+ return missing
2363
+ }
2364
+ }
2365
+
2366
+ // Allowed shape for a backfillable stasis-core path -- a `src/<name>.js` or
2367
+ // `src/<name>.cjs` source, or the package's own `package.json` (required by the
2368
+ // src/package.cjs version shim). Used by the backfill BFS to reject anything that
2369
+ // doesn't look like a real stasis-core file (comment noise, paths escaping `src/`,
2370
+ // etc.). Matched against `/${projectRelativeFile}` so the leading-`/` anchor isn't
2371
+ // fooled by a file at the project root happening to end in `@exodus/stasis-core/...`.
2372
+ // Source basenames are `[a-zA-Z-]+` only -- no `.` in the basename, which is why
2373
+ // `state.util.js` was renamed to `state-util.js`.
2374
+ const STASIS_CORE_FILE_RE = /\/@exodus\/stasis-core\/(?:src\/[a-zA-Z-]+\.c?js|package\.json)$/
2375
+