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