@vzn/vx 0.0.640 → 0.0.641

package/src/cache/archive.ts

@@ -20,11 +20,13 @@
 // holding more than a chunk. `Bun.Archive` used to do all three and
 // needed the whole tar in memory on every side — restoring a 150 MiB
 // artifact peaked at 3.2× its size, saving one at 4.7× (measured
-// 2026-09-03). Every regular entry is written beside its target under a
-// `.vx-tmp-*` name and renamed into place only once the WHOLE archive has
-// been read and every name proven safe, so a poisoned entry anywhere —
-// even the last one — leaves nothing behind but the empty directories it
-// needed, which are pruned too.
+// 2026-09-03). Every regular entry is written to the workspace's staging
+// directory (`.vx/tmp/<pid>-0/`, vx's own, never an output folder) and
+// renamed over its target only once the WHOLE archive has been read and
+// every name proven safe, so a poisoned entry anywhere — even the last
+// one — leaves nothing behind but the empty directories it needed, which
+// are pruned too, and a killed restore leaves its temps where the next
+// run sweeps them (`sweepStaging`).
 //
 // What stays here is the part no tar reader can decide for us: WHERE an
 // entry may land on disk. Every name is validated and every destination
@@ -39,14 +41,33 @@
 
 import {
   chmodSync,
+  chownSync,
+  closeSync,
+  constants,
+  existsSync,
+  fchmodSync,
+  fstatSync,
+  futimesSync,
   lstatSync,
+  openSync,
   readFileSync,
   realpathSync,
-  renameSync,
   statSync,
   utimesSync,
+  writeFileSync,
 } from 'node:fs'
-import { lstat, mkdir, readlink, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  readlink,
+  realpath,
+  rename,
+  rmdir,
+  stat,
+  unlink,
+  writeFile,
+} from 'node:fs/promises'
 import path from 'node:path'
 import { UserError } from '../util/index.js'
 import { WORKSPACE_OUTPUT_PREFIX } from './layer.js'
@@ -595,12 +616,15 @@ export async function extractArtifactStream(
   destDir: string,
   workspaceDest: string | undefined,
   verify?: (provided: ReadonlySet<string>) => void,
+  accept?: (name: string) => boolean,
+  /** The workspace root whose `.vx/tmp/` stages the entries; absent, each stages beside its target. */
+  stageRoot?: string,
 ): Promise<Set<string>> {
   // No `mkdir -p` of the destination here: `stage` creates each entry's
   // directory chain, the destination included, and the cache restores
   // into a project directory that exists. The eager one cost every
   // restore a thread-pool round trip for an EEXIST and a stat (item 627).
-  const x = new Extractor(destDir, workspaceDest)
+  const x = new Extractor(destDir, workspaceDest, stageRoot)
   const provided = new Set<string>()
   const headerMtime = new Map<string, number>()
   let meta: MetaFile['files'] = {}
@@ -615,6 +639,13 @@ export async function extractArtifactStream(
         continue
       }
       assertSafeName(e.name)
+      // Before anything is staged: an entry the task never declared is not
+      // this task's save, and none of the archive lands.
+      if (accept !== undefined && !accept(e.name)) {
+        throw new ArchiveSecurityError(
+          `archive entry is not one of the task's declared outputs: ${e.name}`,
+        )
+      }
       const dest = x.destFor(e.name)
       if (dest === null || dest.rel.length === 0) {
         await drain(body)
@@ -644,6 +675,9 @@ export async function extractArtifactStream(
   return provided
 }
 
+/** BSD gives every new file its directory's group, setgid or not. */
+const INHERITS_GROUP = process.platform === 'darwin'
+
 /**
  * Entries up to this size are buffered and written without waiting, so a
  * thousand tiny outputs restore in parallel; larger ones stream chunk by
@@ -674,8 +708,32 @@ async function bytesOf(body: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
 const textOf = async (body: AsyncIterable<Uint8Array>): Promise<string> =>
   utf8.decode(await bytesOf(body))
 
+/**
+ * Bring a target that already held the entry's bytes to its mode and
+ * mtime, through a descriptor opened without following a link: one
+ * planted since the compare is refused, never written through.
+ */
+function keep(s: Staged, ino: number, mode: number, mtimeMs: number | undefined): void {
+  const fd = openSync(s.target, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const st = fstatSync(fd)
+    if (st.ino !== ino || st.nlink !== 1) {
+      throw new Error(`${s.target} changed while it was restored`)
+    }
+    if ((st.mode & 0o7777) !== (mode & 0o777)) fchmodSync(fd, mode & 0o777)
+    if (mtimeMs !== undefined && Math.floor(st.mtimeMs) !== mtimeMs) {
+      const t = new Date(mtimeMs)
+      futimesSync(fd, t, t)
+    }
+  } finally {
+    closeSync(fd)
+  }
+}
+
 /** One staged entry: written at `tmp`, renamed to `target` on commit. */
 interface Staged {
+  /** `tmp` is in the staging directory, not beside `target`. */
+  staged: boolean
   name: string
   tmp: string
   target: string
@@ -683,6 +741,10 @@ interface Staged {
   created: string | undefined
   /** Written by Bun's file writer, which creates with 0664 where `writeFile` uses 0666 (before the umask). */
   streamed: boolean
+  /** The destination it is contained in. */
+  base: string
+  /** The target already holds the entry's bytes: nothing was written, and only its mode and mtime may change. */
+  same?: number
 }
 
 /**
@@ -709,6 +771,7 @@ class Extractor {
   constructor(
     private readonly destDir: string,
     private readonly workspaceDest: string | undefined,
+    private readonly stageRoot: string | undefined,
   ) {}
 
   /** Each namespace anchors at its own destination dir. */
@@ -865,7 +928,33 @@ class Extractor {
       }
       this.ensuredDirs.add(dir)
     }
-    // Write beside the target and RENAME into place. rename(2) replaces
+    // A target that already holds these bytes stays: renaming over a live
+    // file costs ~0.4 ms on ext4 (auto_da_alloc), and a hit that changed
+    // one of 2,000 outputs paid it 2,000 times. Bytes, not a stat stamp: a
+    // reproducible build gives every output one mtime (item 886).
+    if (body instanceof Uint8Array && created === undefined) {
+      const st = lstatSync(target, { throwIfNoEntry: false })
+      if (
+        st !== undefined &&
+        st.isFile() &&
+        st.nlink === 1 &&
+        st.size === body.byteLength &&
+        readFileSync(target).equals(body)
+      ) {
+        this.staged.push({
+          staged: false,
+          name,
+          tmp: '',
+          target,
+          created,
+          streamed: false,
+          base,
+          same: st.ino,
+        })
+        return
+      }
+    }
+    // Write apart from the target and RENAME into place. rename(2) replaces
     // the destination's directory ENTRY without following it, which is
     // what makes this both link-safe and concurrency-safe:
     //
@@ -882,15 +971,15 @@ class Extractor {
     //
     // A directory at the target makes the rename fail — the same
     // fail-closed outcome the plain write had.
-    // The temp is a sibling with its own short name, never `<target>.suffix`:
-    // a suffix pushed a legal name of 242–255 bytes past NAME_MAX, and the
-    // restore of a valid artifact failed with ENAMETOOLONG (item 666).
-    const tmp = path.join(
-      path.dirname(target),
-      `.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`,
-    )
+    // Staged under `.vx/tmp/`, so no output folder ever holds a temp: a
+    // reader or a key taken meanwhile saw `.vx-tmp-*` files beside the
+    // outputs, and a killed restore left them there (M, 2026-10-16).
+    const staged = this.stageRoot !== undefined
+    const tmp = staged
+      ? path.join(await stagingDir(this.stageRoot!), (tmpSeq++).toString(36))
+      : siblingTemp(target)
     const streamed = !(body instanceof Uint8Array)
-    this.staged.push({ name, tmp, target, created, streamed })
+    this.staged.push({ staged, name, tmp, target, created, streamed, base })
     if (body instanceof Uint8Array) {
       this.inflightBytes += body.byteLength
       // `writeFile`, not `Bun.write`: for a buffer this size `Bun.write`
@@ -926,12 +1015,11 @@ class Extractor {
 
   /**
    * Apply each entry's mode and mtime, then rename everything into place.
-   * Synchronous calls in batches: the three metadata calls per file are a
-   * few microseconds each on the calling thread and ~40 µs each as
-   * thread-pool round trips, and a large artifact has thousands of them
-   * (measured 2026-09-11 on payload's ui, 4,069 files: 892 ms → see the
-   * archive bench). A yield every `COMMIT_BATCH` files keeps the other
-   * restores' round trips flowing. The chmod is skipped when the mode is
+   * The metadata calls are synchronous: a few microseconds each on the
+   * calling thread and ~40 µs each as thread-pool round trips, and a large
+   * artifact has thousands of them (measured 2026-09-11 on payload's ui,
+   * 4,069 files: 892 ms → see the archive bench). The renames go to the
+   * pool, `RENAME_BATCH` at a time: each replaces a live file. The chmod is skipped when the mode is
    * the one the temp file was created with — the common case. The two
    * writers create with different modes (under umask 000: 0666 and 0664),
    * so each is stat'ed once.
@@ -940,38 +1028,107 @@ class Extractor {
     metaFor: (name: string) => [mode: number, mtimeMs: number | undefined],
   ): Promise<void> {
     await this.drain()
-    const createdModes = new Map<boolean, number>()
+    const created = new Map<boolean, { mode: number; uid: number; gid: number }>()
+    // The group a file written in place would take, by directory: a setgid
+    // directory's on Linux, every directory's on BSD/macOS. A file staged
+    // elsewhere took the staging directory's.
+    const setgid = new Map<string, number | null>()
     let n = 0
+    let renames: Promise<void>[] = []
+    const checked = new Set<string>()
     for (const s of this.staged) {
+      await this.assertStillContained(s, checked)
       const [mode, mtimeMs] = metaFor(s.name)
-      let createdMode = createdModes.get(s.streamed)
-      if (createdMode === undefined) {
-        createdMode = statSync(s.tmp).mode & 0o777
-        createdModes.set(s.streamed, createdMode)
+      if (s.same !== undefined) {
+        keep(s, s.same, mode, mtimeMs)
+        continue
+      }
+      let made = created.get(s.streamed)
+      if (made === undefined) {
+        const st = statSync(s.tmp)
+        made = { mode: st.mode & 0o777, uid: st.uid, gid: st.gid }
+        created.set(s.streamed, made)
+      }
+      if ((mode & 0o777) !== made.mode) chmodSync(s.tmp, mode & 0o777)
+      // A Date, not seconds: Bun reads a negative number of seconds as
+      // "now", and a Date before 1970 as itself (Bun 1.4.2).
+      const t = mtimeMs === undefined ? undefined : new Date(mtimeMs)
+      if (t !== undefined) utimesSync(s.tmp, t, t)
+      if (s.staged) {
+        const dir = path.dirname(s.target)
+        let gid = setgid.get(dir)
+        if (gid === undefined) {
+          const st = statSync(dir)
+          gid = INHERITS_GROUP || (st.mode & 0o2000) !== 0 ? st.gid : null
+          setgid.set(dir, gid)
+        }
+        if (gid !== null && gid !== made.gid) chownSync(s.tmp, made.uid, gid)
       }
-      if ((mode & 0o777) !== createdMode) chmodSync(s.tmp, mode & 0o777)
-      if (mtimeMs !== undefined) {
-        // A Date, not seconds: Bun reads a negative number of seconds as
-        // "now", and a Date before 1970 as itself (Bun 1.4.2).
-        const t = new Date(mtimeMs)
-        utimesSync(s.tmp, t, t)
+      renames.push(this.place(s, mode, t))
+      if (++n % RENAME_BATCH === 0) {
+        await settle(renames)
+        renames = []
       }
-      renameSync(s.tmp, s.target)
-      if (++n % COMMIT_BATCH === 0) await new Promise<void>((r) => setImmediate(r))
     }
+    await settle(renames)
     this.staged.length = 0
   }
 
   /**
-   * Never leave a stray `.vx-tmp-*` behind: the declared output globs would
-   * sweep it into the next artifact. Directories this extraction created
+   * Rename `s` over its target. A target on another filesystem than
+   * `.vx/tmp/` (EXDEV) is reached through a temp beside it, for that file
+   * only: the rename that replaces the live file stays atomic.
+   */
+  private async place(s: Staged, mode: number, t: Date | undefined): Promise<void> {
+    try {
+      await rename(s.tmp, s.target)
+    } catch (err) {
+      if (!s.staged || (err as NodeJS.ErrnoException).code !== 'EXDEV') throw err
+      const side = siblingTemp(s.target)
+      try {
+        await copyFile(s.tmp, side)
+        chmodSync(side, mode & 0o777)
+        if (t !== undefined) utimesSync(side, t, t)
+        await rename(side, s.target)
+      } catch (e) {
+        await unlink(side).catch(() => undefined)
+        throw e
+      }
+      await unlink(s.tmp).catch(() => undefined)
+    }
+  }
+
+  /**
+   * The staging check, again at the rename: a directory on the way swapped
+   * for a link out of the base since then would carry the rename with it.
+   * Bun has no `renameat` against a held directory fd, so this is by path,
+   * once per directory per commit.
+   */
+  private async assertStillContained(s: Staged, checked: Set<string>): Promise<void> {
+    const dir = path.dirname(s.target)
+    if (checked.has(dir)) return
+    checked.add(dir)
+    const realBase = await this.realBaseOf(s.base)
+    const real = await realOf(dir, true)
+    if (real !== realBase && !real.startsWith(realBase + path.sep)) {
+      throw await linkOutError(path.resolve(s.base), dir, realBase)
+    }
+  }
+
+  /**
+   * Never leave a temp behind: beside a target, the declared output globs
+   * would sweep it into the next artifact. Directories this extraction created
    * are removed bottom-up while empty; one a concurrent writer has since
    * filled is left alone.
    */
   async abort(): Promise<void> {
     await Promise.allSettled(this.inflight)
     this.inflight = []
-    await Promise.all(this.staged.map((s) => unlink(s.tmp).catch(() => undefined)))
+    await Promise.all(
+      this.staged.map((s) =>
+        s.same === undefined ? unlink(s.tmp).catch(() => undefined) : undefined,
+      ),
+    )
     // Newest first: a later entry's chain can sit inside an earlier one's
     // (`dist/` then `dist/sub/`), never the reverse.
     for (const s of this.staged.toReversed()) {
@@ -997,12 +1154,62 @@ class Extractor {
   }
 }
 
-/** Files renamed into place between two yields of a commit. */
-const COMMIT_BATCH = 256
+/**
+ * Renames in flight at once. A rename over a live file is not the few
+ * microseconds of one into an empty directory: on ext4 replacing a file
+ * starts writeback of the new one's data (`auto_da_alloc`), ~250 µs each,
+ * and synchronous ones stalled the main thread. 300 one-file restores
+ * took 25% longer than delete-then-restore (2026-10-16); on the thread
+ * pool they tie it, and 2,000 files in one restore are faster.
+ */
+const RENAME_BATCH = 64
+
+/** Wait for every rename, then throw the first failure: none is left in flight for `abort`. */
+async function settle(renames: readonly Promise<void>[]): Promise<void> {
+  for (const r of await Promise.allSettled(renames)) if (r.status === 'rejected') throw r.reason
+}
 
 /** Per-process counter for extract temp names; uniqueness only. */
 let tmpSeq = 0
 
+/** `.vx/<STAGING>/`: where restores stage, each process in its own `<pid>-0` directory. */
+export const STAGING = 'tmp'
+
+const stagingMade = new Set<string>()
+
+/**
+ * This process's staging directory under `root`'s `.vx/tmp/`, made on its
+ * first restore and again only if something removed it: one per restore
+ * cost 300 restores 12% (2026-10-16). Every restore's renames empty it;
+ * the next run's `sweepStaging` removes it once this process is gone.
+ */
+async function stagingDir(root: string): Promise<string> {
+  const top = path.join(root, '.vx', STAGING)
+  const own = path.join(top, `${process.pid.toString(36)}-0`)
+  if (stagingMade.has(own) && existsSync(own)) return own
+  await mkdir(own, { recursive: true })
+  // Ignored by git whatever `.vx/.gitignore` an older init committed.
+  try {
+    writeFileSync(path.join(top, '.gitignore'), '*\n', { flag: 'wx' })
+  } catch {
+    // there already, or the restore fails on its first write anyway
+  }
+  stagingMade.add(own)
+  return own
+}
+
+/**
+ * A temp beside `target`, with its own short name, never `<target>.suffix`:
+ * a suffix pushed a legal name of 242–255 bytes past NAME_MAX, and the
+ * restore of a valid artifact failed with ENAMETOOLONG (item 666).
+ */
+function siblingTemp(target: string): string {
+  return path.join(
+    path.dirname(target),
+    `.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`,
+  )
+}
+
 const WORKSPACE_PREFIX = 'workspace-outputs/'
 
 /**

package/src/cache/cache.ts

@@ -60,7 +60,7 @@ import {
   isFsRefusal,
   isOutOfFds,
   OUT_OF_FDS_HINT,
-  outputMatcher,
+  restorableOutput,
   relPosix,
   span,
   splitTaskId,
@@ -1842,9 +1842,14 @@ export class Cache implements CacheLayer {
   outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
     return this.outputs.outputDirsCurrent(projectDir, rows)
   }
-  async restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
+  async restoreOutputs(
+    hash: string,
+    projectDir: string,
+    workspaceRoot?: string,
+    outputs?: DeclaredOutputs,
+  ): Promise<void> {
     try {
-      await this.restoreOutputsOnce(hash, projectDir, workspaceRoot)
+      await this.restoreOutputsOnce(hash, projectDir, workspaceRoot, outputs)
     } catch (err) {
       if (!(err instanceof CorruptArtifactError)) throw err
       // Bad bytes under a good key failed the task on every run until
@@ -1879,7 +1884,8 @@ export class Cache implements CacheLayer {
   private async restoreOutputsOnce(
     hash: string,
     projectDir: string,
-    workspaceRoot?: string,
+    workspaceRoot: string | undefined,
+    outputs: DeclaredOutputs | undefined,
   ): Promise<void> {
     // In-process extraction — no fork+exec on the hot path
     // (~5-10ms reclaimed per hit vs the prior subprocess `tar -xf`).
@@ -1967,7 +1973,14 @@ export class Cache implements CacheLayer {
       // four workers overlap their round trips and a blocking one stalls
       // the other three (1,000-project restore row 1.1–1.2 s → 1.5 s).
       const tar = await decodedTar(inline ?? Bun.file(src), hash, this.artifactCeiling)
-      await extractArtifactStream(tar, projectDir, workspaceRoot, verify)
+      await extractArtifactStream(
+        tar,
+        projectDir,
+        workspaceRoot,
+        verify,
+        outputs === undefined ? undefined : declaredName(outputs),
+        workspaceRoot,
+      )
     } catch (err) {
       // A UserError here is the extractor naming the tree's fault (an
       // output directory that links out of the project).
@@ -1981,8 +1994,8 @@ export class Cache implements CacheLayer {
         throw new CorruptArtifactError(hash, err.message, err)
       // What is on disk, not what is in the archive: a directory standing
       // where the entry holds a file, or a file where it needs a directory.
-      // The clean removes the FILES the output globs select and the
-      // directories that removal emptied, so this is a path it left: one
+      // The restore removes the FILES the output globs select that block it
+      // and the directories that removal emptied, so this is a path it left: one
       // the globs do not cover, or an empty directory where a file goes,
       // which `dist/**` covers and the clean does not take (item 1094).
       // Named as such, not as a corrupt artifact. A
@@ -2001,7 +2014,7 @@ export class Cache implements CacheLayer {
             : 'a file stands where the entry needs a directory'
         throw new UserError(
           `restore of ${hash} into ${projectDir} was blocked by what is on disk (${msg.startsWith(code) ? msg : `${code}: ${msg}`}): ${what}. ` +
-            `The clean before a restore removes the files the output globs select and the directories that empties, not this — remove it and re-run.`,
+            `A restore replaces what the output globs select, not this — remove it and re-run.`,
         )
       }
       // A legal name under a destination deep enough that the two together
@@ -2049,7 +2062,7 @@ export class Cache implements CacheLayer {
       // on one workspace, a `vx watch` beside a `vx run` — a clean landing
       // 4–32 ms into a 2,000-file restore reproduces it, 2026-09-16). The
       // artifact is intact; the tree was not ours alone.
-      if (code === 'ENOENT' && (err as Error).message.includes('.vx-tmp-')) {
+      if (code === 'ENOENT' && /\.vx-tmp-|[\\/]\.vx[\\/]tmp[\\/]/.test((err as Error).message)) {
         throw new UserError(
           `restore of ${hash} into ${projectDir} was interrupted: a file it had just written vanished (${(err as Error).message}). ` +
             `Another vx run is using this workspace — re-run once it is done.`,
@@ -3083,16 +3096,9 @@ function assertArtifactNames(
     }
   }
   if (declared === undefined) return
-  // A path a `!` entry takes back is no declared output either (A-44).
-  const isFile = outputMatcher(declared.files)
-  const isWsFile = outputMatcher(declared.workspaceFiles)
+  const ok = declaredName(declared)
   for (const name of names) {
-    const ok = name.startsWith('outputs/')
-      ? isFile(name.slice('outputs/'.length))
-      : name.startsWith(WORKSPACE_OUTPUT_PREFIX)
-        ? isWsFile(name.slice(WORKSPACE_OUTPUT_PREFIX.length))
-        : true
-    if (!ok) {
+    if (!ok(name)) {
       throw new CorruptArtifactError(
         hash,
         `artifact carries ${name}, which is not one of the task's declared outputs`,
@@ -3101,6 +3107,24 @@ function assertArtifactNames(
   }
 }
 
+/**
+ * Whether an artifact entry names one of the task's declared outputs, as
+ * the save could have packed it (`restorableOutput`: a `!` take-back, vx's
+ * own files and an unnamed `node_modules` are none). Asked at ingest and
+ * again at every restore, so an entry that reached the local store by any
+ * route still writes nothing it should not (2026-10-16).
+ */
+function declaredName(declared: DeclaredOutputs): (name: string) => boolean {
+  const isFile = restorableOutput(declared.files)
+  const isWsFile = restorableOutput(declared.workspaceFiles)
+  return (name) =>
+    name.startsWith('outputs/')
+      ? isFile(name.slice('outputs/'.length))
+      : name.startsWith(WORKSPACE_OUTPUT_PREFIX)
+        ? isWsFile(name.slice(WORKSPACE_OUTPUT_PREFIX.length))
+        : true
+}
+
 /** What `ingest` reads a remote body through. */
 interface ChunkReader {
   read(): Promise<{ done: true; value?: undefined } | { done: false; value: Uint8Array }>

package/src/cache/index.ts

@@ -12,6 +12,7 @@ export {
   type CacheEntry,
   type CacheKeyInput,
   type CacheLayer,
+  type RemoteTraffic,
   type CachePolicy,
   cachesNothing,
   EXECUTED_RUNS_SQL,
@@ -48,6 +49,8 @@ export {
   resolveInputs,
   resolveOutputs,
   resolveWorkspaceOutputs,
+  sweepRestoreTemps,
+  sweepStaging,
   asTrees,
   type ProjectFilesCache,
   type WorkspaceFilesCache,