@vzn/vx 0.0.639 → 0.0.640

package/docs/security.md

@@ -217,7 +217,7 @@ executor's error, telemetry,
 `vx show` (L-26). Values in the run history are digests under a per-store
 salt, and what follows `--` on the command line reaches telemetry as a
 count, not a quote, a secret before it masked (L-44). A remote executor (`@vzn/vx-reapi`) receives a
-task's `exec.env.define` values and the `cache.inputs.env` values its
+task's `exec.env.define` values and the `inputs.env` values its
 local child gets, never `passThrough`; those values sit unmasked in the
 action's Command, which the remote stores in its CAS, as Bazel's
 `--action_env` does, so a secret a remote task needs is trusted to that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.639",
+  "version": "0.0.640",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.639",
-    "@vzn/vx-linux-arm64": "0.0.639",
-    "@vzn/vx-darwin-x64": "0.0.639",
-    "@vzn/vx-darwin-arm64": "0.0.639"
+    "@vzn/vx-linux-x64": "0.0.640",
+    "@vzn/vx-linux-arm64": "0.0.640",
+    "@vzn/vx-darwin-x64": "0.0.640",
+    "@vzn/vx-darwin-arm64": "0.0.640"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/show.json

@@ -90,24 +90,24 @@
             }
           }
         },
+        "inputs": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["files"],
+          "properties": {
+            "files": { "$ref": "#/$defs/stringList" },
+            "workspaceFiles": { "$ref": "#/$defs/stringList" },
+            "env": { "$ref": "#/$defs/stringList" },
+            "tasks": { "$ref": "#/$defs/stringList" },
+            "runtime": { "$ref": "#/$defs/stringList" },
+            "workspaceRuntime": { "$ref": "#/$defs/stringList" }
+          }
+        },
         "cache": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["inputs", "outputs"],
+          "required": ["outputs"],
           "properties": {
-            "inputs": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["files"],
-              "properties": {
-                "files": { "$ref": "#/$defs/stringList" },
-                "workspaceFiles": { "$ref": "#/$defs/stringList" },
-                "env": { "$ref": "#/$defs/stringList" },
-                "tasks": { "$ref": "#/$defs/stringList" },
-                "runtime": { "$ref": "#/$defs/stringList" },
-                "workspaceRuntime": { "$ref": "#/$defs/stringList" }
-              }
-            },
             "outputs": {
               "type": "object",
               "additionalProperties": false,

package/skills/vx/SKILL.md

@@ -90,9 +90,10 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 - Never delete or edit the cache by hand; vx repairs it itself.
 - A sandboxed task that fails on a denied path: grant that one path in
   `exec.sandbox.allow`. Never remove `sandbox` or widen it further.
-- A cached task declares its inputs (`cache.inputs.files`); if a change
-  does not re-run a task, the file is not one of its inputs. Fix the
-  config, do not force.
+- A task declares its inputs (`inputs.files`), cached or not; if a
+  change does not re-run a task, the file is not one of its inputs. Fix
+  the config, do not force. A task with no `inputs` has no key, so every
+  cached task behind it misses: give it `inputs`.
 - Every JSON shape is a JSON Schema in `node_modules/@vzn/vx/schemas/`.
 - Offline reference: `vx docs <words> --format json` searches the CLI, config
   and cache pages that ship with vx; the sections holding every word print

package/src/cache/cache.ts

@@ -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),
     )
   }
 

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

@@ -34,6 +34,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,6 +43,7 @@ export {
   committedFiles,
   cleanWorkspaceOutputs,
   declaresInput,
+  namedOutright,
   workspaceFilesReachInto,
   resolveInputs,
   resolveOutputs,