@exodus/stasis-core 1.0.0-beta.14 → 1.0.0-beta.16

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