@vzn/vx 0.0.12 → 0.0.14

package/src/orchestrator/run.ts

@@ -2,6 +2,7 @@
 // run with caching. Each step delegates to a single-purpose sibling file
 // so the layers can be swapped without touching the others.
 
+import os from 'node:os'
 import {
   type CacheLayer,
   type CachePolicy,
@@ -21,6 +22,7 @@ import {
 } from '../graph/index.js'
 import { ulid, UserError } from '../util/index.js'
 import { executeTask } from './execute-task.js'
+import { resolveResourceCosts } from './resources.js'
 import { computeTaskHash } from './task-hash.js'
 import { busLogger, createEventBus, terminalSubscriber } from './events.js'
 import { installPlugins } from './plugin.js'
@@ -248,6 +250,20 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     const remoteCacheEnabled = cache instanceof LayeredCache
     const policy: CachePolicy = options.cache ?? FULL_CACHE_POLICY
 
+    // `--verify` observes the miss-then-save path, so a policy with NO write
+    // axis (`--no-cache`, `--cache=local:,remote:`) verifies nothing — every
+    // task would come back green with zero verdicts. The user asked for a
+    // proof; silently skipping it is the one failure mode verification must
+    // never have (same platform-honesty rule as the sandbox-unavailable
+    // error). `--force --verify` is the supported re-verify-warm recipe.
+    if (options.verify !== undefined && !policy.localWrite && !policy.remoteWrite) {
+      prepared.cache.close()
+      throw new UserError(
+        '--verify needs cache writes to prove anything (it verifies the save path); ' +
+          'drop --no-cache, or use --force --verify to re-execute and verify a warm graph',
+      )
+    }
+
     // Per-run context for the Tier-3 `invocations` header row. Captured
     // ONCE (git is ONE spawn for commit+branch, behind try/catch; never
     // fails a run). `dirty` reuses the `git status --porcelain` the
@@ -345,6 +361,17 @@ export async function run(options: RunOptions): Promise<RunSummary> {
         if (node.requested || node.surfaced === true) requestedCount++
       }
     }
+    // Resource-aware admission: resolve every task's `exec.resources`
+    // into absolute costs ONCE, up front (percent forms against the
+    // budgets), so the scheduler's inner loop is a plain Map.get. The
+    // CPU budget is the run's concurrency; the memory budget is
+    // os.totalmem() unless `--memory` overrides it (pass `--memory` in
+    // cgroup-limited containers — totalmem() reports the HOST's RAM).
+    // Nothing declared → empty map → fields omitted from the scheduler
+    // AND the footer → byte-identical legacy path.
+    const memBudget = options.memory ?? os.totalmem()
+    const resourceCosts = resolveResourceCosts(nodes, concurrency, memBudget)
+
     // Run context for the footer. The top-of-run header is gone — the
     // banner now lives in the summary, where the eye lands at the end.
     const runContext = {
@@ -353,6 +380,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
       remoteCacheEnabled,
       concurrency,
       workspaceProjectCount,
+      ...(resourceCosts.size > 0 ? { cpuBudget: concurrency, memBudget } : {}),
     }
 
     // Lifecycle hooks drive the default logger's dynamic status line
@@ -501,6 +529,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     const outcomes = await runGraph({
       nodes,
       concurrency,
+      ...(resourceCosts.size > 0 ? { resourceCosts, cpuBudget: concurrency, memBudget } : {}),
       ...(options.continueMode !== undefined ? { continueMode: options.continueMode } : {}),
       onStart: (node) => {
         log.taskStart?.(node)
@@ -586,6 +615,21 @@ export async function run(options: RunOptions): Promise<RunSummary> {
     for (const line of formatRunSummary(list, totalMs, colors, runContext)) log.status(line)
     if (options.verify !== undefined) {
       for (const line of formatVerifySection(list)) log.status(line)
+      // A fingerprint-only run attaches no verdicts, so the verdict-driven
+      // section above prints nothing — report what actually happened.
+      if (options.verify.fingerprint && !options.verify.determinism && !options.verify.inputs) {
+        const n = list.filter((o) => o.outputFp !== undefined).length
+        log.status('')
+        log.status(
+          `  Verify:   fingerprinted ${n} task output trees (cross-machine diff via a connected serve)`,
+        )
+        // Only EXECUTED tasks fingerprint — a warm all-hit run reports 0.
+        // A per-platform matrix wired without `--force` produces nothing
+        // forever, so name the cause instead of a bare 0.
+        if (n === 0) {
+          log.status('            (0 executed — cache hits do not fingerprint; pair with --force)')
+        }
+      }
     }
 
     // Optional artifacts. Errors are surfaced to the user but don't
@@ -658,6 +702,7 @@ export async function run(options: RunOptions): Promise<RunSummary> {
         if (o.peakRssBytes !== undefined) t.peakRssBytes = o.peakRssBytes
         if (o.attempts !== undefined) t.attempts = o.attempts
         if (o.verify !== undefined) t.verify = o.verify
+        if (o.outputFp !== undefined) t.outputFp = o.outputFp
         if (o.wallclockStartNs !== undefined) t.wallclockStartNs = o.wallclockStartNs.toString()
         if (o.wallclockEndNs !== undefined) t.wallclockEndNs = o.wallclockEndNs.toString()
         summaryTasks.push(t)

package/src/orchestrator/summary.ts

@@ -125,6 +125,14 @@ export interface RunContext {
   remoteCacheEnabled: boolean
   /** Total projects discovery found — the bar's denominator. */
   workspaceProjectCount?: number
+  /**
+   * Resource-admission budgets (`exec.resources`), set ONLY when at
+   * least one task declared a reservation — a plain run's footer is
+   * byte-identical. Shown on the `info` row so a packed run says what
+   * it packed against. memBudget in bytes.
+   */
+  cpuBudget?: number
+  memBudget?: number
 }
 
 export function formatSummarySection(
@@ -240,6 +248,9 @@ export function formatSummarySection(
     if (context.concurrency !== undefined)
       info.push(`${context.concurrency} worker${context.concurrency === 1 ? '' : 's'}`)
     info.push(context.remoteCacheEnabled ? 'local + remote cache' : 'local cache')
+    if (context.cpuBudget !== undefined) info.push(`cpu budget ${context.cpuBudget}`)
+    if (context.memBudget !== undefined && Number.isFinite(context.memBudget))
+      info.push(`mem budget ${formatBudgetBytes(context.memBudget)}`)
     lines.push('', row('info', join(info)), row('time', `${formatDuration(totalMs)}${spread}`))
   } else {
     lines.push('', row('time', `${formatDuration(totalMs)}${spread}`))
@@ -247,6 +258,19 @@ export function formatSummarySection(
   return lines
 }
 
+// Local byte formatter — the orchestrator can't import cli/format.ts
+// (module boundary), and the footer only needs one compact form.
+function formatBudgetBytes(bytes: number): string {
+  const units = ['B', 'KB', 'MB', 'GB', 'TB']
+  let v = bytes
+  let u = 0
+  while (v >= 1024 && u < units.length - 1) {
+    v /= 1024
+    u++
+  }
+  return `${u === 0 ? v : v.toFixed(1)} ${units[u]}`
+}
+
 export function formatRunSummary(
   outcomes: readonly TaskOutcome[],
   totalMs: number,

package/src/orchestrator/task-hash.ts

@@ -170,11 +170,26 @@ function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
   if (hashCache) {
     const cached = hashCache.taskConfig.get(cfg)
     if (cached !== undefined) return cached
-    const hash = xxh3hex(JSON.stringify(cfg))
+    const hash = xxh3hex(JSON.stringify(hashableConfig(cfg)))
     hashCache.taskConfig.set(cfg, hash)
     return hash
   }
-  return xxh3hex(JSON.stringify(cfg))
+  return xxh3hex(JSON.stringify(hashableConfig(cfg)))
+}
+
+/**
+ * Project the config for hashing: `exec.resources` is a pure scheduling
+ * hint with zero effect on outputs, so it's stripped — tuning a
+ * reservation never busts a cache. A config that declares none takes the
+ * fast path and stringifies byte-identically to before the field existed
+ * (why this needs no CACHE_VERSION bump). `timeout`/`retries` stay folded
+ * — their keys are distinct by design (see the decision log); stripping
+ * them retroactively would bump CACHE_VERSION.
+ */
+function hashableConfig(cfg: TaskConfig): unknown {
+  if (cfg.exec?.resources === undefined) return cfg
+  const { resources: _resources, ...execRest } = cfg.exec
+  return { ...cfg, exec: execRest }
 }
 
 /**

package/src/orchestrator/telemetry.ts

@@ -16,7 +16,7 @@
 // what or how tasks run. Contrast `backend`/`cache`, which return objects
 // core calls INTO; those are the behavior capabilities, kept separate.
 
-import type { TaskStatus, VerifyVerdict } from '../graph/index.js'
+import type { OutputFingerprint, TaskStatus, VerifyVerdict } from '../graph/index.js'
 import type { RunEvent, RunEventSubscriber } from './events.js'
 
 /** Bumped when the record shape changes. Readers MUST check `v`. */
@@ -103,6 +103,13 @@ export interface TaskTelemetry {
    *  unsound (its outputs aren't a pure function of its declared inputs); this
    *  is the telemetry-side hermeticity signal a dashboard surfaces. */
   verify?: VerifyVerdict
+  /** Output-tree fingerprint — set ONLY under a fingerprinting `--verify*`
+   *  mode (`--verify` / `=all` / `=fingerprint`), executed tasks only. A
+   *  connected serve pairs fingerprints for the SAME `hash` across platforms
+   *  and names diverging outputs (the cross-machine diff). Absent on plain
+   *  runs — additive-optional, no schema bump (the `attempts`/`verify`
+   *  precedent). */
+  outputFp?: OutputFingerprint
   /** bigint hrtime ns relative to run t=0, encoded as a decimal string. */
   wallclockStartNs?: string
   wallclockEndNs?: string
@@ -304,6 +311,7 @@ export function createTelemetrySource(args: {
         if (outcome.peakRssBytes !== undefined) rec.peakRssBytes = outcome.peakRssBytes
         if (outcome.attempts !== undefined) rec.attempts = outcome.attempts
         if (outcome.verify !== undefined) rec.verify = outcome.verify
+        if (outcome.outputFp !== undefined) rec.outputFp = outcome.outputFp
         if (outcome.wallclockStartNs !== undefined)
           rec.wallclockStartNs = outcome.wallclockStartNs.toString()
         if (outcome.wallclockEndNs !== undefined)

package/src/orchestrator/upstream.ts

@@ -1,5 +1,7 @@
 import {
   DependencySpecError,
+  compileTaskPattern,
+  isTaskPattern,
   parseDependencySpec,
   type DependencySpec,
   type TaskOutcome,
@@ -22,6 +24,11 @@ import { UserError } from '../util/index.js'
  *   'name'      same-project task `name`
  *   '^name'     `name` task in every dep workspace
  *   'pkg#name'  specific package's `name` task
+ *   'name.*'    task-NAME patterns — the task half of any form above may
+ *               contain `*` (same glob as dependsOn patterns). A filter
+ *               that matched literally here while dependsOn expanded the
+ *               same string would silently select ZERO upstream hashes —
+ *               a stale-hit trap, so the two surfaces share the matcher.
  *   '!<form>'   exclude — any of the above with a leading `!`
  *
  * Patterns are applied in order; last write wins, so
@@ -62,14 +69,19 @@ export function filterUpstreamHashes(
     }
   })
 
+  // Per-spec task-name matcher, compiled once (exact compare or pattern).
+  const matchers = specs.map((spec) => taskMatcher(spec))
+
   // Dedup by hash (the key fold's unit), but remember the first task id
   // seen for each hash so the diff row can name the upstream.
   const selected = new Map<string, string>()
-  for (const spec of specs) {
+  for (let i = 0; i < specs.length; i++) {
+    const spec = specs[i]!
+    const taskMatches = matchers[i]!
     for (const u of upstream) {
       if (!u.hash) continue
       const isSelf = u.node.projectName === selfProjectName
-      if (!matches(spec, u, isSelf)) continue
+      if (!matches(spec, u, isSelf, taskMatches)) continue
       if (spec.negated) selected.delete(u.hash)
       else if (!selected.has(u.hash)) selected.set(u.hash, u.node.id)
     }
@@ -77,17 +89,33 @@ export function filterUpstreamHashes(
   return [...selected].map(([hash, id]) => [id, hash])
 }
 
-function matches(spec: DependencySpec, u: TaskOutcome, isSelf: boolean): boolean {
+/** Exact-name compare, or the shared `*`-glob when the form is a pattern. */
+function taskMatcher(spec: DependencySpec): (name: string) => boolean {
+  if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps') return () => true
+  if (isTaskPattern(spec.task)) {
+    const re = compileTaskPattern(spec.task)
+    return (name) => re.test(name)
+  }
+  const exact = spec.task
+  return (name) => name === exact
+}
+
+function matches(
+  spec: DependencySpec,
+  u: TaskOutcome,
+  isSelf: boolean,
+  taskMatches: (name: string) => boolean,
+): boolean {
   switch (spec.kind) {
     case 'wildcardSelf':
       return isSelf
     case 'wildcardDeps':
       return !isSelf
     case 'self':
-      return isSelf && u.node.taskName === spec.task
+      return isSelf && taskMatches(u.node.taskName)
     case 'deps':
-      return !isSelf && u.node.taskName === spec.task
+      return !isSelf && taskMatches(u.node.taskName)
     case 'cross':
-      return u.node.projectName === spec.project && u.node.taskName === spec.task
+      return u.node.projectName === spec.project && taskMatches(u.node.taskName)
   }
 }

package/src/orchestrator/verify.ts

@@ -6,8 +6,8 @@
 // See docs/design/cache-correctness-2026-07.md.
 
 import path from 'node:path'
-import type { CacheLayer } from '../cache/index.js'
-import type { TaskOutcome, VerifyVerdict } from '../graph/index.js'
+import type { OutputFingerprint, TaskOutcome, VerifyVerdict } from '../graph/index.js'
+import { xxh3hex } from '../util/index.js'
 
 /** An output file to fingerprint: absolute path + a stable, run-independent
  *  key (project-relative, or `workspace-outputs/<rel-to-root>` for workspace
@@ -35,19 +35,42 @@ export function outputRefs(
   ]
 }
 
-/** Content-fingerprint an output tree: key → git-blob OID. Reuses the same
- *  `Cache.hashFile` primitive the input hashing folds, so it's byte-true and
- *  mtime-independent — two byte-identical trees produce equal fingerprints
- *  even though their tar.zst artifacts (which embed mtimes) would differ. */
-export async function hashOutputTree(
-  cache: CacheLayer,
-  refs: readonly OutputRef[],
-): Promise<Map<string, string>> {
+/** Content-fingerprint an output tree: key → xxh3 of the file's BYTES, read
+ *  unconditionally from disk. Deliberately NOT `Cache.hashFile`: its
+ *  mtime+size memo would return attempt 1's digest for a re-run output with
+ *  equal size and mtime (e.g. a build that normalizes mtimes — standard
+ *  reproducible-build practice), silently proving a divergent task
+ *  deterministic. fp1/fp2 are only ever compared to each other, so any
+ *  content hash works — and the proof must not trust a cache. */
+export async function hashOutputTree(refs: readonly OutputRef[]): Promise<Map<string, string>> {
   const out = new Map<string, string>()
-  for (const r of refs) out.set(r.key, await cache.hashFile(r.abs))
+  for (const r of refs) {
+    out.set(r.key, xxh3hex(new Uint8Array(await Bun.file(r.abs).arrayBuffer())))
+  }
   return out
 }
 
+/** Per-file map cap on a shipped fingerprint (~40 KB at the cap). The tree
+ *  digest always folds ALL entries, so detection never depends on the map. */
+export const FP_MAX_FILES = 500
+
+/** Roll an output-tree fingerprint map into the shippable `OutputFingerprint`
+ *  payload (Phase 4, cross-machine diff): a tree digest over ALL sorted
+ *  entries folded `key\0hash\n` (\0 boundaries so parts can't alias), plus
+ *  the first-`cap` pairs — deterministic truncation, so two machines'
+ *  truncated maps cover the same key subset and stay diffable. */
+export function foldFingerprint(fp: Map<string, string>, cap = FP_MAX_FILES): OutputFingerprint {
+  const keys = [...fp.keys()].sort()
+  let folded = ''
+  for (const k of keys) folded += `${k}\0${fp.get(k)!}\n`
+  return {
+    tree: xxh3hex(folded),
+    fileCount: keys.length,
+    files: keys.slice(0, cap).map((k) => [k, fp.get(k)!] as const),
+    ...(keys.length > cap ? { truncated: true } : {}),
+  }
+}
+
 /** The output keys whose content OID differs between two fingerprints
  *  (added, removed, or changed), sorted. */
 export function diffOutputTrees(a: Map<string, string>, b: Map<string, string>): string[] {

package/src/util/index.ts

@@ -4,4 +4,5 @@
 export { UserError } from './errors.js'
 export { xxh3, xxh3hex } from './hash.js'
 export { relPosix } from './paths.js'
+export { parseSize } from './size.js'
 export { ulid } from './ulid.js'

package/src/util/size.ts

@@ -0,0 +1,16 @@
+/**
+ * Parse a byte-size string: a bare integer (`"1048576"`) or an integer
+ * with a K/M/G/T suffix, powers of 1024, optional trailing `B`
+ * (`"512MB"`, `"8G"`). Returns `null` for anything else — including
+ * fractional sizes (`"1.5GB"`); callers wanting fractions must express
+ * them in a smaller unit.
+ */
+export function parseSize(input: string): number | null {
+  const m = input.match(/^(\d+)([KMGT])?B?$/i)
+  if (!m) return null
+  const n = Number(m[1])
+  const u = (m[2] ?? '').toUpperCase()
+  const mult =
+    u === '' ? 1 : u === 'K' ? 1024 : u === 'M' ? 1024 * 1024 : u === 'G' ? 1024 ** 3 : 1024 ** 4
+  return n * mult
+}

package/src/workspace/project-loader.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
-import { UserError, xxh3hex } from '../util/index.js'
+import { parseSize, UserError, xxh3hex } from '../util/index.js'
 
 const WORKSPACE_CONFIG_FILENAMES = [
   'vx.workspace.ts',
@@ -187,6 +187,10 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
           throw new UserError(`${where}.exec.retries must be a non-negative integer`)
         }
       }
+      const resources = (exec as { resources?: unknown }).resources
+      if (resources !== undefined) {
+        validateResources(resources, `${where}.exec.resources`)
+      }
       const persistent = (exec as { persistent?: unknown }).persistent
       if (persistent !== undefined) {
         if (typeof persistent !== 'object' || persistent === null) {
@@ -454,6 +458,44 @@ function validateSandbox(sandbox: unknown, where: string, hasExec: boolean): voi
   }
 }
 
+const RESOURCES_FIELDS = new Set(['cpus', 'memory'])
+const PERCENT_RE = /^\d+(\.\d+)?%$/
+
+function validateResources(resources: unknown, where: string): void {
+  if (typeof resources !== 'object' || resources === null || Array.isArray(resources)) {
+    throw new UserError(`${where} must be an object (e.g. \`{ cpus: 2, memory: '2GB' }\`)`)
+  }
+  for (const key of Object.keys(resources as object)) {
+    if (!RESOURCES_FIELDS.has(key)) {
+      throw new UserError(
+        `${where} has unknown field "${key}". Allowed: ${[...RESOURCES_FIELDS].sort().join(', ')}`,
+      )
+    }
+  }
+  const { cpus, memory } = resources as { cpus?: unknown; memory?: unknown }
+  if (cpus !== undefined) {
+    const ok =
+      typeof cpus === 'number'
+        ? Number.isFinite(cpus) && cpus >= 0
+        : typeof cpus === 'string' && PERCENT_RE.test(cpus)
+    if (!ok) {
+      throw new UserError(`${where}.cpus must be a non-negative number or a "<n>%" string`)
+    }
+  }
+  if (memory !== undefined) {
+    const ok =
+      typeof memory === 'number'
+        ? Number.isInteger(memory) && memory >= 0
+        : typeof memory === 'string' && (PERCENT_RE.test(memory) || parseSize(memory) !== null)
+    if (!ok) {
+      throw new UserError(
+        `${where}.memory must be a non-negative integer (bytes), ` +
+          `a size string like "512MB", or a "<n>%" string`,
+      )
+    }
+  }
+}
+
 function assertStringArray(v: unknown, where: string): void {
   if (!Array.isArray(v) || v.some((s) => typeof s !== 'string' || s.length === 0)) {
     throw new UserError(`${where} must be an array of non-empty strings`)