@vzn/vx 0.0.16 → 0.0.21

package/src/graph/task-graph.ts

@@ -23,8 +23,8 @@ export interface TaskNode {
   /** Ids of tasks that must complete before this one runs. */
   deps: string[]
   /**
-   * True for the tasks the user actually asked for (via cwd, `-r`, `-F`,
-   * or `pkg#task`). False for dependencies pulled in by `dependsOn`
+   * True for the tasks the user actually asked for (via cwd, `--all`,
+   * `--filter`, or `pkg#task`). False for deps pulled in by `dependsOn`
    * expansion. Used by the orchestrator to scope `forwardArgs` so trailing
    * CLI args don't leak into upstream tasks the user didn't address.
    */
@@ -38,12 +38,38 @@ export interface TaskNode {
    * them `requested`, so `forwardArgs` scoping is unaffected.
    */
   surfaced?: boolean
+  /**
+   * Extra cache-key material from plugins' `key` stage, as sorted
+   * `[name, value]` pairs; set by `prepareRun`, folded by `Cache.key`.
+   * Absent when no plugin declares the stage.
+   */
+  keyParts?: ReadonlyArray<readonly [name: string, value: string]>
 }
 
 export function taskId(project: string, task: string): string {
   return `${project}#${task}`
 }
 
+/**
+ * The inverse of `taskId`. Splits on the FIRST `#`, so a task name that itself
+ * contains one round-trips: `taskId('a', 'b#c')` → `'a#b#c'` → `['a', 'b#c']`.
+ *
+ * This exists because it kept being written by hand as `id.split('#', 2)`,
+ * which is NOT the inverse — it discards everything after the second segment,
+ * so `'a#b#c'` reads back as task `'b'`. Six call sites had that form while
+ * `parseDependencySpec` (the surface that decides what actually runs) has
+ * always split on the first `#`, so the query layer and the graph disagreed
+ * about the identity of the same task: a lookup either found nothing or, worse,
+ * answered with a different task's history.
+ *
+ * A `#`-containing task name is legal and pinned elsewhere in the suite, so
+ * this is reachable rather than theoretical.
+ */
+export function splitTaskId(id: string): [project: string, task: string] {
+  const i = id.indexOf('#')
+  return i < 0 ? [id, ''] : [id.slice(0, i), id.slice(i + 1)]
+}
+
 /**
  * A task is a "group" if it has no `exec` — it exists only to chain
  * `dependsOn` (an umbrella for `vx run ci`). Group tasks:
@@ -134,16 +160,54 @@ export function expandRequested(
     if (idx >= 0) {
       const project = spec.slice(0, idx)
       const task = spec.slice(idx + 1)
-      if (projects.get(project)?.config.tasks?.[task]) push(project, task)
+      if (declaresTask(projects, project, task)) push(project, task)
       continue
     }
     for (const name of candidates) {
-      if (projects.get(name)?.config.tasks?.[spec]) push(name, spec)
+      if (declaresTask(projects, name, spec)) push(name, spec)
     }
   }
   return out
 }
 
+/** Shared by `expandRequested` + `unresolvedRequests` so the two can't drift. */
+function declaresTask(projects: Map<string, ProjectEntry>, project: string, task: string): boolean {
+  return projects.get(project)?.config.tasks?.[task] !== undefined
+}
+
+/**
+ * The requested specs `expandRequested` silently dropped — each one
+ * matched NO project, so nothing it asked for will run.
+ *
+ * A bare name matching only SOME projects is normal (sparse tasks across
+ * a workspace) and never reported. An empty `candidates` scope is also
+ * never reported: that is the legitimate "nothing selected" outcome
+ * (`--affected` with nothing changed), not a typo — the CLI's selection
+ * layer owns that message.
+ *
+ * Deduped so `vx run x x` names `x` once.
+ */
+export function unresolvedRequests(
+  tasks: readonly string[],
+  candidates: readonly string[],
+  projects: Map<string, ProjectEntry>,
+): string[] {
+  const out: string[] = []
+  const seen = new Set<string>()
+  for (const spec of tasks) {
+    if (seen.has(spec)) continue
+    const idx = spec.indexOf('#')
+    const resolved =
+      idx >= 0
+        ? declaresTask(projects, spec.slice(0, idx), spec.slice(idx + 1))
+        : candidates.length === 0 || candidates.some((name) => declaresTask(projects, name, spec))
+    if (resolved) continue
+    seen.add(spec)
+    out.push(spec)
+  }
+  return out
+}
+
 export interface BuildGraphOptions {
   projects: Map<string, ProjectEntry>
   packageGraph: PackageGraph
@@ -225,7 +289,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
           `Task ${id}: dependsOn patterns are not supported in the "pkg#task" form (got "${raw}")`,
         )
       }
-      // CLI `--excludeDependencies=name1,name2` drops edges whose target
+      // CLI `--exclude-dependencies=name1,name2` drops edges whose target
       // task name matches, regardless of bucket (self / deps / cross).
       // Pattern specs re-apply the filter per EXPANDED name below.
       if (skipNames?.has(spec.task)) continue
@@ -267,9 +331,15 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         // With a pattern (`^build.*`), a holder is a package declaring
         // AT LEAST ONE matching task and it receives edges to ALL its
         // matches — holder-ness is about declaration, so a holder still
-        // stops the walk even when every match is --excludeDependencies'd.
+        // stops the walk even when every match is --exclude-dependencies'd.
+        //
+        // The declaring project seeds `visited`: package graphs may legally
+        // contain cycles (the common "b devDepends on a for its tests"
+        // shape), and a cycle walks the frontier straight back to the
+        // origin. Mirrors the self-pattern rule below — a task can never
+        // depend on itself.
         const re = isTaskPattern(spec.task) ? compileTaskPattern(spec.task) : null
-        const visited = new Set<string>()
+        const visited = new Set<string>([projectName])
         const frontier = [...packageGraph.directDeps(projectName)]
         while (frontier.length > 0) {
           const target = frontier.pop()!
@@ -320,10 +390,154 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
   }
 
   detectCycle(nodes)
+  detectOutputCollisions(nodes)
   return nodes
 }
 
-function detectCycle(nodes: Map<string, TaskNode>): void {
+/** A glob with no wildcard — it names exactly one path. */
+function isLiteralGlob(g: string): boolean {
+  return g.search(/[*?[\]]/) === -1
+}
+
+/**
+ * True only when two output globs PROVABLY select an overlapping set.
+ *
+ * Deliberately conservative, because the caller REFUSES the run: a false
+ * positive breaks a build that works today, which is worse than the defect
+ * being caught. So the three cases are exactly the ones that can be decided
+ * without a general glob-intersection algorithm:
+ *
+ *   both literal    — equal paths
+ *   literal vs glob — ask the glob whether it matches the literal (exact)
+ *   both globs      — only identical strings; anything else is undecided
+ *                     here and deliberately allowed through
+ *
+ * The rejected alternative was comparing each glob's static prefix. It is
+ * cheaper and catches more, but it is UNSOUND for a refusal — measured:
+ * `dist/vx-*` and `dist/other.txt` share the prefix `dist` while matching
+ * disjoint sets, so a prefix check refuses a legitimate config. (vx's own
+ * `build.bun.*` tasks escape only because they declare distinct literals.)
+ */
+function outputsOverlap(a: string, b: string): boolean {
+  if (isLiteralGlob(a) && isLiteralGlob(b)) return a === b
+  if (isLiteralGlob(a)) return new Bun.Glob(b).match(a)
+  if (isLiteralGlob(b)) return new Bun.Glob(a).match(b)
+  return a === b
+}
+
+/**
+ * Refuse a graph in which two tasks declare overlapping outputs.
+ *
+ * vx cleans a task's declared outputs before it runs AND before a cache-hit
+ * restore, so that the tree ends byte-identical to the cached artifact. That
+ * makes output ownership STRICT — and two tasks claiming the same path
+ * silently destroy each other's work, in whichever order they happen to run,
+ * while the run reports success. It is data loss with a green summary.
+ *
+ * This is a hazard vx CREATED: Turbo restores additively and cannot hit it,
+ * which is why no Turbo test surfaces it and why the parity research had to
+ * reproduce it end to end.
+ *
+ * Scope follows the two namespaces' reach. `outputs.files` is
+ * project-relative, so only tasks in the SAME project can collide;
+ * `outputs.workspaceFiles` is anchored at the workspace root and ignores
+ * project boundaries by design, so ANY two tasks can. No cache key changes —
+ * this only refuses a graph that was already destroying files.
+ */
+function detectOutputCollisions(nodes: Map<string, TaskNode>): void {
+  // INDEX FIRST, then compare — never all-pairs over the graph. A naive
+  // pairwise loop that filters by project INSIDE the loop is quadratic in the
+  // whole graph: measured 1.6 SECONDS at this project's stated target of 1000
+  // projects x 10 tasks, on every run, against a ~120ms warm run. (Same shape
+  // as the scheduler's priority closure, which took 8.5s on a 1090-package
+  // repo before it was rewritten.)
+  //
+  // Both namespaces have a much smaller natural domain:
+  //   files          — project-relative, so only same-project tasks can
+  //                    collide. Bucketing makes this O(sum of k^2) over
+  //                    per-project task counts, and k is single digits.
+  //   workspaceFiles — root-anchored and boundary-free, so any two tasks can
+  //                    collide — but only tasks that DECLARE it participate,
+  //                    and that set is nearly always empty.
+  const byProject = new Map<string, TaskNode[]>()
+  const wsDeclarers: TaskNode[] = []
+  for (const n of nodes.values()) {
+    const outs = n.config.cache?.outputs
+    if ((outs?.files?.length ?? 0) > 0) {
+      const bucket = byProject.get(n.projectName)
+      if (bucket) bucket.push(n)
+      else byProject.set(n.projectName, [n])
+    }
+    if ((outs?.workspaceFiles?.length ?? 0) > 0) wsDeclarers.push(n)
+  }
+
+  for (const bucket of byProject.values()) {
+    for (let i = 0; i < bucket.length; i++) {
+      for (let j = i + 1; j < bucket.length; j++) {
+        const a = bucket[i]!
+        const b = bucket[j]!
+        collide(a, b, a.config.cache?.outputs.files, b.config.cache?.outputs.files, 'files')
+      }
+    }
+  }
+  for (let i = 0; i < wsDeclarers.length; i++) {
+    for (let j = i + 1; j < wsDeclarers.length; j++) {
+      const a = wsDeclarers[i]!
+      const b = wsDeclarers[j]!
+      collide(
+        a,
+        b,
+        a.config.cache?.outputs.workspaceFiles,
+        b.config.cache?.outputs.workspaceFiles,
+        'workspaceFiles',
+      )
+    }
+  }
+}
+
+/**
+ * A `remote: 'only'` task never materialises its outputs on THIS machine —
+ * execute-task turns off both the read and the write axis for it, so there is
+ * no probe, no restore, no output clean and no local save. The collision
+ * hazard is entirely about local cleaning ("whichever runs second DELETES the
+ * other's output"), so a pair including one of these cannot exhibit it: there
+ * is nothing of its on disk to delete, and it deletes nothing of anyone's.
+ *
+ * Found while trying to give two projects their own install-as-an-action:
+ * both legitimately capture the workspace-root `node_modules` under a
+ * hoisting package manager, and the refusal fired on a pair that cannot
+ * exhibit the hazard. That particular layout was abandoned for an unrelated
+ * reason (identical definitions still get different cache keys), so this is
+ * not load-bearing today — it is a refusal narrowed to what it can prove,
+ * which this file's header asks for explicitly.
+ */
+function neverWritesLocally(n: TaskNode): boolean {
+  return n.config.exec?.remote === 'only'
+}
+
+function collide(
+  a: TaskNode,
+  b: TaskNode,
+  aGlobs: readonly string[] | undefined,
+  bGlobs: readonly string[] | undefined,
+  field: 'files' | 'workspaceFiles',
+): void {
+  if (neverWritesLocally(a) || neverWritesLocally(b)) return
+  for (const ga of aGlobs ?? []) {
+    for (const gb of bGlobs ?? []) {
+      if (!outputsOverlap(ga, gb)) continue
+      throw new UserError(
+        `${a.id} and ${b.id} both declare the output ${JSON.stringify(ga)}` +
+          (ga === gb ? '' : ` / ${JSON.stringify(gb)}`) +
+          ` in cache.outputs.${field} — vx cleans a task's declared outputs before it runs and ` +
+          `before a cache-hit restore, so whichever of these runs second DELETES the other's ` +
+          `output and the run still reports success. Give each task its own output path.`,
+      )
+    }
+  }
+}
+
+export function detectCycle(nodes: Map<string, TaskNode>): void {
   // Iterative DFS over dense-indexed colors. Recursion + `Map<string,
   // number>` worked, but deep workspaces (long chains of `dependsOn`)
   // can blow V8's frame budget, and per-node Map lookups dominate the

package/src/index.ts

@@ -3,13 +3,33 @@
 // This is the stable cross-package contract — any plugin or integration
 // package imports everything it needs from here via the bare
 // `'@vzn/vx'` specifier (never a deep `src/...` path). The surface is pinned
-// by tests/package-boundaries.test.ts; a widening updates that snapshot
-// deliberately. See docs/design/core-cloud-split-2026-06.md §3.5.
+// by tests/package-boundaries.unsafe.test.ts; a widening updates that snapshot
+// deliberately. The boundary law: docs/architecture.md § Repository shape.
 
 export { VERSION } from './version.js'
 
 // Clean error type — user-input failures print a message without a stack.
-export { UserError } from './util/index.js'
+// `clampInt` rides along for the same reason the status predicates do:
+// without it on the façade an integration package writes its own, and that
+// had already happened. A bounds helper whose floor is load-bearing (a
+// fractional SQL LIMIT is a datatype mismatch, not a smaller page) should
+// have one implementation.
+export { clampInt, UserError, isUserError } from './util/index.js'
+// "Did you mean": the hint core's own verbs give for a near-miss name, for a
+// plugin verb to give the same one.
+export { nearMatches } from './util/index.js'
+// Every hook a plugin may fill, in pipeline order — the one list the
+// loader, the host and `vx info` read; exported so a doc pin outside core
+// (the site's guides) holds its tables to the same list.
+export { PLUGIN_HOOKS, type PluginHook } from './config.js'
+// The workspace doctor's facts (`vx info`), for a host that answers the
+// same question over another surface — `@vzn/vx-mcp`'s `getWorkspaceInfo`.
+export { collectInfo, type CollectInfoOptions, type InfoFacts } from './orchestrator/index.js'
+// The machine as this process may use it — cores and memory capped by the
+// cgroup a container runs under. Core's default worker count reads the
+// first; a policy that budgets memory (`@vzn/vx-schedule-history`) reads
+// the second, so the cgroup walk has one implementation.
+export { machineMemoryBytes, machineParallelism } from './util/index.js'
 
 // Schema types and helpers (used by user vx.config files and presets).
 export type {
@@ -21,29 +41,26 @@ export type {
   CacheConfig,
   CacheInputs,
   CacheOutputs,
-  ResourcesConfig,
   SandboxConfig,
-  SandboxNetworkConfig,
+  SandboxGrants,
+  SandboxDenials,
 } from './config.js'
 export { defineProject, defineWorkspace } from './config.js'
+export { definePlugin } from './orchestrator/index.js'
 
-// Programmatic engine API (run / plan / prepare) + the graph primitives a
-// distribution submitter/agent reasons over + the cache-key hashing seam.
-// `deriveStableKeys` is THE shared stable-key derivation (remote-prefetch,
-// the local short-circuit, and the distributed submitter must never drift
-// on the stability gate); `captureGitContext`/`captureWorkspaceIdentity`
-// give agents + the submitter identity before/without a telemetry run.
+// Programmatic engine API: run / plan / prepare (docs/cli.md § Programmatic
+// API). The graph primitives, the cache-key hashing seam and the git / host
+// context capture used to sit beside these for a distributed submitter that
+// left the repo (2026-08); they went with it (2026-09-10) — a seam with no
+// consumer is re-added when one appears, shaped by its use.
 export { run, planRun, prepareRun } from './orchestrator/index.js'
+// The per-task duration history a `schedule` plugin learns from
+// (`@vzn/vx-schedule-history` does; a plugin package reaches core only
+// through this façade, which is what put these here).
+export { LocalHistoryProvider } from './orchestrator/index.js'
+export type { HistoryProvider, HistoryTable, TaskHistory } from './orchestrator/index.js'
 export type { PreparedRun } from './orchestrator/index.js'
-export { computeTaskHash, createHashCache, deriveStableKeys } from './orchestrator/index.js'
-export type { DeriveStableKeysArgs, HashCache, StableKey } from './orchestrator/index.js'
-export {
-  captureGitContext,
-  captureWorkspaceIdentity,
-  resolveCacheScope,
-} from './orchestrator/index.js'
-export type { GitContext, WorkspaceIdentity } from './orchestrator/index.js'
-export { FULL_CACHE_POLICY, parseCachePolicy } from './orchestrator/index.js'
+export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './orchestrator/index.js'
 export type {
   CachePolicy,
   Logger,
@@ -51,172 +68,148 @@ export type {
   RunOptions,
   RunSummary,
 } from './orchestrator/index.js'
-export { defaultLogger, resolveOutputView } from './orchestrator/index.js'
-export { buildTaskGraph, expandRequested, isGroupTask, markSurfacedDeps } from './graph/index.js'
-export type {
-  OutputFingerprint,
-  TaskNode,
-  TaskOutcome,
-  TaskStatus,
-  VerifyVerdict,
-} from './graph/index.js'
-// The one output-tree diff implementation (verify verdicts + a serve's
-// cross-machine fingerprint diff both name rels through it).
-export { diffOutputTrees } from './orchestrator/index.js'
+// `splitTaskId` is on the façade because the alternative is what happened:
+// with only `taskId()` to JOIN an id and nothing exported to SPLIT one,
+// consumers roll their own `split('#', 2)` and drift from the graph, which
+// splits on the FIRST '#'.
+export { splitTaskId } from './graph/index.js'
+export type { TaskNode, TaskOutcome, TaskStatus } from './graph/index.js'
 
-// Cache classes + the layer interface (the `cache` capability's currency)
-// and input-output resolution. The blob-CAS/digest substrate
-// (cas-backend.ts / digest.ts) stays module-internal until it has a
-// consumer — no speculative public API. `cleanOutputs` is public for the
-// distributed submitter's targeted output materialization (wipe declared
-// outputs, then `restoreOutputs` the artifact — never a naive re-run).
-export {
-  Cache,
-  LayeredCache,
-  GitFilesCache,
-  cleanOutputs,
-  resolveInputs,
-  resolveOutputs,
-} from './cache/index.js'
+// Cache classes + the layer interface (the `cache` capability's currency).
+export { Cache, LayeredCache } from './cache/index.js'
 export type { CacheLayer, RemoteCacheLayer, RunRecord, InvocationRecord } from './cache/index.js'
 
 // Workspace discovery + the project/config catalog surface — an
-// out-of-process service/CLI needs these. `readLockfile` is THE one reader
-// of vx-lock.json (the format carries its own version sentinel; a second
-// parser in a sibling package would drift), and the loader chain
-// (`loadWorkspace` → `listProjectMetas` → `loadProjectConfig`) is the same
-// one `vx show` uses. Workspace's `listProjects` re-exports as
-// `listProjectMetas` — the bare name belongs to the metrics query below.
-export { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from './workspace/index.js'
-export { readLockfile, LOCKFILE_NAME } from './workspace/index.js'
-export type { Lockfile, LockfileEntry } from './workspace/index.js'
+// out-of-process service/CLI needs these. `loadProjectConfig` is the RAW
+// per-file load (`vx lock` freezes exactly that); the resolved view a run
+// or `vx show` sees — plugin stages applied — is `loadResolvedProjects`
+// below. Workspace's `listProjects` re-exports as `listProjectMetas` (the
+// bare name once belonged to a metrics query).
+export { findWorkspaceRoot } from './workspace/index.js'
 export {
   loadWorkspace,
   loadProjectConfig,
   listProjects as listProjectMetas,
 } from './workspace/index.js'
 export type { ProjectMeta } from './workspace/index.js'
+// The package graph as a run sees it (workspace deps by manifest), for a tool
+// that needs a project's transitive closure the way `vx run` computes it.
+export { buildPackageGraph } from './workspace/index.js'
+// The run path's RESOLVED view — plugin `config` and `project` stages
+// applied, cached evaluations served — for a reader outside the CLI (the
+// MCP server's `listTasks`, an embedder's task catalog). What `vx show`
+// prints.
+export { loadResolvedProjects } from './orchestrator/index.js'
+export type { ProjectEntry } from './workspace/index.js'
+// The migration seam: how a generated config is planned, rendered, guarded
+// and written. `vx init` (package.json scripts) uses it in core;
+// `@vzn/vx-migrate` (Turbo, Nx) and any other adoption tool use it from here.
+export {
+  applyMigration,
+  PERSISTENT_TASK_NAMES,
+  PERSISTENT_TODO,
+  quoteTsLiteral,
+} from './workspace/index.js'
+export type {
+  ApplyMigrationArgs,
+  MigrationFormat,
+  GeneratedProject,
+  GeneratedTask,
+  MigrationPlan,
+  RawExpr,
+} from './workspace/index.js'
 
 // Plugin API — the run-level extension points. Behavior capabilities
-// (backend / cache) change WHAT/HOW work runs; the observe-only `telemetry`
+// (executor / cache) change WHAT/HOW work runs; the observe-only `telemetry`
 // capability is the canonical data-export path and cannot change behavior.
 // A plugin is declared in vx.workspace.ts via defineWorkspace({ plugins }).
 // See docs/design/observability-architecture-2026-06.md.
+// The claimant's shell for a lockfile plugin (`@vzn/vx-lockfile`):
+// the claim, the per-project key, the memo and the `--affected` diff around
+// a parser; `reachDigests` is the Merkle-over-components digest both use.
+export {
+  lockfileClaim,
+  reachDigests,
+  type LockfileClaimHooks,
+  type LockfileClaimOptions,
+  type ReachGraph,
+} from './orchestrator/index.js'
 export type {
   VxPlugin,
-  EventSink,
-  BackendContext,
+  PluginHooks,
+  PluginOrigin,
   CacheContext,
-  EventSinkContext,
+  ExecutorContext,
+  CommandContext,
+  FingerprintChange,
+  FingerprintClaim,
+  FingerprintContext,
+  GraphHookContext,
+  KeyHookContext,
+  PluginCommand,
+  ProjectHookContext,
+  ScheduleHookContext,
+  AdmitContext,
+  WorkspaceHookContext,
   PluginSetupContext,
 } from './orchestrator/index.js'
+// The per-task execution contract a plugin's `executor` capability returns.
+// (`runCommand` / `runSandboxed`, the local executor's own primitives, left
+// the façade 2026-09-10: no executor plugin built on them — `@vzn/vx-reapi`
+// speaks a wire — and a seam with no consumer is a special case in waiting.)
+export type {
+  ExecuteRequest,
+  ExecuteResult,
+  ExecuteSandbox,
+  ResolvedSandboxConfig,
+  TaskExecutor,
+  TaskPlacement,
+} from './exec/index.js'
 
 // Telemetry — THE canonical, versioned data-export contract every exporter
 // (an OTel exporter, an HTTP sink, or any third-party consumer) reads. A sink implements TelemetrySink and is
 // returned from VxPlugin.telemetry(); it receives immutable records and holds
 // no run handle (observe-only by construction).
-export { TELEMETRY_SCHEMA_VERSION, deriveCacheSource } from './orchestrator/index.js'
+// `isPassStatus` / `isCacheHit` are on the façade for the reason the sweep
+// that added them found: with only the raw `TaskStatus` union exported, every
+// consumer rolls its own Set of status literals — and a Set has no
+// compile-time tripwire when the union gains a member, so it silently answers
+// "no" for the new one. `TASK_STATUSES` is the union at runtime, for a
+// consumer that needs the list rather than the predicate.
+// `escapeMarkdownCell` is on the façade for the same demonstrated need: a
+// plugin that renders a run as a markdown table takes the same unvalidated
+// task names core does, and the cloud job summary shipped without the escape.
+export {
+  escapeMarkdownCell,
+  TELEMETRY_SCHEMA_VERSION,
+  deriveCacheSource,
+  isCacheHit,
+  isPassStatus,
+  TASK_STATUSES,
+} from './orchestrator/index.js'
+// `TaskLogBuffer` is on the façade on the same demonstrated need: EVERY
+// telemetry sink that ships build output has to bound it, and the retention
+// rules (per-task tail, per-run budget, failures never evicted by successes,
+// a hit's bytes belong to the run that executed) are a decision, not an
+// implementation detail. Two sinks rolling their own is how they fork.
+export { LOG_WIRE_VERSION, TaskLogBuffer } from './orchestrator/index.js'
 export type {
   CacheSource,
   RunContextRecord,
   RunSummaryRecord,
+  TaskLogBundle,
+  TaskLogEntry,
   TaskTelemetry,
   TelemetryContext,
   TelemetryRecord,
   TelemetrySink,
 } from './orchestrator/index.js'
 
-// The submitter wire contract + backend interface (the `backend`
-// capability's currency) and the serializable event projection.
-export {
-  optionsToRequest,
-  requestToOptions,
-  projectNode,
-  projectOutcome,
-  createWireRenderer,
-} from './orchestrator/index.js'
-export type {
-  RunBackend,
-  RunRequest,
-  RunResult,
-  ClientMessage,
-  ServerMessage,
-} from './orchestrator/index.js'
-
-// Event bus + wire form — adapters (otel-bridge, custom subscribers) ride this.
-export {
-  createEventBus,
-  wireForwarder,
-  toWireEvent,
-  createVxSurface,
-} from './orchestrator/index.js'
-export type {
-  EventBus,
-  RunEvent,
-  RunEventSubscriber,
-  WireEvent,
-  TaskView,
-  OutcomeView,
-} from './orchestrator/index.js'
+// The serializable run result and its per-task views (what `run()` returns).
+export type { RunResult, TaskView, OutcomeView } from './orchestrator/index.js'
 
-// The JSON-RPC 2.0 wire envelope — an out-of-process serve/agent speaks this framing.
-export {
-  clientMessageToEnvelope,
-  decodeEnvelope,
-  encodeForNDJSON,
-  encodeForSSE,
-  encodeForWS,
-  ENVELOPE_ERRORS,
-  envelopeToClientMessage,
-  envelopeToServerMessage,
-  isEnvelope,
-  isNotification,
-  isRequest,
-  makeError,
-  makeNotification,
-  makeRequest,
-  makeResponse,
-  serverMessageToEnvelope,
-  WIRE_CHANNELS,
-  WIRE_PROTOCOL_VERSION,
-} from './orchestrator/index.js'
-export type {
-  Envelope,
-  ErrorResponse,
-  Notification,
-  WireRequest,
-  WireResponse,
-  WireChannel,
-} from './orchestrator/index.js'
-
-// Metrics / analytics query layer over cache.db — a service plugin's HTTP
-// surface reads from these (the queries stay in core; a serve exposes them over HTTP).
-export {
-  cacheKeyDiff,
-  compareRuns,
-  explainCacheKeyQuery,
-  getBottlenecks,
-  getCacheBreakdown,
-  getCacheSavings,
-  getCacheStatsSql,
-  getFlakiestTasks,
-  getHistory,
-  getHitRateSplit,
-  getInvocation,
-  getParallelismHistory,
-  getPeriodComparison,
-  getPrunableEntries,
-  getRecentFailures,
-  getRegressions,
-  getRun,
-  getRunHeatmap,
-  getRunTrends,
-  getStorageGrowth,
-  getTaskDetail,
-  getTopTimeBurners,
-  listCacheEntries,
-  listInvocations,
-  listProjects,
-  listRuns,
-  whyDidThisRerunQuery,
-} from './orchestrator/index.js'
+// The one run-history query a reader outside the CLI takes today: `vx why`'s
+// answer, which `@vzn/vx-mcp` serves. The event bus / wire form and the
+// other history readers (`listRuns`, `getRun`, …) left the façade 2026-09-10
+// with no consumer; the telemetry seam above is the canonical export path.
+export { whyDidThisRerunQuery } from './orchestrator/index.js'