@exodus/stasis-core 1.0.0-beta.9 → 1.0.0-rc.0

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