@vzn/vx 0.0.0 → 0.0.14

package/src/orchestrator/plugin.ts

@@ -0,0 +1,283 @@
+// Plugin API — in-process extensions on top of the run event bus.
+//
+// Collapses what `architecture-review-2026-06.md §4.1` calls the
+// in-process subscriber + the WS subscriber into ONE Plugin contract.
+// Users register plugins via defineWorkspace({ plugins }); each plugin
+// receives a PluginContext with the bus + workspace metadata and can
+// install lifecycle hooks. Plugins observe; they do not redirect.
+//
+// Crash isolation: a plugin that throws on setup() is wrapped in a
+// UserError-style failure message naming the plugin (clean abort, no
+// stack), matching the existing 'broken vx.config.ts' error style. A
+// plugin that throws inside a hook is logged + the plugin is disabled
+// for the remainder of the run (mirrors the deleted Observer's
+// makeSafeObserver pattern; surfaces are isolated from execution).
+//
+// Hook return values: today every hook is fire-and-forget (the bus IS
+// the message pipe; hooks just give users an ergonomic place to read
+// it). One write-capable hook is reserved for a future iteration —
+// onCacheLookup returning { skip: true } — but not in v1.
+
+import type { Cache, CacheLayer, CachePolicy } from '../cache/index.js'
+import type { TaskNode, TaskOutcome } from '../graph/index.js'
+import { UserError } from '../util/index.js'
+import type { EventBus, RunStartInfo, WireEvent } from './events.js'
+import type { RunBackend, RunRequest } from './protocol.js'
+import type { TelemetryContext, TelemetrySink } from './telemetry.js'
+
+/**
+ * A vx plugin. Contributes any subset of three RUN-LEVEL infrastructure
+ * capabilities — where work routes (backend), which cache is used (cache),
+ * who observes the run (eventSink). It NEVER changes how a task executes
+ * (Architecture principle #3: shell is the API). Registered explicitly in
+ * vx.workspace.ts via defineWorkspace({ plugins: [...] }). No auto-discovery.
+ *
+ * The old observe-only `Plugin` (`{ name, setup(ctx) }`) is a subset of
+ * this shape: a plugin with only `setup` installs and runs exactly as
+ * before via `installPlugins`. The new capabilities are consulted by
+ * `plugin-host.ts`, each falling back to today's default.
+ */
+export interface VxPlugin {
+  /** Stable identifier, convention `'org/name'`. Used in errors + precedence logs. */
+  readonly name: string
+
+  // --- BEHAVIOR capabilities (change WHAT/HOW work runs — opt-in) -----------
+
+  /**
+   * Contribute a run backend. Returns a RunBackend (run(request) → result),
+   * or undefined to decline (core then tries the next plugin, else the
+   * fallback). Consulted ONCE per run, before scheduling. At most one
+   * plugin's backend is used (first non-undefined, in declaration order).
+   */
+  backend?(ctx: BackendContext): RunBackend | undefined | Promise<RunBackend | undefined>
+
+  /**
+   * Contribute a cache layer. Returns a CacheLayer wrapping (or replacing)
+   * the local Cache, or undefined to decline. Consulted ONCE per prepareRun.
+   * Precedence: first non-undefined plugin cache wins; else core's env-var
+   * Turbo-wire LayeredCache; else the bare local Cache.
+   */
+  cache?(ctx: CacheContext): CacheLayer | undefined | Promise<CacheLayer | undefined>
+
+  // --- OBSERVE-ONLY capability (cannot change behavior — by construction) ---
+
+  /**
+   * Contribute one or more telemetry sinks — the canonical data-export path.
+   * A sink receives versioned `TelemetryRecord` / `RunSummaryRecord` values
+   * and holds NO run handle (no bus, no cache, no request), so it provably
+   * cannot change what or how tasks run. ALL plugins' sinks are active at
+   * once (additive); a throwing/slow sink is isolated and can never fail or
+   * stall a run. This is THE export contract OTel, the manual HTTP API, and
+   * any third-party exporter all speak. See docs/design/observability-architecture-2026-06.md.
+   */
+  telemetry?(
+    ctx: TelemetryContext,
+  ):
+    | TelemetrySink
+    | TelemetrySink[]
+    | undefined
+    | Promise<TelemetrySink | TelemetrySink[] | undefined>
+
+  /**
+   * @deprecated Prefer `telemetry`. Contribute an event sink — a consumer of
+   * the serializable WireEvent stream, subscribed for the whole run via
+   * wireForwarder. Fire-and-forget; a throwing sink is isolated and cannot
+   * break the run. Kept as a back-compat path; `telemetry` is the canonical,
+   * analytics-shaped export contract.
+   */
+  eventSink?(ctx: EventSinkContext): EventSink | undefined | Promise<EventSink | undefined>
+
+  /**
+   * Optional one-time setup before any capability is consulted (validate the
+   * workspace, open a connection, read a token). Throwing aborts the run with
+   * a clean UserError naming the plugin — same contract as the old setup().
+   */
+  setup?(ctx: PluginSetupContext): void | Promise<void>
+
+  /** Optional teardown at end-of-run (flush a sink, close a socket). Errors are logged, never thrown. */
+  teardown?(): void | Promise<void>
+}
+
+/** A WireEvent consumer. onEvent is fire-and-forget; flush is awaited at teardown. */
+export interface EventSink {
+  onEvent(event: WireEvent): void
+  flush?(): Promise<void>
+}
+
+/** Shared, read-only context every capability factory receives. */
+interface BaseContext {
+  readonly workspaceRoot: string
+  readonly cacheDir: string
+  /** Funnel warnings into the run:status channel (framed output). */
+  warn(message: string): void
+}
+
+export interface PluginSetupContext extends BaseContext {}
+export interface EventSinkContext extends BaseContext {}
+
+export interface BackendContext extends BaseContext {
+  /** The resolved RunRequest about to be executed — cwd, tasks, policy, flow. */
+  readonly request: RunRequest
+}
+
+export interface CacheContext extends BaseContext {
+  /** The local Cache handle the plugin may wrap (LayeredCache(local, remote)). */
+  readonly localCache: Cache
+  /** The run's cache policy (the 4 read/write axes). */
+  readonly policy: CachePolicy
+}
+
+export interface PluginContext {
+  /** Where the workspace lives on disk. */
+  readonly workspaceRoot: string
+  /** Where vx's cache lives — read-only as far as the plugin is concerned. */
+  readonly cacheDir: string
+  /** The run event bus. A plugin can subscribe directly if its needs exceed the hooks. */
+  readonly bus: EventBus
+  /**
+   * Convenience: register a typed handler keyed off `RunEvent.kind`.
+   * Multiple hooks can chain via repeated calls.
+   */
+  on<K extends PluginHookName>(hook: K, handler: PluginHookHandlers[K]): void
+}
+
+export type PluginHookName =
+  | 'onRunStart'
+  | 'onTaskStart'
+  | 'onTaskStdout'
+  | 'onTaskStderr'
+  | 'onTaskComplete'
+  | 'onRunStatus'
+  | 'onRunEnd'
+
+export interface PluginHookHandlers {
+  onRunStart: (info: RunStartInfo) => void | Promise<void>
+  onTaskStart: (node: TaskNode) => void | Promise<void>
+  onTaskStdout: (node: TaskNode, chunk: string) => void | Promise<void>
+  onTaskStderr: (node: TaskNode, chunk: string) => void | Promise<void>
+  onTaskComplete: (node: TaskNode, outcome: TaskOutcome) => void | Promise<void>
+  onRunStatus: (line: string) => void | Promise<void>
+  onRunEnd: () => void | Promise<void>
+}
+
+export interface Plugin {
+  /** Logged on errors; the convention is `'org/plugin-name'`. */
+  readonly name: string
+  /**
+   * Called once at the start of every run. Register hooks via
+   * `ctx.on(name, fn)` or subscribe to `ctx.bus` directly. Returning
+   * a promise lets a plugin do async setup; the bus subscription must
+   * be installed synchronously inside setup() so no events are missed.
+   *
+   * OPTIONAL: a capability-only plugin (one that contributes
+   * `backend`/`cache`/`eventSink` but no `setup`) is simply skipped by
+   * `installPlugins` — its capabilities are consulted by `plugin-host.ts`.
+   */
+  setup?(ctx: PluginContext): void | Promise<void>
+}
+
+export interface InstallPluginsArgs {
+  plugins: readonly Plugin[]
+  workspaceRoot: string
+  cacheDir: string
+  bus: EventBus
+  /**
+   * Where plugin-throw warnings go. Defaults to console.error; passing
+   * a callback lets the orchestrator funnel into the framed-output
+   * `run:status` channel.
+   */
+  warn?: (message: string) => void
+}
+
+/**
+ * Install every plugin's `setup` hook against a shared bus + context.
+ * Synchronous loop; setup() promises are awaited in order so a plugin's
+ * hooks are subscribed before the next plugin's setup runs. Throws if any
+ * plugin's setup() throws (the run cannot start with a broken plugin).
+ *
+ * A plugin without a `setup` is a capability-only plugin (backend / cache
+ * / eventSink) — skipped here; those capabilities are consulted by
+ * `plugin-host.ts`.
+ */
+export async function installPlugins(args: InstallPluginsArgs): Promise<() => void> {
+  const { plugins, bus, workspaceRoot, cacheDir } = args
+  const warn = args.warn ?? ((m) => console.error(m))
+  const disposers: Array<() => void> = []
+  const disabled = new Set<string>()
+
+  for (const plugin of plugins) {
+    if (typeof plugin.name !== 'string' || plugin.name.length === 0) {
+      throw new UserError('plugin missing `name` field')
+    }
+    // No setup → a capability-only plugin (backend / cache / eventSink),
+    // consulted by plugin-host.ts; skip the hook install. A setup that's
+    // present but not callable is a real authoring error — reject it.
+    if (plugin.setup === undefined) continue
+    if (typeof plugin.setup !== 'function') {
+      throw new UserError(`plugin '${plugin.name}' setup is not a function`)
+    }
+
+    const ctx: PluginContext = {
+      workspaceRoot,
+      cacheDir,
+      bus,
+      on(hook, handler) {
+        const dispose = bus.subscribe((event) => {
+          if (disabled.has(plugin.name)) return
+          // void each handler call: hooks may return Promise; we
+          // intentionally don't await (the bus is synchronous;
+          // long-running plugin work happens off the critical path).
+          try {
+            switch (hook) {
+              case 'onRunStart':
+                if (event.kind === 'run:start')
+                  void (handler as PluginHookHandlers['onRunStart'])(event.info)
+                break
+              case 'onTaskStart':
+                if (event.kind === 'task:start')
+                  void (handler as PluginHookHandlers['onTaskStart'])(event.node)
+                break
+              case 'onTaskStdout':
+                if (event.kind === 'task:stdout')
+                  void (handler as PluginHookHandlers['onTaskStdout'])(event.node, event.chunk)
+                break
+              case 'onTaskStderr':
+                if (event.kind === 'task:stderr')
+                  void (handler as PluginHookHandlers['onTaskStderr'])(event.node, event.chunk)
+                break
+              case 'onTaskComplete':
+                if (event.kind === 'task:complete')
+                  void (handler as PluginHookHandlers['onTaskComplete'])(event.node, event.outcome)
+                break
+              case 'onRunStatus':
+                if (event.kind === 'run:status')
+                  void (handler as PluginHookHandlers['onRunStatus'])(event.line)
+                break
+              case 'onRunEnd':
+                if (event.kind === 'run:end') void (handler as PluginHookHandlers['onRunEnd'])()
+                break
+            }
+          } catch (err) {
+            disabled.add(plugin.name)
+            warn(
+              `[vx] plugin '${plugin.name}' threw in ${hook}; disabled for this run: ${err instanceof Error ? err.message : String(err)}`,
+            )
+          }
+        })
+        disposers.push(dispose)
+      },
+    }
+
+    try {
+      await plugin.setup(ctx)
+    } catch (err) {
+      throw new UserError(
+        `plugin '${plugin.name}' failed to load: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  }
+
+  return () => {
+    for (const d of disposers) d()
+  }
+}

package/src/orchestrator/predict.ts

@@ -0,0 +1,106 @@
+// Predictive scheduling — use HistoryTable to compute expected
+// remaining critical-path duration per node. Replaces the scheduler's
+// graph-counter heuristic priority for runs that opt in via
+// defineWorkspace({ predictive: true }) (predictive-execution-2026-06.md
+// Phase B + architecture-review-2026-06.md §8.4).
+//
+// Pure functions; no side effects; tested standalone. The scheduler
+// reads the priorities at queue time, picks the max.
+
+import type { TaskNode } from '../graph/index.js'
+import type { HistoryTable } from './history.js'
+
+/** Default duration when neither task history nor workspace median exists. */
+const DEFAULT_DURATION_MS = 1000
+
+/**
+ * For each node, the expected remaining critical-path duration (its own
+ * p50 + the max over its dependents). Cache hits are NOT modeled as
+ * zero-cost here because predicting cache state requires knowing the
+ * key + probing the layer — the run-time scheduler can flip the
+ * priority once a hit is observed; the upfront estimate is "what if
+ * everything ran."
+ */
+export function computePredictedPriorities(
+  nodes: readonly TaskNode[],
+  history: HistoryTable,
+): ReadonlyMap<string, number> {
+  // Workspace-median fallback: across every history entry that has a
+  // p50, pick the median of those p50s. If history is sparse, fall
+  // back to DEFAULT_DURATION_MS.
+  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
+
+  // Build a reverse-adjacency map so we can resolve dependents per
+  // node in O(1). The TaskNode graph carries dependsOn (upstream); we
+  // invert.
+  const dependentsOf = buildDependentsIndex(nodes)
+  const ownDuration = (n: TaskNode): number => {
+    const h = history.get(n.id)
+    return h?.p50DurationMs ?? workspaceMedian
+  }
+
+  // Memoized topo-DP. visit[id] = the expected critical path FROM this
+  // node down to a leaf. We compute bottom-up using a stack-based
+  // walker — iterative to avoid V8 stack-frame ceilings on deep graphs.
+  const memo = new Map<string, number>()
+  const nodeById = new Map<string, TaskNode>(nodes.map((n) => [n.id, n]))
+
+  const stack: TaskNode[] = nodes.slice()
+  // First pass: ensure deepest-first ordering via post-order traversal.
+  const order: TaskNode[] = []
+  const visited = new Set<string>()
+  while (stack.length > 0) {
+    const top = stack[stack.length - 1]!
+    if (visited.has(top.id)) {
+      stack.pop()
+      continue
+    }
+    const deps = dependentsOf.get(top.id) ?? []
+    let pushed = false
+    for (const d of deps) {
+      const n = nodeById.get(d)
+      if (n && !visited.has(n.id) && !stack.includes(n)) {
+        stack.push(n)
+        pushed = true
+        break
+      }
+    }
+    if (!pushed) {
+      visited.add(top.id)
+      order.push(top)
+      stack.pop()
+    }
+  }
+
+  for (const n of order) {
+    const own = ownDuration(n)
+    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, own + downstream)
+  }
+
+  return memo
+}
+
+function buildDependentsIndex(nodes: readonly TaskNode[]): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  for (const n of nodes) {
+    for (const upstreamId of n.deps) {
+      const list = out.get(upstreamId)
+      if (list) list.push(n.id)
+      else out.set(upstreamId, [n.id])
+    }
+  }
+  return out
+}

package/src/orchestrator/prepare.ts

@@ -0,0 +1,306 @@
+// Shared setup for `run()` and `planRun()`. Both entry points perform
+// the same workspace-discovery → config-load → graph-build → cache-
+// open sequence; this module centralises it so the two callers stay
+// thin.
+//
+// The caller owns the returned `cache.close()` lifetime: `run()`
+// closes at the bottom of execution, `planRun()` does so via
+// try/finally around its plan() call.
+
+import path from 'node:path'
+import type { ProjectConfig, WorkspaceConfig } from '../config.js'
+import { UserError } from '../util/index.js'
+import {
+  Cache,
+  type CacheLayer,
+  type CachePolicy,
+  FULL_CACHE_POLICY,
+  GitFilesCache,
+  LayeredCache,
+  populateGitFilesCache,
+} from '../cache/index.js'
+import {
+  buildPackageGraph,
+  computeNestedProjectDirs,
+  computeWorkspaceFingerprint,
+  findWorkspaceRoot,
+  frozenProjectConfig,
+  listProjects,
+  loadProjectConfig,
+  loadWorkspace,
+  loadWorkspaceConfig,
+  readLockfile,
+  resolveCacheDir,
+  type ProjectEntry,
+} from '../workspace/index.js'
+import { buildTaskGraph, expandRequested, type TaskNode } from '../graph/index.js'
+import { resolveCache } from './plugin-host.js'
+import type { VxPlugin } from './plugin.js'
+import { createHashCache, type HashCache } from './task-hash.js'
+import type { Logger } from './logger.js'
+import type { RunOptions } from './options.js'
+import { type HistoryTable, LocalHistoryProvider } from './history.js'
+import { computePredictedPriorities } from './predict.js'
+
+export interface PreparedRun {
+  workspaceRoot: string
+  workspaceConfig: WorkspaceConfig | null
+  cacheDir: string
+  cache: CacheLayer
+  /**
+   * The local Cache handle (unwrapped). `cache` may be a LayeredCache
+   * wrapping this; subsystems that need the raw SQLite (e.g.
+   * LocalHistoryProvider) read directly from here.
+   */
+  localCache: Cache
+  /**
+   * Predicted priorities (history-aware critical-path). Populated only
+   * when the workspace opts in via `defineWorkspace({ predictive: true })`.
+   * Empty map otherwise — scheduler falls back to its baseline.
+   */
+  priorities: ReadonlyMap<string, number>
+  nodes: Map<string, TaskNode>
+  workspaceFingerprint: string
+  nestedDirsByProject: Map<string, string[]>
+  /**
+   * Per-run memo for `git ls-files` output, keyed by project dir.
+   * Without this, every task in a project re-spawns git just to
+   * enumerate its input file set (3× per project for build / test /
+   * lint, etc.) — observable in cache-hit run times.
+   */
+  gitFilesCache: GitFilesCache
+  /** Every project discovery found, in or out of scope — header scope bar. */
+  workspaceProjectCount: number
+  /**
+   * Per-run memo for derived hashes — project package.json bytes
+   * keyed by projectDir, task-config hash keyed by config object
+   * identity. Shared across every task's `computeTaskHash` call so
+   * the same project's package.json (and the same task config
+   * object) aren't re-hashed on every task in that project.
+   */
+  hashCache: HashCache
+  /**
+   * Reason `nodes` is empty. `null` when the prepared run is ready to
+   * execute. Either:
+   *   - `'no-tasks-declared'` — `requested.length === 0` after the
+   *     user's task names were resolved against `projects`. Typically
+   *     a typo'd task name; `run()` treats this as a CI footgun and
+   *     returns NOT-ok.
+   *   - `'empty-graph'`       — `requested` was non-empty but the
+   *     graph builder still produced no nodes. Defensive; unreachable
+   *     under current `buildTaskGraph` semantics.
+   */
+  empty: null | 'no-tasks-declared' | 'empty-graph'
+}
+
+/**
+ * Build the prepared-run context: workspace discovery, project-config
+ * load, package + task graph, cache handle (local, optionally wrapped
+ * in a remote layer). Caller owns `cache.close()`.
+ *
+ * Returns even when nothing can run — the `empty` field tells the
+ * caller why. We never throw on "no tasks"; behavior on that case is
+ * caller-specific (run logs + returns NOT-ok; planRun returns an
+ * empty plan).
+ */
+export async function prepareRun(options: RunOptions, log: Logger): Promise<PreparedRun> {
+  const workspaceRoot = await findWorkspaceRoot(options.cwd)
+  const workspace = await loadWorkspace(workspaceRoot)
+  const workspaceConfig = await loadWorkspaceConfig(workspaceRoot)
+  const projectMetas = await listProjects(workspace)
+
+  // SCOPED config loading: configs are programs, and evaluating 1090
+  // of them costs ~200 ms — the dominant fixed cost of small runs.
+  // Only the in-scope projects and their transitive dependency
+  // closure can contribute graph nodes (frontier '^task' expansion
+  // never escapes the closure), so only those configs are evaluated.
+  // Side effect, deliberate and Turbo-like: a broken config in an
+  // unrelated package no longer fails a scoped run — it surfaces
+  // when that package enters a run's scope.
+  const packageGraph = buildPackageGraph(projectMetas)
+  const projectsWithConfigs = projectMetas.filter(
+    (m): m is typeof m & { configPath: string } =>
+      typeof m.configPath === 'string' && m.configPath.length > 0,
+  )
+  const haveConfig = new Set(projectsWithConfigs.map((m) => m.name))
+
+  // Seeds: explicit scope, plus anchored pkg#task targets (which
+  // bypass scope by design). With no explicit scope, bare task names
+  // fan out across the whole workspace — but when EVERY spec is
+  // anchored, the anchors alone are the scope and nothing else needs
+  // its config evaluated.
+  const anchored: string[] = []
+  let hasBare = false
+  for (const spec of options.tasks) {
+    const hashIdx = spec.indexOf('#')
+    if (hashIdx > 0) anchored.push(spec.slice(0, hashIdx))
+    else hasBare = true
+  }
+  const seeds = new Set<string>(
+    options.projects
+      ? options.projects.filter((p) => haveConfig.has(p))
+      : hasBare
+        ? haveConfig
+        : [],
+  )
+  for (const project of anchored) {
+    if (haveConfig.has(project)) seeds.add(project)
+  }
+  const needed = new Set<string>(seeds)
+  for (const seed of seeds) {
+    for (const dep of packageGraph.transitiveDeps(seed)) needed.add(dep)
+  }
+
+  const projects = new Map<string, ProjectEntry>()
+  const toLoad = projectsWithConfigs.filter((m) => needed.has(m.name))
+  // Frozen mode (--frozen, CI): configs load FROM vx-lock.json after a
+  // content-hash tripwire — no evaluation; env-dependent configs keep
+  // their locked values. Default (local) runs ALWAYS evaluate live:
+  // a byte hash can't see a config's import closure (shared presets),
+  // so consuming the lock by default would silently serve stale
+  // freezes. `vx lock --check` is the full re-evaluation audit.
+  // See docs/design/config-lock-2026-06.md.
+  const lock = options.frozen === true ? await readLockfile(workspaceRoot) : null
+  if (options.frozen === true && lock === null) {
+    throw new UserError(
+      `--frozen requires vx-lock.json at the workspace root — run 'vx lock' and commit it`,
+    )
+  }
+  const configs = await Promise.all(
+    toLoad.map((m) =>
+      lock ? frozenProjectConfig(lock, m, workspaceRoot) : loadProjectConfig(m.configPath),
+    ),
+  )
+  for (let i = 0; i < toLoad.length; i++) {
+    const meta = toLoad[i]!
+    const config = configs[i] as ProjectConfig
+    projects.set(meta.name, { name: meta.name, dir: meta.dir, config })
+  }
+
+  // Boundary geometry considers every config-bearing project in the
+  // workspace, loaded or not — an out-of-scope nested project must
+  // still fence its files off from its parent's globs.
+  const nestedDirsByProject = computeNestedProjectDirs(
+    projectsWithConfigs.map((m) => ({ name: m.name, dir: m.dir })),
+  )
+
+  const candidateProjects = options.projects
+    ? options.projects.filter((p) => projects.has(p))
+    : [...projects.keys()]
+
+  const requested = expandRequested(options.tasks, candidateProjects, projects)
+
+  const policy: CachePolicy = options.cache ?? FULL_CACHE_POLICY
+  // `--cache-dir <path>` (RunOptions.cacheDir) overrides the workspace
+  // `cacheDir` field + the `.vx/cache` default; resolved relative to cwd.
+  const cacheDir = options.cacheDir
+    ? path.resolve(options.cwd, options.cacheDir)
+    : resolveCacheDir(workspaceRoot, workspaceConfig)
+  const localCache = new Cache(cacheDir, { read: policy.localRead, write: policy.localWrite })
+  // Cache seam precedence: an EXPLICITLY injected remote layer
+  // (RunOptions.remoteCache — a distribution agent or serve that already
+  // holds a wire client) wins outright; else a plugin's `cache` capability;
+  // else the local cache alone. Core ships no wire client — the remote
+  // cache is a plugin concern (native-cache-wire-2026-07). Injection
+  // winning prevents double-wrapping when the workspace also declares a
+  // cache plugin.
+  const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
+  const cache = options.remoteCache
+    ? new LayeredCache(localCache, options.remoteCache, {
+        policy,
+        onRemoteError: (err) => log.status(`[vx] remote cache: ${err.message}`),
+      })
+    : await resolveCache(
+        plugins,
+        localCache,
+        { workspaceRoot, cacheDir, warn: (m) => log.status(m), localCache, policy },
+        log,
+        () => localCache,
+      )
+  const workspaceFingerprint = await computeWorkspaceFingerprint(workspaceRoot)
+
+  const gitFilesCache = new GitFilesCache()
+  // Bulk-populate via a single `git ls-files` at the workspace root —
+  // partitions the output by project. Avoids one fork+exec per project
+  // (~5-10ms each on Linux; the dominant cold-start cost on big
+  // monorepos). When any loaded task declares inputs.workspaceFiles,
+  // the enumeration must see every file from the root (no pathspec
+  // scoping) and additionally stores a workspace-wide partition.
+  const usesWorkspaceInputs = [...projects.values()].some((p) =>
+    Object.values(p.config.tasks ?? {}).some(
+      (t) => (t.cache?.inputs.workspaceFiles?.length ?? 0) > 0,
+    ),
+  )
+  await populateGitFilesCache(
+    workspaceRoot,
+    [...projects.values()].map((p) => p.dir),
+    gitFilesCache,
+    usesWorkspaceInputs,
+  )
+  const hashCache = createHashCache()
+
+  // Empty-cases bookkeeping. We still construct the cache + fingerprint
+  // so the caller's try/finally pattern can close it uniformly.
+  if (requested.length === 0) {
+    return {
+      workspaceRoot,
+      workspaceConfig,
+      cacheDir,
+      cache,
+      localCache,
+      priorities: new Map(),
+      nodes: new Map(),
+      workspaceFingerprint,
+      nestedDirsByProject,
+      gitFilesCache,
+      hashCache,
+      workspaceProjectCount: projectMetas.length,
+      empty: 'no-tasks-declared',
+    }
+  }
+
+  const nodes = buildTaskGraph({
+    projects,
+    packageGraph,
+    requested,
+    ...(options.excludeDependencies !== undefined
+      ? { excludeDependencies: options.excludeDependencies }
+      : {}),
+  })
+
+  // Predictive scheduling (architecture-review §8.4 / Phase 4): when
+  // the workspace opts in via `predictive: true`, load history for
+  // every node in the graph + compute expected-critical-path weights.
+  // The scheduler applies them on top of the static baseline. Failing
+  // open: any error in history loading degrades to baseline-only,
+  // never to a broken run.
+  let priorities: ReadonlyMap<string, number> = new Map()
+  if (workspaceConfig?.predictive === true) {
+    const history = new LocalHistoryProvider(localCache.dbHandle())
+    try {
+      const ids = [...nodes.keys()]
+      const table: HistoryTable = await history.loadFor(ids)
+      priorities = computePredictedPriorities([...nodes.values()], table)
+    } catch (err) {
+      log.status(
+        `[vx] predictive scheduling fell back to baseline: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  }
+
+  return {
+    workspaceRoot,
+    workspaceConfig,
+    cacheDir,
+    cache,
+    localCache,
+    priorities,
+    nodes,
+    workspaceFingerprint,
+    nestedDirsByProject,
+    gitFilesCache,
+    hashCache,
+    workspaceProjectCount: projectMetas.length,
+    empty: nodes.size === 0 ? 'empty-graph' : null,
+  }
+}