@vzn/vx 0.0.638 → 0.0.639

package/src/graph/task-status.ts

@@ -0,0 +1,95 @@
+// A task's terminal status and what each one means: a pass, a hit, where
+// its result came from. One vocabulary every reader (the run verdict, the
+// logger, the history queries, telemetry, plugins) asks, so none re-lists
+// the statuses.
+
+export type TaskStatus =
+  | 'success'
+  | 'cache-hit'
+  | 'cache-hit-remote'
+  | 'failed'
+  | 'skipped'
+  // A child killed by a shutdown signal (SIGINT/SIGTERM — e.g. Ctrl-C):
+  // the task never finished on its own terms, so it reverts to aborted —
+  // excluded from the tally and the run history. It still PROPAGATES like
+  // a failure (see `willSkip`): the child died mid-write, so its outputs
+  // are partial.
+  | 'aborted'
+
+/** Where a task's result came from, derived ONCE in core from the status. */
+export type CacheSource = 'miss' | 'local' | 'remote' | 'none'
+
+/**
+ * Map a task outcome status to its cache source. `success`/`failed` ran
+ * (a miss as far as the cache read is concerned); the two cache-hit
+ * statuses restored from local/remote; `skipped`/`aborted` never engaged
+ * the cache. Pure function — the single place this mapping is decided;
+ * `isCacheHit` below is derived from it rather than re-listing the two
+ * hit statuses, so there is one decision, not two that can disagree.
+ */
+export function deriveCacheSource(status: TaskStatus): CacheSource {
+  switch (status) {
+    case 'cache-hit':
+      return 'local'
+    case 'cache-hit-remote':
+      return 'remote'
+    case 'success':
+    case 'failed':
+      return 'miss'
+    case 'skipped':
+    case 'aborted':
+      return 'none'
+  }
+}
+
+/**
+ * Whether each status counts as a PASS. Written as a `Record<TaskStatus, …>`
+ * rather than a `new Set([...])` on purpose: a Record must name every member,
+ * so adding a status to the union is a COMPILE error HERE and the omission
+ * cannot ship. A Set of string literals has no such tripwire — it silently
+ * answers `false` for the new member, which is how ten hand-rolled copies of
+ * this vocabulary accumulated across core, cloud and the dashboard.
+ */
+const PASSES: Record<TaskStatus, boolean> = {
+  success: true,
+  'cache-hit': true,
+  'cache-hit-remote': true,
+  failed: false,
+  skipped: false,
+  aborted: false,
+}
+
+/**
+ * Every `TaskStatus`, at runtime. Read off `PASSES`'s keys, which the
+ * `Record<TaskStatus, …>` type guarantees is exactly the union — so this is
+ * derived, not a second list that can fall behind. Exported so a consumer that
+ * cannot import the type (a test asserting a copy of this vocabulary in
+ * another package agrees) can still enumerate the real set.
+ */
+export const TASK_STATUSES: readonly TaskStatus[] = Object.keys(PASSES) as TaskStatus[]
+
+/**
+ * Did the task pass? A cache hit counts — it produced the same result without
+ * spending the time, which is the whole point. `skipped` and `aborted` do NOT:
+ * neither finished on its own terms, so neither can vouch for anything.
+ *
+ * Takes `string`, not `TaskStatus`, because most callers hold a status that
+ * arrived over a wire or out of a database column. An unrecognised string
+ * reads as NOT passing — the safe direction, since the alternative is calling
+ * a run green on a status this build has never heard of.
+ */
+export function isPassStatus(status: string): boolean {
+  return PASSES[status as TaskStatus] === true
+}
+
+/**
+ * Did the task's result come out of the cache (either layer)? Derived from
+ * `deriveCacheSource` rather than re-listing the two hit statuses, so the two
+ * cannot disagree about what a hit is. Unknown strings read as not-a-hit.
+ */
+export function isCacheHit(status: string): boolean {
+  // No known-status guard: an unknown string falls through the switch to
+  // undefined, which is neither hit source (the guard survived item 654).
+  const source = deriveCacheSource(status as TaskStatus)
+  return source === 'local' || source === 'remote'
+}

package/src/{orchestrator → history}/failure-mode.ts

@@ -10,7 +10,7 @@
 
 import type { Database } from 'bun:sqlite'
 import { KEYED_RUNS_SQL } from '../cache/index.js'
-import { isCacheHit, TASK_STATUSES } from './telemetry.js'
+import { isCacheHit, TASK_STATUSES } from '../graph/index.js'
 
 // SQL hit set derived from the predicate — never a hand-typed list and never
 // a prefix LIKE (a prefix counts any status merely NAMED cache-hit-*). The

package/src/{orchestrator → history}/history.ts

@@ -16,7 +16,7 @@ import { branchSource, EXECUTED_RUNS_SQL } from '../cache/index.js'
 import { splitTaskId } from '../util/index.js'
 import { failureModeOf, mixedOutcomeKeysSql } from './failure-mode.js'
 import type { FailureMode } from './failure-mode.js'
-import { isPassStatus, TASK_STATUSES } from './telemetry.js'
+import { isPassStatus, TASK_STATUSES } from '../graph/index.js'
 
 const DEFAULT_RECENT = 50
 

package/src/history/index.ts

@@ -0,0 +1,48 @@
+// What runs leave behind, read back: the duration table a schedule learns
+// from, the flakiness verdict, the queries behind `vx last` / `vx why`, and
+// what a miss's key changed. Read-only SQL over the cache's database; it
+// never runs, renders or writes a run.
+export {
+  EmptyHistoryProvider,
+  type HistoryProvider,
+  type HistoryTable,
+  LocalHistoryProvider,
+  PASS_STATUSES,
+  type TaskHistory,
+  type TaskResources,
+} from './history.js'
+export {
+  detectFlaky,
+  type FailureMode,
+  type FlakyCandidate,
+  type FlakyFinding,
+  type FlakyTask,
+  flakyTasks,
+} from './failure-mode.js'
+export {
+  cacheKeyDiff,
+  explainCacheKey,
+  getInvocation,
+  getRun,
+  inputWriters,
+  latestRunId,
+  listInvocations,
+  listRuns,
+  rootCauses,
+  whyDidThisRerun,
+} from './metrics.js'
+export type {
+  CacheEntryRow,
+  CacheKeyDiff,
+  CacheKeyExplanation,
+  InputDiffEntry,
+  InputWriter,
+  InvocationDetail,
+  ListInvocationsArgs,
+  ListRunsArgs,
+  RootCause,
+  RunDetail,
+  RunSummaryRow,
+  WhyDidThisRerun,
+} from './metrics.js'
+export { createMissExplainer, type MissExplainer } from './miss-reason.js'

package/src/{orchestrator → history}/metrics.ts

@@ -15,11 +15,9 @@ import { statSync } from 'node:fs'
 import path from 'node:path'
 // The keyed-run predicate lives beside the schema in cache/cache.ts, so a
 // rule written once cannot drift.
-import { KEYED_RUNS_SQL } from '../cache/index.js'
-import { splitTaskId } from '../graph/index.js'
+import { KEYED_RUNS_SQL, type TaskInputComponent } from '../cache/index.js'
+import { isPassStatus, splitTaskId } from '../graph/index.js'
 import { clampInt, MASKED, secretNamed } from '../util/index.js'
-import type { TaskInputComponent } from './task-hash.js'
-import { isPassStatus } from './telemetry.js'
 
 // A recorded `cache_policy` is the `--cache-policy` spec (`local:rw,remote:r`).
 const readsCache = (spec: string): boolean => /(?:^|,)(?:local|remote):w?r/.test(spec)
@@ -57,6 +55,8 @@ export interface RunSummaryRow {
   notReady: 'timeout' | 'exited' | 'spawn' | null
   /** The task ran with the run's forwarded args (`-- …`): a requested one under a run that had some. */
   forwarded: boolean
+  /** Each remote read or write of its key that failed, `upload: <message>`, `; `-joined (v40). */
+  remoteError: string | null
 }
 
 export interface ListRunsArgs {
@@ -117,7 +117,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
               wallclock_start_ns AS wallclockStartNs, wallclock_end_ns AS wallclockEndNs,
               blocked_by AS blockedBy, timed_out AS timedOut,
               sandbox_violations AS sandboxViolations, not_ready AS notReady,
-              forward_args IS NOT NULL AS forwarded
+              forward_args IS NOT NULL AS forwarded, remote_error AS remoteError
        FROM runs ${clause} ORDER BY id DESC LIMIT ?`,
     )
     .all(...params, limit) as RawRow[]
@@ -135,8 +135,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
 
 /**
  * One `vx run` invocation header — every `invocations` column, camelCased,
- * `tags` parsed to a `Record<string,string>` and `dirty`/`ci`/`exitOk`
- * surfaced as booleans. The SPA's
+ * `dirty`/`ci`/`exitOk` surfaced as booleans. The SPA's
  * existing fields (runId / startedAt / endedAt / taskCount / failedCount /
  * hitCount / totalDurationMs) are all present, so existing views keep working.
  */
@@ -170,7 +169,6 @@ export interface InvocationDetail {
   os: string | null
   arch: string | null
   vxVersion: string
-  tags: Record<string, string>
 }
 
 interface InvocationRawRow {
@@ -201,7 +199,6 @@ interface InvocationRawRow {
   os: string | null
   arch: string | null
   vxVersion: string
-  tags: string
 }
 
 const INVOCATION_COLUMNS = `
@@ -214,7 +211,7 @@ const INVOCATION_COLUMNS = `
   restored_remote_count AS restoredRemoteCount,
   exit_ok AS exitOk,
   commit_sha AS commitSha, branch, dirty, ci, ci_provider AS ciProvider,
-  host, os, arch, vx_version AS vxVersion, tags`
+  host, os, arch, vx_version AS vxVersion`
 
 function mapInvocation(r: InvocationRawRow): InvocationDetail {
   let requestedTasks: string[] = []
@@ -222,15 +219,6 @@ function mapInvocation(r: InvocationRawRow): InvocationDetail {
     const parsed = JSON.parse(r.requestedTasks) as unknown
     if (Array.isArray(parsed)) requestedTasks = parsed.map(String)
   } catch {}
-  let tags: Record<string, string> = {}
-  try {
-    const parsed = JSON.parse(r.tags) as unknown
-    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
-      tags = Object.fromEntries(
-        Object.entries(parsed as Record<string, unknown>).map(([k, v]) => [k, String(v)]),
-      )
-    }
-  } catch {}
   return {
     runId: r.runId,
     command: r.command,
@@ -259,7 +247,6 @@ function mapInvocation(r: InvocationRawRow): InvocationDetail {
     os: r.os,
     arch: r.arch,
     vxVersion: r.vxVersion,
-    tags,
   }
 }
 

package/src/{orchestrator → history}/miss-reason.ts

@@ -9,7 +9,7 @@
 import type { Database } from 'bun:sqlite'
 import type { InputChanges } from '../graph/index.js'
 import { diffKeyComponents, loadEntryInputs } from './metrics.js'
-import type { TaskInputComponent } from './task-hash.js'
+import type { TaskInputComponent } from '../cache/index.js'
 
 /** How many changed components a miss names; `count` says how many there were. */
 const NAMED = 10

package/src/index.ts

@@ -56,13 +56,9 @@ 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 { currentBranch, LocalHistoryProvider } from './orchestrator/index.js'
-export type {
-  HistoryProvider,
-  HistoryTable,
-  TaskHistory,
-  TaskResources,
-} from './orchestrator/index.js'
+export { currentBranch } from './orchestrator/index.js'
+export { LocalHistoryProvider } from './history/index.js'
+export type { HistoryProvider, HistoryTable, 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'
@@ -72,14 +68,8 @@ export type { AffectedChanges } from './workspace/index.js'
 // docs/cli.md § Programmatic API listed all three (item 387, 2026-09-19).
 export type { RunPlan, PlannedTask } from './orchestrator/index.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './orchestrator/index.js'
-export type {
-  CacheFlags,
-  CachePolicy,
-  Logger,
-  OutputView,
-  RunOptions,
-  RunSummary,
-} from './orchestrator/index.js'
+export type { CacheFlags, CachePolicy, RunOptions, RunSummary } from './orchestrator/index.js'
+export type { Logger, OutputView } from './report/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
@@ -178,8 +168,8 @@ export type {
   RunReportTask,
   PluginHookName,
   PluginHookHandlers,
-  RunStartInfo,
 } from './orchestrator/index.js'
+export type { RunStartInfo } from './report/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`
@@ -211,15 +201,8 @@ export type {
 // 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.
-// `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,
-  isCacheHit,
-  isPassStatus,
-} from './orchestrator/index.js'
+export { type CacheSource, isCacheHit, isPassStatus } from './graph/index.js'
+export { TELEMETRY_SCHEMA_VERSION } 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,
@@ -231,7 +214,6 @@ export { LOG_WIRE_VERSION, TaskLogBuffer } from './orchestrator/index.js'
 // say `128 + SIGKILL`; the decode is the runner's convention, one copy.
 export { exitSignal } from './orchestrator/index.js'
 export type {
-  CacheSource,
   RunContextRecord,
   RunSummaryRecord,
   TaskLogBundle,
@@ -242,5 +224,5 @@ export type {
   TelemetrySink,
 } 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 serializable per-task views.
+export type { TaskView, OutcomeView } from './report/index.js'

package/src/orchestrator/doctor.ts

@@ -30,7 +30,7 @@ import {
   resolveCacheDir,
   resolveStoreRoot,
 } from '../workspace/index.js'
-import { flakyTasks, type FlakyTask } from './failure-mode.js'
+import { flakyTasks, type FlakyTask } from '../history/index.js'
 import type { VxPlugin } from './plugin.js'
 import { discoverProjects, loadProjects, loadWorkspacePlugins, lockReader } from './projects.js'
 import { atPath, envName, resolveSetting, SETTINGS, type SettingSource } from '../settings.js'

package/src/orchestrator/execute-args.ts

@@ -0,0 +1,80 @@
+// What a dispatch hands executeTask: the run's half, built once, and the
+// task's half, looked up per dispatch. The run's half is one fixed-shape
+// object every task spreads; the task's optional fields are assigned only
+// when present: twelve conditional spreads per task cost ~18 ms of object
+// copying on a 1,090-package warm run (X-149).
+
+import type { TaskNode, TaskOutcome } from '../graph/index.js'
+import type { Logger } from '../report/index.js'
+import type { DownloadMode } from './download-policy.js'
+import type { ExecuteArgs } from './execute-task.js'
+import type { ShortCircuit } from './local-shortcircuit.js'
+import { UNPLACED_EXECUTOR, type Placements } from './placement.js'
+
+type TaskField =
+  | 'node'
+  | 'upstream'
+  | 'log'
+  | 'executor'
+  | 'nestedProjectDirs'
+  | 'remoteOnlyNoop'
+  | 'remoteOnly'
+  | 'download'
+  | 'preProbed'
+  | 'upfrontKey'
+  | 'upfrontGroupKey'
+  | 'taintedUpstream'
+  | 'noDependants'
+  | 'terminal'
+
+/** What every task of a run shares; an absent optional stays absent. */
+export type RunScope = Omit<ExecuteArgs, TaskField>
+
+/** Where the task's half is read from, per task id. */
+export interface TaskFacts {
+  log: (node: TaskNode) => Logger
+  placements: Placements
+  nestedDirsByProject: ReadonlyMap<string, string[]>
+  downloadModeOf: ReadonlyMap<string, DownloadMode>
+  shortCircuit: Pick<ShortCircuit, 'preProbed' | 'uncachedKeys' | 'groupKeys'>
+  /** Tasks some other task depends on. */
+  dependedOn: ReadonlySet<string>
+  /** Tasks that hold the terminal (`terminalHolders`). */
+  holders: ReadonlySet<string>
+}
+
+/**
+ * The dispatch builder. `reuseProbe: false` takes the task's key again
+ * instead of the up-front probe (admission's retry after a dropped probe);
+ * `tainted` is the run's taint verdict for this dispatch.
+ */
+export function executeArgsOf(
+  scope: RunScope,
+  facts: TaskFacts,
+): (node: TaskNode, upstream: TaskOutcome[], reuseProbe: boolean, tainted: boolean) => ExecuteArgs {
+  const { placements, shortCircuit } = facts
+  return (node, upstream, reuseProbe, tainted) => {
+    const id = node.id
+    const a: ExecuteArgs = {
+      ...scope,
+      node,
+      upstream,
+      log: facts.log(node),
+      executor: placements.executors.get(id) ?? UNPLACED_EXECUTOR,
+      nestedProjectDirs: facts.nestedDirsByProject.get(node.projectName) ?? [],
+    }
+    const probe = reuseProbe ? shortCircuit.preProbed.get(id) : undefined
+    const upfrontKey = shortCircuit.uncachedKeys.get(id)
+    const upfrontGroupKey = shortCircuit.groupKeys.get(id)
+    if (facts.downloadModeOf.get(id) === 'deferred') a.download = 'deferred'
+    if (placements.remoteOnlyNoop.has(id)) a.remoteOnlyNoop = true
+    if (placements.remoteOnly.has(id)) a.remoteOnly = true
+    if (probe !== undefined) a.preProbed = probe
+    if (upfrontKey !== undefined) a.upfrontKey = upfrontKey
+    if (upfrontGroupKey !== undefined) a.upfrontGroupKey = upfrontGroupKey
+    if (tainted) a.taintedUpstream = true
+    if (!facts.dependedOn.has(id)) a.noDependants = true
+    if (facts.holders.has(id)) a.terminal = true
+    return a
+  }
+}