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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis-plugins",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "description": "Bundler plugins (webpack, esbuild, Metro) for @exodus/stasis-core",
   "type": "module",
   "exports": {
@@ -31,6 +31,6 @@
   },
   "homepage": "https://github.com/ExodusOSS/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.0"
+    "@exodus/stasis-core": "1.0.0-beta.2"
   }
 }

package/src/esbuild.js

@@ -21,6 +21,11 @@ export class StasisEsbuild {
   #resources
   #loaders
 
+  // Build starts observed by this (capture-mode) instance, across rebuilds AND across separate
+  // esbuild.build()/context() calls sharing one instance. The second start is refused -- see
+  // the onStart hook in setup().
+  #captureBuildCount = 0
+
   constructor(options = {}, { loaders } = {}) {
     // A caller that owns a State (e.g. `stasis build`) can pass it directly to drive the plugin, bypassing resolvePluginState; mode follows that State's config, and a foreign-copy State fails closed via the instanceof miss.
     const state = options instanceof State
@@ -49,9 +54,33 @@ export class StasisEsbuild {
     return 'stasis'
   }
 
-  setup = ({ onResolve, onLoad, onEnd, resolve }) => {
+  setup = ({ onResolve, onLoad, onStart, onEnd, resolve }) => {
     if (!this.#state) return  // noop plugin
 
+    // Watch/rebuild capture is EXPLICITLY UNSUPPORTED -- fail the second build loudly before it
+    // captures anything. Capture's dedupe is keyed by PATH, not content (#seen below, plus
+    // State.write's compare-and-skip caches), so on a 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 them outright. esbuild rebuilds (watch mode, context.rebuild())
+    // re-fire onStart/onEnd against the SAME setup registrations, so an instance-level counter
+    // sees every start; it also covers reusing one plugin instance across two esbuild.build()
+    // calls, which has the same staleness hazard. Returning errors from onStart is the
+    // esbuild-idiomatic hard failure (the build reports them and onEnd's clean-build gate then
+    // skips the write). Load mode registers nothing here: it serves immutable attested bytes,
+    // so rebuilds have no drift hazard.
+    if (!this.#state.config.loadBundle) {
+      onStart(() => {
+        this.#captureBuildCount += 1
+        if (this.#captureBuildCount === 1) return undefined
+        return {
+          errors: [{
+            text: 'StasisEsbuild: watch/rebuild is not supported for capture -- run a one-shot build (rebuilds would silently attest stale content)',
+          }],
+        }
+      })
+    }
+
     // 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
     // build finishes -- but only on a clean build, otherwise a partial bundle/lockfile

package/src/metro-transformer.js

@@ -14,15 +14,16 @@ import { State } from '@exodus/stasis-core/state'
 //   there is nothing to synchronize between them. That makes the per-worker transformer
 //   the natural seam for load -- each worker independently serves attested bytes, no IPC.
 //
-// HOW IT WIRES IN (metro.config.js, load mode only):
+// HOW IT WIRES IN (metro.config.js) -- wire it PERMANENTLY, alongside the serializer half:
 //   module.exports = {
-//     transformer: {
-//       transformerPath: require.resolve('@exodus/stasis/metro-transformer'),
-//     },
+//     transformerPath: require.resolve('@exodus/stasis/metro-transformer'),  // top-level, a sibling of `transformer`
 //   }
 //   // run with EXODUS_STASIS_BUNDLE=load (+ EXODUS_STASIS_BUNDLE_FILE / LOCK / SCOPE),
-//   // OR a stasis.config.json with "bundle":"load". Do NOT also wire the StasisMetro
-//   // serializer plugin in load mode -- capture and load are separate wirings.
+//   // OR a stasis.config.json with "bundle":"load". Outside load mode this transformer is
+//   // a transparent pass-through (see getLoadState), and under load the StasisMetro
+//   // serializer is one too -- one committed metro.config.js carries both halves, the
+//   // mode picks the active one (the config is itself attested at capture, so a load
+//   // run must execute it unedited).
 //
 //   Metro calls `transformerPath`'s `transform(config, projectRoot, filename, data,
 //   options)` in each worker with `data` = the file's on-disk bytes (a Buffer) and

package/src/metro.js

@@ -26,6 +26,26 @@ function entrySet(graph) {
   return new Set()
 }
 
+// Well-known files a React Native / Metro build REQUIRES that the serializer's module
+// graph never reliably carries -- attested automatically at capture when they resolve
+// from the project, and skipped when they don't (not every Metro project ships them):
+//   - metro-runtime/src/modules/asyncRequire.js: Metro's default
+//     `transformer.asyncRequireModulePath`. The transform injects it to implement
+//     dynamic import(), so it ships in bundles without necessarily appearing as a
+//     module of the graph handed to the serializer.
+//   - @react-native-community/cli/setup_env.sh: sourced by the React Native CLI's
+//     native build phases (Xcode / Gradle) around the JS bundle step -- build-shaping
+//     toolchain that is never part of the JS module graph at all.
+// A `resource: true` entry bypasses the `resources` allowlist: this is a stasis-vetted
+// list of SPECIFIC files, not a user-widened extension class. Code entries ride the
+// normal loader-format inference. Extend the list here, not via an option -- an option
+// would make the attested set configuration-dependent, which is exactly what
+// auto-include exists to avoid.
+const AUTO_INCLUDES = [
+  { specifier: 'metro-runtime/src/modules/asyncRequire.js', resource: false },
+  { specifier: '@react-native-community/cli/setup_env.sh', resource: true },
+]
+
 // Metro has no public "default serializer" export, but its default bundle CODE is exactly
 // `bundleToString(baseJSBundle(entryPoint, preModules, graph, options)).code` (Metro's own
 // Server.js else-branch when no customSerializer is set). bundleToString returns
@@ -86,14 +106,22 @@ function metroDefaultSerializer() {
 //   inputFileSystem wrapper, esbuild's onLoad). Metro reads + transforms in workers,
 //   before serialization, so the serializer can't inject bytes into the transform.
 //   Load is instead handled per-worker by the companion `./metro-transformer.js`
-//   (wired as Metro's `transformer.transformerPath`): unlike capture, load only ever
+//   (wired as Metro's top-level `transformerPath`): unlike capture, load only ever
 //   READS the immutable bundle and every worker reads the same bytes, so there is no
-//   cross-worker state to merge. This serializer therefore REJECTS bundle=load.
-//   Capture modes (lock/bundle add|replace|frozen, and lock=none/ignore) all work.
+//   cross-worker state to merge. Under bundle=load this serializer is therefore a
+//   transparent PASS-THROUGH (captures nothing, writes nothing, delegates to the
+//   base serializer), mirroring the transformer, which passes through in every
+//   non-load mode. Wire BOTH halves permanently; the mode picks the active one.
+//   That matters because metro.config.js is itself attested at capture, so a load
+//   run must execute it unedited. Capture modes (lock/bundle add|replace|frozen,
+//   and lock=none/ignore) all capture here.
 //
-// USAGE (metro.config.js) -- prefer withStasis:
+// USAGE (metro.config.js) -- prefer withStasis; wire the load half permanently alongside it:
 //   const { withStasis } = require('@exodus/stasis/metro')
-//   module.exports = withStasis(require('./metro.config.base'), { /* scope, lock, ... */ })
+//   module.exports = withStasis({
+//     ...require('./metro.config.base'),
+//     transformerPath: require.resolve('@exodus/stasis/metro-transformer'),  // the load half
+//   }, { /* scope, lock, ... */ })
 //
 //   Then CAPTURE with child-process forwarding ON -- Metro transforms in worker processes, so
 //   `--child-process` is REQUIRED on a capture run to attest the toolchain those workers load
@@ -107,14 +135,38 @@ function metroDefaultSerializer() {
 //   `new StasisMetro(opts).customSerializer(base?)`. `serializerHook` (the experimental
 //   hook) is a lower-coverage fallback -- see its note.
 //
+// AUTO-INCLUDED FILES: capture also attests the fixed AUTO_INCLUDES list (see it above
+//   the class) -- files a React Native build requires that the serializer's graph never
+//   reliably carries (Metro's asyncRequire module, the RN CLI's setup_env.sh). Each is
+//   attested when it resolves from the project and skipped when it doesn't, through the
+//   same addFile path as graph modules, so frozen verification covers them fail-closed.
+//   NOTE: a lockfile captured before this list existed doesn't attest these files, so a
+//   frozen run against it fails once they're present -- recapture (lock=replace) once.
+//
 // KNOWN LIMITATIONS (Metro-specific coverage gaps -- documented, not silently ignored):
-//   - Child-process capture is best-effort and one-shot-build only. A worker KILLED by signal
-//     before its exit hook (jest-worker forceExit / pool overflow) loses its shard SILENTLY at
-//     capture time -- a later frozen run still catches the gap (fail-closed), but nothing warns
-//     during capture. And it relies on the loader's exit-time write: a dev server (`metro start`,
-//     pool kept warm, killed by signal) never gets there, and standalone (no stasis loader) Metro
-//     mints no shard dir -- neither produces a toolchain-complete lockfile. Use a one-shot
-//     `metro build` under `stasis run --child-process` to capture, then verify with `--lock=frozen`.
+//   - Capture is ONE-SHOT ONLY, enforced: a dev server (`metro start`) re-invokes the serializer
+//     per rebuild, and the SECOND invocation throws (see #run) -- capture's path-keyed dedupe
+//     would otherwise keep attesting a file's first-build bytes after an edit changed them.
+//     Metro gives the serializer no watch signal on the first build, so the first rebuild is the
+//     earliest refusal point. Load mode is unaffected and runs fine under a dev server --
+//     the serializer passes through and the worker transformer only reads immutable
+//     attested bytes.
+//   - Child-process capture is best-effort within that one shot. A writing plugin opts the
+//     build's workers into the loader's SIGTERM shard flush (EXODUS_STASIS_SHARD_SIGNAL_FLUSH,
+//     set in the constructor), so a worker force-killed by jest-worker's forceExit -- SIGTERM
+//     500ms after END, routine for a transform worker whose event loop doesn't drain --
+//     contributes its shard best-effort: the flush must complete inside forceExit's follow-up
+//     500ms SIGTERM->SIGKILL window. A worker killed any OTHER way still loses its shard
+//     SILENTLY at capture time -- SIGKILL (jest-worker's memory-limit killChild, a
+//     killSignal:'SIGKILL' override), a non-SIGTERM signal (group SIGINT/SIGHUP, another
+//     killSignal override; the flush handler is SIGTERM-only), or a nested orchestration's
+//     Metro MAIN process (itself a capturing child, it snapshots its config before this
+//     constructor sets the flag, so only its descendants are covered). A later frozen run
+//     catches every such gap (fail-closed), but nothing warns during capture. And it relies
+//     on the loader's exit/signal-time writes, which standalone (no stasis loader) Metro
+//     never reaches -- it mints no shard dir and produces no toolchain-complete lockfile.
+//     Use a one-shot `metro build` under `stasis run --child-process` to capture, then
+//     verify with `--lock=frozen`.
 //   - Scaled asset variants: `import x from './logo.png'` is ONE module in the graph, keyed
 //     by the base path; Metro discovers `logo@2x.png` / `@3x` via its AssetData (parallel
 //     scales/files arrays), NOT as separate graph modules, so only the base file is attested
@@ -130,6 +182,18 @@ export class StasisMetro {
   #state
   #resources
 
+  // Base dir AUTO_INCLUDES resolution starts from: the directory Metro runs in -- the
+  // same cwd resolvePluginState anchors the State at, and an in-or-under-root path by
+  // State's own root detection (which walks UP from it), so Node's node_modules walk-up
+  // from here also covers hoisted workspace layouts. Snapshotted at construction so a
+  // later chdir can't skew what a capture attests.
+  #projectDir = process.cwd()
+
+  // Whether this instance already served one capture (#run). The serializer fires once per
+  // one-shot `metro build`; a dev server re-invokes it per rebuild, which capture refuses --
+  // see the guard in #run.
+  #ran = false
+
   constructor(options = {}) {
     const { state } = resolvePluginState('StasisMetro', options, process.cwd())
     this.#state = state // null when the plugin should be inert (Rule 7)
@@ -151,6 +215,26 @@ export class StasisMetro {
         'is never attested. Enable it: `stasis run --child-process ...`, EXODUS_STASIS_CHILD_PROCESS=1, ' +
         'or "childProcess": true in stasis.config.json.'
       )
+      // Opt this build's children into the loader's SIGTERM shard flush: jest-worker's
+      // forceExit would otherwise silently drop a non-draining worker's shard (mechanics in
+      // the KNOWN LIMITATIONS bullet above; the handler lives in hooks.js). The flag rides
+      // process.env, so EVERY capturing child forked after config time inherits it --
+      // Metro's transform workers are the intended audience, but a codegen fork the build
+      // spawns rides along; the loader's own gates (child + shard forwarding) bound what it
+      // can do there to a flush-then-redeliver on SIGTERM. The plugin can't act inside the
+      // workers (only the loader runs there), so an env opt-in is the seam; scoped HERE,
+      // not globally, because changing a child's default-kill disposition is otherwise the
+      // user's domain. Two deliberate softenings:
+      //   - keyed on the PRELOAD where one exists: the shard channel is minted by, and the
+      //     children's capture mode follows, the preload's config -- a Rule-6 sidecar's own
+      //     bundle mode says nothing about either, and setting the flag under a frozen
+      //     preload would claim an opt-in that can never engage;
+      //   - `||=`, not `=`: an explicit ambient opt-out ('0'/'false', envBool's disable
+      //     values) is the user's call and is honored; only unset/empty is claimed.
+      const channel = State.preload ?? state
+      if (channel.config.writeLockfile || channel.config.writeBundle) {
+        process.env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH ||= '1'
+      }
     }
     // resources is a Config field now (validated + coordinated against any preload in
     // resolvePluginState); cache the resolved Set for the per-file classify hot path.
@@ -184,23 +268,36 @@ export class StasisMetro {
 
   #run(graph, preModules) {
     if (!this.#state) return
-    if (this.#state.config.loadBundle) {
+    // bundle=load: pass through -- load is served by the companion worker transformer, and
+    // metro.config.js is itself attested at capture, so the same wiring must run unedited
+    // in load mode (see the class note). Checked BEFORE the one-shot guard: load captures
+    // nothing and legitimately re-serializes per rebuild under a dev server.
+    if (this.#state.config.loadBundle) return
+    // Watch/dev-server capture is EXPLICITLY UNSUPPORTED -- refuse the second serialization
+    // loudly before it captures anything. Capture's dedupe is keyed by PATH, not content
+    // (#seen below, plus State.write's compare-and-skip caches), so on a rebuild where a
+    // file's bytes changed the plugin would skip re-capture: the emitted bundle would use the
+    // new bytes while the stasis bundle/lockfile silently kept attesting the OLD ones. The
+    // serializer fires exactly once per one-shot `metro build`; only a dev server
+    // (`metro start`) re-invokes it, and Metro hands the serializer no watch-mode signal on
+    // the FIRST build, so the first rebuild is the earliest point capture can refuse. (Load
+    // mode has no such hazard and legitimately runs under a dev server -- it passed through
+    // above, and the companion worker transformer only READS immutable attested bytes.)
+    if (this.#ran) {
       throw new Error(
-        'StasisMetro: bundle=load is served by the companion worker transformer ' +
-        "(transformer.transformerPath = '@exodus/stasis/metro-transformer'), not this serializer " +
-        'plugin -- Metro transforms in workers before serialization. Remove this plugin from your ' +
-        'serializer config in load mode, or use bundle=add/replace/frozen here to capture.'
+        'StasisMetro: watch/dev-server rebuilds are not supported for capture -- use a one-shot `metro build`'
       )
     }
+    this.#ran = true
     this.#capture(graph, preModules)
 
     // 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 here. The
     // serializer only runs once Metro has successfully built + transformed the whole graph
     // (a failed build throws before serialization), so this is the clean-build equivalent of
-    // webpack's `stats.hasErrors()` / esbuild's `result.errors.length` gate. In watch / dev
-    // mode it fires on every rebuild; State.write's per-artifact compare-and-skip makes the
-    // unchanged-graph case a cheap no-op.
+    // webpack's `stats.hasErrors()` / esbuild's `result.errors.length` gate -- and it runs at
+    // most once per instance (the rebuild guard above), so this write is the one-shot build's
+    // single flush.
     if (this.#state !== State.preload) this.#state.write()
   }
 
@@ -212,6 +309,42 @@ export class StasisMetro {
     // app module graph.
     if (preModules) this.#captureModules(preModules, entries)
     this.#captureModules(graph.dependencies.values(), entries)
+    // AFTER the graph so #seen already holds every graph module: an auto-include that
+    // did land in the graph this build (asyncRequire does when the app uses dynamic
+    // import()) is deduped instead of re-recorded.
+    this.#captureAutoIncludes()
+  }
+
+  // Attest the AUTO_INCLUDES list (see its note above). Skips, per entry: a specifier
+  // that doesn't resolve from the project (the file genuinely doesn't exist there --
+  // nothing to attest), a file already captured as a graph module this build, and a
+  // resolution landing outside the project root (unattestable -- lockfile/bundle keys
+  // are root-relative; same out-of-scope stance as the load transformer's inScope).
+  // Everything that IS attested goes through the exact addFile path graph modules use,
+  // so frozen runs verify these files fail-closed like any other capture.
+  #captureAutoIncludes() {
+    for (const { specifier, resource } of AUTO_INCLUDES) {
+      let modPath
+      try {
+        modPath = require.resolve(specifier, { paths: [this.#projectDir] })
+      } catch {
+        continue // not installed in this project -- nothing to attest
+      }
+      if (this.#seen.has(modPath)) continue
+      try {
+        this.#state.relative(modPath)
+      } catch {
+        continue // outside the project root -- unattestable
+      }
+      this.#seen.add(modPath)
+      // Real reader for the same reason as #captureModules: this is plugin bookkeeping,
+      // not a program fs read -- it must not be re-recorded by a --fs patched reader.
+      const source = realReadFileSync(modPath)
+      if (!resource) {
+        assert.ok(isUtf8(source), `StasisMetro: code-classified file has non-UTF-8 bytes: ${modPath}`)
+      }
+      this.#state.addFile(pathToFileURL(modPath).toString(), { source, resource, reason: 'StasisMetro' })
+    }
   }
 
   #captureModules(modules, entries) {

package/src/plugins.js

@@ -163,6 +163,8 @@ export function resolvePluginState(label, options, cwd) {
       debug: pc.debug,
       childProcess: pc.childProcess,
       resources: [...pc.resources],
+      // carried over: sidecars skip stasis.config.json discovery, which may have set it
+      brotliQuality: pc.brotliQuality,
     })
     return { state: sidecar, isNoop: false }
   }
@@ -199,6 +201,7 @@ export function resolvePluginState(label, options, cwd) {
     debug: pc.debug,
     childProcess: pc.childProcess,
     resources: [...pc.resources],
+    brotliQuality: pc.brotliQuality, // carried over, like the Rule 6 sidecar above
   })
   return { state: sidecar, isNoop: false }
 }

package/src/webpack.js

@@ -484,35 +484,45 @@ export class StasisWebpack {
       })
     })
 
+    // 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.
+    compiler.hooks.watchRun.tap('Stasis', () => {
+      throw new Error(
+        'StasisWebpack: watch mode is not supported for capture -- ' +
+        'run a one-shot build (watch rebuilds would silently attest stale content)'
+      )
+    })
+
     // 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.
     if (this.#state !== State.preload) {
-      // Watch-mode detection. compiler.hooks.watchRun fires ONLY under compiler.watch() (both
-      // webpack 4 and 5) and always before that build's `done`, so the flag is set in time.
-      // The flag is per-compiler (this closure), which is what we want: each compiler reports
-      // its own run kind even when one shared plugin instance drives several.
-      let watching = false
-      compiler.hooks.watchRun.tap('Stasis', () => { watching = true })
       compiler.hooks.done.tap('Stasis', (stats) => {
         if (stats.hasErrors()) return
-        // Write immediately when the bundle cannot grow across `done`s:
-        //   - watch mode: a watcher keeps the event loop alive, so a deferred flush would never
-        //     fire; per-rebuild freshness is the point, and State.write's compare-and-skip keeps
-        //     an unchanged rebuild a ~no-op; and
-        //   - 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
+        // 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). esbuild / metro
+        // 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.
-        if (watching || this.#captureApplyCount === 1) this.#state.write()
+        if (this.#captureApplyCount === 1) this.#state.write()
         else this.#deferWrite()
       })
     }
@@ -526,9 +536,14 @@ export class StasisWebpack {
   // 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 already relies on
-  // (hooks.js) and metro documents; the common build-and-exit and watch (`--watch`, dev-server)
-  // flows are unaffected, and a single-compiler build never reaches here (it writes on `done`).
+  // 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).
   #deferWrite() {
     this.#deferredWriteDirty = true
     if (this.#deferredWriteArmed) return