@exodus/stasis-plugins 1.0.0-beta.8 → 1.0.0-rc.0

package/src/metro.js

@@ -1,39 +1,51 @@
 import assert from 'node:assert/strict'
-import { isUtf8 } from 'node:buffer'
+import { Buffer } from 'node:buffer'
 import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import { isAbsolute, join } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
-import { resolvePluginState } from './plugins.js'
+import { assertCodeUtf8, classifyOrThrow, resolvePluginState } from './plugins.js'
+import { AUTO_INCLUDES, FILE_STAT, RN_CORE_INCLUDE_FILES, bundleDirHost, looksNative, metroAssetFiles, nativeInputs } from './metro-native.js'
+import { diskHost } from '@exodus/stasis-core/host'
 import { State } from '@exodus/stasis-core/state'
-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'
+// realReadFileSync throughout: the plugin's own reads, which --fs must not record as the program's.
+import { inScope, realReadFileSync } from '@exodus/stasis-core/state-util'
+import { classifyExtension, classifyFormat, isPathWithin, nodeExtFormat, splitNodeModulesPath } from '@exodus/stasis-core/util'
 
 const require = createRequire(import.meta.url)
 
-// 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
-  if (Array.isArray(ep)) return new Set(ep)
-  return new Set()
+const TRANSFORMER = fileURLToPath(new URL('./metro-transformer.js', import.meta.url))
+
+// A graph module's absolute path, or undefined for a virtual one (require.context's ?ctx=, __prelude__).
+function diskPath(module) {
+  const modPath = module?.path
+  return typeof modPath === 'string' && isAbsolute(modPath) && existsSync(modPath) ? modPath : undefined
 }
 
-// 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 = [
-  'metro-runtime/src/modules/asyncRequire.js',
-  '@react-native-community/cli/setup_env.sh',
-]
+// Metro's `graph.entryPoints` is a Set, an Array before ~0.71.
+const entrySet = ({ entryPoints }) => new Set(entryPoints instanceof Set || Array.isArray(entryPoints) ? entryPoints : [])
+
+// The files Metro's transform worker hashes into its cache key for its transform plugins: from the project, else
+// through metro and its transform worker (a pnpm install links metro-transform-plugins only beside them).
+function metroTransformPluginFiles(projectDir) {
+  for (const chain of [['metro-transform-plugins'], ['metro', 'metro-transform-worker', 'metro-transform-plugins']]) {
+    let file
+    try {
+      for (const name of chain) file = require.resolve(name, { paths: [file === undefined ? projectDir : dirname(file)] })
+    } catch {
+      continue
+    }
+    const { getTransformPluginCacheKeyFiles } = require(file)
+    return typeof getTransformPluginCacheKeyFiles === 'function' ? getTransformPluginCacheKeyFiles() : []
+  }
+  return []
+}
 
-// 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.
+// `react-native config`'s output, or null without the RN CLI; a failing CLI throws, as under-attesting breaks frozen runs.
 function loadReactNativeConfig(projectDir) {
   let cliPath
   try {
@@ -41,27 +53,14 @@ function loadReactNativeConfig(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 })
-  }
+  // As vanilla Node: with stasis's env or an inherited loader, it would join this capture nondeterministically.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('EXODUS_STASIS_') && key !== 'NODE_OPTIONS'))
+  const res = spawnSync(process.execPath, [cliPath, 'config'], { cwd: projectDir, encoding: 'utf8', maxBuffer: 128 * 1024 * 1024, 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}` : ''}`
+      `StasisMetro: 'react-native config' exited ${res.status}${res.signal ? ` on signal ${res.signal}` : ''}${detail ? `: ${detail}` : ''}`
     )
   }
   try {
@@ -71,28 +70,27 @@ function loadReactNativeConfig(projectDir) {
   }
 }
 
-// Native when at least one platform config is non-null; an all-null dep is JS-only (already in the graph).
+// 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)
+  return typeof platforms === 'object' && platforms !== null && 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.
+// Metro exports no default serializer: its internal one is under metro/src through ~0.82, metro/private from 0.81.4.
 let metroDefault
 function metroDefaultSerializer() {
   if (metroDefault) return metroDefault
   const M = 'metro'
+  const load = (dir) => ['DeltaBundler/Serializers/baseJSBundle', 'lib/bundleToString'].map((lib) => {
+    const mod = require(`${M}/${dir}/${lib}`)
+    return mod.default ?? mod
+  })
   let baseJSBundle, bundleToString
   try {
-    baseJSBundle = require(`${M}/src/DeltaBundler/Serializers/baseJSBundle`)
-    bundleToString = require(`${M}/src/lib/bundleToString`)
+    [baseJSBundle, bundleToString] = load('src')
   } catch {
     try {
-      baseJSBundle = require(`${M}/private/DeltaBundler/Serializers/baseJSBundle`)
-      bundleToString = require(`${M}/private/lib/bundleToString`)
+      [baseJSBundle, bundleToString] = load('private')
     } catch (cause) {
       throw new Error(
         "StasisMetro: couldn't load Metro's default serializer (tried metro/src and " +
@@ -101,48 +99,29 @@ function metroDefaultSerializer() {
       )
     }
   }
-  // Metro ships CJS; require exposes the fn as the namespace or under `.default`.
-  baseJSBundle = baseJSBundle.default ?? baseJSBundle
-  bundleToString = bundleToString.default ?? bundleToString
-  metroDefault = (entryPoint, preModules, graph, options) =>
-    bundleToString(baseJSBundle(entryPoint, preModules, graph, options)).code
+  metroDefault = (entryPoint, preModules, graph, options) => bundleToString(baseJSBundle(entryPoint, preModules, graph, options)).code
   return metroDefault
 }
 
-// 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).
+// Hooks Metro's serializer, which runs once in the main process with the full graph (a worker's State could never
+// be merged); ./metro-transformer.js is the worker half. Under bundle=load it asserts each edge against the bundle.
+// Prefer withStasis: serializerHook never sees preModules, and only withStasis can drop Metro's transform cache.
 export class StasisMetro {
   #seen = new Set()
+  #realRoot
+  #bundleDirs
   #state
   #resources
-
-  // Base dir for resolution; snapshotted at construction so a later chdir can't skew capture.
+  // Snapshotted so a later chdir can't skew capture.
   #projectDir = process.cwd()
-
-  // Whether this instance already captured; the dev-server rebuild guard in #run trips on the second.
   #ran = false
-
-  // 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 0 or Rule 7)
+    this.#state = state
     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).
+    // The worker toolchain is only ever loaded in workers, so a writing capture needs --child-process.
     if (state && (state.config.writeLockfile || state.config.writeBundle)) {
       assert.ok(
         state.config.childProcess,
@@ -151,66 +130,52 @@ 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 (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.
+      // Opt the children into the loader's SIGTERM shard flush, else jest-worker's forceExit drops a shard. Keyed on
+      // the preload's mode, which the shard channel follows; `||=` honours an explicit opt-out.
       const channel = State.preload ?? state
       if (channel.config.writeLockfile || channel.config.writeBundle) {
         process.env.EXODUS_STASIS_SHARD_SIGNAL_FLUSH ||= '1'
       }
     }
-    // Cache the resolved resources Set for the per-file classify hot path.
     this.#resources = state?.config.resources ?? new Set()
   }
 
-  // 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.
+  // Whether the build relies on Metro really transforming files (capture, frozen and load all do), which a cached
+  // transform would skip.
   get needsTransforms() {
     const config = this.#state?.config
-    if (!config) return false
-    return config.useLockfile || config.bundle
+    return config !== undefined && (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.
+    // Inert: the base as is, never loading Metro's internals.
     if (!this.#state) return baseSerializer
     return (entryPoint, preModules, graph, options) => {
       this.#run(graph, preModules)
-      const serialize = baseSerializer ?? metroDefaultSerializer()
-      return serialize(entryPoint, preModules, graph, options)
+      return (baseSerializer ?? metroDefaultSerializer())(entryPoint, preModules, graph, options)
     }
   }
 
-  // `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 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 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).
+    // Before the one-shot guard: load records nothing, and may re-serialize under a dev server.
+    if (this.#state.config.loadBundle) {
+      this.#assertEdges(graph, preModules)
+      return
+    }
     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(
@@ -221,35 +186,27 @@ export class StasisMetro {
       )
     }
     this.#capture(graph, preModules)
-
-    // 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.
+    // The preload writes itself; a failed build never reaches serialization.
     if (this.#state !== State.preload) this.#state.write()
   }
 
   #capture(graph, preModules) {
     const entries = entrySet(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 graph modules -- an auto-include that landed in the
-    // graph (asyncRequire, when the app uses dynamic import()) is deduped, not re-recorded.
+    const platform = graph.transformOptions?.platform ?? null
+    if (preModules) this.#captureModules(preModules, entries, platform)
+    this.#captureModules(graph.dependencies.values(), entries, platform)
     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.#captureTransformPlugins()
+    // Last, past what is already captured: the native build inputs 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' })
+  #recordCapture(full, source, { format, resource, inferFormat = true, reason = 'metro' }) {
+    this.#state.addFile(pathToFileURL(full).toString(), { source, format: format ?? undefined, resource, inferFormat, reason })
   }
 
-  // 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.
+  // Each of AUTO_INCLUDES resolving within the project root, tagged by the shared classifier so it agrees with any
+  // other path meeting the file (setup_env.sh is 'shell'), else a resource.
   #captureAutoIncludes() {
     for (const specifier of AUTO_INCLUDES) {
       let modPath
@@ -258,61 +215,44 @@ export class StasisMetro {
       } catch {
         continue
       }
-      if (this.#seen.has(modPath)) continue
-      try {
-        this.#state.relative(modPath)
-      } catch {
-        continue
-      }
+      if (this.#seen.has(modPath) || !this.#within(modPath)) continue
       this.#seen.add(modPath)
-      // Real reader: plugin bookkeeping, not a program fs read -- must not be re-recorded by --fs.
       const source = realReadFileSync(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 })
+      this.#recordCapture(modPath, source, { format, resource: format === undefined, inferFormat: false, reason: 'run' })
     }
   }
 
-  // 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.
+  // Metro's worker hashes every transform plugin into its cache key, but loads each only as the build's options call
+  // for it, so a capture loads them all, as the loader then records with their imports, and records each under `run`.
+  #captureTransformPlugins() {
+    for (const file of metroTransformPluginFiles(this.#projectDir)) {
+      if (this.#seen.has(file) || !this.#within(file)) continue
+      this.#seen.add(file)
+      try {
+        require(file)
+      } catch { /* one that can't load can't run under Metro either: its bytes are still recorded */ }
+      this.#recordCapture(file, realReadFileSync(file), { reason: 'run' })
+    }
+  }
+
+  // The native build inputs of the deps autolinking reports, of those the graph reached that ship native code
+  // (integrated by hand), and of RN core, which config names only as reactNativePath. One outside the root is skipped.
   #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.#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 */ }
-    }
+    const rnPath = typeof config.reactNativePath === 'string' && isAbsolute(config.reactNativePath) ? config.reactNativePath : null
+    if (rnPath !== null) roots.add(rnPath)
+    for (const root of roots) if (this.#within(root)) this.#captureNativeTree(root)
+    // RN core's `.js` build scripts, which the walk leaves to Metro but its graph never has.
+    if (rnPath !== null && this.#within(rnPath)) for (const file of RN_CORE_INCLUDE_FILES) this.#captureNativeFile(join(rnPath, file))
   }
 
-  // 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
@@ -326,160 +266,196 @@ export class StasisMetro {
     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).
+  // RN core is walked as 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))
+    const reached = this.#seen.values().map((abs) => splitNodeModulesPath(abs)).filter((nm) => nm && nm.name !== 'react-native')
+    return [...new Set(reached.map((nm) => nm.dir))].filter((root) => looksNative(root, diskHost))
   }
 
-  #looksNative(root) {
-    if (existsSync(join(root, 'ios')) || existsSync(join(root, 'android'))) return true
-    return this.#hasPodspec(root)
+  // In the format nativeInputs gives (none for a codegen source, as Metro's code has none, so none is inferred).
+  #captureNativeTree(root) {
+    for (const { file, source, action, format } of nativeInputs(root, diskHost, { resources: this.#resources, skip: (f) => this.#seen.has(f) })) {
+      this.#seen.add(file)
+      this.#recordCapture(file, source, { format, resource: action === 'resource', inferFormat: false })
+    }
   }
 
-  // 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
+  // bundle=load: Metro resolved every import itself, so each edge must be the one the bundle attests, for the
+  // platform Metro builds.
+  #assertEdges(graph, preModules) {
+    const platform = graph.transformOptions?.platform ?? undefined
+    for (const module of [...(preModules ?? []), ...graph.dependencies.values()]) {
+      const modPath = diskPath(module)
+      if (modPath === undefined) continue
+      const url = pathToFileURL(modPath).toString()
+      for (const [specifier, target] of this.#edges(module)) this.#state.assertImport(url, specifier, target, { platform })
+      for (const files of this.#consumedResources(module, modPath)) {
+        this.#assertOnDisk(files, { what: `which a Babel plugin inlines into '${modPath}'`, servedBy: ['sync', 'async'] })
+      }
+      this.#assertAssetFiles(module, modPath, platform ?? null)
     }
-    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
+  }
+
+  // A module's edges, keyed as the source wrote them (`stasisAsWritten`, where Babel rewrote one), to code and resource
+  // targets alike. One the source doesn't write (`stasisInserted`: a Babel helper, Metro's asyncRequire) is no edge.
+  #edges(module) {
+    const edges = []
+    for (const dep of module.dependencies?.values?.() ?? []) {
+      if (dep?.data?.stasisInserted === true) continue
+      const target = dep?.absolutePath
+      if (typeof target !== 'string' || !isAbsolute(target) || !existsSync(target)) continue
+      if (classifyExtension(target, this.#resources) === 'unknown') continue
+      for (const specifier of dep.data?.stasisAsWritten ?? [dep.data?.name]) {
+        if (typeof specifier === 'string') edges.push([specifier, pathToFileURL(target).toString()])
       }
     }
-    return false
+    return edges
+  }
+
+  #captureModules(modules, entries, platform) {
+    for (const module of modules) {
+      const modPath = diskPath(module)
+      if (modPath === undefined) continue
+      const kind = classifyOrThrow('StasisMetro', modPath, this.#resources)
+      const url = pathToFileURL(modPath).toString()
+      for (const [specifier, target] of this.#edges(module)) this.#state.addImport(url, specifier, target)
+      if (!this.#captureRead(modPath, kind, entries.has(modPath))) continue
+      for (const { file } of this.#consumedResources(module, modPath)) this.#captureRead(file, 'resource')
+      this.#captureAssetFiles(module, modPath, platform)
+    }
+  }
+
+  #within(path) {
+    return isPathWithin(this.#state.root, path)
   }
 
-  // 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
+  #realWithin(path) {
+    let real
     try {
-      entries = realReaddirSync(dir, { withFileTypes: true })
+      real = diskHost.realpath(path)
+      this.#realRoot ??= diskHost.realpath(this.#state.root)
     } catch {
-      return // dir missing / not a directory -- nothing to walk
+      return null
     }
-    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' })
+    return this.#within(real) && isPathWithin(this.#realRoot, real) ? real : null
+  }
+
+  // The resources a Babel plugin inlined in transforming `module` (`stasisConsumed`, `require('./messages.po')`): no
+  // module of Metro's, so no edge, but build inputs. One naming code (babel-plugin-lodash's split imports) is passed
+  // over. -> each as { file: its real path within the root, read: the path read }
+  * #consumedResources(module, modPath) {
+    for (const specifier of module.output?.[0]?.data?.stasisConsumed ?? []) {
+      if (typeof specifier !== 'string' || !(isAbsolute(specifier) || /^\.\.?\//u.test(specifier))) continue
+      const read = resolve(dirname(modPath), specifier)
+      const file = diskHost.stat(read)?.isFile() ? this.#realWithin(read) : null
+      if (file === null) continue
+      if (classifyOrThrow('StasisMetro', file, this.#resources, `'${file}', which a Babel plugin inlines into '${modPath}'`) === 'code') continue
+      yield { file, read }
     }
   }
 
-  #captureModules(modules, entries) {
-    for (const module of modules) {
-      // module.path is the absolute path (both graph modules and preModules carry it).
-      const modPath = module?.path
-      // 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)
-      if (kind === 'unknown') {
-        throw new Error(
-          `StasisMetro: unsupported extension for '${modPath}' -- ` +
-          `add its extension or filename to the plugin's resources option or stop importing it`
-        )
-      }
-      const url = pathToFileURL(modPath).toString()
+  // Capture `path` once, as the `kind` classifyExtension gives it: code with only the format its name gives
+  // (nodeExtFormat), as Metro transforms it from source. From disk: addFile re-reads it to assert the bytes.
+  // -> whether it was new
+  #captureRead(path, kind, isEntry = false) {
+    if (this.#seen.has(path)) return false
+    this.#seen.add(path)
+    const source = realReadFileSync(path)
+    if (kind === 'code') assertCodeUtf8('StasisMetro', path, source)
+    const format = kind === 'code' ? nodeExtFormat(path) : undefined
+    const resource = kind === 'resource'
+    this.#state.addFile(pathToFileURL(path).toString(), { source, format, isEntry, resource, inferFormat: false, reason: 'metro' })
+    return true
+  }
 
-      // 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
-        if (typeof target !== 'string' || !isAbsolute(target) || !existsSync(target)) continue
-        if (typeof specifier !== 'string') continue
-        if (classifyExtension(target, this.#resources) !== 'code') continue
-        this.#state.addImport(url, specifier, pathToFileURL(target).toString())
-      }
+  // The files Metro reads to build the asset module `module` (its `scales` and `hash`) and copies out with it: it
+  // and its other scales (metroAssetFiles, Metro's own rule for `platform`). No import names one, so no edge.
+  #assetFiles(module, modPath, platform) {
+    return module.output?.[0]?.type === 'js/module/asset' ? metroAssetFiles(modPath, platform, this.#assetDirHost()) : []
+  }
 
-      if (this.#seen.has(modPath)) continue
-      this.#seen.add(modPath)
+  // Where Metro lists an asset's files: on disk, but under load with --fs=async, which serves the listing, the
+  // bundle's (a file added on disk since is none of the asset's; one gone from disk holds no drift).
+  #assetDirHost() {
+    const state = this.#state
+    if (!state.config.loadBundle || state.config.fs !== 'async') return diskHost
+    return {
+      readdir: (dir) => state.getFsDirFamily(pathToFileURL(dir).toString())?.map((name) => ({ name })) ?? diskHost.readdir(dir),
+      stat: (path) => diskHost.stat(path) ?? (state.getFsStatFamily(pathToFileURL(path).toString()) === 'file' ? FILE_STAT : null),
+    }
+  }
 
-      // 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; 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: 'metro' })
+  #bundleDirHost() {
+    return (this.#bundleDirs ??= bundleDirHost(this.#state))
+  }
+
+  // By the name Metro reads each by, with the bytes it reads there, so a load holds that name to them. One linked
+  // from outside the project is passed over, as is one of a kind unknown (the module itself was refused).
+  #captureAssetFiles(module, modPath, platform) {
+    for (const read of this.#assetFiles(module, modPath, platform)) {
+      const kind = classifyExtension(read, this.#resources)
+      if (kind !== 'unknown' && this.#realWithin(read) !== null) this.#captureRead(read, kind)
     }
   }
+
+  // Metro reads an asset's files from disk, past the stasis transformer: each must be the bundle's under that name (a
+  // scale added since the capture, or one a symlink redirects, is drift), and each the bundle carries must still be
+  // there (one gone builds another asset) -- unless --fs=async serves them.
+  #assertAssetFiles(module, modPath, platform) {
+    const read = this.#assetFiles(module, modPath, platform)
+    if (read.length === 0) return
+    const what = `a file of the asset '${modPath}' Metro builds`
+    for (const path of read) {
+      if (diskHost.stat(path)?.isFile()) this.#assertOnDisk({ file: path, read: path }, { what, servedBy: ['async'] })
+    }
+    if (!inScope(this.#state, pathToFileURL(modPath).toString())) return
+    for (const file of metroAssetFiles(modPath, platform, this.#bundleDirHost())) {
+      if (read.includes(file)) continue
+      throw new Error(`StasisMetro: '${file}', ${what} as the bundle carries it, is gone -- Metro would build the asset without it under load; restore it`)
+    }
+  }
+
+  // `read`, a file Metro reads from disk past the stasis transformer, held to the bundle's bytes for `file` where in
+  // scope (getFile throws on one it doesn't carry) -- unless --fs, in a mode of `servedBy`, serves it by the path read.
+  #assertOnDisk({ file, read }, { what, servedBy }) {
+    const state = this.#state
+    const url = pathToFileURL(file).toString()
+    if (!inScope(state, url)) return
+    if (servedBy.includes(state.config.fs) && state.getFsFileFamily(pathToFileURL(read).toString()) !== undefined) return
+    const { source } = state.getFile(url)
+    if (realReadFileSync(file).equals(Buffer.isBuffer(source) ? source : Buffer.from(source))) return
+    throw new Error(
+      `StasisMetro: '${file}', ${what}, differs on disk from the bundle -- ` +
+      'Metro\'s build reads it from disk under load; restore it, or run with --fs to serve it from the bundle'
+    )
+  }
 }
 
-// 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`.
+// A new Metro config whose customSerializer captures the graph and preModules while the existing serializer (else
+// Metro's default) still produces the bundle, and whose transformer runs through ./metro-transformer.js.
 export function withStasis(config = {}, 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.
+  // Metro's transform cache decides which modules Metro loads: a hit skips the worker, so its toolchain goes
+  // unattested and a frozen run passes vacuously, and the default store is shared with every other Metro run. Dropped
+  // under load too: an enabled cache resolves its cache-key files, which a bundle can't know, failing getImport.
+  const active = stasis.needsTransforms
+  // `undefined` is Metro's own default store; an array or a factory is the user's, so replacing it is announced.
   const stores = config.cacheStores
-  if (dropCache && (typeof stores === 'function' || stores?.length > 0)) {
+  if (active && (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'
     )
   }
+  // Metro hands `transformer` to each worker's transformer as is.
   return {
     ...config,
-    ...(dropCache && { cacheStores: [] }),
-    serializer: {
-      ...config.serializer,
-      customSerializer: stasis.customSerializer(existing),
-    },
+    ...(active && {
+      cacheStores: [],
+      transformerPath: TRANSFORMER,
+      transformer: { ...config.transformer, stasisBaseTransformerPath: config.transformerPath },
+    }),
+    serializer: { ...config.serializer, customSerializer: stasis.customSerializer(existing) },
   }
 }