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

package/src/metro.js

@@ -1,24 +1,19 @@
 import assert from 'node:assert/strict'
 import { isUtf8 } from 'node:buffer'
+import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import { isAbsolute } from 'node:path'
+import { isAbsolute, join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 import { resolvePluginState } from './plugins.js'
 import { State } from '@exodus/stasis-core/state'
-import { realReadFileSync } from '@exodus/stasis-core/state-util'
-import { classifyExtension } from '@exodus/stasis-core/util'
+import { realReadFileSync, realReaddirSync } from '@exodus/stasis-core/state-util'
+import { RN_CORE_INCLUDE_FILES, classifyExtension, classifyFormat, classifyNativeCapture, isExcludedNativeDir, isNativeArtifact, isPodspec, isSkippedNativeWalkDir, refineNativeCapture, splitNodeModulesPath } from '@exodus/stasis-core/util'
 
 const require = createRequire(import.meta.url)
 
-// `graph.entryPoints` is a `Set<string>` of absolute entry paths in current Metro (it was
-// an `Array<string>` before ~0.71; it has never been a Map). Normalize to a Set so
-// `isEntry` is a single `.has`. The one-shot `metro build` passes the graph but no separate
-// entry arg, and `customSerializer`'s separate `entryPoint` string names only the PRIMARY
-// entry, so `graph.entryPoints` is the authoritative full set (matters for multi-entry
-// builds). An absent/odd shape yields an empty set -- nothing marked an entry rather than
-// throwing, matching how the other plugins treat an entry they can't positively identify.
+// Metro's `graph.entryPoints` is a Set now, an Array before ~0.71; normalize to a Set.
 function entrySet(graph) {
   const ep = graph?.entryPoints
   if (ep instanceof Set) return ep
@@ -26,37 +21,66 @@ 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.
+// Files a React Native build requires that Metro's module graph never carries; attested (tagged by
+// the shared classifier, see #captureAutoIncludes) when they resolve from the project.
 const AUTO_INCLUDES = [
-  { specifier: 'metro-runtime/src/modules/asyncRequire.js', resource: false },
-  { specifier: '@react-native-community/cli/setup_env.sh', resource: true },
+  'metro-runtime/src/modules/asyncRequire.js',
+  '@react-native-community/cli/setup_env.sh',
 ]
 
-// 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
-// `{ code, metadata }` -- we return the `code` string; a plain string is a valid
-// customSerializer return and Metro regenerates the source map itself, the same way its
-// else-branch does. These internal module paths are the ecosystem-standard entry (Expo,
-// metro-serializer-*): `metro/src/*` resolves through ~0.82, `metro/private/*` exists from
-// 0.81.4 on (and is the ONLY option from 0.83), so the two-tier require below spans the
-// range. Loaded lazily and ONLY when withStasis()/customSerializer() must produce output
-// with no user-supplied base, so a normal capture build never touches Metro internals --
-// and the `metro` spec is built indirectly so it isn't treated as a hard dependency of stasis.
+// The worker-side toolchain that only Metro's transform workers load, named in both the
+// --child-process assert and the transform-cache warning so the two can't describe different sets.
+const WORKER_TOOLCHAIN = 'babel.config.js, @babel/core, the RN preset + plugins'
+
+// Run `react-native config` (RN's autolinking resolver) for native deps. Null when the RN CLI
+// isn't installed; THROWS when present but failing -- silently under-attesting breaks frozen runs.
+function loadReactNativeConfig(projectDir) {
+  let cliPath
+  try {
+    cliPath = require.resolve('react-native/cli.js', { paths: [projectDir] })
+  } catch {
+    return null
+  }
+  // Run the child as vanilla Node: strip stasis's env and any inherited loader, else it joins
+  // this capture nondeterministically or aborts on a config it can't satisfy.
+  const env = { ...process.env }
+  for (const key of Object.keys(env)) {
+    if (key.startsWith('EXODUS_STASIS_')) delete env[key]
+  }
+  delete env.NODE_OPTIONS
+  const res = spawnSync(process.execPath, [cliPath, 'config'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+    maxBuffer: 128 * 1024 * 1024, // a large monorepo's config JSON can be many MB
+    env,
+  })
+  if (res.error) {
+    throw new Error(`StasisMetro: failed to run 'react-native config': ${res.error.message}`, { cause: res.error })
+  }
+  if (res.status !== 0) {
+    const detail = (res.stderr || '').trim()
+    throw new Error(
+      `StasisMetro: 'react-native config' exited ${res.status}${res.signal ? ` on signal ${res.signal}` : ''}` +
+      `${detail ? `: ${detail}` : ''}`
+    )
+  }
+  try {
+    return JSON.parse(res.stdout)
+  } catch (cause) {
+    throw new Error("StasisMetro: couldn't parse 'react-native config' output as JSON", { cause })
+  }
+}
+
+// Native when at least one platform config is non-null; an all-null dep is JS-only (already in the graph).
+function isNativeDependency(dep) {
+  const platforms = dep?.platforms
+  if (!platforms || typeof platforms !== 'object') return false
+  return Object.values(platforms).some((p) => p != null)
+}
+
+// Metro has no public default-serializer export; reproduce its default output via internal
+// baseJSBundle + bundleToString. Path moved: metro/src/* through ~0.82, metro/private/* from
+// 0.81.4 on (the only option from 0.83), so the two-tier require below spans the range.
 let metroDefault
 function metroDefaultSerializer() {
   if (metroDefault) return metroDefault
@@ -77,179 +101,88 @@ function metroDefaultSerializer() {
       )
     }
   }
-  // Interop: Metro ships CJS; `require` of its Flow-compiled modules exposes the function
-  // either as the namespace itself or under `.default`.
+  // Metro ships CJS; require exposes the fn as the namespace or under `.default`.
   baseJSBundle = baseJSBundle.default ?? baseJSBundle
   bundleToString = bundleToString.default ?? bundleToString
-  // Return the `.code` string (bundleToString yields { code, metadata }); a string is a
-  // valid customSerializer return and Metro regenerates the source map itself.
   metroDefault = (entryPoint, preModules, graph, options) =>
     bundleToString(baseJSBundle(entryPoint, preModules, graph, options)).code
   return metroDefault
 }
 
-// Stasis plugin for the Metro bundler (React Native).
-//
-// WHY THIS HOOKS THE SERIALIZER, NOT A TRANSFORMER:
-//   Metro transforms each file in a pool of WORKER processes. A stasis State is
-//   process-local (its observed sources/imports/formats live in in-memory Maps
-//   flushed by State.write on the main process), so a transformer-side capture
-//   would scatter observations across workers that never reach the writer.
-//   Metro's serializer runs once, in the MAIN process, AFTER the whole graph is
-//   built, with the complete module graph in hand -- the one place a single State
-//   can see every module and resolution edge (mirrors webpack's afterResolve and
-//   esbuild's onResolve/onLoad, which likewise run in the bundler's main process).
-//
-// THIS PLUGIN IS THE CAPTURE HALF -- LOAD LIVES IN A SEPARATE TRANSFORMER:
-//   The other plugins serve bundle bytes back into the build because their bundler
-//   reads + transforms files in the same process the bundle lives in (webpack's
-//   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 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. 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; wire the load half permanently alongside it:
-//   const { withStasis } = require('@exodus/stasis/metro')
-//   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
-//   (babel.config.js, @babel/core, the RN preset + plugins). The plugin throws at config time if
-//   you forget it on a writing run:  `stasis run --lock=add --child-process -- <metro build cmd>`.
-//   A later `--lock=frozen` verify needs NO flag (verification is per-process, independent of the
-//   shard channel). withStasis wires the STABLE `serializer.customSerializer`, which is the only
-//   Metro surface that receives `preModules` (the polyfills/runtime Metro prepends to every
-//   bundle -- real shipped files). It wraps an existing customSerializer if you have one,
-//   otherwise reproduces Metro's default output. For manual wiring use
-//   `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):
-//   - 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
-//     here. Assets pulled in by the native build via `react-native.config.js` (e.g. fonts
-//     through `react-native-asset`) aren't in Metro's JS graph at all and aren't covered.
-//   - Platform-specific lockfiles: edges are recorded under the as-written specifier
-//     ('./Foo') resolved to the platform variant Metro picked ('Foo.ios.js'), all under the
-//     '*' conditions key. A lockfile captured for one platform won't match a frozen run for
-//     another -- capture/verify per platform. It fails CLOSED (rejects, never silently
-//     accepts a mismatched resolution).
+// Stasis capture plugin for Metro (React Native). Hooks Metro's serializer, which runs ONCE in
+// the MAIN process with the full module graph -- a per-worker transformer's process-local State
+// could never be merged. This is the CAPTURE half; the LOAD half is the companion
+// ./metro-transformer.js. Wire both permanently (withStasis + transformerPath); the mode picks
+// the active one, and under bundle=load this serializer is a transparent pass-through.
+// Capture is one-shot (dev-server rebuilds refused, see #run) and REQUIRES --child-process so the
+// worker-side toolchain (babel, RN preset) is attested (enforced in the constructor). withStasis
+// wires the stable customSerializer -- the only surface that receives preModules; serializerHook
+// is a lower-coverage fallback that never sees them. Prefer withStasis for a second reason too: a
+// hand-wired serializer leaves the Metro config -- and therefore its transform cache -- out of
+// stasis's hands (see withStasis).
 export class StasisMetro {
   #seen = new Set()
   #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.
+  // Base dir for resolution; snapshotted at construction so a later chdir can't skew capture.
   #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.
+  // Whether this instance already captured; the dev-server rebuild guard in #run trips on the second.
   #ran = false
 
-  constructor(options = {}) {
+  // Set by withStasis, which returns the Metro config and can therefore drop its transform cache;
+  // a hand-wired customSerializer/serializerHook can't, so #run warns instead. Internal wiring, in
+  // the second options bag like StasisEsbuild's -- not a user-facing option.
+  #ownsConfig
+
+  constructor(options = {}, { ownsConfig = false } = {}) {
     const { state } = resolvePluginState('StasisMetro', options, process.cwd())
-    this.#state = state // null when the plugin should be inert (Rule 7)
-    // A CAPTURE-THAT-WRITES requires child-process forwarding: Metro transforms every file in a
-    // pool of worker processes (see the class note), and the toolchain those workers load --
-    // babel.config.js, @babel/core, the React Native preset + its plugins -- is observed only
-    // there. Without --child-process those workers can't report back, so that toolchain goes
-    // unattested and a later frozen/load run rejects it. Fail loudly at config time rather than
-    // silently emit an incomplete lockfile. Gate on the SAME predicate as the shard channel itself
-    // (writeLockfile || writeBundle, i.e. lock/bundle add|replace) so the flag is demanded exactly
-    // when forwarding does something: a frozen/ignore/none run verifies per-process and needs no
-    // channel (the CLI frozen tests pass without the flag), and load mode reads the bundle via the
-    // companion transformer -- none of those should be forced to pass --child-process.
+    this.#state = state // null when the plugin should be inert (Rule 0 or Rule 7)
+    this.#ownsConfig = ownsConfig
+    // A capture-that-writes REQUIRES --child-process: the worker toolchain (babel, RN preset) is
+    // observed only in workers. Gate on writeLockfile||writeBundle so it's demanded only when
+    // forwarding does something (frozen/load verify per-process and need no channel).
     if (state && (state.config.writeLockfile || state.config.writeBundle)) {
       assert.ok(
         state.config.childProcess,
         'StasisMetro: child-process capture must be enabled -- Metro transforms in worker processes, ' +
-        'and without it the toolchain they load (babel.config.js, @babel/core, the RN preset + plugins) ' +
+        `and without it the toolchain they load (${WORKER_TOOLCHAIN}) ` +
         '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.
+      // Opt this build's children into the loader's SIGTERM shard flush (handler in hooks.js) so
+      // jest-worker forceExit doesn't silently drop a non-draining worker's shard. Key on the
+      // PRELOAD's mode where one exists (the shard channel follows it, not a Rule-6 sidecar), and
+      // use `||=` not `=` so an explicit ambient opt-out ('0'/'false') is honored.
       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.
+    // Cache the resolved resources Set for the per-file classify hot path.
     this.#resources = state?.config.resources ?? new Set()
   }
 
-  // Build a Metro `serializer.customSerializer`: captures the graph AND `preModules`
-  // (Metro's prepended polyfills/runtime -- real shipped files that the experimental hook
-  // never sees), writes state, then produces output. With a `baseSerializer` we delegate to
-  // it; with none we reproduce Metro's default output. This is the stable, full-coverage
-  // surface (withStasis wires it for you).
+  // True when this build's guarantees depend on Metro actually TRANSFORMING files: a capture records
+  // what the workers load, frozen checks it, and load REPLAYS it -- all three break if a cached
+  // transform skips the work. False only when inert or attesting nothing ('none'/'ignore', what
+  // useLockfile/bundle exclude). Read by withStasis to decide whether to drop the transform cache.
+  get needsTransforms() {
+    const config = this.#state?.config
+    if (!config) return false
+    return config.useLockfile || config.bundle
+  }
+
+  // Build a Metro `serializer.customSerializer`: captures the graph + preModules (which the
+  // experimental hook never sees), then delegates to base or reproduces Metro's default output.
   customSerializer(baseSerializer = undefined) {
     if (baseSerializer !== undefined && typeof baseSerializer !== 'function') {
       throw new TypeError('StasisMetro.customSerializer(base?): base must be a function or omitted')
     }
+    // Inert (#state === null): hand the base straight back -- the wrapper below would otherwise
+    // fall back to metroDefaultSerializer(), loading Metro internals a do-nothing plugin mustn't touch.
+    if (!this.#state) return baseSerializer
     return (entryPoint, preModules, graph, options) => {
       this.#run(graph, preModules)
       const serialize = baseSerializer ?? metroDefaultSerializer()
@@ -257,105 +190,218 @@ export class StasisMetro {
     }
   }
 
-  // Wire into `serializer.experimentalSerializerHook`. Observation-only: Metro ignores the
-  // return value, so stasis never produces output -- convenient when you can't touch
-  // `customSerializer`. LOWER COVERAGE: the hook's signature is `(graph, delta)`; Metro never
-  // passes `preModules` to it, so the prepended polyfills/runtime go UNATTESTED. Prefer
-  // withStasis/customSerializer. Bound so it can be passed by reference.
+  // `serializer.experimentalSerializerHook`: observation-only, and LOWER COVERAGE -- Metro never
+  // passes preModules here, so the prepended polyfills/runtime go unattested. Prefer customSerializer.
   serializerHook = (graph, _delta) => {
     this.#run(graph)
   }
 
   #run(graph, preModules) {
     if (!this.#state) return
-    // 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.
+    // bundle=load: pass through (load is served by the worker transformer). Checked BEFORE the
+    // one-shot guard -- load captures nothing and legitimately re-serializes 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.)
+    // Watch/dev-server 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. Refuse
+    // the second serialization loudly (the first rebuild is the earliest refusal point Metro allows).
     if (this.#ran) {
       throw new Error(
         'StasisMetro: watch/dev-server rebuilds are not supported for capture -- use a one-shot `metro build`'
       )
     }
     this.#ran = true
+    // Keyed on ownership: a withStasis-built instance already dropped the stores (see withStasis).
+    // Nothing here can detect a cache hit, so say it once rather than silently under-attest.
+    if (!this.#ownsConfig && this.needsTransforms) {
+      console.warn(
+        "[stasis] StasisMetro: wired without withStasis(), so Metro's transform cache is outside " +
+        `stasis's control -- a cached transform skips the worker and the toolchain it loads ` +
+        `(${WORKER_TOOLCHAIN}) goes unattested. Wrap your config in withStasis(), or set ` +
+        '`cacheStores: []` yourself for every stasis build.'
+      )
+    }
     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 -- and it runs at
-    // most once per instance (the rebuild guard above), so this write is the one-shot build's
-    // single flush.
+    // The preload writes itself (hooks.js); standalone/sidecar States are written here. Reaching
+    // serialization means a clean build (a failed build throws first), so no error gate is needed.
     if (this.#state !== State.preload) this.#state.write()
   }
 
   #capture(graph, preModules) {
     const entries = entrySet(graph)
-    // preModules first (Metro's prepended polyfills/runtime + InitializeCore -- real on-disk
-    // files that ship in every bundle; only the customSerializer path receives them, and the
-    // synthetic ones like __prelude__ are skipped by the existsSync guard below). Then the
-    // app module graph.
+    // preModules first (Metro's prepended polyfills/runtime; synthetic ones like __prelude__ are
+    // skipped by the existsSync guard below), then the app 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.
+    // AFTER the graph so #seen already holds graph modules -- an auto-include that landed in the
+    // graph (asyncRequire, when the app uses dynamic import()) is deduped, not re-recorded.
     this.#captureAutoIncludes()
+    // AFTER the graph + auto-includes (same dedupe reason): the native pass only adds the native
+    // build-input surface (podspec/gradle/sources) that no module graph carries.
+    this.#captureNativeModules()
+  }
+
+  // Shared epilogue for the classify-driven capture paths: record under the given format/resource.
+  // `format` null/undefined lets addFile pick (loader format for JS, byte-derived for a resource);
+  // addFile already asserts UTF-8 for a non-resource (code) source, so no guard is needed here.
+  #recordCapture(full, source, { format, resource }) {
+    this.#state.addFile(pathToFileURL(full).toString(), { source, format: format ?? undefined, resource, reason: 'metro' })
   }
 
-  // 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.
+  // Attest the AUTO_INCLUDES list. Per entry, skip: unresolvable, already-seen, or resolving
+  // outside the project root (keys are root-relative). Attested entries ride the normal addFile path.
   #captureAutoIncludes() {
-    for (const { specifier, resource } of AUTO_INCLUDES) {
+    for (const specifier of AUTO_INCLUDES) {
       let modPath
       try {
         modPath = require.resolve(specifier, { paths: [this.#projectDir] })
       } catch {
-        continue // not installed in this project -- nothing to attest
+        continue
       }
       if (this.#seen.has(modPath)) continue
       try {
         this.#state.relative(modPath)
       } catch {
-        continue // outside the project root -- unattestable
+        continue
       }
       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.
+      // Real reader: plugin bookkeeping, not a program fs read -- must not be re-recorded by --fs.
       const source = realReadFileSync(modPath)
-      if (!resource) {
-        assert.ok(isUtf8(source), `StasisMetro: code-classified file has non-UTF-8 bytes: ${modPath}`)
+      // Tag from the ONE shared classifier so an auto-include agrees with any other path meeting
+      // the same file (native walk, --fs): setup_env.sh -> 'shell', not a forced 'resource' that
+      // would collide at the format noupsert. Unrecognized -> resource (vetted list, so no allowlist).
+      const format = classifyFormat(modPath, { content: source })
+      this.#recordCapture(modPath, source, { format, resource: format === undefined })
+    }
+  }
+
+  // Attest each native dependency's build-input surface. Discovery is `react-native config`; each
+  // dep root is walked (isSkippedNativeWalkDir pruned) and its native sources are attested as code,
+  // other assets as resources, plus each package.json. Node-runnable JS/TS is skipped (already in
+  // Metro's graph). Skipped when the RN CLI is absent or a root is outside root.
+  #captureNativeModules() {
+    const config = loadReactNativeConfig(this.#projectDir)
+    if (!config) return
+    const roots = new Set()
+    // Autolinked native deps: linked into the app regardless of whether their JS is imported.
+    for (const dep of Object.values(config.dependencies ?? {})) {
+      if (isNativeDependency(dep) && typeof dep.root === 'string' && isAbsolute(dep.root)) roots.add(dep.root)
+    }
+    // Native modules the app imports but autolinking never reports (manually integrated via Podfile).
+    for (const root of this.#reachedNativePackageRoots()) roots.add(root)
+    // RN CORE isn't a `dependencies` entry (config reports only reactNativePath) and autolinking
+    // never lists it, but its native source (React/, ReactCommon/, ReactAndroid/, sdks/, ...) is a
+    // build input like any other dep's -- walk it in full, the same way.
+    const rnPath = config.reactNativePath
+    if (typeof rnPath === 'string' && isAbsolute(rnPath)) roots.add(rnPath)
+    for (const root of roots) {
+      try {
+        this.#state.relative(root) // asserts the package lives inside the project root
+      } catch {
+        continue
       }
-      this.#state.addFile(pathToFileURL(modPath).toString(), { source, resource, reason: 'StasisMetro' })
+      this.#captureNativeTree(root, true)
+    }
+    // RN core's `.js` build scripts the walk skips (Metro-owned by extension, but never in the graph).
+    if (typeof rnPath === 'string' && isAbsolute(rnPath)) {
+      try {
+        this.#state.relative(rnPath)
+        for (const file of RN_CORE_INCLUDE_FILES) this.#captureNativeFile(join(rnPath, file))
+      } catch { /* react-native resolved outside the project root -- unattestable */ }
+    }
+  }
+
+  // Attest a single vetted file (RN_CORE_INCLUDE_FILES) the tree walk skips; absent -> skipped.
+  // Tagged via the shared classifier like every other path (a `.js` build script -> code).
+  #captureNativeFile(full) {
+    if (this.#seen.has(full)) return
+    let source
+    try {
+      source = realReadFileSync(full)
+    } catch {
+      return
+    }
+    this.#seen.add(full)
+    const format = classifyFormat(full, { content: source })
+    this.#recordCapture(full, source, { format, resource: format === undefined })
+  }
+
+  // node_modules roots the graph reached that also ship native code (podspec or ios/android dir):
+  // the manually-integrated native modules `react-native config` omits. Derived from #seen; RN core
+  // is skipped here because it's added to the walk explicitly (via reactNativePath).
+  #reachedNativePackageRoots() {
+    const pkgRoots = new Set()
+    for (const abs of this.#seen) {
+      const nm = splitNodeModulesPath(abs)
+      if (!nm || nm.name === 'react-native') continue
+      pkgRoots.add(nm.dir)
+    }
+    return [...pkgRoots].filter((root) => this.#looksNative(root))
+  }
+
+  #looksNative(root) {
+    if (existsSync(join(root, 'ios')) || existsSync(join(root, 'android'))) return true
+    return this.#hasPodspec(root)
+  }
+
+  // True if any *.podspec exists under `dir`, pruning the same subtrees the capture walk skips.
+  #hasPodspec(dir) {
+    let entries
+    try {
+      entries = realReaddirSync(dir, { withFileTypes: true })
+    } catch {
+      return false
+    }
+    for (const ent of entries) {
+      if (ent.isSymbolicLink()) continue
+      if (ent.isFile()) {
+        if (isPodspec(ent.name)) return true
+      } else if (ent.isDirectory() && !isSkippedNativeWalkDir(ent.name)) {
+        if (this.#hasPodspec(join(dir, ent.name))) return true
+      }
+    }
+    return false
+  }
+
+  // Recursively attest native build-input files under `dir`. Genuine readers (plugin bookkeeping,
+  // not re-recorded by --fs); symlinks not followed (cycle/escape hazard).
+  #captureNativeTree(dir, atRoot = false) {
+    let entries
+    try {
+      entries = realReaddirSync(dir, { withFileTypes: true })
+    } catch {
+      return // dir missing / not a directory -- nothing to walk
+    }
+    for (const ent of entries) {
+      if (ent.isSymbolicLink()) continue
+      const full = join(dir, ent.name)
+      if (ent.isDirectory()) {
+        // Skip build-output subtrees, Apple binary bundles + their loose per-arch slice dirs, and an
+        // off-platform toplevel dir.
+        if (!isSkippedNativeWalkDir(ent.name) && !(atRoot && isExcludedNativeDir(ent.name))) this.#captureNativeTree(full)
+        continue
+      }
+      if (!ent.isFile()) continue // sockets/FIFOs/etc. -- no attestable bytes
+      // Prebuilt binary artifacts are build output, non-deterministic -- never captured.
+      if (isNativeArtifact(ent.name)) continue
+      if (this.#seen.has(full)) continue // already captured as a graph module or auto-include
+      const byName = classifyNativeCapture(ent.name)
+      // Node-runnable JS/TS is captured via Metro's graph, not here (action==='skip').
+      if (byName.action === 'skip') continue
+      const source = realReadFileSync(full)
+      // Byte-level rules (prebuilt binaries, binary plists) -- see refineNativeCapture.
+      const { action, format } = refineNativeCapture(byName, ent.name, source, this.#resources)
+      if (action === 'skip') continue
+      this.#seen.add(full)
+      this.#recordCapture(full, source, { format, resource: action === 'resource' })
     }
   }
 
   #captureModules(modules, entries) {
     for (const module of modules) {
-      // Metro keys `graph.dependencies` by the module's absolute path; `module.path` is that
-      // same path and is what preModules carry too, so we read it off the module either way.
+      // module.path is the absolute path (both graph modules and preModules carry it).
       const modPath = module?.path
-      // Skip synthetic / virtual modules (Metro injects some with non-disk paths, e.g.
-      // require.context's `?ctx=` modules and __prelude__): a path that isn't an existing
-      // absolute file has no bytes to hash. Mirrors webpack's `isAbsolute && existsSync`
-      // guard and esbuild's `namespace === 'file'` gate.
+      // Skip synthetic/virtual modules (require.context's ?ctx=, __prelude__): no on-disk bytes to hash.
       if (typeof modPath !== 'string' || !isAbsolute(modPath) || !existsSync(modPath)) continue
 
       const kind = classifyExtension(modPath, this.#resources)
@@ -367,12 +413,8 @@ export class StasisMetro {
       }
       const url = pathToFileURL(modPath).toString()
 
-      // Record this module's outgoing resolution edges. Metro keys a module's `dependencies`
-      // by an opaque hash; the as-written specifier is `dep.data.name` (e.g. './hello' or
-      // 'react-native') and the resolved target is `dep.absolutePath`. We only attest edges
-      // whose TARGET is code: resource imports (an asset pulled in for its bytes) are captured
-      // as files below but carry no import edge, matching webpack/esbuild (`kind === 'code'`).
-      // Edges to virtual/unresolved targets are skipped like the modules above.
+      // Outgoing edges: as-written specifier is `dep.data.name`, target `dep.absolutePath`.
+      // Only code targets get an edge (resource imports are captured as files, no edge).
       for (const dep of module.dependencies?.values?.() ?? []) {
         const target = dep?.absolutePath
         const specifier = dep?.data?.name
@@ -385,36 +427,56 @@ export class StasisMetro {
       if (this.#seen.has(modPath)) continue
       this.#seen.add(modPath)
 
-      // Read the bytes from disk rather than `module.getSource()` -- addFile re-reads disk
-      // and asserts byte-equality against what we pass, and disk is the thing stasis attests.
-      // Use the REAL reader (state-util.js), like webpack/esbuild: this capture read is the
-      // plugin's own bookkeeping, NOT a program fs read. `import { readFileSync } from
-      // 'node:fs'` (the named binding above, before this fix) is rebound to the patched
-      // reader by `stasis run --fs`'s syncBuiltinESMExports(), so reading through it would
-      // re-record the whole Metro module graph into the preload/main bundle -- it belongs to
-      // THIS plugin's sidecar instead.
+      // Read from disk, not module.getSource() -- addFile re-reads disk and asserts byte-equality.
+      // Real reader (state-util.js): a --fs-patched readFileSync would re-record the graph into the preload.
       const source = realReadFileSync(modPath)
-      // Code-classified files must be UTF-8. A code extension carrying non-UTF-8 bytes is
-      // malformed input; refuse it rather than silently encoding it as a resource. Resource-
-      // classified files pass through as-is -- State derives 'resource' vs 'resource:base64'.
+      // 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), `StasisMetro: code-classified file has non-UTF-8 bytes: ${modPath}`)
       }
-      this.#state.addFile(url, { source, isEntry: entries.has(modPath), resource: kind === 'resource', reason: 'StasisMetro' })
+      this.#state.addFile(url, { source, isEntry: entries.has(modPath), resource: kind === 'resource', reason: 'metro' })
     }
   }
 }
 
-// Idiomatic Metro-config wrapper (cf. withNativeWind / withSentryConfig): returns a new
-// config with `serializer.customSerializer` wired so stasis captures the graph + preModules
-// and your existing customSerializer (or Metro's default) still produces the bundle. This is
-// the recommended surface -- it uses the stable customSerializer (so preModules are covered)
-// rather than the experimental hook. Pure (returns a new object; doesn't mutate `config`).
+// Idiomatic Metro-config wrapper: returns a new config with `serializer.customSerializer` wired
+// so stasis captures the graph + preModules while your existing serializer (or Metro's default)
+// still produces the bundle, and with Metro's transform cache dropped so the workers really run.
+// Pure -- returns a new object, doesn't mutate `config`.
 export function withStasis(config = {}, options = {}) {
-  const stasis = new StasisMetro(options)
+  const stasis = new StasisMetro(options, { ownsConfig: true })
   const existing = config.serializer?.customSerializer ?? undefined
+  // Metro's transform cache is a CORRECTNESS hazard here, not a speed knob: it decides which modules
+  // Metro itself LOADS. On a cache hit Metro returns the stored result without calling a worker, so
+  // the worker-side toolchain is never loaded in any process and never reaches the root -- exactly
+  // what the constructor's --child-process assert exists to guarantee. The default store is a
+  // FileStore in the OS tmpdir shared with every other Metro run, so ONE earlier `metro build`/dev
+  // server silently decides what gets attested: a capture over a warm cache drops the toolchain
+  // (exit 0, no warning) and a later frozen run rejects the lockfile it wrote, while a frozen run
+  // over a warm cache passes vacuously (it verifies transforms nobody performed).
+  //
+  // Dropped in EVERY active mode, load included, so the module set can't diverge between record and
+  // replay. `new Transformer` calls getTransformCacheKey() only when the cache is enabled
+  // (metro/src/DeltaBundler/Transformer.js: `this._cache.isDisabled ? '' : ...`), and that call tree
+  // resolves the transformer plus its plugins' cache-key files. Disabled during capture, those edges
+  // are never recorded; left enabled under load they resolve for real and getImport fails closed on
+  // a bundle that cannot know them ("Cannot find module 'metro-transform-worker' imported from
+  // .../getTransformCacheKey.js" -- Metro reports it as "Failed to construct transformer").
+  //
+  // Slower, but the loaded set stops depending on what ran before. These builds are one-shot anyway.
+  const dropCache = stasis.needsTransforms
+  // `undefined` is Metro's own default store, which the user never chose; an array or a
+  // `(MetroCache) => stores` factory is theirs, so replacing it is worth saying out loud.
+  const stores = config.cacheStores
+  if (dropCache && (typeof stores === 'function' || stores?.length > 0)) {
+    console.warn(
+      '[stasis] StasisMetro: ignoring the `cacheStores` in your Metro config for this build -- a cached ' +
+      'transform skips the worker, leaving the toolchain it loads unattested'
+    )
+  }
   return {
     ...config,
+    ...(dropCache && { cacheStores: [] }),
     serializer: {
       ...config.serializer,
       customSerializer: stasis.customSerializer(existing),