@exodus/stasis-plugins 1.0.0-beta.2 → 1.0.0-beta.5

package/src/webpack.js

@@ -10,39 +10,21 @@ import { State } from '@exodus/stasis-core/state'
 import { realReadFileSync } from '@exodus/stasis-core/state-util'
 import { classifyExtension } from '@exodus/stasis-core/util'
 
-// A CJS require anchored at this ESM module, used only to optionally locate the
-// PROJECT's babel-plugin-module-resolver for the capture-time monkey-patch below.
-// stasis-plugins takes no dependency on it: the package is never imported statically, and
-// a project without it just skips the patch.
+// CJS require anchored here, used only to locate the PROJECT's babel-plugin-module-resolver below.
 const require = createRequire(import.meta.url)
 
-// Original package.json "imports" subpath specifiers ('#app/abc.js') recovered by the
-// babel-plugin-module-resolver monkey-patch (see StasisWebpack#patchModuleResolver),
-// keyed by `${importerAbsolute}\0${rewrittenRequest}` -> the original '#'-specifier(s).
-// The value is an ARRAY: usually one, but more than one when several subpath aliases map to the
-// SAME file from the same importer (they all rewrite to the identical relative request, colliding
-// on one key). afterResolve records an edge for EACH, so no subpath import is silently dropped.
-// Module-level (not per-instance) so the single patch -- installed by whichever plugin
-// instance applies first -- and every instance's afterResolve lookup share one map; the
-// patch wrapper and the lookup both live in THIS module, so the closure reference agrees.
-// Intentionally never cleared: keys are deterministic (absolute importer + rewritten request)
-// and values are deduped, so a watch rebuild RE-RECORDS the same entries idempotently rather
-// than accumulating -- bounded by the project's '#'-edge count. Not scoped per build because a
-// parallel MultiCompiler would race a per-`done` clear,
-// and entries are tiny (~a path + a short specifier). The only unbounded case is a long-lived
-// process building MANY DISTINCT graphs (e.g. a build server with per-run temp dirs); that's
-// outside stasis's per-`stasis run`-process model, so the simplicity wins.
+// Recovered package.json "imports" subpaths ('#app/abc.js'), keyed by (importerAbsolute, NUL,
+// rewrittenRequest) -> array of original '#'-specifier(s) (several aliases can collide on one key,
+// so afterResolve records an edge for each). Module-level so the single patch and every instance's
+// lookup share it; never cleared (keys deterministic, values deduped).
 const subpathOriginals = new Map()
 const edgeKey = (importerAbsolute, request) => `${importerAbsolute}\u0000${request}`
 
-// Marks an already-wrapped chokepoint so watch rebuilds / multiple plugin instances
-// don't double-wrap babel-plugin-module-resolver.
+// Marks an already-wrapped chokepoint so we don't double-wrap babel-plugin-module-resolver.
 const PATCHED = Symbol('stasis.modresolver.patched')
 
-// Synthetic stat for files served from the bundle in load mode. Webpack's resolver
-// + module factory call inputFileSystem.stat() to check existence and read size;
-// we don't keep the real mtime/mode/etc., they're not security-relevant here (the
-// lockfile already attests content via hash; getFile re-verifies on every read).
+// Synthetic stat for bundle-served files in load mode: webpack's resolver only needs existence +
+// size; mtime/mode aren't security-relevant (the lockfile attests content via hash).
 function bundleStat(size, isDir = false) {
   return {
     isFile: () => !isDir,
@@ -78,25 +60,19 @@ export class StasisWebpack {
   #state
   #resources
 
-  // Number of compilers this (capture-mode) instance is applied to. webpack constructs every
-  // compiler -- and runs every plugin's apply() -- before any build starts, so by the first
-  // `done` this is final: 1 for a lone compiler, N when one shared instance drives a
-  // MultiCompiler's N child compilers. Only the latter accumulates files into one State across
-  // N `done`s, which is the case worth deferring (see the done hook).
+  // Number of compilers this instance drives (final by the first `done`): 1 for a lone compiler,
+  // N for a MultiCompiler. Only the multi case accumulates across N `done`s and defers its write.
   #captureApplyCount = 0
 
-  // Deferred-write bookkeeping for the MULTI-compiler one-shot case, see #deferWrite. #armed:
-  // whether the single beforeExit/exit flush pair has been registered (idempotent across the
-  // N child-compiler `done`s a MultiCompiler fires). #dirty: a clean build completed since the
-  // last flush, so there is something to write.
+  // Deferred-write bookkeeping for the multi-compiler case (see #deferWrite). #armed: the single
+  // flush pair is registered; #dirty: a clean build completed since the last flush.
   #deferredWriteArmed = false
   #deferredWriteDirty = false
 
   constructor(options = {}) {
     const { state } = resolvePluginState('StasisWebpack', options, process.cwd())
     this.#state = state  // null when plugin should be inert
-    // resources is a Config field now (validated + coordinated against any preload in
-    // resolvePluginState); cache the resolved Set for the per-file classify hot path.
+    // Cache the resolved resources Set for the per-file classify hot path.
     this.#resources = state?.config.resources ?? new Set()
   }
 
@@ -109,54 +85,18 @@ export class StasisWebpack {
     this.#applyCaptureMode(compiler)
   }
 
-  // Load mode: mirrors `stasis run --bundle=load` for the webpack plugin context.
-  // The decision "serve from bundle vs defer to disk" depends solely on bundle
-  // mode + scope, never on whether the path happens to live in the bundle -- a
-  // missing in-scope file is a hard error, not a silent disk fallback.
-  //   In scope:
-  //     - full scope: every path under state.root is in scope; everything outside
-  //       the project root is genuinely external (system files, OS paths) and
-  //       defers to disk
-  //     - node_modules scope: node_modules paths under state.root only; app
-  //       sources are deliberately disk-served
-  //   Wiring:
-  //     - inputFileSystem.readFile / stat: in-scope paths MUST come from the
-  //       bundle (getFile re-verifies the hash against the lockfile); a path no
-  //       bundle carries throws rather than falling back to disk. "The bundle"
-  //       here is the FAMILY -- this State plus its parent when the plugin runs
-  //       as a sidecar (its app-graph bundle alongside the ambient preload's
-  //       build-closure bundle, both under the one shared lockfile). stat serves
-  //       a synthetic directory Stats for any dir the family records (explicit
-  //       capture or one implied by a bundled descendant) so the resolver's walk
-  //       over intermediate dirs short-circuits without touching disk
-  //     - normalModuleFactory.hooks.beforeResolve: an in-scope (issuer, request)
-  //       edge the bundle attests is redirected to its absolute bundle path. A
-  //       request the bundle records no edge for is not a file the bundle carries
-  //       -- at a successful capture it was EXTERNALIZED (a Node built-in,
-  //       `electron` under an electron target, a user `externals` entry); those
-  //       are never recorded as edges, so we defer to webpack's resolver/externals
-  //       handling. This relaxes only the resolve-time EDGE lookup; the fail-closed
-  //       gate for in-scope file BYTES stays the inputFileSystem wrapper above,
-  //       which still serves every in-scope read from the bundle or throws.
-  //     - Out-of-scope paths defer to disk
-  //
-  //   KNOWN LIMITATION: every path the resolver touches must be attested by some
-  //   family bundle. Intermediate-directory stats are covered (getFsStat over the
-  //   family, including dirs implied by a parent-bundle file -- e.g. a webpack
-  //   loader's directory). The residual gap is the package.json files webpack's
-  //   resolver reads via fs.readFile through DescriptionFilePlugin: the Node run
-  //   loader captures modules Node IMPORTS, not arbitrary resolver fs.readFile
-  //   calls, so a package.json neither bundle carries still fails closed here.
-  //   Capturing those (or a description-file shortcut) is the remaining work; see
-  //   `tests/webpack.test.js` and its skipped TODO.
+  // Load mode: mirrors `stasis run --bundle=load`. In-scope paths MUST come from the bundle
+  // (getFile re-verifies the hash); a missing in-scope file is a hard error, never a silent disk
+  // fallback. In scope = full (everything under state.root) or node_modules-only per scope.
+  // "The bundle" is the FAMILY -- this State plus its parent when running as a sidecar (both under
+  // one shared lockfile). KNOWN LIMITATION: package.json the resolver reads via fs.readFile
+  // (DescriptionFilePlugin) that no family bundle carries still fails closed -- see tests/webpack.test.js TODO.
   #applyLoadMode(compiler) {
     const state = this.#state
     const orig = compiler.inputFileSystem
 
-    // True iff `p` is a path the bundle is supposed to cover under load mode.
-    // `state.relative` throws for paths outside `state.root`, which we treat as
-    // out-of-scope (system files, /tmp scratch, ...). state.inNodeModules is
-    // itself tolerant of un-canonicalizable URLs.
+    // True iff `p` is in scope for load mode. state.relative throws outside state.root (treated
+    // as out-of-scope: system files, scratch).
     const inScope = (p) => {
       if (typeof p !== 'string') return false
       try { state.relative(p) } catch { return false }
@@ -164,39 +104,21 @@ export class StasisWebpack {
       return state.inNodeModules(pathToFileURL(p).toString())
     }
 
-    // The plugin's State may be a SIDECAR: when its bundleFile differs from the
-    // ambient preload's, resolvePluginState (Rule 6) gives the plugin its own
-    // State carrying the webpack app graph, parented to the ambient. The webpack
-    // app graph lives in the sidecar's bundle, but build-time machinery the
-    // resolver must see -- webpack loaders (babel-loader, ts-loader, ...) and the
-    // directories/package.json along their resolution path -- lives in the PARENT
-    // (ambient) bundle, captured when `stasis run` drove the build. Both bundles
-    // validate against the SAME shared lockfile (the sidecar inherits the parent's
-    // #lockImports/#lockFormats), so the attested set the build may touch is the
-    // whole family: this State plus its parent. Consult them in order -- the
-    // sidecar's own app graph first -- so a path either bundle attests is served
-    // from the bundle that carries it. With no parent (the reuse case: one unified
-    // bundle) the family is just `state`, and behavior is unchanged.
+    // Family = the sidecar's own app-graph bundle first, then its parent (loaders + resolution-path
+    // dirs the ambient preload captured). Both share one lockfile; no parent -> just [state].
     const family = state.parent ? [state, state.parent] : [state]
-    // The first family State that attests `url` (as a file or directory), else
-    // undefined. getFsStat is a pure existence check over each bundle's recorded
-    // files/resources/dirs; it never reads bytes or touches disk.
+    // First family State that attests `url` (file or dir), else undefined. Pure existence check.
     const ownerOf = (url) => family.find((s) => s.getFsStat(url) !== undefined)
 
-    // getFile re-verifies the hash against the lockfile on every read (tampered
-    // bundle fails closed). Serve from whichever family bundle carries the path;
-    // a path NO family bundle attests falls through to state.getFile, whose throw
-    // is the canonical fail-closed gate -- an in-scope miss surfaces here, never
-    // a silent disk fallback.
+    // Serve from whichever family bundle carries the path; getFile re-verifies the hash and throws
+    // on a miss (the fail-closed gate -- never a silent disk fallback).
     const serveFromBundle = (p) => {
       const url = pathToFileURL(p).toString()
       return (ownerOf(url) ?? state).getFile(url).source
     }
 
-    // Wrap inputFileSystem. CachedInputFileSystem stores internal state on `this`,
-    // so a naive Object.create or Object.assign would strand methods like readdir
-    // / lstat / purge that aren't intercepted; a Proxy keeps `this` pointing at
-    // orig for forwarded calls and only overrides readFile and stat.
+    // Proxy (not Object.assign): CachedInputFileSystem stores state on `this`, so forwarded calls
+    // must keep `this` = orig; we override only readFile and stat.
     const wrappedReadFile = (p, options, callback) => {
       if (typeof options === 'function') { callback = options; options = undefined }
       if (inScope(p)) {
@@ -208,33 +130,22 @@ export class StasisWebpack {
           return callback(err)
         }
       }
-      // Only forward `options` when caller actually provided one. webpack's
-      // CachedInputFileSystem.readFile is `(path, callback)`-shaped (no options
-      // slot); passing `undefined` in the middle would land in its callback
-      // position and Storage.finished would later try to invoke `undefined(...)`.
+      // Forward `options` only when provided: CachedInputFileSystem.readFile is (path, callback);
+      // an undefined middle arg lands in the callback slot and later crashes Storage.finished.
       if (options === undefined) return orig.readFile(p, callback)
       return orig.readFile(p, options, callback)
     }
     const wrappedStat = (p, callback) => {
       if (inScope(p)) {
-        // A directory has no bundle content, so serveFromBundle/getFile (which only
-        // attests files) throws "file not attested" on it. webpack's resolver stat()s
-        // intermediate directories (`<root>`, `<root>/node_modules`, `.../<pkg>`) while
-        // walking, so serve a directory Stats from the family's existence record
-        // (getFsStat covers explicit `directory` captures AND dirs implied by a bundled
-        // file under them -- e.g. `node_modules/<loader>` implied by the loader's files
-        // in the PARENT bundle). This is what the async resolver tripped on; the sync
-        // path happened to work only because the Proxy wraps stat but not statSync.
+        // Directories have no bundle content, so serve a synthetic dir Stats from the family's
+        // existence record (getFsStat) -- webpack's resolver stat()s intermediate dirs while walking.
         const url = pathToFileURL(p).toString()
         if (ownerOf(url)?.getFsStat(url) === 'directory') {
           return callback(null, bundleStat(0, true))
         }
         try {
           const src = serveFromBundle(p)
-          // Use byte length, not String.length -- a multibyte-UTF-8 code source
-          // (sources are strings; see state.getFile) has fewer JS-chars than
-          // bytes-on-disk. Webpack 4 only uses stat.size for display, but the
-          // discrepancy would still be wrong if any downstream consumer slices.
+          // Byte length, not String.length -- a multibyte-UTF-8 source has fewer JS chars than bytes.
           const size = typeof src === 'string' ? Buffer.byteLength(src) : src.length
           return callback(null, bundleStat(size))
         } catch (err) {
@@ -256,76 +167,37 @@ export class StasisWebpack {
       nmf.hooks.beforeResolve.tap('Stasis', (data) => {
         const issuer = data.contextInfo?.issuer
         if (!issuer) return  // entries: already absolute, inputFileSystem covers them
-        // Out-of-scope parents (nm-scope app code, webpack-internal loader
-        // resolution) were never the bundle's responsibility to attest -- defer
-        // to webpack's resolver.
+        // Out-of-scope parents were never the bundle's responsibility -- defer to webpack's resolver.
         if (!inScope(issuer)) return
-        // Node built-ins (`constants`, `fs`, `node:path`, ...) are never bundled and
-        // never recorded as edges: the capture-side resolve hook and CJS resolution
-        // shim (stasis-core/hooks.js) short-circuit isBuiltin() specifiers to Node
-        // before addImport sees them. Skip them up front -- defer to webpack
-        // (target:'node' externalizes them, a browser target polyfills them) and,
-        // crucially, NEVER consult getImport for a builtin name, so a tampered
-        // bundle can't smuggle in an edge that redirects `fs` to an arbitrary file.
+        // Built-ins are never bundled or recorded as edges; skip up front. SECURITY: never consult
+        // getImport for a builtin name, so a tampered bundle can't redirect `fs` to an arbitrary file.
         if (isBuiltin(data.request)) return
         const parentURL = pathToFileURL(issuer).toString()
         let resolved
         try {
           resolved = state.getImport(parentURL, data.request)
         } catch (err) {
-          // No attested edge. getImport tried the recorded edge under every conditions
-          // bucket (resolveBundled), so a miss means the request names nothing the
-          // bundle carries. At a SUCCESSFUL capture that is an EXTERNAL -- a module
-          // webpack externalized instead of bundling: `electron` under an electron
-          // target, anything the target's
-          // externals preset covers, or a user `externals` entry. Externals are
-          // never recorded as edges (afterResolve only records resolutions with an
-          // on-disk path; see #applyCaptureMode), exactly like built-ins -- so defer
-          // to webpack's resolver/externals handling rather than failing the build.
-          // This relaxes ONLY the resolve-time edge lookup: a genuinely missing
-          // in-scope FILE still fails closed at the inputFileSystem wrapper (it
-          // serves in-scope bytes from the bundle or throws), so no disk fallback
-          // is introduced. A non-MODULE_NOT_FOUND error is a real fault -- rethrow.
+          // No attested edge -- at a successful capture that's an EXTERNAL (never recorded as an
+          // edge), so defer to webpack. File BYTES still fail closed at the inputFileSystem wrapper.
+          // A non-MODULE_NOT_FOUND error is a real fault -- rethrow.
           if (err?.code === 'ERR_MODULE_NOT_FOUND') return
           throw err
         }
-        // Redirect the resolver to the absolute bundle path; our stat wrapper
-        // then reports it exists, so the resolver short-circuits without
-        // walking node_modules or trying extension fallbacks.
+        // Redirect the resolver to the absolute bundle path; the stat wrapper then reports it exists.
         data.request = fileURLToPath(resolved.url)
       })
     })
   }
 
-  // babel-plugin-module-resolver is the babel plugin webpack-4 builds use to make
-  // package.json "imports" subpaths resolvable: webpack 4's enhanced-resolve has no
-  // imports-field support, so a '#app/abc.js' specifier MUST be rewritten in source
-  // (to an importer-relative '../../abc.js') before webpack's parser sees it. That
-  // rewrite happens in a LOADER, before the parser builds the dependency, so by
-  // afterResolve webpack's rawRequest is the resolved relative path and the original
-  // '#'-specifier is gone from every field. To record the ORIGINAL specifier as the
-  // import key -- it's portable (resolves within the importer's OWN package regardless
-  // of layout) and is what every other capture backend records (the Node loader's
-  // resolve hook and Metro both key edges by the as-written specifier) -- hook the
-  // rewrite at its source. The plugin has a single rewrite chokepoint that reads the
-  // original `nodePath.node.value`, resolves it, then replaceWith()s the result;
-  // across majors it is `lib/mapPath.js`'s default export (v5) or `lib/utils.js`'s
-  // `mapPathString` (v3/v4). Wrap whichever the PROJECT'S copy exposes and record
-  // (importer, rewritten) -> original for each '#'-rewrite; afterResolve then keys the
-  // edge by the original instead of the resolved relative rawRequest.
-  //
-  // Best-effort and side-effect-only: a project without babel-plugin-module-resolver
-  // (no '#'-rewriting in play) skips the patch entirely and capture is unchanged. The
-  // wrapper is a transparent passthrough -- it never alters the rewrite, only observes
-  // it -- so leaving it installed across watch rebuilds is harmless; PATCHED guards
-  // against re-wrapping. stasis-plugins takes no dependency on it: it is located
-  // via the project's own node_modules (createRequire) and absent-package errors are
-  // swallowed.
+  // webpack 4's enhanced-resolve has no imports-field support, so babel-plugin-module-resolver
+  // rewrites '#app/abc.js' subpaths in a loader before the parser -- by afterResolve the original
+  // '#'-specifier is gone. Wrap the plugin's rewrite chokepoint (v5 lib/mapPath default export, or
+  // v3/v4 lib/utils.mapPathString) to record (importer, rewritten) -> original, so afterResolve can
+  // key the edge by the portable original. Best-effort, side-effect-only passthrough; absent package
+  // skips the patch; PATCHED guards against re-wrapping.
   #patchModuleResolver() {
     const paths = [this.#state.root, process.cwd()]
-    // No `"exports"` map in any major, so deep `/lib/...` requires resolve fine. Try the
-    // v5 chokepoint first, then the v3/v4 one; wrap every shape the copy actually exposes
-    // (a stale-but-uninvoked export is never called, so a double-wrap can't double-record).
+    // Deep /lib/... requires resolve (no "exports" map). Try v5 then v3/v4; wrap every shape present.
     const candidates = [
       { sub: 'babel-plugin-module-resolver/lib/mapPath', prop: 'default' },
       { sub: 'babel-plugin-module-resolver/lib/utils', prop: 'mapPathString' },
@@ -344,16 +216,13 @@ export class StasisWebpack {
         const result = original.apply(this, arguments)
         try {
           const after = nodePath?.node?.value
-          // Only package.json "imports" subpaths ('#'-prefixed) are recovered; any other
-          // module-resolver alias keeps webpack's rawRequest. A node that didn't actually
-          // change (after === before) records nothing.
+          // Only '#'-prefixed subpaths are recovered (other aliases keep webpack's rawRequest);
+          // an unchanged node records nothing.
           if (typeof before === 'string' && before.startsWith('#') &&
               typeof after === 'string' && after !== before) {
             const importer = state?.file?.opts?.filename
             if (typeof importer === 'string') {
-              // Append, don't overwrite: two distinct subpath aliases that resolve to the same
-              // file from this importer rewrite to the identical `after`, so they share one key.
-              // Keeping both (deduped) lets afterResolve record an edge for each.
+              // Append (deduped), don't overwrite: aliases colliding on one key each need an edge.
               const key = edgeKey(path.resolve(importer), after)
               const originals = subpathOriginals.get(key)
               if (originals === undefined) subpathOriginals.set(key, [before])
@@ -371,29 +240,15 @@ export class StasisWebpack {
   }
 
   #applyCaptureMode(compiler) {
-    // Count compilers this instance drives (final by the first `done`; see the field comment).
     this.#captureApplyCount += 1
-    // Install the babel-plugin-module-resolver hook before the build runs (apply() is
-    // called synchronously at webpack() construction, before compiler.run()), so the
-    // recorder is populated by the loader pass before afterResolve looks an edge up.
+    // Install the module-resolver hook now (apply() runs at webpack() construction, before
+    // compiler.run()), so the recorder is populated before afterResolve looks an edge up.
     this.#patchModuleResolver()
     compiler.hooks.normalModuleFactory.tap('Stasis', (nmf) => {
-      // webpack 4's resolver reuses `resourceResolveData.context.issuer` across
-      // factory invocations -- by the time `afterResolve` fires for a given
-      // dependency, that field can hold the issuer from an EARLIER resolution.
-      // The resolved path (rrd.path) is still correct, so webpack's bundle is
-      // fine, but a plugin reading rrd.context.issuer for parent attribution
-      // would mis-bucket the edge. Reproduced under webpack@4.15.1 and 4.47.0
-      // (see tests/fixtures/webpack-stale-issuer-repro/NOTES.md for the
-      // BEFORE-vs-AFTER trace evidence).
-      //
-      // beforeResolve's `data.contextInfo.issuer` is the fresh value passed
-      // into create() for this exact dependency, so capture it there keyed
-      // by the dependency object and look it up in afterResolve. The same
-      // `data.dependencies[0]` reference flows through the create() pipeline
-      // unchanged (NormalModuleFactory passes the array through to factory()
-      // -> resolver -> afterResolve), so a WeakMap keyed on dep[0] keeps the
-      // mapping correct without holding refs after the dep is GC'd.
+      // webpack 4's resolver reuses rrd.context.issuer across factory invocations, so by
+      // afterResolve it can hold an EARLIER resolution's issuer (repro: webpack@4.15.1/4.47.0, see
+      // tests/fixtures/webpack-stale-issuer-repro/NOTES.md). beforeResolve's contextInfo.issuer is
+      // fresh, so capture it there in a WeakMap keyed by dep[0] (the same ref flows through create()).
       const issuerByDep = new WeakMap()
       nmf.hooks.beforeResolve.tap('Stasis', (data) => {
         const dep = data?.dependencies?.[0]
@@ -402,23 +257,11 @@ export class StasisWebpack {
       })
 
       nmf.hooks.afterResolve.tap('Stasis', (data) => {
-        // Cross-version field unwrap: webpack 5 wraps `rawRequest` and
-        // `resourceResolveData` inside `data.createData` (the bundle of fields
-        // that will populate the NormalModule), whereas webpack 4 hangs them off
-        // `data` directly. Same field names underneath, just one level of
-        // indirection -- fall through to `data` when `createData` is absent so
-        // both shapes flow through the same code path below.
+        // Cross-version unwrap: webpack 5 nests rawRequest/resourceResolveData under createData;
+        // webpack 4 hangs them off data. Fall through to data when createData is absent.
         const cd = data.createData ?? data
-        // resourceResolveData.path is the resolved on-disk path without query/fragment;
-        // data.resource may carry a `?query` (inline-loader, asset import suffixes) or
-        // be a synthetic resource (data:, null-loader). We track the resolved file only.
-        //
-        // Silent skip: data: URIs, null-loader stubs, and any resolution that
-        // produced no on-disk path bypass capture entirely. If the same underlying
-        // file is reachable through a non-null-loader path elsewhere in the graph
-        // it'll get captured then; otherwise it stays unattested. This matches
-        // webpack's view -- those resolutions don't have a real source file we
-        // could hash.
+        // Track the resolved on-disk path (resourceResolveData.path, no query/fragment). Silently
+        // skip data: URIs, null-loader stubs, and any resolution with no on-disk file to hash.
         const filePath = cd.resourceResolveData?.path
         if (!filePath || !path.isAbsolute(filePath) || !existsSync(filePath)) return
 
@@ -431,16 +274,9 @@ export class StasisWebpack {
         }
 
         const url = pathToFileURL(filePath).toString()
-        // Issuer attribution -- tier the sources from most reliable to least:
-        //   1. beforeResolve-captured value (works on both webpack 4 and 5;
-        //      necessary on webpack 4 to dodge the stale rrd.context.issuer bug)
-        //   2. data.contextInfo.issuer (fresh in webpack 5's afterResolve, often
-        //      undefined in webpack 4's, but harmless when set)
-        //   3. createData.resourceResolveData.context.issuer (webpack 4 only --
-        //      enhanced-resolve 5 removed `context.issuer` from ResolveRequest, so
-        //      tier 3 is structurally dead under webpack 5. Kept as a defensive
-        //      last resort for any stacked plugin that reached afterResolve
-        //      without firing beforeResolve on webpack 4.)
+        // Issuer attribution, most reliable first: (1) beforeResolve WeakMap (dodges the webpack 4
+        // stale-issuer bug), (2) contextInfo.issuer (fresh on webpack 5), (3) rrd.context.issuer
+        // (webpack 4 only; enhanced-resolve 5 removed it).
         const dep = data?.dependencies?.[0]
         const issuer = (dep && issuerByDep.get(dep))
           ?? data.contextInfo?.issuer
@@ -451,14 +287,9 @@ export class StasisWebpack {
         if (kind === 'code' && !isEntry) {
           const issuerAbsolute = path.resolve(issuer)
           const parentURL = pathToFileURL(issuerAbsolute).toString()
-          // When babel-plugin-module-resolver rewrote one or more package.json "imports"
-          // subpaths ('#app/abc.js') into this resolved-relative rawRequest, the monkey-patch
-          // (#patchModuleResolver) recorded the original specifier(s) for this exact
-          // (importer, rewritten-request) edge. Key the edge by each ORIGINAL instead of the
-          // position-coupled relative path: it round-trips at load (where the same subpath
-          // reaches beforeResolve) and activates state.js's resolveBundled '#'-handling. Several
-          // aliases can collapse onto one rawRequest, so record an edge per original. No rewrite
-          // seen -> fall back to webpack's rawRequest unchanged.
+          // If babel-plugin-module-resolver rewrote '#' subpaths into this rawRequest, key the edge
+          // by each recorded ORIGINAL (portable, round-trips at load) instead of the relative path;
+          // no rewrite -> fall back to rawRequest.
           const originals = subpathOriginals.get(edgeKey(issuerAbsolute, rawRequest))
           for (const specifier of originals ?? [rawRequest]) {
             this.#state.addImport(parentURL, specifier, url)
@@ -467,35 +298,20 @@ export class StasisWebpack {
 
         if (!this.#seen.has(filePath)) {
           this.#seen.add(filePath)
-          // Read through the REAL reader: this capture read is the plugin's own bookkeeping,
-          // not a program fs read, so under `stasis run --fs` it must not be recorded into
-          // the preload/main bundle (it belongs to THIS plugin's bundle). See state-util.js.
+          // Real reader (state-util.js): plugin bookkeeping, must not be re-recorded under --fs.
           const source = realReadFileSync(filePath)
-          // Code-classified files must be UTF-8. A code extension with non-UTF-8
-          // bytes is malformed input (e.g. a .json mis-saved as UTF-16); refuse
-          // it rather than silently encoding it as a resource. Resource-classified
-          // files are passed through as-is -- State picks 'resource' vs
-          // 'resource:base64' from content.
+          // Code-classified files must be UTF-8; refuse non-UTF-8 rather than silently encode as a resource.
           if (kind === 'code') {
             assert.ok(isUtf8(source), `StasisWebpack: code-classified file has non-UTF-8 bytes: ${filePath}`)
           }
-          this.#state.addFile(url, { source, isEntry, resource: kind === 'resource', reason: 'StasisWebpack' })
+          this.#state.addFile(url, { source, isEntry, resource: kind === 'resource', reason: 'webpack' })
         }
       })
     })
 
-    // Watch-mode capture is EXPLICITLY UNSUPPORTED -- refuse it loudly before anything is
-    // captured. Capture's dedupe is keyed by PATH, not content (#seen above, plus State.write's
-    // compare-and-skip caches), so on a watch rebuild where a file's bytes changed the plugin
-    // would skip re-capture: the emitted output would use the new bytes while the bundle /
-    // lockfile silently kept attesting the OLD ones. Rather than track content changes across
-    // rebuilds, refuse watch outright. compiler.hooks.watchRun fires ONLY under
-    // compiler.watch() (both webpack 4 and 5) and BEFORE the first watch build's compilation,
-    // so this rejects the whole watch session up front, not just the second build. watchRun is
-    // an AsyncSeriesHook: a sync `.tap` callback that throws propagates through the hook's call
-    // chain and fails the watcher -- exactly the loud refusal we want, so keep it a plain tap.
-    // Load mode is deliberately untouched (see #applyLoadMode): it serves immutable attested
-    // bytes back into the build, so a dev-server rebuild has no drift hazard there.
+    // Watch-mode capture is unsupported: dedupe is keyed by PATH not content, so a rebuild with
+    // changed bytes would emit new bytes while the bundle/lockfile keep the OLD ones. watchRun fires
+    // only under compiler.watch(), before the first build, so throwing here refuses the whole session.
     compiler.hooks.watchRun.tap('Stasis', () => {
       throw new Error(
         'StasisWebpack: watch mode is not supported for capture -- ' +
@@ -503,59 +319,33 @@ export class StasisWebpack {
       )
     })
 
-    // The stasis preload owns its own write via beforeExit/exit hooks (stasis-core/hooks.js).
-    // Standalone and sidecar States have no such hook, so the plugin writes them when the
-    // compiler finishes -- but only on a clean build. A failed compilation has incomplete
-    // state, and lock=replace would otherwise overwrite a good lockfile with a partial one.
+    // The preload writes itself (hooks.js); standalone/sidecar States are written on compiler
+    // finish -- only on a clean build (a partial one would overwrite a good lockfile).
     if (this.#state !== State.preload) {
       compiler.hooks.done.tap('Stasis', (stats) => {
         if (stats.hasErrors()) return
-        // Write immediately for a single compiler: only one `done`, so there is no N-write
-        // amplification and no reason to give up the old write-by-`done` durability (the
-        // bundle is on disk by the time compiler.run()'s callback resolves). Defer ONLY the
-        // multi-compiler one-shot case. compiler.hooks.done fires once PER CHILD COMPILER, so
-        // a MultiCompiler with N targets sharing this one State's growing bundle would
-        // otherwise pay N brotli + writeFileSync passes over an ever-larger payload (the
-        // dominant, super-linear cost). Deferral collapses those into ONE write of the final
-        // bundle at process exit -- mirroring how the preload writes (hooks.js). Watch mode
-        // never reaches this hook: capture refuses it at watchRun above. esbuild / metro
-        // are deliberately NOT changed: their write hook fires once per build (no per-child
-        // amplification), and stasis build reads esbuild output in-process, so their synchronous
-        // write is load-bearing in a way webpack's per-child `done` write is not.
+        // Single compiler: write now (one `done`). Multi-compiler: defer -- `done` fires per child,
+        // so writing each time pays N super-linear brotli passes over a growing bundle; coalesce to one.
         if (this.#captureApplyCount === 1) this.#state.write()
         else this.#deferWrite()
       })
     }
   }
 
-  // Mark the State dirty and ensure a single end-of-process flush is registered, so a
-  // MultiCompiler's per-child-compiler `done` events coalesce into one write of the final
-  // bundle rather than re-serializing + brotli-compressing (quality 11, super-linear in size)
-  // an ever-growing bundle on every target's completion.
-  //
-  // KNOWN LIMITATION: the flush runs at process exit, so a multi-compiler one-shot build inside
-  // a process that never exits normally -- one that stays alive after building and is then
-  // killed by a signal (SIGINT/SIGTERM/SIGKILL), which bypass both beforeExit and exit -- would
-  // not flush. That is the same capture-then-exit assumption the preload's ROOT write relies
-  // on (hooks.js). NB: the SIGTERM shard flush metro opts its workers into
-  // (EXODUS_STASIS_SHARD_SIGNAL_FLUSH, hooks.js) does NOT help here and setting it wouldn't
-  // either -- it covers a capturing CHILD's shard forward, while this deferred write is the
-  // MAIN process's State.write via THIS plugin's own beforeExit/exit listeners, which a signal
-  // death (or the loader's re-delivered SIGTERM) still bypasses. The common build-and-exit
-  // flow is unaffected, a single-compiler build never reaches here (it writes on `done`), and
-  // watch (`--watch`, dev-server) capture is refused outright at watchRun (see #applyCaptureMode).
+  // Mark dirty and register a single end-of-process flush so a MultiCompiler's per-child `done`
+  // events coalesce into one write of the final bundle. KNOWN LIMITATION: the flush runs at
+  // beforeExit/exit, so a signal death (SIGINT/SIGTERM/SIGKILL) bypasses it -- same capture-then-exit
+  // assumption as the preload's write (hooks.js).
   #deferWrite() {
     this.#deferredWriteDirty = true
     if (this.#deferredWriteArmed) return
     this.#deferredWriteArmed = true
     const flush = () => {
-      if (!this.#deferredWriteDirty) return  // already flushed; the exit backstop is then a no-op
-      this.#state.write()                    // synchronous; if it throws, dirty stays set so the
-      this.#deferredWriteDirty = false       // exit backstop retries -- clear ONLY after success
+      if (!this.#deferredWriteDirty) return  // already flushed; exit backstop is a no-op
+      this.#state.write()                    // sync write; on throw, dirty stays set so exit retries
+      this.#deferredWriteDirty = false       // clear ONLY after a successful write
     }
-    // beforeExit handles the natural event-loop drain; exit is the synchronous backstop for an
-    // explicit process.exit(). state.write() is fully synchronous (writeFileSync/brotliCompressSync),
-    // so it is safe in the exit handler, and the dirty guard makes the second of the two a no-op.
+    // beforeExit for the natural drain; exit is the sync backstop for process.exit() (write is sync).
     process.on('beforeExit', flush)
     process.on('exit', flush)
   }