@vzn/vx 0.0.639 → 0.0.641

package/src/cache/cache.ts

@@ -60,7 +60,7 @@ import {
   isFsRefusal,
   isOutOfFds,
   OUT_OF_FDS_HINT,
-  outputMatcher,
+  restorableOutput,
   relPosix,
   span,
   splitTaskId,
@@ -112,6 +112,7 @@ import { FileHashStore } from './file-hashes.js'
 import { OutputIndex } from './output-index.js'
 import { RunHistory } from './run-history.js'
 import { CACHE_VERSION, foldKey } from './key-fold.js'
+import { behindLink } from './linked-inputs.js'
 
 /**
  * An artifact or temp file without an `entries` row is never reaped
@@ -1493,11 +1494,13 @@ export class Cache implements CacheLayer {
   }
 
   key(input: CacheKeyInput): Promise<string> {
+    const hashFile = (f: string): Promise<string> => this.hashFile(f)
     return foldKey(
       input,
-      (f) => this.hashFile(f),
+      hashFile,
       (f) => this.relFor(input.workspaceRoot, f),
       (v) => this.digestValue(v),
+      (link) => behindLink(link, hashFile),
     )
   }
 
@@ -1839,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
@@ -1876,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`).
@@ -1964,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).
@@ -1978,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
@@ -1998,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
@@ -2046,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.`,
@@ -3080,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`,
@@ -3098,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/file-hashes.ts

@@ -163,14 +163,10 @@ export class FileHashStore {
       // a more useful error.
       return await this.hashFileFromDisk(filePath)
     }
-    // A symlink folds as git folds it: the blob of its TARGET STRING, which
-    // is its mode-120000 index OID. Not the bytes behind it — a link to a
-    // directory has none, a dangling one has none, and a link to a file
-    // outside the project would fold bytes `git diff` and `--affected`
-    // cannot see. A link to a file inside the project tracks that file's
-    // content only when the file matches the task's globs too. No
-    // memo: readlink is one syscall, and the row would be keyed on the
-    // link's own stat, not its target's.
+    // A symlink's identity is git's: the blob of its TARGET STRING, its
+    // mode-120000 index OID, so a retarget moves it. What it points to
+    // folds after it (linked-inputs.ts). No memo: readlink is one syscall,
+    // and the row would be keyed on the link's own stat, not its target's.
     if (st.isSymbolicLink()) {
       return fileIdentity(
         '120000',
@@ -257,12 +253,11 @@ export class FileHashStore {
     for (const p of paths) {
       if (stats.has(p) || out.has(p)) continue
       try {
-        // lstat, not stat: `hashFile` folds a symlink as git folds it —
+        // lstat, not stat: `hashFile` identifies a symlink as git does —
         // the blob of its TARGET STRING — and this form promises the same
         // digest. Following the link here instead hashed the target's
         // BYTES, so the same path identified differently depending on
-        // which entry point the caller used, and the batch folded bytes
-        // `git diff` and `--affected` cannot see.
+        // which entry point the caller used.
         const st = lstatSync(p)
         if (st.isSymbolicLink()) {
           // No memo, for `hashFile`'s reason: the row would be keyed on
@@ -367,7 +362,7 @@ export class FileHashStore {
       if (!isPermissionError(err)) throw err
       throw new UserError(
         `${filePath} is not readable by this user (${err.code}), and vx reads it to derive a ` +
-          'cache key. Make it readable, or, for a task input, take it out of cache.inputs.files.',
+          'cache key. Make it readable, or, for a task input, take it out of inputs.files.',
       )
     }
     return this.hashBytes(bytes, filePath)

package/src/cache/fs-clock.ts

@@ -0,0 +1,62 @@
+// How far the workspace's file system clock runs behind this process's. A
+// racy window (`racyWindowMs`) compares a file's stamp, on the clock of the
+// file system that holds it, with a moment vx read from `Date.now()`, as if
+// they were one clock. A file system behind it (a WSL2 VM drifted from the
+// Windows host that stamps `/mnt/c`, a Docker Desktop bind mount, an NFS
+// server) dated an edit made while a command ran before the command, and the
+// entry filed the edit's output under the key of the bytes before it. A
+// clock ahead only makes a stamp look newer, which every window reads the
+// safe way.
+
+import { mkdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * A lag at or under this is the kernel's coarse tick, which stamps a write
+ * up to ~10 ms behind `Date.now()` on every box and which each window
+ * already holds; widening by it withheld saves after a fast upstream.
+ */
+const FS_CLOCK_TICK_MS = 20
+
+let lagMs = 0
+
+/** The lag every racy window is widened by: 0 unless measured past the tick. */
+export function fsClockLag(): number {
+  return lagMs
+}
+
+/** Widen every racy window by `ms`, when it is past the tick. */
+export function setFsClockLag(ms: number): void {
+  lagMs = ms > FS_CLOCK_TICK_MS ? ms : 0
+}
+
+/**
+ * What a stamp's own precision may hide (see `racyWindowMs`): a stamp with
+ * no sub-second part stands for any moment in its second, an even one for
+ * FAT's two.
+ */
+export function stampGrainMs(stampMs: number): number {
+  if (stampMs % 2000 === 0) return 2000
+  return stampMs % 1000 === 0 ? 1000 : 0
+}
+
+/**
+ * Measure the lag from a file written and removed in `dir` (the run's cache
+ * dir: on the workspace's file system by default, and ignored by git and
+ * `vx watch`), and apply it. Once a run: one write, one stat, one unlink. A
+ * directory that cannot take the file measures no lag.
+ */
+export function measureFsClockLag(dir: string): void {
+  const stamp = path.join(dir, `.vx-clock-${process.pid}`)
+  let ms = 0
+  try {
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(stamp, '')
+    const at = statSync(stamp).mtimeMs
+    ms = Date.now() - at - stampGrainMs(at)
+    unlinkSync(stamp)
+  } catch {
+    // unmeasured: no lag, as before
+  }
+  setFsClockLag(ms)
+}

package/src/cache/git-inputs.ts

@@ -1262,7 +1262,7 @@ function stripPrefixFromSet(paths: Set<string>, prefix: string): Set<string> {
  * directly — clean-tree input hashing costs zero reads/stats/SQLite.
  *
  * `workspaceWide`: set when any loaded task declares
- * `cache.inputs.workspaceFiles`. Disables pathspec scoping (those
+ * `inputs.workspaceFiles`. Disables pathspec scoping (those
  * globs must see every file from the root) and additionally stores a
  * workspace-wide partition keyed by `workspaceRoot` (files + trusted
  * OIDs), which `resolveWorkspaceFiles` consumes. When false, the
@@ -1839,7 +1839,7 @@ export async function applyGitEnumeration(
     // workspace's git holds as ONE entry (a gitlink, `dir/` when untracked)
     // — is listed through its own git above (`expandNestedRepos`), but under
     // a pathspec naming a project inside it the workspace's git lists
-    // nothing at all; so is a directory ignored outright. Storing the empty slice made the key never move: `cache.inputs
+    // nothing at all; so is a directory ignored outright. Storing the empty slice made the key never move: `inputs
     // matched no files`, then a stale hit under a green run once the source
     // changed (2026-09-16). No partition instead: `resolveFiles` spawns
     // `git ls-files` in the project's own directory, which a nested

package/src/cache/index.ts

@@ -12,6 +12,7 @@ export {
   type CacheEntry,
   type CacheKeyInput,
   type CacheLayer,
+  type RemoteTraffic,
   type CachePolicy,
   cachesNothing,
   EXECUTED_RUNS_SQL,
@@ -34,6 +35,8 @@ export {
   vxCacheEntries,
 } from './cache.js'
 export { ABSENT_INPUT, absentOr, CACHE_VERSION } from './key-fold.js'
+export { measureFsClockLag, setFsClockLag } from './fs-clock.js'
+export { filesBehind } from './linked-inputs.js'
 export {
   addedInput,
   type InputListing,
@@ -41,10 +44,13 @@ export {
   committedFiles,
   cleanWorkspaceOutputs,
   declaresInput,
+  namedOutright,
   workspaceFilesReachInto,
   resolveInputs,
   resolveOutputs,
   resolveWorkspaceOutputs,
+  sweepRestoreTemps,
+  sweepStaging,
   asTrees,
   type ProjectFilesCache,
   type WorkspaceFilesCache,