@vzn/vx 0.0.0 → 0.0.12

package/src/orchestrator/summary.ts

@@ -0,0 +1,291 @@
+// Turbo-style end-of-run summary. Always printed after a `vx run`
+// invocation completes (success or failure). Counts come from the
+// shared `tallyOutcomes` helper, which excludes group tasks — they
+// aren't real work and would inflate "N total" misleadingly.
+
+import type { TaskOutcome } from '../graph/index.js'
+import { paint, type ColorSupport } from './colors.js'
+import { tallyOutcomes } from './tally.js'
+import { isGroupTask } from '../graph/index.js'
+
+const NO_COLOR: ColorSupport = { enabled: false }
+
+const SUCCESS = '#22c55e'
+const WARN = '#eab308'
+// Cache provenance hues (owner): local light blue, remote dark blue —
+// yellow is skipped's color on both meters.
+const LOCAL = '#38bdf8' // sky-400
+const REMOTE = '#2563eb' // blue-600
+const ERROR = '#ef4444'
+
+const BAR_WIDTH = 50
+// Brand gradient for the rule: identity violet → pink (the project /
+// task hues), faded across the dash run. Plain dashes when colors
+// are off.
+const GRADIENT_FROM = [0xa7, 0x8b, 0xfa] as const
+const GRADIENT_TO = [0xf4, 0x72, 0xb6] as const
+// Rule ends flush with the bars: 2 indent + 8 label + 2 gap + 50 cells.
+const RULE_DASHES = 57
+
+/** Total visible rule width: `\u2500 <mark> ` + dashes. Shared by summary + header. */
+export function gradientRule(colors: ColorSupport, mark = 'vx'): string {
+  const head = `\u2500 `
+  const dashes = '\u2500'.repeat(Math.max(8, RULE_DASHES + 2 - mark.length))
+  if (!colors.enabled) return `${head}${mark} ${dashes}`
+  const chunks = 8
+  const per = Math.ceil(RULE_DASHES / chunks)
+  let out = ''
+  for (let i = 0; i < chunks; i++) {
+    const seg = dashes.slice(i * per, (i + 1) * per)
+    if (seg.length === 0) break
+    const f = i / (chunks - 1)
+    const hex = `#${GRADIENT_FROM.map((c, j) =>
+      Math.round(c + (GRADIENT_TO[j]! - c) * f)
+        .toString(16)
+        .padStart(2, '0'),
+    ).join('')}`
+    out += paint(hex, seg, colors)
+  }
+  return `${paint(`#${GRADIENT_FROM.map((c) => c.toString(16).padStart(2, '0')).join('')}`, head, colors)}${paint('', mark, colors, { bold: true })} ${out}`
+}
+
+/**
+ * Stacked state meter: one ▰ run per bucket, proportional cells via
+ * largest-remainder, every non-zero bucket guaranteed at least one
+ * cell. Color carries the state; the color-coded numbers ride beside
+ * the bar.
+ */
+function segmentBar(
+  segments: readonly { n: number; color: string; glyph?: string; dim?: boolean }[],
+  colors: ColorSupport,
+): string {
+  const total = segments.reduce((sum, seg) => sum + seg.n, 0)
+  if (total === 0) return ''
+  const exact = segments.map((seg) => (seg.n / total) * BAR_WIDTH)
+  const cells = exact.map(Math.floor)
+  let leftover = BAR_WIDTH - cells.reduce((sum, c) => sum + c, 0)
+  const order = exact
+    .map((e, i) => ({ i, frac: e - Math.floor(e) }))
+    .sort((x, y) => y.frac - x.frac)
+  for (const { i } of order) {
+    if (leftover === 0) break
+    cells[i]!++
+    leftover--
+  }
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i]!.n > 0 && cells[i] === 0) {
+      const biggest = cells.indexOf(Math.max(...cells))
+      cells[biggest]!--
+      cells[i] = 1
+    }
+  }
+  return segments
+    .map((seg, i) =>
+      paint(seg.color, (seg.glyph ?? '\u25b0').repeat(cells[i]!), colors, {
+        ...(seg.dim === true ? { dim: true } : {}),
+      }),
+    )
+    .join('')
+}
+
+/** Aggregate counts feeding the summary section — buildable from a
+ *  finished outcome list (formatRunSummary) or incrementally by the
+ *  live logger, so the in-flight region and the final summary are the
+ *  SAME section, one filling in as the other will print. */
+export interface SummaryStats {
+  failed: number
+  /** Ended OK — executed successes AND cache hits. */
+  successful: number
+  skipped: number
+  total: number
+  upToDate: number
+  restoredLocal: number
+  restoredRemote: number
+  /** Tasks that executed (success + failed) — the cache misses. */
+  miss: number
+  /** Still to run (live section only; 0 in the final summary) — renders
+   *  as a gray ▱ remainder so the live meters FILL toward the final. */
+  left?: number
+  /** Cache-miss duration spread (only tasks that actually executed). */
+  spread: { maxMs: number; minMs: number; sumMs: number; count: number } | null
+}
+
+/**
+ * Run context the footer carries (final summary only — the live region
+ * passes none). This is the data the top-of-run header used to show:
+ * what the run covered + version + cache mode. Folded into the footer
+ * so the run has one banner, at the end, where the eye lands.
+ */
+export interface RunContext {
+  version: string
+  /** Projects covered by the graph — the "affected" half of the bar. */
+  packageCount: number
+  /** Worker-pool size for this run; shown on the `info` row. */
+  concurrency?: number
+  remoteCacheEnabled: boolean
+  /** Total projects discovery found — the bar's denominator. */
+  workspaceProjectCount?: number
+}
+
+export function formatSummarySection(
+  stats: SummaryStats,
+  totalMs: number,
+  colors: ColorSupport = NO_COLOR,
+  context?: RunContext,
+): string[] {
+  const hits = stats.upToDate + stats.restoredLocal + stats.restoredRemote
+  const miss = stats.miss
+  const left = stats.left ?? 0
+  const remainder = { n: left, color: '', glyph: '\u25b1', dim: true }
+
+  const dim = (txt: string) => paint('', txt, colors, { dim: true })
+  const row = (label: string, value: string): string => `  ${dim(label.padEnd(8))}  ${value}`
+  const join = (parts: string[]): string => parts.join(` ${dim('\u00b7')} `)
+
+  // Tasks meter + numbers, fixed order: failed · success · skipped,
+  // then a dim total so the legend reads against the whole graph.
+  const taskParts: string[] = []
+  if (stats.failed > 0)
+    taskParts.push(paint(ERROR, `${stats.failed} failed`, colors, { bold: true }))
+  if (stats.successful > 0) taskParts.push(paint(SUCCESS, `${stats.successful} success`, colors))
+  if (stats.skipped > 0) taskParts.push(paint(WARN, `${stats.skipped} skipped`, colors))
+  if (stats.total > 0) taskParts.push(dim(`${stats.total} total`))
+  const taskBar = segmentBar(
+    [
+      { n: stats.failed, color: ERROR },
+      { n: stats.successful, color: SUCCESS },
+      { n: stats.skipped, color: WARN },
+      remainder,
+    ],
+    colors,
+  )
+  // Bars on the label row, color-coded legend on its own line below,
+  // indented to the bar column (2 indent + 8 label + 2 gap = 12).
+  const legend = (parts: string[]): string => `${' '.repeat(12)}${join(parts)}`
+  // Version rides the wordmark rule when run context is present (final
+  // footer); the live region passes none and keeps a bare `vx`.
+  const lines: string[] = [
+    '',
+    gradientRule(colors, context !== undefined ? `vx ${context.version}` : 'vx'),
+  ]
+
+  // Run context (final footer only): the projects bar leads the meter
+  // stack — affected (yellow) vs the rest of the workspace (dim).
+  if (context !== undefined) {
+    const wsTotal = context.workspaceProjectCount
+    if (wsTotal !== undefined && wsTotal > 0) {
+      const cells = Math.min(
+        BAR_WIDTH,
+        Math.max(1, Math.round((context.packageCount / wsTotal) * BAR_WIDTH)),
+      )
+      const bar =
+        paint(WARN, '▰'.repeat(cells), colors) +
+        paint('', '▱'.repeat(BAR_WIDTH - cells), colors, { dim: true })
+      lines.push(
+        row('projects', bar),
+        legend([paint(WARN, `${context.packageCount} affected`, colors), dim(`${wsTotal} total`)]),
+      )
+    }
+  }
+
+  if (taskBar.length > 0) {
+    lines.push(row('tasks', taskBar))
+    // No legend line until the first bucket lands (live: all-gray bar).
+    if (taskParts.length > 0) lines.push(legend(taskParts))
+  } else {
+    lines.push(row('tasks', dim('0 tasks')))
+  }
+
+  // Cache meter + numbers, fixed order: miss · up-to-date · local ·
+  // remote.
+  if (miss + hits + left + stats.skipped > 0) {
+    const cacheBar = segmentBar(
+      [
+        { n: miss, color: ERROR },
+        { n: stats.upToDate, color: SUCCESS },
+        { n: stats.restoredLocal, color: LOCAL },
+        { n: stats.restoredRemote, color: REMOTE },
+        { n: stats.skipped, color: WARN },
+        remainder,
+      ],
+      colors,
+    )
+    const cacheParts: string[] = []
+    if (miss > 0) cacheParts.push(paint(ERROR, `${miss} miss`, colors))
+    if (stats.upToDate > 0) cacheParts.push(paint(SUCCESS, `${stats.upToDate} up-to-date`, colors))
+    if (stats.restoredLocal > 0)
+      cacheParts.push(paint(LOCAL, `${stats.restoredLocal} local`, colors))
+    if (stats.restoredRemote > 0)
+      cacheParts.push(paint(REMOTE, `${stats.restoredRemote} remote`, colors))
+    // Skipped tasks have no cache provenance, but omitting them made
+    // the cache legend sum below the tasks legend (owner-reported
+    // confusion) — on the bar and in the legend, yellow like the
+    // tasks meter.
+    if (stats.skipped > 0) cacheParts.push(paint(WARN, `${stats.skipped} skipped`, colors))
+    lines.push(row('cache', cacheBar))
+    if (cacheParts.length > 0) lines.push(legend(cacheParts))
+  }
+
+  // Cache-miss duration spread (owner: hits' restore times polluted
+  // it — only tasks that actually executed count). Dim: context.
+  let spread = ''
+  if (stats.spread !== null && stats.spread.count > 0) {
+    const { maxMs, minMs, sumMs, count } = stats.spread
+    spread = ` ${dim(`\u00b7 max ${formatDuration(maxMs)} \u00b7 avg ${formatDuration(sumMs / count)} \u00b7 min ${formatDuration(minMs)}`)}`
+  }
+  // Run-shape footer (final summary only): worker pool + cache mode,
+  // grouped with time under a blank line below the meters.
+  if (context !== undefined) {
+    const info: string[] = []
+    if (context.concurrency !== undefined)
+      info.push(`${context.concurrency} worker${context.concurrency === 1 ? '' : 's'}`)
+    info.push(context.remoteCacheEnabled ? 'local + remote cache' : 'local cache')
+    lines.push('', row('info', join(info)), row('time', `${formatDuration(totalMs)}${spread}`))
+  } else {
+    lines.push('', row('time', `${formatDuration(totalMs)}${spread}`))
+  }
+  return lines
+}
+
+export function formatRunSummary(
+  outcomes: readonly TaskOutcome[],
+  totalMs: number,
+  colors: ColorSupport = NO_COLOR,
+  context?: RunContext,
+): string[] {
+  const t = tallyOutcomes(outcomes)
+  // Spread over executed tasks only — `success`/`failed` statuses ran
+  // a command; cache-hit statuses replayed one.
+  const durations = outcomes
+    .filter((o) => (o.status === 'success' || o.status === 'failed') && !isGroupTask(o.node))
+    .map((o) => o.durationMs)
+  return formatSummarySection(
+    {
+      failed: t.failed,
+      successful: t.successful,
+      skipped: t.skipped,
+      total: t.total,
+      upToDate: t.upToDate,
+      restoredLocal: t.restoredLocal,
+      restoredRemote: t.restoredRemote,
+      miss: t.total - t.skipped - (t.cachedLocal + t.cachedRemote),
+      spread:
+        durations.length > 0
+          ? {
+              maxMs: Math.max(...durations),
+              minMs: Math.min(...durations),
+              sumMs: durations.reduce((sum, d) => sum + d, 0),
+              count: durations.length,
+            }
+          : null,
+    },
+    totalMs,
+    colors,
+    context,
+  )
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  return `${(ms / 1000).toFixed(2)}s`
+}

package/src/orchestrator/tally.ts

@@ -0,0 +1,69 @@
+// Shared outcome-tally helper. Both `summary.ts` (end-of-run terminal
+// block) and `run-artifacts.ts` (`--summarize` JSON) count the same
+// numbers; centralising it keeps the two surfaces consistent.
+
+import { isGroupTask, type TaskOutcome } from '../graph/index.js'
+
+export interface Tally {
+  successful: number
+  failed: number
+  skipped: number
+  cachedLocal: number
+  /** Hits that materialized files from the local artifact. */
+  restoredLocal: number
+  /** Hits that materialized files pulled from the remote layer. */
+  restoredRemote: number
+  /** Cache hits whose tree already matched — nothing was written. */
+  upToDate: number
+  cachedRemote: number
+  /** Tasks counted toward `total`. Group tasks are excluded by default. */
+  total: number
+}
+
+/**
+ * Walk the outcome list and return a `Tally`. Group tasks (no `exec`)
+ * are filtered out — they aren't real work, and including them
+ * inflates the per-run "N total" count in ways that mislead the user
+ * ("3 of 4 cached" when one was a group that ran nothing).
+ *
+ * Status bucket rules:
+ *   `success`            → +successful
+ *   `cache-hit`          → +successful, +cachedLocal
+ *   `cache-hit-remote`   → +successful, +cachedRemote
+ *   `failed`             → +failed
+ *   `skipped`            → +skipped
+ */
+export function tallyOutcomes(outcomes: readonly TaskOutcome[]): Tally {
+  const t: Tally = {
+    successful: 0,
+    failed: 0,
+    skipped: 0,
+    cachedLocal: 0,
+    restoredLocal: 0,
+    restoredRemote: 0,
+    upToDate: 0,
+    cachedRemote: 0,
+    total: 0,
+  }
+  for (const o of outcomes) {
+    if (isGroupTask(o.node)) continue
+    // aborted (killed by a shutdown signal) is no work — excluded
+    // from totals and every bucket, exactly like a group task.
+    if (o.status === 'aborted') continue
+    t.total++
+    if (o.status === 'success') t.successful++
+    else if (o.status === 'cache-hit') {
+      t.successful++
+      t.cachedLocal++
+      if (o.restored === true) t.restoredLocal++
+      else t.upToDate++
+    } else if (o.status === 'cache-hit-remote') {
+      t.successful++
+      t.cachedRemote++
+      if (o.restored === true) t.restoredRemote++
+      else t.upToDate++
+    } else if (o.status === 'failed') t.failed++
+    else if (o.status === 'skipped') t.skipped++
+  }
+  return t
+}

package/src/orchestrator/task-hash.ts

@@ -0,0 +1,238 @@
+import path from 'node:path'
+import type { TaskConfig, CacheConfig } from '../config.js'
+import { type CacheLayer, resolveInputs, type GitFilesCache } from '../cache/index.js'
+import type { TaskNode, TaskOutcome } from '../graph/index.js'
+import { xxh3hex } from '../util/index.js'
+import { filterUpstreamHashes } from './upstream.js'
+
+/**
+ * Per-run memoization caches for the two derived hashes that don't
+ * change across tasks within one run:
+ *   - `packageJson`: keyed by absolute projectDir. Every task in a
+ *     project re-reads the same `package.json`; without this, a
+ *     monorepo with N projects × M tasks per project does N×M reads
+ *     of the same bytes.
+ *   - `taskConfig`: keyed by the resolved-config object reference.
+ *     Each task's config is created once at prepareRun time; the
+ *     JSON.stringify + xxh3 of it is deterministic. WeakMap so
+ *     entries free when the orchestrator is done.
+ *
+ * Both fields are optional — the helpers fall back to computing
+ * fresh when the cache is missing.
+ */
+export interface HashCache {
+  packageJson: Map<string, Promise<string>>
+  taskConfig: WeakMap<TaskConfig, string>
+  runtime: Map<string, Promise<string>>
+  workspaceRuntime: Map<string, Promise<string>>
+}
+
+export function createHashCache(): HashCache {
+  return {
+    packageJson: new Map(),
+    taskConfig: new WeakMap(),
+    runtime: new Map(),
+    workspaceRuntime: new Map(),
+  }
+}
+
+/**
+ * One cache-key component captured at hash time. On a cache MISS the
+ * orchestrator persists these to `entry_inputs` (keyed by the entry
+ * hash, inside the save transaction) so a later run can diff its inputs
+ * against this one (the Tier-3 "why did this re-run?" moat). A cache
+ * HIT never saves, so it captures nothing — the warm path is free.
+ * Mirrors `Cache.key()`'s fold-site rows one-for-one.
+ */
+export interface TaskInputComponent {
+  kind: string
+  name: string
+  hash: string
+}
+
+export interface ComputeHashArgs {
+  node: TaskNode
+  upstream: TaskOutcome[]
+  workspaceRoot: string
+  workspaceFingerprint: string
+  cache: CacheLayer
+  forwardArgs?: readonly string[] | undefined
+  nestedProjectDirs: string[]
+  gitFilesCache?: GitFilesCache
+  hashCache?: HashCache
+  /**
+   * When provided, the resolved `CacheKeyInput` components are pushed
+   * here (one per key contribution) so the caller can persist them.
+   * No effect on the returned hash — pure capture of values `key()`
+   * already folds. The push happens inside `cache.key()` at each fold
+   * site, so the recorded set can't drift from the key.
+   */
+  captureInto?: TaskInputComponent[]
+}
+
+/**
+ * Resolve every input the cache key depends on (file content, env
+ * values, upstream hashes, config bytes, project package.json bytes,
+ * forwardArgs) and ask the cache layer to combine them. Used by both
+ * `executeTask` for the real run and `plan()` for `--dry-run` /
+ * `--graph` previews.
+ *
+ * Caller is responsible for handling the group-task case before
+ * calling this — groups have no `exec` and no `cache.inputs`, so the
+ * key-derivation steps below would all fall back to defaults.
+ * `computeGroupHash` is exported for that purpose.
+ */
+export async function computeTaskHash(args: ComputeHashArgs): Promise<string> {
+  const cfg = args.node.config
+  const cacheCfg: CacheConfig | undefined = cfg.cache
+  const outputs = cacheCfg?.outputs.files ?? []
+
+  const resolved = await resolveInputs({
+    projectDir: args.node.projectDir,
+    workspaceRoot: args.workspaceRoot,
+    envSource: process.env,
+    inputs: cacheCfg?.inputs,
+    ownOutputs: outputs,
+    ownWorkspaceOutputs: cacheCfg?.outputs.workspaceFiles ?? [],
+    nestedProjectDirs: args.nestedProjectDirs,
+    ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
+    ...(args.hashCache !== undefined
+      ? {
+          runtimeCache: args.hashCache.runtime,
+          workspaceRuntimeCache: args.hashCache.workspaceRuntime,
+        }
+      : {}),
+  })
+
+  const upstreamPairs = filterUpstreamHashes(
+    args.upstream,
+    cacheCfg?.inputs?.tasks,
+    args.node.projectName,
+    args.node.id,
+  )
+  const upstreamHashes = upstreamPairs.map(([, hash]) => hash)
+  // hash → upstream task id, for capture-row naming only (not folded).
+  const upstreamIds = new Map(upstreamPairs.map(([id, hash]) => [hash, id]))
+  // Trusted index-OID map for this project (populated by the run's
+  // bulk `git ls-files -s` + `git status` pass). Mapped files skip
+  // hashFile entirely; everything else falls back to the identical
+  // in-process blob-OID computation. Tasks declaring workspaceFiles
+  // also merge the workspace-wide partition's OIDs (keyed by abs
+  // path, so the two maps agree wherever they overlap).
+  let fileHashes = args.gitFilesCache?.oidsFor(args.node.projectDir)
+  if ((cacheCfg?.inputs.workspaceFiles?.length ?? 0) > 0) {
+    const wsOids = args.gitFilesCache?.oidsFor(args.workspaceRoot)
+    if (wsOids !== undefined && wsOids !== fileHashes) {
+      fileHashes = fileHashes === undefined ? wsOids : new Map([...wsOids, ...fileHashes])
+    }
+  }
+  const taskConfigHash = hashTaskConfig(cfg, args.hashCache)
+  const projectPackageJsonHash = await hashProjectPackageJson(
+    args.node.projectDir,
+    args.cache,
+    args.hashCache,
+    fileHashes,
+  )
+
+  const effectiveForwardArgs = args.node.requested ? (args.forwardArgs ?? []) : []
+
+  return await args.cache.key({
+    taskId: args.node.id,
+    taskConfigHash,
+    projectPackageJsonHash,
+    envValues: resolved.envValues,
+    runtimeValues: resolved.runtimeValues,
+    workspaceRuntimeValues: resolved.workspaceRuntimeValues,
+    inputFiles: resolved.files,
+    workspaceRoot: args.workspaceRoot,
+    upstreamHashes,
+    upstreamIds,
+    workspaceFingerprint: args.workspaceFingerprint,
+    forwardArgs: effectiveForwardArgs,
+    ...(fileHashes !== undefined ? { fileHashes } : {}),
+    ...(args.captureInto !== undefined ? { captureInto: args.captureInto } : {}),
+  })
+}
+
+/**
+ * Hash the resolved task config. Folds every config-time decision
+ * (command, env names, dependsOn, cache directives, outputs,
+ * passThroughEnv list, etc.) into the cache key. Imported values
+ * participate because the loader has already baked them into the
+ * resolved object before we serialize.
+ *
+ * The schema is JSON-serializable by construction (no functions in
+ * fields). The `hashCache.taskConfig` WeakMap is consulted first —
+ * each task's config object is created once per run, so a hit there
+ * skips the JSON.stringify + xxh3 entirely.
+ */
+function hashTaskConfig(cfg: TaskConfig, hashCache?: HashCache): string {
+  if (hashCache) {
+    const cached = hashCache.taskConfig.get(cfg)
+    if (cached !== undefined) return cached
+    const hash = xxh3hex(JSON.stringify(cfg))
+    hashCache.taskConfig.set(cfg, hash)
+    return hash
+  }
+  return xxh3hex(JSON.stringify(cfg))
+}
+
+/**
+ * Derive a stable hash for a group task (no `exec`) from its upstream
+ * outcomes. Lets downstream tasks that filter `inputs.tasks` to
+ * include a group still invalidate naturally when anything beneath
+ * the group changes. Sorted so the hash is order-independent. Empty
+ * group (no upstream) yields a fixed sentinel hash.
+ */
+export function computeGroupHash(upstream: TaskOutcome[]): string {
+  const ids = upstream
+    .map((u) => `${u.node.id}:${u.hash ?? ''}`)
+    .sort()
+    .join('|')
+  return xxh3hex(`group|${ids}`)
+}
+
+/**
+ * Hash the project's `package.json` bytes. Folded into every task's
+ * cache key in that project so dep changes (devDependencies, scripts,
+ * version bumps) invalidate the project's tasks even when
+ * `cache.inputs.files` is narrow and doesn't cover the file.
+ *
+ * Matches Turbo and Nx's "implicit dependencies" behavior. Returns
+ * '' for the edge case of a project without a package.json (impossible
+ * in practice — workspace discovery requires one).
+ *
+ * Two optimizations: routed through `Cache.hashFile` so the mtime+size
+ * fast path applies (an unchanged pkg.json takes a stat + SQLite SELECT
+ * instead of a full file read). And memoized within-run per projectDir
+ * so a monorepo with 100 projects × 3 tasks each does 100 lookups, not
+ * 300.
+ */
+async function hashProjectPackageJson(
+  projectDir: string,
+  cache: CacheLayer,
+  hashCache?: HashCache,
+  fileHashes?: ReadonlyMap<string, string>,
+): Promise<string> {
+  const cached = hashCache?.packageJson.get(projectDir)
+  if (cached !== undefined) return cached
+  const promise = doHashProjectPackageJson(projectDir, cache, fileHashes)
+  hashCache?.packageJson.set(projectDir, promise)
+  return promise
+}
+
+async function doHashProjectPackageJson(
+  projectDir: string,
+  cache: CacheLayer,
+  fileHashes?: ReadonlyMap<string, string>,
+): Promise<string> {
+  const filePath = path.join(projectDir, 'package.json')
+  // Clean tracked package.json: its index OID is already in hand —
+  // no exists probe, no stat, no SQLite.
+  const oid = fileHashes?.get(filePath)
+  if (oid !== undefined) return oid
+  if (!(await Bun.file(filePath).exists())) return ''
+  // Route through the cache layer's mtime+size fast path so the
+  // typical re-run sees a stat + SQLite lookup instead of a file read.
+  return await cache.hashFile(filePath)
+}

package/src/orchestrator/telemetry-host.ts

@@ -0,0 +1,80 @@
+// Telemetry consultation — sibling to plugin-host.ts, for the observe-only
+// `telemetry` capability. Asks each declared plugin for its sink(s),
+// collects them, and (only if at least one exists) wires a TelemetrySource
+// onto the run event bus.
+//
+// PERF INVARIANT: with zero registered sinks, NOTHING subscribes to the bus
+// and the returned handle is a no-op — the hot path is byte-identical to a
+// run with no telemetry plugin. A plugin that declines (returns undefined,
+// e.g. otel() with no OTLP endpoint) contributes no sink, so it costs
+// nothing. This is what keeps telemetry off the critical path entirely.
+//
+// See docs/design/observability-architecture-2026-06.md §1, §3.
+
+import type { EventBus } from './events.js'
+import type {
+  RunContextRecord,
+  RunSummaryRecord,
+  TelemetryContext,
+  TelemetrySink,
+} from './telemetry.js'
+import { createTelemetrySource } from './telemetry.js'
+import type { VxPlugin } from './plugin.js'
+
+/** A wired telemetry handle, present ONLY when at least one sink exists. */
+export interface TelemetryHandle {
+  /** Emit the per-run summary to every sink (crash-isolated). */
+  emitSummary(summary: RunSummaryRecord): void
+  /** Await every sink's flush (crash-isolated, time-bounded by the sink). */
+  flush(): Promise<void>
+  /** Remove the bus subscription. Idempotent. */
+  dispose(): void
+}
+
+/**
+ * Consult every plugin's `telemetry` capability, collect the sinks, and —
+ * only if at least one sink results — create a TelemetrySource and subscribe
+ * it to the bus. A plugin that throws during consultation is logged + skipped
+ * (observability must never break a run). Returns `undefined` when no sink is
+ * contributed, so the bus gains no subscriber AND the caller does zero
+ * summary-building work — the no-telemetry hot path stays byte-identical.
+ */
+export async function subscribeTelemetry(
+  plugins: readonly VxPlugin[],
+  bus: EventBus,
+  ctx: TelemetryContext,
+  run: RunContextRecord,
+  extraSinks?: readonly TelemetrySink[],
+): Promise<TelemetryHandle | undefined> {
+  const sinks: TelemetrySink[] = extraSinks === undefined ? [] : [...extraSinks]
+  for (const plugin of plugins) {
+    if (plugin.telemetry === undefined) continue
+    let result
+    try {
+      result = await plugin.telemetry(ctx)
+    } catch (err) {
+      ctx.warn(
+        `[vx] plugin '${plugin.name}' telemetry failed to initialize; disabled for this run: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      continue
+    }
+    if (result === undefined) continue
+    if (Array.isArray(result)) sinks.push(...result)
+    else sinks.push(result)
+  }
+
+  if (sinks.length === 0) return undefined
+
+  const source = createTelemetrySource({ sinks, run })
+  const dispose = bus.subscribe(source.subscriber)
+  let disposed = false
+  return {
+    emitSummary: (summary) => source.emitSummary(summary),
+    flush: () => source.flush(),
+    dispose() {
+      if (disposed) return
+      disposed = true
+      dispose()
+    },
+  }
+}