@vzn/vx 0.0.126 → 0.0.128

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.126",
+  "version": "0.0.128",
   "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.126",
-    "@vzn/vx-linux-arm64": "0.0.126",
-    "@vzn/vx-darwin-x64": "0.0.126",
-    "@vzn/vx-darwin-arm64": "0.0.126"
+    "@vzn/vx-linux-x64": "0.0.128",
+    "@vzn/vx-linux-arm64": "0.0.128",
+    "@vzn/vx-darwin-x64": "0.0.128",
+    "@vzn/vx-darwin-arm64": "0.0.128"
   },
   "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/workspace/config-schema.ts

@@ -379,7 +379,9 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
       const persistent = (exec as { persistent?: unknown }).persistent
       if (persistent !== undefined) {
         if (typeof persistent !== 'object' || persistent === null) {
-          throw new UserError(`${where}.exec.persistent must be an object (or omitted)`)
+          throw new UserError(
+            `${where}.exec.persistent must be an object (or omitted) — \`persistent: {}\`, or \`{ readyWhen: '<regex>' }\` to wait for a line`,
+          )
         }
         // The one nested object that had no unknown-key check while every
         // sibling did — and the failure it let through is the quiet kind:
@@ -451,7 +453,9 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
     }
     if (cache !== undefined) {
       if (typeof cache !== 'object' || cache === null) {
-        throw new UserError(`${where}.cache must be an object when present`)
+        throw new UserError(
+          `${where}.cache must be an object when present — \`cache: { inputs: { files: [...] }, outputs: { files: [...] } }\`, or no \`cache\` for a task that never caches`,
+        )
       }
       assertKnownFields(cache, CACHE_FIELDS, `${where}.cache`)
       const inputs = (cache as { inputs?: unknown }).inputs
@@ -697,6 +701,29 @@ export const REMOVED_FIELDS: ReadonlyMap<
   ],
 ])
 
+/**
+ * Another runner's spelling of a field vx has under another name, by the
+ * level that meets it (D-37): a Turbo `outputs: [...]` or Nx `command` on
+ * a task was refused as an unknown field that named neither the field
+ * nor where vx keeps it.
+ */
+const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, string>>> = new Map([
+  [
+    TASK_FIELDS,
+    {
+      inputs: '`cache.inputs.files`',
+      outputs: '`cache.outputs.files`',
+      env: '`cache.inputs.env` (to key the task on a variable) or `exec.env` (to pass one)',
+      passThroughEnv: '`exec.env.passThrough`',
+      command: '`exec.command`',
+      cmd: '`exec.command`',
+      script: '`exec.command`',
+      persistent: '`exec.persistent: {}`',
+    },
+  ],
+  [EXEC_FIELDS, { cmd: '`command`', script: '`command`' }],
+])
+
 function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: string): void {
   // `typeof [] === 'object'`, so an array reaches here and its indices read
   // as fields: `outputs: ['dist/**']` (Turbo's spelling) was refused as
@@ -717,10 +744,15 @@ function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: s
       }
       // The nearest accepted spelling first: the list says what the level
       // takes, the hint says which one was meant.
+      const foreign = FOREIGN_FIELDS.get(allowed)?.[key]
       const near = nearest(key, allowed)
       throw new UserError(
         `${where} has unknown field "${key}" (allowed: ${[...allowed].sort().join(', ')})` +
-          (near === undefined ? '' : ` — did you mean ${near}?`),
+          (foreign !== undefined
+            ? ` — vx spells it ${foreign}`
+            : near === undefined
+              ? ''
+              : ` — did you mean ${near}?`),
       )
     }
   }

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: {