@exodus/stasis-core 1.0.0-beta.0 → 1.0.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/state.js CHANGED
@@ -3,59 +3,74 @@ import { isUtf8 } from 'node:buffer'
3
3
  import * as fs from 'node:fs'
4
4
  import { join, resolve, relative, basename, dirname, extname, isAbsolute } from 'node:path'
5
5
  import { fileURLToPath, pathToFileURL } from 'node:url'
6
- import { findPackageJSON } from 'node:module'
7
6
  import { brotliCompressSync, brotliDecompressSync } from 'node:zlib'
8
7
 
9
8
  import { Config } from './config.js'
10
- import { Bundle } from './bundle.js'
9
+ import { Bundle, mergeRepo } from './bundle.js'
11
10
  import { Lockfile } from './lockfile.js'
11
+ import { parseShard, serializeShard } from './shard.js'
12
12
  import { canonicalizePath, sha512integrity, readFileSyncMaybe, noupsert } from './state-util.js'
13
13
  import { brotliOptions } from './brotli.js'
14
- import { CODE_EXTENSIONS, classifyExtension, fileMapToObject, moduleFileKey, objectToMaps, sortPaths, splitNodeModulesPath } from './util.js'
14
+ import { CODE_EXTENSIONS, EMPTY_MODULE_PATH, canObserveExecuteBits, classifyFormat, erasedTypeScriptFormat, fileMapToObject, hasNodeModulesSegment, isBinaryPlist, isNativeArtifact, isPackageString, isPathWithin, isStatFormat, isSubpackage, moduleFileKey, moduleInfo, narrowExecutable, nestedMap, objectToMaps, observeExecutable, pathExt, reconcileFormat, relativeEscapes, sortPaths, splitNodeModulesPath, withMetadataOf } from './util.js'
15
+ import { detectRepo, namedManifestOf, packageJSONStat, packageJSONText, packageRepo, readModuleManifest, vendorDirOf, vendoredPackageOf } from './bundle-util.js'
16
+ import { diskHost } from './host.js'
15
17
  import corePackage from './package.cjs'
16
18
 
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
19
+ // Destructure off the namespace: captures the real fns at eval time, so writes survive --mock's
20
+ // syncBuiltinESMExports() remock of node:fs.
21
+ const { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } = fs
24
22
 
25
23
  const FILE_CONFIG = 'stasis.config.json'
26
24
  const FILE_LOCK = 'stasis.lock.json'
27
25
  const FILE_CODE = 'stasis.code.br'
28
26
 
29
- function readPackageJSON(pkgAbsolute) {
30
- const buf = readFileSync(pkgAbsolute)
27
+ // Via src/package.cjs: a bundler-safe re-export of package.json.
28
+ const VERSION = corePackage.version
29
+
30
+ const CAN_OBSERVE_EXECUTE_BITS = canObserveExecuteBits()
31
+
32
+ const invalidPackageConfig = (pkgAbsolute, cause) => Object.assign(
33
+ cause === undefined ? new Error(`Invalid package config ${pkgAbsolute}.`) : new Error(`Invalid package config ${pkgAbsolute}.`, { cause }),
34
+ { code: 'ERR_INVALID_PACKAGE_CONFIG' })
35
+
36
+ // A package.json's fields; one that is no JSON object is refused as Node refuses it.
37
+ function readPackageJSON(host, pkgAbsolute) {
38
+ const buf = host.readFile(pkgAbsolute)
31
39
  assert.ok(isUtf8(buf))
32
- return JSON.parse(buf.toString())
40
+ let json
41
+ try {
42
+ json = JSON.parse(packageJSONText(buf))
43
+ } catch (cause) {
44
+ throw invalidPackageConfig(pkgAbsolute, cause)
45
+ }
46
+ if (json === null || typeof json !== 'object' || Array.isArray(json)) throw invalidPackageConfig(pkgAbsolute)
47
+ return json
33
48
  }
34
49
 
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
50
+ // A weak 'stat:*' yields to a real format; two real formats or a stat kind flip are fatal.
51
+ function upsertFormat(map, file, format) {
52
+ const currentFormat = map.get(file)
53
+ map.set(file, currentFormat === undefined ? format : reconcileFormat(format, currentFormat, file))
54
+ }
42
55
 
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.
56
+ // Loader formats the extension alone decides; `.js`/`.ts` follow the nearest package `type`.
57
+ const EXT_FORMATS = { __proto__: null, '.json': 'json', '.mjs': 'module', '.cjs': 'commonjs', '.mts': 'module-typescript', '.cts': 'commonjs-typescript' }
58
+ // With no `type`, Node decides .js/.ts by syntax detection: either variant is possible, the first is the default.
59
+ const UNTYPED_VARIANTS = { __proto__: null, '.js': ['commonjs', 'module'], '.ts': ['commonjs-typescript', 'module-typescript'] }
60
+
61
+ // Nested package.json files known to disagree with their package root's name/version because of
62
+ // upstream packaging, exempt from #locateModule's consistency check. Matched as a segment-aligned
63
+ // suffix of the project-relative path, so hoisted, nested and .pnpm-store copies all match.
64
+ // Maintained list: add only a confirmed upstream false positive, with its reason.
65
+ const INCONSISTENT_PACKAGE_JSON_EXCEPTIONS = [
66
+ 'node_modules/@redis/client/dist/package.json', // stale build-time copy
67
+ ]
68
+ const isInconsistentPackageJsonException = (file) =>
69
+ INCONSISTENT_PACKAGE_JSON_EXCEPTIONS.some((suffix) => file === suffix || file.endsWith(`/${suffix}`))
70
+
71
+ // On globalThis via `Symbol.for` so the registry is shared across duplicate stasis-core copies.
55
72
  const STATES_KEY = Symbol.for('@exodus/stasis-core/states')
56
- function liveStates() {
57
- return (globalThis[STATES_KEY] ??= new Set())
58
- }
73
+ const liveStates = () => (globalThis[STATES_KEY] ??= new Set())
59
74
 
60
75
  export class State {
61
76
  hashes = new Map()
@@ -65,585 +80,339 @@ export class State {
65
80
  formats = new Map()
66
81
  modules = new Map()
67
82
  imports = new Map()
83
+ // Project-relative files carrying a POSIX execute bit; disk is authoritative (a file that lost
84
+ // the bit drops out). Emitted as the artifacts' `executable` list.
85
+ executable = new Set()
68
86
  config
69
87
  root
70
88
  #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
89
  #isPreload = false
90
+ #host
75
91
 
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.
92
+ // Claimed write-target paths (canonicalized -> label), for cross-State collision detection; a
93
+ // State built with `claim: false`, which never writes (a static build), claims none.
94
+ #claim
79
95
  #claims = new Map()
80
96
 
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.
97
+ // WRITE-mode sidecars: lockfile CONTRIBUTORS (#mergedImports/#mergedFormats union theirs in).
90
98
  #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).
99
+ // LOAD-mode sidecars: read-only, NOT lockfile contributors (getFs*Family serves bytes from them).
100
100
  #readSidecars = new Set()
101
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.
102
+ // Lockfile-attested resolutions (conditions -> parent -> specifier -> file) and loader formats
103
+ // (file -> format), or null; may be supersets of what a run observes, so kept apart from the live maps.
107
104
  #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
105
  #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.
106
+ // Loaded a lockfile at construction: #mergeBundleMetadata cross-checks bundle metadata against
107
+ // it instead of absorbing it as source of truth.
121
108
  #lockfileLoaded = false
122
109
 
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.
110
+ // Keys THIS process recorded this run (not the seeded baseline); shardSnapshot forwards only these.
127
111
  #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.
112
+ // file -> consumers that recorded it, for the bundle's informational `reason` field.
131
113
  #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
114
  #runImported = new Set()
136
115
  #fsReadPostPlugin = new Set()
137
116
  #pluginAttached = false
138
117
 
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.
118
+ // Attested by a frozen bundle (bundle=frozen), or null: closes the attested set, so anything the
119
+ // bundle never recorded is rejected. Separate from the live maps.
148
120
  #bundleSources = null
149
121
  #bundleResources = null
150
122
  #bundleImports = null
151
123
  #bundleFormats = null
152
124
 
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.
125
+ // Lazily-built dirs IMPLIED by recorded files, so getFsStat answers isDirectory() at bundle=load.
159
126
  #impliedDirIndex = null
160
127
 
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.
128
+ // Native resolutions (parent URL -> specifier -> resolved URL) from the Module._resolveFilename
129
+ // shim: require.resolve()/CJS require()s bypassing the resolve hook.
165
130
  #observedResolutions = new Map()
166
131
 
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.
132
+ // Files a require() actually EXECUTED (from the Module._load shim) -- unlike a resolve-only
133
+ // edge, an executed file with no captured bytes is a hole in the attestation, so write()
134
+ // backfills it from disk (a transplanted require.extensions handler, e.g. a transforming
135
+ // preload's CJS TypeScript pipeline, loads files without ever hitting the load hook).
136
+ #executedFiles = new Set()
137
+
138
+ // Files whose BYTES this run captured via addFile. Distinct from this.hashes, which also
139
+ // absorbs lockfile-seeded entries: #backfillExecutedFiles must key on "observed this run", or
140
+ // a frozen/add run would skip verifying an executed file merely because a hash is on record.
141
+ #filesCapturedThisRun = new Set()
142
+
143
+ // Node's require-condition set, from the first require()-context addImport;
144
+ // #backfillObservedResolutions keys native edges under it so the lockfile is Node-version-stable.
179
145
  #requireConditions = null
180
146
 
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.
147
+ // Root of a package Node loaded BEFORE our hooks (stasis-core's own); write()'s backfill
148
+ // statically parses files under it to recover edges the resolve hook never observed.
188
149
  #preloadRoot = null
189
150
 
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.
151
+ // Per-artifact "last serialized" caches: write() skips brotli + writeFileSync on unchanged text.
197
152
  #lastLockData = null
198
153
  #lastUnifiedBundle = null
199
154
  #lastCodeBundle = null
200
155
  #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.
156
+ // Lazy `{ value: detectRepo(this.root, this.#host) }`.
157
+ #detectedRepoCache
158
+ // Half ('code' | 'resources') -> `repo` of the bundle absorbed there for adding to.
159
+ #absorbedRepos = new Map()
160
+
161
+ // Memoized #canonicalUncached (per URL, State-lifetime): a realpathSync per node_modules URL, and
162
+ // hot callers repeat relentlessly. Sound only because the tree holds still mid-run; the cached
163
+ // result is shared -- never mutate it.
164
+ #canonicalCache = new Map()
165
+
166
+ // Options: `preload` (the unique preload State), `parent` (run as a sidecar sharing the parent's
167
+ // hashes/entries/modules, with its own sources/formats/imports/resources and bundle) and
168
+ // `skipDiscovery` (a caller-populated in-memory State, NO filesystem discovery; read-only modes
169
+ // only). All other keys forward to Config.
210
170
  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)
171
+ const { preload: isPreload = false, parent: parentState, preloadRoot, skipDiscovery = false, host = diskHost, env = process.env, claim = true, ...configOptions } = options
172
+ this.config = new Config({ ...configOptions, env, host })
173
+ this.#host = host
174
+ this.#claim = claim
214
175
  if (isPreload) assert.ok(!State.preload, 'Only one preload Stasis instance is supported')
215
176
  assert.ok(!(isPreload && parentState), 'preload and parent are mutually exclusive')
216
177
  this.#isPreload = isPreload
217
178
 
218
179
  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.
180
+ // A sidecar shares the parent's maps and inherits its attestation, so a version skew is
181
+ // unsound (a different module copy is fine -- it reads only the parent's PUBLIC surface).
228
182
  assert.equal(parentState.version, VERSION,
229
183
  `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
184
  this.#parent = parentState
233
185
  this.root = parentState.root
234
186
  this.hashes = parentState.hashes
235
187
  this.entries = parentState.entries
236
188
  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.
189
+ // Public sidecarInheritance() (works across copies): the lockfile attestation must reach the
190
+ // sidecar, else a tampered bundle could redirect a resolution on hash-valid bytes.
244
191
  const inherited = parentState.sidecarInheritance()
245
192
  this.#preloadRoot = inherited.preloadRoot
246
193
  this.#lockImports = inherited.lockImports
247
194
  this.#lockFormats = inherited.lockFormats
248
195
  this.#lockfileLoaded = inherited.lockfileLoaded
249
196
  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.
197
+ // Only writing States claim, so two write-intent States can't silently target the same file.
259
198
  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
- }
199
+ this.#claimWritePath('bundleFile', 'sidecar ')
200
+ this.#claimWritePath('resourcesBundleFile', 'sidecar ')
265
201
  }
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) {
202
+ // frozenBundle MUST go through this branch too -- it has its own attestation snapshot to build.
203
+ if (this.config.bundle) {
271
204
  const sourcesPath = this.config.bundleFile
272
- const sources = readFileSyncMaybe(dirname(sourcesPath), basename(sourcesPath))
205
+ const sources = this.#readMaybe(sourcesPath)
273
206
  if (sources && !this.config.replaceBundle) {
274
207
  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.
208
+ // v0 bundle has no per-file formats or import map -- serving one via a sidecar widens trust.
278
209
  assert.equal(bundle.version, Bundle.VERSION,
279
210
  `stasis sidecar requires a v1 bundle; ${sourcesPath} is v${bundle.version}. ` +
280
211
  `Re-bundle with the current stasis or \`bundle=replace\` against a v0-free starting point.`)
281
212
  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
- }
213
+ // Cross-checked against the parent's lockfile, or absorbed if none (shared hashes/entries/
214
+ // modules mean those writes propagate to the parent).
215
+ this.#absorbCodeBundle(bundle, this.#lockfileLoaded)
310
216
  }
217
+ this.#absorbResourcesBundleFile(this.#lockfileLoaded)
311
218
  }
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
219
  if (this.config.frozenBundle) {
315
220
  assert.ok(this.#bundleSources !== null, 'No bundle, but attempting to run in frozen bundle mode')
316
221
  }
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.
222
+ // Register AFTER every fallible step so a throw leaves no dead reference. Frozen sidecars
223
+ // join neither registry (--fs neither captures nor serves in frozen-bundle mode).
332
224
  if (this.config.writeBundle) parentState.registerSidecar(this)
333
225
  else if (this.config.loadBundle) parentState.registerReadSidecar(this)
334
- liveStates().add(this)
226
+ if (this.#claims.size > 0) liveStates().add(this)
335
227
  return
336
228
  }
337
229
 
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
230
  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
231
  assert.ok(!this.config.frozen && !this.config.frozenBundle && !this.config.writeBundle && !this.config.writeLockfile,
347
232
  'skipDiscovery is read-only: incompatible with frozen and write (add/replace) lock/bundle modes')
348
233
  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)
234
+ this.#setPreloadRoot(preloadRoot)
235
+ if (isPreload) liveStates().add(this)
354
236
  return
355
237
  }
356
238
 
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.
239
+ // Capture and load MUST agree on where the upward walk stops (PROJECT_CWD/.git/
240
+ // pnpm-workspace.yaml), else they commit different roots and fail "outside the project root".
360
241
  const potentialRoots = []
361
- let cursor = root
362
- while (cursor) {
363
- if (existsSync(join(cursor, 'package.json'))) {
242
+ for (let cursor = root; cursor; cursor = dirname(cursor)) {
243
+ // One there that can't be read is refused, not walked past to a root above (packageJSONStat).
244
+ if (packageJSONStat(this.#host, join(cursor, 'package.json')) !== null) {
364
245
  potentialRoots.push(cursor)
365
- } else if (
366
- existsSync(join(cursor, FILE_CONFIG)) ||
367
- existsSync(join(cursor, FILE_LOCK)) ||
368
- existsSync(join(cursor, FILE_CODE))) {
246
+ } else if ([FILE_CONFIG, FILE_LOCK, FILE_CODE].some((file) => this.#exists(join(cursor, file)))) {
369
247
  throw new Error('Unexpected stasis config without package.json')
370
248
  }
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
249
+ if (cursor === env.PROJECT_CWD) break // e.g. yarn sets this
250
+ if (this.#exists(join(cursor, '.git')) || this.#exists(join(cursor, 'pnpm-workspace.yaml'))) break
251
+ if (dirname(cursor) === cursor) break
378
252
  }
379
253
 
380
254
  // default root is top-level package.json, to opt-in to per-dir create stasis.config.json
381
255
  this.root = potentialRoots.at(-1)
256
+ assert.ok(this.root, `stasis: no package.json found at or above ${resolve(root)}; run stasis from within a project`)
382
257
 
383
258
  let loaded = false
384
259
  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.
260
+ // Explicit lockFile: suppress the per-rootDir probe so a stale project-root lockfile can't
261
+ // shadow it; substituted below.
390
262
  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.
263
+ // A construction-time (flag/env) `bundleFile` is rootDir-INDEPENDENT, so it must NOT be a
264
+ // root-detection signal: picking the innermost dir would diverge load's root from the capture
265
+ // root. A config-only bundleFile is NOT suppressed (its dir already carries the config signal).
406
266
  const explicitBundlePath = this.config.bundleFile
407
267
  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)
268
+ const config = readFileSyncMaybe(rootDir, FILE_CONFIG, 'utf-8', this.#host)
269
+ const lockProbe = explicitLockPath ? null : readFileSyncMaybe(rootDir, FILE_LOCK, 'utf-8', this.#host)
270
+ let sourcesPath = explicitBundlePath || join(rootDir, FILE_CODE)
271
+ let sources = this.#readMaybe(sourcesPath)
272
+ // Root-SELECTION signals: a config, a lockfile, or only the DEFAULT <rootDir>/stasis.code.br
273
+ // (see explicitBundlePath; an explicit bundleFile is still loaded via `sources`).
274
+ if (config === null && lockProbe === null && (explicitBundlePath || sources === null)) continue
275
+ if (loaded) throw new Error('Stasis config already loaded')
276
+ loaded = true
277
+ this.root = rootDir
278
+
279
+ if (config) {
280
+ this.config.loadConfig(config)
281
+ // stasis.config.json may set a `bundleFile` the probe couldn't see -- re-resolve and re-read.
282
+ const configuredPath = this.config.bundleFile || join(rootDir, FILE_CODE)
283
+ if (configuredPath !== sourcesPath) {
284
+ sourcesPath = configuredPath
285
+ sources = this.#readMaybe(sourcesPath)
497
286
  }
287
+ }
498
288
 
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
- }
289
+ const lock = explicitLockPath ? this.#readMaybe(explicitLockPath, 'utf-8') : lockProbe
290
+ lockfileLoaded = this.#absorbLockfile(lock, explicitLockPath || join(rootDir, FILE_LOCK))
291
+ this.#loadBundleArtifacts(sources, sourcesPath, lockfileLoaded)
512
292
 
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
- }
293
+ // Innermost matching rootDir wins (per-dir opt-in); without this break an outer root
294
+ // re-detects a rootDir-independent bundleFile and trips `loaded`.
295
+ break
520
296
  }
521
297
 
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.
298
+ // Explicit lockfile but no discovery indicator: the loop never ran, so absorb here against
299
+ // `this.root` (outermost) so the run still has attestation.
527
300
  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
- }
301
+ lockfileLoaded = this.#absorbLockfile(this.#readMaybe(explicitLockPath, 'utf-8'), explicitLockPath)
557
302
  }
558
303
 
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
- }
304
+ // Explicit bundleFile suppressed as a root signal above: load against `this.root` (outermost).
305
+ if (!loaded && (explicitBundlePath || this.config.resourcesBundleFile)) {
306
+ this.#loadBundleArtifacts(explicitBundlePath ? this.#readMaybe(explicitBundlePath) : null, explicitBundlePath, lockfileLoaded)
586
307
  }
587
308
 
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.
309
+ // Post-loop: with no stasis files the loop never runs, and a frozen run must fail closed.
594
310
  if (this.config.frozen) assert.ok(lockfileLoaded, 'No lockfile, but attempting to run in frozen mode')
595
311
  if (this.config.frozenBundle) assert.ok(this.#bundleSources !== null, 'No bundle, but attempting to run in frozen bundle mode')
596
312
 
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)
313
+ // Claim write targets so no other live State (any copy) silently targets the same file.
314
+ if (this.config.writeBundle) {
315
+ this.#claimWritePath('bundleFile')
316
+ this.#claimWritePath('resourcesBundleFile')
613
317
  }
318
+ if (this.config.writeLockfile) this.#claimWritePath('lockFile')
319
+
320
+ this.#setPreloadRoot(preloadRoot)
614
321
 
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
322
+ // The registry answers for the preload and for write claims; any other State stays out of it.
323
+ if (isPreload || this.#claims.size > 0) liveStates().add(this)
324
+ }
325
+
326
+ #exists(p) {
327
+ return this.#host.stat(p) !== null
328
+ }
329
+
330
+ // The file at `path` through the host, or null when there is none.
331
+ #readMaybe(path, encoding) {
332
+ return readFileSyncMaybe(dirname(path), basename(path), encoding, this.#host)
333
+ }
334
+
335
+ #setPreloadRoot(preloadRoot) {
336
+ if (preloadRoot === undefined) return
337
+ assert.equal(typeof preloadRoot, 'string', 'preloadRoot must be a string')
338
+ this.#preloadRoot = preloadRoot
339
+ }
340
+
341
+ // Absorb a lockfile's attestation; returns whether it was actually absorbed. Lockfile.parse
342
+ // requires both imports and formats, so an absorbed lockfile always attests them.
343
+ #absorbLockfile(lock, lockPath) {
344
+ if (lock && !this.config.useLockfile && !this.config.ignoreLockfile) {
345
+ throw new Error(`Unexpected ${lockPath} with config.lock = 'none'`)
346
+ }
347
+ if (!lock || !this.config.useLockfile || this.config.replaceLockfile) return false
348
+ const lockfile = Lockfile.parse(lock)
349
+ if (this.config.frozen) assert.equal(lockfile.config.scope, this.config.scope)
350
+
351
+ const includeSources = lockfile.config.scope === 'full' && this.config.full
352
+ for (const [dir, info] of lockfile.modules) {
353
+ if (!hasNodeModulesSegment(dir) && !includeSources) continue
354
+ this.modules.set(dir, info)
355
+ }
356
+ if (includeSources) this.entries = lockfile.entries
357
+
358
+ for (const [dir, { files }] of this.modules) {
359
+ for (const [name, hash] of Object.entries(files)) noupsert(this.hashes, join(dir, name), hash)
360
+ }
361
+ this.#lockImports = lockfile.imports
362
+ this.#lockFormats = lockfile.formats
363
+ // Seeded into the live set (not a separate baseline) so re-reading a file this run can CLEAR
364
+ // a stale exec bit.
365
+ this.#absorbExecutable(lockfile)
366
+ this.#lockfileLoaded = true
367
+ return true
368
+ }
369
+
370
+ // An on-disk bundle is read in under add/load/frozen; replace starts over.
371
+ get #absorbsBundles() {
372
+ return this.config.bundle && !this.config.replaceBundle
373
+ }
374
+
375
+ // Gate and load the bundle artifacts for a committed root; `sources` may be null (no bundle, or
376
+ // resources-only).
377
+ #loadBundleArtifacts(sources, sourcesPath, lockfileLoaded) {
378
+ if (sources && this.config.bundleMode === 'none') {
379
+ throw new Error(`Unexpected ${sourcesPath} with config.bundle = 'none'`)
380
+ }
381
+ // A frozen bundle is self-attesting, so it needs no sibling lockfile and is exempt here.
382
+ if (sources && !lockfileLoaded && this.config.useLockfile && !this.config.replaceLockfile && !this.config.frozenBundle) {
383
+ throw new Error('stasis.lock.json missing, can not use sources')
622
384
  }
385
+ if (sources && this.#absorbsBundles) this.#loadCodeBundle(sources, sourcesPath, lockfileLoaded)
386
+ this.#absorbResourcesBundleFile(lockfileLoaded)
387
+ }
623
388
 
624
- liveStates().add(this)
389
+ // The resources half of a split layout, when configured and present on disk.
390
+ #absorbResourcesBundleFile(lockfileLoaded) {
391
+ const resourcesPath = this.config.resourcesBundleFile
392
+ const resourcesData = resourcesPath ? this.#readMaybe(resourcesPath) : null
393
+ if (resourcesData && this.#absorbsBundles) this.#absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath })
625
394
  }
626
395
 
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.
396
+ #loadCodeBundle(sources, sourcesPath, lockfileLoaded) {
634
397
  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.
398
+ // Bundle.parse accepts v0 for offline tooling; the runtime refuses it -- v0 has no per-file
399
+ // formats or import map, so serving one widens the trust boundary.
642
400
  assert.equal(bundle.version, Bundle.VERSION,
643
401
  `stasis run requires a v1 bundle; ${sourcesPath} is v${bundle.version}. ` +
644
402
  `Re-bundle with the current stasis (\`stasis bundle\`) or \`stasis run --bundle=replace\` ` +
645
403
  `against a v0-free starting point to upgrade.`)
646
404
  assert.equal(bundle.config.scope, this.config.scope)
405
+ // assertEntry short-circuits on an empty set, so a runnable full-scope code bundle must declare
406
+ // an entry here -- else any bundled file could run as the root. Add-only bundles have none.
407
+ assert.ok(!this.config.full || bundle.entries.size > 0 || !bundle.hasCode,
408
+ `${sourcesPath}: a full-scope bundle carrying code must declare an entry to run ` +
409
+ `(an add-only attestation has none; run a bundle built by \`stasis bundle\`/\`stasis run\`)`)
410
+ this.#absorbCodeBundle(bundle, lockfileLoaded)
411
+ }
412
+
413
+ // Take a parsed code bundle (unified, or the code half) as the live maps, cross-checked against
414
+ // the loaded lockfile, and snapshot it when it is the frozen attestation.
415
+ #absorbCodeBundle(bundle, lockfileLoaded) {
647
416
  this.#mergeBundleMetadata(bundle, { lockfileLoaded })
648
417
  for (const [file, content] of bundle.sources) {
649
418
  if (Bundle.isResourceFormat(bundle.formats.get(file))) this.resources.set(file, content)
@@ -651,12 +420,12 @@ export class State {
651
420
  }
652
421
  this.formats = bundle.formats
653
422
  this.imports = bundle.imports
423
+ this.#absorbExecutable(bundle)
424
+ this.#seedReasonFromBundle(bundle)
425
+ this.#absorbRepo('code', bundle)
654
426
  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.
427
+ // Snapshot before addFile/addImport mutate the live maps; imports is deep-cloned because
428
+ // this.imports shares bundle.imports's nested Maps.
660
429
  this.#bundleSources = new Set(this.sources.keys())
661
430
  this.#bundleResources = new Set(this.resources.keys())
662
431
  this.#bundleImports = objectToMaps(fileMapToObject(bundle.imports))
@@ -664,44 +433,31 @@ export class State {
664
433
  }
665
434
  }
666
435
 
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.
436
+ // Cross-check bundle metadata (entries/modules) against the loaded lockfile, or absorb it as
437
+ // source of truth when none. v0 buckets carry no version, so unverifiable entries are skipped.
679
438
  #mergeBundleMetadata(bundle, { lockfileLoaded }) {
680
439
  if (lockfileLoaded) {
681
440
  if (bundle.entries.size > 0) {
682
- assert.deepStrictEqual(
683
- [...bundle.entries].toSorted(),
684
- [...this.entries].toSorted(),
685
- 'bundle/lockfile entries mismatch'
686
- )
441
+ assert.deepStrictEqual([...bundle.entries].toSorted(), [...this.entries].toSorted(), 'bundle/lockfile entries mismatch')
687
442
  }
688
443
  for (const [dir, info] of bundle.modules) {
689
444
  if (!info.name) continue // workspace bucket or fallback: no inferable name
690
445
  assert.ok(this.modules.has(dir), `bundle module ${dir} missing in lockfile`)
691
446
  const lockModule = this.modules.get(dir)
692
447
  assert.equal(info.name, lockModule.name)
693
- if (info.version) assert.equal(info.version, lockModule.version)
448
+ // Strict, absent included: every absorb site requires a v1 bundle, so a missing version is
449
+ // a real workspace identity (or a stripped field), never v0 partial metadata -- a
450
+ // version-less bundle bucket must not dodge the lockfile consistency check.
451
+ assert.equal(info.version, lockModule.version, `bundle module ${dir} version mismatch with lockfile`)
452
+ // `repo` and `vendored` are metadata, which a lockfile never records: the bundle's are taken, to be written again.
453
+ const withMetadata = withMetadataOf(lockModule, info)
454
+ if (withMetadata !== lockModule) this.modules.set(dir, withMetadata)
694
455
  for (const rel of Object.keys(info.files)) {
695
456
  assert.ok(Object.hasOwn(lockModule.files, rel), `bundle file ${dir}/${rel} missing in lockfile`)
696
457
  }
697
458
  }
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.
459
+ // Hashes alone don't stop a redirect to a different hash-valid file, so every edge the bundle
460
+ // could serve must match the lockfile's attested target (a lockfile superset is fine).
705
461
  if (this.#lockImports !== null) {
706
462
  for (const [conditions, byParent] of bundle.imports) {
707
463
  for (const [parent, specifiers] of byParent) {
@@ -711,27 +467,14 @@ export class State {
711
467
  }
712
468
  }
713
469
  }
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).
470
+ // A format flip changes how hash-valid bytes parse (module<->commonjs) without touching a
471
+ // hash, so every bundle format must match the lockfile's; unattested is fatal.
720
472
  if (this.#lockFormats !== null) {
721
473
  for (const [file, format] of bundle.formats) {
722
474
  this.#assertAttestedFormat(this.#lockFormats, file, format, { what: 'bundle', source: 'lockfile' })
723
475
  }
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.)
476
+ // Inverse: a lockfile-tagged resource MUST be tagged in the bundle too, else omitting the
477
+ // tag routes the base64 payload through this.sources (code) to the loader.
735
478
  for (const [dir, { files }] of bundle.modules) {
736
479
  for (const rel of Object.keys(files)) {
737
480
  const file = moduleFileKey(dir, rel)
@@ -743,45 +486,36 @@ export class State {
743
486
  }
744
487
  }
745
488
  } 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.
489
+ // Mutate in place: this.entries may be shared by reference with a sidecar's parent.
749
490
  for (const e of bundle.entries) this.entries.add(e)
750
491
  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)
492
+ // Skip v0 partial metadata (nameless workspace buckets, version-less node_modules
493
+ // buckets); a v1 workspace bucket may omit version, so its identity is absorbed anyway.
494
+ if (!info.name || (!info.version && hasNodeModulesSegment(dir))) continue
495
+ const existing = this.modules.get(dir)
496
+ if (existing === undefined) {
497
+ this.modules.set(dir, moduleInfo({ ...info, files: Object.create(null) }))
498
+ } else {
499
+ // A dir may be added twice (code + resource entries), and both must agree.
757
500
  assert.equal(info.name, existing.name, `bundle ${dir} name mismatch`)
758
501
  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) })
502
+ // `repo` and `vendored` are metadata, held to nothing: the first half's that records one.
503
+ const withMetadata = withMetadataOf(existing, info)
504
+ if (withMetadata !== existing) this.modules.set(dir, withMetadata)
763
505
  }
764
506
  }
765
507
  }
766
508
  }
767
509
 
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.
510
+ // Load the resources half of a split-bundle layout: ONLY resource-format files, unioned into the
511
+ // bundleFile state.
775
512
  #absorbResourcesBundle(resourcesData, { lockfileLoaded, resourcesPath }) {
776
513
  const bundle = Bundle.parse(brotliDecompressSync(resourcesData).toString('utf-8'))
777
514
  assert.equal(bundle.version, Bundle.VERSION,
778
515
  `stasis run requires a v1 resources bundle; ${resourcesPath} is v${bundle.version}. ` +
779
516
  `Re-bundle with the current stasis or \`bundle=replace\` against a v0-free starting point to upgrade.`)
780
517
  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.
518
+ // A populated imports/entries map means mixed halves or tampering -- widens trust on the code side.
785
519
  assert.equal(bundle.imports.size, 0, `resources bundle ${resourcesPath} must have empty imports`)
786
520
  assert.equal(bundle.entries.size, 0, `resources bundle ${resourcesPath} must have empty entries`)
787
521
  for (const [file, format] of bundle.formats) {
@@ -789,42 +523,37 @@ export class State {
789
523
  `resources bundle ${resourcesPath} declares non-resource format='${format}' for ${file}`)
790
524
  }
791
525
  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).
526
+ for (const [file, content] of bundle.sources) this.resources.set(file, content)
527
+ // Union formats: the two halves' file sets must be disjoint.
797
528
  for (const [file, format] of bundle.formats) {
798
529
  const existing = this.formats.get(file)
799
530
  assert.ok(existing === undefined || existing === format,
800
531
  `format conflict for ${file}: bundleFile declares '${existing}', resourcesBundleFile declares '${format}'`)
801
532
  this.formats.set(file, format)
802
533
  }
534
+ this.#absorbExecutable(bundle)
535
+ this.#seedReasonFromBundle(bundle)
536
+ this.#absorbRepo('resources', bundle)
803
537
  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())
538
+ // Extend the frozen snapshot, init lazily: resources-only deployments are legal, so
539
+ // bundleFile may not have populated these.
540
+ this.#bundleResources ??= new Set()
541
+ this.#bundleFormats ??= new Map()
542
+ this.#bundleImports ??= objectToMaps(fileMapToObject(this.imports))
543
+ this.#bundleSources ??= new Set(this.sources.keys())
812
544
  for (const f of bundle.sources.keys()) this.#bundleResources.add(f)
813
545
  for (const [f, fmt] of bundle.formats) this.#bundleFormats.set(f, fmt)
814
546
  }
815
547
  }
816
548
 
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).
549
+ // Union (never replace) an absorbed artifact's `executable` list into the live set: a lockfile
550
+ // seed, or the code half of a split layout, may already have contributed.
551
+ #absorbExecutable(artifact) {
552
+ for (const file of artifact.executable) this.executable.add(file)
553
+ }
554
+
555
+ // Verify one resolution edge against an attestation map: exact conditions key first, else accept
556
+ // only if every condition set agrees on one target. Unknown edges fatal unless tolerateUnknown.
828
557
  #assertAttestedResolution(attestation, conditions, parent, specifier, file, { what, source = 'lockfile', tolerateUnknown = false }) {
829
558
  const edge = `'${specifier}' from ${parent} (${conditions})`
830
559
  let attested = attestation.get(conditions)?.get(parent)?.get(specifier)
@@ -839,21 +568,16 @@ export class State {
839
568
  assert.ok(targets.size === 1, `${what} resolution ${edge} is attested inconsistently across condition sets in the ${source}`)
840
569
  ;[attested] = targets
841
570
  }
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.
571
+ // A per-platform edge is a Map<platform, target>: compare structurally (assert.equal is
572
+ // reference equality).
846
573
  const matches = file instanceof Map && attested instanceof Map
847
574
  ? file.size === attested.size && [...file].every(([platform, target]) => attested.get(platform) === target)
848
575
  : file === attested
849
576
  assert.ok(matches, `${what} resolution ${edge} mismatches the ${source}`)
850
577
  }
851
578
 
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.
579
+ // Verify one file's loader format. Callers only pass files that must be attested, so an
580
+ // unattested file means a forged/extra entry -- fatal.
857
581
  #assertAttestedFormat(attestation, file, format, { what, source = 'lockfile' }) {
858
582
  const attested = attestation.get(file)
859
583
  assert.ok(attested !== undefined, `${what} format for ${file} is not attested by the ${source}`)
@@ -861,62 +585,49 @@ export class State {
861
585
  }
862
586
 
863
587
  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.
588
+ // No entry attestation to check against (lock=none/ignore, fresh build) -- #loadCodeBundle
589
+ // already refuses a runnable code bundle that declares none.
867
590
  if (this.entries.size === 0) return
868
591
  const file = this.#canonicalFile(url)
869
592
  assert.ok(this.entries.has(file), `Unknown entry point: ${file}`)
870
593
  }
871
594
 
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
595
  static get preload() {
875
596
  for (const state of liveStates()) if (state.isPreload) return state
876
597
  return undefined
877
598
  }
878
599
 
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.
600
+ // Public so State.preload works across copies.
881
601
  get isPreload() {
882
602
  return this.#isPreload
883
603
  }
884
604
 
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.
605
+ // Public for #claimWritePath's cross-copy collision scan.
887
606
  claimedWritePathLabel(canonical) {
888
607
  return this.#claims.get(canonical)
889
608
  }
890
609
 
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)
610
+ // Refuse a path another live State (ANY copy) already claims; canonicalized so `./x`/`x`/symlinks
611
+ // compare equal. `key` names the config option; nothing is claimed when it is unset.
612
+ #claimWritePath(key, prefix = '') {
613
+ const value = this.config[key]
614
+ if (!value || !this.#claim) return
615
+ const label = `${prefix}${key} '${value}'`
616
+ const canonical = canonicalizePath(value, this.#host)
900
617
  for (const other of liveStates()) {
901
618
  const owner = other.claimedWritePathLabel(canonical)
902
- assert.ok(owner === undefined, `${label} '${value}' is already claimed by ${owner} of another live State`)
619
+ assert.ok(owner === undefined, `${label} is already claimed by ${owner} of another live State`)
903
620
  }
904
621
  this.#claims.set(canonical, label)
905
622
  }
906
623
 
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).
624
+ // Public so a sidecar can verify it matches its parent's across copies.
910
625
  get version() {
911
626
  return VERSION
912
627
  }
913
628
 
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.
629
+ // PUBLIC (not private-field reads) so a sidecar from a different copy can read it across the
630
+ // class brand.
920
631
  sidecarInheritance() {
921
632
  return {
922
633
  preloadRoot: this.#preloadRoot,
@@ -926,20 +637,12 @@ export class State {
926
637
  }
927
638
  }
928
639
 
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.
640
+ // WRITE-mode sidecar: this parent's lockData unions its imports/formats. Public (cross-copy).
934
641
  registerSidecar(sidecar) {
935
642
  this.#sidecars.add(sidecar)
936
643
  }
937
644
 
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.
645
+ // LOAD-mode sidecar: served by getFs*Family, never a lockfile contributor. Public (cross-copy).
943
646
  registerReadSidecar(sidecar) {
944
647
  this.#readSidecars.add(sidecar)
945
648
  }
@@ -954,142 +657,136 @@ export class State {
954
657
  relative(absolute) {
955
658
  assert.ok(absolute)
956
659
  const file = relative(this.root, absolute)
957
- assert.ok(!file.startsWith('..'))
958
- return file
660
+ assert.ok(!relativeEscapes(file))
661
+ // The project root is keyed '.', never '' -- mixing the two desyncs write from read.
662
+ return file === '' ? '.' : file
959
663
  }
960
664
 
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
665
  #canonical(url) {
666
+ let result = this.#canonicalCache.get(url)
667
+ if (result === undefined) {
668
+ result = this.#canonicalUncached(url)
669
+ this.#canonicalCache.set(url, result)
670
+ }
671
+ return result
672
+ }
673
+
674
+ // A node_modules file whose REAL path is outside node_modules is a linked-in workspace source
675
+ // (pnpm): canonicalize so it's recorded as a source, not a dependency. Everything else passes through.
676
+ #canonicalUncached(url) {
969
677
  const absolute = this.absolute(url)
970
678
  const file = relative(this.root, absolute)
971
- if (file.startsWith('..') || !splitNodeModulesPath(file)) return { url, absolute }
679
+ if (relativeEscapes(file) || !splitNodeModulesPath(file)) return { url, absolute }
972
680
  let real
973
681
  try {
974
- real = realpathSync(absolute)
682
+ real = this.#host.realpath(absolute)
975
683
  } catch {
976
684
  return { url, absolute }
977
685
  }
978
- if (real === absolute) return { url, absolute } // not a symlink
686
+ if (real === absolute) return { url, absolute }
979
687
  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 }
688
+ if (relativeEscapes(realFile) || splitNodeModulesPath(realFile)) return { url, absolute }
983
689
  return { url: pathToFileURL(real).toString(), absolute: real }
984
690
  }
985
691
 
986
- // The canonical project-relative path a URL is recorded/looked up under.
987
692
  #canonicalFile(url) {
988
693
  return this.relative(this.#canonical(url).absolute)
989
694
  }
990
695
 
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
696
+ // #canonicalFile, or undefined for a URL outside the project root (the shims then pass through).
697
+ #canonicalFileMaybe(url) {
1001
698
  try {
1002
- file = this.#canonicalFile(url)
699
+ return this.#canonicalFile(url)
1003
700
  } catch {
1004
- return false
701
+ return undefined
1005
702
  }
1006
- return splitNodeModulesPath(file) !== null
1007
703
  }
1008
704
 
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.
705
+ // True when `url` resolves (through any workspace symlink) into node_modules -- not a raw
706
+ // `/node_modules/` substring test, so a symlinked workspace source is read from disk.
707
+ inNodeModules(url) {
708
+ const file = this.#canonicalFileMaybe(url)
709
+ return file !== undefined && splitNodeModulesPath(file) !== null
710
+ }
711
+
712
+ // Nearest package.json at or above a directory (findPackageJSON is unreliable for a directory
713
+ // URL, see #locateModule), refusing one there that can't be read as findPackageJSON does
714
+ // (packageJSONStat). Bounded by the project root.
1014
715
  #nearestPackageJsonFor(dirAbsolute) {
1015
- let dir = dirAbsolute
1016
- while (true) {
716
+ for (let dir = dirAbsolute; ; dir = dirname(dir)) {
1017
717
  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
718
+ if (packageJSONStat(this.#host, candidate)?.isFile()) return candidate
719
+ // The root's package.json was just checked; never escape root.
720
+ if (dir === this.root || dirname(dir) === dir) break
1023
721
  }
1024
- // Unreachable in practice: state.root is resolved to a dir that has package.json.
722
+ // Unreachable: state.root is resolved to a dir that has package.json.
1025
723
  assert.fail(`no package.json at or above directory ${this.relative(dirAbsolute)}`)
1026
724
  }
1027
725
 
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))
726
+ // Canonicalize `url` and resolve/register the owning package bucket. `directory: true` walks up
727
+ // ourselves -- Node's findPackageJSON is unreliable for a directory URL (EISDIR, or the parent's).
728
+ // `synthetic: true` (EMPTY_MODULE_PATH) is never on disk: it must NOT exist, and walks up from its dir.
729
+ #locateModule(url, { directory = false, synthetic = false } = {}) {
730
+ // Canonicalize first: a linked-in workspace source is recorded under its real path (a source).
731
+ const { absolute } = this.#canonical(url)
1048
732
  const file = this.relative(absolute)
733
+ if (synthetic) {
734
+ assert.ok(this.#host.stat(absolute) === null, `the reserved path ${file} is needed for a synthetic empty module, but the project has a real file there`)
735
+ } else {
736
+ assert.ok(this.#host.stat(absolute) !== null)
737
+ }
1049
738
 
1050
- const closestPkgAbsolute = directory ? this.#nearestPackageJsonFor(absolute) : findPackageJSON(url)
1051
- const closestPkg = readPackageJSON(closestPkgAbsolute)
739
+ const closestPkgAbsolute = directory ? this.#nearestPackageJsonFor(absolute)
740
+ : synthetic ? this.#nearestPackageJsonFor(dirname(absolute)) : this.#host.findPackageJSON(absolute)
741
+ const closestPkg = readPackageJSON(this.#host, closestPkgAbsolute)
1052
742
 
1053
743
  const closestType = closestPkg.type
1054
744
  assert.ok(closestType === undefined || closestType === 'module' || closestType === 'commonjs')
1055
745
 
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
746
+ // findPackageJSON may land on a `{"type":"module"}` sub-bucket marker lacking name/version.
747
+ const { dir: nmRoot, rel: nmRel } = splitNodeModulesPath(file) ?? {}
748
+ let pkgAbsolute, name, version, repo, vendored, subpackage
1060
749
  if (nmRoot) {
1061
750
  pkgAbsolute = resolve(this.root, nmRoot, 'package.json')
1062
- const rootPkg = pkgAbsolute === closestPkgAbsolute ? closestPkg : readPackageJSON(pkgAbsolute)
751
+ const rootPkg = pkgAbsolute === closestPkgAbsolute ? closestPkg : readPackageJSON(this.#host, pkgAbsolute)
1063
752
  ;({ name, version } = rootPkg)
753
+ repo = packageRepo(rootPkg)
1064
754
  assert.ok(name, `Missing name in ${this.relative(pkgAbsolute)}`)
1065
755
  assert.ok(version, `Missing version in ${this.relative(pkgAbsolute)}`)
1066
- if (closestPkgAbsolute !== pkgAbsolute) {
756
+ // A package.json in a package vendored into this one (bundle-util's vendor dirs) names that
757
+ // package: the file is this one's, listed as that package's in `vendored`.
758
+ const vendorDir = vendorDirOf(name, nmRel)
759
+ const vendor = vendorDir === undefined ? undefined : vendoredPackageOf(nmRel, vendorDir, (sub) => {
760
+ const candidate = resolve(this.root, nmRoot, sub, 'package.json')
761
+ return packageJSONStat(this.#host, candidate)?.isFile() ? readPackageJSON(this.#host, candidate) : null
762
+ })
763
+ vendored = vendor?.vendored
764
+ if (closestPkgAbsolute !== pkgAbsolute && !vendor?.below && !isInconsistentPackageJsonException(this.relative(closestPkgAbsolute))) {
1067
765
  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)
766
+ // Allow fake module-name subpaths: the real module owns the prefix (npm wouldn't publish this).
767
+ if (closestPkg.name !== undefined && closestPkg.name !== name) assert.ok(closestPkg.name.startsWith(`${name}/`), message)
768
+ // A subpackage is the package's, listed in `subpackages`; where the closest package.json is its
769
+ // own (no marker below it), its version is its own too.
770
+ subpackage = this.#subpackageOf(nmRoot, nmRel, closestPkg, name)
771
+ const ownVersion = subpackage !== undefined && closestPkg.name !== undefined
772
+ if (closestPkg.version !== undefined && !ownVersion) assert.equal(closestPkg.version, version, message)
1075
773
  }
1076
774
  } else {
1077
775
  pkgAbsolute = closestPkgAbsolute
1078
776
  let json = closestPkg
1079
- while (true) {
1080
- if (json.name !== undefined && json.version !== undefined) {
1081
- ;({ name, version } = json)
1082
- break
1083
- }
777
+ // A workspace package outside node_modules may omit version (private/unpublished): the
778
+ // name alone claims the bucket. node_modules buckets (above) still require both.
779
+ while (json.name === undefined) {
1084
780
  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)
781
+ const dir = dirname(pkgAbsolute)
782
+ assert.ok(dir !== this.root && isPathWithin(this.root, dir), `No package.json with a name found for ${file}`)
783
+ pkgAbsolute = this.#nearestPackageJsonFor(dirname(dir))
784
+ json = readPackageJSON(this.#host, pkgAbsolute)
1092
785
  }
786
+ name = json.name
787
+ // A literal `"version": null` folds to undefined here too: the parsers normalize the same
788
+ // way, and recording null verbatim would split identity on the next run's re-read.
789
+ version = json.version ?? undefined
1093
790
  }
1094
791
  const pkg = this.relative(pkgAbsolute)
1095
792
  assert.ok(pkg === 'package.json' || pkg.endsWith('/package.json'))
@@ -1097,112 +794,97 @@ export class State {
1097
794
  const dir = dirname(pkg)
1098
795
  if (nmRoot) assert.equal(dir, nmRoot)
1099
796
  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) })
797
+ // Tag node_modules buckets `npm`; workspace/top-level buckets carry no ecosystem.
798
+ this.modules.set(dir, moduleInfo({ name, version, ecosystem: nmRoot ? 'npm' : undefined, repo, files: Object.create(null) }))
1107
799
  }
1108
800
  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 } = {}) {
801
+ if (module.name !== name || module.version !== version) {
802
+ // Message built only on failure: addFile is hot, and the mismatch is a migration/drift event.
803
+ const hint = (module.version == null) === (version == null) ? '' :
804
+ ' -- an artifact from an older stasis may record a placeholder version for a workspace ' +
805
+ 'package without one; regenerate it (lock=replace / bundle=replace)'
806
+ assert.fail(`module identity mismatch for '${dir}': artifact records ` +
807
+ `'${module.name}@${module.version ?? '(none)'}', package.json has '${name}@${version ?? '(none)'}'${hint}`)
808
+ }
809
+ // A dependency's repo is metadata, its package.json's, held to nothing: a record with none gets it.
810
+ if (module.repo === undefined && repo !== undefined) this.modules.set(dir, moduleInfo({ ...module, repo }))
811
+
812
+ return { absolute, file, dir, module: this.modules.get(dir), closestType, vendored, subpackage }
813
+ }
814
+
815
+ // The subpackage (isSubpackage) of the package `name` at `nmRoot` that its file `nmRel` is in: the nearest
816
+ // package.json above the file with a name, past `{"type":"module"}` markers (namedManifestOf), walked by
817
+ // the file's own path, not the real one findPackageJSON resolves through a symlinked install -> { dir, name,
818
+ // version? }, or undefined. Looked for only where the closest package.json, `closest`, is such a marker or
819
+ // names a subpath.
820
+ #subpackageOf(nmRoot, nmRel, closest, name) {
821
+ if (closest.name !== undefined && !(typeof closest.name === 'string' && closest.name.startsWith(`${name}/`))) return undefined
822
+ const found = namedManifestOf(nmRel, (sub) => {
823
+ const candidate = resolve(this.root, nmRoot, sub, 'package.json')
824
+ return packageJSONStat(this.#host, candidate)?.isFile() ? readPackageJSON(this.#host, candidate) : null
825
+ })
826
+ if (found === undefined || !isSubpackage(found.pkg.name, name, found.dir)) return undefined
827
+ return { dir: found.dir, name: found.pkg.name, ...(isPackageString(found.pkg.version) ? { version: found.pkg.version } : {}) }
828
+ }
829
+
830
+ // `resource: true` (legacy alias `isBinary: true`): format derived from bytes. `inferFormat: false`
831
+ // records bytes without imposing a loader format (defers module-vs-commonjs to the loader).
832
+ addFile(url, options = {}) {
833
+ this.#addFile(url, options)
834
+ }
835
+
836
+ // Record the empty module a disabled import resolves to (EMPTY_MODULE_PATH, the file `stasis bundle`
837
+ // emits for a `browser` field `false`), attested like any file but never read from disk. -> its URL
838
+ addEmptyModule({ reason = 'run' } = {}) {
839
+ const url = pathToFileURL(resolve(this.root, EMPTY_MODULE_PATH)).toString()
840
+ this.#addFile(url, { source: '', format: 'commonjs', inferFormat: false, reason }, { synthetic: true })
841
+ return url
842
+ }
843
+
844
+ #addFile(url, { source, format, isEntry, isBinary, resource, inferFormat = true, reason = 'run', fsRead = false } = {}, { synthetic = false } = {}) {
1127
845
  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
846
  if (!asResource && Bundle.isResourceFormat(format)) {
1137
847
  throw new Error(`addFile: format '${format}' requires resource: true`)
1138
848
  }
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.
849
+ if (isStatFormat(format)) {
850
+ throw new Error(`addFile: format '${format}' is a payload-free stat record; use addFsStat`)
851
+ }
1146
852
  if (asResource && isEntry) {
1147
853
  throw new Error(`addFile: a resource can't be an entry (resource:true + isEntry:true)`)
1148
854
  }
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())) {
855
+ const { absolute, file, dir, module, closestType, vendored, subpackage } = this.#locateModule(url, { synthetic })
856
+
857
+ // Real content supersedes a payload-free stat record: drop it so the noupsert below records the
858
+ // actual format instead of conflicting with 'stat:*'.
859
+ if (isStatFormat(this.formats.get(file))) this.formats.delete(file)
860
+
861
+ const ext = extname(file)
862
+ if (asResource && CODE_EXTENSIONS.has(ext.slice(1).toLowerCase())) {
1160
863
  throw new Error(`addFile: a code file can't be recorded as a resource: ${file}`)
1161
864
  }
1162
865
 
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
866
  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)]
867
+ const inferredFormat = EXT_FORMATS[ext] ??
868
+ (closestType === undefined ? undefined : ext === '.js' ? closestType : ext === '.ts' ? `${closestType}-typescript` : undefined)
1180
869
  if (inferredFormat !== undefined) {
870
+ // A transforming preload (`stasis run --import tsx`) loads a TypeScript file as its
871
+ // post-erasure family ('module-typescript' arrives as 'module'): attest the on-disk
872
+ // format, not the transformer's runtime view. Anything else must still match exactly.
873
+ if (format != null && format === erasedTypeScriptFormat(inferredFormat)) format = inferredFormat
1181
874
  if (format != null) assert.equal(format, inferredFormat)
1182
875
  else format = inferredFormat
1183
876
  } 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)]
877
+ // No `type`: reuse an extension-appropriate format already recorded this session (the
878
+ // loader's call, or the parent's for a sidecar) rather than re-defaulting to commonjs and mis-attesting.
879
+ const variants = UNTYPED_VARIANTS[ext]
1204
880
  const known = this.formats.get(file) ?? this.#parent?.formats.get(file)
1205
881
  format = variants?.includes(known) ? known : variants?.[0]
882
+ } else if (ext === '.ts' && (format === 'commonjs' || format === 'module')) {
883
+ // No `type`, but a transforming preload reported this .ts as its post-erasure family:
884
+ // attest the on-disk '-typescript' variant, keeping same-stack replays self-consistent.
885
+ // Stacks can still honestly disagree about a no-`type` .ts (tsx defaults to commonjs,
886
+ // Node syntax-detects) -- that rightly surfaces as a format flip, not silently here.
887
+ format = `${format}-typescript`
1206
888
  }
1207
889
  }
1208
890
 
@@ -1210,20 +892,18 @@ export class State {
1210
892
  if (typeof source === 'string') {
1211
893
  assert.ok(source.isWellFormed())
1212
894
  } else {
1213
- if (source === undefined || source === null) { source = readFileSync(absolute); sourceFromDisk = true }
895
+ if (source == null) {
896
+ source = this.#host.readFile(absolute)
897
+ sourceFromDisk = true
898
+ }
1214
899
  assert.ok(Buffer.isBuffer(source))
1215
900
  if (!asResource) assert.ok(isUtf8(source), `File is not UTF-8: ${file}`)
1216
901
  }
1217
902
 
1218
903
  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'.
904
+ // Verify a CALLER-PROVIDED source against disk; tautological when we read it ourselves.
905
+ if (!sourceFromDisk && !synthetic) assert.deepStrictEqual(this.#host.readFile(absolute), buf)
906
+
1227
907
  if (asResource) {
1228
908
  const derived = isUtf8(buf) ? 'resource' : 'resource:base64'
1229
909
  if (format != null) assert.equal(format, derived, `resource format mismatch for ${file}`)
@@ -1233,45 +913,34 @@ export class State {
1233
913
  if (isEntry) this.entries.add(file)
1234
914
  const integrity = sha512integrity(source)
1235
915
  noupsert(this.hashes, file, integrity)
916
+ this.#filesCapturedThisRun.add(file)
1236
917
  if (this.config.childProcess) this.#observed.add(file) // only a child's shardSnapshot reads it; skip when the channel is off
918
+ // Provenance for the bundle's `reason` field (null = the caller attributes it, see includePackageJson).
1237
919
  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).
920
+ this.#recordReason(reason, file)
921
+ // Track HOW 'run' saw this file so #bundleReason can drop files run merely fs-READ post-plugin.
1241
922
  if (reason === 'run') {
1242
923
  if (!fsRead) this.#runImported.add(file)
1243
924
  else if (this.#pluginAttached) this.#fsReadPostPlugin.add(file)
1244
925
  }
1245
926
  }
1246
927
  const rel = relative(dir, file)
1247
- assert.ok(!rel.startsWith('..'))
928
+ assert.ok(!relativeEscapes(rel))
1248
929
 
1249
- const inAttestedZone = dir.includes('node_modules') || this.config.full
930
+ const inAttestedZone = hasNodeModulesSegment(dir) || this.config.full
1250
931
  if (this.config.frozen && inAttestedZone) {
1251
- assert.ok(Object.hasOwn(module.files, rel))
932
+ assert.ok(Object.hasOwn(module.files, rel), `File not attested by the frozen lockfile: ${file}`)
1252
933
  }
1253
934
 
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.
935
+ // Close the attested set (bytes are checked by the noupsert below); node_modules scope
936
+ // deliberately doesn't attest workspace files.
1260
937
  if (this.config.frozenBundle && inAttestedZone) {
1261
938
  const attested = asResource ? this.#bundleResources : this.#bundleSources
1262
939
  assert.ok(attested?.has(file), `File not attested by the frozen bundle: ${file}`)
1263
940
  }
1264
941
 
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`.
942
+ // `type` is usually not hash-attested, so a flip recategorizes a hash-valid file
943
+ // (commonjs<->module) with no hash mismatch.
1275
944
  if (this.config.frozen && this.#lockFormats !== null && format != null && inAttestedZone) {
1276
945
  this.#assertAttestedFormat(this.#lockFormats, file, format, { what: 'observed', source: 'lockfile' })
1277
946
  }
@@ -1279,102 +948,94 @@ export class State {
1279
948
  this.#assertAttestedFormat(this.#bundleFormats, file, format, { what: 'observed', source: 'frozen bundle' })
1280
949
  }
1281
950
 
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.)
951
+ // Catch a format flip on already-attested bytes here; at write()'s #mergedFormats it would
952
+ // surface only as a bare `Conflict`.
1291
953
  if (this.config.writeLockfile && this.#lockFormats !== null && format != null && inAttestedZone) {
1292
954
  const attested = this.#lockFormats.get(file)
1293
- assert.ok(attested === undefined || attested === format,
955
+ // A 'stat:*' baseline is not a flip: real content this run UPGRADES the record (#mergedFormats).
956
+ assert.ok(attested === undefined || attested === format || isStatFormat(attested),
1294
957
  `format flip for ${file}: lockfile attests '${attested}', observed '${format}' (bytes unchanged) -- re-run with --lock=replace to re-attest`)
1295
958
  }
1296
959
 
1297
960
  if (!Object.hasOwn(module.files, rel)) module.files[rel] = integrity
1298
961
  assert.equal(module.files[rel], integrity)
962
+ // The vendored package or subpackage this file is in is reached: listed in the host's `vendored` or
963
+ // `subpackages` (metadata, the first identity recorded for its dir standing).
964
+ for (const [field, entry] of [['vendored', vendored], ['subpackages', subpackage]]) {
965
+ if (entry === undefined || Object.hasOwn(this.modules.get(dir)[field] ?? {}, entry.dir)) continue
966
+ const { dir: sub, ...identity } = entry
967
+ this.modules.set(dir, withMetadataOf(this.modules.get(dir), { [field]: { [sub]: Object.freeze(identity) } }))
968
+ }
1299
969
 
1300
970
  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
- }
971
+ if (asResource) noupsert(this.resources, file, buf.toString(format === 'resource:base64' ? 'base64' : 'utf8'))
972
+ else noupsert(this.sources, file, typeof source === 'string' ? source : source.toString())
1308
973
  }
1309
974
 
1310
975
  if (format) noupsert(this.formats, file, format)
976
+
977
+ if (!synthetic) this.#recordExecutable(file, absolute)
1311
978
  }
1312
979
 
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.
980
+ // Observe `file` on disk and record or refute its execute bit; disk wins over whatever a lockfile/
981
+ // bundle seeded, but only a real observation refutes (`undefined` and Windows mean "unknowable").
982
+ // A record touches only this State; a REFUTATION must reach the whole family, else
983
+ // #mergedExecutable's union resurrects the bit from a sibling's seeded entry.
984
+ #recordExecutable(file, absolute) {
985
+ const executable = observeExecutable(absolute, this.#host)
986
+ if (executable === true) {
987
+ this.executable.add(file)
988
+ return
989
+ }
990
+ if (executable !== false || !CAN_OBSERVE_EXECUTE_BITS) return
991
+ this.executable.delete(file)
992
+ const root = this.#parent ?? this
993
+ root.executable.delete(file)
994
+ for (const sidecar of root.sidecars()) sidecar.executable.delete(file)
995
+ }
996
+
997
+ // Public so #recordExecutable reaches them across the class brand (duplicate stasis-core copies).
998
+ sidecars() {
999
+ return this.#sidecars
1000
+ }
1001
+
1002
+ // Record an `fs.readFileSync` capture (--fs). classifyFormat routes the bytes: a concrete format
1003
+ // is code, null defers to the loader, and undefined (or a binary plist, whose bytes can't be the
1004
+ // UTF-8 code its format implies) is a resource IFF allowlisted, else THROW -- an undeclared file
1005
+ // would widen the attested set.
1332
1006
  addFsFile(url, source) {
1333
1007
  assert.ok(Buffer.isBuffer(source), 'addFsFile requires a Buffer source')
1334
1008
  const path = fileURLToPath(url)
1335
- const kind = classifyExtension(path, this.config.resources)
1336
- if (kind === 'resource') {
1009
+ const format = classifyFormat(path, { content: source })
1010
+ if (format !== undefined && !isBinaryPlist(path, source)) {
1011
+ this.addFile(url, { source, format: format ?? undefined, inferFormat: false, fsRead: true })
1012
+ } else if (this.config.resources.has(pathExt(path) || basename(path).toLowerCase())) {
1337
1013
  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
- )
1014
+ } else {
1015
+ throw new Error(`addFsFile: ${path} is neither code nor a declared resource; add its extension or filename to the resources allowlist or stop reading it`)
1346
1016
  }
1347
- this.addFile(url, { source, inferFormat: ext !== '.js' && ext !== '.ts', fsRead: true })
1348
1017
  }
1349
1018
 
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).
1019
+ // Record an `fs.readdirSync` capture: the listing is SORTED for reproducibility and stored as a
1020
+ // 'directory'-format payload.
1357
1021
  addFsDir(url, names) {
1358
1022
  assert.ok(Array.isArray(names) && names.every((n) => typeof n === 'string'),
1359
1023
  'addFsDir requires an array of string names')
1360
1024
  const { file, dir, module } = this.#locateModule(url, { directory: true })
1025
+ // As in addFile: a real record supersedes a payload-free stat record.
1026
+ if (isStatFormat(this.formats.get(file))) this.formats.delete(file)
1361
1027
  const content = JSON.stringify(names.toSorted())
1362
1028
  const format = 'directory'
1363
1029
  const integrity = sha512integrity(content)
1364
1030
  noupsert(this.hashes, file, integrity)
1365
1031
  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
1032
  if (this.config.bundle) this.#recordReason('run', file)
1370
1033
  const rel = relative(dir, file)
1371
- assert.ok(!rel.startsWith('..'))
1034
+ assert.ok(!relativeEscapes(rel))
1372
1035
 
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
1036
+ const inAttestedZone = hasNodeModulesSegment(dir) || this.config.full
1376
1037
  if (this.config.frozen && inAttestedZone) {
1377
- assert.ok(Object.hasOwn(module.files, rel))
1038
+ assert.ok(Object.hasOwn(module.files, rel), `Directory not attested by the frozen lockfile: ${file}`)
1378
1039
  }
1379
1040
  if (this.config.frozenBundle && inAttestedZone) {
1380
1041
  assert.ok(this.#bundleResources?.has(file), `Directory not attested by the frozen bundle: ${file}`)
@@ -1390,145 +1051,115 @@ export class State {
1390
1051
  assert.equal(module.files[rel], integrity)
1391
1052
  if (this.config.bundle) noupsert(this.resources, file, content)
1392
1053
  noupsert(this.formats, file, format)
1054
+ // A listing is never executable (both artifacts' parsers refuse one in `executable`), so drop
1055
+ // any bit a prior content record left on this path.
1056
+ this.executable.delete(file)
1057
+ }
1058
+
1059
+ // Record a stat capture as a PAYLOAD-FREE record (`formats[file] = 'stat:file'|'stat:directory'`,
1060
+ // no bytes/hash/module-files entry), so getFsStat answers isFile()/isDirectory() at load. Skipped
1061
+ // when a content record already exists; upsertFormat lets a real format win, a kind flip is fatal.
1062
+ addFsStat(url, kind) {
1063
+ assert.ok(kind === 'file' || kind === 'directory', `addFsStat: unsupported kind '${kind}'`)
1064
+ const file = this.#canonicalFile(url)
1065
+ if (this.hashes.has(file) || this.sources.has(file) || this.resources.has(file)) return
1066
+ upsertFormat(this.formats, file, `stat:${kind}`)
1067
+ // Only forward when a stat record actually landed -- upsertFormat may have yielded to a real
1068
+ // format, and forwarding THAT would ship an entry mergeShard's stat replay ignores.
1069
+ if (this.config.childProcess && isStatFormat(this.formats.get(file))) this.#observed.add(file)
1393
1070
  }
1394
1071
 
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.
1072
+ // Serve an `fs.readFileSync` from the bundle: raw bytes, or undefined when uncaptured (the hook
1073
+ // falls back to disk) or a captured directory. Served by presence, not format.
1402
1074
  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
1075
+ if (!this.hasFsFileContent(url)) return undefined
1407
1076
  const { source } = this.getFile(url)
1408
1077
  return Buffer.isBuffer(source) ? source : Buffer.from(source, 'utf8')
1409
1078
  }
1410
1079
 
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
1080
  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)
1081
+ const file = this.#canonicalFileMaybe(url)
1082
+ if (file === undefined || this.formats.get(file) !== 'directory') return undefined
1083
+ const names = JSON.parse(this.getFile(url).source)
1420
1084
  assert.ok(Array.isArray(names), `corrupt directory listing for ${file}`)
1421
1085
  return names
1422
1086
  }
1423
1087
 
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).
1088
+ // Every ancestor directory implied by recorded keys; built once.
1427
1089
  #impliedDirs() {
1428
1090
  if (this.#impliedDirIndex) return this.#impliedDirIndex
1429
- const dirs = new Set([''])
1091
+ const dirs = new Set(['.'])
1430
1092
  const add = (key) => {
1431
- let prefix = ''
1432
1093
  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
- }
1094
+ for (let i = 1; i < parts.length; i++) dirs.add(parts.slice(0, i).join('/'))
1437
1095
  }
1438
1096
  for (const key of this.sources.keys()) add(key)
1439
1097
  for (const key of this.resources.keys()) add(key)
1098
+ // Stat records prove existence too, so they imply their ancestor dirs.
1099
+ for (const [key, format] of this.formats) if (isStatFormat(format)) add(key)
1440
1100
  this.#impliedDirIndex = dirs
1441
1101
  return dirs
1442
1102
  }
1443
1103
 
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.
1104
+ // Classify a captured path for the stat shim: 'directory', 'file', or undefined (uncaptured -> the
1105
+ // shim falls back to disk). Order matters: 'directory' first, content before stat records, implied
1106
+ // dirs last. NB: 'file' means "recorded", NOT "bytes serveable" (use hasFsFileContent).
1451
1107
  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'
1108
+ const file = this.#canonicalFileMaybe(url)
1109
+ if (file === undefined) return undefined
1110
+ const format = this.formats.get(file)
1111
+ if (format === 'directory') return 'directory'
1112
+ if (this.sources.has(file) || this.resources.has(file) || format === 'stat:file') return 'file'
1113
+ if (format === 'stat:directory' || this.#impliedDirs().has(file)) return 'directory'
1457
1114
  return undefined
1458
1115
  }
1459
1116
 
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.
1117
+ // True when the bundle carries actual BYTE content for `url` (not a directory/stat-only record).
1118
+ hasFsFileContent(url) {
1119
+ const file = this.#canonicalFileMaybe(url)
1120
+ return file !== undefined && this.formats.get(file) !== 'directory' && (this.sources.has(file) || this.resources.has(file))
1121
+ }
1122
+
1123
+ // --fs <-> bundler-plugin coordination: CAPTURE skips a read a write-mode sidecar already attests,
1124
+ // else --fs re-records the bundler's whole module graph into the main bundle and defeats the split.
1480
1125
  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
1126
+ // hasFsFileContent, not getFsStat: over-skipping on an implied dir or stat-only record would
1127
+ // leave a real read unattested.
1128
+ for (const s of this.#sidecars) if (s.hasFsFileContent(url)) return true
1486
1129
  return false
1487
1130
  }
1488
1131
 
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)
1132
+ // getFs* over this State first, then its load-mode sidecars. Only #readSidecars -- write-mode
1133
+ // sidecars only capture.
1134
+ #fromFamily(method, url) {
1135
+ const own = this[method](url)
1496
1136
  if (own !== undefined) return own
1497
- for (const s of this.#readSidecars) { const v = s.getFsFile(url); if (v !== undefined) return v }
1137
+ for (const s of this.#readSidecars) {
1138
+ const v = s[method](url)
1139
+ if (v !== undefined) return v
1140
+ }
1498
1141
  return undefined
1499
1142
  }
1500
1143
 
1144
+ getFsFileFamily(url) {
1145
+ return this.#fromFamily('getFsFile', url)
1146
+ }
1147
+
1501
1148
  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
1149
+ return this.#fromFamily('getFsStat', url)
1506
1150
  }
1507
1151
 
1508
1152
  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
1153
+ return this.#fromFamily('getFsDir', url)
1516
1154
  }
1517
1155
 
1518
1156
  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('..')).
1157
+ // Wrap #canonicalFile so a URL escaping state.root gives a contextual error, not a bare assert.
1523
1158
  let file
1524
1159
  try { file = this.#canonicalFile(url) }
1525
1160
  catch (cause) { throw new Error(`stasis: file is outside the project root: ${url}`, { cause }) }
1526
1161
  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.
1162
+ // A missing entry throws: this single getFile call is the fail-closed gate.
1532
1163
  let source
1533
1164
  if (Bundle.isResourceFormat(format)) {
1534
1165
  source = this.resources.get(file)
@@ -1536,16 +1167,31 @@ export class State {
1536
1167
  if (format === 'resource:base64') source = Buffer.from(source, 'base64')
1537
1168
  } else {
1538
1169
  source = this.sources.get(file)
1539
- if (source === undefined) throw new Error(`stasis: file not attested in bundle: ${url}`)
1170
+ if (source === undefined) {
1171
+ // Stat-record case: the bundle knows the path but not its bytes -- "not attested" would misdiagnose it.
1172
+ if (isStatFormat(format)) {
1173
+ throw new Error(
1174
+ `stasis: only a payload-free stat record ('${format}') is attested for ${url} -- ` +
1175
+ `the capture stat'd this path but never read or imported it, so the bundle has no bytes to serve`
1176
+ )
1177
+ }
1178
+ throw new Error(`stasis: file not attested in bundle: ${url}`)
1179
+ }
1540
1180
  }
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.
1181
+ // Without a lockfile the bundle is self-attesting -- verifying its hash against its own bytes is a tautology.
1543
1182
  if (this.config.useLockfile) assert.equal(this.hashes.get(file), sha512integrity(source))
1544
1183
  return { source, format }
1545
1184
  }
1546
1185
 
1186
+ // The recorded LOADER format, or undefined. Masks 'stat:*' (existence, not how bytes parse) so a
1187
+ // stat'd require.resolve target isn't refused by the resolve hook's format gate; getFile does NOT mask.
1188
+ #loaderFormat(file) {
1189
+ const format = this.formats.get(file)
1190
+ return isStatFormat(format) ? undefined : format
1191
+ }
1192
+
1547
1193
  getFormat(url) {
1548
- return this.formats.get(this.#canonicalFile(url))
1194
+ return this.#loaderFormat(this.#canonicalFile(url))
1549
1195
  }
1550
1196
 
1551
1197
  // Different conditions / import attributes can yield different URLs/formats for the same parent+specifier
@@ -1558,41 +1204,22 @@ export class State {
1558
1204
  return `${cond} (with: ${JSON.stringify(sorted)})`
1559
1205
  }
1560
1206
 
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.
1207
+ // An already-resolved ABSOLUTE require()/import() target as the specifier would be a
1208
+ // machine-specific lockfile key, so renormalize in-root ones against the IMPORTING FILE's dir.
1209
+ // Must be applied identically in addImport and getImport so keys written and queried agree.
1581
1210
  #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)
1211
+ if (typeof specifier !== 'string') return specifier
1212
+ const path = specifier.startsWith('file:') ? fileURLToPath(specifier) : specifier
1213
+ if (!isAbsolute(path)) return specifier
1214
+ const fromRoot = relative(this.root, path)
1215
+ if (fromRoot === '' || relativeEscapes(fromRoot)) return specifier // outside the project root
1216
+ const rel = relative(dirname(fileURLToPath(parentURL)), path)
1586
1217
  return rel.startsWith('.') ? rel : `./${rel}`
1587
1218
  }
1588
1219
 
1589
1220
  addImport(parentURL, specifier, url, { conditions = '*', format, importAttributes } = {}) {
1590
1221
  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).
1222
+ // Capture Node's require-condition set on the first require()-context edge (see #requireConditions).
1596
1223
  if (this.#requireConditions === null && Array.isArray(conditions) &&
1597
1224
  conditions.includes('require') && !conditions.includes('import')) {
1598
1225
  this.#requireConditions = conditions
@@ -1603,32 +1230,19 @@ export class State {
1603
1230
  specifier = this.#canonicalSpecifier(parentURL, specifier)
1604
1231
  const key = this.#conditionsKey(conditions, importAttributes)
1605
1232
 
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')
1233
+ // Frozen runs verify disk resolutions against the lockfile: hashes can't see a redirect to
1234
+ // another attested file. Unknown edges are tolerated only for workspace parents in nm scope.
1235
+ const tolerateUnknown = !this.config.full && !hasNodeModulesSegment(parent)
1616
1236
  if (this.config.frozen && this.#lockImports !== null) {
1617
1237
  this.#assertAttestedResolution(this.#lockImports, key, parent, specifier, file, { what: 'observed', source: 'lockfile', tolerateUnknown })
1618
1238
  }
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
1239
  if (this.config.frozenBundle && this.#bundleImports !== null) {
1623
1240
  this.#assertAttestedResolution(this.#bundleImports, key, parent, specifier, file, { what: 'observed', source: 'frozen bundle', tolerateUnknown })
1624
1241
  }
1625
1242
 
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)
1243
+ noupsert(nestedMap(nestedMap(this.imports, key), parent), specifier, file)
1244
+ // upsertFormat, not noupsert: a real format must replace a weak 'stat:*' record from an --fs stat.
1245
+ if (format) upsertFormat(this.formats, file, format)
1632
1246
  }
1633
1247
 
1634
1248
  getImport(parentURL, specifier, { conditions = '*', importAttributes } = {}) {
@@ -1637,360 +1251,351 @@ export class State {
1637
1251
  const parent = this.#canonicalFile(parentURL)
1638
1252
  specifier = this.#canonicalSpecifier(parentURL, specifier)
1639
1253
  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.
1254
+ // Static bundles store edges under '*' (Node's condition set is unpredictable); the runtime
1255
+ // loader records precise conditions, so the specific lookup wins.
1649
1256
  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
- }
1257
+ if (file === undefined && key !== '*') file = this.imports.get('*')?.get(parent)?.get(specifier)
1653
1258
  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.
1259
+ // The edge may be recorded under a DIFFERENT conditions bucket -- resolveBundled scans every bucket.
1658
1260
  if (this.config.loadBundle) {
1659
1261
  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
- }
1262
+ if (abs !== undefined) return { url: pathToFileURL(abs).toString(), format: this.#loaderFormat(relative(this.root, abs)) }
1664
1263
  }
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.
1264
+ // Node's ERR_MODULE_NOT_FOUND shape, not a bare assert: dynamic-import callers guard on that
1265
+ // code, which ERR_ASSERTION escapes.
1266
+ throw Object.assign(new Error(`Cannot find module '${specifier}' imported from ${parent}`), { code: 'ERR_MODULE_NOT_FOUND' })
1267
+ }
1268
+ // A --metro per-platform edge is a { platform: file } Map; plain bundle=load has no platform
1269
+ // context to pick one, so fail closed rather than feed a Map where a path is expected.
1679
1270
  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
1271
+ throw Object.assign(
1272
+ 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`),
1273
+ { code: 'ERR_STASIS_PLATFORM_SPECIFIC' })
1683
1274
  }
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.
1275
+ return { url: pathToFileURL(resolve(this.root, file)).toString(), format: this.#loaderFormat(file) }
1276
+ }
1277
+
1278
+ // Resolve a CJS require() target to a bundled absolute path, or undefined to defer to Node (the
1279
+ // hooks.js CJS shim needs this: registerHooks can't intercept Module._resolveFilename). Matches
1280
+ // under ANY conditions bucket, since native require gives none; divergent buckets -> defer.
1707
1281
  resolveBundled(parentURL, specifier) {
1708
- let parent
1709
- try { parent = this.#canonicalFile(parentURL) } catch { return undefined }
1282
+ const parent = this.#canonicalFileMaybe(parentURL)
1283
+ if (parent === undefined) return undefined
1710
1284
  const spec = this.#canonicalSpecifier(parentURL, specifier)
1711
1285
  const matches = new Set()
1712
1286
  for (const [, byParent] of this.imports) {
1713
1287
  const file = byParent.get(parent)?.get(spec)
1714
1288
  if (file !== undefined) matches.add(file)
1715
1289
  }
1716
- return matches.size === 1 ? resolve(this.root, [...matches][0]) : undefined
1290
+ if (matches.size !== 1) return undefined
1291
+ const [only] = matches
1292
+ // Per-platform { platform: file } Map (--metro) has no single path: defer to native, not resolve()'s TypeError.
1293
+ return typeof only === 'string' ? resolve(this.root, only) : undefined
1717
1294
  }
1718
1295
 
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).
1296
+ // Union of lockfile-attested and live resolutions, so a partial lock=add run extends without
1297
+ // dropping edges. Conflicting targets are fatal (add semantics).
1724
1298
  #mergedImports() {
1725
1299
  const merged = new Map()
1726
1300
  const mergeIn = (imports) => {
1727
1301
  for (const [conditions, byParent] of imports) {
1728
- if (!merged.has(conditions)) merged.set(conditions, new Map())
1729
- const mergedParents = merged.get(conditions)
1302
+ const mergedParents = nestedMap(merged, conditions)
1730
1303
  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
- }
1304
+ const mergedSpecifiers = nestedMap(mergedParents, parent)
1305
+ for (const [specifier, file] of specifiers) noupsert(mergedSpecifiers, specifier, file)
1736
1306
  }
1737
1307
  }
1738
1308
  }
1739
1309
  if (this.#lockImports) mergeIn(this.#lockImports)
1740
1310
  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.
1311
+ // Write-mode sidecars too, so the lockfile attests their edges for frozen verify.
1744
1312
  for (const sidecar of this.#sidecars) mergeIn(sidecar.imports)
1745
1313
  return merged
1746
1314
  }
1747
1315
 
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.
1316
+ // Union of lockfile-attested and observed formats (+ sidecars'), append-only like #mergedImports,
1317
+ // except that a weak 'stat:*' is UPGRADED by real content; two real formats stay fatal.
1751
1318
  #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)
1319
+ const merged = new Map(this.#lockFormats ?? [])
1320
+ for (const [file, format] of this.formats) upsertFormat(merged, file, format)
1755
1321
  for (const sidecar of this.#sidecars) {
1756
- for (const [file, format] of sidecar.formats) noupsert(merged, file, format)
1322
+ for (const [file, format] of sidecar.formats) upsertFormat(merged, file, format)
1323
+ }
1324
+ // A payload-free 'stat:*' must never survive on a file that now carries a content hash: a stat
1325
+ // entry re-seeded from #lockFormats is beyond addFile's delete, and an ambiguous .js/.ts yields
1326
+ // no real format to override it above.
1327
+ for (const [file, format] of merged) {
1328
+ if (isStatFormat(format) && this.hashes.has(file)) merged.delete(file)
1757
1329
  }
1758
1330
  return merged
1759
1331
  }
1760
1332
 
1761
- get lockData() {
1333
+ // The executable list the LOCKFILE attests (this State's + write-mode sidecars'), narrowed by
1334
+ // scope to the keys it will SERIALIZE: a non-full-scope lockfile drops its workspace buckets, and
1335
+ // an entry for a dropped bucket writes a lockfile Lockfile.parse then refuses.
1336
+ #mergedExecutable(formats) {
1337
+ const all = new Set(this.executable)
1338
+ for (const sidecar of this.#sidecars) for (const file of sidecar.executable) all.add(file)
1339
+ return narrowExecutable(all, { modules: this.modules, formats, scope: this.config.scope })
1340
+ }
1341
+
1342
+ // The executable list ONE bundle declares, narrowed to that half's own buckets and formats.
1343
+ #bundleExecutable(modules, formats) {
1344
+ return narrowExecutable(this.executable, { modules, formats, scope: this.config.scope })
1345
+ }
1346
+
1347
+ get lockfile() {
1348
+ const formats = this.#mergedFormats()
1762
1349
  return new Lockfile({
1763
1350
  config: this.config.values,
1764
1351
  entries: this.entries,
1765
1352
  modules: this.modules,
1766
1353
  imports: this.#mergedImports(),
1767
- formats: this.#mergedFormats(),
1768
- }).serialize()
1354
+ formats,
1355
+ executable: this.#mergedExecutable(formats),
1356
+ })
1357
+ }
1358
+
1359
+ get lockData() {
1360
+ return this.lockfile.serialize()
1769
1361
  }
1770
1362
 
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.
1363
+ // Pair each module's recorded file list with content from perFile, dropping modules with none.
1775
1364
  #bundleModules(perFile) {
1776
1365
  const modules = new Map()
1777
1366
  for (const [dir, info] of this.modules) {
1778
1367
  const files = {}
1779
1368
  for (const rel of Object.keys(info.files)) {
1780
- const file = moduleFileKey(dir, rel)
1781
- const content = perFile.get(file)
1369
+ const content = perFile.get(moduleFileKey(dir, rel))
1782
1370
  if (content !== undefined) files[rel] = content
1783
1371
  }
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
- }
1372
+ if (Object.keys(files).length > 0) modules.set(dir, moduleInfo({ ...info, files }))
1789
1373
  }
1790
1374
  return modules
1791
1375
  }
1792
1376
 
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.
1377
+ // Files fs-READ after this point that a plugin also bundles are the plugin's, not run's (see
1378
+ // #bundleReason). Public, cross-copy.
1798
1379
  markPluginAttached() {
1799
1380
  this.#pluginAttached = true
1800
1381
  }
1801
1382
 
1802
- // Record which consumer (`reason`) observed `file`, for the bundle's informational `reason` map.
1803
1383
  #recordReason(reason, file) {
1804
1384
  let set = this.#reasonFiles.get(reason)
1805
1385
  if (set === undefined) this.#reasonFiles.set(reason, set = new Set())
1806
1386
  set.add(file)
1807
1387
  }
1808
1388
 
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.
1389
+ // Seed `reason` from an absorbed on-disk bundle so a bundle=add re-run preserves other consumers'
1390
+ // attribution. Called from every absorb site, including the sidecar's.
1391
+ #seedReasonFromBundle(bundle) {
1392
+ if (!this.config.writeBundle || bundle.reason === undefined) return
1393
+ for (const [consumer, files] of Object.entries(bundle.reason)) {
1394
+ for (const file of files) this.#recordReason(consumer, file)
1395
+ }
1396
+ }
1397
+
1398
+ // The bundle's informational `reason` map, restricted to `bundledFiles`; only when >1 consumer
1399
+ // contributed. Never attested.
1813
1400
  #bundleReason(bundledFiles) {
1814
1401
  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.
1402
+ // A file run merely fs-READ post-plugin that a plugin also bundles is the plugin's, not run's.
1818
1403
  const pluginFiles = new Set()
1819
1404
  for (const [who, recorded] of this.#reasonFiles) {
1820
- if (who === 'run') continue
1821
- for (const file of recorded) pluginFiles.add(file)
1405
+ if (who !== 'run') for (const file of recorded) pluginFiles.add(file)
1822
1406
  }
1823
1407
  const runOverclaims = (file) =>
1824
1408
  this.#fsReadPostPlugin.has(file) && !this.#runImported.has(file) && pluginFiles.has(file)
1825
1409
 
1826
1410
  const reason = {}
1827
1411
  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.
1412
+ // Sort keys and file lists: the JSON must be byte-reproducible regardless of record order, else
1413
+ // #emitBundle's compare-and-skip sees spurious diffs.
1831
1414
  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)
1415
+ const files = [...this.#reasonFiles.get(who)].filter((file) => inBundle.has(file) && !(who === 'run' && runOverclaims(file)))
1416
+ if (files.length > 0) {
1417
+ reason[who] = files.toSorted(sortPaths)
1418
+ consumers += 1
1837
1419
  }
1838
- if (files.length > 0) { reason[who] = files.toSorted(sortPaths); consumers += 1 }
1839
1420
  }
1840
1421
  return consumers > 1 ? reason : undefined
1841
1422
  }
1842
1423
 
1424
+ // The formats a bundle declares: `this.formats`, minus a 'stat:*' the run's unified attestation
1425
+ // upgraded to a real format (else the bundle fails its lockfile cross-check at load).
1426
+ #formatsForBundle() {
1427
+ if (this.#sidecars.size === 0) return this.formats
1428
+ const merged = this.#mergedFormats()
1429
+ let out = null // copy-on-write: clone only when an entry must be dropped
1430
+ for (const [file, format] of this.formats) {
1431
+ if (isStatFormat(format) && merged.get(file) !== format) {
1432
+ out ??= new Map(this.formats)
1433
+ out.delete(file)
1434
+ }
1435
+ }
1436
+ return out ?? this.formats
1437
+ }
1438
+
1439
+ #absorbRepo(half, bundle) {
1440
+ this.#absorbedRepos.set(half, this.#absorbedRepos.has(half) ? mergeRepo(this.#absorbedRepos.get(half), bundle.repo) : bundle.repo)
1441
+ }
1442
+
1443
+ get #detectedRepo() {
1444
+ return (this.#detectedRepoCache ??= { value: detectRepo(this.root, this.#host) }).value
1445
+ }
1446
+
1447
+ // `repo` to write for a half: detected, merged with that half's absorbed one when adding to it.
1448
+ #repoFor(half) {
1449
+ if (!this.#absorbedRepos.has(half)) return this.#detectedRepo
1450
+ const absorbed = this.#absorbedRepos.get(half)
1451
+ return absorbed && mergeRepo(absorbed, this.#detectedRepo)
1452
+ }
1453
+
1454
+ // One bundle artifact over `contents` (file -> stored content) with the `formats` it declares;
1455
+ // the code side carries entries/imports, the resources half none.
1456
+ #bundle(half, contents, formats, { entries = this.entries, imports = this.imports } = {}) {
1457
+ const modules = this.#bundleModules(contents)
1458
+ return new Bundle({
1459
+ config: this.config.values,
1460
+ entries,
1461
+ modules,
1462
+ formats,
1463
+ imports,
1464
+ executable: this.#bundleExecutable(modules, formats),
1465
+ reason: this.#bundleReason(contents.keys()),
1466
+ repo: this.#repoFor(half),
1467
+ })
1468
+ }
1469
+
1843
1470
  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.
1471
+ // One bundle holds code + resources, with `formats` tagging which; the key sets must be
1472
+ // disjoint, asserted so an overlap fails locally rather than silently.
1851
1473
  const contents = new Map(this.sources)
1852
1474
  for (const [file, content] of this.resources) {
1853
1475
  assert.ok(!contents.has(file), `state invariant: file ${file} in both sources and resources`)
1854
1476
  contents.set(file, content)
1855
1477
  }
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
- })
1478
+ return this.#bundle('code', contents, this.#formatsForBundle())
1864
1479
  }
1865
1480
 
1866
1481
  get sourceData() {
1867
1482
  return this.sourceBundle.serialize()
1868
1483
  }
1869
1484
 
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.
1485
+ // Split-bundle counterparts to sourceBundle/sourceData: the code half owns entries/imports + code
1486
+ // formats (stat records too: they aren't resource formats, so the resources half's shape check
1487
+ // would reject them), the resources half owns resource formats + bytes. Both declare per-dir
1488
+ // module identity so each file verifies alone.
1877
1489
  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
- })
1490
+ const codeFormats = new Map([...this.#formatsForBundle()].filter(([, format]) => !Bundle.isResourceFormat(format)))
1491
+ return this.#bundle('code', this.sources, codeFormats)
1893
1492
  }
1894
1493
 
1895
1494
  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
- })
1495
+ const resourceFormats = new Map([...this.formats].filter(([, format]) => Bundle.isResourceFormat(format)))
1496
+ // No entries/imports (Bundle.parse waives the entries requirement when no code).
1497
+ return this.#bundle('resources', this.resources, resourceFormats, { entries: new Set(), imports: new Map() })
1911
1498
  }
1912
1499
 
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.
1500
+ // Record a native resolution verbatim (last-write-wins per parent+specifier);
1501
+ // #backfillObservedResolutions decides at write() which to add.
1916
1502
  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.
1503
+ nestedMap(this.#observedResolutions, parentURL).set(specifier, resolvedURL)
1504
+ }
1505
+
1506
+ // Record that a require() executed `url` (from the Module._load shim). Out-of-root targets are
1507
+ // skipped like #backfillObservedResolutions' -- the live hooks correctly ignore them too.
1508
+ observeExecution(url) {
1509
+ const file = this.#canonicalFileMaybe(url)
1510
+ if (file !== undefined) this.#executedFiles.add(file)
1511
+ }
1512
+
1513
+ // Whether the bundle carries source bytes for `url` (the hooks' bundle-bypass reconciliation).
1514
+ isBundledSource(url) {
1515
+ const file = this.#canonicalFileMaybe(url)
1516
+ return file !== undefined && this.sources.has(file)
1517
+ }
1518
+
1519
+ // Attest every executed-but-never-captured file from disk. A resolve-only edge stays byte-less
1520
+ // by design (see #backfillBeforeWrite), but an EXECUTED file the load hook never saw is a hole:
1521
+ // leaving it silent would ship an artifact that misses code the run provably evaluated, and a
1522
+ // frozen replay would never verify it. addFile re-checks bytes against the lockfile/bundle in
1523
+ // frozen modes, so tampering still fails the run -- at write time, but loudly.
1524
+ #backfillExecutedFiles() {
1525
+ for (const file of this.#executedFiles) {
1526
+ // "Captured this run", NOT this.hashes: a lockfile-seeded hash must still be VERIFIED
1527
+ // against disk here when the run executed the file without the load hook observing it.
1528
+ if (this.#filesCapturedThisRun.has(file)) continue
1529
+ // A require()d native addon never passes the load hook and is deliberately not captured
1530
+ // (non-deterministic across installs, like the rest of NATIVE_ARTIFACT_EXTS).
1531
+ if (isNativeArtifact(file)) continue
1532
+ const url = pathToFileURL(resolve(this.root, file)).toString()
1533
+ if (!this.config.full && !this.inNodeModules(url)) continue
1534
+ this.addFile(url, { reason: 'run' })
1535
+ }
1536
+ }
1537
+
1538
+ // Backfill edges the live resolve hook never observed (require.resolve()/native CJS require()).
1539
+ // The resolution is attested but its bytes are NOT seeded -- that would widen trust to everything
1540
+ // that merely resolves. Skips out-of-scope targets and dedups across all condition buckets.
1948
1541
  #backfillObservedResolutions() {
1949
- if (this.#observedResolutions.size === 0) return
1950
1542
  for (const [parentURL, specs] of this.#observedResolutions) {
1951
- let parent
1952
- try { parent = this.#canonicalFile(parentURL) } catch { continue }
1543
+ const parent = this.#canonicalFileMaybe(parentURL)
1544
+ if (parent === undefined) continue
1953
1545
  for (const [specifier, resolvedURL] of specs) {
1954
- let file
1955
- try { file = this.#canonicalFile(resolvedURL) } catch { continue }
1546
+ const file = this.#canonicalFileMaybe(resolvedURL)
1547
+ if (file === undefined) continue
1956
1548
  const bundled = this.sources.has(file) || this.resources.has(file)
1957
1549
  if (!bundled && !this.config.full && !this.inNodeModules(resolvedURL)) continue
1958
1550
  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
- }
1551
+ const recorded = this.imports.values().some((byParent) => byParent.get(parent)?.get(spec) !== undefined)
1963
1552
  if (!recorded) this.addImport(parentURL, specifier, resolvedURL, { conditions: this.#requireConditions ?? '*' })
1964
1553
  }
1965
1554
  }
1966
1555
  }
1967
1556
 
1557
+ // Add every bundled module's `<dir>/package.json` (config.packageJSON) even if the run never
1558
+ // reached it, so a load/prune can read each dependency's manifest. The skip keys on bundle
1559
+ // membership, NOT this.hashes (which also holds lockfile-absorbed entries and is shared by
1560
+ // reference across sidecars).
1561
+ includePackageJson() {
1562
+ // Gather first: addFile mutates this.modules, so don't addFile while iterating it.
1563
+ const realRoot = this.#host.realpath(this.root)
1564
+ const toAdd = []
1565
+ for (const [dir, module] of this.modules) {
1566
+ const rel = moduleFileKey(dir, 'package.json')
1567
+ if (this.sources.has(rel) || this.resources.has(rel)) continue // already in this bundle
1568
+ const buf = readModuleManifest({ baseDir: this.root, realBase: realRoot, rel, host: this.#host })
1569
+ if (!buf) continue
1570
+ // Only carry a manifest whose on-disk identity still matches the bundled bucket: under
1571
+ // bundle=add a dep may have drifted, and addFile -> #locateModule would crash on it.
1572
+ let pkg
1573
+ try { pkg = JSON.parse(buf.toString()) } catch { continue } // malformed manifest for an untouched bucket: skip
1574
+ if (pkg?.name !== module.name || pkg?.version !== module.version) continue
1575
+ // The manifest rides along BECAUSE some consumer bundled the bucket, so it inherits every
1576
+ // consumer that recorded a file of the bucket -- nothing observed the manifest itself, but an
1577
+ // unattributed file can't be sorted by provenance downstream. Derived BEFORE the adds below,
1578
+ // so one fold's manifest can't count as another bucket's consumer evidence.
1579
+ const files = Object.keys(module.files)
1580
+ const consumers = [...this.#reasonFiles].filter(([, recorded]) => files.some((f) => recorded.has(moduleFileKey(dir, f)))).map(([who]) => who)
1581
+ toAdd.push({ rel, buf, consumers })
1582
+ }
1583
+ for (const { rel, buf, consumers } of toAdd) {
1584
+ this.addFile(pathToFileURL(resolve(this.root, rel)).toString(), { source: buf, reason: null })
1585
+ for (const who of consumers) this.#recordReason(who, rel)
1586
+ }
1587
+ }
1588
+
1968
1589
  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.
1590
+ // BEFORE the stasis-core BFS: a resolve-only edge to a stasis-core submodule is added only here,
1591
+ // and the BFS must see it to seed the file's bytes, else the bundle ships a dangling edge.
1980
1592
  this.#backfillObservedResolutions()
1593
+ this.#backfillExecutedFiles()
1981
1594
  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.
1595
+ // AFTER the backfills, so buckets they create are covered too.
1596
+ if (this.config.writeBundle && this.config.packageJSON) this.includePackageJson()
1993
1597
 
1598
+ // Sidecars never write the lockfile (parent owns it); they only emit their bundle.
1994
1599
  if (this.config.writeLockfile && !this.#parent) {
1995
1600
  const lockText = this.lockData
1996
1601
  if (lockText !== this.#lastLockData) {
@@ -2003,204 +1608,140 @@ export class State {
2003
1608
  if (this.config.writeBundle) {
2004
1609
  const sourcesPath = this.config.bundleFile || join(this.root, FILE_CODE)
2005
1610
  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())
1611
+ // hasContent gates each half so an empty one is dropped under bundle=replace.
1612
+ this.#lastCodeBundle = this.#emitBundle(sourcesPath, this.sources.size > 0, this.#lastCodeBundle, () => this.codeBundle.serialize())
1613
+ this.#lastResourcesBundle = this.#emitBundle(this.config.resourcesBundleFile, this.resources.size > 0, this.#lastResourcesBundle, () => this.resourcesBundle.serialize())
2017
1614
  } else {
2018
- this.#lastUnifiedBundle = this.#emitBundle(
2019
- sourcesPath, this.sources.size > 0 || this.resources.size > 0, this.#lastUnifiedBundle,
2020
- () => this.sourceData)
1615
+ this.#lastUnifiedBundle = this.#emitBundle(sourcesPath, this.sources.size > 0 || this.resources.size > 0, this.#lastUnifiedBundle, () => this.sourceData)
2021
1616
  }
2022
1617
  }
2023
1618
  }
2024
1619
 
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().
1620
+ // Snapshot of what THIS process observed, for a forked child to hand back to the root. Content is
1621
+ // omitted -- the root re-reads bytes from disk.
2032
1622
  shardSnapshot() {
2033
1623
  this.#backfillObservedResolutions()
1624
+ this.#backfillExecutedFiles()
2034
1625
  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.
1626
+ // Only what THIS process observed, never the seeded baseline (shard-size bloat). Entries are
1627
+ // dropped: a child's "entry" is its fork target, not a root's.
1628
+ const files = []
2059
1629
  const formats = new Map()
2060
1630
  for (const file of this.#observed) {
2061
- const fmt = this.formats.get(file)
2062
- if (fmt !== undefined) formats.set(file, fmt)
1631
+ const format = this.formats.get(file)
1632
+ if (format !== undefined) formats.set(file, format)
1633
+ if (this.hashes.has(file)) files.push(file)
2063
1634
  }
1635
+ // Only edges whose PARENT was observed, dropping the bundle-seeded ones the root already attests.
2064
1636
  const imports = new Map()
2065
1637
  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)
1638
+ for (const parent of this.#observed) {
1639
+ const specs = byParent.get(parent)
1640
+ if (specs !== undefined) nestedMap(imports, conditions).set(parent, specs)
2071
1641
  }
2072
1642
  }
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.
1643
+ return serializeShard({ scope: this.config.scope, files, formats, imports })
1644
+ }
1645
+
1646
+ // Merge a child's shardSnapshot() as if this process read those files itself: replay each file
1647
+ // (re-reading bytes/listings from disk) and each edge. Best-effort -- a gone/out-of-scope record is
1648
+ // skipped rather than aborting the merge.
1649
+ mergeShard(shardText) {
1650
+ const shard = parseShard(shardText)
1651
+ // Defense-in-depth: cross-scope is signature-rejected upstream, but a mismatch here means a
1652
+ // malformed/foreign shard -- refuse.
1653
+ assert.equal(shard.scope, this.config.scope, `shard scope "${shard.scope}" != root scope "${this.config.scope}"`)
1654
+ // An in-root shard KEY may resolve (through a symlink) OUTSIDE the root on THIS disk, so every
1655
+ // replay re-checks real-path containment -- the same boundary fs.js enforces on live --fs reads.
1656
+ let realRoot
1657
+ const realContained = (absolute) => {
1658
+ if (realRoot === undefined) {
1659
+ try { realRoot = realpathSync(this.root) } catch { realRoot = this.root }
1660
+ }
1661
+ let real
1662
+ try { real = realpathSync(absolute) } catch { return false }
1663
+ return isPathWithin(realRoot, real)
1664
+ }
1665
+ // Files first, then edges. Merged files are NEVER marked entries -- a child's "entry" is its
1666
+ // fork-target main, not a root entry.
1667
+ for (const file of shard.files) {
1668
+ const absolute = resolve(this.root, file)
1669
+ // Skip a key whose on-disk path escapes the root through a symlink.
1670
+ if (!realContained(absolute)) continue
1671
+ // ABOVE the already-attested fast path below: a child that re-read a file and found no bit
1672
+ // refutes it by OMISSION, so every file the shard RECORDS needs an observation. Re-derived
1673
+ // from THIS process's disk, so the shard cannot inject a forged bit.
1674
+ this.#recordExecutable(file, absolute)
1675
+ // Skip a file the root already attests (the byte re-read dominates merge cost), EXCEPT to
1676
+ // carry a concrete format the root LACKS, else a later frozen run rejects the unattested format.
1677
+ const format = shard.formats.get(file)
1678
+ if (this.hashes.has(file) && (format === undefined || (this.formats.get(file) ?? this.#lockFormats?.get(file)) !== undefined)) continue
1679
+ const url = pathToFileURL(absolute).toString()
1680
+ try {
1681
+ if (format === 'directory') {
1682
+ // Range-check FIRST so a child-forged `..` key can't make us list it.
1683
+ if (!isPathWithin(this.root, absolute)) continue
1684
+ this.addFsDir(url, readdirSync(absolute))
1685
+ } else if (format === 'resource' || format === 'resource:base64') {
1686
+ // Let addFile re-derive the exact resource tag from the re-read bytes rather than trusting
1687
+ // the shard's and risking a mismatch.
1688
+ this.addFile(url, { resource: true })
1689
+ } else if (format === undefined) {
1690
+ // No format recorded (an fs-READ .js/.ts): inferFormat:false so we don't bake in the
1691
+ // commonjs default and collide with the `module` the loader records if it's later imported.
1692
+ this.addFile(url, { inferFormat: false })
1693
+ } else {
1694
+ // Carry the child's format, else a child-only ESM .js under a no-`type` package re-defaults
1695
+ // to commonjs and a frozen run rejects the mismatch.
1696
+ this.addFile(url, { format })
2161
1697
  }
1698
+ } catch {
1699
+ // Gone/unreadable, or addFile-rejected (out of scope): skip, like the edge replay below.
2162
1700
  }
2163
1701
  }
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
- }
1702
+ // Stat records live ONLY in the shard's formats map, so replay each here, re-deriving the kind
1703
+ // from DISK (a shard can't inject a forged kind). Range-check BEFORE touching disk.
1704
+ for (const [file, format] of shard.formats) {
1705
+ if (!isStatFormat(format)) continue
1706
+ const absolute = resolve(this.root, file)
1707
+ if (!isPathWithin(this.root, absolute)) continue
1708
+ try {
1709
+ // statSync, NOT lstatSync: the child's capture followed symlinks, so this reproduces the kind
1710
+ // a legitimate shard carries where lstatSync would report the link and drop it.
1711
+ const stats = statSync(absolute)
1712
+ const kind = stats.isDirectory() ? 'directory' : stats.isFile() ? 'file' : null
1713
+ // statSync follows links: a symlink pointing OUT must not attest an external kind under an
1714
+ // in-root key.
1715
+ if (kind === null || !realContained(absolute)) continue
1716
+ this.addFsStat(pathToFileURL(absolute).toString(), kind)
1717
+ } catch {
1718
+ // Gone/dangling, or a kind conflict with the root's capture: skip.
1719
+ }
1720
+ }
1721
+ for (const [conditions, byParent] of shard.imports) {
1722
+ // Reverse #conditionsKey: '*', else a ', '-joined list with an optional ' (with: {json})'
1723
+ // suffix -- parse it so attributed edges merge under the child's key.
1724
+ let condStr = conditions
1725
+ let importAttributes
1726
+ const withAt = conditions.indexOf(' (with: ')
1727
+ if (withAt !== -1) {
1728
+ condStr = conditions.slice(0, withAt)
1729
+ try { importAttributes = JSON.parse(conditions.slice(withAt + ' (with: '.length, -1)) } catch { /* leave undefined */ }
1730
+ }
1731
+ const cond = condStr === '*' ? '*' : condStr.split(', ')
1732
+ for (const [parent, specs] of byParent) {
1733
+ const parentURL = pathToFileURL(resolve(this.root, parent)).toString()
1734
+ for (const [specifier, file] of specs) {
1735
+ const url = pathToFileURL(resolve(this.root, file)).toString()
1736
+ // Same best-effort stance as addFile above.
1737
+ try { this.addImport(parentURL, specifier, url, { conditions: cond, importAttributes }) } catch { /* skipped */ }
2188
1738
  }
2189
1739
  }
2190
1740
  }
2191
1741
  }
2192
1742
 
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.
1743
+ // Emit one bundle artifact, returning its new "last serialized" cache. Empty under bundle=replace
1744
+ // DELETES the file (a replace run is authoritative); unchanged text skips brotli + writeFileSync.
2204
1745
  #emitBundle(path, hasContent, lastText, serialize) {
2205
1746
  if (!hasContent && this.config.replaceBundle) {
2206
1747
  rmSync(path, { force: true })
@@ -2209,99 +1750,49 @@ export class State {
2209
1750
  const text = serialize()
2210
1751
  if (text !== lastText) {
2211
1752
  mkdirSync(dirname(path), { recursive: true })
2212
- writeFileSync(path, brotliCompressSync(text, brotliOptions()))
2213
- return text
1753
+ writeFileSync(path, brotliCompressSync(text, brotliOptions(this.config.brotliQuality)))
2214
1754
  }
2215
- return lastText
1755
+ return text
2216
1756
  }
2217
1757
 
2218
1758
  get parent() {
2219
1759
  return this.#parent
2220
1760
  }
2221
1761
 
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.
1762
+ // Capture stasis-core's own files + internal edges the live hooks missed: for a preload-cached
1763
+ // module the resolve hook records the edge but the load hook never fires. The BFS below is scoped
1764
+ // to the stasis-core src shape.
2237
1765
  #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
1766
  const missing = this.#collectMissingImportedFiles()
2244
1767
  if (missing.size === 0) return
2245
1768
 
2246
1769
  const isStasisCoreFile = (file) => STASIS_CORE_FILE_RE.test(`/${file}`)
2247
1770
 
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.
1771
+ // Only stasis-core files are reconstructed; everything else stays a resolution attested without
1772
+ // bytes (the load-time getFile gate, not this pass, enforces the trust boundary).
2259
1773
  const stasisCoreMissing = [...missing].filter((file) => isStasisCoreFile(file))
2260
1774
  if (stasisCoreMissing.length === 0) return
2261
1775
 
2262
1776
  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,
1777
+ assert.ok(preloadRel !== null && !relativeEscapes(preloadRel),
2271
1778
  `state.write() has imports referencing un-captured stasis-core files but no usable preloadRoot ` +
2272
1779
  `(preloadRoot=${this.#preloadRoot ?? 'unset'}). The live load hook missed an in-scope target -- ` +
2273
1780
  `investigate rather than silently patch: ${stasisCoreMissing.slice(0, 3).join(', ')}`)
2274
1781
 
2275
1782
  const PRELOAD_CONDITIONS = ['node', 'import', 'module-sync', 'node-addons']
2276
1783
  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
1784
  assert.ok(isStasisCoreFile(file),
2282
1785
  `state.write() backfill refused: '${file}' is not a stasis-core source file ` +
2283
1786
  `(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)
1787
+ // reason 'run': Node evaluated these before registerHooks could observe it (that blindness is
1788
+ // why this backfill exists), so they're run-loaded modules like any other. A consumer-less
1789
+ // record can't be sorted by provenance downstream (app code vs toolchain).
1790
+ this.addFile(pathToFileURL(resolve(this.root, file)).toString(), { reason: 'run' })
2303
1791
  }
2304
1792
 
1793
+ // Seeded from the missing files + every stasis-core file already in sources, to walk their
1794
+ // transitive imports too.
1795
+ const queue = [...stasisCoreMissing, ...[...this.sources.keys()].filter(isStasisCoreFile)]
2305
1796
  const processed = new Set()
2306
1797
  while (queue.length > 0) {
2307
1798
  const file = queue.shift()
@@ -2316,42 +1807,25 @@ export class State {
2316
1807
  const targetAbsolute = fileURLToPath(targetURL)
2317
1808
  let targetFile
2318
1809
  try { targetFile = this.relative(targetAbsolute) } catch { return }
2319
- if (!isStasisCoreFile(targetFile)) return
2320
- if (!existsSync(targetAbsolute)) return
1810
+ if (!isStasisCoreFile(targetFile) || !existsSync(targetAbsolute)) return
2321
1811
  queue.push(targetFile)
2322
1812
  this.addImport(baseURL, specifier, targetURL, { conditions: PRELOAD_CONDITIONS })
2323
1813
  }
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).
1814
+ // stasis-core's ESM import shape, tight enough to ignore JSDoc/template-literal false positives.
2329
1815
  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.
1816
+ // The src/package.cjs version shim, matched exactly.
2334
1817
  for (const m of source.matchAll(/require\('(\.\.\/package\.json)'\)/g)) recordEdge(m[1])
2335
1818
  }
2336
1819
  }
2337
1820
 
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.
1821
+ // Files referenced by this.imports but not captured, restricted to the in-scope set (out-of-scope
1822
+ // files are excluded -- the live hooks correctly skip them).
2344
1823
  #collectMissingImportedFiles() {
2345
1824
  const missing = new Set()
2346
1825
  for (const [, byParent] of this.imports) {
2347
1826
  for (const [, specifiers] of byParent) {
2348
1827
  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.
1828
+ if (typeof file !== 'string' || missing.has(file)) continue
2355
1829
  if (this.hashes.has(file) || this.sources.has(file) || this.resources.has(file)) continue
2356
1830
  const url = pathToFileURL(resolve(this.root, file)).toString()
2357
1831
  if (!this.config.full && !this.inNodeModules(url)) continue
@@ -2363,13 +1837,6 @@ export class State {
2363
1837
  }
2364
1838
  }
2365
1839
 
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`.
1840
+ // Backfillable stasis-core paths. Anchored against `/${file}` so a project-root file merely ending
1841
+ // in `@exodus/stasis-core/...` isn't matched.
2374
1842
  const STASIS_CORE_FILE_RE = /\/@exodus\/stasis-core\/(?:src\/[a-zA-Z-]+\.c?js|package\.json)$/
2375
-