@vzn/vx 0.0.21 → 0.0.23

package/src/workspace/package-graph.ts

@@ -1,3 +1,4 @@
+import path from 'node:path'
 import type { ProjectMeta } from './workspace.js'
 
 export interface PackageGraph {
@@ -23,7 +24,12 @@ export function buildPackageGraph(
   taskEdges?: ReadonlyMap<string, readonly string[]>,
 ): PackageGraph {
   const byName = new Map<string, ProjectMeta>()
-  for (const p of projects) byName.set(p.name, p)
+  const byDir = new Map<string, ProjectMeta>()
+  for (const p of projects) {
+    byName.set(p.name, p)
+    byDir.set(path.resolve(p.dir), p)
+  }
+  const linked = linkedTarget(byName, byDir)
 
   // Two adjacencies. ORDER (`directDeps`, the `^task` walk) is what the
   // package imports at build time: dependencies, devDependencies,
@@ -42,8 +48,17 @@ export function buildPackageGraph(
   // reads no peers, runs it; an unconditional order edge made `^build`
   // a task cycle, 2026-09-11), so a peer edge that would close a cycle
   // through the order graph is reach only: the consumer above provides
-  // that peer. Peers are tried in (package, peer) name order, so which
-  // edge of a two-peer cycle stays is stable across runs.
+  // that peer.
+  //
+  // Which edge of a MUTUAL two-peer cycle stays is stable across runs,
+  // and the PACKAGE sort below is what makes it so: the first package
+  // in name order keeps its edge, whatever order the projects arrive
+  // in. The per-package peer sort provides none of that — measured
+  // (item 571), both manifest orders give identical graphs in every
+  // arrangement tried, because `reaches(peer, p)` walks edges INTO `p`
+  // and adding an edge OUT of `p` cannot change it. It stays as cheap
+  // insurance against a future rule that does depend on it; it is not
+  // what the stability rests on.
   const directDeps = new Map<string, string[]>()
   const reachDeps = new Map<string, string[]>()
   const order = new Map<string, Set<string>>()
@@ -54,22 +69,41 @@ export function buildPackageGraph(
     for (const name of taskEdges?.get(p.name) ?? []) {
       if (name !== p.name && byName.has(name)) own.add(name)
     }
-    const add = (
-      field: 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies',
-      into: Set<string>,
-    ) => {
-      const obj = p.packageJson[field]
-      if (!obj) return
-      for (const name of Object.keys(obj)) {
-        if (name !== p.name && byName.has(name)) into.add(name)
-      }
+    const optional = bucket(p.packageJson.optionalDependencies)
+    const prod = bucket(p.packageJson.dependencies)
+    const dev = bucket(p.packageJson.devDependencies)
+    const add = (key: string, spec: unknown, installed: boolean, into: Set<string>): void => {
+      if (typeof spec !== 'string') return
+      const target = linked(key, spec.trim(), p.dir, installed)
+      if (target !== undefined && target !== p.name) into.add(target)
     }
-    add('dependencies', own)
-    add('devDependencies', own)
-    add('optionalDependencies', own)
+    // Which entry is installed when a key sits in more than one field,
+    // measured with bun 1.4, npm 10, yarn 1 and pnpm 12 (2026-09-24): bun
+    // and npm take devDependencies, then optionalDependencies, then
+    // dependencies; yarn and pnpm take optionalDependencies, then
+    // dependencies, then devDependencies. vx cannot tell which manager
+    // installed the tree, so either winner linking is an edge: a spare
+    // edge costs order, a missing one a stale hit. A dev or optional
+    // entry wins under one order or the other; a prod entry loses to an
+    // optional one under both.
+    for (const key in dev) add(key, dev[key], true, own)
+    for (const key in optional) add(key, optional[key], true, own)
+    for (const key in prod) if (!Object.hasOwn(optional, key)) add(key, prod[key], true, own)
     order.set(p.name, own)
+    // A peer is not installed by the package that declares it: when an
+    // installed entry names the same key, that entry is what resolves
+    // (turborepo#12640: a registry `buffer@^6` dev dependency beside a
+    // `workspace:*` peer on it installs the registry copy in all four).
+    // Alone, a peer on a sibling resolves to the sibling whatever its
+    // range, since bun and yarn hoist the workspace copy (npm refuses an
+    // unmet one; pnpm 12 fetched it from the registry).
     const peer = new Set<string>()
-    add('peerDependencies', peer)
+    const peerDeps = bucket(p.packageJson.peerDependencies)
+    for (const key in peerDeps) {
+      if (!Object.hasOwn(optional, key) && !Object.hasOwn(prod, key) && !Object.hasOwn(dev, key)) {
+        add(key, peerDeps[key], false, peer)
+      }
+    }
     peers.set(p.name, peer)
   }
   // `to` reaches `from` through the order edges so far ⇒ from → to
@@ -219,3 +253,107 @@ export function buildPackageGraph(
     transitiveDependents: makeAccessor(directDependents),
   }
 }
+
+function bucket(field: unknown): Readonly<Record<string, unknown>> {
+  return typeof field === 'object' && field !== null ? (field as Record<string, unknown>) : {}
+}
+
+// The ranges a manifest carries, in the part of npm's grammar (node-semver)
+// where `Bun.semver.satisfies` answers as npm does: `||`-joined sets, each
+// a hyphen range, one comparator, or two or more `<`/`>` bounds, over
+// versions whose wildcards trail (`1.x`, `1.2.*`). Bun 1.4.2 answers true
+// for text that is no range at all (`latest`, `npm:foo@1`, `github:a/b`,
+// `../x`), ORs bare comparators npm ANDs (`1 2`), and reads `>x` and a
+// leading wildcard (`x.3.1`) its own way; a spec outside this grammar
+// counts as unmet. One corner inside it still differs (item 831): a
+// prerelease at a `<` bound over a partial (`<3.x`, `<3.1`) or at a hyphen
+// range's partial end, beside a lower bound naming that prerelease's own
+// version — `3.0.0-beta` against `>=3.0.0-alpha <3.x` — Bun admits and npm
+// does not. bun installs by the first answer and the others by the second,
+// so neither is right everywhere; the graph takes Bun's. The playground's
+// port (packages/vx-docs, src/playground/shim/semver.ts) is held to Bun
+// over this grammar.
+const W = String.raw`[xX*]`
+const PRE = String.raw`(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?`
+const NUMERIC = String.raw`[vV]?\d+(?:\.${W}(?:\.${W})?|\.\d+(?:\.${W}|\.\d+${PRE})?)?`
+const SINGLE = String.raw`(?:(?:[<>]=?|~>?|\^)\s*${NUMERIC}|=?\s*(?:${NUMERIC}|${W}(?:\.${W}){0,2}))`
+const BOUND = String.raw`[<>]=?\s*${NUMERIC}`
+const SET = String.raw`(?:${NUMERIC}\s+-\s+${NUMERIC}|${BOUND}(?:\s+${BOUND})+|${SINGLE})`
+export const SEMVER_RANGE = new RegExp(String.raw`^(?:${SET}(?:\s*\|\|\s*${SET})*)?$`)
+/** `<name>[@<range>]` after `npm:` or `workspace:`; the name may be scoped. */
+const ALIAS = /^(@[^@/]+\/[^@/]+|[^@/.][^@/]*)(?:@(.*))?$/
+const PATH_PROTOCOLS = ['file:', 'link:', 'portal:'] as const
+const MAY_POINT_ELSEWHERE = /^(?:workspace:|npm:|file:|link:|portal:|\.\.?\/|\/)/
+
+/**
+ * The workspace package a manifest entry resolves to, or undefined when
+ * the package manager installs it from elsewhere. `installed` is false
+ * for a peer, which the hoisted workspace copy under its key provides
+ * whatever the spec. The rule and its measurements are
+ * docs/modules/package-graph.md § Which entries are edges.
+ */
+function linkedTarget(
+  byName: ReadonlyMap<string, ProjectMeta>,
+  byDir: ReadonlyMap<string, ProjectMeta>,
+): (key: string, spec: string, fromDir: string, installed: boolean) => string | undefined {
+  // A monorepo repeats a few ranges and versions thousands of times, and
+  // the grammar test and `Bun.semver` cost about a microsecond a call:
+  // unmemoised they tripled the graph build at 1000 projects × 30 deps.
+  const isRange = new Map<string, boolean>()
+  const range = (spec: string): boolean => {
+    let ok = isRange.get(spec)
+    if (ok === undefined) isRange.set(spec, (ok = SEMVER_RANGE.test(spec)))
+    return ok
+  }
+  const satisfiedBy = new Map<string, Map<string, boolean>>()
+  // A dist-tag (`latest`) is no range, and bun, npm, yarn and pnpm all
+  // installed it from the registry beside a matching workspace package.
+  const satisfies = (p: ProjectMeta, spec: string): boolean => {
+    if (spec === '*' || spec === '') return true
+    const version = p.packageJson.version
+    if (typeof version !== 'string' || !range(spec)) return false
+    let memo = satisfiedBy.get(version)
+    if (memo === undefined) satisfiedBy.set(version, (memo = new Map()))
+    let ok = memo.get(spec)
+    if (ok === undefined) memo.set(spec, (ok = Bun.semver.satisfies(version, spec)))
+    return ok
+  }
+  const named = (name: string, spec: string): string | undefined => {
+    const p = byName.get(name)
+    return p !== undefined && satisfies(p, spec) ? name : undefined
+  }
+  const atPath = (fromDir: string, rel: string): string | undefined =>
+    byDir.get(path.resolve(fromDir, rel))?.name
+  return (key, spec, fromDir, installed) => {
+    if (spec === 'workspace:*') return named(key, '*')
+    // Only a protocol or a path points a key at another package; every
+    // other spec (a range, a tag, a URL) is decided by the key.
+    if (!MAY_POINT_ELSEWHERE.test(spec)) {
+      const local = byName.get(key)
+      if (local === undefined) return undefined
+      // A catalog entry's range lives where the graph does not read
+      // (`pnpm-workspace.yaml`, bun's root `catalog`): it keeps the edge.
+      if (!installed || spec.startsWith('catalog:')) return key
+      return satisfies(local, spec) ? key : undefined
+    }
+    if (spec.startsWith('workspace:')) {
+      const rest = spec.slice('workspace:'.length)
+      if (rest === '^' || rest === '~') return named(key, '*')
+      if (range(rest)) return named(key, rest)
+      const alias = ALIAS.exec(rest)
+      if (alias !== null) return named(alias[1]!, alias[2] ?? '*')
+      return atPath(fromDir, rest)
+    }
+    if (spec.startsWith('npm:')) {
+      // bun links a satisfied alias; npm and yarn fetch it from the
+      // registry. The edge is the spare one, as above.
+      const alias = ALIAS.exec(spec.slice('npm:'.length))
+      return alias === null ? undefined : named(alias[1]!, alias[2] ?? '*')
+    }
+    for (const protocol of PATH_PROTOCOLS) {
+      if (spec.startsWith(protocol)) return atPath(fromDir, spec.slice(protocol.length))
+    }
+    // A bare `./`, `../` or `/` path is a directory to bun, npm and pnpm.
+    return atPath(fromDir, spec)
+  }
+}

package/src/workspace/project-loader.ts

@@ -2,8 +2,10 @@ import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
 import { UserError, xxh3hex } from '../util/index.js'
 import { validateProjectConfig, validateWorkspace } from './config-schema.js'
-import { evaluateConfigFresh } from './config-eval.js'
+import { beginEvalRound, evaluateConfigFresh } from './config-eval.js'
+import { hasEsmExport, unprovidedBareImports } from './config-imports.js'
 import { configEvalKey, configEvalKeyFromClosure, type ConfigEvalStore } from './config-cache.js'
+import { readOnce } from './load-reads.js'
 
 // The validator lives in config-schema.ts; re-exported so a reader that
 // reaches the loader for it (the tests do) keeps working.
@@ -26,6 +28,80 @@ function assertDefaultObject(mod: unknown, kind: string, configPath: string): vo
   }
 }
 
+/**
+ * The source a load already holds, by the specifier it imports it under.
+ * Bun's loader would open and read a project config a second time; the
+ * `vx-config-bytes` plugin hands it this instead, so the evaluation runs
+ * exactly the bytes the eval-cache key and the import gate saw. It is also
+ * the cheaper load: 1,000 configs imported this way took 80–100 ms against
+ * 180 ms read by Bun (measured 2026-09-24).
+ *
+ * Handed over as a string: `onLoad` reads a byte array as Latin-1, and a
+ * `ü` in a description came back as `ü`. So only UTF-8 is served, and
+ * only ESM (`hasEsmExport`): source handed to `onLoad` is always evaluated
+ * as a module, and a CommonJS config's `module.exports` would vanish. Any
+ * other config takes Bun's own path, which reads the file and decides its
+ * format as it always did. The two paths carry different queries because
+ * `onLoad` cannot decline a path it matched.
+ *
+ * The workspace config is never served. Proving it ESM is the parser's
+ * first use in a warm run, ~0.27 ms, and serving the one file saves less
+ * than that: `loadWorkspaceConfig` measured 0.3 ms slower served (40
+ * interleaved runs, 2026-09-24). Bun reads it a second time instead.
+ */
+//
+// Held by the bytes' hash, not the specifier: Bun hands `onLoad` the path
+// it RESOLVED, which is the real path, so a config reached through a
+// symlinked directory (macOS's `/var` → `/private/var`, every temp root
+// there) came back under a key nobody set, and every such load failed.
+// Equal hashes are equal sources, so two loads of the same bytes share an
+// entry; `uses` keeps it until the last of them has imported.
+const heldSources = new Map<string, { source: string; uses: number }>()
+let serving = false
+
+const HELD_QUERY = /\?vx-held=([0-9a-f]+)$/
+
+function serveHeldSources(): void {
+  if (serving) return
+  serving = true
+  Bun.plugin({
+    name: 'vx-config-bytes',
+    setup(build) {
+      build.onLoad({ filter: HELD_QUERY }, (args) => ({
+        contents: heldSources.get(HELD_QUERY.exec(args.path)![1]!)!.source,
+        loader: /\.[cm]?ts\?/.test(args.path) ? 'ts' : 'js',
+      }))
+    },
+  })
+}
+
+function holdSource(hash: string, source: string): void {
+  const held = heldSources.get(hash)
+  if (held === undefined) heldSources.set(hash, { source, uses: 1 })
+  else held.uses++
+}
+
+function releaseSource(hash: string): void {
+  const held = heldSources.get(hash)!
+  if (--held.uses === 0) heldSources.delete(hash)
+}
+
+const utf8 = new TextDecoder('utf-8', { fatal: true })
+
+/** `bytes` as the source `onLoad` may stand in for Bun's read with, or null (see `heldSources`). */
+function servableSource(bytes: Uint8Array, loader: 'ts' | 'js'): string | null {
+  let source: string
+  try {
+    source = utf8.decode(bytes)
+  } catch {
+    return null
+  }
+  return hasEsmExport(source, loader) ? source : null
+}
+
+/** vx's module-cache query, which no user wrote: stripped from anything shown to them. */
+const BUST_QUERY = /\?vx-(?:bust|held)=[^'"\s]*/g
+
 // Bun has native TS / ESM execution — no transpiler dep needed. We fold
 // a short content hash into the import URL as a cache-bust key so that:
 //   same content   → same URL → Bun's module cache hits (fast)
@@ -37,26 +113,59 @@ function assertDefaultObject(mod: unknown, kind: string, configPath: string): vo
 async function loadDefaultExport(
   configPath: string,
   kind: string,
-  fresh = false,
-  bytes?: Uint8Array,
+  bytes: Uint8Array,
 ): Promise<unknown> {
-  bytes ??= await Bun.file(configPath).bytes()
-  // `fresh` opts out of module-cache reuse entirely: `vx lock` and
-  // `vx lock --check` must observe the CURRENT environment, and the
-  // content-hash bust would replay an evaluation made under earlier
-  // env values when the file bytes are unchanged in this process.
-  const bust = fresh ? `${xxh3hex(bytes)}-${Bun.randomUUIDv7()}` : xxh3hex(bytes)
+  refuseUnprovidedImports(bytes, configPath, kind)
+  // No random bust for `vx lock`: a project config reaches this import
+  // only on its FIRST load in the process, so nothing is cached under the
+  // URL yet, and a repeat load (the one that could replay an evaluation
+  // made under earlier env values) re-evaluates in a worker instead
+  // (`loadedConfigs`, item 678).
+  const source =
+    kind === 'Project' ? servableSource(bytes, /\.[cm]?ts$/.test(configPath) ? 'ts' : 'js') : null
+  const hash = xxh3hex(bytes)
+  const specifier = `${configPath}?vx-${source !== null ? 'held' : 'bust'}=${hash}`
+  if (source !== null) {
+    serveHeldSources()
+    holdSource(hash, source)
+  }
   let ns: { default?: unknown }
   try {
-    ns = (await import(`${configPath}?vx-bust=${bust}`)) as { default?: unknown }
+    ns = (await import(specifier)) as { default?: unknown }
   } catch (err) {
+    // A served module's frames name its specifier; the user wrote the path.
+    if (err instanceof Error && err.stack !== undefined) {
+      err.stack = err.stack.replaceAll(specifier, configPath).replace(BUST_QUERY, '')
+    }
     throw configLoadError(err, configPath, kind) ?? err
+  } finally {
+    if (source !== null) releaseSource(hash)
   }
   const mod = ns?.default
   assertDefaultObject(mod, kind, configPath)
   return mod
 }
 
+/**
+ * A bare import nothing above the config provides is refused BEFORE the
+ * evaluation: left to Bun, a workspace with no `node_modules` would have
+ * the package auto-installed from the registry first (config-imports.ts),
+ * and a config must never download. The message keeps the shape Bun's own
+ * refusal has, with the remedy.
+ */
+function refuseUnprovidedImports(bytes: Uint8Array, configPath: string, kind: string): void {
+  const loader = /\.[cm]?ts$/.test(configPath) ? 'ts' : 'js'
+  const missing = unprovidedBareImports(
+    new TextDecoder().decode(bytes),
+    path.dirname(configPath),
+    loader,
+  )
+  if (missing.length === 0) return
+  throw new UserError(
+    `${kind} config ${configPath}: cannot find '${missing[0]}' — no node_modules above the config provides it; install the workspace's dependencies first`,
+  )
+}
+
 /**
  * Where a transpile error was found. Bun's `BuildMessage` carries it as
  * `position`; the config worker forwards the same three fields (see
@@ -85,18 +194,26 @@ interface BuildPosition {
  * fallback.
  */
 export function configLoadError(err: unknown, configPath: string, kind: string): UserError | null {
-  if (!(err instanceof Error)) return null
-  if (err.name === 'ResolveMessage') {
-    const spec = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(err.message)?.[1]
-    const what =
-      spec === undefined ? err.message.replace(/\?vx-bust=\S+/g, '') : `cannot find '${spec}'`
+  // Matched on SHAPE, not `instanceof Error`. Bun's `BuildMessage` is not an
+  // Error subclass on every build — on 1.3.11 its prototype chain is
+  // `BuildMessage → Object` — and an `instanceof` guard there hands the user
+  // a raw transpile object for a missing brace in their own config, which is
+  // the defect `isFsRefusal` exists to prevent one layer down. The two names
+  // below are Bun's own and nothing else answers to them, so this is
+  // narrower than it looks: every other throw still passes through (2026-09-20).
+  if (err === null || typeof err !== 'object') return null
+  const { name, message } = err as { name?: unknown; message?: unknown }
+  if (typeof message !== 'string') return null
+  if (name === 'ResolveMessage') {
+    const spec = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(message)?.[1]
+    const what = spec === undefined ? message.replace(BUST_QUERY, '') : `cannot find '${spec}'`
     const hint =
       spec?.startsWith('@vzn/vx') === true
         ? `; install it in the workspace: bun add -d @vzn/vx`
         : ''
     return new UserError(`${kind} config ${configPath}: ${what}${hint}`)
   }
-  if (err.name === 'BuildMessage') {
+  if (name === 'BuildMessage') {
     const pos = (err as { position?: BuildPosition | null }).position ?? {}
     const file = typeof pos.file === 'string' && pos.file.length > 0 ? pos.file : configPath
     const at =
@@ -104,13 +221,13 @@ export function configLoadError(err: unknown, configPath: string, kind: string):
         ? `:${pos.line}${typeof pos.column === 'number' ? `:${pos.column}` : ''}`
         : ''
     const where = file === configPath ? `${configPath}${at}` : `${configPath} (in ${file}${at})`
-    return new UserError(`${kind} config ${where}: ${err.message}`)
+    return new UserError(`${kind} config ${where}: ${message}`)
   }
   return null
 }
 
 export interface LoadProjectConfigOptions {
-  /** Observe the CURRENT environment: no module-cache reuse, no eval cache. */
+  /** Observe the CURRENT environment: no eval cache, even when `evalCache` is passed. */
   fresh?: boolean
   /**
    * Serve a provably-pure config from its cached evaluation (see
@@ -132,6 +249,11 @@ export async function loadProjectConfigs(
   const evalCache = opts?.fresh === true ? undefined : opts?.evalCache
   const store = evalCache?.store
   const hashFile = store?.hashFile?.bind(store)
+  const hashBytes = store?.hashBytes?.bind(store)
+  // The slow path keys from the bytes it already holds; `hashFile` there
+  // memoised every closure file one autocommit upsert at a time (item 615).
+  const slowKeyHash =
+    hashBytes !== undefined ? { hashBytes } : hashFile !== undefined ? { hashFile } : {}
   // The warm fast path: a config whose ordered closure the store remembers
   // is keyed from per-file identities (a stat each, no read, no scan); the
   // slow path below reads, gates and scans, and indexes the closure for
@@ -175,7 +297,7 @@ export async function loadProjectConfigs(
               configPath,
               bytes,
               workspaceFingerprint: evalCache.workspaceFingerprint,
-              ...(hashFile !== undefined ? { hashFile } : {}),
+              ...slowKeyHash,
             })
       return {
         configPath,
@@ -201,58 +323,89 @@ export async function loadProjectConfigs(
     }
   }
   const out: ProjectConfig[] = []
-  for (const entry of prepared) {
-    const { configPath, cacheKey } = entry
-    const hit = cacheKey === null ? undefined : hits.get(cacheKey)
-    // Stored AFTER validation, so a hit needs none; the key covers every
-    // byte the evaluation could have read.
-    if (hit !== undefined) {
-      out.push(JSON.parse(hit) as ProjectConfig)
-      continue
-    }
-    // A fast key that missed: the closure is stale or the file changed.
-    // Take the slow path for this one config, which re-indexes it.
-    let bytes = entry.bytes
-    let closure = entry.closure
-    let key = cacheKey
-    if (entry.indexed) {
-      bytes = await Bun.file(configPath).bytes()
-      const keyed = await configEvalKey({
-        configPath,
-        bytes,
-        workspaceFingerprint: evalCache!.workspaceFingerprint,
-        ...(hashFile !== undefined ? { hashFile } : {}),
-      })
-      key = keyed?.key ?? null
-      closure = keyed !== null && keyed.indexable ? keyed.closure : undefined
-      const slowHit = key === null ? null : (store!.getConfigEval(key) ?? null)
-      if (slowHit !== null) {
-        out.push(JSON.parse(slowHit) as ProjectConfig)
-        if (closure !== undefined) store!.putConfigClosure?.(configPath, closure)
+  // What the round learned, written ONCE at the end: one transaction per
+  // table where each evaluation was its own (1,000 configs cold: 100 ms of
+  // autocommit inserts against 5, item 615). Written in `finally`, so a
+  // config that fails validation costs the next attempt only its own
+  // evaluation.
+  const evals: Array<readonly [string, string]> = []
+  const learnedClosures: Array<readonly [string, readonly string[]]> = []
+  // One worker for every repeat load in this round, however many there are.
+  const endRound = beginEvalRound()
+  try {
+    for (const entry of prepared) {
+      const { configPath, cacheKey } = entry
+      const hit = cacheKey === null ? undefined : hits.get(cacheKey)
+      // Stored AFTER validation, so a hit needs none; the key covers every
+      // byte the evaluation could have read.
+      if (hit !== undefined) {
+        out.push(JSON.parse(hit) as ProjectConfig)
         continue
       }
-    }
-    // A REPEAT load in this process re-evaluates in a worker, because the
-    // bust above cannot reach the config's import closure — see
-    // config-eval.ts. A FIRST load keeps the in-process import, so the
-    // single `vx run` hot path never pays for a worker.
-    const repeat = loadedConfigs.has(configPath)
-    loadedConfigs.add(configPath)
-    const mod = repeat
-      ? await evaluateConfigFresh(configPath).catch((err: unknown) => {
-          throw configLoadError(err, configPath, 'Project') ?? err
+      // A fast key that missed: the closure is stale or the file changed.
+      // Take the slow path for this one config, which re-indexes it.
+      let bytes = entry.bytes
+      let closure = entry.closure
+      let key = cacheKey
+      if (entry.indexed) {
+        bytes = await Bun.file(configPath).bytes()
+        const keyed = await configEvalKey({
+          configPath,
+          bytes,
+          workspaceFingerprint: evalCache!.workspaceFingerprint,
+          ...slowKeyHash,
         })
-      : await loadDefaultExport(configPath, 'Project', opts?.fresh === true, bytes!)
-    assertDefaultObject(mod, 'Project', configPath)
-    // Validation runs HERE, on whichever object we ended up with, so a
-    // malformed config reports the identical UserError whether it was
-    // evaluated in-process or in a worker.
-    validateProjectConfig(mod as ProjectConfig, configPath)
-    if (key !== null) {
-      evalCache!.store.putConfigEval(key, JSON.stringify(mod))
-      if (closure !== undefined) evalCache!.store.putConfigClosure?.(configPath, closure)
+        key = keyed?.key ?? null
+        closure = keyed !== null && keyed.indexable ? keyed.closure : undefined
+        const slowHit = key === null ? null : (store!.getConfigEval(key) ?? null)
+        if (slowHit !== null) {
+          out.push(JSON.parse(slowHit) as ProjectConfig)
+          if (closure !== undefined) learnedClosures.push([configPath, closure])
+          continue
+        }
+      }
+      // A REPEAT load in this process re-evaluates in a worker, because the
+      // bust above cannot reach the config's import closure — see
+      // config-eval.ts. A FIRST load keeps the in-process import, so the
+      // single `vx run` hot path never pays for a worker.
+      const repeat = loadedConfigs.has(configPath)
+      loadedConfigs.add(configPath)
+      if (repeat) refuseUnprovidedImports(bytes!, configPath, 'Project')
+      const mod = repeat
+        ? await evaluateConfigFresh(configPath).catch((err: unknown) => {
+            throw configLoadError(err, configPath, 'Project') ?? err
+          })
+        : await loadDefaultExport(configPath, 'Project', bytes!)
+      assertDefaultObject(mod, 'Project', configPath)
+      // Validation runs HERE, on whichever object we ended up with, so a
+      // malformed config reports the identical UserError whether it was
+      // evaluated in-process or in a worker.
+      validateProjectConfig(mod as ProjectConfig, configPath)
+      const json = JSON.stringify(mod)
+      if (key !== null) {
+        evals.push([key, json])
+        if (closure !== undefined) learnedClosures.push([configPath, closure])
+      }
+      // A tree of its own, as a hit and the lock hand out. The module object
+      // shares what the config shares: one preset's task in two configs, one
+      // `exec` in two tasks. A `project` hook that edits in place then edited
+      // them all, so a cold run ran `echo P +plug +plug` where the warm run
+      // and `--frozen` ran `echo P +plug`, under another key (item 967). A
+      // config is JSON data (config-schema.ts), so the copy loses nothing.
+      out.push(JSON.parse(json) as ProjectConfig)
+    }
+  } finally {
+    endRound()
+    if (store !== undefined) {
+      if (evals.length > 0) {
+        if (store.putConfigEvals !== undefined) store.putConfigEvals(evals)
+        else for (const [k, json] of evals) store.putConfigEval(k, json)
+      }
+      if (learnedClosures.length > 0 && store.putConfigClosure !== undefined) {
+        if (store.putConfigClosures !== undefined) store.putConfigClosures(learnedClosures)
+        else for (const [p, files] of learnedClosures) store.putConfigClosure(p, files)
+      }
     }
-    out.push(mod as ProjectConfig)
   }
   return out
 }
@@ -272,15 +425,12 @@ export async function loadProjectConfig(
  * a `UserError` on malformed input.
  */
 export async function loadWorkspaceConfig(root: string): Promise<WorkspaceConfig | null> {
-  let configPath: string | null = null
-  for (const candidate of WORKSPACE_CONFIG_FILENAMES.map((f) => path.join(root, f))) {
-    if (await Bun.file(candidate).exists()) {
-      configPath = candidate
-      break
-    }
+  for (const configPath of WORKSPACE_CONFIG_FILENAMES.map((f) => path.join(root, f))) {
+    const bytes = await readOnce(undefined, configPath)
+    if (bytes === null) continue
+    const mod = (await loadDefaultExport(configPath, 'Workspace', bytes)) as WorkspaceConfig
+    validateWorkspace(mod, configPath)
+    return mod
   }
-  if (!configPath) return null
-  const mod = (await loadDefaultExport(configPath, 'Workspace')) as WorkspaceConfig
-  validateWorkspace(mod, configPath)
-  return mod
+  return null
 }