@vzn/vx 0.0.0 → 0.0.14

package/src/orchestrator/verify.ts

@@ -0,0 +1,164 @@
+// Cache-correctness verification (Phase 1: determinism). Pure helpers for the
+// `vx run --verify` hook in execute-task.ts: content-fingerprint a task's
+// output tree (mtime-independent) and diff two runs' trees, so a task whose
+// outputs are NOT a pure function of its declared inputs — a non-hermetic task
+// whose cache entry would replay arbitrary past bytes — is caught and named.
+// See docs/design/cache-correctness-2026-07.md.
+
+import path from 'node:path'
+import type { OutputFingerprint, TaskOutcome, VerifyVerdict } from '../graph/index.js'
+import { xxh3hex } from '../util/index.js'
+
+/** An output file to fingerprint: absolute path + a stable, run-independent
+ *  key (project-relative, or `workspace-outputs/<rel-to-root>` for workspace
+ *  outputs — matching the cache artifact's namespace so the two never collide). */
+export interface OutputRef {
+  abs: string
+  key: string
+}
+
+/** Build the fingerprint key set from a task's resolved output paths. */
+export function outputRefs(
+  projectDir: string,
+  outputFiles: readonly string[],
+  workspaceRoot: string,
+  workspaceOutputFiles: readonly string[],
+): OutputRef[] {
+  const rel = (from: string, abs: string): string =>
+    path.relative(from, abs).split(path.sep).join('/')
+  return [
+    ...outputFiles.map((abs) => ({ abs, key: rel(projectDir, abs) })),
+    ...workspaceOutputFiles.map((abs) => ({
+      abs,
+      key: `workspace-outputs/${rel(workspaceRoot, abs)}`,
+    })),
+  ]
+}
+
+/** Content-fingerprint an output tree: key → xxh3 of the file's BYTES, read
+ *  unconditionally from disk. Deliberately NOT `Cache.hashFile`: its
+ *  mtime+size memo would return attempt 1's digest for a re-run output with
+ *  equal size and mtime (e.g. a build that normalizes mtimes — standard
+ *  reproducible-build practice), silently proving a divergent task
+ *  deterministic. fp1/fp2 are only ever compared to each other, so any
+ *  content hash works — and the proof must not trust a cache. */
+export async function hashOutputTree(refs: readonly OutputRef[]): Promise<Map<string, string>> {
+  const out = new Map<string, string>()
+  for (const r of refs) {
+    out.set(r.key, xxh3hex(new Uint8Array(await Bun.file(r.abs).arrayBuffer())))
+  }
+  return out
+}
+
+/** Per-file map cap on a shipped fingerprint (~40 KB at the cap). The tree
+ *  digest always folds ALL entries, so detection never depends on the map. */
+export const FP_MAX_FILES = 500
+
+/** Roll an output-tree fingerprint map into the shippable `OutputFingerprint`
+ *  payload (Phase 4, cross-machine diff): a tree digest over ALL sorted
+ *  entries folded `key\0hash\n` (\0 boundaries so parts can't alias), plus
+ *  the first-`cap` pairs — deterministic truncation, so two machines'
+ *  truncated maps cover the same key subset and stay diffable. */
+export function foldFingerprint(fp: Map<string, string>, cap = FP_MAX_FILES): OutputFingerprint {
+  const keys = [...fp.keys()].sort()
+  let folded = ''
+  for (const k of keys) folded += `${k}\0${fp.get(k)!}\n`
+  return {
+    tree: xxh3hex(folded),
+    fileCount: keys.length,
+    files: keys.slice(0, cap).map((k) => [k, fp.get(k)!] as const),
+    ...(keys.length > cap ? { truncated: true } : {}),
+  }
+}
+
+/** The output keys whose content OID differs between two fingerprints
+ *  (added, removed, or changed), sorted. */
+export function diffOutputTrees(a: Map<string, string>, b: Map<string, string>): string[] {
+  const changed: string[] = []
+  for (const k of new Set([...a.keys(), ...b.keys()])) {
+    if (a.get(k) !== b.get(k)) changed.push(k)
+  }
+  return changed.sort()
+}
+
+/** Turn a determinism diff into a verdict, honoring the `--verify-allow`
+ *  escape hatch (an allowed divergence is reported but never fails the run). */
+export function classifyDeterminism(changed: readonly string[], allowed: boolean): VerifyVerdict {
+  if (changed.length === 0) return { kind: 'proven-deterministic' }
+  return allowed
+    ? { kind: 'allowed-nondeterministic', changed }
+    : { kind: 'nondeterministic', changed }
+}
+
+/** Extract the workspace-relative paths a task read outside its declared inputs
+ *  (Phase 2, `--verify=inputs`). A strace-derived violation line carries the
+ *  offending absolute path in trailing brackets (`… [/abs/path]`); pull it out,
+ *  make it workspace-relative, dedup, and sort. Lines without a bracketed path
+ *  (e.g. macOS syscall lines) fall back to the raw line so nothing is lost. */
+export function undeclaredInputPaths(
+  violations: readonly { line: string }[],
+  workspaceRoot: string,
+): string[] {
+  const rels = new Set<string>()
+  for (const v of violations) {
+    const m = /\[([^\]]+)\]\s*$/.exec(v.line)
+    const raw = m ? m[1]! : v.line
+    rels.add(
+      path.isAbsolute(raw) ? path.relative(workspaceRoot, raw).split(path.sep).join('/') : raw,
+    )
+  }
+  return [...rels].sort()
+}
+
+/** The end-of-run `--verify` summary section: a counts line plus a
+ *  failures block naming each non-hermetic task and its diverging outputs.
+ *  Empty when no task carried a verdict. */
+export function formatVerifySection(outcomes: readonly TaskOutcome[]): string[] {
+  const verdicts = outcomes.filter((o) => o.verify !== undefined)
+  if (verdicts.length === 0) return []
+  let proven = 0
+  let bad = 0
+  let na = 0
+  let notVerified = 0
+  for (const o of verdicts) {
+    switch (o.verify!.kind) {
+      case 'proven-deterministic':
+      case 'proven-complete':
+        proven++
+        break
+      case 'nondeterministic':
+      case 'rerun-failed':
+      case 'undeclared-inputs':
+        bad++
+        break
+      case 'allowed-nondeterministic':
+      case 'no-outputs':
+        na++
+        break
+      case 'not-verified':
+        notVerified++
+        break
+    }
+  }
+  const lines = [
+    '',
+    `  Verify:   ${proven} proven · ${bad} unsafe · ${na} n/a · ${notVerified} not-verified`,
+  ]
+  for (const o of outcomes) {
+    const v = o.verify
+    if (v === undefined) continue
+    if (v.kind === 'nondeterministic') {
+      lines.push(`    ✗ ${o.node.id} — nondeterministic`)
+      lines.push(`        changed: ${v.changed.join(', ')}`)
+    } else if (v.kind === 'undeclared-inputs') {
+      lines.push(`    ✗ ${o.node.id} — read undeclared inputs`)
+      if (v.paths.length > 0) lines.push(`        ${v.paths.join(', ')}`)
+      lines.push('        add them to cache.inputs.files / workspaceFiles')
+    } else if (v.kind === 'rerun-failed') {
+      lines.push(`    ✗ ${o.node.id} — verify re-run failed (exit ${v.exitCode})`)
+    } else if (v.kind === 'allowed-nondeterministic') {
+      lines.push(`    ⚠ ${o.node.id} — nondeterministic (allowed)`)
+    }
+  }
+  return lines
+}

package/src/orchestrator/wire-render.ts

@@ -0,0 +1,92 @@
+// The inverse of `wireForwarder`: turn a stream of `WireEvent`s back into
+// `Logger` calls on a concrete renderer. A `vx serve` client feeds the
+// service's event stream through this into a normal `defaultLogger`, so a
+// DELEGATED run renders identically to a local one — the terminal
+// renderer stays completely untouched (it just receives reconstructed
+// node-shaped objects instead of live graph nodes). This file is the
+// whole adapter; it can be rewritten or removed without touching the
+// renderer or the producer side.
+
+import type { TaskNode, TaskOutcome } from '../graph/index.js'
+import type { Logger } from './logger.js'
+import type { OutcomeView, TaskView, WireEvent } from './events.js'
+
+/**
+ * Rebuild a node-shaped object from a `TaskView`. The formatters only ever
+ * read `id` / `projectName` / `taskName` / `requested` / `surfaced` and
+ * `config.exec` (presence ⇒ not a group; `.command`; `.persistent`), so a
+ * structural stand-in is indistinguishable from a real `TaskNode` to them.
+ */
+function reconstructNode(view: TaskView): TaskNode {
+  const exec = view.isGroup
+    ? undefined
+    : {
+        command: view.command ?? '',
+        ...(view.persistent ? { persistent: { readyWhen: '' } } : {}),
+      }
+  return {
+    id: view.id,
+    projectName: view.project,
+    taskName: view.task,
+    requested: view.requested,
+    surfaced: view.surfaced,
+    config: exec === undefined ? {} : { exec },
+  } as unknown as TaskNode
+}
+
+function reconstructOutcome(view: OutcomeView, node: TaskNode): TaskOutcome {
+  return {
+    node,
+    status: view.status,
+    exitCode: view.exitCode,
+    durationMs: view.durationMs,
+    ...(view.restored !== undefined ? { restored: view.restored } : {}),
+    ...(view.sandboxViolations !== undefined ? { sandboxViolations: view.sandboxViolations } : {}),
+    ...(view.sandboxViolationLines !== undefined
+      ? { sandboxViolationLines: view.sandboxViolationLines }
+      : {}),
+  } as TaskOutcome
+}
+
+/**
+ * Build a `WireEvent` consumer that drives `sink` (typically a
+ * `defaultLogger`). Stateful: it accumulates the reconstructed nodes from
+ * `task:start` so later `task:*` events can resolve their node by id.
+ */
+export function createWireRenderer(sink: Logger): (event: WireEvent) => void {
+  const nodes = new Map<string, TaskNode>()
+  return (event) => {
+    switch (event.kind) {
+      case 'run:start':
+        sink.runStart?.(event.info)
+        return
+      case 'task:start': {
+        const node = reconstructNode(event.task)
+        nodes.set(node.id, node)
+        sink.taskStart?.(node)
+        return
+      }
+      case 'task:stdout': {
+        const node = nodes.get(event.taskId)
+        if (node) sink.taskStdout(node, event.chunk)
+        return
+      }
+      case 'task:stderr': {
+        const node = nodes.get(event.taskId)
+        if (node) sink.taskStderr(node, event.chunk)
+        return
+      }
+      case 'task:complete': {
+        const node = nodes.get(event.outcome.taskId)
+        if (node) sink.taskComplete(node, reconstructOutcome(event.outcome, node))
+        return
+      }
+      case 'run:status':
+        sink.status(event.line)
+        return
+      case 'run:end':
+        sink.runEnd?.()
+        return
+    }
+  }
+}

package/src/orchestrator/wire.ts

@@ -0,0 +1,212 @@
+// JSON-RPC 2.0 envelope + OTel-LogRecord payload — the wire spec
+// committed by docs/design/wire-protocol-2026-06.md. Lives alongside
+// the existing protocol.ts (t-discriminated ServerMessage/ClientMessage)
+// so vx serve can speak both formats during the transition.
+//
+// One envelope, three transports (WS / SSE / NDJSON), four channels
+// (vx:events / vx:state / vx:rpc / vx:submit). Every external consumer
+// that already speaks JSON-RPC works against vx out of the box.
+//
+// Pure types + a small adapter pair. No transport here; the Hono
+// router in src/cli/serve.ts wires the byte frames.
+
+import type { RunRequest, RunResult, ServerMessage, ClientMessage } from './protocol.js'
+import type { WireEvent as InternalWireEvent } from './events.js'
+
+/** Protocol version returned by GET /version. */
+export const WIRE_PROTOCOL_VERSION = '1.0'
+
+/** The four channels we expose; clients pick the subset they care about. */
+export const WIRE_CHANNELS = ['vx:events', 'vx:state', 'vx:rpc', 'vx:submit'] as const
+export type WireChannel = (typeof WIRE_CHANNELS)[number]
+
+/** JSON-RPC 2.0 method names emitted by the server (notifications). */
+export type ServerNotificationMethod = 'events.append' | 'state.patch'
+
+/** JSON-RPC 2.0 method names dispatched from the client (request/response). */
+export type ClientRequestMethod = 'state.snapshot' | 'submit.run' | `rpc.${string}`
+
+/**
+ * The JSON-RPC 2.0 envelope. One of four shapes per the spec.
+ *
+ *   - request:      { jsonrpc, id, method, params? }
+ *   - response:     { jsonrpc, id, result }
+ *   - error:        { jsonrpc, id, error: { code, message, data? } }
+ *   - notification: { jsonrpc, method, params? }
+ */
+export type Envelope = Request | Response | ErrorResponse | Notification
+
+export interface Request {
+  jsonrpc: '2.0'
+  id: number | string
+  method: string
+  params?: unknown
+}
+
+export interface Response {
+  jsonrpc: '2.0'
+  id: number | string
+  result: unknown
+}
+
+export interface ErrorResponse {
+  jsonrpc: '2.0'
+  id: number | string
+  error: { code: number; message: string; data?: unknown }
+}
+
+export interface Notification {
+  jsonrpc: '2.0'
+  method: string
+  params?: unknown
+}
+
+/** JSON-RPC 2.0 error codes used by vx. The spec reserves -32000..-32099 for impl-defined. */
+export const ENVELOPE_ERRORS = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  USER_ERROR: -32000, // a vx UserError — clean message, no stack
+  TASK_HASH_UNKNOWN: -32001,
+  RUN_NOT_FOUND: -32002,
+  UNAUTHORIZED: -32003,
+  RATE_LIMITED: -32004,
+} as const
+
+/** Build a request envelope. */
+export function makeRequest(id: number | string, method: string, params?: unknown): Request {
+  const req: Request = { jsonrpc: '2.0', id, method }
+  if (params !== undefined) req.params = params
+  return req
+}
+
+/** Build a notification envelope. */
+export function makeNotification(method: string, params?: unknown): Notification {
+  const note: Notification = { jsonrpc: '2.0', method }
+  if (params !== undefined) note.params = params
+  return note
+}
+
+/** Build a success response envelope. */
+export function makeResponse(id: number | string, result: unknown): Response {
+  return { jsonrpc: '2.0', id, result }
+}
+
+/** Build an error response envelope. */
+export function makeError(
+  id: number | string,
+  code: number,
+  message: string,
+  data?: unknown,
+): ErrorResponse {
+  const err: ErrorResponse = { jsonrpc: '2.0', id, error: { code, message } }
+  if (data !== undefined) err.error.data = data
+  return err
+}
+
+/** Type-guard: does a parsed object look like an Envelope? */
+export function isEnvelope(value: unknown): value is Envelope {
+  if (value === null || typeof value !== 'object') return false
+  const v = value as { jsonrpc?: unknown }
+  return v.jsonrpc === '2.0'
+}
+
+/** Type-guard for a request envelope. */
+export function isRequest(env: Envelope): env is Request {
+  return 'method' in env && 'id' in env
+}
+
+/** Type-guard for a notification envelope (request without id). */
+export function isNotification(env: Envelope): env is Notification {
+  return 'method' in env && !('id' in env)
+}
+
+// ---------------------------------------------------------------------------
+// Bidirectional adapters between the legacy t-discriminated wire and the
+// JSON-RPC envelope. Lets vx serve accept both formats on the same WS
+// endpoint during the transition: parse one, fall back to the other.
+// ---------------------------------------------------------------------------
+
+/**
+ * Project a ServerMessage to an envelope. Events become `events.append`
+ * notifications; results become `submit.run` responses; errors become
+ * error responses. The distributed coordinator messages map to the
+ * `coord.*` namespace in a distribution plugin's own adapters.
+ */
+export function serverMessageToEnvelope(msg: ServerMessage, id?: number | string): Envelope {
+  switch (msg.t) {
+    case 'event':
+      return makeNotification('events.append', msg.event)
+    case 'result':
+      // submit.run's response. id required from the caller.
+      return makeResponse(id ?? 0, msg.result)
+    case 'error':
+      return makeError(id ?? 0, ENVELOPE_ERRORS.USER_ERROR, msg.message)
+  }
+}
+
+/**
+ * Project an envelope back to a ServerMessage where one exists. Returns
+ * null for envelopes that don't have a mapping (e.g. state.snapshot
+ * responses — pure JSON-RPC, no submitter form).
+ */
+export function envelopeToServerMessage(env: Envelope): ServerMessage | null {
+  if (isNotification(env) && env.method === 'events.append') {
+    return { t: 'event', event: env.params as InternalWireEvent }
+  }
+  if ('result' in env) {
+    return { t: 'result', result: env.result as RunResult }
+  }
+  if ('error' in env) {
+    return { t: 'error', message: env.error.message }
+  }
+  return null
+}
+
+/** Project a ClientMessage to an envelope. `run` becomes a `submit.run` request. */
+export function clientMessageToEnvelope(msg: ClientMessage, id?: number | string): Envelope {
+  return makeRequest(id ?? 1, 'submit.run', msg.request)
+}
+
+/** Project an envelope back to a ClientMessage. */
+export function envelopeToClientMessage(env: Envelope): ClientMessage | null {
+  if (isRequest(env) && env.method === 'submit.run') {
+    return { t: 'run', request: env.params as RunRequest }
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// Transport encoders — single bus, one envelope, three byte framings.
+// Helpers exposed for the Hono mounts in src/cli/serve.ts.
+// ---------------------------------------------------------------------------
+
+/** Encode an envelope for a WebSocket frame (one JSON object per frame). */
+export function encodeForWS(env: Envelope): string {
+  return JSON.stringify(env)
+}
+
+/**
+ * Encode an envelope as an SSE event block. Each block is one
+ * `data: <json>\n\n` chunk so a `curl` or browser EventSource gets it
+ * cleanly.
+ */
+export function encodeForSSE(env: Envelope): string {
+  return `data: ${JSON.stringify(env)}\n\n`
+}
+
+/** Encode an envelope as a NDJSON line. One envelope per line. */
+export function encodeForNDJSON(env: Envelope): string {
+  return JSON.stringify(env) + '\n'
+}
+
+/** Parse a UTF-8 string back to an envelope (and validate the shape). */
+export function decodeEnvelope(raw: string): Envelope {
+  const value = JSON.parse(raw) as unknown
+  if (!isEnvelope(value)) {
+    throw new Error(`not a JSON-RPC 2.0 envelope: ${raw.slice(0, 100)}`)
+  }
+  return value
+}

package/src/util/errors.ts

@@ -0,0 +1,11 @@
+// Shared error types used across modules to distinguish user-input
+// failures (clean message only) from internal bugs (full stack trace).
+//
+// `bin.ts` consults `instanceof UserError` to decide what to print.
+
+export class UserError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'UserError'
+  }
+}

package/src/util/hash.ts

@@ -0,0 +1,25 @@
+// Shared non-cryptographic hash helper. xxHash3 is ~5× faster than
+// SHA-256 on modern x86 and produces enough entropy (64 bits) for our
+// uses: cache-key derivation, file content fingerprinting, config-
+// load module cache-busting. None of those need collision resistance
+// against an adversary; they just need uniqueness across honest input.
+//
+// Hex output is a fixed 16-char string. Turbo uses the same shape
+// (xxh64 -> hex(to_be_bytes(u64))) — short enough to live in
+// filenames, recognizable when grepping logs.
+//
+// `Bun.hash.xxHash3` has no streaming Hasher API but takes a seed —
+// we use that seed to chain multiple updates: each `xxh3(part, prev)`
+// folds `part` into the running digest. Equivalent to the old
+// `CryptoHasher.update(...).update(...).digest()` pattern, without
+// allocating an intermediate buffer.
+
+/** xxHash3 bigint output. Use as the seed for the next chain step. */
+export function xxh3(input: string | Uint8Array, seed: bigint = 0n): bigint {
+  return Bun.hash.xxHash3(input, seed)
+}
+
+/** xxHash3 hex-encoded, fixed 16 chars (zero-padded). */
+export function xxh3hex(input: string | Uint8Array, seed: bigint = 0n): string {
+  return xxh3(input, seed).toString(16).padStart(16, '0')
+}

package/src/util/index.ts

@@ -0,0 +1,8 @@
+// Module contract. Cross-module imports must come through here; see
+// docs/design/module-isolation-2026-06.md and tests/module-boundaries.test.ts.
+
+export { UserError } from './errors.js'
+export { xxh3, xxh3hex } from './hash.js'
+export { relPosix } from './paths.js'
+export { parseSize } from './size.js'
+export { ulid } from './ulid.js'

package/src/util/paths.ts

@@ -0,0 +1,16 @@
+import path from 'node:path'
+
+const IS_POSIX = path.sep === '/'
+
+/** Convert a path to POSIX-style for cross-platform stable cache keys. */
+export function toPosix(p: string): string {
+  // Fast path: on Linux/macOS the separator is already '/'. This
+  // function is called for every input file on every cache-key
+  // derivation; skipping the split+join is free perf on the dominant
+  // dev platform.
+  return IS_POSIX ? p : p.split(path.sep).join('/')
+}
+
+export function relPosix(from: string, to: string): string {
+  return toPosix(path.relative(from, to))
+}

package/src/util/size.ts

@@ -0,0 +1,16 @@
+/**
+ * Parse a byte-size string: a bare integer (`"1048576"`) or an integer
+ * with a K/M/G/T suffix, powers of 1024, optional trailing `B`
+ * (`"512MB"`, `"8G"`). Returns `null` for anything else — including
+ * fractional sizes (`"1.5GB"`); callers wanting fractions must express
+ * them in a smaller unit.
+ */
+export function parseSize(input: string): number | null {
+  const m = input.match(/^(\d+)([KMGT])?B?$/i)
+  if (!m) return null
+  const n = Number(m[1])
+  const u = (m[2] ?? '').toUpperCase()
+  const mult =
+    u === '' ? 1 : u === 'K' ? 1024 : u === 'M' ? 1024 * 1024 : u === 'G' ? 1024 ** 3 : 1024 ** 4
+  return n * mult
+}

package/src/util/ulid.ts

@@ -0,0 +1,15 @@
+// Run-id generator. Thin wrapper over `Bun.randomUUIDv7()` so the
+// `runId` column on `runs` carries a timestamp-ordered identifier —
+// `vx stats --since` queries can range-scan without an index on the
+// time column, and the IDs lexicographically sort by creation time
+// for grouping.
+//
+// UUIDv7 layout: 48-bit ms-epoch timestamp + 74 bits of randomness
+// across the remaining bytes (RFC 9562). Standard format, hex with
+// hyphens, 36 chars. Previously a hand-rolled 26-char Crockford-
+// base32 ULID — Bun's built-in covers the same guarantees with zero
+// custom code.
+
+export function ulid(): string {
+  return Bun.randomUUIDv7()
+}

package/src/version.ts

@@ -0,0 +1,10 @@
+// Leaf module so orchestrator/cli can read the version without
+// importing the public façade (index.ts imports the orchestrator —
+// that edge must stay one-directional).
+//
+// Single source of truth is package.json — Bun resolves the JSON
+// import natively (and inlines it under `bun build --compile`), so
+// a release bump can never drift from what the banner prints.
+import pkg from '../package.json'
+
+export const VERSION: string = pkg.version