@exodus/stasis-plugins 1.0.0-beta.15 → 1.0.0-beta.17

package/src/plugins.js

@@ -1,49 +1,54 @@
-// Plugin <-> preload coordination (resolvePluginState): decides which State a bundler plugin
-// drives, given its options and the ambient preload.
-
 import assert from 'node:assert/strict'
+import { isUtf8 } from 'node:buffer'
 
-import { DEFAULT_LOCK, assertOptionsMatchConfig, validatePluginOptions } from '@exodus/stasis-core/config'
+import { DEFAULT_LOCK, assertKnownKeys, assertOption } from '@exodus/stasis-core/config'
 import { ensureStateForLoader, isLoaderInstalled } from '@exodus/stasis-core/hooks'
 import { State } from '@exodus/stasis-core/state'
-import { extSetsEqual, parseResourcesOption } from '@exodus/stasis-core/util'
-
-// 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 sharing the preload's lockfile data.
-//  7. lock='none' AND bundle='none' with no preload is a no-op (env-controlled-off framework plugins).
+import { classifyExtension, extSetsEqual, parseResourcesOption } from '@exodus/stasis-core/util'
+
+// The Config options a plugin takes; not `lockFile`, as the lockfile is always the preload's.
+const PLUGIN_OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'resourcesBundleFile', 'debug', 'childProcess', 'packageJSON', 'resources']
+
+// Validated as Config validates them, without constructing one (which has side effects).
+export function validatePluginOptions(label, options) {
+  assertKnownKeys(Object.keys(options), PLUGIN_OPTION_KEYS, label)
+  for (const key of PLUGIN_OPTION_KEYS) {
+    if (options[key] === undefined) continue
+    if (key === 'resources') parseResourcesOption(label, options.resources)
+    else assertOption(key, options[key])
+  }
+}
+
+// The active Config is authoritative; `resources`, a Set, is coordinated in resolvePluginState instead.
+export function assertOptionsMatchConfig(config, options) {
+  try {
+    for (const key of PLUGIN_OPTION_KEYS) {
+      if (key !== 'resources' && options[key] !== undefined) assert.equal(config[key === 'bundle' ? 'bundleMode' : key], options[key])
+    }
+  } catch (cause) {
+    throw new Error(`Plugin options conflict with active stasis state: ${cause.message}`, { cause })
+  }
+}
+
+// The State a bundler plugin runs against, given its options and the ambient preload: { state: null, isNoop: true }
+// (inert: register no hooks), else { state, isNoop: false }. The lockfile is always the preload's; only the bundle
+// may split off, to a sidecar State at its own bundleFile.
 export function resolvePluginState(label, options, cwd) {
   validatePluginOptions(label, options)
   const { lock, bundle, bundleFile, resourcesBundleFile, 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.
+  // The loader is installed but its lazy init hasn't fired (webpack builds plugins before user code). Never 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.
+    // `stasis run` always exports EXODUS_STASIS_LOCK, whichever 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) {
+    // Inert in a plain build, as where both are 'none' (a framework plugin switched off by env).
+    if ((!underStasisRun && lock === undefined && bundle === undefined) || (lock === 'none' && bundle === 'none')) {
       return { state: null, isNoop: true }
     }
-
-    if (lock === 'none' && bundle === 'none') return { state: null, isNoop: true } // Rule 7
-    // 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.
+    // A partial opt-out would otherwise meet a misleading throw; an active bundle with lock='none' is legitimate.
     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' ` +
@@ -51,14 +56,10 @@ export function resolvePluginState(label, options, cwd) {
         `bundle=${bundle === undefined ? 'default' : `'${bundle}'`})`
       )
     }
-    // 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.
+    // A writing or verifying lock would miss the bundler's own deps without a preload, but under `stasis run`.
     const effectiveLock = lock ?? DEFAULT_LOCK
     if (!underStasisRun && effectiveLock !== 'none' && effectiveLock !== 'ignore') {
-      const phrasing = lock === undefined
-        ? `the default lockfile mode ('${DEFAULT_LOCK}')`
-        : `lockfile mode '${lock}'`
+      const phrasing = lock === undefined ? `the default lockfile mode ('${DEFAULT_LOCK}')` : `lockfile mode '${lock}'`
       throw new Error(
         `${label}: ${phrasing} requires a stasis preload; ` +
         `pass lock='none' or lock='ignore' to opt out, or run under the stasis loader`
@@ -67,18 +68,15 @@ export function resolvePluginState(label, options, cwd) {
     return { state: new State(cwd, options), isNoop: false }
   }
 
-  // Preload active: the lockfile is necessarily the ambient's. Enforce field coordination, then reuse or sidecar.
+  // These must agree with the preload, which a reuse adopts and a sidecar copies.
   const pc = ambient.config
-  // lock/scope/debug/childProcess/packageJSON must agree with the preload (reuse adopts it, sidecar
-  // copies it). The string modes are quoted, the boolean toggles not (validatePluginOptions typed them).
   const shown = (value) => (typeof value === 'string' ? `'${value}'` : value)
   for (const key of ['lock', 'scope', 'debug', 'childProcess', 'packageJSON']) {
     if (options[key] !== undefined && options[key] !== pc[key]) {
       throw new Error(`${label}: ${key}=${shown(options[key])} conflicts with active preload ${key}=${shown(pc[key])}`)
     }
   }
-  // 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.
+  // resources is process-wide: compared as parsed sets, so that no plugin silently widens the asset set.
   if (resources !== undefined) {
     const parsed = parseResourcesOption(label, resources)
     if (!extSetsEqual(parsed, pc.resources)) {
@@ -88,74 +86,70 @@ export function resolvePluginState(label, options, cwd) {
     }
   }
 
-  // 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.
+  // So the preload's `reason` map can tell files merely fs-read during the build from the run's own dependencies.
   ambient.markPluginAttached()
 
-  // A State of its own bundle (`mode`, at bundleFile) beside the preload, whose lockfile it shares
-  // and whose other settings it carries over (sidecars skip stasis.config.json discovery).
-  const sidecar = (mode) => ({
-    state: new State(cwd, {
-      parent: ambient,
-      scope: pc.scope,
-      lock: pc.lock,
-      bundle: mode,
-      bundleFile,
-      resourcesBundleFile,
-      debug: pc.debug,
-      childProcess: pc.childProcess,
-      packageJSON: pc.packageJSON,
-      resources: [...pc.resources],
-      brotliQuality: pc.brotliQuality,
-    }),
-    isNoop: false,
-  })
+  // Sidecars skip stasis.config.json discovery, so carry the preload's settings over.
+  const sidecar = (mode) => {
+    const inherited = Object.fromEntries(['scope', 'lock', 'debug', 'childProcess', 'packageJSON', 'brotliQuality'].map((key) => [key, pc[key]]))
+    const state = new State(cwd, { parent: ambient, ...inherited, bundle: mode, bundleFile, resourcesBundleFile, resources: [...pc.resources] })
+    return { state, isNoop: false }
+  }
 
   if (pc.bundle) {
-    // Preload has bundle on -- plugin can't disable (pc.bundleMode is neither 'none' nor 'ignore'), must match mode.
     if (bundle !== undefined && bundle !== pc.bundleMode) {
-      throw new Error(
-        `${label}: bundle='${bundle}' conflicts with active preload bundle='${pc.bundleMode}'`
-      )
-    }
-    if (bundleFile === undefined || bundleFile === pc.bundleFile) {
-      // Rule 5: same bundleFile (or unspecified) reuses the preload.
-      assertOptionsMatchConfig(pc, options)
-      return { state: ambient, isNoop: false }
+      throw new Error(`${label}: bundle='${bundle}' conflicts with active preload bundle='${pc.bundleMode}'`)
     }
-    // Rule 6: different path -- sidecar inherits preload's modes, overrides bundleFile.
-    return sidecar(pc.bundleMode)
+    if (bundleFile !== undefined && bundleFile !== pc.bundleFile) return sidecar(pc.bundleMode)
+    assertOptionsMatchConfig(pc, options)
+    return { state: ambient, isNoop: false }
   }
 
-  // Preload exists but has no bundle.
   if (bundle === undefined || bundle === 'none' || bundle === 'ignore') {
-    // 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.
+    // 'ignore' and the preload's 'none' both mean no bundle, so the field leaves the cross-check; the assert pins
+    // that to today's no-bundle modes, so that a future one 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
     assertOptionsMatchConfig(pc, rest)
     return { state: ambient, isNoop: false }
   }
-  // Plugin wants its own bundle alongside preload's lockfile -- sidecar.
   if (!bundleFile) {
-    throw new Error(
-      `${label}: bundle='${bundle}' alongside a preload without bundle requires an explicit bundleFile`
-    )
+    throw new Error(`${label}: bundle='${bundle}' alongside a preload without bundle requires an explicit bundleFile`)
   }
   return sidecar(bundle)
 }
 
-// What a plugin (`label`) says of a file it is given (`what`, as it names it) whose extension it
-// neither bundles as code nor is allowed as a resource.
+// A State the caller owns (`stasis build`'s), else resolvePluginState's; a foreign copy's State fails the instanceof.
+export const ownOrResolvedState = (label, options) =>
+  (options instanceof State ? options : resolvePluginState(label, options, process.cwd()).state)
+
+// Dedupe is by path, so a rebuild with new bytes would emit them while the bundle and lockfile keep the old ones.
+export const rebuildRefused = (label) =>
+  `${label}: watch/rebuild is not supported for capture -- run a one-shot build (rebuilds would silently attest stale content)`
+
 export const unsupportedExtension = (label, what) =>
   `${label}: unsupported extension for ${what} -- add its extension or filename to the plugin's resources option or stop importing it`
 
-// `state.getImport(parentURL, specifier, options)`, or undefined where the bundle attests no such edge:
-// at a successful capture that's an EXTERNAL (never recorded as an edge), the bundler's to resolve as
-// without us. File BYTES still fail closed where the plugin loads them; any other error is a real
-// fault, thrown.
+// A file's kind (code|resource), or a throw naming it as `what` where it's neither.
+export function classifyOrThrow(label, path, resources, what = `'${path}'`) {
+  const kind = classifyExtension(path, resources)
+  if (kind === 'unknown') throw new Error(unsupportedExtension(label, what))
+  return kind
+}
+
+// Refuse non-UTF-8 code rather than silently encode it as a resource.
+export function assertCodeUtf8(label, path, source) {
+  assert.ok(isUtf8(source), `${label}: code-classified file has non-UTF-8 bytes: ${path}`)
+}
+
+// Only the `type` import attribute persists to the lockfile.
+export function assertPersistableAttributes(attrs) {
+  for (const k of Object.keys(attrs)) assert.equal(k, 'type', `unsupported import attribute: ${k}`)
+}
+
+// `state.getImport(...)`, or undefined where the bundle attests no such edge: an EXTERNAL at capture, which the
+// bundler resolves as without us (file BYTES still fail closed where the plugin loads them).
 export function attestedImport(state, parentURL, specifier, options) {
   try {
     return state.getImport(parentURL, specifier, options)

package/src/rollup.js

@@ -1,65 +1,50 @@
 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 { attestedImport, resolvePluginState, unsupportedExtension } from './plugins.js'
+import { assertCodeUtf8, assertPersistableAttributes, attestedImport, classifyOrThrow, ownOrResolvedState, rebuildRefused } 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 { inScope, realReadFile } from '@exodus/stasis-core/state-util'
 import { classifyExtension, isPathWithin } 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).
+// An on-disk file by its absolute path, not a sibling plugin's virtual module (\0-prefixed or relative) or no importer.
+const isDiskId = (id) => Boolean(id) && isAbsolute(id) && !id.startsWith('\0')
+
+// Rollup chains resolveId/load hooks first-non-null-wins, so this plugin goes FIRST in `plugins`: listed later, a
+// sibling resolver answers before stasis sees the edge (file BYTES still fail closed at the load hook).
 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.
+    // Transforms run as ordinary rollup plugins after this one: refuse a port's esbuild-style bag, not 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
+    const state = ownOrResolvedState('StasisRollup', options)
     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`
+    if (!state) return // inert: 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.
+    // Rollup binds `this` to its PluginContext, so the instance arrives via the closure.
     const plugin = this
-    this.resolveId = async function (source, importer, opts) {
+    this.resolveId = function (source, importer, opts) {
       return plugin.#resolveId(this, source, importer, opts)
     }
-    this.load = async function (id) {
+    this.load = 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.
+    // A warm `cache:` object reuses modules and resolutions WITHOUT calling resolveId/load, so they'd go unattested
+    // at capture and unverified at load. Rollup still builds a fresh cache for this run.
     this.options = (inputOptions) => {
       if (typeof inputOptions.cache !== 'object' || inputOptions.cache === null) return null
       console.warn(
@@ -71,34 +56,18 @@ export class StasisRollup {
     }
 
     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.
+      // Watch rebuilds, and a second rollup() call reusing this instance, re-fire buildStart.
       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)'
-        )
+        if (plugin.#captureBuildCount > 1) throw new Error(rebuildRefused('StasisRollup'))
       }
-
-      // 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.
+  // Rollup asset plugins read their files from disk in their own load hook, with no seam for attested bytes.
   #refuseResourceLoad(path) {
     throw new Error(
       `StasisRollup: bundle=load can't serve resource '${path}' -- rollup asset plugins read ` +
@@ -107,22 +76,8 @@ export class StasisRollup {
     )
   }
 
-  // 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.
+  // A '?'/'#'-suffixed variant of an on-disk path ('./icon.svg?url') feeds the file's bytes to the build under a key
+  // that can't be persisted, so skipping it would leave a build input unattested. A wholly virtual id is skippable.
   #refuseSuffixedOnDisk(id) {
     const stripped = id.split(/[?#]/u, 1)[0]
     if (stripped !== id && existsSync(stripped)) {
@@ -134,89 +89,53 @@ export class StasisRollup {
     }
   }
 
-  // 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(unsupportedExtension('StasisRollup', `'${id}'`))
-    }
-    return kind
-  }
-
   #inRoot(path) {
     return isPathWithin(this.#state.root, path)
   }
 
   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.
+    // Left to the user's external config. SECURITY: never consult getImport for a builtin, so a tampered bundle
+    // can't redirect `fs`.
     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.
+    // Load mode resolves through the bundle's import map: the file may not be on disk.
     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.
+        // Rollup defaults isEntry to !importer, so this covers bare sibling probes too: the load hook asserts entries
+        // from the graph instead. Anchored as rollup's resolver does, else to cwd as the run loader is.
         if (source.startsWith('file:')) return { id: fileURLToPath(source) }
-        const base = importer && isAbsolute(importer) && !importer.startsWith('\0')
-          ? dirname(importer)
-          : process.cwd()
+        const base = isDiskId(importer) ? 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: ...)`.
-      // No attested edge: rollup's. File BYTES still fail closed at the load hook.
-      const attested = attestedImport(this.#state, parentURL, source, { importAttributes: attrs })
+      if (!isDiskId(importer) || !this.#inRoot(importer)) return null
+      assertPersistableAttributes(attrs)
+      const attested = attestedImport(this.#state, pathToFileURL(importer).toString(), source, { importAttributes: attrs })
       if (attested === undefined) return null
       const { url, format } = attested
       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) && inScope(this.#state, 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.
+      // An out-of-scope resource comes from disk through the user's asset plugin, as at capture.
+      if (Bundle.isResourceFormat(format) && inScope(this.#state, url)) this.#refuseResourceLoad(path)
+      // KNOWN GAP: a sibling's resolution metadata (moduleSideEffects, syntheticNamedExports, meta) isn't in the
+      // bundle, so tree-shaking may differ from the capture build's.
       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.
+    // Capture: the remaining resolveId hooks and rollup's own algorithm, passed through with the edge recorded.
     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)
+    if (!isDiskId(id)) return resolution
+    if (!existsSync(id)) {
+      this.#refuseSuffixedOnDisk(id)
+      return resolution
+    }
+    classifyOrThrow('StasisRollup', id, this.#resources)
 
-    // 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)
+    // Code and resource targets alike, but never for an entry, flagged from the graph in buildEnd (opts.isEntry is
+    // a sibling's probe too), nor an out-of-root importer, which load mode defers too.
+    if (!isEntry && isDiskId(importer) && this.#inRoot(importer)) {
+      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}`
@@ -228,30 +147,21 @@ export class StasisRollup {
   }
 
   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.
+    // getFile verifies the hash and throws on a file the bundle doesn't carry: no disk fallback. Ids other plugins
+    // resolved land here too.
     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
+      if (!isDiskId(id) || !this.#inRoot(id)) return null
       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.
+      // The graph's isEntry: a sibling's resolve() probe carries isEntry too but never loads.
       if (this.#state.config.full && ctx.getModuleInfo(id)?.isEntry) this.#state.assertEntry(url)
       if (!inScope(this.#state, 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
+    // A sibling resolver may have minted ids our resolveId never saw. The read is the existence check.
+    if (!isDiskId(id)) return null
     let source
     try {
       source = await realReadFile(id)
@@ -260,55 +170,34 @@ export class StasisRollup {
       this.#refuseSuffixedOnDisk(id)
       return null
     }
-    const kind = this.#classifyOrThrow(id)
+    const resource = classifyOrThrow('StasisRollup', id, this.#resources) === 'resource'
     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 (!resource) assertCodeUtf8('StasisRollup', id, source)
     if (!this.#seen.has(id)) {
       this.#seen.add(id)
-      this.#state.addFile(url, { source, reason: 'rollup' })
+      this.#state.addFile(pathToFileURL(id).toString(), { source, resource, 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')
+    // A resource is the user's asset plugin's to load; code is served as recorded (transform hooks still run after).
+    return resource ? null : 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().
+  // Flags the graph's real entries (resolveId's opts.isEntry would take a sibling's bare probe for one), then writes
+  // a standalone or sidecar State on a clean build. buildEnd, not closeBundle, which only bundle.close() fires.
   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
+      if (!this.#seen.has(id)) return false
       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.
+    // addFile re-verifies the bytes, and refuses a RESOURCE entry, as StasisEsbuild does.
     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()
   }
 }