@vzn/vx 0.0.632 → 0.0.634

package/src/orchestrator/miss-reason.ts

@@ -4,11 +4,11 @@
 //
 // Paid only when a telemetry sink exists, and only on a miss: one scan of
 // `entries` for the newest entry per task, the first time a miss asks, then
-// one primary-key read of that entry's `entry_inputs` per miss.
+// one primary-key read of that entry's `entry_inputs` row per miss.
 
 import type { Database } from 'bun:sqlite'
 import type { InputChanges } from '../graph/index.js'
-import { diffKeyComponents } from './metrics.js'
+import { diffKeyComponents, loadEntryInputs } from './metrics.js'
 import type { TaskInputComponent } from './task-hash.js'
 
 /** How many changed components a miss names; `count` says how many there were. */
@@ -37,9 +37,7 @@ export function createMissExplainer(db: Database): MissExplainer {
       )
       const prev = newest.get(taskId)
       if (prev === undefined) return undefined
-      const before = db
-        .query('SELECT kind, name, hash FROM entry_inputs WHERE entry_hash = ?')
-        .all(prev) as TaskInputComponent[]
+      const before = loadEntryInputs(db, prev)
       // Pruned, or saved before fingerprints were kept: nothing to compare.
       if (before.length === 0) return undefined
       const { entries } = diffKeyComponents(before, components)

package/src/orchestrator/miss-save.ts

@@ -191,11 +191,12 @@ export async function saveMiss(a: SaveMissArgs): Promise<{ landed: Promise<SaveF
     endSave()
     if (a.measure === true) {
       facts.saveMs = Math.round(performance.now() - saveStart)
-      try {
-        facts.artifactBytes = statSync(cache.outputsPath(a.hash)).size
-      } catch {
-        // No local artifact (local writes off): no size to say.
-      }
+      // No local artifact (local writes off): no size to say.
+      const size =
+        cache.artifactSize !== undefined
+          ? cache.artifactSize(a.hash)
+          : statSync(cache.outputsPath(a.hash), { throwIfNoEntry: false })?.size
+      if (size !== undefined) facts.artifactBytes = size
     }
     // The files the task just wrote are the entry's bytes: stamp them,
     // so the next hit can tell them from another entry's with the same

package/src/orchestrator/projects.ts

@@ -328,8 +328,8 @@ export async function loadProjects(args: LoadProjectsArgs): Promise<LoadedProjec
  * one (owner, 2026-10-04): a group behind `^build`, keyed on every file of
  * the project. A package consumed as source then carries its files to every
  * dependent behind `^build`, in the key and in `--affected`, and the chain
- * through it to deeper builds holds. The one keyed group: a config cannot
- * declare `cache` on a group (config-schema.ts), so nothing else is.
+ * through it to deeper builds holds. A keyed group, as a config may
+ * declare one (config-schema.ts).
  */
 const DEFAULT_BUILD: TaskConfig = Object.freeze({
   dependsOn: Object.freeze(['^build']),

package/src/orchestrator/remote-prefetch.ts

@@ -113,11 +113,17 @@ async function runPrefetch(args: PrefetchArgs): Promise<void> {
  */
 export function getContext(node: TaskNode, command: string) {
   const outputs = node.config.cache?.outputs
+  let masked: string | undefined
   return {
     taskId: node.id,
     // Stored in the entry row a remote hit inserts: masked as a save's is,
-    // or the token a config inlined sat in cache.db (L-27).
-    command: maskedCommand(command, node.config.exec?.env),
+    // or the token a config inlined sat in cache.db (L-27). Masked on the
+    // first read: only an adopt or a remote hit reads it, and masking every
+    // lookup's command cost a cold 1,090-package run ~20 ms before its
+    // first task.
+    get command() {
+      return (masked ??= maskedCommand(command, node.config.exec?.env))
+    },
     outputs: { files: outputs?.files ?? [], workspaceFiles: outputs?.workspaceFiles ?? [] },
   }
 }

package/src/orchestrator/run.ts

@@ -945,7 +945,15 @@ async function runOnBus(
     // shouldShortCircuit (local reads on, no remote layer); when off, both
     // maps are empty and the run is byte-identical.
     let shortCircuit: ShortCircuit = emptyShortCircuit()
-    if (shouldShortCircuit(nodes, policy, cache)) {
+    // An empty local cache answers every probe with a miss: each task
+    // derives its key as it starts instead (~100 ms before a cold 1,090-
+    // package run's first spawn), and every sandboxed task runs.
+    const coldLocal =
+      cache === prepared.localCache &&
+      shouldShortCircuit(nodes, policy, cache) &&
+      prepared.localCache.holdsNothing()
+    if (coldLocal) prewarm()
+    else if (shouldShortCircuit(nodes, policy, cache)) {
       shortCircuit = await startLocalShortCircuit({
         nodes,
         cache,
@@ -1165,6 +1173,10 @@ async function runOnBus(
       // A `schedule` plugin's weights; the scheduler keeps its structural
       // baseline as the tie-break. Empty map → baseline only.
       ...(prepared.priorities.size > 0 ? { priorities: prepared.priorities } : {}),
+      // The baseline under them; `most-work` when the workspace names none.
+      ...(prepared.workspaceConfig?.schedule !== undefined
+        ? { strategy: prepared.workspaceConfig.schedule }
+        : {}),
       // Local short-circuit: confirmed stable local hits the scheduler
       // runs ahead of their deps as low-priority worker-slot backfill.
       // Empty when the short-circuit didn't fire → byte-identical.

package/src/orchestrator/task-hash.ts

@@ -411,8 +411,8 @@ function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
  * in place. Its one behavioural case is a config with NO `exec`, where
  * the spread would add `exec: {}` — and nothing reaches here that way,
  * proven by throwing on a no-exec config and running the whole suite:
- * a group takes `computeGroupKey`, and the one keyed group (the default
- * `build`) declares no `remote`. `timeout`/`retries` stay folded — their keys are
+ * a group takes `computeGroupKey`, and a keyed group has no `exec`, so no
+ * `remote`. `timeout`/`retries` stay folded — their keys are
  * distinct by design (see the decision log); stripping them retroactively
  * would bump CACHE_VERSION.
  */
@@ -423,8 +423,8 @@ function hashableConfig(cfg: TaskConfig): unknown {
 }
 
 /**
- * A group's key: its upstream, and for a keyed group — the default
- * `build` (projects.ts), the one group with `cache` — its own inputs too,
+ * A group's key: its upstream, and for a keyed group — one with `cache`,
+ * the default `build` (projects.ts) or a config's — its own inputs too,
  * the way a task's key folds them.
  */
 export async function computeGroupKey(args: ComputeHashArgs): Promise<string> {

package/src/util/errors.ts

@@ -62,9 +62,16 @@ export function wantsJson(argv: readonly string[]): boolean {
   return false
 }
 
-/** The JSON a verb that answers JSON prints for a refusal: one line. */
+/**
+ * The JSON a verb that answers JSON prints for a refusal: one line. A
+ * core code (`VX_E_…`) links its section of cli.md, which says the fix;
+ * `vx docs <code>` prints the same section offline. A plugin's code has none.
+ */
 export function errorDocument(code: string, message: string): string {
-  return `${JSON.stringify({ ok: false, error: { code, message } })}\n`
+  const docs = code.startsWith('VX_E_')
+    ? { docs: `https://vznjs.github.io/vx/cli/#${code.toLowerCase()}` }
+    : {}
+  return `${JSON.stringify({ ok: false, error: { code, message, ...docs } })}\n`
 }
 
 /**

package/src/util/paths.ts

@@ -195,6 +195,30 @@ export const EXTGLOB = /[!@+*?]\(/
  * else: one site that forgot is a route directory that keys nothing.
  */
 export function taskGlob(pattern: string): Bun.Glob {
+  const memo = memoFor(taskGlobs)
+  let glob = memo.get(pattern)
+  if (glob === undefined) memo.set(pattern, (glob = compileTaskGlob(pattern)))
+  return glob
+}
+
+/**
+ * Compiled once per pattern: a Turbo-mapped config repeats one 400-entry
+ * list across two thousand tasks, and the graph's overlap checks compiled
+ * each entry per task pair, 3.3 s of an astro plan (2026-10-09). A pattern
+ * comes from a config, so the set is bounded by what the configs say. Kept
+ * per `Bun.Glob` in force: the playground and a test swap it, and a glob
+ * built by one is not the other's.
+ */
+const taskGlobs = new WeakMap<object, Map<string, Bun.Glob>>()
+const anyTaskGlobs = new WeakMap<object, Map<string, (rel: string) => boolean>>()
+
+function memoFor<T>(memos: WeakMap<object, Map<string, T>>): Map<string, T> {
+  let memo = memos.get(Bun.Glob)
+  if (memo === undefined) memos.set(Bun.Glob, (memo = new Map()))
+  return memo
+}
+
+function compileTaskGlob(pattern: string): Bun.Glob {
   // A `]` with no `[` before it is already literal to `Bun.Glob`.
   const source = pattern.includes('[') ? pattern.replace(/(?<!\\)[[\]]/g, '\\$&') : pattern
   const glob = new Bun.Glob(source)
@@ -228,6 +252,14 @@ export function taskGlob(pattern: string): Bun.Glob {
  * `src/a.ts` and never `src/deep/a.ts`, and an edit there was a stale hit.
  */
 export function anyTaskGlob(rawPatterns: readonly string[]): (rel: string) => boolean {
+  const memo = memoFor(anyTaskGlobs)
+  const key = rawPatterns.join('\0')
+  let any = memo.get(key)
+  if (any === undefined) memo.set(key, (any = compileAnyTaskGlob(rawPatterns)))
+  return any
+}
+
+function compileAnyTaskGlob(rawPatterns: readonly string[]): (rel: string) => boolean {
   const patterns = rawPatterns.flatMap(braceAlternatives)
   if (patterns.length === 0) return () => false
   const sources = patterns.map(regExpSource)

package/src/util/verbs.ts

@@ -14,6 +14,7 @@ export const CORE_VERBS = [
   'info',
   'why',
   'last',
+  'docs',
   'completions',
   'help',
   'version',

package/src/workspace/config-schema.ts

@@ -56,9 +56,18 @@ const WORKSPACE_FIELDS = new Set([
   'affectedBase',
   'cacheScope',
   'rules',
+  'schedule',
   'plugins',
 ])
 
+type Schedule = NonNullable<WorkspaceConfig['schedule']>
+const SCHEDULES = {
+  'most-work': true,
+  'critical-path': true,
+  'direct-dependents': true,
+  'ready-order': true,
+} satisfies Record<Schedule, true>
+
 const RULE_FIELDS = new Set(['exclusiveOutputs', 'upfrontKeys'])
 
 function validateRules(rules: unknown, configPath: string): void {
@@ -184,6 +193,13 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
     throw new UserError(`${configPath}: \`cacheScope\` ${CACHE_SCOPE_RULE}`)
   }
   if (config.rules !== undefined) validateRules(config.rules, configPath)
+  if (config.schedule !== undefined && !Object.hasOwn(SCHEDULES, config.schedule)) {
+    throw new UserError(
+      `${configPath}: \`schedule\` must be one of ${Object.keys(SCHEDULES)
+        .map((k) => `'${k}'`)
+        .join(', ')}`,
+    )
+  }
   if (config.plugins !== undefined) {
     if (!Array.isArray(config.plugins)) {
       throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)
@@ -616,15 +632,12 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
       // so a dependant's `^build` finds it and waits on nothing
       // (the quickstart). The comment here used to call that case
       // "almost certainly a config mistake" while the docs taught it.
-      if (dependsOn === undefined) {
-        throw new UserError(
-          `${where}: a task with no \`exec\` must declare \`dependsOn\` ` +
-            `(group tasks exist to chain dependencies)`,
-        )
-      }
-      if (cache !== undefined) {
+      // A keyed group (`cache` with no `exec`) is a declaration on its own:
+      // its inputs are a key that dependants fold, with no process.
+      if (dependsOn === undefined && cache === undefined) {
         throw new UserError(
-          `${where}: \`cache\` requires \`exec\` — a group task has nothing to cache`,
+          `${where}: a task with no \`exec\` must declare \`dependsOn\` or \`cache.inputs\` ` +
+            `(group tasks exist to chain dependencies or carry a key)`,
         )
       }
     }
@@ -852,6 +865,11 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
       if (wsOutputs !== undefined) {
         validateWorkspaceGlobs(wsOutputs, `${where}.cache.outputs.workspaceFiles`, false)
       }
+      if (exec === undefined && (outFiles.length > 0 || wsOutputs !== undefined)) {
+        throw new UserError(
+          `${where}.cache.outputs: a task with no \`exec\` writes nothing — \`outputs: { files: [] }\``,
+        )
+      }
     }
   }
 }

package/src/workspace/lockfile.ts

@@ -36,6 +36,8 @@ export interface LockfileEntry {
 export interface Lockfile {
   version: number
   projects: Record<string, LockfileEntry>
+  /** Written by `writeLockfile` from the bytes; never read off the object. */
+  validated?: string
 }
 
 export function lockfilePath(root: string): string {
@@ -100,12 +102,33 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
     }
   }
   lockDigests.set(parsed, xxh3(text).toString(16))
+  const stamped = VALIDATED_LINE.exec(text)
+  if (stamped !== null && stamped[1] === validatedDigest(text.slice(0, stamped.index) + '\n}')) {
+    selfValidated.add(parsed)
+  }
   return parsed as Lockfile
 }
 
 /** The digest of the bytes each lock `readLockfile` returned was parsed from. */
 const lockDigests = new WeakMap<object, string>()
 
+/**
+ * The lock's own record that this vx validated its entries: `vx lock`
+ * evaluates and validates every config, then writes a digest of the bytes
+ * it wrote, under vx's version (validation's rules are vx's alone, so Bun's
+ * is left out and does not churn a committed lock), as the last field. A lock
+ * whose digest matches is validated already, and a cold `--frozen` run
+ * skips the ~30 ms of validating 1,090 entries before its first task. An
+ * edit, a merge, or another vx version leaves it unmatched, and the
+ * entries are validated as before.
+ */
+const VALIDATED_LINE = /,\n {2}"validated": "([0-9a-f]+)"\n\}\n?$/
+const selfValidated = new WeakSet<object>()
+
+function validatedDigest(body: string): string {
+  return xxh3(`vx-lock-valid-v${CONFIG_EVAL_VERSION}\0${VERSION}\0${body}`).toString(16)
+}
+
 export async function writeLockfile(root: string, lock: Lockfile): Promise<void> {
   // Written beside its name and renamed over it: `Bun.write` truncates in
   // place, so a `--frozen` run, or `vx watch --frozen` woken by the write
@@ -114,7 +137,8 @@ export async function writeLockfile(root: string, lock: Lockfile): Promise<void>
   const file = lockfilePath(root)
   const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`
   try {
-    await Bun.write(tmp, `${JSON.stringify(lock, null, 2)}\n`)
+    const body = JSON.stringify({ version: lock.version, projects: lock.projects }, null, 2)
+    await Bun.write(tmp, `${body.slice(0, -2)},\n  "validated": "${validatedDigest(body)}"\n}\n`)
     await rename(tmp, file)
   } catch (err) {
     // Best effort: where the write was refused the temp cannot be named
@@ -187,7 +211,10 @@ export async function frozenProjectConfigs(
   // asked for 1,090 per-project rows in one `IN` query, ~10 ms of its
   // config load, where the eval-cache path it replaces is cheaper (X-181).
   // A scoped run still validates, and remembers, only what it loads.
-  if (prefix !== undefined && store !== undefined && store.getConfigEval(prefix) !== null) {
+  if (
+    selfValidated.has(lock) ||
+    (prefix !== undefined && store !== undefined && store.getConfigEval(prefix) !== null)
+  ) {
     return entries.map((e) => e.config)
   }
   const keys = prefix === undefined ? undefined : metas.map((m) => `${prefix}\0${m.name}`)

package/src/workspace/migration.ts

@@ -261,6 +261,11 @@ export interface ApplyMigrationArgs {
    * and compiled the config into its dist (TanStack/query, 2026-09-11).
    */
   format?: MigrationFormat
+  /**
+   * With `dry`: one JSON document on stdout (`schemas/init.json`) in place
+   * of the files and the report, so an agent reads the plan as data.
+   */
+  json?: boolean
 }
 
 export type MigrationFormat = 'ts' | 'mjs'
@@ -360,11 +365,11 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     const existing = metas.find((m) => m.dir === p.dir)?.configPath
     if (existing && existing !== path.join(p.dir, configName)) replaced.push(existing)
   }
-  if (dry) {
+  if (dry && args.json !== true) {
     for (const f of files) {
       process.stdout.write(`── ${f.relPath} ──\n${f.contents}\n`)
     }
-  } else {
+  } else if (!dry) {
     for (const f of files) await Bun.write(f.abs, f.contents)
     for (const f of replaced) await unlink(f)
   }
@@ -476,7 +481,29 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     ...(inGitWorkTree(root) ? [] : ['git init']),
     ...(empty ? [`declare a task as the example shows`] : []),
   ]
-  report.push('', `next: ${steps.length === 0 ? run : `${steps.join(', ')}, then ${run}`}`)
+  const next = steps.length === 0 ? run : `${steps.join(', ')}, then ${run}`
+  if (args.json === true) {
+    process.stdout.write(
+      `${JSON.stringify({
+        dry,
+        source,
+        files: files.map((f) => ({ path: f.relPath, contents: f.contents })),
+        kept,
+        replaced: replaced.map((f) => relPosix(root, f)),
+        todos: [...todos].map(([reason, tasks]) => ({ reason, tasks })),
+        notes: [
+          ...(empty && unreached.length > 0 ? [unreachedHint(unreached, root)] : []),
+          ...(empty ? noMembers : []),
+          ...(args.notes ?? []),
+          ...plan.headerNotes,
+          ...plan.notes,
+        ],
+        next,
+      })}\n`,
+    )
+    return 0
+  }
+  report.push('', `next: ${next}`)
   process.stdout.write(`${report.join('\n')}\n`)
   return 0
 }