@vzn/vx 0.0.12 → 0.0.15

package/src/cli/run.ts

@@ -26,6 +26,7 @@ import {
 } from '../orchestrator/index.js'
 import type { ContinueMode } from '../graph/index.js'
 import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
+import { parseSize } from '../util/index.js'
 import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
 import { localBackend } from './backend.js'
 
@@ -68,13 +69,21 @@ export interface RunArgs {
    */
   timeout: number | undefined
   /**
-   * `--verify[=determinism|inputs|all]`: cache-correctness verification.
-   * Undefined when not passed. `determinism` re-runs and content-compares
-   * outputs; `inputs` sandboxes with the declared-input baseline and flags
-   * undeclared reads. `allow` (from `--verify-allow=<pkg#task>,…`) exempts
-   * tasks from failing the run on a divergence.
+   * `--memory <size>` / `--memory=<size>`: memory budget (resolved to
+   * bytes) for `exec.resources.memory` reservations. Defaults to
+   * os.totalmem() when not passed — pass it in cgroup-limited containers.
    */
-  verify: { determinism: boolean; inputs: boolean } | undefined
+  memory: number | undefined
+  /**
+   * `--verify[=determinism|inputs|fingerprint|all]`: cache-correctness
+   * verification. Undefined when not passed. `determinism` re-runs and
+   * content-compares outputs; `inputs` sandboxes with the declared-input
+   * baseline and flags undeclared reads; `fingerprint` ships output-tree
+   * fingerprints for the cross-machine diff (no re-run; the determinism
+   * modes set it too, for free). `allow` (from `--verify-allow=<pkg#task>,…`)
+   * exempts tasks from failing the run on a divergence.
+   */
+  verify: { determinism: boolean; inputs: boolean; fingerprint: boolean } | undefined
   verifyAllow: string[]
   outputLogs?: 'full' | 'errors-only' | 'none'
   forwardArgs: string[]
@@ -108,6 +117,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     frozen: false,
     retries: undefined,
     timeout: undefined,
+    memory: undefined,
     verify: undefined,
     verifyAllow: [],
     forwardArgs: [],
@@ -174,18 +184,28 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
         return { ...out, error: `--timeout must be a positive integer (ms), got: ${v}` }
       }
       out.timeout = n
+    } else if (a === '--memory' || a?.startsWith('--memory=')) {
+      const v = a === '--memory' ? before[++i] : a.slice('--memory='.length)
+      if (v === undefined || v === '') return { ...out, error: `--memory requires a value` }
+      const bytes = parseSize(v)
+      if (bytes === null || bytes <= 0) {
+        return { ...out, error: `--memory must be a size like 8GB or 512MB, got: ${v}` }
+      }
+      out.memory = bytes
     } else if (a === '--verify' || a?.startsWith('--verify=')) {
       const what = a === '--verify' ? 'determinism' : a.slice('--verify='.length)
       if (what === 'determinism') {
-        out.verify = { determinism: true, inputs: false }
+        out.verify = { determinism: true, inputs: false, fingerprint: true }
       } else if (what === 'inputs') {
-        out.verify = { determinism: false, inputs: true }
+        out.verify = { determinism: false, inputs: true, fingerprint: false }
+      } else if (what === 'fingerprint') {
+        out.verify = { determinism: false, inputs: false, fingerprint: true }
       } else if (what === 'all') {
-        out.verify = { determinism: true, inputs: true }
+        out.verify = { determinism: true, inputs: true, fingerprint: true }
       } else {
         return {
           ...out,
-          error: `--verify must be determinism | inputs | all (or bare --verify), got: ${what}`,
+          error: `--verify must be determinism | inputs | fingerprint | all (or bare --verify), got: ${what}`,
         }
       }
     } else if (a?.startsWith('--verify-allow=')) {
@@ -405,11 +425,13 @@ export async function resolveRunOptions(
   if (projects !== undefined) opts.projects = projects
   if (parsed.retries !== undefined) opts.retries = parsed.retries
   if (parsed.timeout !== undefined) opts.timeout = parsed.timeout
+  if (parsed.memory !== undefined) opts.memory = parsed.memory
   if (parsed.cacheDir !== undefined) opts.cacheDir = parsed.cacheDir
   if (parsed.verify !== undefined) {
     opts.verify = {
       determinism: parsed.verify.determinism,
       inputs: parsed.verify.inputs,
+      fingerprint: parsed.verify.fingerprint,
       allow: new Set(parsed.verifyAllow),
     }
   }

package/src/config.ts

@@ -239,6 +239,16 @@ export interface ExecConfig {
    * default, including `retries: 0`.
    */
   retries?: number
+  /**
+   * Resource RESERVATIONS for admission control — NOT enforcement: vx
+   * does not cgroup-limit, nice, or kill the task; it only decides what
+   * to co-schedule so concurrent reservations never exceed the CPU /
+   * memory budget. Each axis defaults to 0 = reserve nothing: the task
+   * runs subject only to the concurrency-count limit. A pure scheduling
+   * hint — the whole object is stripped from the cache key, so tuning a
+   * reservation never invalidates a cached result.
+   */
+  resources?: ResourcesConfig
   /**
    * Long-running / continuous task (dev server, watcher, daemon).
    * When present, the task is spawned but the runner does NOT wait
@@ -255,6 +265,27 @@ export interface ExecConfig {
   persistent?: PersistentConfig
 }
 
+/**
+ * Per-task resource reservation (see `ExecConfig.resources`). Grouped so
+ * a future axis slots in without new top-level `exec` fields; the loader
+ * rejects unknown keys.
+ */
+export interface ResourcesConfig {
+  /**
+   * CPU units (fractional ok, e.g. `0.5`), or a `"<n>%"` string of the
+   * CPU budget (the run's `concurrency`). `cpus: "50%"` on a budget of 8
+   * reserves 4 units.
+   */
+  cpus?: number | string
+  /**
+   * Bytes, a size string (`"2GB"`, `"512MB"` — K/M/G/T, powers of 1024),
+   * or a `"<n>%"` string of the memory budget (`os.totalmem()` unless
+   * overridden with `--memory` — pass `--memory` in cgroup-limited
+   * containers, where `os.totalmem()` reports the HOST's RAM).
+   */
+  memory?: number | string
+}
+
 export interface PersistentConfig {
   /**
    * Regex pattern (string) matched against stdout/stderr line-by-line.
@@ -394,8 +425,16 @@ export interface CacheInputs {
  *                          here, so any `^`-prefixed string is allowed.
  *   - `` `${string}#${string}` `` — a specific package's task
  *                          (`'pkg#build'`); cross-project, not key-checked.
+ *   - `` `${string}*${string}` `` — a task-name pattern (`'build.*'`);
+ *                          expands at graph build, so it can't be
+ *                          key-checked (a bare `'*'` still fails at
+ *                          runtime — bare wildcards are filter-only).
  */
-type DependsOnEntry<K extends string> = K | `^${string}` | `${string}#${string}`
+type DependsOnEntry<K extends string> =
+  | K
+  | `^${string}`
+  | `${string}#${string}`
+  | `${string}*${string}`
 
 /**
  * Identity function — exists only so TypeScript narrows literal types

package/src/graph/dependency-spec.ts

@@ -32,6 +32,22 @@ export class DependencySpecError extends Error {
  * builder vs the filter) decide which ones make semantic sense and
  * surface their own validation errors. This keeps the parser pure.
  */
+/** True when a task form is a `*` pattern (`build.*`) rather than an exact name. */
+export function isTaskPattern(task: string): boolean {
+  return task.includes('*')
+}
+
+/**
+ * Compile a `*`-only glob over task names: `build.*` → /^build\..*$/.
+ * `*` is the sole metacharacter — everything else matches literally, so the
+ * dotted-namespace convention (`build.bun.linux-x64`) needs no escaping by
+ * the user.
+ */
+export function compileTaskPattern(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+  return new RegExp(`^${escaped}$`)
+}
+
 export function parseDependencySpec(raw: string): DependencySpec {
   if (raw.length === 0) throw new DependencySpecError(raw, 'empty spec')
 

package/src/graph/index.ts

@@ -1,13 +1,22 @@
 // Module contract. Cross-module imports must come through here; see
 // docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
 
-export { DependencySpecError, parseDependencySpec, type DependencySpec } from './dependency-spec.js'
+export {
+  DependencySpecError,
+  compileTaskPattern,
+  isTaskPattern,
+  parseDependencySpec,
+  type DependencySpec,
+} from './dependency-spec.js'
 export {
   type ContinueMode,
+  type OutputFingerprint,
+  type ResourceCost,
   runGraph,
   type TaskOutcome,
   type TaskStatus,
   type VerifyVerdict,
+  ZERO_COST,
 } from './scheduler.js'
 export {
   buildTaskGraph,

package/src/graph/scheduler.ts

@@ -42,6 +42,31 @@ export type VerifyVerdict =
   /** Didn't execute (cache hit) / not cacheable / group / persistent. */
   | { kind: 'not-verified' }
 
+/**
+ * Content fingerprint of a task's output tree, computed under a `--verify*`
+ * mode on the executed (miss) path. Never hashed into any key; pure telemetry
+ * side-channel for the cross-machine diff (a serve pairs fingerprints for the
+ * SAME cache key across platforms and names diverging outputs). Declared here
+ * (structurally) because `graph` can't import `orchestrator` — the
+ * `VerifyVerdict` pattern. See docs/design/verify-cross-machine-2026-07.md.
+ */
+export interface OutputFingerprint {
+  /** Roll-up: xxh3hex over the sorted (key, hash) pairs, folded as
+   *  `key \0 hash \n` (\0 boundaries — the v18 lesson). Always present;
+   *  divergence DETECTION never depends on the per-file map. */
+  tree: string
+  /** Total files in the tree (pre-truncation). */
+  fileCount: number
+  /** Per-file map as sorted [outputKey, xxh3hex] pairs, capped at
+   *  FP_MAX_FILES (500). Deterministic truncation — sorted by key,
+   *  first N — so two machines' truncated maps cover the same subset
+   *  and partial diffs still name real rels. */
+  files?: ReadonlyArray<readonly [string, string]>
+  /** Set when `files` was truncated to the cap (or dropped by the
+   *  sink's run budget). */
+  truncated?: boolean
+}
+
 export interface TaskOutcome {
   node: TaskNode
   status: TaskStatus
@@ -94,10 +119,30 @@ export interface TaskOutcome {
    * mode; a plain run leaves it undefined. Pure side-channel (never hashed).
    */
   verify?: VerifyVerdict
+  /**
+   * Output-tree fingerprint under a fingerprinting `--verify*` mode
+   * (`--verify` / `=all` / `=fingerprint`), executed + cacheable +
+   * output-declaring tasks only. A plain run leaves it undefined.
+   */
+  outputFp?: OutputFingerprint
 }
 
 export type ContinueMode = 'never' | 'deps-ok' | 'always'
 
+/**
+ * Resolved per-task resource reservation, in absolute units (cpu may be
+ * fractional; mem is bytes). Declared here (structurally) because `graph`
+ * can't import `orchestrator`, where the resolver lives — same pattern as
+ * `VerifyVerdict`. A `0` axis means "reserve nothing, run freely": the
+ * task is exempt from that axis entirely (needs no headroom, holds none).
+ */
+export interface ResourceCost {
+  cpu: number
+  mem: number
+}
+
+export const ZERO_COST: ResourceCost = { cpu: 0, mem: 0 }
+
 export interface ScheduleOptions {
   nodes: Map<string, TaskNode>
   concurrency: number
@@ -147,6 +192,18 @@ export interface ScheduleOptions {
    * second cache.get. When undefined/empty, behavior is byte-identical.
    */
   restoreTier?: ReadonlySet<string>
+  /**
+   * Resolved per-task resource reservations (`exec.resources`, resolved
+   * by the orchestrator against the run's budgets). An absent id means
+   * zero cost; undefined/empty means no task opted in — the scheduler
+   * takes the legacy path byte-identically. Admission control only —
+   * nothing is enforced on the child process.
+   */
+  resourceCosts?: ReadonlyMap<string, ResourceCost>
+  /** CPU budget reservations pack against. Defaults to `concurrency`. */
+  cpuBudget?: number
+  /** Memory budget (bytes). Defaults to Infinity (axis off). */
+  memBudget?: number
 }
 
 /**
@@ -269,9 +326,14 @@ class ReadyHeap {
     this.seq[i] = this.seq[j]!
     this.seq[j] = si
   }
-  push(id: string): void {
+  /**
+   * `seq` defaults to a fresh monotonic counter. A parked-then-repushed
+   * task passes its ORIGINAL seq back in so FIFO-among-equals survives
+   * the round trip (a fresh seq would demote it behind later arrivals).
+   */
+  push(id: string, seq: number = this.next++): void {
     this.ids.push(id)
-    this.seq.push(this.next++)
+    this.seq.push(seq)
     let i = this.ids.length - 1
     while (i > 0) {
       const parent = (i - 1) >> 1
@@ -280,6 +342,10 @@ class ReadyHeap {
       i = parent
     }
   }
+  /** The head's enqueue seq (capture before `pop` for a possible repush). */
+  peekSeq(): number {
+    return this.seq[0] ?? -1
+  }
   pop(): string | undefined {
     const n = this.ids.length
     if (n === 0) return undefined
@@ -362,11 +428,89 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
   let active = 0
   let resolved = false
 
+  // Resource admission (2-D bin packing over the count limit). Inactive
+  // (no task opted in) → the tick loop short-circuits before any of this
+  // and behaves byte-identically to the count-only scheduler.
+  const costs = options.resourceCosts
+  const resourcesActive = costs !== undefined && costs.size > 0
+  const cpuBudget = options.cpuBudget ?? concurrency
+  const memBudget = options.memBudget ?? Infinity
+  // Reservations are FLOAT sums (fractional cpus, and percent-of-budget
+  // resolves to non-representable values like `0.30000000000000004`), so
+  // add/release cycles leave ~1e-17 residue instead of an exact 0. Two
+  // guards keep that residue from corrupting admission:
+  //   - the solo-clamp gate ("is the axis idle?") reads INTEGER holder
+  //     counts, never the float sum === 0 — a residue would otherwise
+  //     park an over-budget task forever (active===0, no future tick =
+  //     a silent hang / exit-0-without-running);
+  //   - `reserved` snaps back to EXACT 0 whenever its holder count hits
+  //     0, so residue can't accumulate across busy periods.
+  // The within-budget comparison also carries a tiny relative epsilon so
+  // an exact-fill (`reserved + cost == budget`) can't mis-round into a
+  // spurious block. Admission is a hint, so the epsilon's sub-ulp
+  // over-admission is harmless.
+  let reservedCpu = 0
+  let reservedMem = 0
+  let holdersCpu = 0
+  let holdersMem = 0
+
+  // A restore-tier task is a confirmed local cache hit: its "execution"
+  // is a cheap tar extract, not the task's real work — it reserves ZERO
+  // regardless of what the config declares, so it never holds budget
+  // against a real executor (and never parks).
+  const costOf = (id: string): ResourceCost =>
+    options.restoreTier?.has(id) ? ZERO_COST : (costs?.get(id) ?? ZERO_COST)
+
+  // Zero never blocks; a within-budget cost needs headroom (with an
+  // exact-fill epsilon); an over-budget cost can never have headroom, so
+  // it solo-clamps: admitted only when the axis is idle (no holders — an
+  // idle pool always admits at least one ready task, no deadlock).
+  const fitsAxis = (cost: number, reserved: number, holders: number, budget: number): boolean =>
+    cost === 0 ? true : cost <= budget ? reserved + cost <= budget + budget * 1e-9 : holders === 0
+
+  const fits = (id: string): boolean => {
+    const c = costOf(id)
+    return (
+      fitsAxis(c.cpu, reservedCpu, holdersCpu, cpuBudget) &&
+      fitsAxis(c.mem, reservedMem, holdersMem, memBudget)
+    )
+  }
+
+  // Reserve/release keep the float sum AND the integer holder count in
+  // lockstep; releasing the last holder on an axis snaps its sum to 0.
+  const reserve = (c: ResourceCost): void => {
+    if (c.cpu > 0) {
+      reservedCpu += c.cpu
+      holdersCpu++
+    }
+    if (c.mem > 0) {
+      reservedMem += c.mem
+      holdersMem++
+    }
+  }
+  const release = (c: ResourceCost): void => {
+    if (c.cpu > 0 && --holdersCpu === 0) reservedCpu = 0
+    else reservedCpu -= c.cpu
+    if (c.mem > 0 && --holdersMem === 0) reservedMem = 0
+    else reservedMem -= c.mem
+  }
+
   return new Promise<Map<string, TaskOutcome>>((resolve) => {
     const finishOne = (id: string, outcome: TaskOutcome): void => {
       if (continueMode === 'never' && outcome.status === 'failed') failFastTripped = true
       outcomes.set(id, outcome)
-      onFinish?.(outcome)
+      // Observer hook (the logger's taskComplete). Crash-isolated: a
+      // throwing observer must NOT break scheduling — it would otherwise
+      // skip the dependent-enqueue + tick below and hang the run. Same
+      // "observability never breaks a run" rule the telemetry/eventSink
+      // paths hold. Isolated here (not the completion arm) so a throw
+      // can't be mistaken for the task itself failing.
+      try {
+        onFinish?.(outcome)
+      } catch (err) {
+        const m = err instanceof Error ? err.message : String(err)
+        process.stderr.write(`[vx] onFinish observer threw for ${id}: ${m}\n`)
+      }
       const ds = dependents.get(id)
       if (!ds) return
       for (const d of ds) {
@@ -378,57 +522,102 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
       }
     }
 
-    // Drain a worker slot: prefer an exec-tier task (misses own the
-    // pool); only when none is ready does a restore-tier task backfill.
-    const takeReady = (): string | undefined =>
-      execReady.size > 0 ? execReady.pop() : restoreReady.pop()
+    // True when the task would be finished as `skipped` without running
+    // (fail-fast tripped, or a failed/skipped upstream under
+    // continueMode !== 'always'). ONE predicate shared by the admission
+    // parker and the dispatch loop's skip branch — a would-skip task
+    // executes nothing, so it must never park on a resource fit (a
+    // too-big doomed task parking forever would hang the run).
+    //
+    // Restore-tier tasks BYPASS the dep check: their key is independent
+    // of any dep's success (pure-input transitive hashing), so a valid
+    // cached output is reported `cache-hit` even if a dep failed — and
+    // they're dep-independent, so they typically restore before a dep
+    // could fail anyway.
+    const willSkip = (id: string): boolean => {
+      if (failFastTripped) return true
+      if (restoreTier?.has(id)) return false
+      if (continueMode === 'always') return false
+      const node = nodes.get(id) as TaskNode
+      return node.deps.some((d) => {
+        const u = outcomes.get(d)
+        return u?.status === 'failed' || u?.status === 'skipped'
+      })
+    }
 
     const tick = (): void => {
       if (resolved) return
+      // Exec-tier tasks parked THIS tick on a failed resource fit.
+      // Within one synchronous tick `reserved` only increases (release
+      // happens in the async completion callbacks, which run a fresh
+      // tick), so a task that doesn't fit now cannot fit later in the
+      // same tick — parking it for the tick's remainder is exact, and
+      // each id pops at most once per tick (O(R log R)).
+      const parked: Array<[string, number]> = []
 
-      while (active < concurrency && (execReady.size > 0 || restoreReady.size > 0)) {
-        const id = takeReady() as string
+      // Highest-priority admissible task: exec tier first (misses own
+      // the pool), then restore tier. With no reservations declared this
+      // short-circuits to exactly the legacy takeReady. A would-skip
+      // task returns without a fit check (finishing it is free); restore
+      // tasks cost zero by construction, so they never park.
+      const takeFitting = (): string | undefined => {
+        while (execReady.size > 0) {
+          const seq = execReady.peekSeq()
+          const id = execReady.pop() as string
+          if (!resourcesActive || willSkip(id) || fits(id)) return id
+          parked.push([id, seq])
+        }
+        return restoreReady.pop()
+      }
+
+      while (active < concurrency) {
+        const id = takeFitting()
+        if (id === undefined) break // nothing ready is admissible right now
         const node = nodes.get(id) as TaskNode
-        const isRestore = restoreTier?.has(id) === true
 
-        // If any upstream failed/skipped, propagate skip synchronously
-        // without running. Skipped tasks still flow through this queue
-        // because dependents are pushed when `pending` hits 0 regardless
-        // of outcome — keeps the propagation logic in one place.
-        //
-        // Restore-tier tasks BYPASS this check: their key is independent
-        // of any dep's success (pure-input transitive hashing), so a
-        // valid cached output is reported `cache-hit` even if a dep
-        // failed — and they're dep-independent, so they typically
-        // restore before a dep could fail anyway.
-        //
         // For a restore-tier task running BEFORE its deps finish, the
         // `upstream` entries below can be undefined (the cast lies) —
         // the preProbed hit path in execute-task never reads them, and
         // nothing on the restore path may.
         const upstream = node.deps.map((d) => outcomes.get(d) as TaskOutcome)
-        if (failFastTripped) {
+
+        // If any upstream failed/skipped, propagate skip synchronously
+        // without running. Skipped tasks still flow through this queue
+        // because dependents are pushed when `pending` hits 0 regardless
+        // of outcome — keeps the propagation logic in one place.
+        if (willSkip(id)) {
           finishOne(id, { node, status: 'skipped', exitCode: 1, durationMs: 0 })
           continue
         }
-        if (!isRestore && continueMode !== 'always') {
-          const failedDep = upstream.find((u) => u.status === 'failed' || u.status === 'skipped')
-          if (failedDep) {
-            finishOne(id, { node, status: 'skipped', exitCode: 1, durationMs: 0 })
-            continue
-          }
-        }
 
         active++
-        onStart?.(node)
+        // Reserve on dispatch; capture the cost so the release in the
+        // completion callbacks is symmetric even if the maps change.
+        const cost = costOf(id)
+        reserve(cost)
+        // Crash-isolated observer hook — a throwing onStart must not abort
+        // the dispatch loop (it would strand the tick with reservations held).
+        try {
+          onStart?.(node)
+        } catch (err) {
+          const m = err instanceof Error ? err.message : String(err)
+          process.stderr.write(`[vx] onStart observer threw for ${id}: ${m}\n`)
+        }
 
-        execute(node, upstream)
-          .then((outcome) => {
+        // `.then(onFulfilled, onRejected)` — NOT `.then(f).catch(g)`. The
+        // rejection arm handles ONLY `execute()` rejecting; a throw from
+        // the fulfillment arm (finishOne / onFinish / tick) must NOT also
+        // run the rejection arm, or `active`/`reserved` release twice —
+        // and a double release drives `reserved` negative, permanently
+        // wedging the solo-clamp gate.
+        execute(node, upstream).then(
+          (outcome) => {
             active--
+            release(cost)
             finishOne(id, outcome)
             tick()
-          })
-          .catch((err: unknown) => {
+          },
+          (err: unknown) => {
             const message = err instanceof Error ? err.message : String(err)
             const outcome: TaskOutcome = {
               node,
@@ -437,6 +626,7 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
               durationMs: 0,
             }
             active--
+            release(cost)
             finishOne(id, outcome)
             // Surface the error live; the outcome itself doesn't
             // carry captured stderr (that's the logger's job). A
@@ -450,9 +640,14 @@ export async function runGraph(options: ScheduleOptions): Promise<Map<string, Ta
               process.stderr.write(`[vx] internal error in ${id}: ${named}${message}\n`)
             }
             tick()
-          })
+          },
+        )
       }
 
+      // Repush parked ids with their ORIGINAL seqs — FIFO-among-equals
+      // is exactly preserved for the next tick's admission pass.
+      for (const [id, seq] of parked) execReady.push(id, seq)
+
       if (outcomes.size === nodes.size && active === 0) {
         resolved = true
         resolve(outcomes)