@vzn/vx 0.0.644 → 0.0.645

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vx contributors
+Copyright (c) 2026 VZN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -12,7 +12,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@vzn/vx"><img src="https://img.shields.io/npm/v/@vzn/vx?color=7cb518" alt="npm"></a>
-  <a href="https://github.com/vznjs/vx/actions/workflows/ci.yml"><img src="https://github.com/vznjs/vx/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/vznjs/vx/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush"><img src="https://github.com/vznjs/vx/actions/workflows/ci.yml/badge.svg?branch=main&event=push" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
   <a href="https://vznjs.github.io/vx/"><img src="https://img.shields.io/badge/docs-vznjs.github.io%2Fvx-c6f84e" alt="Documentation"></a>
 </p>
@@ -35,13 +35,12 @@ Windows: run vx inside WSL2.
 
 ## Quick start
 
-In a git repo with a `package.json` workspace:
+In a git repo:
 
 ```sh
-npm install -D @vzn/vx         # the scope matters: npm's `vx` is an unrelated package
-npx @vzn/vx init               # beside turbo.json or nx.json: migrates them; else a vx.config.ts per package
-npx @vzn/vx run build --all    # builds in dependency order and stores the results
-npx @vzn/vx run build --all    # nothing changed: every task up-to-date
+npx @vzn/vx init       # installs vx globally and in the repo; beside turbo.json or nx.json: migrates them; else a root vx.config.ts
+vx run build --all     # builds in dependency order and stores the results
+vx run build --all     # nothing changed: every task up-to-date
 ```
 
 Bun workspaces: `bun add -d @vzn/vx` and `bunx @vzn/vx` (npm refuses to run in
@@ -166,17 +165,17 @@ Every gap, and when another tool is the better pick:
 
 <!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
 
-| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx          | Turborepo | Nx         | Vite Task |
-| ---------------------------------------------------------- | ----------- | --------- | ---------- | --------- |
-| Nothing changed                                            | **856 ms**  | 855 ms    | 23.22 s    | 11.24 s   |
-| Nothing changed, outputs restored                          | **1.45 s**  | 1.50 s    | 21.64 s    | 11.21 s   |
-| Cold build                                                 | **7.73 s**  | 10.32 s   | 3 min 23 s | 9.44 s    |
-| Cold build: CPU the runner burns                           | **36.42 s** | 1 min 3 s | 5 min 35 s | 25.64 s   |
+| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx         | Turborepo | Nx         | Vite Task |
+| ---------------------------------------------------------- | ---------- | --------- | ---------- | --------- |
+| Nothing changed                                            | **757 ms** | 761 ms    | 22.63 s    | 12.26 s   |
+| Nothing changed, outputs restored                          | **1.27 s** | 1.76 s    | 22.16 s    | 11.66 s   |
+| Cold build                                                 | **6.13 s** | 8.87 s    | 3 min 20 s | 7.94 s    |
+| Cold build: CPU the runner burns                           | 30.06 s    | 1 min 8 s | 5 min 45 s | 23.91 s   |
 
 Time each tool adds over the ideal run; lower is better.
 
 Benchmark workload: a synthetic monorepo of 1,601 projects and 9,603 tasks in 30 dependency levels, five core libraries a quarter of the projects use; build 300 ms, test and typecheck 150 ms, lint 75 ms, publish 30 ms; real repos with uneven task times will differ.
-Run 2026-10-12 on linux x64, 4 cores: vx at commit 126d60a93, Turborepo 2.11.7, Nx 23.3.0, Vite Task (vite-plus) 1.1.0.
+Run 2026-10-20 on linux x64, 4 cores: vx at commit a88652b0b, Turborepo 2.11.9, Nx 23.3.0, Vite Task (vite-plus) 1.3.0.
 
 Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).
 
@@ -188,17 +187,10 @@ Same graph, commands and concurrency: [how it is measured](https://vznjs.github.
 vx. The schema may still change; 1.0's promise:
 [versioning-1.0.md](packages/vx/docs/design/versioning-1.0.md).
 
-## Contributing
+## Issues
 
-```sh
-git clone https://github.com/vznjs/vx && cd vx
-bun install
-bun packages/vx/src/bin.ts run ci --all     # lint, test, docs build: every package
-```
-
-Needs Bun ≥ 1.4. Every dev task is a vx task; no `package.json`
-scripts. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and
-[STATUS.md](packages/vx/docs/STATUS.md).
+vx is maintained by VZN and takes issues, not pull requests: report a
+bug or ask for a feature in [issues](https://github.com/vznjs/vx/issues).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.644",
+  "version": "0.0.645",
   "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.644",
-    "@vzn/vx-linux-arm64": "0.0.644",
-    "@vzn/vx-darwin-x64": "0.0.644",
-    "@vzn/vx-darwin-arm64": "0.0.644"
+    "@vzn/vx-linux-x64": "0.0.645",
+    "@vzn/vx-linux-arm64": "0.0.645",
+    "@vzn/vx-darwin-x64": "0.0.645",
+    "@vzn/vx-darwin-arm64": "0.0.645"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/init.json

@@ -52,6 +52,11 @@
     "next": {
       "type": ["string", "null"],
       "description": "the command to type after the real run; null where the plan names none"
+    },
+    "installs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "core's plan only: the install commands the real run runs (global, then the root devDependency)"
     }
   }
 }

package/src/cache/archive.ts

@@ -163,8 +163,6 @@ class SumCheck {
   add(bytes: Uint8Array): void {
     this.sum.add(bytes)
   }
-  /** The checked sum's text, once `verify` passed. */
-  checked = ''
   verify(got: string): void {
     if (got !== this.sum.hex()) {
       throw new TarFormatError(
@@ -172,7 +170,6 @@ class SumCheck {
       )
     }
     this.seen = true
-    this.checked = got
   }
   done(): void {
     if (!this.seen) throw new TarFormatError('artifact carries no checksum')
@@ -478,14 +475,11 @@ function streamOf(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
 /**
  * The tree form (`cache.store.decompress`, v47): an artifact's members
  * as plain files under one directory, `outputs/<rel>` and
- * `workspace-outputs/<rel>` as named in the tar, beside its sidecar and a
- * `.vx-sum` over them. stdout lives in the index. A restore copies (or
- * clones) each file out, so a hit decodes nothing; an upload packs the
- * tree back into the artifact a remote expects.
- */
-const TREE_SUM = SUM_ENTRY
-
-/**
+ * `workspace-outputs/<rel>` as named in the tar, beside its sidecar.
+ * stdout lives in the index. A restore copies (or clones) each file out,
+ * so a hit decodes nothing; an upload packs the tree back into the
+ * artifact a remote expects.
+ *
  * Write `plan`'s outputs into the empty `dir` as the tree form, each copied
  * by the kernel (`copy_file_range`, or a clone where the filesystem has one)
  * and given its sidecar mtime, and return what a scan of the plan's tar
@@ -515,24 +509,14 @@ export async function writeTree(plan: ArtifactPlan, dir: string): Promise<Artifa
     }),
   )
   await writeFile(path.join(dir, META_ENTRY), meta)
-  await writeFile(path.join(dir, TREE_SUM), await treeSum(dir, stdoutOf(plan)))
   return fold.result()
 }
 
-function stdoutOf(plan: ArtifactPlan): string {
-  return utf8.decode(plan.inputs.find((i) => i.name === STDOUT_ENTRY)!.body as Uint8Array)
-}
-
 /**
- * Write a scanned artifact's sidecar and sum into `dir`, whose outputs an
- * extract just wrote: an ingested remote hit kept as a tree.
+ * Write a scanned artifact's sidecar into `dir`, whose outputs an extract
+ * just wrote: an ingested remote hit kept as a tree.
  */
-export async function sealTree(
-  dir: string,
-  scan: ArtifactScan,
-  /** The archive's own sidecar text and checked sum (`extractArtifactStream`'s `onScan`). */
-  raw?: { meta: string; sum: string },
-): Promise<void> {
+export async function sealTree(dir: string, scan: ArtifactScan): Promise<void> {
   // An artifact with no outputs extracts nothing, so nothing made `dir`.
   await mkdir(dir, { recursive: true })
   const meta: MetaFile = { version: 1, files: {} }
@@ -543,20 +527,7 @@ export async function sealTree(
   if (scan.dirs.length > 0) meta.dirs = scan.dirs
   if (scan.links.length > 0) meta.links = Object.fromEntries(scan.links)
   if (scan.exec !== undefined) meta.exec = scan.exec
-  const text = JSON.stringify(meta)
-  await writeFile(path.join(dir, META_ENTRY), text)
-  // The tree packs back to the archive it came from when the sidecar is
-  // the same bytes and the entries came in its order (stdout first, the
-  // sidecar last): the sum the extract checked is then the tree's, and the
-  // tree is not read back to sum it.
-  const names = Object.keys(meta.files)
-  const same =
-    raw !== undefined &&
-    raw.meta === text &&
-    scan.entries[0]?.name === STDOUT_ENTRY &&
-    scan.entries.length === names.length + 1 &&
-    names.every((n, i) => scan.entries[i + 1]!.name === n)
-  await writeFile(path.join(dir, TREE_SUM), same ? raw.sum : await treeSum(dir, scan.stdout ?? ''))
+  await writeFile(path.join(dir, META_ENTRY), JSON.stringify(meta))
 }
 
 /** The plan that packs the tree in `dir` back into the artifact it holds. */
@@ -579,28 +550,6 @@ export function planOfTree(dir: string, stdout: string): ArtifactPlan {
   return { inputs, size: tarSize([...inputs, sumInput('0'.repeat(SUM_SIZE))]) }
 }
 
-/** The sum over the tree's members, as `SUM_ENTRY` defines it for the tar it packs to. */
-async function treeSum(dir: string, stdout: string): Promise<string> {
-  const sum = new EntrySum()
-  for (const i of planOfTree(dir, stdout).inputs) {
-    sum.entry(i.name)
-    if (i.body instanceof Blob && i.size > 1 << 20)
-      for await (const c of i.body.stream()) sum.add(c)
-    else if (i.body instanceof Blob) sum.add(await i.body.bytes())
-    else sum.add(i.body as Uint8Array)
-  }
-  return sum.hex()
-}
-
-/** Whether the tree's bytes still sum to what was stored (`cache.store.verify: 'hash'`). */
-export async function treeIntact(dir: string, stdout: string): Promise<boolean> {
-  try {
-    return (await treeSum(dir, stdout)) === readFileSync(path.join(dir, TREE_SUM), 'utf8')
-  } catch {
-    return false
-  }
-}
-
 /** What a scan of an artifact reads out of it. */
 interface ArtifactScan {
   entries: ArchiveEntry[]
@@ -794,12 +743,8 @@ export async function extractArtifactStream(
   accept?: (name: string) => boolean,
   /** The workspace root whose `.vx/tmp/` stages the entries; absent, each stages beside its target. */
   stageRoot?: string,
-  /**
-   * Handed what `scanArtifact` would read of the same bytes, once their sum
-   * has checked, with the sidecar's text and the sum when the sidecar came
-   * last: what `sealTree` may reuse rather than read the tree back.
-   */
-  onScan?: (scan: ArtifactScan, raw: { meta: string; sum: string } | undefined) => void,
+  /** Handed what `scanArtifact` would read of the same bytes, once their sum has checked. */
+  onScan?: (scan: ArtifactScan) => void,
 ): Promise<Set<string>> {
   // No `mkdir -p` of the destination here: `stage` creates each entry's
   // directory chain, the destination included, and the cache restores
@@ -813,20 +758,15 @@ export async function extractArtifactStream(
   let dirs: string[] = []
   let links: Array<[string, string]> = []
   const fold = onScan === undefined ? undefined : new ScanFold()
-  let metaText: string | undefined
-  let metaLast = false
   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
-      metaLast = false
       if (e.name === META_ENTRY) {
         const text = await textOf(body)
         fold?.sidecar(text)
-        metaText = text
-        metaLast = true
         const parsed = JSON.parse(text) as MetaFile
         meta = parsed.files ?? {}
         dirs = dirsOf(parsed)
@@ -855,11 +795,7 @@ export async function extractArtifactStream(
       await x.stage(e.name, dest.base, target, e.size <= SMALL_ENTRY ? await bytesOf(body) : body)
     }
     check.done()
-    if (fold !== undefined)
-      onScan!(
-        fold.result(),
-        metaLast && metaText !== undefined ? { meta: metaText, sum: check.checked } : undefined,
-      )
+    if (fold !== undefined) onScan!(fold.result())
     for (const name of dirs) {
       if (accept !== undefined && !accept(name)) {
         throw new ArchiveSecurityError(

package/src/cache/cache.ts

@@ -78,7 +78,6 @@ import {
   planArtifact,
   planOfTree,
   sealTree,
-  treeIntact,
   writeTree,
 } from './archive.js'
 import { readUmask, restoredMode } from './umask.js'
@@ -814,14 +813,11 @@ export interface StoreOptions {
   embeddings: number
   /** A file-backed entry is a `<hash>.tree` of plain files; off, one `<hash>.tar.zst`. */
   decompress: boolean
-  /** What a tree restore checks first: each file's size and mtime, every byte, or nothing. */
-  verify: 'stat' | 'hash' | 'none'
 }
 
 export const DEFAULT_STORE: StoreOptions = {
   embeddings: 32 * 1024,
   decompress: true,
-  verify: 'stat',
 }
 
 /** What a run's background uploads moved: totals over the ones that landed. */
@@ -859,6 +855,8 @@ export class Cache implements CacheLayer {
    * so the run can report them without a method on the layer seam.
    */
   readonly uploads: UploadTally = { count: 0, bytes: 0, ms: 0, failed: 0 }
+  /** The run's hits pulled from those remotes, and their bytes on the wire. */
+  readonly downloads: { count: number; bytes: number } = { count: 0, bytes: 0 }
   /** The same remotes' traffic per key, filled by the same `LayeredCache`. */
   readonly traffic: RemoteTraffic = { inFlight: 0, keys: new Map() }
 
@@ -1924,9 +1922,8 @@ export class Cache implements CacheLayer {
   }
 
   /**
-   * Restore a tree-form entry: its files checked as `cache.store.verify`
-   * says, then copied (or cloned) out one by one where the outputs are
-   * absent, as on every restore after a clean. Anything else (a tree to
+   * Restore a tree-form entry: its files copied (or cloned) out one by
+   * one where the outputs are absent, as on every restore after a clean. Anything else (a tree to
    * restore into, a workspace output, a link) goes through the extractor
    * the tar form uses, fed the tree packed back into its tar.
    */
@@ -1948,21 +1945,6 @@ export class Cache implements CacheLayer {
         `its outputs hold ${formatBytes(bytes)}, past the ${formatBytes(this.artifactCeiling)} artifact ceiling`,
       )
     }
-    if (this.store.verify === 'stat') {
-      const changed = await Promise.all(
-        files.map((r) =>
-          stat(path.join(tree, treeName(r.path))).then(
-            (st) => st.size !== r.size || Math.floor(st.mtimeMs) !== r.mtimeMs,
-            () => true,
-          ),
-        ),
-      )
-      if (changed.includes(true)) {
-        throw new CorruptArtifactError(hash, 'a stored file changed since it was saved')
-      }
-    } else if (this.store.verify === 'hash' && !(await treeIntact(tree, this.stdoutText(hash)))) {
-      throw new CorruptArtifactError(hash, 'the stored files no longer sum to what was saved')
-    }
     if (await this.copyTree(tree, rows, files, projectDir, accept)) return
     await extractArtifactStream(
       packArtifactStream(planOfTree(tree, this.stdoutText(hash))),
@@ -2699,7 +2681,6 @@ export class Cache implements CacheLayer {
         const dir = this.tempTreePath(hash)
         tree = dir
         let scan: Awaited<ReturnType<typeof scanArtifact>> | undefined
-        let raw: { meta: string; sum: string } | undefined
         await extractArtifactStream(
           await decodedTar(
             compressed instanceof Uint8Array ? compressed : Bun.file(tmpPath!),
@@ -2711,13 +2692,12 @@ export class Cache implements CacheLayer {
           undefined,
           undefined,
           undefined,
-          (s, r) => {
+          (s) => {
             scan = s
-            raw = r
           },
         )
         scanned = scan!
-        await sealTree(dir, scanned, raw)
+        await sealTree(dir, scanned)
       } else if (tar !== undefined) {
         // Our own tar, in memory: read in place, on this thread.
         scanned = scanTarBytes(tar)

package/src/cache/index.ts

@@ -82,14 +82,13 @@ export {
   type BlobSizeMemo,
 } from './git-inputs.js'
 export {
+  type ArtifactInfo,
   LayeredCache,
   type RemoteCacheLayer,
-  type RemoteKey,
   type RemoteOpenContext,
 } from './layered-cache.js'
 export { networkConcurrency } from './remote-lane.js'
 export type { ResolvedRemote } from './remote-lane.js'
-export { BranchScope } from './scoped-cache.js'
 export {
   absentPluginCache,
   pluginCache,

package/src/cache/layer.ts

@@ -5,6 +5,7 @@
 // reference to `Cache` below is a type (the local handle a layer may wrap).
 
 import type { Cache } from './cache.js'
+import type { ArtifactInfo } from './layered-cache.js'
 import { fsClockLag, stampGrainMs } from './fs-clock.js'
 
 export interface CacheKeyInput {
@@ -550,12 +551,12 @@ export interface CacheLayer {
    */
   readonly hasRemote?: boolean
   /**
-   * Batch existence probe over the remote — the subset of `hashes` stored
-   * remotely, in ONE round-trip, or `null` for "no batch info; use
-   * per-hash". Only meaningful with `hasRemote`; a remote layer that can't
+   * Batch existence probe over the remote — the `hashes` stored remotely
+   * and what the first remote holding each knows of it (`ArtifactInfo`), in
+   * ONE round-trip, or `null` for "no batch info; use per-hash". Only meaningful with `hasRemote`; a remote layer that can't
    * batch omits it and the prefetch pass falls back to per-hash GETs.
    */
-  remoteHasMany?(hashes: readonly string[]): Promise<Set<string> | null>
+  remoteHasMany?(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null>
   /**
    * The subset of `hashes` the local store already holds. The prefetch
    * pass probes the remote only for the rest, so a run the local cache
@@ -581,8 +582,6 @@ export interface CacheLayer {
    * about to call absent. Only meaningful with `hasRemote`.
    */
   probeFirst?(started: Promise<void>): void
-  /** `taskId`'s key is `hash`: a scoped run picks each remote key by its task (`BranchScope`). */
-  noteKey?(taskId: string, hash: string): void
   /**
    * Resolve once every background write-through upload settles. The
    * orchestrator awaits it before `close()` — an upload reading layer state