@vzn/vx 0.0.637 → 0.0.639

package/src/cache/plugin-cache.ts

@@ -0,0 +1,240 @@
+// A plugin's own entries in the cache the workspace declares (`ctx.cache`,
+// owner 2026-10-14): the local store first, then each remote in declared
+// order, under the run's policy and scope. The plugin speaks names; core
+// derives the key, so no plugin reaches another's entries or a task's. An
+// entry is written once and never replaced (the cache is immutable). Every
+// failure is an absent answer, never a warning (M: no extra runtime
+// warnings): what a plugin keeps here is a hint.
+
+import type { Database } from 'bun:sqlite'
+import { xxh3hex } from '../util/index.js'
+import type { CachePolicy } from './policy.js'
+import type { ResolvedRemote } from './remote-lane.js'
+import { scopedKey } from './scoped-cache.js'
+import { runReadKeys } from './run-store.js'
+
+/** The largest entry kept or read, in bytes: a remote's larger body is a miss, read no further. */
+export const PLUGIN_ENTRY_MAX_BYTES = 1024 * 1024
+
+/** What a plugin's `ctx.cache` offers. Keys are the plugin's own names. */
+export interface PluginCache {
+  /** The bytes stored under `key`, from the first layer holding them; null when none does. */
+  get(key: string): Promise<Uint8Array | null>
+  /** Store `bytes` under `key` in every layer the policy writes, where it is not already; empty bytes store nothing. */
+  put(key: string, bytes: Uint8Array): Promise<void>
+  /** Whether some layer holds `key`; null when no layer could answer. */
+  has(key: string): Promise<boolean | null>
+  /**
+   * The subset of `keys` some layer holds, in one probe per layer; null
+   * when a readable remote has no batch probe: ask `get` one at a time.
+   */
+  hasMany(keys: readonly string[]): Promise<Set<string> | null>
+  /**
+   * What core kept of a run under `name` (a `log` or `outputs` name its
+   * `RunReport` hands `teardown`), from the first readable remote holding
+   * it; null when none does. Uncapped: core wrote it.
+   */
+  getRun(name: string): Promise<Uint8Array | null>
+}
+
+export interface PluginCacheHost {
+  /** The run's index; its store holds `plugin_blobs`. */
+  readonly db: Database
+  readonly policy: CachePolicy
+  readonly remotes: readonly ResolvedRemote[]
+  readonly scope: string | undefined
+}
+
+/** The key `name` stores under for `plugin`: task-key shaped, so every wire stores it unchanged. */
+function entryKey(plugin: string, name: string): string {
+  return xxh3hex(`vx-plugin\0${plugin}\0${name}`)
+}
+
+/**
+ * A remote body's bytes; null past the cap (read no further than it) and for
+ * an empty or odd body, which kept would hide every later good one: an entry
+ * is written once (Security, #3580).
+ */
+async function capped(body: unknown, max = PLUGIN_ENTRY_MAX_BYTES): Promise<Uint8Array | null> {
+  if (body instanceof Blob) {
+    if (body.size === 0 || body.size > max) return null
+    return new Uint8Array(await body.arrayBuffer())
+  }
+  if (!(body instanceof Response) || body.body === null) return null
+  const reader = body.body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.byteLength
+    if (size > max) {
+      await reader.cancel().catch(() => {})
+      return null
+    }
+    chunks.push(value)
+  }
+  if (size === 0) return null
+  const out = new Uint8Array(size)
+  let at = 0
+  for (const c of chunks) {
+    out.set(c, at)
+    at += c.byteLength
+  }
+  return out
+}
+
+/**
+ * `plugin`'s view of the cache. A scoped run reads the default key, then
+ * the scope's, and writes only the scope's, as tasks do (`ScopedCache`).
+ */
+export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache {
+  const { db, policy, scope } = host
+  const readers = host.remotes.filter((r) => r.read)
+  const writers = host.remotes.filter((r) => r.write)
+  const reads = (name: string): string[] => {
+    const key = entryKey(plugin, name)
+    return scope === undefined ? [key] : [key, scopedKey(scope, key)]
+  }
+  const writeKey = (name: string): string => {
+    const key = entryKey(plugin, name)
+    return scope === undefined ? key : scopedKey(scope, key)
+  }
+
+  const localGet = (key: string): Uint8Array | null => {
+    if (!policy.localRead) return null
+    try {
+      const row = db.query('SELECT bytes FROM plugin_blobs WHERE key = ?').get(key) as {
+        bytes: Uint8Array
+      } | null
+      return row === null ? null : new Uint8Array(row.bytes)
+    } catch {
+      return null
+    }
+  }
+  const localHas = (keys: readonly string[]): Set<string> => {
+    const found = new Set<string>()
+    if (!policy.localRead || keys.length === 0) return found
+    try {
+      const rows = db
+        .query(`SELECT key FROM plugin_blobs WHERE key IN (${keys.map(() => '?').join(', ')})`)
+        .all(...keys) as Array<{ key: string }>
+      for (const r of rows) found.add(r.key)
+    } catch {
+      // an unreadable index holds nothing
+    }
+    return found
+  }
+  const localPut = (key: string, bytes: Uint8Array): void => {
+    try {
+      db.query('INSERT OR IGNORE INTO plugin_blobs(key, bytes, at) VALUES (?, ?, ?)').run(
+        key,
+        bytes,
+        Date.now(),
+      )
+    } catch {
+      // a read-only or busy index keeps nothing
+    }
+  }
+
+  return {
+    async get(name) {
+      const keys = reads(name)
+      for (const key of keys) {
+        const hit = localGet(key)
+        if (hit !== null) return hit
+      }
+      for (const { remote } of readers) {
+        for (const key of keys) {
+          try {
+            const got = await remote.get(key)
+            if (got === null) continue
+            const bytes = await capped(got.body)
+            if (bytes === null) continue
+            if (policy.localWrite) localPut(key, bytes)
+            return bytes
+          } catch {
+            // a failing remote is a miss there
+          }
+        }
+      }
+      return null
+    },
+
+    async put(name, bytes) {
+      if (bytes.byteLength === 0 || bytes.byteLength > PLUGIN_ENTRY_MAX_BYTES) return
+      const key = writeKey(name)
+      if (policy.localWrite) localPut(key, bytes)
+      for (const { remote } of writers) {
+        try {
+          await remote.put(key, new Blob([bytes]), { durationMs: 0 })
+        } catch {
+          // the other layers still keep it
+        }
+      }
+    },
+
+    async has(name) {
+      const keys = reads(name)
+      if (localHas(keys).size > 0) return true
+      let answered = policy.localRead
+      for (const { remote } of readers) {
+        for (const key of keys) {
+          try {
+            if (await remote.has(key)) return true
+            answered = true
+          } catch {
+            // no answer from this remote
+          }
+        }
+      }
+      return answered ? false : null
+    },
+
+    async hasMany(names) {
+      const byKey = new Map<string, string>()
+      for (const name of names) for (const key of reads(name)) byKey.set(key, name)
+      const keys = [...byKey.keys()]
+      const found = new Set<string>()
+      for (const key of localHas(keys)) found.add(byKey.get(key)!)
+      for (const { remote } of readers) {
+        const ask = keys.filter((k) => !found.has(byKey.get(k)!))
+        if (ask.length === 0) break
+        if (remote.hasMany === undefined) return null
+        try {
+          const got: unknown = await remote.hasMany(ask)
+          if (!(got instanceof Set)) return null
+          for (const key of got) if (byKey.has(key as string)) found.add(byKey.get(key as string)!)
+        } catch {
+          return null
+        }
+      }
+      return found
+    },
+
+    async getRun(name) {
+      for (const { remote } of readers) {
+        for (const key of runReadKeys(name, scope)) {
+          try {
+            const got = await remote.get(key)
+            if (got === null) continue
+            const bytes = await capped(got.body, Infinity)
+            if (bytes !== null) return bytes
+          } catch {
+            // a failing remote is a miss there
+          }
+        }
+      }
+      return null
+    },
+  }
+}
+
+/** A cache with no layer: every answer absent. What a context built outside a run holds. */
+export const absentPluginCache: PluginCache = {
+  get: async () => null,
+  put: async () => {},
+  has: async () => null,
+  hasMany: async () => null,
+  getRun: async () => null,
+}

package/src/cache/policy.ts

@@ -90,6 +90,15 @@ export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_PO
   return out
 }
 
+/**
+ * The `--cache-policy` spec for `p`, both layers named, so the line
+ * `vx last` shows pastes back as the flag: `local:rw,remote:r`.
+ */
+export function formatCachePolicy(p: CachePolicy): string {
+  const flags = (r: boolean, w: boolean): string => `${r ? 'r' : ''}${w ? 'w' : ''}`
+  return `local:${flags(p.localRead, p.localWrite)},remote:${flags(p.remoteRead, p.remoteWrite)}`
+}
+
 /** `--no-cache` and `--force`, which still apply over whichever spec set the base. */
 export interface CacheFlags {
   /** `--no-cache`: every axis off. Beats `force`. */

package/src/cache/remote-lane.ts

@@ -0,0 +1,383 @@
+// One declared remote as `LayeredCache` reaches it: what the run lets it
+// do, the boundary its answers cross (a plugin's shape is checked, its throw
+// becomes a miss), its own upload pool, and its failures said once per
+// class with the endpoint named. The order across remotes, the local store
+// and provenance are `LayeredCache`'s; nothing here knows another remote.
+
+import type { RemoteKeyTraffic, RemoteTraffic } from './cache.js'
+import type { RemoteCacheLayer } from './layered-cache.js'
+
+/** One remote, resolved: its wire and what the run's policy and its `access` let it do. */
+export interface ResolvedRemote {
+  readonly remote: RemoteCacheLayer
+  readonly read: boolean
+  readonly write: boolean
+  /** Told of each failure this remote degrades to a miss; the default writes stderr. */
+  readonly onError?: (err: Error) => void
+}
+
+/**
+ * Cap on concurrent background PUTs per remote. Keeps a burst of cache
+ * misses from opening one socket per task; excess uploads queue and drain
+ * FIFO.
+ */
+const UPLOAD_CONCURRENCY = 4
+
+/** The seam call a failure happened in, as the warning names it. */
+export type RemoteOp = 'probe' | 'download' | 'upload'
+
+const PREPOSITION: Record<RemoteOp, string> = { probe: 'at', download: 'from', upload: 'to' }
+
+/**
+ * What a remote layer resolves is a plugin's, so its shape is a boundary
+ * (item 252): a `get` that resolved `{ body: 'abc' }` was reported as
+ * "corrupt artifact … not a readable archive" — the bytes blamed for the
+ * plugin's shape — and a `hasMany` that resolved an array reached the
+ * prefetch pass's `.has()`. Named here and degraded to a miss, like every
+ * other remote failure.
+ */
+function invalidRemoteResult(what: string): Error {
+  return new Error(
+    `remote cache layer returned an invalid result: ${what} — a plugin bug, degraded to a miss`,
+  )
+}
+
+function isBody(value: unknown): value is Blob | Response {
+  return value instanceof Blob || value instanceof Response
+}
+
+function describeValue(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'an array'
+  // The pre-stream contract's shape, named so an unported layer reads its fix.
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value))
+    return `a ${value.constructor.name}`
+  return typeof value === 'object' ? 'an object' : typeof value
+}
+
+/** The layer's `endpoint` as it may be printed: no userinfo, query or fragment. */
+function printableEndpoint(endpoint: unknown): string | undefined {
+  if (typeof endpoint !== 'string' || endpoint === '') return undefined
+  if (!URL.canParse(endpoint)) return endpoint
+  const u = new URL(endpoint)
+  if (u.username === '' && u.password === '' && u.search === '' && u.hash === '') return endpoint
+  u.username = ''
+  u.password = ''
+  u.search = ''
+  u.hash = ''
+  return u.toString()
+}
+
+/**
+ * What makes two failures "the same way": the error's `code` when it
+ * carries one (a gRPC status, an errno, Bun's `ConnectionRefused`), because
+ * gRPC writes the elapsed time into its message and no two deadline messages
+ * match; else the message with the artifact's hash taken out, so a 500 on
+ * one hash and a 500 on the next are one class. The operation is not part of
+ * it: an unreachable server fails the probe, the download and the upload
+ * alike, and that is one fact.
+ */
+function failureClass(err: Error, hash: string | undefined): string {
+  const code = (err as { code?: unknown }).code
+  if (typeof code === 'string' || typeof code === 'number') return `${err.name}\0${code}`
+  return hash === undefined ? err.message : err.message.replaceAll(hash, '\0')
+}
+
+/** A batch probe names no one hash, so its line counts them. */
+function batchOf(hashes: readonly string[]): { batch: string } {
+  return { batch: `of ${hashes.length} artifact${hashes.length === 1 ? '' : 's'}` }
+}
+
+export class RemoteLane {
+  readonly read: boolean
+  readonly write: boolean
+  private readonly remote: RemoteCacheLayer
+  private readonly endpoint: string | undefined
+  private readonly onError: ((err: Error) => void) | undefined
+
+  /**
+   * Hashes a batch probe found absent here, so a later fetch skips this
+   * remote without a round-trip. Same point-in-time staleness as the probe.
+   */
+  private readonly absent = new Set<string>()
+  /** What a `hasMany` said this remote holds, as `absent` records the rest. */
+  private readonly held = new Set<string>()
+
+  /**
+   * A remote the run writes but does not read (`--force`): which of the
+   * run's up-front keys it already holds, from one `hasMany`. `found` is
+   * null when the probe failed.
+   */
+  private presence: Promise<{ asked: Set<string>; found: Set<string> | null } | null> | undefined
+
+  private readonly uploadQueue: Array<() => Promise<void>> = []
+  private activeUploads = 0
+  private drainWaiters: Array<() => void> = []
+  /** Set by `stop()`: the run was stopped, so no upload starts and the drain waits on none. */
+  private stopped = false
+  private onStop: () => void = () => {}
+  private readonly stopping = new Promise<void>((resolve) => {
+    this.onStop = resolve
+  })
+
+  /**
+   * One entry per failure class said: its first line went out, `repeats`
+   * counts the ones held back. A run's requests are concurrent, so an
+   * unreachable server otherwise printed its bare runtime message once per
+   * request (three lines for one task over the Turbo wire, item 749).
+   */
+  private readonly reported = new Map<string, { cause: string; repeats: number }>()
+
+  constructor(
+    resolved: ResolvedRemote,
+    private readonly traffic: RemoteTraffic,
+  ) {
+    this.remote = resolved.remote
+    this.read = resolved.read
+    this.write = resolved.write
+    this.onError = resolved.onError
+    this.endpoint = printableEndpoint(resolved.remote.endpoint)
+  }
+
+  /**
+   * Existence probe; a failure is a miss. A key a `hasMany` this run
+   * answered for is not asked again: `--dry` batches its keys first.
+   */
+  async has(hash: string): Promise<boolean> {
+    if (this.held.has(hash)) return true
+    if (this.absent.has(hash)) return false
+    try {
+      return Boolean(await this.remote.has(hash))
+    } catch (err) {
+      this.report('probe', hash, err)
+      return false
+    }
+  }
+
+  /**
+   * The subset of `hashes` stored here in one round-trip, recording the
+   * rest as absent; `null` when this remote cannot batch or the probe
+   * failed, which the caller reads as "no batch info".
+   */
+  async hasMany(hashes: readonly string[]): Promise<Set<string> | null> {
+    if (this.remote.hasMany === undefined) return null
+    let found: unknown
+    try {
+      found = await this.remote.hasMany(hashes)
+    } catch (err) {
+      this.report('probe', batchOf(hashes), err)
+      return null
+    }
+    if (found === null || found === undefined) return null
+    if (!(found instanceof Set)) {
+      this.report(
+        'probe',
+        batchOf(hashes),
+        invalidRemoteResult(
+          `hasMany() resolved ${describeValue(found)} (expected a Set of the hashes present, or null)`,
+        ),
+      )
+      return null
+    }
+    const set = found as Set<string>
+    for (const h of hashes) (set.has(h) ? this.held : this.absent).add(h)
+    return set
+  }
+
+  /** The artifact's body, or null on a miss, a known absence, a failure or a malformed answer. */
+  async get(hash: string): Promise<{ body: Blob | Response; durationMs?: number } | null> {
+    if (this.absent.has(hash)) return null
+    let result: unknown
+    try {
+      result = await this.remote.get(hash)
+    } catch (err) {
+      this.report('download', hash, err)
+      return null
+    }
+    if (!result) return null
+    if (typeof result !== 'object' || !isBody((result as { body?: unknown }).body)) {
+      const shape =
+        typeof result !== 'object'
+          ? describeValue(result)
+          : `body is ${describeValue((result as { body?: unknown }).body)}`
+      this.report(
+        'download',
+        hash,
+        invalidRemoteResult(
+          `get() resolved ${shape} (expected { body: Blob | Response, durationMs } or null)`,
+        ),
+      )
+      return null
+    }
+    return result as { body: Blob | Response; durationMs?: number }
+  }
+
+  /**
+   * Start the batch probe `presence` reads. A lane that reads, never
+   * writes, or cannot batch (no `hasMany`) ignores it: each upload then
+   * asks `has` for its own key.
+   */
+  probeBeforeUpload(hashes: Promise<readonly string[]>): void {
+    if (this.read || !this.write || this.remote.hasMany === undefined) return
+    this.presence = hashes.then(
+      async (asked) =>
+        asked.length === 0 ? null : { asked: new Set(asked), found: await this.hasMany(asked) },
+      () => null,
+    )
+  }
+
+  /**
+   * Whether this remote already holds `hash`, asked only by a lane the run
+   * does not read: an entry is immutable, so a key it holds is the same
+   * bytes and is not sent again. Answered from the batch probe when it
+   * covered the key, else by one `has`; a failure reads as absent, and the
+   * upload goes as before.
+   */
+  private async holds(hash: string): Promise<boolean> {
+    const probed = await this.presence
+    if (probed !== undefined && probed !== null && probed.found !== null && probed.asked.has(hash))
+      return probed.found.has(hash)
+    return this.has(hash)
+  }
+
+  /** Queue a PUT in this remote's bounded pool; `body` is asked for when the job starts. */
+  upload(
+    hash: string,
+    durationMs: number,
+    body: () => { body: Blob; release?: () => Promise<void> },
+    tally: { count: number; bytes: number; ms: number; failed: number },
+  ): void {
+    const key = this.trafficOf(hash)
+    key.uploading++
+    this.traffic.inFlight++
+    this.uploadQueue.push(async () => {
+      let release: (() => Promise<void>) | undefined
+      try {
+        if (this.stopped) return
+        if (!this.read && (await this.holds(hash))) return
+        if (this.stopped) return
+        const start = performance.now()
+        const got = body()
+        release = got.release
+        await this.remote.put(hash, got.body, { durationMs })
+        tally.count++
+        tally.bytes += got.body.size
+        tally.ms += Math.round(performance.now() - start)
+        key.landed = true
+      } catch (err) {
+        tally.failed++
+        this.report('upload', hash, err)
+      } finally {
+        await release?.()
+        key.uploading--
+        this.traffic.inFlight--
+        // Nothing sent and nothing failed (the remote held it, or the run
+        // stopped first): no traffic, so the footer counts no upload.
+        if (key.uploading === 0 && !key.landed && key.failures.length === 0)
+          this.traffic.keys.delete(hash)
+      }
+    })
+    this.pump()
+  }
+
+  /** Resolves once every queued and in-flight upload has settled, or the run was stopped. */
+  async drain(): Promise<void> {
+    // A probe no upload waited on still runs: settled before the run tears
+    // the plugin down.
+    await Promise.race([this.presence, this.stopping])
+    if (this.stopped || (this.activeUploads === 0 && this.uploadQueue.length === 0)) return
+    await new Promise<void>((resolve) => this.drainWaiters.push(resolve))
+  }
+
+  /**
+   * The run was stopped (Ctrl-C, SIGTERM, an embedder's abort): queued
+   * uploads never start and the drain stops waiting on the ones in flight,
+   * which a plugin cannot be asked to cancel. A slow remote held a stopped
+   * run past the signal's exit bound, which then exited with no footer.
+   */
+  stop(): void {
+    this.stopped = true
+    this.onStop()
+    for (const resolve of this.drainWaiters.splice(0)) resolve()
+  }
+
+  /** Say the held-back repeats; the run drained first, so the counts are final. */
+  close(): void {
+    for (const { cause, repeats } of this.reported.values()) {
+      if (repeats === 0) continue
+      this.emit(
+        new Error(
+          `${repeats} more request${repeats === 1 ? '' : 's'} failed the same way: ${cause}`,
+        ),
+      )
+    }
+    this.reported.clear()
+  }
+
+  /**
+   * `subject` is the artifact's hash, or the batch for a `hasMany`. The
+   * wire's own message says what went wrong but not on what or where: an
+   * upload deadline read `The operation timed out.` with no upload, hash or
+   * server in it (item 749).
+   */
+  report(op: RemoteOp, subject: string | { batch: string }, err: unknown): void {
+    const e = err instanceof Error ? err : new Error(String(err))
+    const hash = typeof subject === 'string' ? subject : undefined
+    // A batch probe's failure is no one task's: each of its hashes is asked
+    // again on its own, and that ask is the one counted.
+    if (hash !== undefined) {
+      const failures = this.trafficOf(hash).failures
+      const said = `${op}: ${e.message}`
+      if (!failures.includes(said)) failures.push(said)
+    }
+    const cls = failureClass(e, hash)
+    const seen = this.reported.get(cls)
+    if (seen !== undefined) {
+      seen.repeats++
+      return
+    }
+    this.reported.set(cls, { cause: e.message, repeats: 0 })
+    const what = typeof subject === 'string' ? subject : subject.batch
+    const where = this.endpoint === undefined ? '' : ` ${PREPOSITION[op]} ${this.endpoint}`
+    this.emit(new Error(`${op} ${what}${where} failed: ${e.message}`, { cause: e }))
+  }
+
+  private trafficOf(hash: string): RemoteKeyTraffic {
+    let key = this.traffic.keys.get(hash)
+    if (key === undefined) {
+      key = { uploading: 0, landed: false, failures: [] }
+      this.traffic.keys.set(hash, key)
+    }
+    return key
+  }
+
+  private pump(): void {
+    while (this.activeUploads < UPLOAD_CONCURRENCY && this.uploadQueue.length > 0) {
+      const job = this.uploadQueue.shift()!
+      this.activeUploads++
+      // Jobs never reject (each wraps its PUT in the never-fail guard).
+      void job().finally(() => {
+        this.activeUploads--
+        this.pump()
+      })
+    }
+    if (this.activeUploads === 0 && this.uploadQueue.length === 0 && this.drainWaiters.length > 0) {
+      const waiters = this.drainWaiters
+      this.drainWaiters = []
+      for (const w of waiters) w()
+    }
+  }
+
+  private emit(e: Error): void {
+    // The remote cache is fully optional: NO remote failure — a 500, a
+    // network drop, a corrupt artifact, even a throwing reporter — may
+    // ever fail the run. A buggy reporter can't turn an optional-cache
+    // hiccup into a run failure.
+    try {
+      if (this.onError) this.onError(e)
+      else process.stderr.write(`[vx] remote cache: ${e.message}\n`)
+    } catch {
+      // swallow — reporting must never escalate
+    }
+  }
+}