@vzn/vx 0.0.641 → 0.0.643

package/src/cache/inputs.ts

@@ -27,13 +27,13 @@ import {
   isInstalledPath,
   isLiteralPattern,
   normalizeGlob,
-  namesNodeModules,
-  OUTPUT_NEVER,
   outputMatcher,
+  outputNever,
   realpathOf,
   relPosix,
   shellArgv,
   slashBraceExpansions,
+  braceAlternatives,
   splitNegations,
   staticPrefix,
   stripTrailingSlash,
@@ -66,6 +66,11 @@ export {
 // would. (Literal pattern, not the workspace `LOCKFILE_NAME` constant:
 // cache is a leaf module and must not import from workspace.)
 //
+// Relative to the project, so only where vx writes them: its root's `.vx`
+// and the `vx.lock.json` beside its config. Matched at any depth, a
+// project's own `src/.vx/tmp/*` or `src/sub/vx.lock.json` keyed nothing,
+// and an edit to one was a hit (2026-10-17).
+//
 // `node_modules` is not here: the enumeration drops an untracked file
 // under one (`isInstalledPath`), and a tracked one is a source.
 const ALWAYS_IGNORE = [
@@ -80,21 +85,27 @@ const ALWAYS_IGNORE = [
   // member of this list is load-bearing and has a row that fails without
   // it. Kept: the day an enumeration stops going through git, this is
   // what keeps a repository's object store out of a cache key.
-  '**/.git/**',
+  '.git/**',
   // vx's machine-local state; the workspace config beside it is a source.
-  '**/.vx/cache/**',
-  '**/.vx/projects.lock.json',
+  '.vx/cache/**',
+  '.vx/projects.lock.json',
   // `vx lock`'s review copy of a project's resolved config: the config is
   // keyed already, and a re-lock must not move every `**` reader's key.
-  '**/vx.lock.json',
+  'vx.lock.json',
   // What `vx lock` and `vx init` write beside the lock: a re-lock or init
   // must not select every `**` reader under --affected.
-  '**/.vx/.gitattributes',
-  '**/.vx/.gitignore',
+  '.vx/.gitattributes',
+  '.vx/.gitignore',
   // Where restores stage (archive.ts): vx's own, never an input.
-  '**/.vx/tmp/**',
+  '.vx/tmp/**',
 ]
 
+/**
+ * `ALWAYS_IGNORE` relative to the workspace root, for `inputs.workspaceFiles`:
+ * those globs cross into other projects, and each one's `vx.lock.json` is vx's.
+ */
+const WORKSPACE_ALWAYS_IGNORE = [...ALWAYS_IGNORE, '**/vx.lock.json']
+
 const DEFAULT_FILE_GLOBS: readonly string[] = ['**/*']
 
 export interface ResolvedInputs {
@@ -158,6 +169,8 @@ export interface ResolveInputsArgs {
   workspaceFilesCache?: WorkspaceFilesCache
   /** Per-run memo for `inputs.files`; see `ProjectFilesCache`. */
   projectFilesCache?: ProjectFilesCache
+  /** Resolve no files: the caller folds them from a `filesToken` memo. */
+  skipFiles?: boolean
 }
 
 export type WorkspaceFilesCache = Map<
@@ -184,23 +197,67 @@ export type ProjectFilesCache = Map<
   { snapshot: readonly string[]; result: readonly string[] }
 >
 
+/**
+ * What a task's input files fold to is a function of this token when it is
+ * one of the git records alone: the project's partition holds only files
+ * the enumeration trusted an index OID for (`GitFilesCache.filesDigest`),
+ * and the declaration reaches no gitignored path and no workspace file.
+ * The token is the digest, the workspace root (the fold folds paths
+ * relative to it) and everything `resolveFiles` keys its memo on.
+ * Undefined when only resolving the files can say.
+ */
+export function filesToken(args: ResolveInputsArgs): string | undefined {
+  if ((args.inputs?.workspaceFiles?.length ?? 0) > 0) return undefined
+  const plan = filesPlan(args.inputs?.files, args.ownOutputs)
+  const cache = args.gitFilesCache
+  if (plan === null || cache === undefined) return undefined
+  const snapshot = cache.snapshotFor(args.projectDir, plan.positiveGlobs)
+  if (snapshot === undefined) return undefined
+  const digest = cache.filesDigest(args.projectDir, snapshot)
+  if (
+    digest === undefined ||
+    ignoredReach(plan, snapshot, { dir: args.projectDir, cache }).length > 0
+  )
+    return undefined
+  return `${args.workspaceRoot}\0${filesMemoKey(args.projectDir, plan, args.ownOutputs, args.ownWorkspaceOutputs ?? [], args.nestedProjectDirs)}\0${digest}`
+}
+
+/** Everything below the git snapshot that decides `resolveFiles`' result. */
+function filesMemoKey(
+  projectDir: string,
+  plan: FilesPlan,
+  ownOutputs: readonly string[],
+  ownWorkspaceOutputs: readonly string[],
+  nestedProjectDirs: readonly string[],
+): string {
+  return `${projectDir}\0${plan.positive.join('\u0001')}\0${plan.negative.join('\u0001')}\0${ownOutputs.join('\u0001')}\0${ownWorkspaceOutputs.join('\u0001')}\0${nestedProjectDirs.join('\u0001')}`
+}
+
 export async function resolveInputs(args: ResolveInputsArgs): Promise<ResolvedInputs> {
-  const projectRel = path.relative(args.workspaceRoot, args.projectDir).split(path.sep).join('/')
-  const { files: projectFiles, listing } = await resolveFiles({
-    projectDir: args.projectDir,
-    workspaceRoot: args.workspaceRoot,
-    files: args.inputs?.files,
-    ownOutputs: args.ownOutputs,
-    ownWorkspaceOutputs: args.ownWorkspaceOutputs ?? [],
-    projectRel,
-    nestedProjectDirs: args.nestedProjectDirs,
-    ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
-    ...(args.projectFilesCache !== undefined ? { projectFilesCache: args.projectFilesCache } : {}),
-  })
+  const projectRel =
+    args.skipFiles === true
+      ? ''
+      : path.relative(args.workspaceRoot, args.projectDir).split(path.sep).join('/')
+  const { files: projectFiles, listing } =
+    args.skipFiles === true
+      ? { files: [], listing: undefined }
+      : await resolveFiles({
+          projectDir: args.projectDir,
+          workspaceRoot: args.workspaceRoot,
+          files: args.inputs?.files,
+          ownOutputs: args.ownOutputs,
+          ownWorkspaceOutputs: args.ownWorkspaceOutputs ?? [],
+          projectRel,
+          nestedProjectDirs: args.nestedProjectDirs,
+          ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
+          ...(args.projectFilesCache !== undefined
+            ? { projectFilesCache: args.projectFilesCache }
+            : {}),
+        })
   let files = projectFiles
   const listings = listing === undefined ? [] : [listing]
   const wsDecl = args.inputs?.workspaceFiles
-  if (wsDecl !== undefined && wsDecl.length > 0) {
+  if (wsDecl !== undefined && wsDecl.length > 0 && args.skipFiles !== true) {
     const ws = resolveWorkspaceFiles({
       workspaceRoot: args.workspaceRoot,
       workspaceFiles: wsDecl,
@@ -274,7 +331,6 @@ function resolveWorkspaceFiles(args: {
 }): { files: Promise<string[]>; listing: InputListing } | undefined {
   const positive: string[] = []
   const negative: string[] = []
-  refuseOneAlternativeBrace(args.workspaceFiles, 'workspaceFiles')
   for (const entry of args.workspaceFiles) {
     if (entry.startsWith('!')) negative.push(entry.slice(1))
     else positive.push(entry)
@@ -308,7 +364,7 @@ function resolveWorkspaceFiles(args: {
   let isExcluded: ((rel: string) => boolean) | undefined
   let isPositive: ((rel: string) => boolean) | undefined
   const excludedByDeclaration = (rel: string): boolean =>
-    (isExcluded ??= anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)]))(rel)
+    (isExcluded ??= anyTaskGlob([...WORKSPACE_ALWAYS_IGNORE, ...asTrees(negative)]))(rel)
   // A committed file stays an input whatever output reaches it (`committedFiles`).
   let committed: ((abs: string) => boolean) | undefined
   const own = (rel: string): boolean =>
@@ -343,7 +399,10 @@ function resolveWorkspaceFiles(args: {
   const ownsAny =
     splitNegations(args.ownWorkspaceOutputs).positive.length > 0 ||
     splitNegations(args.ownOutputs).positive.length > 0
-  const reach = ignoredReach(reachOf(positive), gitFiles)
+  const reach = ignoredReach(reachOf(positive), gitFiles, {
+    dir: args.workspaceRoot,
+    cache: args.gitFilesCache,
+  })
   const files = base.then((all) => {
     const kept = ownsAny ? all.filter((abs) => !own(relPosix(args.workspaceRoot, abs))) : all
     refuseUndecodable(kept, undecodable, args.workspaceRoot, 'workspaceFiles')
@@ -667,17 +726,13 @@ async function resolveRuntimeValues(
 }
 
 /**
- * What a set of output globs may not reach: `OUTPUT_NEVER`, and every
- * `node_modules` unless a glob names one. `**\/*.js` meant the build's
- * files, and the clean before each run deleted every installed `.js`
- * under `node_modules` with them (A-13); an install task declares
- * `node_modules/**` and keeps it. Workspace outputs took none of this, not
- * even `.git`.
+ * What a set of output globs may not reach (`outputNever`). `**\/*.js`
+ * meant the build's files, and the clean before each run deleted every
+ * installed `.js` under `node_modules` with them (A-13); an install task
+ * declares `node_modules/**` and keeps it.
  */
-function outputExcludes(outputs: readonly string[]): Bun.Glob[] {
-  return (namesNodeModules(outputs) ? OUTPUT_NEVER : [...OUTPUT_NEVER, '**/node_modules/**']).map(
-    globFor,
-  )
+function outputExcludes(outputs: readonly string[], scope: 'project' | 'workspace'): Bun.Glob[] {
+  return outputNever(outputs, scope).map(globFor)
 }
 
 /**
@@ -690,9 +745,31 @@ export async function resolveOutputs(args: {
   outputs: readonly string[]
   nestedProjectDirs: string[]
 }): Promise<string[]> {
+  return (await scanOutputs(args)).files
+}
+
+/**
+ * `resolveOutputs`, plus the empty directories the globs match: a save
+ * keeps them, so a hit leaves the tree a miss left (Turbo and Nx restore
+ * them too). Only a save asks; a hit's walk compares files.
+ */
+export async function resolveOutputTree(args: {
+  projectDir: string
+  outputs: readonly string[]
+  nestedProjectDirs: string[]
+}): Promise<{ files: string[]; emptyDirs: string[] }> {
+  const emptyDirs = new Set<string>()
+  const { files } = await scanOutputs(args, emptyDirs)
+  return { files, emptyDirs: containedIn(args.projectDir, [...emptyDirs]).sort() }
+}
+
+async function scanOutputs(
+  args: { projectDir: string; outputs: readonly string[]; nestedProjectDirs: string[] },
+  emptyDirs?: Set<string>,
+): Promise<{ files: string[] }> {
   const { positive, negative } = splitNegations(args.outputs)
-  if (positive.length === 0) return []
-  const excludeGlobs = [...outputExcludes(positive), ...asTrees(negative).map(globFor)]
+  if (positive.length === 0) return { files: [] }
+  const excludeGlobs = [...outputExcludes(positive, 'project'), ...asTrees(negative).map(globFor)]
   const trees = asTrees(positive)
   refuseDirLinkedOut(args.projectDir, trees)
   const scanned = [
@@ -701,6 +778,7 @@ export async function resolveOutputs(args: {
       excludeGlobs,
       args.projectDir,
       inNestedProject(args.projectDir, args.nestedProjectDirs),
+      emptyDirs,
     )),
   ]
   // Containment, enforced HERE and not only at the loader. `cleanOutputs`
@@ -710,7 +788,7 @@ export async function resolveOutputs(args: {
   // outside the project, so any future caller reaching it by another route (a
   // programmatic embedder, a config source that skips the loader) is contained
   // by construction.
-  return containedIn(args.projectDir, scanned).sort()
+  return { files: containedIn(args.projectDir, scanned).sort() }
 }
 
 /**
@@ -729,8 +807,8 @@ export function committedFiles(
 
 /**
  * The literal head of each output glob, walked: the scan follows a link
- * there (`dist -> ../elsewhere` for `dist/**`) and only there. A link to a
- * FILE is the archive's to judge (L-23); a dangling one the restore's.
+ * there (`dist -> ../elsewhere` for `dist/**`) and only there. A link
+ * below it is an output, kept as the link (`archive.ts`).
  */
 function refuseDirLinkedOut(projectDir: string, trees: readonly string[]): void {
   let realRoot: string | undefined
@@ -742,10 +820,11 @@ function refuseDirLinkedOut(projectDir: string, trees: readonly string[]): void
       if (!isInside(projectDir, at)) break
       let st
       try {
-        st = lstatSync(at)
+        st = lstatSync(at, { throwIfNoEntry: false })
       } catch {
         break
       }
+      if (st === undefined) break
       if (!st.isSymbolicLink()) continue
       let real: string
       try {
@@ -948,6 +1027,8 @@ export async function cleanOutputPaths(args: {
   rels: readonly string[]
   outputs: readonly string[]
   committed?: (abs: string) => boolean
+  /** Directories the prune leaves standing even when emptied (absolute). */
+  keep?: ReadonlySet<string>
 }): Promise<void> {
   const committed = args.committed ?? committedFiles(undefined, args.projectDir)
   const files = args.rels.map((r) => path.resolve(args.projectDir, r)).filter((f) => !committed(f))
@@ -955,6 +1036,7 @@ export async function cleanOutputPaths(args: {
     args.projectDir,
     await removeAll(files, args.projectDir),
     pruneScope(args.projectDir, args.outputs),
+    args.keep,
   )
 }
 
@@ -1147,6 +1229,7 @@ async function pruneEmptiedDirs(
   root: string,
   removed: readonly string[],
   scope?: PruneScope,
+  keep?: ReadonlySet<string>,
 ): Promise<void> {
   const rootResolved = path.resolve(root)
   // LEVEL ORDER, not a walk-up per directory. A parent is attempted only
@@ -1166,7 +1249,8 @@ async function pruneEmptiedDirs(
       (dir) =>
         dir !== rootResolved &&
         dir.startsWith(rootResolved + path.sep) &&
-        (scope === undefined || inScope(dir, scope)),
+        (scope === undefined || inScope(dir, scope)) &&
+        keep?.has(dir) !== true,
     )
     const gone = (err: NodeJS.ErrnoException): boolean => err.code === 'ENOENT'
     if (dirs.length <= SYNC_CLEAN_MAX) {
@@ -1240,7 +1324,7 @@ export async function resolveWorkspaceOutputs(args: {
 }): Promise<string[]> {
   const { positive, negative } = splitNegations(args.outputs)
   if (positive.length === 0) return []
-  const excludeGlobs = [...outputExcludes(positive), ...asTrees(negative).map(globFor)]
+  const excludeGlobs = [...outputExcludes(positive, 'workspace'), ...asTrees(negative).map(globFor)]
   const scanned = [...(await scanUnion(asTrees(positive), excludeGlobs, args.workspaceRoot))]
   // Same containment as the project twin, anchored one level out. These globs
   // deliberately ignore PROJECT boundaries — that is the escape hatch — but
@@ -1301,7 +1385,11 @@ export { asTrees } from '../util/index.js'
  * unanswered. Testing every literal against every file was ~1.5 ms of a
  * 1,800-file all-cached run (2026-10-06).
  */
-function unanswered(literals: readonly string[], files: readonly string[]): Set<string> {
+function unanswered(
+  literals: readonly string[],
+  files: readonly string[],
+  newIgnored?: (lit: string) => boolean,
+): Set<string> {
   const left = new Set<string>()
   for (const lit of literals) {
     const under = `${lit}/`
@@ -1309,7 +1397,7 @@ function unanswered(literals: readonly string[], files: readonly string[]): Set<
       files[lowerBound(files, lit)] === lit ||
       files[lowerBound(files, under)]?.startsWith(under) === true ||
       files.some((rel) => rel === lit || rel.startsWith(under))
-    if (!answered) left.add(lit)
+    if (!answered || newIgnored?.(lit) === true) left.add(lit)
   }
   return left
 }
@@ -1337,19 +1425,33 @@ function lowerBound(files: readonly string[], key: string): number {
 function ignoredReach(
   reach: { prefixes: readonly string[]; literals: readonly string[] },
   listed: readonly string[],
+  ignoredIn?: { dir: string; cache: GitFilesCache | undefined },
 ): readonly string[] {
-  const named = outright(reach)
+  let named = outrightMemo.get(reach)
+  if (named === undefined) outrightMemo.set(reach, (named = outright(reach)))
   if (named.length === 0) return []
   // Per listing and entries: thousands of tasks share a few declarations.
   let memo = reachMemo.get(listed)
   if (memo === undefined) reachMemo.set(listed, (memo = new Map()))
   const key = named.join('\0')
   let left = memo.get(key)
-  if (left === undefined) memo.set(key, (left = [...unanswered(named, listed)]))
+  if (left === undefined) {
+    // A listed path under a named directory git otherwise ignores (a kept
+    // `gen/.gitkeep`) answered for the whole of it, and the untracked files
+    // beside it never entered the key.
+    const cache = ignoredIn?.cache
+    const newIgnored =
+      cache === undefined
+        ? undefined
+        : (lit: string) => cache.newFilesIgnored(path.resolve(ignoredIn!.dir, lit))
+    memo.set(key, (left = [...unanswered(named, listed, newIgnored)]))
+  }
   return left
 }
 
 const reachMemo = new WeakMap<readonly string[], Map<string, readonly string[]>>()
+// A declaration's plan is memoized, so its entries are reckoned once.
+const outrightMemo = new WeakMap<object, string[]>()
 
 /**
  * A declaration's literals and globs' fixed prefixes, each once: none for a
@@ -1458,30 +1560,6 @@ function refuseUndecodable(
   )
 }
 
-const ONE_ALTERNATIVE_BRACE = /(?<!\\)\{[^{},]*\}/
-
-/**
- * `Bun.Glob` reads `{b}` as a brace of one alternative, so `src/{b}.ts`
- * matches `src/b.ts` and never a file named `{b}.ts`: that file stays out
- * of the key and an edit to it is a hit. Neither reading is sure to be
- * the one meant, so the entry is refused with both spellings.
- */
-function refuseOneAlternativeBrace(
-  entries: readonly string[],
-  field: 'files' | 'workspaceFiles',
-): void {
-  for (const entry of entries) {
-    const m = ONE_ALTERNATIVE_BRACE.exec(entry)
-    if (m === null) continue
-    const inner = m[0].slice(1, -1)
-    throw new UserError(
-      `inputs.${field}: "${entry}" holds a brace with one alternative, which matches ` +
-        `"${inner}" and never a name holding "${m[0]}". Write "${entry.replace(m[0], inner)}", ` +
-        `or "${entry.replace(m[0], `\\{${inner}\\}`)}" for the braces themselves.`,
-    )
-  }
-}
-
 /** What a `files` declaration and its task's outputs compile to, whatever the project. */
 interface FilesPlan {
   positive: string[]
@@ -1530,7 +1608,6 @@ function filesPlan(
   if (files === undefined) {
     positive.push(...DEFAULT_FILE_GLOBS)
   } else {
-    refuseOneAlternativeBrace(files, 'files')
     for (const entry of files) {
       if (entry.startsWith('!')) negative.push(entry.slice(1))
       else positive.push(entry)
@@ -1637,7 +1714,7 @@ function workspaceMatcher(decl: readonly string[]): (rel: string) => boolean {
   if (m !== undefined) return m
   const { positive, negative } = splitNegations(decl)
   const isPositive = anyTaskGlob(asTrees(positive))
-  const isExcluded = anyTaskGlob([...ALWAYS_IGNORE, ...asTrees(negative)])
+  const isExcluded = anyTaskGlob([...WORKSPACE_ALWAYS_IGNORE, ...asTrees(negative)])
   m = (rel) => isPositive(rel) && !isExcluded(rel)
   workspaceMatchers.set(key, m)
   return m
@@ -1648,7 +1725,7 @@ async function resolveFiles(
 ): Promise<{ files: string[]; listing?: InputListing }> {
   const plan = filesPlan(args.files, args.ownOutputs)
   if (plan === null) return { files: [] }
-  const { positive, negative, isExcluded, ownOutput, positiveGlobs, isPositive } = plan
+  const { isExcluded, ownOutput, positiveGlobs, isPositive } = plan
 
   const nested = inNestedProject(args.projectDir, args.nestedProjectDirs)
   // Its root-anchored outputs that land in the project, as `files` sees them.
@@ -1664,7 +1741,13 @@ async function resolveFiles(
   // duration of one orchestrator run.
   // Everything below the snapshot that decides the result: the project, what
   // it declares, what it excludes as its own outputs, and the boundaries.
-  const memoKey = `${args.projectDir}\0${positive.join('\u0001')}\0${negative.join('\u0001')}\0${args.ownOutputs.join('\u0001')}\0${args.ownWorkspaceOutputs.join('\u0001')}\0${args.nestedProjectDirs.join('\u0001')}`
+  const memoKey = filesMemoKey(
+    args.projectDir,
+    plan,
+    args.ownOutputs,
+    args.ownWorkspaceOutputs,
+    args.nestedProjectDirs,
+  )
   let gitFiles = args.gitFilesCache?.snapshotFor(args.projectDir, positiveGlobs)
   let undecodable = args.gitFilesCache?.undecodableNames
   if (gitFiles !== undefined) {
@@ -1677,7 +1760,7 @@ async function resolveFiles(
         files: withIgnored(
           args.projectDir,
           memo.result,
-          ignoredReach(plan, gitFiles),
+          ignoredReach(plan, gitFiles, { dir: args.projectDir, cache: args.gitFilesCache }),
           plan,
           nested,
           ownWsOutput,
@@ -1739,7 +1822,7 @@ async function resolveFiles(
     if (!input && !committed(abs)) continue
     candidates.push(abs)
   }
-  const reach = ignoredReach(plan, gitFiles)
+  const reach = ignoredReach(plan, gitFiles, { dir: args.projectDir, cache: args.gitFilesCache })
   refuseUndecodable(candidates, undecodable, args.projectDir, 'files')
   // Second pass: existence check — but ONLY for paths without a
   // trusted index OID. A clean-per-status tracked file necessarily
@@ -1870,7 +1953,11 @@ export interface InputListing {
   literals: readonly string[]
 }
 
-function reachOf(positive: readonly string[]): { prefixes: string[]; literals: string[] } {
+function reachOf(entries: readonly string[]): { prefixes: string[]; literals: string[] } {
+  // Each alternative names what it would alone: `{gen/a.txt,gen/b.txt}`
+  // names both files, as `gen/{a,b}.txt` does; whole, it had no fixed
+  // prefix and named nothing (Growth's parity, 2026-10-17).
+  const positive = entries.flatMap(braceAlternatives)
   const prefixes = new Set<string>()
   for (const p of asTrees(positive)) {
     if (isLiteralPattern(p)) continue
@@ -2013,6 +2100,7 @@ async function scanUnion(
   excludeGlobs: readonly Bun.Glob[],
   cwd: string,
   nested: (rel: string) => boolean = () => false,
+  emptyDirs?: Set<string>,
 ): Promise<Set<string>> {
   const matches = new Set<string>()
   // `Bun.Glob`'s scan finds nothing for a brace whose alternatives hold a
@@ -2026,7 +2114,9 @@ async function scanUnion(
       const abs = path.resolve(cwd, rel)
       const st = lstatSync(abs, { throwIfNoEntry: false })
       if (st !== undefined && (st.isFile() || st.isSymbolicLink())) matches.add(abs)
-      else if (st === undefined && rel.includes('\ufffd')) refuseUndecodableOutput(abs)
+      else if (emptyDirs !== undefined && st?.isDirectory() === true) {
+        if (readdirSync(abs).length === 0) emptyDirs.add(abs)
+      } else if (st === undefined && rel.includes('\ufffd')) refuseUndecodableOutput(abs)
     }
   }
   return matches

package/src/cache/key-fold.ts

@@ -110,7 +110,14 @@ import type { CacheKeyInput } from './layer.js'
 // v43 stays when core stopped folding package files (2026-10-14): the
 // `workspace:` and `pkg:` parts left the chain, so every key moved and no
 // unchanged key holds wrong bytes.
-export const CACHE_VERSION = 'vx-cache-v43'
+// v44: the sidecar lists the empty directories under the outputs; a v43
+// artifact holds none and a hit left them out (Growth's parity, 2026-10-16).
+// v45: the sidecar lists the symlinks under the outputs and a hit makes
+// them; a v44 artifact holds a link as a copy of its target (M, 2026-10-16).
+// v46: vx's names are reserved only at the project root; a v45 artifact
+// left out a build's own `dist/.git/**`, `dist/.vx/**` and nested
+// `vx.lock.json` (Growth's parity, 2026-10-17).
+export const CACHE_VERSION = 'vx-cache-v46'
 
 /**
  * The digest a key folds for an input gone between its enumeration and its
@@ -151,6 +158,87 @@ export async function foldKey(
    */
   behind?: (link: string) => Promise<string>,
 ): Promise<string> {
+  const cap = input.captureInto
+  let h = foldHead(input, digestValue)
+
+  // `resolveFiles` already returns its paths sorted, and a copy-and-sort
+  // of three thousand strings per task is not free: 7.4 ms of a 44-task
+  // run here (2026-09-20). A linear order check costs one comparison per
+  // file instead of n log n, and a caller that hands over an unsorted set
+  // — a plugin's own input list — still gets one. `>` on strings compares
+  // UTF-16 code units, which is what a comparator-less `sort` does.
+  let sortedInputs: readonly string[] = input.inputFiles
+  for (let i = 1; i < sortedInputs.length; i++) {
+    if (sortedInputs[i - 1]! > sortedInputs[i]!) {
+      sortedInputs = [...input.inputFiles].sort()
+      break
+    }
+  }
+  h = xxh3(`inputs:${sortedInputs.length}`, h)
+  // Per-file hash source, in preference order: the caller-supplied
+  // index-OID map (clean tracked files — zero I/O), then hashFile's
+  // stat memo (no read), then a full in-process blob-OID computation.
+  // All three describe the WORKTREE bytes, which is what the task
+  // reads — the index-OID map is only populated for paths whose
+  // worktree form matches their index form, because a clean filter
+  // (`text`/`eol`/`ident`/`filter`/`working-tree-encoding`) makes the index blob a DIFFERENT sequence
+  // of bytes and folding it would let two distinct worktree contents
+  // share a key. The fold order is locked to `sortedInputs` so
+  // results are stable across runs.
+  // The common warm shape is that the caller's OID map covers every file,
+  // and then there is nothing to await: building three thousand promises
+  // per task to resolve values already in hand cost 8.4 ms of that same
+  // run. One pass fills the array, and the first gap falls back to the
+  // awaited form for the whole list.
+  let fileHashes: readonly string[] | undefined
+  const provided = input.fileHashes
+  if (provided !== undefined) {
+    const out: string[] = []
+    for (const file of sortedInputs) {
+      const oid = provided.get(file)
+      if (oid === undefined) break
+      out.push(oid)
+    }
+    if (out.length === sortedInputs.length) fileHashes = out
+  }
+  fileHashes ??= await Promise.all(
+    sortedInputs.map((f) => provided?.get(f) ?? hashFile(f).catch(absentOr)),
+  )
+  // Links are rare, so a list without one awaits nothing more.
+  let behindLinks: Map<number, string> | undefined
+  if (behind !== undefined) {
+    const links: number[] = []
+    for (let i = 0; i < fileHashes.length; i++)
+      if (fileHashes[i]!.startsWith('120000:')) links.push(i)
+    if (links.length > 0) {
+      const digests = await Promise.all(links.map((i) => behind(sortedInputs[i]!)))
+      behindLinks = new Map(links.map((i, n) => [i, digests[n]!]))
+    }
+  }
+  for (let i = 0; i < sortedInputs.length; i++) {
+    const file = sortedInputs[i]!
+    const rel = relOf(file)
+    const oid = fileHashes[i]!
+    const linked = behindLinks?.get(i)
+    // A link folds what it points to in its own step, so a key without one is unchanged.
+    h = xxh3(linked === undefined ? `${rel}\0${oid}` : `${rel}\0${oid}\0${linked}`, h)
+    // The OID is already awaited — file capture is zero extra I/O.
+    if (cap) cap.push({ kind: 'file', name: rel, hash: oid })
+    if (linked !== undefined && cap) cap.push({ kind: 'linked', name: rel, hash: xxh3hex(linked) })
+  }
+
+  return h.toString(16).padStart(16, '0')
+}
+
+/**
+ * The fold up to the input files, which come last: what a task's key is
+ * once its files are folded onto it. `computeTaskHash` asks it alone when
+ * a remembered fold of the same files answers the rest (`FoldMemo`).
+ */
+export function foldHead(
+  input: CacheKeyInput,
+  digestValue: (value: string) => string = xxh3hex,
+): bigint {
   // Seed-chained xxHash3: each step folds one field into the
   // running digest via `xxh3(part, prevDigest)`. Equivalent to the
   // old CryptoHasher.update() pattern, no intermediate buffer.
@@ -230,72 +318,5 @@ export async function foldKey(
       for (const [n, v] of pluginParts) cap.push({ kind: 'plugin', name: n, hash: digestValue(v) })
     }
   }
-
-  // `resolveFiles` already returns its paths sorted, and a copy-and-sort
-  // of three thousand strings per task is not free: 7.4 ms of a 44-task
-  // run here (2026-09-20). A linear order check costs one comparison per
-  // file instead of n log n, and a caller that hands over an unsorted set
-  // — a plugin's own input list — still gets one. `>` on strings compares
-  // UTF-16 code units, which is what a comparator-less `sort` does.
-  let sortedInputs: readonly string[] = input.inputFiles
-  for (let i = 1; i < sortedInputs.length; i++) {
-    if (sortedInputs[i - 1]! > sortedInputs[i]!) {
-      sortedInputs = [...input.inputFiles].sort()
-      break
-    }
-  }
-  h = xxh3(`inputs:${sortedInputs.length}`, h)
-  // Per-file hash source, in preference order: the caller-supplied
-  // index-OID map (clean tracked files — zero I/O), then hashFile's
-  // stat memo (no read), then a full in-process blob-OID computation.
-  // All three describe the WORKTREE bytes, which is what the task
-  // reads — the index-OID map is only populated for paths whose
-  // worktree form matches their index form, because a clean filter
-  // (`text`/`eol`/`ident`/`filter`/`working-tree-encoding`) makes the index blob a DIFFERENT sequence
-  // of bytes and folding it would let two distinct worktree contents
-  // share a key. The fold order is locked to `sortedInputs` so
-  // results are stable across runs.
-  // The common warm shape is that the caller's OID map covers every file,
-  // and then there is nothing to await: building three thousand promises
-  // per task to resolve values already in hand cost 8.4 ms of that same
-  // run. One pass fills the array, and the first gap falls back to the
-  // awaited form for the whole list.
-  let fileHashes: readonly string[] | undefined
-  const provided = input.fileHashes
-  if (provided !== undefined) {
-    const out: string[] = []
-    for (const file of sortedInputs) {
-      const oid = provided.get(file)
-      if (oid === undefined) break
-      out.push(oid)
-    }
-    if (out.length === sortedInputs.length) fileHashes = out
-  }
-  fileHashes ??= await Promise.all(
-    sortedInputs.map((f) => provided?.get(f) ?? hashFile(f).catch(absentOr)),
-  )
-  // Links are rare, so a list without one awaits nothing more.
-  let behindLinks: Map<number, string> | undefined
-  if (behind !== undefined) {
-    const links: number[] = []
-    for (let i = 0; i < fileHashes.length; i++)
-      if (fileHashes[i]!.startsWith('120000:')) links.push(i)
-    if (links.length > 0) {
-      const digests = await Promise.all(links.map((i) => behind(sortedInputs[i]!)))
-      behindLinks = new Map(links.map((i, n) => [i, digests[n]!]))
-    }
-  }
-  for (let i = 0; i < sortedInputs.length; i++) {
-    const file = sortedInputs[i]!
-    const rel = relOf(file)
-    const oid = fileHashes[i]!
-    const linked = behindLinks?.get(i)
-    // A link folds what it points to in its own step, so a key without one is unchanged.
-    h = xxh3(linked === undefined ? `${rel}\0${oid}` : `${rel}\0${oid}\0${linked}`, h)
-    // The OID is already awaited — file capture is zero extra I/O.
-    if (cap) cap.push({ kind: 'file', name: rel, hash: oid })
-    if (linked !== undefined && cap) cap.push({ kind: 'linked', name: rel, hash: xxh3hex(linked) })
-  }
-
-  return h.toString(16).padStart(16, '0')
+  return h
 }