@vzn/vx-dte 0.0.0 → 0.0.650

package/src/trace.ts

@@ -0,0 +1,288 @@
+// A distributed run in time, for `vx run --profile` (2026-10-23: "a
+// Chrome profile with all workers and tasks they executed in time"): Trace
+// Event Format events, one process per machine.
+// A worker's first row is its life (warm-up, idle, leave); each task gets
+// the first row free over its time there. The orchestrator's rows hold
+// what it asked and when, the tasks it held waiting for room, and its
+// restores. Times are this machine's, so a worker's are when it heard.
+
+/** One slice: a span of a row, in `performance.now()` ms. */
+interface Slice {
+  readonly track: string
+  readonly name: string
+  readonly cat: string
+  readonly from: number
+  readonly to: number
+  readonly args?: Record<string, unknown>
+  /** Slices inside it, on its row. */
+  readonly parts?: readonly { name: string; from: number; to: number }[]
+  /** Its first row, not one of its own: a worker's life. */
+  readonly life?: true
+}
+
+interface Mark {
+  readonly track: string
+  readonly name: string
+  readonly at: number
+  readonly args?: Record<string, unknown>
+}
+
+/** A task's cores on its worker over its time: the counters. */
+interface Use {
+  readonly track: string
+  readonly from: number
+  readonly to: number
+  readonly booked: number
+  readonly used: number
+}
+
+type Event = Record<string, unknown>
+
+export const ORCHESTRATOR = 'orchestrator'
+
+export class Trace {
+  private readonly slices: Slice[] = []
+  private readonly marks: Mark[] = []
+  private readonly uses: Use[] = []
+  /** Each worker's machine: cores busy, as it reported, task or not. */
+  private readonly loads: {
+    readonly track: string
+    readonly at: number
+    readonly cpu: number
+    readonly tasks: number | undefined
+  }[] = []
+  /** Each worker's time online: idle is what its tasks leave of it. */
+  private readonly online = new Map<string, { from: number; to?: number }>()
+  /** `performance.now()` here when `Date.now()` was `wall`: a worker's own clock to ours. */
+  private readonly wall = Date.now() - performance.now()
+
+  slice(s: Slice): void {
+    if (s.to >= s.from) this.slices.push(s)
+  }
+
+  mark(track: string, name: string, args?: Record<string, unknown>, at = performance.now()): void {
+    this.marks.push({ track, name, at, ...(args === undefined ? {} : { args }) })
+  }
+
+  use(u: Use): void {
+    if (u.to > u.from) this.uses.push(u)
+  }
+
+  /**
+   * Worker `track`'s machine had `cpu` cores busy at `at`, its tasks' or
+   * not, and its running tasks' process trees `tasks` of them: a Mac
+   * whose tasks used 0.65 cores read 2.3 busy and queued a 1.67-core
+   * build 65 s (main b141dd5, 2026-10-24).
+   */
+  load(track: string, cpu: number, at = performance.now(), tasks?: number): void {
+    const last = this.loads.findLast((l) => l.track === track)
+    if (last?.cpu !== cpu || last.tasks !== tasks) this.loads.push({ track, at, cpu, tasks })
+  }
+
+  /**
+   * Worker `track` joined at `at`, asked for at `askedAt` when this run
+   * started it; `booted` is the wall-clock time its `vx` started, which
+   * splits its warm-up into its machine's start (a CI queue, a checkout,
+   * an install) and vx's own boot.
+   */
+  joined(track: string, at: number, askedAt?: number, booted?: number): void {
+    this.online.set(track, { from: at })
+    if (askedAt === undefined) return
+    const boot = booted === undefined ? undefined : booted - this.wall
+    const split = boot !== undefined && boot > askedAt && boot < at
+    this.slice({
+      track,
+      name: 'warm-up',
+      cat: 'worker',
+      from: askedAt,
+      to: at,
+      life: true,
+      ...(split
+        ? {
+            parts: [
+              { name: 'machine start', from: askedAt, to: boot },
+              { name: 'vx boot + join', from: boot, to: at },
+            ],
+          }
+        : {}),
+    })
+  }
+
+  /** Worker `track` left (`how`: left, lost, stopped) at `at`. */
+  left(track: string, how: string, at = performance.now()): void {
+    const o = this.online.get(track)
+    if (o === undefined || o.to !== undefined) return
+    o.to = at
+    this.mark(track, how, undefined, at)
+  }
+
+  /** A worker asked for that never joined, from its ask to `at`. */
+  unstarted(track: string, askedAt: number, why: string, at = performance.now()): void {
+    this.slice({
+      track,
+      name: 'warm-up',
+      cat: 'worker',
+      from: askedAt,
+      to: at,
+      life: true,
+      args: { failed: why },
+    })
+  }
+
+  /** The run's events, ended at `end`: `ts` in microseconds of `performance.now()` (`TaskExecutor.profile`). */
+  events(end: number): Event[] {
+    const us = (ms: number): number => Math.round(ms * 1000)
+    const tracks = [
+      ORCHESTRATOR,
+      ...new Set(
+        // Every source of a row: a worker with no slice yet still has its idle and counters.
+        [
+          ...this.slices.map((s) => s.track),
+          ...this.marks.map((m) => m.track),
+          ...this.online.keys(),
+          ...this.uses.map((u) => u.track),
+        ]
+          .filter((t) => t !== ORCHESTRATOR)
+          .sort((a, b) => a.localeCompare(b, 'en', { numeric: true })),
+      ),
+    ]
+    const pid = new Map(tracks.map((t, i) => [t, i + 1]))
+    const events: Event[] = []
+    for (const [t, p] of pid) {
+      events.push({ ph: 'M', name: 'process_name', pid: p, tid: 0, args: { name: t } })
+      events.push({ ph: 'M', name: 'process_sort_index', pid: p, tid: 0, args: { sort_index: p } })
+      events.push({
+        ph: 'M',
+        name: 'thread_name',
+        pid: p,
+        tid: 0,
+        args: { name: t === ORCHESTRATOR ? 'run' : 'worker' },
+      })
+    }
+    // Idle: a worker's time online that no task of its covers.
+    const idle: Slice[] = []
+    for (const [track, o] of this.online) {
+      const busy = this.slices
+        .filter((s) => s.track === track && s.life !== true)
+        .map((s) => [s.from, s.to] as const)
+        .sort((a, b) => a[0] - b[0])
+      let at = o.from
+      const until = o.to ?? end
+      for (const [from, to] of busy) {
+        if (from > at)
+          idle.push({
+            track,
+            name: 'idle',
+            cat: 'idle',
+            from: at,
+            to: Math.min(from, until),
+            life: true,
+          })
+        at = Math.max(at, to)
+      }
+      if (until > at)
+        idle.push({ track, name: 'idle', cat: 'idle', from: at, to: until, life: true })
+    }
+    // Rows by first free, one set per kind (a worker's tasks, the run's
+    // waits, its restores): a slice takes the lowest of its kind whose last ended.
+    const rows = new Map<string, { tid: number; end: number }[]>()
+    const tids = new Map<string, number>()
+    for (const s of [...this.slices, ...idle].sort((a, b) => a.from - b.from)) {
+      const p = pid.get(s.track)!
+      let tid = 0
+      if (s.life !== true) {
+        const kind = `${s.track}\0${s.cat}`
+        const free = rows.get(kind) ?? []
+        rows.set(kind, free)
+        let row = free.find((r) => r.end <= s.from)
+        if (row === undefined) {
+          tid = (tids.get(s.track) ?? 0) + 1
+          tids.set(s.track, tid)
+          row = { tid, end: 0 }
+          free.push(row)
+          events.push({
+            ph: 'M',
+            name: 'thread_name',
+            pid: p,
+            tid,
+            args: { name: `${s.cat} ${free.length}` },
+          })
+        }
+        row.end = s.to
+        tid = row.tid
+      }
+      events.push({
+        ph: 'X',
+        name: s.name,
+        cat: s.cat,
+        pid: p,
+        tid,
+        ts: us(s.from),
+        dur: Math.max(0, us(s.to) - us(s.from)),
+        ...(s.args === undefined ? {} : { args: s.args }),
+      })
+      for (const part of s.parts ?? [])
+        if (part.to > part.from)
+          events.push({
+            ph: 'X',
+            name: part.name,
+            cat: s.cat,
+            pid: p,
+            tid,
+            ts: us(part.from),
+            dur: us(part.to) - us(part.from),
+          })
+    }
+    for (const m of this.marks)
+      events.push({
+        ph: 'i',
+        s: 'p',
+        name: m.name,
+        cat: 'mark',
+        pid: pid.get(m.track)!,
+        tid: 0,
+        ts: us(m.at),
+        ...(m.args === undefined ? {} : { args: m.args }),
+      })
+    // Each worker's cores: booked by the run and used by its tasks, as they change.
+    for (const track of new Set(this.uses.map((u) => u.track))) {
+      const steps = this.uses
+        .filter((u) => u.track === track)
+        .flatMap((u) => [
+          [u.from, u.booked, u.used],
+          [u.to, -u.booked, -u.used],
+        ])
+        .sort((a, b) => a[0]! - b[0]!)
+      let booked = 0
+      let used = 0
+      for (const [at, b, u] of steps) {
+        booked += b!
+        used += u!
+        events.push({
+          ph: 'C',
+          name: 'cores',
+          pid: pid.get(track)!,
+          tid: 0,
+          ts: us(at!),
+          args: { booked: round(booked), used: round(used) },
+        })
+      }
+    }
+    for (const l of this.loads) {
+      const id = pid.get(l.track)
+      if (id !== undefined)
+        events.push({
+          ph: 'C',
+          name: 'machine',
+          pid: id,
+          tid: 0,
+          ts: us(l.at),
+          args: { busy: round(l.cpu), ...(l.tasks === undefined ? {} : { tasks: round(l.tasks) }) },
+        })
+    }
+    return events
+  }
+}
+
+/** Two decimals, and no `-0` or float dust from adding and taking away. */
+const round = (n: number): number => Math.max(0, Math.round(n * 100) / 100)

package/src/tree.ts

@@ -0,0 +1,78 @@
+// What a worker must have checked out: the tracked files as the run sees
+// them. Workers compare trees, not commits, so a run on uncommitted changes
+// still matches the worktrees `local()` makes from them.
+
+import { copyFile, mkdtemp, rm, stat, utimes } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * A commit of the tracked files as they are now (`HEAD`'s when none changed),
+ * and its tree; both empty when git cannot say.
+ */
+export async function snapshot(root: string): Promise<{ commit: string; tree: string }> {
+  const none = { commit: '', tree: '' }
+  const head = (await git(['rev-parse', '--verify', '-q', 'HEAD^{commit}'], root))?.trim()
+  if (head === undefined || head === '') return none
+  // The working tree's tracked files staged into a copy of the index, which
+  // leaves the index and the working tree as they are. `git stash create`
+  // did the same, but refused an intent-to-add entry (`git add -N`), and
+  // HEAD stood in for the changes (2026-10-28).
+  const index = (
+    await git(['rev-parse', '--path-format=absolute', '--git-path', 'index'], root)
+  )?.trim()
+  if (index === undefined) return none
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'vx-dte-index-'))
+  try {
+    const env = { GIT_INDEX_FILE: path.join(dir, 'index') }
+    try {
+      await copyFile(index, env.GIT_INDEX_FILE)
+      // The copy keeps the index's mtime (as core's refreshedIndex): git
+      // trusts an entry's stat only while its file is older than the index,
+      // and a fresh mtime took a same-size edit made in the tick the index
+      // was written for clean, its old blob in the tree (2026-10-29).
+      const st = await stat(index)
+      await utimes(env.GIT_INDEX_FILE, st.atime, st.mtime)
+    } catch {
+      // quiet: no index yet, so HEAD's tree is its tracked set.
+      if ((await git(['read-tree', head], root, env)) === undefined) return none
+    }
+    if ((await git(['add', '-u', '--', ':/'], root, env)) === undefined) return none
+    const tree = (await git(['write-tree'], root, env))?.trim()
+    if (tree === undefined || tree === '') return none
+    const was = (await git(['rev-parse', `${head}^{tree}`], root))?.trim()
+    if (tree === was) return { commit: head, tree }
+    // The commit is nobody's, so it needs no one's identity: a CI runner
+    // with none made `git stash create` fail (2026-10-28).
+    const commit = (
+      await git(['commit-tree', tree, '-p', head, '-m', 'vx dte'], root, IDENTITY)
+    )?.trim()
+    return commit === undefined || commit === '' ? none : { commit, tree }
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+
+const IDENTITY = {
+  GIT_AUTHOR_NAME: 'vx',
+  GIT_AUTHOR_EMAIL: 'vx@localhost',
+  GIT_COMMITTER_NAME: 'vx',
+  GIT_COMMITTER_EMAIL: 'vx@localhost',
+}
+
+/** git's stdout, or undefined when it failed. */
+async function git(
+  args: string[],
+  cwd: string,
+  env?: Record<string, string>,
+): Promise<string | undefined> {
+  const p = Bun.spawn(['git', ...args], {
+    cwd,
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'ignore',
+    ...(env === undefined ? {} : { env: { ...process.env, ...env } }),
+  })
+  const [out, code] = await Promise.all([new Response(p.stdout).text(), p.exited])
+  return code === 0 ? out : undefined
+}

package/src/usage.ts

@@ -0,0 +1,135 @@
+// What one machine did in a distributed run, from its tasks' results: the
+// final summary's per-worker block.
+
+interface Span {
+  readonly start: number
+  readonly end: number
+  readonly cores: number
+  readonly memory: number
+}
+
+export interface UsageStats {
+  readonly onlineMs: number
+  /** Time with at least one task running. */
+  readonly busyMs: number
+  /** Cores and bytes in use at once, at the most and on average over its time online. */
+  readonly cpuPeak: number
+  readonly cpuAvg: number
+  readonly memoryPeak: number
+  readonly memoryAvg: number
+  /** Core-time its tasks used over the core-time it had. */
+  readonly utilization: number
+  readonly cpuMs: number
+  /** Cores the run held for its tasks, on average over its time online: what packing gave it. */
+  readonly bookedAvg: number
+  /**
+   * Cores busy on its machine, any process's, on average since its worker
+   * started, as its last frame said: what `cpuAvg` leaves out (a Mac's
+   * indexer, a task's orphans). Undefined when it said none.
+   */
+  readonly machineAvg?: number | undefined
+}
+
+export class Usage {
+  done = 0
+  failed = 0
+  /** Killed by the run's stop, as core counts a task `aborted`. */
+  aborted = 0
+  /** Messages and bytes the run sent it, and those it sent the run. */
+  messagesIn = 0
+  bytesIn = 0
+  messagesOut = 0
+  bytesOut = 0
+  /** When it left, if before the run ended. */
+  to: number | undefined
+  private readonly spans: Span[] = []
+  private booked = 0
+  private bookedMs = 0
+  private bookedAt = 0
+  /** Its machine's busy cores on average, as its last frame said. */
+  machineAvg: number | undefined
+
+  constructor(readonly from: number = performance.now()) {}
+
+  /**
+   * A task it finished, as it ends: on it `from` its send (else its
+   * command's duration), its CPU time spread over that. Its command alone
+   * left the restore of its dependencies and its save idle: a worker
+   * busy all along read 10 s idle (2026-10-24).
+   */
+  record(
+    r: {
+      readonly exitCode: number
+      readonly signal?: string | number | undefined
+      readonly timedOut?: boolean | undefined
+      readonly durationMs: number
+      readonly cpuMs?: number | undefined
+      readonly peakRssBytes?: number | undefined
+    },
+    from?: number,
+  ): void {
+    if (r.exitCode === 0) this.done++
+    else if ((r.signal === 'SIGINT' || r.signal === 'SIGTERM') && r.timedOut !== true)
+      this.aborted++
+    else this.failed++
+    const end = performance.now()
+    const ms = Math.max(1, from === undefined ? r.durationMs : end - from)
+    this.spans.push({
+      start: end - ms,
+      end,
+      cores: (r.cpuMs ?? 0) / ms,
+      memory: r.peakRssBytes ?? 0,
+    })
+  }
+
+  /** The run now holds `cores` more of it for its tasks (fewer when negative). */
+  book(cores: number, at: number = performance.now()): void {
+    this.bookedMs += this.booked * (at - this.bookedAt)
+    this.bookedAt = at
+    this.booked += cores
+  }
+
+  stats(cores: number, until: number): UsageStats {
+    // Never before it joined: a time from before would read it online 1 ms.
+    const end = Math.max(this.from, this.to ?? until)
+    const onlineMs = Math.max(1, end - this.from)
+    // Ends before starts at one instant: back to back is not at once.
+    const events = this.spans
+      .flatMap((s) => [[s.start, 1, s] as const, [s.end, -1, s] as const])
+      .sort((a, b) => a[0] - b[0] || a[1] - b[1])
+    let running = 0
+    let cpu = 0
+    let memory = 0
+    let cpuPeak = 0
+    let memoryPeak = 0
+    let busyMs = 0
+    let last = 0
+    for (const [at, d, s] of events) {
+      if (running > 0) busyMs += at - last
+      last = at
+      running += d
+      cpu += d * s.cores
+      memory += d * s.memory
+      cpuPeak = Math.max(cpuPeak, cpu)
+      memoryPeak = Math.max(memoryPeak, memory)
+    }
+    let cpuMs = 0
+    let memoryMs = 0
+    for (const s of this.spans) {
+      cpuMs += s.cores * (s.end - s.start)
+      memoryMs += s.memory * (s.end - s.start)
+    }
+    return {
+      onlineMs,
+      busyMs,
+      cpuPeak,
+      cpuAvg: cpuMs / onlineMs,
+      memoryPeak,
+      memoryAvg: memoryMs / onlineMs,
+      utilization: cpuMs / (cores * onlineMs),
+      cpuMs,
+      bookedAvg: (this.bookedMs + this.booked * Math.max(0, end - this.bookedAt)) / onlineMs,
+      machineAvg: this.machineAvg,
+    }
+  }
+}

package/src/warm-ups.ts

@@ -0,0 +1,85 @@
+// Each size's warm-up across runs, through the workspace's cache (M,
+// 2026-10-23: "planner needs to use warmup from history"): a CI run writes
+// the least time a worker of each size took to join under its commit, over
+// the sizes it read; a run reads its newest first-parent ancestor's. Before
+// any worker of a size joins, the plan waits that long for one, not 20 s:
+// main fd5c72e's small workers joined in 15 s, its mac in 27 s. The blob is
+// untrusted: it only sizes a plan, and a bad one reads as none.
+
+import type { PluginCache } from '@vzn/vx'
+
+/** Commits walked back from HEAD for a blob. */
+const WALK = 6
+const MAX_BYTES = 64 * 1024
+const MAX_SIZES = 256
+const MAX_MS = 3_600_000
+
+const keyOf = (sha: string): string => `warm-ups\0${sha}`
+
+/** `{ version: 1, sizes: { name: ms } }`'s warm-ups, each ms finite in [0, 1 h]; null for anything else. */
+export function parseWarmUps(bytes: Uint8Array): Map<string, number> | null {
+  if (bytes.byteLength > MAX_BYTES) return null
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(bytes))
+    // quiet: not JSON reads as no blob
+  } catch {
+    return null
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const { version, sizes } = parsed as { version?: unknown; sizes?: unknown }
+  if (version !== 1 || typeof sizes !== 'object' || sizes === null || Array.isArray(sizes))
+    return null
+  const entries = Object.entries(sizes)
+  if (entries.length > MAX_SIZES) return null
+  const out = new Map<string, number>()
+  for (const [name, ms] of entries)
+    if (typeof ms === 'number' && Number.isFinite(ms) && ms >= 0 && ms <= MAX_MS) out.set(name, ms)
+  return out
+}
+
+/** HEAD and its first-parent ancestors, newest first; none outside git. */
+async function commits(root: string): Promise<string[]> {
+  try {
+    const proc = Bun.spawn({
+      cmd: ['git', 'rev-list', '--first-parent', `--max-count=${WALK}`, 'HEAD'],
+      cwd: root,
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    const [out, exit] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+    return exit === 0 ? out.split('\n').filter((l) => l !== '') : []
+    // quiet: a local git read; no commits reads no blob
+  } catch {
+    return []
+  }
+}
+
+/** The newest warm-ups an ancestor's run wrote, the base branch's on a scoped run. */
+export async function readWarmUps(cache: PluginCache, root: string): Promise<Map<string, number>> {
+  const keys = (await commits(root)).map(keyOf)
+  if (keys.length === 0) return new Map()
+  const held = await cache.hasMany(keys, false)
+  for (const key of keys) {
+    if (held !== null && !held.has(key)) continue
+    const bytes = await cache.get(key, false)
+    const got = bytes === null ? null : parseWarmUps(bytes)
+    if (got !== null) return got
+  }
+  return new Map()
+}
+
+/** `learned` with this run's own over it, under HEAD: once per commit, as every entry is. */
+export async function writeWarmUps(
+  cache: PluginCache,
+  root: string,
+  learned: ReadonlyMap<string, number>,
+  run: ReadonlyMap<string, number>,
+): Promise<void> {
+  if (run.size === 0) return
+  const [head] = await commits(root)
+  if (head === undefined) return
+  const sizes: Record<string, number> = {}
+  for (const [name, ms] of [...learned, ...run]) sizes[name] = Math.round(ms)
+  await cache.put(keyOf(head), new TextEncoder().encode(JSON.stringify({ version: 1, sizes })))
+}