@vzn/vx 0.0.637 → 0.0.639

package/schemas/summary.json

@@ -1,133 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "vx run --summarize",
-  "description": "Every task's outcome in one run: <cacheDir>/runs/<runId>.json, or the --summarize=<path> file.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "runId",
-    "ok",
-    "exitCode",
-    "startedAt",
-    "endedAt",
-    "totalMs",
-    "savedMs",
-    "tasks",
-    "aborted",
-    "summary"
-  ],
-  "properties": {
-    "runId": { "type": "string" },
-    "ok": { "type": "boolean", "description": "the run's verdict: exitCode is 0" },
-    "exitCode": { "type": "integer" },
-    "startedAt": { "type": "string", "description": "ISO 8601" },
-    "endedAt": { "type": "string", "description": "ISO 8601" },
-    "totalMs": { "type": "number" },
-    "savedMs": {
-      "type": "number",
-      "description": "what the cache hits skipped: the sum of their storedDurationMs"
-    },
-    "tasks": {
-      "type": "array",
-      "description": "every counted task: not a group, not aborted",
-      "items": { "$ref": "#/$defs/task" }
-    },
-    "aborted": {
-      "type": "array",
-      "description": "tasks a shutdown signal killed; in no bucket and no total",
-      "items": { "$ref": "#/$defs/task" }
-    },
-    "summary": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "successful",
-        "failed",
-        "skipped",
-        "cachedLocal",
-        "restoredLocal",
-        "restoredRemote",
-        "upToDate",
-        "cachedRemote",
-        "aborted",
-        "total"
-      ],
-      "properties": {
-        "successful": { "type": "integer" },
-        "failed": { "type": "integer" },
-        "skipped": { "type": "integer" },
-        "cachedLocal": { "type": "integer" },
-        "restoredLocal": { "type": "integer" },
-        "restoredRemote": { "type": "integer" },
-        "upToDate": { "type": "integer" },
-        "cachedRemote": { "type": "integer" },
-        "aborted": { "type": "integer" },
-        "total": { "type": "integer" }
-      }
-    }
-  },
-  "$defs": {
-    "task": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["id", "project", "task", "status", "exitCode", "durationMs", "hash"],
-      "properties": {
-        "id": { "type": "string" },
-        "project": { "type": "string" },
-        "task": { "type": "string" },
-        "status": {
-          "enum": ["success", "cache-hit", "cache-hit-remote", "failed", "skipped", "aborted"]
-        },
-        "exitCode": { "type": "integer" },
-        "durationMs": { "type": "number" },
-        "hash": { "type": ["string", "null"] },
-        "restored": {
-          "type": "boolean",
-          "description": "on a hit only: true when outputs were restored, false when they were already up to date"
-        },
-        "noCache": {
-          "const": true,
-          "description": "the task declares no cache block: it could never hit"
-        },
-        "flaky": {
-          "type": "object",
-          "description": "this key both passed and failed on record, or the task needed a retry",
-          "additionalProperties": false,
-          "required": ["passes", "failures", "attempts"],
-          "properties": {
-            "passes": { "type": "integer" },
-            "failures": { "type": "integer" },
-            "attempts": { "type": "integer" }
-          }
-        },
-        "cpuMs": { "type": "number" },
-        "peakRssBytes": { "type": "integer" },
-        "storedDurationMs": {
-          "type": "number",
-          "description": "a hit: how long the producing execution ran, what the hit skipped"
-        },
-        "storedCpuMs": {
-          "type": "number",
-          "description": "a hit: what the producing execution used"
-        },
-        "storedPeakRssBytes": { "type": "integer" },
-        "admissionHeldMs": {
-          "type": "number",
-          "description": "an admit policy held it with a worker free"
-        },
-        "blockedBy": {
-          "type": "string",
-          "description": "a skipped task: the failed task at the root of what blocked it"
-        },
-        "timedOut": { "const": true },
-        "sandboxViolations": { "type": "integer" },
-        "notReady": { "enum": ["timeout", "exited", "spawn"] },
-        "wallclockStartNs": {
-          "type": "string",
-          "description": "decimal nanoseconds from the run's start"
-        },
-        "wallclockEndNs": { "type": "string" }
-      }
-    }
-  }
-}

package/src/cache/chained-cache.ts

@@ -1,276 +0,0 @@
-// Several declared cache layers, consulted in declaration order. Lookup
-// walks the layers until one answers; a save reaches every layer; the FIRST
-// layer owns the run index (history, stats, prune) so a run is recorded
-// once. Restore goes to the layer that produced the hit — remembered per
-// hash — because an entry's artifact lives wherever it was found.
-//
-// A layer that throws in a lookup (a batch row load or a has-many included)
-// is a miss there and the walk goes on; a throwing drain is passed; one
-// that throws in a save is skipped and the rest still save. Unisolated, a
-// plugin layer's throw ended the walk before the local floor under it: its
-// `get` failed the task, its `save` kept the entry from every later layer
-// (item 1020). A save that fails in EVERY layer still throws, so the
-// caller's own "cache save failed" line stays the one word on it.
-
-import { statSync } from 'node:fs'
-import type {
-  Cache,
-  CacheEntry,
-  CacheGetContext,
-  CacheKeyInput,
-  CacheLayer,
-  CacheStats,
-  CacheStatsOptions,
-  IngestMeta,
-  InvocationRecord,
-  OutputDirRow,
-  OutputFileRow,
-  PruneOptions,
-  PruneResult,
-  RunRecord,
-} from './cache.js'
-
-/** Told of a layer's failure the chain went past: its index, the method, the error. */
-export type LayerErrorReport = (layer: number, method: string, err: unknown) => void
-
-export class ChainedCache implements CacheLayer {
-  readonly hasRemote: boolean
-  private readonly hitLayer = new Map<string, CacheLayer>()
-
-  constructor(
-    readonly layers: readonly CacheLayer[],
-    private readonly onLayerError: LayerErrorReport = () => undefined,
-  ) {
-    if (layers.length < 2) throw new Error('ChainedCache needs at least two layers')
-    this.hasRemote = layers.some((l) => l.hasRemote === true)
-  }
-
-  /** `layer`'s answer, or `fallback` once its failure is reported. */
-  private async ask<T>(layer: CacheLayer, method: string, call: () => Promise<T>, fallback: T) {
-    try {
-      return await call()
-    } catch (err) {
-      this.onLayerError(this.layers.indexOf(layer), method, err)
-      return fallback
-    }
-  }
-
-  get local(): Cache | undefined {
-    return this.layers[0]!.local
-  }
-
-  private owner(hash: string): CacheLayer {
-    return this.hitLayer.get(hash) ?? this.layers[0]!
-  }
-
-  key(input: CacheKeyInput): Promise<string> {
-    return this.layers[0]!.key(input)
-  }
-
-  async get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null> {
-    // The layer that pulled this hash in a prefetch answers first. Layers
-    // may share one local store, and an earlier layer found the pulled copy
-    // there and called it a local hit: a second remote's hit was counted as
-    // saved locally, in the outcome, the summary and telemetry (item 889).
-    const owner = this.hitLayer.get(hash)
-    if (owner !== undefined) {
-      const entry = await this.ask(owner, 'get', () => owner.get(hash, ctx), null)
-      if (entry !== null) return entry
-    }
-    for (const layer of this.layers) {
-      const entry = await this.ask(layer, 'get', () => layer.get(hash, ctx), null)
-      if (entry !== null) {
-        this.hitLayer.set(hash, layer)
-        return entry
-      }
-    }
-    return null
-  }
-
-  async has(hash: string): Promise<'local' | 'remote' | null> {
-    for (const layer of this.layers) {
-      const where = await this.ask(layer, 'has', () => layer.has(hash), null)
-      if (where !== null) {
-        this.hitLayer.set(hash, layer)
-        return where
-      }
-    }
-    return null
-  }
-
-  async prefetch(hash: string, ctx?: CacheGetContext): Promise<boolean> {
-    for (const layer of this.layers) {
-      if (await this.ask(layer, 'prefetch', () => layer.prefetch(hash, ctx), false)) {
-        this.hitLayer.set(hash, layer)
-        return true
-      }
-    }
-    return false
-  }
-
-  async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
-    // The caller (remote-prefetch) treats a non-null answer as authoritative
-    // for the WHOLE chain: complement = absent, broadcast. That is sound only
-    // if EVERY remote layer answered — a partial union would poison a layer
-    // that cannot batch with another layer's negatives, and its later lazy
-    // get() would skip a real remote hit. So: each answering layer gets its
-    // OWN complement marked here (its own truth — this also spares it the
-    // per-hash GETs for hashes only a sibling holds), and the merged answer
-    // is returned only when no remote layer was left unanswered.
-    let out: Set<string> | null = null
-    let complete = true
-    for (const layer of this.layers) {
-      if (layer.hasRemote !== true) continue
-      const found = await this.ask(
-        layer,
-        'remoteHasMany',
-        // The shape check and the mark sit inside the ask: a layer that
-        // answers a non-Set or throws marking gave no answer.
-        async () => {
-          const got: unknown = (await layer.remoteHasMany?.(hashes)) ?? null
-          if (got === null) return null
-          if (!(got instanceof Set)) throw new TypeError('remoteHasMany answered a non-Set')
-          const set = got as Set<string>
-          layer.markRemoteAbsent?.(hashes.filter((h) => !set.has(h)))
-          return set
-        },
-        null,
-      )
-      if (found === null) {
-        complete = false
-        continue
-      }
-      out ??= new Set()
-      for (const h of found) out.add(h)
-    }
-    return complete ? out : null
-  }
-
-  markRemoteAbsent(hashes: Iterable<string>): void {
-    const list = [...hashes]
-    for (const layer of this.layers) layer.markRemoteAbsent?.(list)
-  }
-
-  async drainUploads(): Promise<void> {
-    await Promise.all(
-      this.layers.map((l) =>
-        this.ask(l, 'drainUploads', async () => l.drainUploads?.(), undefined),
-      ),
-    )
-  }
-
-  loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]> {
-    const out = new Map<string, OutputFileRow[]>()
-    for (const [i, layer] of this.layers.entries()) {
-      let rows: Map<string, OutputFileRow[]>
-      try {
-        rows = layer.loadOutputFilesBatch(hashes)
-      } catch (err) {
-        this.onLayerError(i, 'loadOutputFilesBatch', err)
-        continue
-      }
-      for (const [h, r] of rows) if (!out.has(h)) out.set(h, r)
-    }
-    return out
-  }
-
-  isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean> {
-    return this.layers[0]!.isOutputsCurrent(projectDir, expected)
-  }
-
-  // The directory short-circuit lives with the layer that owns the local
-  // rows — the first, like the file check.
-  recordOutputDirs(
-    hash: string,
-    projectDir: string,
-    prefixes: readonly string[],
-    holds?: (files: readonly string[]) => boolean,
-  ): Promise<void> {
-    return (
-      this.layers[0]!.recordOutputDirs?.(hash, projectDir, prefixes, holds) ?? Promise.resolve()
-    )
-  }
-  recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void {
-    this.layers[0]!.recordOutputStamps?.(hash, projectDir, workspaceRoot)
-  }
-
-  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
-    return this.layers[0]!.loadOutputDirsBatch?.(hashes) ?? new Map()
-  }
-
-  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
-    return this.layers[0]!.outputDirsCurrent?.(projectDir, rows) ?? Promise.resolve(false)
-  }
-
-  restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
-    return this.owner(hash).restoreOutputs(hash, projectDir, workspaceRoot)
-  }
-
-  async save(args: Parameters<CacheLayer['save']>[0]): Promise<void> {
-    // Layers wrapping the SAME local handle (two remote plugins over
-    // ctx.localCache) would each pack + write the identical artifact; the
-    // first write is the only one that matters, so later layers get
-    // `skipLocalWrite` and go straight to their remote upload (which reads
-    // the artifact the first layer just wrote — same handle, same path).
-    const seenLocals = new Set<NonNullable<CacheLayer['local']>>()
-    const failures: Array<[layer: number, err: unknown]> = []
-    for (const [i, layer] of this.layers.entries()) {
-      const local = layer.local
-      const skip = local !== undefined && seenLocals.has(local)
-      try {
-        await layer.save(skip ? { ...args, skipLocalWrite: true } : args)
-      } catch (err) {
-        failures.push([i, err])
-        continue
-      }
-      if (local !== undefined) seenLocals.add(local)
-    }
-    if (failures.length === this.layers.length) throw failures[0]![1]
-    for (const [i, err] of failures) this.onLayerError(i, 'save', err)
-  }
-
-  ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void> {
-    return this.layers[0]!.ingest(hash, body, meta)
-  }
-
-  recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void {
-    this.layers[0]!.recordRunBundle(bundle)
-  }
-
-  stats(opts?: CacheStatsOptions): CacheStats {
-    return this.layers[0]!.stats(opts)
-  }
-
-  hashFile(filePath: string): Promise<string> {
-    return this.layers[0]!.hashFile(filePath)
-  }
-
-  outputsPath(hash: string): string {
-    return this.owner(hash).outputsPath(hash)
-  }
-
-  /** A layer that cannot say keeps a file at `outputsPath`, or nothing. */
-  artifactSize(hash: string): number | undefined {
-    const owner = this.owner(hash)
-    return owner.artifactSize !== undefined
-      ? owner.artifactSize(hash)
-      : statSync(owner.outputsPath(hash), { throwIfNoEntry: false })?.size
-  }
-
-  prune(options: PruneOptions): Promise<PruneResult> {
-    return this.layers[0]!.prune(options)
-  }
-
-  close(): void {
-    // Every layer closes even if an earlier one throws; the first error wins.
-    let failure: unknown
-    for (const layer of this.layers) {
-      try {
-        layer.close()
-      } catch (err) {
-        failure ??= err
-      }
-    }
-    if (failure !== undefined) throw failure
-  }
-}

package/src/orchestrator/tally.ts

@@ -1,112 +0,0 @@
-// Shared outcome-tally helper. `summary.ts` (end-of-run terminal block),
-// `run-artifacts.ts` (`--summarize` JSON) and `run-report.ts`
-// (`--report=markdown`) all count the same numbers; centralising the bucket
-// rules keeps the three surfaces from disagreeing about one run.
-
-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
-  /**
-   * Killed by a shutdown signal. No work, so it joins no outcome bucket and
-   * not `total` — but it is counted, because it makes the run red: a red run
-   * whose every counted task succeeded is undiagnosable without this.
-   */
-  aborted: number
-  /** Tasks counted toward `total`. Group tasks are excluded by default. */
-  total: number
-}
-
-/**
- * The minimum an outcome must expose to be bucketed. The in-process
- * `TaskOutcome` and the serializable `OutcomeView` both satisfy it; they
- * differ only in how they carry group-ness (a live node ref vs. a projected
- * boolean), so each entry point supplies that and the RULE lives in one
- * place. Declared structurally here rather than importing `OutcomeView`,
- * which would close a module cycle (events → summary → tally).
- */
-export interface TallyItem {
-  status: TaskOutcome['status']
-  restored?: boolean
-}
-
-function emptyTally(): Tally {
-  return {
-    successful: 0,
-    failed: 0,
-    skipped: 0,
-    cachedLocal: 0,
-    restoredLocal: 0,
-    restoredRemote: 0,
-    upToDate: 0,
-    cachedRemote: 0,
-    aborted: 0,
-    total: 0,
-  }
-}
-
-/**
- * Fold ONE outcome into the tally — the single owner of the bucket rules.
- *
- * Group tasks (no `exec`) aren't real work; including them inflates the
- * per-run "N total" count in ways that mislead ("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
- *   `aborted`            → +aborted only (no bucket, no total)
- */
-function fold(t: Tally, o: TallyItem, isGroup: boolean): void {
-  if (isGroup) return
-  if (o.status === 'aborted') {
-    t.aborted++
-    return
-  }
-  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++
-}
-
-/** Walk live outcomes and return a `Tally`. */
-export function tallyOutcomes(outcomes: readonly TaskOutcome[]): Tally {
-  const t = emptyTally()
-  for (const o of outcomes) fold(t, o, isGroupTask(o.node))
-  return t
-}
-
-/**
- * The same tally over the serializable projection (`OutcomeView`), which
- * carries group-ness as a flag because it has no node back-ref. An absent
- * flag reads as "not a group" — the only outcomes without one predate the
- * field and none of them are groups.
- */
-export function tallyViews(views: readonly (TallyItem & { isGroup?: boolean })[]): Tally {
-  const t = emptyTally()
-  for (const v of views) fold(t, v, v.isGroup === true)
-  return t
-}