@exodus/stasis-plugins 1.0.0-beta.1 → 1.0.0-beta.10

package/src/plugins.js

@@ -1,9 +1,5 @@
-// Plugin <-> preload coordination (resolvePluginState): decides which State a bundler
-// plugin drives, given its options and the ambient preload. The per-file classification
-// helpers (pathExt / parseResourcesOption / classifyExtension) live in util.js -- they're
-// pure and shared with State's `--fs` capture, so both paths classify against one source
-// of truth. Kept out of state.js because the coordination only consults State.preload +
-// Config helpers, never State internals.
+// Plugin <-> preload coordination (resolvePluginState): decides which State a bundler plugin
+// drives, given its options and the ambient preload.
 
 import assert from 'node:assert/strict'
 
@@ -12,58 +8,42 @@ import { ensureStateForLoader, isLoaderInstalled } from '@exodus/stasis-core/hoo
 import { State } from '@exodus/stasis-core/state'
 import { extSetsEqual, parseResourcesOption } from '@exodus/stasis-core/util'
 
-// Decides which State a bundler plugin (StasisWebpack / StasisEsbuild) should run against,
-// given its constructor options and the ambient preload (or lack thereof). Returns either
-// { state: null, isNoop: true } -- plugin should register no hooks and become inert -- or
-// { state, isNoop: false } -- plugin should drive the returned State.
-//
-// The lockfile is always unified: a plugin never specifies its own lockfile position
-// (validatePluginOptions rejects `lockFile`). When an ambient preload exists the plugin
-// MUST share it -- it either reuses the preload State outright or runs as a sidecar that
-// shares the preload's hashes/entries/modules + lockfile data. Only the BUNDLE may split
-// off per-plugin (via bundleFile, a sidecar). A process that genuinely needs a non-default
-// lockfile location sets it process-wide (Config / EXODUS_STASIS_LOCK_FILE), not per-plugin.
-//
-// Rules:
-//  1. Plugin asking for any lockfile mode other than 'none' / 'ignore' requires a preload.
-//     Without one it's a hard throw -- the lockfile would otherwise only cover the bundled
-//     app and silently miss every dependency the bundler itself pulled in.
-//  2. With a preload, the plugin's lock mode must agree with the preload's.
-//  3. Lockfile is unified: when plugin and preload align we reuse the preload State so a
-//     single lockfile is written.
-//  4. Bundle may split: with a preload that already has bundle on, the plugin cannot disable
-//     bundle and the bundle mode must match. The plugin's bundleFile, however, may differ
-//     -- in which case we construct a sidecar State sharing the preload's lockfile data.
+// Decides which State a bundler plugin runs against, given its options and the ambient preload.
+// Returns { state: null, isNoop: true } (inert -- register no hooks) or { state, isNoop: false }.
+// The lockfile is always unified (plugins can't set lockFile); only the BUNDLE may split per-plugin
+// (bundleFile -> sidecar). Rules, referenced by number in the code below:
+//  0. No preload, not under `stasis run`, no lock/bundle option -> inert (safe on a plain build).
+//  1. A writing/verifying lock mode without a preload throws (it would miss the bundler's own deps).
+//  2. With a preload, the plugin's lock mode must agree with it.
+//  3. When plugin and preload align, reuse the preload State (single lockfile).
+//  4. Preload with bundle on: plugin can't disable it and the mode must match; bundleFile may differ.
 //  5. Same bundleFile (or unspecified) reuses the preload State.
-//  6. Different bundleFile creates a sidecar.
-//  7. Plugin with lock='none' AND bundle='none' and no preload is a no-op (lets framework
-//     plugins be env-controlled off without throwing on the lock=none/bundle=none invariant).
+//  6. Different bundleFile creates a sidecar sharing the preload's lockfile data.
+//  7. lock='none' AND bundle='none' with no preload is a no-op (env-controlled-off framework plugins).
 export function resolvePluginState(label, options, cwd) {
   validatePluginOptions(label, options)
-  const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess, resources } = options
-  // Same-instance fast path: the plugin's stasis-core IS the binary's, the
-  // hooks are installed, but the lazy initState hasn't fired yet (plugin
-  // ran AHEAD of the first user-file load -- webpack constructs plugins
-  // during config-parse before user code executes). Force-init now so the
-  // plugin lands in the ambient branch and inherits the loader's Config.
-  // We deliberately do NOT do this when the loader is a SEPARATE module
-  // instance (different stasis-core copy in the plugin's node_modules vs
-  // the binary's): force-init there would create a phantom State.preload
-  // with its own beforeExit/exit save handlers that race the real loader's
-  // lockfile write. Cross-instance detection lives below via env vars.
+  const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess, packageJSON, resources } = options
+  // Same-instance fast path: loader installed but lazy initState hasn't fired (webpack builds plugins
+  // before user code). Force-init so the plugin lands in the ambient branch. NOT for a separate
+  // stasis-core copy -- that would mint a phantom State.preload racing the real loader's write.
   if (!State.preload && isLoaderInstalled()) ensureStateForLoader()
   const ambient = State.preload
 
   if (!ambient) {
+    // "Under stasis run" detection: the bin script always exports EXODUS_STASIS_LOCK, so it's a
+    // process-wide signal regardless of which stasis-core copy hosts this code.
+    const underStasisRun = process.env.EXODUS_STASIS_LOCK !== undefined
+
+    // Rule 0: no preload, not under `stasis run`, no lock/bundle option -> do nothing, so a bare
+    // plugin sits inertly in a plain build. Capture is governed elsewhere (env or explicit options).
+    if (!underStasisRun && lock === undefined && bundle === undefined) {
+      return { state: null, isNoop: true }
+    }
+
     if (lock === 'none' && bundle === 'none') return { state: null, isNoop: true } // Rule 7
-    // Rule 7 needs BOTH to be 'none'. A partial opt-out -- one field is 'none' but
-    // the other was simply omitted -- would otherwise fall through to either a
-    // misleading Rule 1 throw about the default lockfile mode, or to Config's
-    // generic "stasis needs a lockfile or a bundle" RangeError. Catch the partial
-    // case explicitly. Only fires when the OTHER field is undefined: an active
-    // bundle mode like `bundle:'load'` / `'frozen'` / `'add'` paired with
-    // `lock:'none'` is a legitimate "bundle as trust root" config that Config
-    // accepts (see config.js's bundle=load / bundle=frozen rules).
+    // A partial opt-out (one field 'none', the other omitted) would otherwise hit a misleading
+    // Rule 1 throw or Config's generic error; catch it explicitly. An active bundle mode paired
+    // with lock='none' is a legitimate "bundle as trust root" config, so only fire when the other is undefined.
     if ((lock === 'none' && bundle === undefined) || (bundle === 'none' && lock === undefined)) {
       throw new Error(
         `${label}: to opt out of stasis without a preload, pass BOTH lock='none' and bundle='none' ` +
@@ -71,18 +51,9 @@ export function resolvePluginState(label, options, cwd) {
         `bundle=${bundle === undefined ? 'default' : `'${bundle}'`})`
       )
     }
-    // Cross-instance "running under stasis run" detection: `stasis run`'s
-    // bin script always sets EXODUS_STASIS_LOCK on the spawned child (even
-    // for the default `--lock=add`), so the env var is a reliable
-    // process-wide signal regardless of which stasis-core copy is hosting
-    // this code. When set, the runtime's loader is providing full lockfile
-    // coverage for the process; the plugin's lockfile (at its own path,
-    // typically a sidecar like `sources.stasis.lock.json`) is a sibling
-    // artifact covering bundler-side resolutions, and the "lock=add needs
-    // a preload" rationale doesn't apply. Skip that rule under stasis run;
-    // Config below will pick up env-var defaults (lock/scope/bundle) for
-    // the standalone plugin State.
-    const underStasisRun = process.env.EXODUS_STASIS_LOCK !== undefined
+    // A writing/verifying lock (add|replace|frozen) still needs a preload unless under stasis run
+    // (whose loader gives full coverage). `lock` may be undefined here if only a writing `bundle`
+    // was passed, so the throw below distinguishes a defaulted mode from an explicit one.
     const effectiveLock = lock ?? DEFAULT_LOCK
     if (!underStasisRun && effectiveLock !== 'none' && effectiveLock !== 'ignore') {
       const phrasing = lock === undefined
@@ -96,16 +67,12 @@ export function resolvePluginState(label, options, cwd) {
     return { state: new State(cwd, options), isNoop: false }
   }
 
-  // Preload is active. Since `lockFile` is not a plugin option, the lockfile is
-  // necessarily the ambient's -- the plugin shares it (reuse or sidecar below).
-  // Enforce coordination on the remaining fields before deciding which.
+  // Preload active: the lockfile is necessarily the ambient's. Enforce field coordination, then reuse or sidecar.
   const pc = ambient.config
   if (lock !== undefined && lock !== pc.lock) {
     throw new Error(`${label}: lock='${lock}' conflicts with active preload lock='${pc.lock}'`)
   }
-  // scope/debug/childProcess must agree with the preload on every preload-coupled path -- reuse
-  // adopts preload's config wholesale, and sidecar copies it field by field. Catch a
-  // disagreement here rather than silently overriding the user's value.
+  // scope/debug/childProcess must agree with the preload (reuse adopts it, sidecar copies it).
   if (scope !== undefined && scope !== pc.scope) {
     throw new Error(`${label}: scope='${scope}' conflicts with active preload scope='${pc.scope}'`)
   }
@@ -115,10 +82,11 @@ export function resolvePluginState(label, options, cwd) {
   if (childProcess !== undefined && childProcess !== pc.childProcess) {
     throw new Error(`${label}: childProcess=${childProcess} conflicts with active preload childProcess=${pc.childProcess}`)
   }
-  // resources is process-wide (a Config field), so a plugin's allowlist must agree with
-  // the preload's -- reuse adopts it wholesale, a sidecar inherits it. Compare the parsed
-  // sets (order/dupes/case don't matter), failing on a real disagreement rather than
-  // letting one plugin silently widen the attested asset set.
+  if (packageJSON !== undefined && packageJSON !== pc.packageJSON) {
+    throw new Error(`${label}: packageJSON=${packageJSON} conflicts with active preload packageJSON=${pc.packageJSON}`)
+  }
+  // resources is process-wide, so a plugin's allowlist must agree with the preload's -- compare
+  // parsed sets (order/dupes/case-insensitive) to prevent one plugin silently widening the asset set.
   if (resources !== undefined) {
     const parsed = parseResourcesOption(label, resources)
     if (!extSetsEqual(parsed, pc.resources)) {
@@ -128,10 +96,8 @@ export function resolvePluginState(label, options, cwd) {
     }
   }
 
-  // A plugin instance is attaching to the preload now (its constructor called us). Mark it so the
-  // preload's bundle `reason` map can tell apart files run merely fs-READS during the build (the
-  // plugin's modules, e.g. webpack+babel reading app source through --fs) from genuine run
-  // dependencies recorded before any plugin existed. See State#bundleReason.
+  // Mark the plugin attached so the preload's bundle `reason` map can distinguish files merely
+  // fs-READ during the build from genuine run dependencies recorded before any plugin existed.
   ambient.markPluginAttached()
 
   if (pc.bundle) {
@@ -151,8 +117,7 @@ export function resolvePluginState(label, options, cwd) {
       assertOptionsMatchConfig(pc, options)
       return { state: ambient, isNoop: false }
     }
-    // Rule 6: different path -- sidecar inherits preload's modes, overrides bundleFile
-    // (and resourcesBundleFile if the plugin provided one for a split layout).
+    // Rule 6: different path -- sidecar inherits preload's modes, overrides bundleFile.
     const sidecar = new State(cwd, {
       parent: ambient,
       scope: pc.scope,
@@ -162,21 +127,19 @@ export function resolvePluginState(label, options, cwd) {
       resourcesBundleFile,
       debug: pc.debug,
       childProcess: pc.childProcess,
+      packageJSON: pc.packageJSON,
       resources: [...pc.resources],
+      // carried over: sidecars skip stasis.config.json discovery
+      brotliQuality: pc.brotliQuality,
     })
     return { state: sidecar, isNoop: false }
   }
 
   // Preload exists but has no bundle.
   if (bundle === undefined || bundle === 'none' || bundle === 'ignore') {
-    // Plugin doesn't want a bundle either: just reuse preload for lockfile coverage.
-    // bundle='ignore' here legitimately disagrees with preload's bundleMode ('none'),
-    // both mean "no bundle written by the plugin", so skip the bundle field in the
-    // cross-check rather than letting assertOptionsMatchConfig flag the difference.
-    // Defense-in-depth: the strip is only safe when the preload's bundleMode is
-    // actually in the no-bundle equivalence class. If a future bundleMode reads as
-    // `!pc.bundle` but means something else, the strip would silently mask a real
-    // disagreement -- the assert pins the contract to today's two values.
+    // Plugin wants no bundle either: reuse preload for lockfile coverage. bundle='ignore' vs the
+    // preload's 'none' both mean "no plugin bundle", so strip the bundle field from the cross-check;
+    // the assert pins that strip to today's no-bundle values so a future mode can't silently mask a disagreement.
     assert.ok(pc.bundleMode === 'none' || pc.bundleMode === 'ignore',
       `unexpected preload bundleMode='${pc.bundleMode}' in the no-bundle branch`)
     const { bundle: _b, ...rest } = options
@@ -198,7 +161,9 @@ export function resolvePluginState(label, options, cwd) {
     resourcesBundleFile,
     debug: pc.debug,
     childProcess: pc.childProcess,
+    packageJSON: pc.packageJSON,
     resources: [...pc.resources],
+    brotliQuality: pc.brotliQuality, // carried over, like the Rule 6 sidecar above
   })
   return { state: sidecar, isNoop: false }
 }

package/src/rollup.js

@@ -0,0 +1,327 @@
+import assert from 'node:assert/strict'
+import { isUtf8 } from 'node:buffer'
+import { existsSync } from 'node:fs'
+import { isBuiltin } from 'node:module'
+import { dirname, isAbsolute, resolve as resolvePath } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { resolvePluginState } from './plugins.js'
+import { State } from '@exodus/stasis-core/state'
+// Pre-patch snapshot, not `import { readFile }`: under --fs=async that builtin is patched, and
+// this plugin loads after, so a direct import would route rollup's reads through the capture hook.
+import { realReadFile } from '@exodus/stasis-core/state-util'
+import { classifyExtension } from '@exodus/stasis-core/util'
+
+// Rollup chains resolveId/load hooks first-non-null-wins, so put this plugin FIRST in `plugins`:
+// listed later, a sibling resolver (node-resolve, commonjs) answers before stasis sees the edge --
+// capture would under-record specifiers and load mode would fall back to sibling disk resolution
+// (file BYTES still fail closed at the load hook, which serves every in-scope path it reaches).
+export class StasisRollup {
+  #seen = new Set()
+  #state
+  #resources
+
+  // Build starts observed by this instance (watch rebuilds and separate rollup() calls sharing one
+  // plugin object both re-fire buildStart); the second is refused there.
+  #captureBuildCount = 0
+
+  name = 'stasis'
+
+  constructor(options = {}, unsupported = undefined) {
+    // StasisEsbuild's second { loaders, transform } bag has no rollup analogue (transforms run as
+    // ordinary rollup plugins after this one) -- refuse it so a port doesn't silently drop it.
+    assert.equal(unsupported, undefined,
+      'StasisRollup takes a single options argument -- there is no esbuild-style { loaders, transform } bag (run transforms as rollup plugins after this one)')
+    // A caller that owns a State (e.g. tests) can pass it directly; a foreign-copy State fails
+    // closed via the instanceof miss.
+    const state = options instanceof State
+      ? options
+      : resolvePluginState('StasisRollup', options, process.cwd()).state
+    this.#state = state
+    // Cache the resolved resources Set for the per-file classify hot path.
+    this.#resources = state?.config.resources ?? new Set()
+    if (!state) return // noop plugin: no hooks assigned, rollup sees only `name`
+
+    // Hooks are per-instance functions, not prototype methods: rollup invokes them with `this`
+    // bound to its PluginContext (whose resolve/getModuleInfo the hooks need), so instance state
+    // has to arrive via the closure instead.
+    const plugin = this
+    this.resolveId = async function (source, importer, opts) {
+      return plugin.#resolveId(this, source, importer, opts)
+    }
+    this.load = async function (id) {
+      return plugin.#load(this, id)
+    }
+
+    // A warm `cache:` from a previous build makes rollup reuse cached module code and dependency
+    // resolutions WITHOUT calling resolveId/load, so a capture would silently drop those modules'
+    // edges and bytes from the attestation, and a load-mode build would consume cached code no
+    // hook re-verified. Strip it (rollup still builds a fresh cache for this run) -- StasisMetro's
+    // withStasis drops Metro's cacheStores for the same hazard. `cache: true/false` carries no
+    // prior modules, so only an object is a hazard.
+    this.options = (inputOptions) => {
+      if (typeof inputOptions.cache !== 'object' || inputOptions.cache === null) return null
+      console.warn(
+        '[stasis] StasisRollup: ignoring the `cache` option for this build -- cached modules ' +
+        'bypass the stasis hooks, so their imports and bytes would go unattested at capture and ' +
+        'unverified at load'
+      )
+      return { ...inputOptions, cache: undefined }
+    }
+
+    if (!state.config.loadBundle) {
+      // Watch/rebuild 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. Watch rebuilds
+      // (and a second rollup() call reusing this instance) re-fire buildStart, so an instance counter
+      // catches the second and errors.
+      this.buildStart = () => {
+        plugin.#captureBuildCount += 1
+        if (plugin.#captureBuildCount === 1) return
+        throw new Error(
+          'StasisRollup: watch/rebuild is not supported for capture -- run a one-shot build (rebuilds would silently attest stale content)'
+        )
+      }
+
+      // Capture epilogue: flag entries from the completed graph, then persist. resolveId's
+      // opts.isEntry is never trusted for attestation -- rollup defaults it to !importer, so a
+      // sibling's bare `this.resolve(id)` probe looks exactly like an entry and would widen the
+      // attested set of runnable roots. The graph's ModuleInfo.isEntry is authoritative (real
+      // `input` entries and emitFile'd chunks -- both genuinely run as roots; probes never join
+      // the graph).
+      this.buildEnd = function (error) {
+        return plugin.#buildEnd(this, error)
+      }
+    }
+  }
+
+  // Rollup asset plugins (url/image/...) read their file from disk themselves inside their own
+  // load hook -- there is no seam to hand them attested bytes (load hooks don't chain), so a
+  // resource under bundle=load can't be served faithfully and must fail loudly, not fall back to
+  // unattested disk bytes.
+  #refuseResourceLoad(path) {
+    throw new Error(
+      `StasisRollup: bundle=load can't serve resource '${path}' -- rollup asset plugins read ` +
+      'from disk directly, so attested replay is not possible; keep sources on disk and use a ' +
+      'capture/verify mode instead'
+    )
+  }
+
+  // Accept only the `type` import attribute; other attributes aren't persistable to the lockfile
+  // yet. Checked only where an edge is recorded (addImport) or queried (getImport), so an
+  // attributed EXTERNAL passes through untouched -- exactly as under StasisEsbuild, whose
+  // equivalent assert sits in onLoad, which externals never reach.
+  #assertPersistableAttributes(attrs) {
+    for (const k of Object.keys(attrs)) {
+      assert.equal(k, 'type', `unsupported import attribute: ${k}`)
+    }
+  }
+
+  // Throws when `id` is a '?'/'#'-suffixed variant of an on-disk path (rollup's plugin-param
+  // convention, e.g. './icon.svg?url'): the underlying bytes feed the build, but the suffixed key
+  // can't be persisted or replayed, so skipping it would silently leave a build input unattested
+  // (a frozen run would be blind to tampering). The esbuild plugin refuses its `suffix` analogue
+  // the same way. A fully virtual id (nothing on disk under the stripped path either) is a
+  // sibling plugin's own module and stays skippable, like \0-prefixed ids.
+  #refuseSuffixedOnDisk(id) {
+    const stripped = id.split(/[?#]/u, 1)[0]
+    if (stripped !== id && existsSync(stripped)) {
+      throw new Error(
+        `StasisRollup: can't attest suffixed module id '${id}' (the on-disk file '${stripped}' ` +
+        "with a '?'/'#' suffix) -- stasis can't persist suffixes; disable the plugin minting it " +
+        'or import the file directly'
+      )
+    }
+  }
+
+  // True when `id` is an on-disk file; false defers a virtual id to its owning plugin. The
+  // dangerous middle case -- a suffixed variant of a real file -- refuses instead (see above).
+  #existsOrRefuseSuffixed(id) {
+    if (existsSync(id)) return true
+    this.#refuseSuffixedOnDisk(id)
+    return false
+  }
+
+  #classifyOrThrow(id) {
+    const kind = classifyExtension(id, this.#resources)
+    if (kind === 'unknown') {
+      throw new Error(
+        `StasisRollup: unsupported extension for '${id}' -- add its extension or filename to the plugin's resources option or stop importing it`
+      )
+    }
+    return kind
+  }
+
+  #inRoot(path) {
+    try {
+      this.#state.relative(path)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async #resolveId(ctx, source, importer, opts) {
+    // Built-ins are never bundled or recorded as edges; hand them back to rollup (null) so the
+    // user's external config applies. SECURITY: never consult getImport for a builtin name, so a
+    // tampered bundle can't redirect `fs` to an arbitrary file.
+    if (isBuiltin(source)) return null
+    const { isEntry, attributes: attrs = {} } = opts
+
+    // Load mode: resolution comes from the bundle's import map, not rollup's resolver -- the file
+    // may not be on disk. Return the original absolute path so output bytes match a capture build.
+    if (this.#state.config.loadBundle) {
+      if (isEntry) {
+        // Entry-flagged resolutions cover real `input` entries, emitFile'd chunks, and -- because
+        // rollup defaults isEntry to !importer -- bare sibling probes. Anchor like rollup's own
+        // resolver: against the importer when one exists (emitFile passes it), else cwd (like the
+        // run loader). No assertEntry here: a probe is indistinguishable from an entry at this
+        // point, so the load hook asserts from the graph's authoritative isEntry instead -- and a
+        // probe that never loads is never asserted.
+        if (source.startsWith('file:')) return { id: fileURLToPath(source) }
+        const base = importer && isAbsolute(importer) && !importer.startsWith('\0')
+          ? dirname(importer)
+          : process.cwd()
+        return { id: resolvePath(base, source) }
+      }
+      // A missing, virtual, or out-of-root importer was never the bundle's responsibility -- defer to rollup.
+      if (!importer || importer.startsWith('\0') || !isAbsolute(importer)) return null
+      if (!this.#inRoot(importer)) return null
+      const parentURL = pathToFileURL(importer).toString()
+      this.#assertPersistableAttributes(attrs)
+      // Forward import attributes (`with { type: 'json' }`) so plugin-capture round-trips to
+      // plugin-load, both keyed under `* (with: ...)`.
+      let url, format
+      try {
+        ;({ url, format } = this.#state.getImport(parentURL, source, { importAttributes: attrs }))
+      } catch (err) {
+        // No attested edge -- at a successful capture that's an EXTERNAL (never recorded as an
+        // edge), so hand it back to rollup. File BYTES still fail closed at the load hook.
+        // A non-MODULE_NOT_FOUND error is a real fault -- rethrow.
+        if (err?.code === 'ERR_MODULE_NOT_FOUND') return null
+        throw err
+      }
+      const path = fileURLToPath(url)
+      // Refuse a resource only when load mode would actually serve it: an out-of-scope workspace
+      // resource under node_modules scope comes from disk via the user's asset plugin, exactly
+      // like a capture build (the load hook defers it with the same scope gate).
+      if (Bundle.isResourceFormat(format) && (this.#state.config.full || this.#state.inNodeModules(url))) {
+        this.#refuseResourceLoad(path)
+      }
+      // KNOWN GAP: sibling resolution metadata (moduleSideEffects, syntheticNamedExports, meta)
+      // isn't persisted in the bundle, so load mode can't replay it -- tree-shaking of a module a
+      // sibling marked side-effect-free at capture may differ from the capture build's output.
+      return { id: path }
+    }
+
+    // Capture: run the remaining resolveId hooks plus rollup's default algorithm (skipSelf guards
+    // re-entry), record the observed edge, and pass the resolution through unchanged.
+    const resolution = await ctx.resolve(source, importer, { ...opts, skipSelf: true })
+    if (!resolution || resolution.external) return resolution
+    const { id } = resolution
+    // Skip virtual modules (\0-prefixed or otherwise not an on-disk file); a suffixed variant of
+    // an on-disk file refuses inside the check rather than slipping through unattested.
+    if (id.startsWith('\0') || !isAbsolute(id) || !this.#existsOrRefuseSuffixed(id)) return resolution
+    this.#classifyOrThrow(id)
+
+    // Record the edge for BOTH code and resource targets, but never for entries (matching the
+    // loader) and never for an out-of-root importer (not the project's graph; load mode defers
+    // those parents the same way). Entries are flagged from the graph in buildEnd instead of
+    // trusting opts.isEntry -- see the constructor comment.
+    if (!isEntry && importer && isAbsolute(importer) && !importer.startsWith('\0') && this.#inRoot(importer)) {
+      this.#assertPersistableAttributes(attrs)
+      if (!this.#inRoot(id)) {
+        throw new Error(
+          `StasisRollup: '${source}' imported from ${importer} resolves outside the project root and can't be attested: ${id}`
+        )
+      }
+      this.#state.addImport(pathToFileURL(importer).toString(), source, pathToFileURL(id).toString(), { importAttributes: attrs })
+    }
+    return resolution
+  }
+
+  async #load(ctx, id) {
+    // Load mode: serve bytes the bundle attested. getFile verifies the hash and throws on a file
+    // the bundle doesn't carry -- a missing in-scope file is a hard error, not a disk fallback.
+    // In scope = full (everything under state.root) or node_modules-only per scope; ids other
+    // plugins resolved land here too, so the gate can't rely on our own resolveId alone.
+    if (this.#state.config.loadBundle) {
+      if (id.startsWith('\0') || !isAbsolute(id)) return null
+      if (!this.#inRoot(id)) return null // out of the project root -- not ours
+      const url = pathToFileURL(id).toString()
+      // Entries are asserted here from the graph's authoritative isEntry (known before load runs):
+      // a sibling's bare resolve() probe carries isEntry too but never loads, so only genuine
+      // roots reach this gate.
+      if (this.#state.config.full && ctx.getModuleInfo(id)?.isEntry) this.#state.assertEntry(url)
+      if (!this.#state.config.full && !this.#state.inNodeModules(url)) return null
+      const { source, format } = this.#state.getFile(url)
+      if (Bundle.isResourceFormat(format)) this.#refuseResourceLoad(id)
+      // Code is stored as UTF-8 text, exactly what rollup's parser expects.
+      return source
+    }
+
+    // Capture. Skip virtual modules and classify the rest exactly like the resolve hook (a sibling
+    // resolver may have minted ids our resolveId never saw). One read doubles as the existence
+    // check: ENOENT defers -- unless the id is a suffixed variant of an on-disk file, which
+    // refuses -- and any other read error is real.
+    if (id.startsWith('\0') || !isAbsolute(id)) return null
+    let source
+    try {
+      source = await realReadFile(id)
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err
+      this.#refuseSuffixedOnDisk(id)
+      return null
+    }
+    const kind = this.#classifyOrThrow(id)
+    if (!this.#inRoot(id)) {
+      throw new Error(`StasisRollup: module is outside the project root and can't be attested: ${id}`)
+    }
+    const url = pathToFileURL(id).toString()
+
+    if (kind === 'resource') {
+      // Mark as a resource (State picks 'resource' vs 'resource:base64' from bytes). Return null:
+      // loading it into the graph is the user's asset plugin's job.
+      if (!this.#seen.has(id)) {
+        this.#seen.add(id)
+        this.#state.addFile(url, { source, resource: true, reason: 'rollup' })
+      }
+      return null
+    }
+
+    // Code-classified files must be UTF-8; refuse non-UTF-8 rather than silently encode as a resource.
+    assert.ok(isUtf8(source), `StasisRollup: code-classified file has non-UTF-8 bytes: ${id}`)
+
+    if (!this.#seen.has(id)) {
+      this.#seen.add(id)
+      this.#state.addFile(url, { source, reason: 'rollup' })
+    }
+
+    // Return the attested bytes so the build consumes exactly what was recorded (transform hooks
+    // still run after, symmetrically with load mode).
+    return source.toString('utf8')
+  }
+
+  // Capture epilogue (see the constructor comment): flag real entries from the completed graph,
+  // then write standalone/sidecar States -- only on a clean build (a partial one would overwrite
+  // the user's good file). buildEnd, not closeBundle: the capture is complete once the graph is,
+  // and closeBundle only fires when the caller remembers bundle.close().
+  async #buildEnd(ctx, error) {
+    if (error) return
+    const entryIds = [...ctx.getModuleIds()].filter((id) => {
+      if (!this.#seen.has(id)) return false // virtual/external/unattested ids never joined the capture
+      const info = ctx.getModuleInfo(id)
+      return Boolean(info?.isEntry) && !info.isExternal
+    })
+    // Re-record each entry with the flag set: addFile re-verifies the bytes against disk, and a
+    // RESOURCE entry fails loudly here ('a resource can't be an entry'), matching StasisEsbuild,
+    // instead of silently writing an artifact whose entries list omits the build's real entry.
+    const sources = await Promise.all(entryIds.map((id) => realReadFile(id)))
+    for (const [i, id] of entryIds.entries()) {
+      const resource = classifyExtension(id, this.#resources) === 'resource'
+      this.#state.addFile(pathToFileURL(id).toString(), { source: sources[i], isEntry: true, resource, reason: 'rollup' })
+    }
+    // The preload writes itself (hooks.js); standalone/sidecar States are written here.
+    if (this.#state !== State.preload) this.#state.write()
+  }
+}