@vzn/vx 0.0.16 → 0.0.21

package/src/orchestrator/plan.ts

@@ -14,6 +14,7 @@
 import type { CacheLayer, CachePolicy, GitFilesCache } from '../cache/index.js'
 import { FULL_CACHE_POLICY } from '../cache/index.js'
 import { isGroupTask, runGraph, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import type { HistoryProvider } from './history.js'
 import { computeGroupHash, computeTaskHash } from './task-hash.js'
 
 export type CacheStatus =
@@ -29,14 +30,67 @@ export interface PlannedTask {
   cacheStatus: CacheStatus
   /** Sorted task ids this task depends on (same as TaskNode.deps). */
   deps: readonly string[]
+  /**
+   * The task's typical executed duration (wall-clock p50 over its recent
+   * non-hit runs in the local cache.db), when history exists. Attached to
+   * every real task so a would-run task can show what it usually costs.
+   */
+  p50Ms?: number
+  /**
+   * Name of the executor this task would be PLACED on. Attached only when
+   * the workspace declares more than one executor — with a single one every
+   * line would carry the same label and say nothing. Absent for group tasks
+   * and persistent tasks, which never reach an executor.
+   */
+  executor?: string
+  /**
+   * `'deferred'` when this task's outputs would stay in the remote store
+   * (`--download=none` / `toplevel`). Attached only when it is TRUE — an
+   * eager task is the default and saying so on every line says nothing.
+   */
+  download?: 'deferred'
+}
+
+/**
+ * Time prediction over the plan: what would this run cost? Derived purely
+ * from recorded history (each task's p50) — cache hits and groups cost 0
+ * (a restore is a tar extract, near-instant next to execution).
+ */
+export interface PlanPrediction {
+  /** Predicted wall-clock: the longest dependency chain of would-run cost. */
+  wallMs: number
+  /** Total predicted execution across would-run tasks (the CPU-time story). */
+  workMs: number
+  /** Would-run tasks with NO history — their cost is unknown and counted as
+   *  0, so wallMs/workMs are lower bounds when this is > 0. */
+  unknownCount: number
 }
 
 export interface RunPlan {
   tasks: PlannedTask[]
+  /** Present when a history provider was available and usable. */
+  predicted?: PlanPrediction
+  /**
+   * Requested task specs that matched no project. Non-empty means the
+   * plan was abandoned: planning what WOULD run is meaningless when the
+   * equivalent `vx run` would refuse to start.
+   */
+  unresolvedTasks?: readonly string[]
+  /**
+   * Producers `--download` WANTED to defer but could not, mapped to why.
+   * Without this the gate is invisible: a user asks for `--download=none`,
+   * gets no deferral, and has nothing to read. Empty/absent under
+   * `--download=all`, which defers nothing by definition.
+   */
+  downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
 }
 
 export interface PlanArgs {
   nodes: Map<string, TaskNode>
+  /** Per-task `--download` decision, when the policy is not `all`. */
+  downloadOf?: (id: string) => 'eager' | 'deferred' | 'never' | undefined
+  /** See `RunPlan.downloadDowngrades`. */
+  downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
   workspaceRoot: string
   workspaceFingerprint: string
   cache: CacheLayer
@@ -45,6 +99,11 @@ export interface PlanArgs {
   nestedDirsByProject: Map<string, string[]>
   gitFilesCache?: GitFilesCache
   hashCache?: import('./task-hash.js').HashCache
+  /** When provided, per-task p50s are attached and `RunPlan.predicted` is
+   *  computed. Failing open: a history error yields a plan without them. */
+  history?: HistoryProvider
+  /** Placement lookup (`run.ts`), passed only when >1 executor is declared. */
+  executorOf?: (id: string) => string | undefined
 }
 
 /**
@@ -108,14 +167,98 @@ export async function plan(args: PlanArgs): Promise<RunPlan> {
     const o = outcomes.get(id)
     const node = args.nodes.get(id)
     if (!o || !node) continue
+    const executor = args.executorOf?.(id)
     tasks.push({
       node,
       hash: o.hash ?? '',
       cacheStatus: cacheStatusById.get(id) ?? 'no-cache',
       deps: node.deps,
+      ...(executor !== undefined ? { executor } : {}),
+      ...(args.downloadOf?.(id) === 'deferred' ? { download: 'deferred' as const } : {}),
     })
   }
-  return { tasks }
+
+  if (args.history !== undefined) {
+    try {
+      const realIds = tasks.filter((t) => t.cacheStatus !== 'group').map((t) => t.node.id)
+      const table = await args.history.loadFor(realIds)
+      for (const t of tasks) {
+        const p50 = table.get(t.node.id)?.p50DurationMs
+        if (p50 !== undefined) t.p50Ms = p50
+      }
+      return { tasks, predicted: predictPlan(tasks), ...downgradeField(args) }
+    } catch {
+      // Failing open: prediction is a nicety — a broken history read must
+      // never break `--dry`.
+    }
+  }
+  return { tasks, ...downgradeField(args) }
+}
+
+/** Carried onto the plan only when the gate actually refused something. */
+function downgradeField(args: PlanArgs): {
+  downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
+} {
+  const d = args.downloadDowngrades
+  return d !== undefined && d.length > 0 ? { downloadDowngrades: d } : {}
+}
+
+/** A task the plan expects to EXECUTE (a no-cache task executes every run). */
+function wouldRun(t: PlannedTask): boolean {
+  return t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache'
+}
+
+/**
+ * Longest dependency chain of predicted cost, via one pass over a Kahn
+ * topological order — no recursion, so a pathologically deep chain can't
+ * overflow the stack. Hits + groups cost 0; a would-run task with no
+ * history also costs 0 (counted in `unknownCount`, making the totals
+ * honest lower bounds).
+ */
+function predictPlan(tasks: PlannedTask[]): PlanPrediction {
+  const cost = (t: PlannedTask): number => (wouldRun(t) ? (t.p50Ms ?? 0) : 0)
+  const byId = new Map(tasks.map((t) => [t.node.id, t]))
+  const dependents = new Map<string, string[]>()
+  const indeg = new Map<string, number>()
+  for (const t of tasks) {
+    const deps = t.deps.filter((d) => byId.has(d))
+    indeg.set(t.node.id, deps.length)
+    for (const d of deps) {
+      const list = dependents.get(d)
+      if (list) list.push(t.node.id)
+      else dependents.set(d, [t.node.id])
+    }
+  }
+  const dist = new Map<string, number>()
+  const queue: string[] = []
+  for (const [id, n] of indeg) if (n === 0) queue.push(id)
+  let head = 0
+  let wallMs = 0
+  while (head < queue.length) {
+    const id = queue[head++]!
+    const t = byId.get(id)!
+    let best = 0
+    for (const d of t.deps) {
+      const v = dist.get(d)
+      if (v !== undefined && v > best) best = v
+    }
+    const v = best + cost(t)
+    dist.set(id, v)
+    if (v > wallMs) wallMs = v
+    for (const dep of dependents.get(id) ?? []) {
+      const n = indeg.get(dep)! - 1
+      indeg.set(dep, n)
+      if (n === 0) queue.push(dep)
+    }
+  }
+  let workMs = 0
+  let unknownCount = 0
+  for (const t of tasks) {
+    if (!wouldRun(t)) continue
+    if (t.p50Ms === undefined) unknownCount++
+    else workMs += t.p50Ms
+  }
+  return { wallMs, workMs, unknownCount }
 }
 
 function planOutcome(node: TaskNode, hash: string): TaskOutcome {