@vzn/vx 0.0.18 → 0.0.21

package/src/orchestrator/missing-plugin.ts

@@ -1,9 +0,0 @@
-/** Shown by every "no <capability> plugin declared" error. */
-export const MISSING_PLUGIN_HINT = `vx runs nothing it was not told to. Declare the plugins in vx.workspace.ts:
-
-  import { defineWorkspace } from '@vzn/vx'
-  import { localExecutorPlugin } from '@vzn/vx/plugins/local-executor'
-  import { localCachePlugin } from '@vzn/vx/plugins/local-cache'
-  export default defineWorkspace({ plugins: [localExecutorPlugin(), localCachePlugin()] })
-
-Put a remote executor or cache plugin BEFORE the local one to prefer it.`

package/src/orchestrator/resources.ts

@@ -1,45 +0,0 @@
-// Resolve `exec.resources` declarations into the absolute per-task costs the
-// scheduler's 2-D admission gate packs against. Pure; the loader has already
-// validated every form (this module trusts internal code), so an unparseable
-// value can't reach it from a real config.
-//
-// The declared units are CPU CORES and MEGABYTES — the same numbers on this
-// machine and on a remote worker, which is why they are also what
-// `TaskPlacement.resources` hands an executor verbatim. Percent forms were
-// removed on 2026-08-30: a percentage names a fraction of THIS run's budget,
-// and an executor placing the task on someone else's machine has no way to
-// mean anything by it.
-
-import type { ResourceCost, TaskNode } from '../graph/index.js'
-
-const BYTES_PER_MB = 1024 * 1024
-
-/** `cpus` → CPU units. Absent → 0 = reserve nothing. */
-export function resolveCpu(v: number | undefined): number {
-  return v ?? 0
-}
-
-/** `memory` (megabytes) → bytes, which is what the budget axis counts. */
-export function resolveMem(v: number | undefined): number {
-  return v === undefined ? 0 : v * BYTES_PER_MB
-}
-
-/**
- * Resolve the whole graph's declared reservations, OMITTING zero-cost
- * tasks: an empty map means "no reservations declared", the single gate
- * the scheduler (and run.ts's option threading) keys off to keep every
- * current run byte-identical.
- */
-export function resolveResourceCosts(
-  nodes: ReadonlyMap<string, TaskNode>,
-): Map<string, ResourceCost> {
-  const out = new Map<string, ResourceCost>()
-  for (const node of nodes.values()) {
-    const declared = node.config.exec?.resources
-    if (declared === undefined) continue
-    const cpu = resolveCpu(declared.cpus)
-    const mem = resolveMem(declared.memory)
-    if (cpu > 0 || mem > 0) out.set(node.id, { cpu, mem })
-  }
-  return out
-}

package/src/orchestrator/verify.ts

@@ -1,174 +0,0 @@
-// Cache-correctness verification (Phase 1: determinism). Pure helpers for the
-// `vx run --verify` hook in execute-task.ts: content-fingerprint a task's
-// output tree (mtime-independent) and diff two runs' trees, so a task whose
-// outputs are NOT a pure function of its declared inputs — a non-hermetic task
-// whose cache entry would replay arbitrary past bytes — is caught and named.
-// See docs/design/cache-correctness-2026-07.md.
-
-import path from 'node:path'
-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
- *  outputs — matching the cache artifact's namespace so the two never collide). */
-export interface OutputRef {
-  abs: string
-  key: string
-}
-
-/** Build the fingerprint key set from a task's resolved output paths. */
-export function outputRefs(
-  projectDir: string,
-  outputFiles: readonly string[],
-  workspaceRoot: string,
-  workspaceOutputFiles: readonly string[],
-): OutputRef[] {
-  const rel = (from: string, abs: string): string =>
-    path.relative(from, abs).split(path.sep).join('/')
-  return [
-    ...outputFiles.map((abs) => ({ abs, key: rel(projectDir, abs) })),
-    ...workspaceOutputFiles.map((abs) => ({
-      abs,
-      key: `workspace-outputs/${rel(workspaceRoot, abs)}`,
-    })),
-  ]
-}
-
-/** 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, 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. */
-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[] {
-  const changed: string[] = []
-  for (const k of new Set([...a.keys(), ...b.keys()])) {
-    if (a.get(k) !== b.get(k)) changed.push(k)
-  }
-  return changed.sort()
-}
-
-/** Turn a determinism diff into a verdict, honoring the `--verify-allow`
- *  escape hatch (an allowed divergence is reported but never fails the run). */
-export function classifyDeterminism(changed: readonly string[], allowed: boolean): VerifyVerdict {
-  if (changed.length === 0) return { kind: 'proven-deterministic' }
-  return allowed
-    ? { kind: 'allowed-nondeterministic', changed }
-    : { kind: 'nondeterministic', changed }
-}
-
-/** Extract the workspace-relative paths a task read outside its declared inputs
- *  (Phase 2, `--verify=inputs`). A strace-derived violation line carries the
- *  offending absolute path in trailing brackets (`… [/abs/path]`); pull it out,
- *  make it workspace-relative, dedup, and sort. Lines without a bracketed path
- *  (e.g. macOS syscall lines) fall back to the raw line so nothing is lost. */
-export function undeclaredInputPaths(
-  violations: readonly { line: string }[],
-  workspaceRoot: string,
-): string[] {
-  const rels = new Set<string>()
-  for (const v of violations) {
-    // Two wire shapes: Linux strace lines carry `[path]`; macOS
-    // sandbox-exec lines end in a bare absolute path
-    // (`node(123) deny(1) file-read-data /abs/path`). Fall back to the
-    // raw line only when neither parses — a path the user can act on
-    // beats a log line every time.
-    const m = /\[([^\]]+)\]\s*$/.exec(v.line) ?? /\s(\/\S+)\s*$/.exec(v.line)
-    const raw = m ? m[1]! : v.line
-    rels.add(
-      path.isAbsolute(raw) ? path.relative(workspaceRoot, raw).split(path.sep).join('/') : raw,
-    )
-  }
-  return [...rels].sort()
-}
-
-/** The end-of-run `--verify` summary section: a counts line plus a
- *  failures block naming each non-hermetic task and its diverging outputs.
- *  Empty when no task carried a verdict. */
-export function formatVerifySection(outcomes: readonly TaskOutcome[]): string[] {
-  const verdicts = outcomes.filter((o) => o.verify !== undefined)
-  if (verdicts.length === 0) return []
-  let proven = 0
-  let bad = 0
-  let na = 0
-  let notVerified = 0
-  for (const o of verdicts) {
-    switch (o.verify!.kind) {
-      case 'proven-deterministic':
-      case 'proven-complete':
-        proven++
-        break
-      case 'nondeterministic':
-      case 'rerun-failed':
-      case 'undeclared-inputs':
-        bad++
-        break
-      case 'allowed-nondeterministic':
-      case 'no-outputs':
-        na++
-        break
-      case 'not-verified':
-        notVerified++
-        break
-      case 'unverifiable-remote-only':
-        na++
-        break
-    }
-  }
-  const lines = [
-    '',
-    `  Verify:   ${proven} proven · ${bad} unsafe · ${na} n/a · ${notVerified} not-verified`,
-  ]
-  for (const o of outcomes) {
-    const v = o.verify
-    if (v === undefined) continue
-    if (v.kind === 'nondeterministic') {
-      lines.push(`    ✗ ${o.node.id} — nondeterministic`)
-      lines.push(`        changed: ${v.changed.join(', ')}`)
-    } else if (v.kind === 'undeclared-inputs') {
-      lines.push(`    ✗ ${o.node.id} — read undeclared inputs`)
-      if (v.paths.length > 0) lines.push(`        ${v.paths.join(', ')}`)
-      lines.push('        add them to cache.inputs.files / workspaceFiles')
-    } else if (v.kind === 'rerun-failed') {
-      lines.push(`    ✗ ${o.node.id} — verify re-run failed (exit ${v.exitCode})`)
-    } else if (v.kind === 'unverifiable-remote-only') {
-      lines.push(`    ⚠ ${o.node.id} — remote-only: no local execution to prove (unverified)`)
-    } else if (v.kind === 'allowed-nondeterministic') {
-      lines.push(`    ⚠ ${o.node.id} — nondeterministic (allowed)`)
-    }
-  }
-  return lines
-}

package/src/plugins/local-cache/index.ts

@@ -1,11 +0,0 @@
-// Core's cache as a plugin: the `.vx/cache` handle the host opened (the run
-// index + the local artifact store). Declared like any other cache layer;
-// put a remote layer BEFORE it to look there first.
-
-import type { VxPlugin } from '@vzn/vx'
-
-export const LOCAL_CACHE_PLUGIN = 'vx/local-cache'
-
-export function localCachePlugin(): VxPlugin {
-  return { name: LOCAL_CACHE_PLUGIN, cache: (ctx) => ctx.localCache }
-}

package/src/plugins/schedule-history/index.ts

@@ -1,109 +0,0 @@
-// History-based scheduling as a plugin: order ready tasks by their expected
-// REMAINING critical-path duration (own p50 + the longest chain of
-// dependents), learned from the local run history. This was core's opt-in
-// `predictive` mode until 2026-09-02; it is the reference `schedule` plugin
-// now — declared like any other, and paying its history read only in
-// workspaces that ask for it.
-//
-// Cache hits are NOT modelled as zero-cost: predicting cache state needs
-// the key and a probe, which the scheduler handles at run time (a confirmed
-// hit is backfill, never a critical-path task). The estimate here is "what
-// if everything ran", which is exactly the case where order matters.
-
-import { LocalHistoryProvider, type HistoryTable, type TaskNode, type VxPlugin } from '@vzn/vx'
-
-const SCHEDULE_HISTORY_PLUGIN = 'vx/schedule-history'
-
-/** Default duration when neither task history nor a workspace median exists. */
-const DEFAULT_DURATION_MS = 1000
-
-export interface ScheduleHistoryOptions {
-  /** How many recent runs per task to learn from. Default 20. */
-  readonly window?: number
-}
-
-export function scheduleHistoryPlugin(options: ScheduleHistoryOptions = {}): VxPlugin {
-  return {
-    name: SCHEDULE_HISTORY_PLUGIN,
-    async schedule(nodes, ctx) {
-      const provider =
-        options.window === undefined
-          ? new LocalHistoryProvider(ctx.localCache.dbHandle())
-          : new LocalHistoryProvider(ctx.localCache.dbHandle(), options.window)
-      let table: HistoryTable
-      try {
-        table = await provider.loadFor([...nodes.keys()])
-      } catch (err) {
-        // Failing open: a broken history read costs the ordering, never the run.
-        ctx.warn(
-          `[vx] schedule-history: falling back to the baseline order: ${err instanceof Error ? err.message : String(err)}`,
-        )
-        return undefined
-      }
-      return criticalPathPriorities([...nodes.values()], table)
-    },
-  }
-}
-
-/**
- * For each node, the expected remaining critical-path duration: its own p50
- * plus the maximum over its dependents. A node with no history takes the
- * workspace median; an empty history takes a flat default.
- */
-export function criticalPathPriorities(
-  nodes: readonly TaskNode[],
-  history: HistoryTable,
-): ReadonlyMap<string, number> {
-  const p50s: number[] = []
-  for (const h of history.values()) {
-    if (h.p50DurationMs !== undefined) p50s.push(h.p50DurationMs)
-  }
-  p50s.sort((a, b) => a - b)
-  const workspaceMedian =
-    p50s.length > 0
-      ? (p50s[Math.floor(p50s.length / 2)] ?? DEFAULT_DURATION_MS)
-      : DEFAULT_DURATION_MS
-
-  const dependentsOf = new Map<string, string[]>()
-  for (const n of nodes) {
-    for (const upstreamId of n.deps) {
-      const list = dependentsOf.get(upstreamId)
-      if (list) list.push(n.id)
-      else dependentsOf.set(upstreamId, [n.id])
-    }
-  }
-  const ownDuration = (n: TaskNode): number => history.get(n.id)?.p50DurationMs ?? workspaceMedian
-
-  // Reverse-topological pass: a node's value is final once every dependent's
-  // is, so start from the sinks (no dependents) and release each upstream
-  // when its last dependent has been scored.
-  const memo = new Map<string, number>()
-  const nodeById = new Map<string, TaskNode>(nodes.map((n) => [n.id, n]))
-  const pending = new Map<string, number>()
-  const queue: TaskNode[] = []
-  for (const n of nodes) {
-    const count = dependentsOf.get(n.id)?.length ?? 0
-    pending.set(n.id, count)
-    if (count === 0) queue.push(n)
-  }
-  let head = 0
-  while (head < queue.length) {
-    const n = queue[head++]!
-    let downstream = 0
-    for (const dep of dependentsOf.get(n.id) ?? []) {
-      const d = memo.get(dep) ?? 0
-      if (d > downstream) downstream = d
-    }
-    memo.set(n.id, ownDuration(n) + downstream)
-    for (const up of n.deps) {
-      const left = (pending.get(up) ?? 0) - 1
-      pending.set(up, left)
-      if (left === 0) {
-        const upNode = nodeById.get(up)
-        if (upNode) queue.push(upNode)
-      }
-    }
-  }
-  for (const n of nodes) if (!memo.has(n.id)) memo.set(n.id, ownDuration(n))
-  return memo
-}