@vzn/vx 0.0.127 → 0.0.129

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.127",
+  "version": "0.0.129",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.127",
-    "@vzn/vx-linux-arm64": "0.0.127",
-    "@vzn/vx-darwin-x64": "0.0.127",
-    "@vzn/vx-darwin-arm64": "0.0.127"
+    "@vzn/vx-linux-x64": "0.0.129",
+    "@vzn/vx-linux-arm64": "0.0.129",
+    "@vzn/vx-darwin-x64": "0.0.129",
+    "@vzn/vx-darwin-arm64": "0.0.129"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/archive.ts

@@ -49,6 +49,79 @@ const META_ENTRY = '.vx-meta.json'
 /** Archive entry name of the always-present stdout record. */
 const STDOUT_ENTRY = 'stdout'
 
+/**
+ * The last entry: a CRC-32 over every entry before it, each its name, a
+ * NUL, then its body, as 8 lowercase hex digits (v36, L-19). Nothing else
+ * checks an entry's BODY: tar sums its headers only, and neither zstd
+ * writer asks for a frame checksum, so a byte flipped in a raw zstd block
+ * (incompressible output: an image, a wasm, a tarball) decoded clean and
+ * replayed wrong bytes under a green hit — 1,141 of 1,141 flips in a
+ * random 8 KB body went unseen (probed). A CRC catches that transit or
+ * storage damage; it is no defense against a store that forges artifacts,
+ * which keys cannot tell apart from honest ones either.
+ */
+const SUM_ENTRY = '.vx-sum'
+const SUM_SIZE = 8
+
+/** The running CRC-32 over entries' names and bodies, as `SUM_ENTRY` defines it. */
+class EntrySum {
+  private crc = 0
+  entry(name: string): void {
+    this.crc = Bun.hash.crc32(new TextEncoder().encode(`${name}\0`), this.crc)
+  }
+  add(chunk: Uint8Array): void {
+    this.crc = Bun.hash.crc32(chunk, this.crc)
+  }
+  async *through(body: AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array> {
+    for await (const chunk of body) {
+      this.add(chunk)
+      yield chunk
+    }
+  }
+  hex(): string {
+    return (this.crc >>> 0).toString(16).padStart(SUM_SIZE, '0')
+  }
+}
+
+/**
+ * The reader's half: every regular entry is hashed as it is consumed, and
+ * `check` is handed the sum entry's body. An archive whose sum is absent,
+ * wrong, or followed by another entry is refused before anything it held
+ * is committed.
+ */
+class SumCheck {
+  private readonly sum = new EntrySum()
+  private seen: boolean = false
+  /** The entry's body, hashed as the caller reads it; null for the sum entry itself (checked here). */
+  async body(
+    name: string,
+    body: AsyncIterable<Uint8Array>,
+  ): Promise<AsyncIterable<Uint8Array> | null> {
+    if (this.seen) throw new TarFormatError(`entry ${name} follows the artifact's checksum`)
+    if (name === SUM_ENTRY) {
+      const got = await textOf(body)
+      if (got !== this.sum.hex()) {
+        throw new TarFormatError(
+          `artifact content does not match its checksum (${got}, read ${this.sum.hex()})`,
+        )
+      }
+      this.seen = true
+      return null
+    }
+    this.sum.entry(name)
+    return this.sum.through(body)
+  }
+  done(): void {
+    if (!this.seen) throw new TarFormatError('artifact carries no checksum')
+  }
+}
+
+const drain = async (body: AsyncIterable<Uint8Array>): Promise<void> => {
+  for await (const _ of body) {
+    // read through the checksum
+  }
+}
+
 const WIN32 = process.platform === 'win32'
 // A Windows link target may be spelled with either separator.
 const LINK_SEP = WIN32 ? /[\\/]/ : '/'
@@ -190,12 +263,36 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
     })),
     { name: META_ENTRY, size: metaBytes.byteLength, body: metaBytes },
   ]
-  return { inputs, size: tarSize(inputs) }
+  return { inputs, size: tarSize([...inputs, sumInput('0'.repeat(SUM_SIZE))]) }
 }
 
 /** The tar as a stream: each output is read from disk as it is written. */
 export function packArtifactStream(plan: ArtifactPlan): ReadableStream<Uint8Array> {
-  return streamOf(tarPack(plan.inputs))
+  return streamOf(tarPack(summed(plan.inputs)))
+}
+
+const sumInput = (hex: string): TarInput => ({ name: SUM_ENTRY, size: SUM_SIZE, body: hex })
+
+/**
+ * The inputs with each body hashed as `tarPack` reads it, then the sum
+ * entry: `tarPack` drains one input before it asks for the next, so the
+ * sum is whole when it is asked for.
+ */
+async function* summed(inputs: readonly TarInput[]): AsyncGenerator<TarInput> {
+  const sum = new EntrySum()
+  for (const i of inputs) {
+    sum.entry(i.name)
+    if (i.body instanceof Blob) {
+      yield { ...i, body: sum.through(i.body.stream()) }
+    } else if (typeof i.body === 'string' || i.body instanceof Uint8Array) {
+      const bytes = typeof i.body === 'string' ? new TextEncoder().encode(i.body) : i.body
+      sum.add(bytes)
+      yield { ...i, body: bytes }
+    } else {
+      yield { ...i, body: sum.through(i.body) }
+    }
+  }
+  yield sumInput(sum.hex())
 }
 
 /**
@@ -212,7 +309,7 @@ export async function packArtifactBytes(plan: ArtifactPlan): Promise<Uint8Array>
   )
   const out = new Uint8Array(plan.size)
   let off = 0
-  for await (const chunk of tarPack(inputs)) {
+  for await (const chunk of tarPack(summed(inputs))) {
     out.set(chunk, off)
     off += chunk.byteLength
   }
@@ -256,10 +353,13 @@ export async function scanArtifact(tar: ReadableStream<Uint8Array>): Promise<{
   let exec: ExecUsage | undefined
   let key: string | undefined
   let stdout: string | null = null
+  const check = new SumCheck()
   for await (const e of tarEntries(tar)) {
     if (e.type !== '0') continue
+    const body = await check.body(e.name, e.body)
+    if (body === null) continue
     if (e.name === META_ENTRY) {
-      const parsed = JSON.parse(await textOf(e.body)) as MetaFile
+      const parsed = JSON.parse(await textOf(body)) as MetaFile
       meta = parsed.files ?? {}
       // The ingest side is the untrusted boundary: a foreign sidecar's
       // usage is taken only when it is a plain non-negative number.
@@ -268,9 +368,11 @@ export async function scanArtifact(tar: ReadableStream<Uint8Array>): Promise<{
       continue
     }
     assertSafeName(e.name)
-    if (e.name === STDOUT_ENTRY) stdout = await textOf(e.body)
+    if (e.name === STDOUT_ENTRY) stdout = await textOf(body)
+    else await drain(body)
     seen.push({ name: e.name, size: e.size, mtimeMs: e.mtimeMs })
   }
+  check.done()
   return {
     entries: seen.map((s) => {
       const m = meta[s.name]
@@ -322,26 +424,28 @@ export async function extractArtifactStream(
   const headerMtime = new Map<string, number>()
   let meta: MetaFile['files'] = {}
   try {
+    const check = new SumCheck()
     for await (const e of tarEntries(tar)) {
       if (e.type !== '0') continue
+      const body = await check.body(e.name, e.body)
+      if (body === null) continue
       if (e.name === META_ENTRY) {
-        meta = (JSON.parse(await textOf(e.body)) as MetaFile).files ?? {}
+        meta = (JSON.parse(await textOf(body)) as MetaFile).files ?? {}
         continue
       }
       assertSafeName(e.name)
       const dest = x.destFor(e.name)
-      if (dest === null || dest.rel.length === 0) continue
+      if (dest === null || dest.rel.length === 0) {
+        await drain(body)
+        continue
+      }
       const target = path.join(dest.base, dest.rel)
       await x.assertContained(dest.base, target, e.name)
       provided.add(e.name)
       headerMtime.set(e.name, e.mtimeMs)
-      await x.stage(
-        e.name,
-        dest.base,
-        target,
-        e.size <= SMALL_ENTRY ? await bytesOf(e.body) : e.body,
-      )
+      await x.stage(e.name, dest.base, target, e.size <= SMALL_ENTRY ? await bytesOf(body) : body)
     }
+    check.done()
     verify?.(provided)
     // The sidecar's stat is the truth, a mode of 000 and an mtime at or
     // before the epoch included (`SOURCE_DATE_EPOCH=0`). Without one, a

package/src/cache/key-fold.ts

@@ -87,7 +87,7 @@ import type { CacheKeyInput } from './layer.js'
 // never folded and saved what it built. The fix withholds that link unless
 // the key answers for the package, but an entry saved before it still hits
 // after the sibling changes (probed: the old output replayed).
-export const CACHE_VERSION = 'vx-cache-v35'
+export const CACHE_VERSION = 'vx-cache-v36'
 
 /**
  * Fold one task's key inputs into its 16-hex cache key. `hashFile` answers

package/src/cache/tar-stream.ts

@@ -246,7 +246,8 @@ export interface TarInput {
   mode?: number
   /** Seconds since epoch; the sidecar carries the millisecond value. */
   mtime?: number
-  body: Blob | Uint8Array | string
+  /** An iterable is read once, in order, as the entry is written (`size` is its length). */
+  body: Blob | Uint8Array | string | AsyncIterable<Uint8Array>
 }
 
 const encoder = new TextEncoder()
@@ -326,6 +327,9 @@ function needsPax(name: string): boolean {
   return bytes.byteLength > 100 && splitForUstar(bytes) === null
 }
 
+const isChunks = (b: TarInput['body']): b is AsyncIterable<Uint8Array> =>
+  typeof b === 'object' && Symbol.asyncIterator in b
+
 /** The exact number of bytes `tarPack` writes for these inputs. */
 export function tarSize(inputs: readonly TarInput[]): number {
   let size = BLOCK * 2
@@ -360,9 +364,10 @@ export async function* tarPack(
       headerName = encoder.encode(input.name).subarray(0, 100)
     }
     yield header(headerName, input.size, '0', mode, mtime)
-    if (input.body instanceof Blob) {
+    if (input.body instanceof Blob || isChunks(input.body)) {
       let n = 0
-      for await (const chunk of input.body.stream()) {
+      const chunks = input.body instanceof Blob ? input.body.stream() : input.body
+      for await (const chunk of chunks) {
         n += chunk.byteLength
         yield chunk
       }

package/src/util/index.ts

@@ -51,4 +51,5 @@ export { CORE_VERBS, MOVED_VERBS } from './verbs.js'
 export { isUnsupportedBun, MIN_BUN, unsupportedBunMessage } from './bun-version.js'
 export { executablePath, shellArgv } from './which.js'
 export { procfsIsOwn } from './procfs.js'
+export { realPath } from './real-path.js'
 export { maskedCommand, maskedEmitter, MASKED, secretMask, type SecretMask } from './secret-mask.js'

package/src/util/real-path.ts

@@ -0,0 +1,12 @@
+import { realpathSync } from 'node:fs'
+
+/**
+ * A path's canonical spelling. On Windows `realpathSync` keeps an 8.3
+ * short name (`C:\Users\RUNNER~1\…`) where git, `fs.promises.realpath`
+ * and every other reader say `runneradmin`, so one file had two
+ * spellings and a key or a comparison that folds the path split on
+ * them (O-16). The native call asks the OS for the final path.
+ */
+export function realPath(p: string): string {
+  return realpathSync.native(p)
+}

package/src/workspace/config-cache.ts

@@ -28,9 +28,9 @@
 // `vx lock` both go through `JSON.stringify` — so a cached config derives
 // the same cache key as a live evaluation of the same bytes.
 
-import { lstatSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { lstatSync, readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
-import { xxh3 } from '../util/index.js'
+import { realPath, xxh3 } from '../util/index.js'
 import { VERSION } from '../version.js'
 
 /** Bump when the key derivation or the stored shape changes. */
@@ -395,8 +395,8 @@ const EXPLICIT_EXT = /\.(?:m?[jt]s|cjs|cts)$/
  * per run (`read-once.unsafe.test.ts`).
  */
 function realDirOf(file: string): string {
-  if (lstatSync(file).isSymbolicLink()) return path.dirname(realpathSync(file))
-  return realpathSync(path.dirname(file))
+  if (lstatSync(file).isSymbolicLink()) return path.dirname(realPath(file))
+  return realPath(path.dirname(file))
 }
 
 /** Each workspace root's real path, asked once per process. */
@@ -418,7 +418,7 @@ function reachedThroughNoLink(file: string, realDir: string, root: string | unde
   if (root === undefined) return true
   let realRoot = realRoots.get(root)
   if (realRoot === undefined) {
-    realRoot = realpathSync(root)
+    realRoot = realPath(root)
     realRoots.set(root, realRoot)
   }
   return path.relative(realRoot, realDir) === path.relative(root, dir)
@@ -427,7 +427,7 @@ function reachedThroughNoLink(file: string, realDir: string, root: string | unde
 /** A regular file reached through no symlink: the path IS the file. */
 function isCanonicalFile(file: string): boolean {
   try {
-    return realpathSync(file) === file && statSync(file).isFile()
+    return realPath(file) === file && statSync(file).isFile()
   } catch {
     return false
   }
@@ -500,7 +500,7 @@ export async function configEvalKey(a: ConfigEvalKeyArgs): Promise<ConfigEvalKey
           // workspace under /var vs /private/var), and the key folds the
           // path — a spelling that drifts between runs is a spurious miss
           // and a duplicated memo row.
-          resolved = realpathSync(Bun.resolveSync(spec, dir))
+          resolved = realPath(Bun.resolveSync(spec, dir))
         } catch {
           return null
         }
@@ -574,7 +574,7 @@ export async function configImports(configPath: string): Promise<string[]> {
       let resolved: string
       try {
         dir ??= realDirOf(file)
-        resolved = realpathSync(Bun.resolveSync(spec, dir))
+        resolved = realPath(Bun.resolveSync(spec, dir))
       } catch {
         continue
       }

package/src/workspace/migrate-scripts.ts

@@ -37,6 +37,7 @@ import {
   type MigrationPlan,
   PERSISTENT_TASK_NAMES,
   PERSISTENT_TODO,
+  CACHE_TODO,
 } from './migration.js'
 
 // `lint` is not here: a linter reads sources, and an edge to `build`
@@ -187,10 +188,6 @@ function scriptsOf(meta: ProjectMeta): Record<string, unknown> {
   return raw as Record<string, unknown>
 }
 
-/** The cache block the task that builds should declare, as a TODO on it. */
-const CACHE_TODO =
-  "cache: add `cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } }` with this package's real inputs and outputs — without it the task always runs and every file here, what it writes included, folds into the key its dependents fold; a block with EMPTY outputs would be a cached no-op, not an uncached task"
-
 /**
  * A `build` that only delegates (`build: pnpm run compile`) is a group over
  * its target, and the `^build` edge every `build` carries belongs on the
@@ -330,7 +327,10 @@ export function migrateScripts(metas: readonly ProjectMeta[]): MigrationPlan {
   }
   return {
     headerNotes: [
-      'each script became a task with its command verbatim; caching needs declared inputs and outputs, so no task got a cache block — `build`, or the script it delegates to, carries a TODO showing the one to add',
+      // Where to add one is the TODO's to say, when there is one: an Nx repo
+      // whose only script is `codegen` read "`build` carries a TODO" over
+      // "0 TODOs" (the first-five-minutes walk, 2026-09-28).
+      'each script became a task with its command verbatim; caching needs declared inputs and outputs, so no task got a cache block',
     ],
     projects,
     extraFiles: [],

package/src/workspace/migration.ts

@@ -67,6 +67,10 @@ export function foldScriptHooks(
   return `vx_script() {\n${parts.join(' && ')}\n}\nvx_script`
 }
 
+/** The cache block the task that builds should declare, as a TODO on it. */
+export const CACHE_TODO =
+  "cache: add `cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } }` with this package's real inputs and outputs — without it the task always runs and every file here, what it writes included, folds into the key its dependents fold; a block with EMPTY outputs would be a cached no-op, not an uncached task"
+
 /** The one wording every mapper emits for a task it made persistent. */
 export const PERSISTENT_TODO =
   'persistent task — set persistent.readyWhen (regex matched against output) so ' +
@@ -219,12 +223,23 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     for (const f of replaced) await unlink(f)
   }
 
-  const todoList: string[] = []
+  // One reason, its tasks: on a Turbo template the same two-line cache TODO
+  // printed five times and the persistent one eight (the first-five-minutes
+  // walk, 2026-09-28), and the list read as noise.
+  const todos = new Map<string, string[]>()
+  let todoCount = 0
   let clean = 0
+  let cached = false
   for (const p of plan.projects) {
     for (const t of p.tasks) {
       if (t.todos.length === 0 && t.task !== null) clean++
-      for (const reason of t.todos) todoList.push(`${p.name}#${t.name}: ${reason}`)
+      if (t.task !== null && 'cache' in t.task) cached = true
+      for (const reason of t.todos) {
+        todoCount++
+        const ids = todos.get(reason) ?? []
+        ids.push(`${p.name}#${t.name}`)
+        todos.set(reason, ids)
+      }
     }
   }
   const report: string[] = []
@@ -262,9 +277,16 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     report.push(
       '',
       `${clean} task${clean === 1 ? '' : 's'} migrated clean, ` +
-        `${todoList.length} TODO${todoList.length === 1 ? '' : 's'}${todoList.length > 0 ? ':' : ''}`,
+        `${todoCount} TODO${todoCount === 1 ? '' : 's'}${todoCount > 0 ? ':' : ''}`,
     )
-    for (const line of todoList) report.push(`  ${line}`)
+    for (const [reason, ids] of todos) {
+      if (ids.length === 1) report.push(`  ${ids[0]}: ${reason}`)
+      else {
+        const shown = ids.slice(0, TODO_IDS_SHOWN).join(', ')
+        const more = ids.length - TODO_IDS_SHOWN
+        report.push(`  ${shown}${more > 0 ? ` and ${more} more` : ''}:`, `    ${reason}`)
+      }
+    }
     report.push(...plan.notes)
     report.push(dry ? 'files (dry run, nothing written):' : 'files written:')
     for (const f of files) report.push(`  ${f.relPath}`)
@@ -277,11 +299,19 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     plan.projects.flatMap((p) => p.tasks.map((t) => t.name)).find((n) => n === 'build') ??
     plan.projects[0]?.tasks[0]?.name ??
     'build'
+  // A run of tasks none of which caches is never a hit, and a first try
+  // that runs twice to see the cache work saw it run twice.
+  if (!cached && todos.has(CACHE_TODO)) {
+    report.push('', 'no task caches yet: add the cache block a TODO shows, and a second run hits')
+  }
   report.push('', `next: vx run ${firstTask} --all`)
   process.stdout.write(`${report.join('\n')}\n`)
   return 0
 }
 
+/** Ids named per shared TODO; the files carry each one (sveltejs/kit: 92 persistent tasks). */
+const TODO_IDS_SHOWN = 5
+
 const EXAMPLE_BODY = `export default {
   tasks: {
     build: {