@vzn/vx 0.0.649 → 0.0.650

package/src/history/history.ts

@@ -12,7 +12,7 @@
 // (zero-config); the interface is the seam a plugin fills for any other.
 
 import type { Database } from 'bun:sqlite'
-import { branchSource, EXECUTED_RUNS_SQL } from '../cache/index.js'
+import { branchSource, type Cache, EXECUTED_RUNS_SQL, indexDb } from '../cache/index.js'
 import { isMeasure, splitTaskId } from '../util/index.js'
 import { failureModeOf, mixedOutcomeKeysSql } from './failure-mode.js'
 import type { FailureMode } from './failure-mode.js'
@@ -117,8 +117,40 @@ export class EmptyHistoryProvider implements HistoryProvider {
   }
 }
 
+/** One local cache's run history, read and written by core (`localHistory`): plain rows out, no handle. */
+export interface LocalHistory extends HistoryProvider {
+  /** Each task's measured need (`p50DurationMs`, peak cores and memory). */
+  resourcesFor(taskIds: readonly string[]): Promise<ReadonlyMap<string, TaskResources>>
+  /** Whether timings of commit `sha` were imported. */
+  hasImported(sha: string): boolean
+  /** Keep commit `sha`'s timings (task id → ms) and needs as forecast rows. */
+  importTimings(
+    sha: string,
+    timings: ReadonlyMap<string, number>,
+    needs?: ReadonlyMap<string, TaskResources>,
+    defs?: ReadonlyMap<string, string>,
+  ): void
+}
+
+export interface LocalHistoryOptions {
+  /** The newest invocations a read sees (default 50). */
+  readonly recent?: number | undefined
+  /** The run's branch (`currentBranch`); undefined: a read sees every branch's timings. */
+  readonly branch?: string | null | undefined
+  /** Each task's definition (`taskDefinitions`): given, a task reads only rows of it as it is now. */
+  readonly defs?: ReadonlyMap<string, string> | undefined
+}
+
+/**
+ * The run history in `cache`'s index. A plugin reads history only through
+ * this: core owns every read and write of cache.db (2026-10-29).
+ */
+export function localHistory(cache: Cache, options: LocalHistoryOptions = {}): LocalHistory {
+  return new LocalHistoryProvider(indexDb(cache), options.recent, options.branch, options.defs)
+}
+
 /** Reads from the orchestrator's local SQLite cache.db. */
-export class LocalHistoryProvider implements HistoryProvider {
+export class LocalHistoryProvider implements LocalHistory {
   constructor(
     private readonly db: Database,
     readonly recent: number = DEFAULT_RECENT,

package/src/history/index.ts

@@ -6,6 +6,9 @@ export {
   EmptyHistoryProvider,
   type HistoryProvider,
   type HistoryTable,
+  type LocalHistory,
+  type LocalHistoryOptions,
+  localHistory,
   LocalHistoryProvider,
   PASS_STATUSES,
   type TaskHistory,

package/src/index.ts

@@ -66,8 +66,15 @@ export { run, planRun, prepareRun } from './orchestrator/index.js'
 // (`@vzn/vx-history` does; a plugin package reaches core only
 // through this façade, which is what put these here).
 export { currentBranch } from './orchestrator/index.js'
-export { LocalHistoryProvider } from './history/index.js'
-export type { HistoryProvider, HistoryTable, TaskHistory, TaskResources } from './history/index.js'
+export { localHistory } from './history/index.js'
+export type {
+  HistoryProvider,
+  HistoryTable,
+  LocalHistory,
+  LocalHistoryOptions,
+  TaskHistory,
+  TaskResources,
+} from './history/index.js'
 export type { PreparedRun } from './orchestrator/index.js'
 // `RunOptions.affected`: what `--affected`'s diff changed, per project.
 export type { AffectedChanges } from './workspace/index.js'

package/src/orchestrator/doctor.ts

@@ -7,7 +7,7 @@
 
 import os from 'node:os'
 import path from 'node:path'
-import { Cache, CACHE_VERSION, SCHEMA_VERSION } from '../cache/index.js'
+import { indexDb, Cache, CACHE_VERSION, SCHEMA_VERSION } from '../cache/index.js'
 import { PLUGIN_HOOKS, type WorkspaceConfig } from '../config.js'
 import {
   cgroupCpuQuota,
@@ -245,7 +245,7 @@ async function collectWorkspaceInfo(
       indexStore = cache.storeDir
       stats = cache.stats()
       orphans = await cache.orphanStats()
-      flaky = flakyTasks(cache.dbHandle())
+      flaky = flakyTasks(indexDb(cache))
     } finally {
       cache.close()
     }

package/src/orchestrator/hit-restore.ts

@@ -458,6 +458,9 @@ function hitOutcome(restore: RestoreHitArgs, restored: boolean): TaskOutcome {
     ...(hit.cpuMs !== undefined ? { storedCpuMs: hit.cpuMs } : {}),
     ...(hit.peakRssBytes !== undefined ? { storedPeakRssBytes: hit.peakRssBytes } : {}),
     ...(hit.sizeBytes !== undefined ? { artifactBytes: hit.sizeBytes } : {}),
+    ...(hit.outputRows !== undefined
+      ? { outputBytes: hit.outputRows.reduce((n, r) => n + r.size, 0) }
+      : {}),
     ...(hit.fetchMs !== undefined ? { fetchMs: hit.fetchMs } : {}),
     hash,
     restored: restored || hit.source === 'remote',

package/src/orchestrator/index.ts

@@ -146,7 +146,6 @@ export {
   type TaskLog,
   taskLog,
 } from './run-failures.js'
-export { type RunStep, runSteps, runWarnings } from './run-steps.js'
 export { resolveRunId, shortRunId } from './run-id.js'
 export { collectInfo, type CollectInfoOptions, type InfoFacts } from './doctor.js'
 export { localFloor, type LocalFloor } from './local-floor.js'

package/src/orchestrator/live-usage.ts

@@ -0,0 +1,93 @@
+// The live list's `cpu` and `mem`: what each running task's process tree
+// uses now. Looked at on a timer only once the list asks for a row, so a
+// run with no live list (a pipe, CI) registers pids and reads nothing.
+// The look is async and off the dispatch path: a slow one skips a tick.
+
+import { sampleTrees, type TreeUsage } from '../exec/index.js'
+import type { LiveUsage } from '../report/index.js'
+
+/** How often a tracked tree is looked at while the live list shows. */
+const LOOK_MS = 500
+
+type Every = (ms: number, fn: () => Promise<void>) => () => void
+
+const everyInterval: Every = (ms, fn) => {
+  const timer = setInterval(() => void fn(), ms)
+  timer.unref()
+  return () => clearInterval(timer)
+}
+
+interface Tracked {
+  pid: number
+  last?: { ts: number; cpuMs: number }
+  now?: LiveUsage
+}
+
+export function createLiveUsage(
+  opts: {
+    every?: Every
+    now?: () => number
+    sample?: (pids: number[]) => Promise<Map<number, TreeUsage>>
+  } = {},
+): {
+  track(taskId: string, pid: number): () => void
+  usage(taskId: string): LiveUsage | undefined
+} {
+  const every = opts.every ?? everyInterval
+  const now = opts.now ?? Date.now
+  const sample = opts.sample ?? sampleTrees
+  const tracked = new Map<string, Tracked>()
+  let asked = false
+  let looking = false
+  let stop: (() => void) | undefined
+
+  const look = async (): Promise<void> => {
+    if (looking) return
+    looking = true
+    try {
+      const entries = [...tracked]
+      const usage = await sample(entries.map(([, t]) => t.pid))
+      const ts = now()
+      for (const [id, t] of entries) {
+        const u = usage.get(t.pid)
+        if (u === undefined || tracked.get(id) !== t) continue
+        // A descendant that exited takes its CPU out of the live sum, so
+        // an interval can read negative: none is shown below zero.
+        if (t.last !== undefined && ts > t.last.ts) {
+          const cores = Math.max(0, (u.cpuMs - t.last.cpuMs) / (ts - t.last.ts))
+          t.now = { cores: Math.round(cores * 100) / 100, rssBytes: u.rssBytes }
+        }
+        t.last = { ts, cpuMs: u.cpuMs }
+      }
+    } catch {
+      // A failed look is a missing point, never a broken run.
+    } finally {
+      looking = false
+    }
+  }
+  const start = (): void => {
+    if (asked && stop === undefined && tracked.size > 0) stop = every(LOOK_MS, look)
+  }
+
+  return {
+    track(taskId, pid) {
+      const t: Tracked = { pid }
+      tracked.set(taskId, t)
+      start()
+      return () => {
+        if (tracked.get(taskId) === t) tracked.delete(taskId)
+        if (tracked.size === 0 && stop !== undefined) {
+          stop()
+          stop = undefined
+        }
+      }
+    },
+    usage(taskId) {
+      if (!asked) {
+        asked = true
+        start()
+      }
+      return tracked.get(taskId)?.now
+    },
+  }
+}

package/src/orchestrator/lockfile-claim.ts

@@ -7,14 +7,15 @@
 // fallback for a project the file does not list and the `--affected`
 // diff are one implementation here, so a third lockfile is a parser.
 //
-// The digests are memoised on disk under the cache dir by the file's
-// xxh3, so a warm run pays one read + hash + a small JSON read, never a
-// parse; within one process (a run, a watch cycle) the file's size,
+// The digests are memoised in cache.db (`lockfile_memos`, one row per
+// lockfile and claimant) by the file's xxh3, so a warm run pays one read +
+// hash + one row read, never a parse; within one process (a run, a watch cycle) the file's size,
 // mtime, ctime and inode gate even the read; and per run the read happens once (a WeakMap
 // on the context core hands every `key` call of a run).
 
 import path from 'node:path'
-import { rename, stat } from 'node:fs/promises'
+import { stat } from 'node:fs/promises'
+import { type LockfileMemo, readLockfileMemo, writeLockfileMemo } from '../cache/index.js'
 import { relPosix, UserError, xxh3, xxh3hex } from '../util/index.js'
 import type { TaskNode } from '../graph/index.js'
 import type {
@@ -62,6 +63,12 @@ export interface LockfileClaimOptions {
    * parse. Called once per distinct content, under either scope.
    */
   readonly importers?: (text: string) => ReadonlyMap<string, LockfileImporter>
+  /**
+   * Each importer's recorded dependency names, from the same text, kept in
+   * the memo so a staleness check reads them without a parse. Called once
+   * per distinct content.
+   */
+  readonly recorded?: (text: string) => ReadonlyMap<string, readonly string[]>
 }
 
 /**
@@ -89,6 +96,11 @@ export interface LockfileClaimHooks {
     readonly workspaceRoot: string
     readonly cacheDir: string
   }): Promise<ReadonlyMap<string, LockfileImporter> | undefined>
+  /** `recorded`'s answer for the file as it is now, as `importers` reads it; undefined when the file is absent or `recorded` is unset. */
+  recorded(ctx: {
+    readonly workspaceRoot: string
+    readonly cacheDir: string
+  }): Promise<ReadonlyMap<string, ReadonlySet<string>> | undefined>
 }
 
 interface Digests {
@@ -96,16 +108,7 @@ interface Digests {
   readonly lock: string
   readonly importers: ReadonlyMap<string, string>
   readonly edges: ReadonlyMap<string, LockfileImporter>
-}
-
-interface Memo {
-  version: number
-  claimant: string
-  lock: string
-  /** `extraFiles` → content hash when the digests were computed. */
-  extras?: Record<string, string>
-  importers: Record<string, string>
-  edges?: Record<string, LockfileImporter>
+  readonly recorded: ReadonlyMap<string, ReadonlySet<string>> | undefined
 }
 
 /**
@@ -202,6 +205,7 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       String(digest),
       String(options.extraFiles ?? ''),
       String(options.importers ?? ''),
+      String(options.recorded ?? ''),
     ].join('\0'),
   )
   if (scope !== 'project' && scope !== 'workspace') {
@@ -216,8 +220,18 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       extras: readonly string[]
       extraStats: Readonly<Record<string, string>>
       digests: Digests
+      /** The memo a run found no index to keep in (a discover before the first run's open). */
+      unsaved?: LockfileMemo
     }
   >()
+  // Workspace scope with nothing else to keep has nothing a memo saves.
+  const memoises =
+    scope === 'project' || options.importers !== undefined || options.recorded !== undefined
+  const readMemo = (cacheDir: string, lock: string) => {
+    const memo = readLockfileMemo(cacheDir, file, claimant)
+    if (memo === undefined || memo.version !== version || memo.lock !== lock) return undefined
+    return memo
+  }
   // Per run: every `key` call of one run gets the same context object.
   const perRun = new WeakMap<object, Promise<Digests>>()
 
@@ -227,7 +241,12 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
     try {
       identity = identityOf(await stat(full))
     } catch {
-      const digests: Digests = { lock: '', importers: new Map(), edges: new Map() }
+      const digests: Digests = {
+        lock: '',
+        importers: new Map(),
+        edges: new Map(),
+        recorded: undefined,
+      }
       seen.set(workspaceRoot, { identity: 'gone', extras: [], extraStats: {}, digests })
       return digests
     }
@@ -235,26 +254,30 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
     if (last !== undefined && last.identity === identity) {
       const now = await statsOf(workspaceRoot, last.extras)
       if (now.every((s, i) => s === last.extraStats[last.extras[i]!])) {
+        if (last.unsaved !== undefined && writeLockfileMemo(cacheDir, file, claimant, last.unsaved))
+          delete last.unsaved
         return last.digests
       }
     }
     const bytes = await Bun.file(full).bytes()
     const lockHash = xxh3hex(bytes)
-    const memoFile = path.join(cacheDir, 'lockfile-claims', `${file}.json`)
     // The extra files the last digest read, and their hashes now: a warm run
     // re-hashes the files the memo names and never parses to learn them.
-    const memo = await readMemo(memoFile, version, claimant, lockHash)
+    const memo = memoises ? readMemo(cacheDir, lockHash) : undefined
     let extras: Record<string, string> = {}
     let extraStats: Record<string, string> = {}
     let importers: ReadonlyMap<string, string> | undefined
     let edges: ReadonlyMap<string, LockfileImporter> = new Map()
+    let recorded: ReadonlyMap<string, readonly string[]> | undefined
+    let unsaved: LockfileMemo | undefined
     if (memo !== undefined) {
       const now = await hashExtras(workspaceRoot, Object.keys(memo.extras))
       if (Object.entries(memo.extras).every(([rel, h]) => now.hashes[rel] === h)) {
         extras = memo.extras
         extraStats = now.stats
-        importers = memo.importers
-        edges = memo.edges
+        importers = new Map(Object.entries(memo.importers))
+        edges = new Map(Object.entries(memo.edges as Record<string, LockfileImporter>))
+        recorded = memo.recorded === undefined ? undefined : new Map(Object.entries(memo.recorded))
       }
     }
     if (importers === undefined) {
@@ -268,9 +291,17 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
           ? new Map<string, string>()
           : digest(text, new Map(Object.entries(extras)))
       edges = options.importers?.(text) ?? new Map()
-      // Workspace scope with no edges to keep has nothing a memo saves.
-      if (scope === 'project' || options.importers !== undefined) {
-        await writeMemo(memoFile, { version, claimant, lock: lockHash }, extras, importers, edges)
+      recorded = options.recorded?.(text)
+      if (memoises) {
+        const kept: LockfileMemo = {
+          version,
+          lock: lockHash,
+          extras,
+          importers: Object.fromEntries(importers),
+          edges: Object.fromEntries(edges),
+          ...(recorded !== undefined ? { recorded: Object.fromEntries(recorded) } : {}),
+        }
+        if (!writeLockfileMemo(cacheDir, file, claimant, kept)) unsaved = kept
       }
     }
     const rels = Object.keys(extras)
@@ -278,8 +309,22 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       rels.length === 0
         ? lockHash
         : xxh3hex([lockHash, ...rels.map((r) => `${r}\0${extras[r]}`)].join('\0'))
-    const digests: Digests = { lock, importers, edges }
-    seen.set(workspaceRoot, { identity, extras: rels, extraStats, digests })
+    const digests: Digests = {
+      lock,
+      importers,
+      edges,
+      recorded:
+        recorded === undefined
+          ? undefined
+          : new Map([...recorded].map(([i, names]) => [i, new Set(names)])),
+    }
+    seen.set(workspaceRoot, {
+      identity,
+      extras: rels,
+      extraStats,
+      digests,
+      ...(unsaved !== undefined ? { unsaved } : {}),
+    })
     return digests
   }
   const loadOnce = (ctx: KeyHookContext): Promise<Digests> => {
@@ -339,8 +384,7 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
             // parser: `--affected` asks on every diff, and a cold parse of
             // a large lockfile was most of its selection's cost.
             async extraFiles(_file: string, bytes: Uint8Array, ctx: FingerprintContext) {
-              const memoFile = path.join(ctx.cacheDir, 'lockfile-claims', `${file}.json`)
-              const memo = await readMemo(memoFile, version, claimant, xxh3hex(bytes))
+              const memo = memoises ? readMemo(ctx.cacheDir, xxh3hex(bytes)) : undefined
               return memo !== undefined
                 ? Object.keys(memo.extras)
                 : options.extraFiles!(decode(bytes))
@@ -360,6 +404,10 @@ export function lockfileClaim(options: LockfileClaimOptions): LockfileClaimHooks
       const digests = await load(ctx.workspaceRoot, ctx.cacheDir)
       return digests.lock === '' ? undefined : digests.edges
     },
+    async recorded(ctx) {
+      const digests = await load(ctx.workspaceRoot, ctx.cacheDir)
+      return digests.lock === '' ? undefined : digests.recorded
+    },
   }
 }
 
@@ -394,59 +442,6 @@ function importerOf(workspaceRoot: string, projectDir: string): string {
   return relPosix(workspaceRoot, projectDir) || '.'
 }
 
-async function readMemo(
-  memoFile: string,
-  version: number,
-  claimant: string,
-  lock: string,
-): Promise<
-  | {
-      extras: Record<string, string>
-      importers: Map<string, string>
-      edges: Map<string, LockfileImporter>
-    }
-  | undefined
-> {
-  try {
-    const memo = (await Bun.file(memoFile).json()) as Memo
-    if (memo.version !== version || memo.claimant !== claimant || memo.lock !== lock) {
-      return undefined
-    }
-    return {
-      extras: memo.extras ?? {},
-      importers: new Map(Object.entries(memo.importers)),
-      edges: new Map(Object.entries(memo.edges ?? {})),
-    }
-  } catch {
-    return undefined
-  }
-}
-
-async function writeMemo(
-  memoFile: string,
-  identity: Pick<Memo, 'version' | 'claimant' | 'lock'>,
-  extras: Record<string, string>,
-  importers: ReadonlyMap<string, string>,
-  edges: ReadonlyMap<string, LockfileImporter>,
-): Promise<void> {
-  const memo: Memo = {
-    ...identity,
-    extras,
-    importers: Object.fromEntries(importers),
-    ...(edges.size > 0 ? { edges: Object.fromEntries(edges) } : {}),
-  }
-  // Write-then-rename: a reader never sees a half-written memo, and two
-  // concurrent runs each land a whole one.
-  const tmp = `${memoFile}.tmp-${process.pid}-${Date.now()}`
-  try {
-    await Bun.write(tmp, JSON.stringify(memo))
-    await rename(tmp, memoFile)
-  } catch {
-    // The memo is a speed-up, never a requirement: the digests are
-    // computed either way, and the next run computes them again.
-  }
-}
-
 function decode(bytes: Uint8Array): string {
   return new TextDecoder().decode(bytes)
 }

package/src/orchestrator/plugin.ts

@@ -527,9 +527,9 @@ export interface AdmitContext {
 }
 
 export interface ScheduleHookContext extends BaseContext {
-  /** The run's local cache handle — its `dbHandle()` holds the run history a policy can learn from. */
+  /** The run's local cache: `localHistory(localCache)` reads the run history a policy learns from. */
   readonly localCache: Cache
-  /** The run's branch (`currentBranch`), the timings a forecast reads first: pass it to `LocalHistoryProvider`. */
+  /** The run's branch (`currentBranch`), the timings a forecast reads first: pass it to `localHistory`. */
   readonly branch: string | null
   /** The refs the run reads, in order (`CacheContext.refs`): a remote's timings are read by them too. */
   readonly refs: readonly string[]

package/src/orchestrator/prepare.ts

@@ -20,6 +20,7 @@ import {
   UserError,
 } from '../util/index.js'
 import {
+  indexDb,
   Cache,
   type CacheLayer,
   applyCacheFlags,
@@ -834,7 +835,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       let own = pluginCaches.get(plugin)
       if (own === undefined) {
         own = pluginCache(plugin, {
-          db: localCache.dbHandle(),
+          db: indexDb(localCache),
           policy,
           remotes,
           scope: cacheScope,