Design notes

These are forward-looking proposals and historical design notes — the record of what was explored, what shipped, and why. They are not part of the stable contract. Newest first.

November 2026

Console UI — design: vx’s output was written line by line from many places: verbs, the run screen, plugins. Each picked its own words, colours and layout, so the same fact…

October 2026

Cache integrity: the cache server’s job (2026-10): Cache integrity is the cache server’s job. It works like npm trusted publishing:
Cache save CPU — design: Cold run, 1,090 packages / 2,180 tasks, 1,090 saves of a tiny dist/: vx’s own CPU is ~8.6 s, and the save costs ~3.8 s of it (no save: 8.7 → 4.7 s). Vite…
Distributed task execution (@vzn/vx-dte), 2026-10: One run spread over workers that the user’s own CI spawns. The workers reach it through a relay that anyone can host. This page lists every decision VZN has…
Language-agnostic core (2026-10): Core knows JS packages in five ways: it finds projects through package manager member globs, names them by package.json#name, derives ^task edges and…
Task timings through the remote cache (2026-10): @vzn/vx-history orders by learned durations. A fresh CI runner or a new clone has none, so its first run orders blind. file (timings-file.ts) carries them,…
The key fuzzer: a differential probe for stale hits (2026-10-02): The workspace’s tasks print what they read: each listed src file’s name, mode bit and bytes or link target, a constant from an imported conf.mjs, a cached…
The shared store (2026-10-06): Owner ask (2026-10-05): “global cache in home folder like Nx in order to share cache across workspaces”.
The vx cache server (@vzn/vx-cache-server), 2026-10: A server anyone hosts that keeps vx’s artifacts, so a fresh CI runner or a new branch starts warm. It is optional: a workspace that declares no plugin for…

September 2026

A sandboxed task reads a linked sibling unseen (2026-09-24): sandboxRequestFor grants every nodemodules link from the project and from the workspace root (linkedDeps). It reports denials only inside the project…
A streaming remote cache seam (2026-09-23, roadmap 2.2): The remote cache seam is the last place a whole artifact must sit in memory. RemoteCacheLayer.get resolves { body: ArrayBuffer } and put takes ArrayBuffer |…
Adoption tooling leaves core (2026-09-10): Core reads no other runner’s format. vx init (package.json scripts) stays; Turbo and Nx migrations are @vzn/vx-migrate, a package with its own bin; the…
An Nx repo under vx with nothing written (2026-09-22): turbo() already runs a Turbo repo unchanged: a project-stage plugin maps turbo.json to tasks at config time. Nx has the same seam available and one extra…
Parity ledger audit (2026-09-23, item 659, roadmap 2.3): The two parity ledgers, turbo-nx-parity-2026-07.md and turbo-nx-test-gaps.md, listed behaviours vx did not pin, and neither said which were ever closed.…
Plugin-named projects: a discover stage (2026-09-28, stream D): Core finds projects one way: the package manager’s member globs (and, since D-39, a root vx.config). An integrated Nx repo does not list its projects there.…
Resource reservations learned from history (2026-09): exec.resources was the one config field a developer could not write well. The number a task needs is a property of its inputs and the machine, it changes…
Survey of the Turbo and Nx test suites (2026-09-10): The owner’s ask: “go through all tests of nx and turbo, see if we miss any test or any core functionality, e.g. prevention of circular task deps.” Two…
The mutation sweep: method and rules (2026-09-18 → 09-21): Status: the record of a finished campaign. Items 342–572 swept core one source file or region at a time; item 572’s verdict is that the candidate list is…
The pipeline — plugin API v2 (2026-09): The owner’s direction (2026-09-02): vx is the Vite of task orchestration. Core is a pipeline; plugins decide what happens at each stage. Today core has…
The site teaches (2026-09-23, roadmap track W): The owner asked for this on 2026-09-23: redo the site so it teaches what task orchestration is, with interactive examples and diagrams, and shows where vx…
The site, redone as one story (2026-09-24, owner): The owner’s verdict on the site after track W: “Website is very bad. I told you to redo it, not add sections. It should tell a coherent story and teach…
The site, short (2026-09-24): The owner, after the Guide shipped: “The website is still terrible. It should be short but visualizing. Maybe one diagram that has all the examples. And we…
Two cached tasks, one output path (2026-09-20): Two cached tasks, B depends on A, and both declare the same directory as their output. Nx caches both; vx leaves the dependent one uncached, and…
Workspace-root tasks (2026-09-28, stream D): The two runners vx adopts both have tasks that live at the workspace root: Turbo’s root tasks (//#lint in turbo.json, run from the root package.json…

August 2026

Download policy + deferred outputs (2026-08): With remote execution (@vzn/vx-reapi phase 2, shipped), a task runs on a worker and materialiseOutputs downloads every output to the submitter’s disk. For a…
Per-task executor seam + @vzn/vx-reapi (2026-08): Owner decision, 2026-08-22: vx-cloud is too complex to set up and work with. Core becomes the thing anyone can build a “vx cloud” on top of, through plugins…

July 2026

Per-task logs + artifacts in the dashboard — design: Nx Cloud’s table-stakes triage flow: a CI run fails → click the failed task on the run-detail page → read its terminal output in the browser. vx has the…
vx parity with Turbo and Nx: behavioural contracts vx does not pin (2026-07): Two independent research passes, run 2026-07-28 against the current upstream trees, cataloguing behaviour those runners’ own suites pin that vx has no…

June 2026

Config lock — vx lock / .vx/lock.json (2026-06): vx configs are programs (vx.config.ts is evaluated, not parsed). That is the source of vx’s “resolved-config hashing” power — imports and computed values…
Module isolation — design: src/ already has directory-shaped concerns (workspace/, graph/, cache/, exec/, orchestrator/, cli/, util/), but nothing enforces them: 30+ cross-directory…
Observability + integration architecture — design: The core/cloud split gave us a typed VxPlugin and an eventSink capability, but three gaps remain against the owner’s directive:
Run event stream + devframe surfaces: Status: proposal (2026-06-17). Owner-driven: “drive our current terminal output through devframe; use a separate thread so rendering never blocks the…
Runtime inputs — design (2026-06): A task’s cache key today is derived from declared files, env-var values, upstream hashes, the resolved config, and the project package.json. There is no way…

Undated

Roadmap to 1.0 (2026-09-23): The question this answers: when is vx feature complete, and what is left before a 1.0? Before this page the repo had no definition of either. The only…
Versioning and support (2026-09-23, roadmap 3.1–3.4): This page says what a vx release may change, and what it may not. It takes effect at 1.0. Until then, releases are 0.x and a minor may break anything, but…
vx test gaps against Turbo and Nx: Generated: 2026-05-17. Source enumeration of ~205 Turbo tests (Rust unit + Cucumber-style .t integration fixtures across turborepo-task-hash,…

Turborepo, Nx and other product names are trademarks of their owners. vx is not affiliated with or endorsed by them.