@vzn/vx-reapi 0.0.0 → 0.0.485

package/src/wire.ts

@@ -0,0 +1,1658 @@
+// The full gRPC surface of the Bazel Remote Execution API: Execution,
+// ActionCache, ContentAddressableStorage, Capabilities and ByteStream.
+// `@grpc/proto-loader` parses the vendored protos (28 ms) and `@grpc/grpc-js`
+// carries the calls.
+
+import * as grpc from '@grpc/grpc-js'
+import * as protoLoader from '@grpc/proto-loader'
+import path from 'node:path'
+import { canDigest, concat, digestWith, hasherFor, type DigestFunctionName } from './merkle.js'
+
+/** Bare varint bytes, for the hand-encoded RequestMetadata header. */
+function varintBytes(n: number): Uint8Array {
+  const out: number[] = []
+  let v = n
+  while (v >= 0x80) {
+    out.push((v & 0x7f) | 0x80)
+    v >>>= 7
+  }
+  out.push(v)
+  return new Uint8Array(out)
+}
+
+/**
+ * Default bytes per ByteStream message.
+ *
+ * NOT a throughput knob. Bun's `node:http2` client HANGS — it does not error —
+ * when a request carries more than one message and any single message exceeds
+ * a threshold that the PEER's flow-control behaviour decides. Go's gRPC server
+ * grows its window dynamically (a `WINDOW_UPDATE` then a `SETTINGS` raise) and
+ * Bun mishandles the tail of that sequence; a `node:http2` server, which does
+ * not do it, accepts 4 MB writes happily. See Bun #30342 / #26915, largely
+ * fixed by #31584 — which is why the ceiling ROSE from ~64 KB on 1.3.x to
+ * ~216 KB on 1.4.0 rather than the hang disappearing.
+ *
+ * The default is therefore `SAFE_CHUNK_BYTES` (65535, the RFC 7540 default
+ * initial window every peer must honour with no WINDOW_UPDATE at all), the
+ * one size with no peer-dependence. 128 KB was the default and stalled a
+ * 1 MiB write against bazel-remote in 2 of 12 fresh runs on Bun 1.4.2, each
+ * costing the call's 30 s deadline before the downgrade below retried it;
+ * 65535 stalled in none (F-20). It costs ~51% on a 32 MiB upload
+ * (390 → 590 ms on loopback), far below one expected stall. A larger
+ * `chunkBytes` stays available, with the downgrade as its net.
+ *
+ * Full probe matrix: `docs/design/plugin-executor-reapi-2026-08.md` §14.
+ */
+export const CHUNK_BYTES = 65535
+
+/**
+ * The largest message needing no `WINDOW_UPDATE` from any conformant peer, so
+ * the one size with no peer-dependence: the default, and what a larger
+ * `chunkBytes` downgrades to when a write stalls.
+ */
+export const SAFE_CHUNK_BYTES = 65535
+
+/** The oldest Bun whose http2 client survives a CHUNK_BYTES-sized message. */
+export const MIN_BUN = [1, 4, 0] as const
+
+/**
+ * Refuse to run on a Bun that would hang instead of uploading. A version this
+ * plugin cannot use is a startup error naming the fix, never a wedged run —
+ * the failure mode being guarded is a HANG, which gives a user nothing to go
+ * on.
+ */
+export function assertBunSupportsChunking(version: string = Bun.version): void {
+  const parts = version.split('.').map((p) => Number.parseInt(p, 10))
+  const [maj = 0, min = 0, patch = 0] = parts
+  const older =
+    maj < MIN_BUN[0] ||
+    (maj === MIN_BUN[0] && min < MIN_BUN[1]) ||
+    (maj === MIN_BUN[0] && min === MIN_BUN[1] && patch < MIN_BUN[2])
+  if (older) {
+    throw new Error(
+      `@vzn/vx-reapi needs Bun >= ${MIN_BUN.join('.')} (running ${version}). ` +
+        `Older Bun hangs on the chunked uploads this plugin makes — see ` +
+        `docs/design/plugin-executor-reapi-2026-08.md §14. Upgrade with \`bun upgrade\`.`,
+    )
+  }
+}
+
+export interface Digest {
+  hash: string
+  size_bytes: number
+}
+
+export interface ServerCapabilities {
+  digestFunctions: string[]
+  maxBatchBytes: number
+  acUpdateEnabled: boolean
+  /** False for a cache-only deployment (bazel-remote). Gates the executor. */
+  execEnabled: boolean
+  /** `Compressor.Value` names the server accepts on ByteStream. */
+  supportedCompressors: string[]
+  /** Compressors accepted specifically on `BatchUpdateBlobs`. */
+  supportedBatchCompressors: string[]
+  /** How the server treats absolute symlink targets. */
+  symlinkAbsolutePathStrategy: string
+  /** Experimental `SplitBlob`/`SpliceBlob` support. */
+  splitBlobSupport: boolean
+  spliceBlobSupport: boolean
+}
+
+/** REAPI `Directory` node types — the Merkle input root. */
+export interface FileNode {
+  name: string
+  digest: Digest
+  is_executable: boolean
+  node_properties?: { unixMode?: number; mtimeMs?: number }
+}
+export interface DirectoryNode {
+  name: string
+  digest: Digest
+}
+export interface SymlinkNode {
+  name: string
+  target: string
+}
+export interface Directory {
+  files: FileNode[]
+  directories: DirectoryNode[]
+  symlinks: SymlinkNode[]
+}
+
+const PROTO_ROOT = path.join(import.meta.dir, '..', 'protos')
+/**
+ * Download-integrity check: bytes that came back for `digest` must hash to
+ * it. A corrupt or poisoned remote otherwise lands wrong bytes in the local
+ * content-addressed store under a trusted name — served forever under a
+ * green hit. Hashed with the NEGOTIATED digest function via the same
+ * helper every upload uses; a function this build cannot compute falls
+ * back to the length check alone (it also could never have negotiated).
+ */
+function assertBlobIntegrity(
+  bytes: Uint8Array,
+  digest: Digest,
+  digestFunction: DigestFunctionName,
+): void {
+  assertServed(
+    bytes.length,
+    canDigest(digestFunction) ? () => digestWith(digestFunction, bytes).hash : undefined,
+    digest,
+  )
+}
+
+/**
+ * A zstd reply decoded no further than the size its digest declares, plus
+ * one byte to tell "more" from "exactly": `Bun.zstdDecompressSync` expands
+ * a frame to its end, and a 1 MiB batch entry or a ByteStream body of a
+ * few KB expanded to GiBs before the size check ran (L-3). A body that
+ * decodes past the digest is refused as it passes the bound.
+ */
+async function unzstdBounded(data: Uint8Array, digest: Digest): Promise<Uint8Array> {
+  const max = Number(digest.size_bytes)
+  const parts: Uint8Array[] = []
+  let size = 0
+  const reader = new Blob([data]).stream().pipeThrough(new DecompressionStream('zstd')).getReader()
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.byteLength
+    if (size > max) {
+      await reader.cancel()
+      throw overServed(digest)
+    }
+    parts.push(value)
+  }
+  return parts.length === 1 ? parts[0]! : new Uint8Array(Buffer.concat(parts))
+}
+
+/** More bytes than the digest declares, refused before the rest arrive. */
+const overServed = (digest: Digest): Error =>
+  new Error(
+    `@vzn/vx-reapi: blob integrity failure for ${digest.hash.slice(0, 16)}…: ` +
+      `served past its declared ${digest.size_bytes} bytes`,
+  )
+
+/**
+ * The most a zstd body of `size` decoded bytes can take on the wire: the
+ * format's own bound for incompressible input (ZSTD_COMPRESSBOUND) and a
+ * frame header's slack.
+ */
+const wireBound = (size: number): number => size + (size >> 8) + 1024
+
+/** The check itself, over a size and a hash however they were computed (whole or streamed). */
+function assertServed(size: number, hash: (() => string) | undefined, digest: Digest): void {
+  if (size !== Number(digest.size_bytes)) {
+    throw new Error(
+      `@vzn/vx-reapi: blob integrity failure for ${digest.hash.slice(0, 16)}…: ` +
+        `size ${size} != declared ${digest.size_bytes}`,
+    )
+  }
+  if (hash === undefined) return
+  const got = hash()
+  if (got !== digest.hash) {
+    throw new Error(
+      `@vzn/vx-reapi: blob integrity failure: bytes hash to ${got.slice(0, 16)}… ` +
+        `but were served for digest ${digest.hash.slice(0, 16)}…`,
+    )
+  }
+}
+
+const LOAD_OPTIONS: protoLoader.Options = {
+  includeDirs: [PROTO_ROOT],
+  keepCase: true,
+  longs: String,
+  enums: String,
+  defaults: true,
+  oneofs: true,
+}
+
+interface ServiceClients {
+  cas: grpc.Client
+  ac: grpc.Client
+  bs: grpc.Client
+  caps: grpc.Client
+  exec: grpc.Client
+  ops: grpc.Client
+}
+
+type Ctors = Record<string, new (...a: unknown[]) => grpc.Client>
+let loaded: { v2: Ctors; bs: Ctors; ops: Ctors } | undefined
+
+/** Parsed ONCE per process: proto parsing is ~28 ms and identical every time. */
+function ctors(): { v2: Ctors; bs: Ctors; ops: Ctors } {
+  if (loaded !== undefined) return loaded
+  // remote_execution.proto imports google.longrunning: its Operations
+  // service comes with the same parse.
+  const reapi = grpc.loadPackageDefinition(
+    protoLoader.loadSync('build/bazel/remote/execution/v2/remote_execution.proto', LOAD_OPTIONS),
+  ) as unknown as {
+    build: { bazel: { remote: { execution: { v2: Ctors } } } }
+    google: { longrunning: Ctors }
+  }
+  const bytestream = grpc.loadPackageDefinition(
+    protoLoader.loadSync('google/bytestream/bytestream.proto', LOAD_OPTIONS),
+  ) as unknown as { google: { bytestream: Ctors } }
+  loaded = {
+    v2: reapi.build.bazel.remote.execution.v2,
+    bs: bytestream.google.bytestream,
+    ops: reapi.google.longrunning,
+  }
+  return loaded
+}
+
+/** Per-entry encoding cost in a Batch request: a 64-char hex hash, a size,
+ *  and the nested field tags and length prefixes around them. Rounded up. */
+const BATCH_ENTRY_OVERHEAD = 128
+
+/** One batch must fit in a single gRPC message; 4 MiB is the ecosystem
+ *  default and 64 KiB leaves room for the envelope. */
+const SAFE_BATCH_BYTES = 4 * 1024 * 1024 - 64 * 1024
+
+/** Batches and streamed writes one `uploadBlobs` keeps in flight. */
+const UPLOAD_CONCURRENCY = 8
+
+/** A `Digest` in a request past its hash: size varint and field framing. */
+const FIND_MISSING_ENTRY_OVERHEAD = 16
+
+/** grpc's 4 MiB receive default is far below REAPI's real message sizes. */
+const MAX_MESSAGE_BYTES = 256 * 1024 * 1024
+
+/**
+ * The receive window the client offers, per stream and per connection.
+ * HTTP/2's default 64 KiB moves one window per round trip: a read at 30 ms
+ * round trip ran at 2 MB/s (8 MB in 3988 ms, 142 ms at 16 MiB; F-32).
+ */
+const FLOW_CONTROL_WINDOW = 16 * 1024 * 1024
+
+/**
+ * All six service stubs share ONE channel. Constructing them independently
+ * opens one HTTP/2 connection per service to the same endpoint — six times
+ * the sockets, six times the flow-control state, and a server that sees six
+ * clients where there is one. `channelOverride` is grpc-js's supported way to
+ * bind extra stubs onto an existing channel.
+ */
+function loadServices(target: string, creds: grpc.ChannelCredentials): ServiceClients {
+  const { v2, bs, ops } = ctors()
+  // An ActionResult listing a real dependency tree is megabytes, and the
+  // default limit rejects it with RESOURCE_EXHAUSTED — measured at 4 359 595
+  // bytes against the 4 194 304 default. Applied to EVERY stub: the limit is
+  // per-client, so sharing one channel does not share it.
+  const opts = {
+    'grpc.max_receive_message_length': MAX_MESSAGE_BYTES,
+    'grpc.max_send_message_length': MAX_MESSAGE_BYTES,
+    'grpc-node.flow_control_window': FLOW_CONTROL_WINDOW,
+  }
+  const cas = new v2['ContentAddressableStorage']!(target, creds, opts)
+  const shared = { ...opts, channelOverride: cas.getChannel() }
+  return {
+    cas,
+    ac: new v2['ActionCache']!(target, creds, shared),
+    caps: new v2['Capabilities']!(target, creds, shared),
+    exec: new v2['Execution']!(target, creds, shared),
+    bs: new bs['ByteStream']!(target, creds, shared),
+    ops: new ops['Operations']!(target, creds, shared),
+  }
+}
+
+/** Transient statuses a retry can heal: UNAVAILABLE, RESOURCE_EXHAUSTED when
+ *  the server is shedding load, and INTERNAL, which is how grpc-js spells a
+ *  call cut in transit — an RST_STREAM(INTERNAL_ERROR), the frame a proxy
+ *  sends when the backend behind it goes away, and a stream that ended with
+ *  no gRPC status at all. Bazel's remote executor retries all three.
+ *  NOT_FOUND/INVALID_ARGUMENT never heal. */
+function isRetryable(code: number | undefined): boolean {
+  return (
+    code === grpc.status.UNAVAILABLE ||
+    code === grpc.status.RESOURCE_EXHAUSTED ||
+    code === grpc.status.INTERNAL
+  )
+}
+
+const RETRY_DELAYS_MS = [100, 400, 1600]
+
+const deadlineOf = (bounds: grpc.CallOptions): number => (bounds.deadline as Date).getTime()
+
+const executionAborted = (): Error => new Error('reapi: execution aborted')
+
+/** A backoff an abort ends at once: the caller's deadline may fire mid-wait. */
+function abortableSleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      reject(executionAborted())
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+const NOT_FOUND = grpc.status.NOT_FOUND
+
+export interface ReapiOptions {
+  /** `host:port` of the REAPI server. */
+  endpoint: string
+  /** Multi-tenant servers scope by instance; most single-tenant ones use ''. */
+  instanceName?: string
+  /** Sent on every call (auth, routing). */
+  headers?: Record<string, string>
+  /** TLS. Default: on with any PEM below or an `https://`/`grpcs://` endpoint, else insecure. */
+  tls?: boolean
+  /** PEM of the CA that signed the server's certificate, in place of the system roots. */
+  tlsCaPem?: string
+  /** PEM of a client certificate and its key, for a server that asks for mutual TLS. */
+  tlsClientCertPem?: string
+  tlsClientKeyPem?: string
+  /** Reported in REAPI `RequestMetadata.tool_details`. */
+  toolName?: string
+  toolVersion?: string
+  /** Groups several vx runs as one logical build in a server's UI. */
+  correlatedInvocationsId?: string
+  /** Surfaced for degraded-but-recovered operations (e.g. a chunk-size downgrade). */
+  onWarn?: (message: string) => void
+  /**
+   * Deadline for every CACHE-PATH call (unary RPCs, ByteStream transfers).
+   * Default 30 000 ms. This is what turns a WEDGED server — accepts TCP,
+   * never answers — into an error the layer above can degrade to a MISS;
+   * without it the first probe hangs the whole run. Execution streams are
+   * NOT bounded by this (queueing behind a busy worker pool is legitimate
+   * and unbounded); a wedged server still cannot reach Execute, because the
+   * deadline-bounded Capabilities call runs first and fails.
+   */
+  callTimeoutMs?: number
+  /**
+   * Deadline for CONTROL-PLANE calls — Capabilities, GetActionResult,
+   * UpdateActionResult, FindMissingBlobs, QueryWriteStatus. Defaults to
+   * `min(callTimeoutMs, 15 000)`.
+   *
+   * Separate from `callTimeoutMs` because the two classes have nothing in
+   * common but a transport. A control-plane message is small and bounded — a
+   * healthy server answers in single-digit milliseconds — while a bulk
+   * transfer is size-proportional and legitimately slow: capturing a
+   * `node_modules` tree is the case that pushes real deployments to raise
+   * `callTimeoutMs` into the minutes. With one knob for both, buying enough
+   * headroom for the upload also means every metadata probe against a WEDGED
+   * server costs those same minutes before it can degrade to a miss, which is
+   * the opposite of what the deadline exists for. Measured against a
+   * NativeLink that had degraded into serving every AC hit never: misses
+   * answered in 3 ms while every hit burned the full deadline.
+   */
+  metaTimeoutMs?: number
+  /**
+   * Bytes per ByteStream message. Defaults to `CHUNK_BYTES` (65535, the size
+   * with no peer-dependence); a larger value risks the stall described on
+   * `CHUNK_BYTES`, retried once at `SAFE_CHUNK_BYTES`.
+   */
+  chunkBytes?: number
+}
+
+/** The ceiling a derived control-plane deadline never exceeds, however far
+ *  `callTimeoutMs` is raised for a bulk transfer. */
+export const META_TIMEOUT_CAP_MS = 15_000
+
+/**
+ * `body` from `from` as ByteStream messages of `chunkBytes`. A `Blob` is read
+ * from its stream as the caller asks, re-cut to the message size: a file
+ * stream's pieces are its own (256 KiB and up), not the wire's.
+ */
+async function* messagesOf(
+  body: Uint8Array | Blob,
+  from: number,
+  chunkBytes: number,
+): AsyncGenerator<Uint8Array> {
+  if (body instanceof Uint8Array) {
+    for (let at = from; at < body.length; at += chunkBytes) {
+      yield body.subarray(at, Math.min(at + chunkBytes, body.length))
+    }
+    return
+  }
+  let carry: Uint8Array = new Uint8Array(0)
+  let skip = from
+  for await (const whole of body.stream()) {
+    // A resumed write starts past what the server committed.
+    const piece = skip === 0 ? whole : whole.subarray(Math.min(skip, whole.length))
+    skip -= whole.length - piece.length
+    if (piece.length === 0) continue
+    const data = carry.length === 0 ? piece : concat([carry, piece])
+    let at = 0
+    for (; data.length - at >= chunkBytes; at += chunkBytes)
+      yield data.subarray(at, at + chunkBytes)
+    carry = data.slice(at)
+  }
+  if (carry.length > 0) yield carry
+}
+
+export class ReapiClient {
+  private readonly svc: ServiceClients
+  private readonly instance: string
+  private readonly headers: Record<string, string>
+  private readonly chunkBytes: number
+  private readonly callTimeoutMs: number
+  /** What `negotiate()` learned the server will accept in one Batch call.
+   *  Used whenever a caller does not pass a budget, so a call site cannot
+   *  silently fall back to a larger default than the server allows. */
+  private negotiatedBatchBytes = 0
+  /** The control-plane deadline in force: `metaTimeoutMs` as given, else
+   *  `min(callTimeoutMs, META_TIMEOUT_CAP_MS)`. Readable so the derivation is
+   *  pinned on the instance, not waited out on the wire. */
+  readonly metaTimeoutMs: number
+  private readonly onWarn: (message: string) => void
+  private digestFunction: DigestFunctionName = 'SHA256'
+  private compression = false
+  private batchCompression = false
+  private negotiated: ServerCapabilities | undefined
+  private readonly toolName: string
+  private readonly toolVersion: string
+  private readonly correlatedInvocationsId: string
+  /** Set when a call spent its retries on UNAVAILABLE; cleared by any answer. */
+  private unreachable = false
+  /** Set per action so the server can group its RPCs under one action. */
+  actionId = ''
+  toolInvocationId = ''
+
+  constructor(opts: ReapiOptions) {
+    assertBunSupportsChunking()
+    const pem = (text: string | undefined): Buffer | null =>
+      text === undefined ? null : Buffer.from(text)
+    const tls =
+      opts.tls ??
+      (opts.tlsCaPem !== undefined ||
+        opts.tlsClientCertPem !== undefined ||
+        /^(https|grpcs):\/\//.test(opts.endpoint))
+    const target = opts.endpoint.replace(/^(https?|grpcs?):\/\//, '')
+    this.svc = loadServices(
+      target,
+      tls
+        ? grpc.credentials.createSsl(
+            pem(opts.tlsCaPem),
+            pem(opts.tlsClientKeyPem),
+            pem(opts.tlsClientCertPem),
+          )
+        : grpc.credentials.createInsecure(),
+    )
+    this.instance = opts.instanceName ?? ''
+    this.headers = opts.headers ?? {}
+    // grpc-js refuses a metadata value outside printable ASCII on EVERY call
+    // and quotes it in the error, so an auth header's secret reached each
+    // degrade warning (item 928). Refused once, here, by key alone.
+    for (const [k, v] of Object.entries(this.headers)) {
+      if (!/^[ -~]*$/.test(v)) {
+        throw new Error(
+          `reapi: header ${JSON.stringify(k)} holds a character gRPC metadata cannot carry (printable ASCII only) — check it (its value is not printed)`,
+        )
+      }
+    }
+    this.toolName = opts.toolName ?? 'vx'
+    this.toolVersion = opts.toolVersion ?? '0.0.0'
+    this.correlatedInvocationsId = opts.correlatedInvocationsId ?? ''
+    this.chunkBytes = opts.chunkBytes ?? CHUNK_BYTES
+    this.callTimeoutMs = opts.callTimeoutMs ?? 30_000
+    // Derived, not required: raising `callTimeoutMs` for a big upload must
+    // not silently lengthen every metadata probe too.
+    this.metaTimeoutMs = opts.metaTimeoutMs ?? Math.min(this.callTimeoutMs, META_TIMEOUT_CAP_MS)
+    this.onWarn = opts.onWarn ?? (() => undefined)
+    // A zero, negative or non-number deadline ended every call as it began.
+    for (const [name, ms] of [
+      ['callTimeoutMs', this.callTimeoutMs],
+      ['metaTimeoutMs', this.metaTimeoutMs],
+    ] as const) {
+      if (!(typeof ms === 'number' && Number.isFinite(ms) && ms > 0)) {
+        throw new Error(
+          `@vzn/vx-reapi: ${name} must be a positive number of ms (got ${JSON.stringify(ms)})`,
+        )
+      }
+    }
+    if (!Number.isInteger(this.chunkBytes) || this.chunkBytes < 1) {
+      throw new Error(
+        `@vzn/vx-reapi: chunkBytes must be a positive integer (got ${this.chunkBytes})`,
+      )
+    }
+  }
+
+  /**
+   * The wait before retry `attempt` of a cache-path call that failed with
+   * `code`, or undefined to give up. A call that spends its retries on
+   * UNAVAILABLE marks the server unreachable, and until a call succeeds the
+   * next ones give up at their first UNAVAILABLE, until a call succeeds or
+   * the server answers with a status of its own: a refused port cost every
+   * request 2.1 s of backoff, and a five-task run 24 s (J-74).
+   */
+  private retryDelay(attempt: number, code: number | undefined): number | undefined {
+    const unavailable = code === grpc.status.UNAVAILABLE
+    // A status the server sent (NOT_FOUND is a miss) proves it answers.
+    if (!unavailable && code !== grpc.status.DEADLINE_EXCEEDED && code !== grpc.status.CANCELLED) {
+      this.unreachable = false
+    }
+    if (!isRetryable(code)) return undefined
+    if (unavailable && this.unreachable) return undefined
+    const delay = RETRY_DELAYS_MS[attempt]
+    if (delay === undefined && unavailable) this.unreachable = true
+    return delay
+  }
+
+  /**
+   * Promisified unary call with bounded retry on transient failure. Every
+   * unary REAPI call is idempotent by construction (CAS writes are
+   * content-addressed, AC updates are last-writer-wins on an immutable key),
+   * so retrying cannot double-apply anything.
+   */
+  private async unary<T>(
+    client: grpc.Client,
+    method: string,
+    req: unknown,
+    meta: grpc.Metadata,
+    options: grpc.CallOptions = {},
+  ): Promise<T> {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const res = await new Promise<T>((resolve, reject) => {
+          ;(client as unknown as Record<string, Function>)[method]!(
+            req,
+            meta,
+            options,
+            (err: grpc.ServiceError | null, res: T) => (err ? reject(err) : resolve(res)),
+          )
+        })
+        this.unreachable = false
+        return res
+      } catch (err) {
+        const delay = this.retryDelay(attempt, (err as grpc.ServiceError).code)
+        if (delay === undefined) throw err
+        await Bun.sleep(delay)
+      }
+    }
+  }
+
+  /** Call options for a BULK transfer — deadline scales with payload size. */
+  private bounded(): grpc.CallOptions {
+    return { deadline: new Date(Date.now() + this.callTimeoutMs) }
+  }
+
+  /** Call options for a CONTROL-PLANE call — small message, short deadline. */
+  private boundedMeta(): grpc.CallOptions {
+    return { deadline: new Date(Date.now() + this.metaTimeoutMs) }
+  }
+
+  /**
+   * Per-call metadata. Beyond the user's headers this carries REAPI's
+   * `RequestMetadata` in the well-known binary header, which is how a server
+   * groups the dozens of CAS/AC calls an action makes into one build in its
+   * UI. Omitting it is legal and makes vx invisible in every REAPI server's
+   * dashboard, which is the whole reason the field exists.
+   */
+  private meta(): grpc.Metadata {
+    const m = new grpc.Metadata()
+    for (const [k, v] of Object.entries(this.headers)) m.set(k, v)
+    m.set(
+      'build.bazel.remote.execution.v2.requestmetadata-bin',
+      Buffer.from(this.requestMetadata()),
+    )
+    return m
+  }
+
+  /**
+   * `RequestMetadata { tool_details = 1, action_id = 2, tool_invocation_id = 3,
+   *                    correlated_invocations_id = 4, action_mnemonic = 6 }`
+   * with `ToolDetails { tool_name = 1, tool_version = 2 }`.
+   */
+  private requestMetadata(): Uint8Array {
+    const str = (field: number, v: string): Uint8Array => {
+      if (v === '') return new Uint8Array()
+      const bytes = new TextEncoder().encode(v)
+      return concat([varintBytes((field << 3) | 2), varintBytes(bytes.length), bytes])
+    }
+    const tool = concat([str(1, this.toolName), str(2, this.toolVersion)])
+    const toolField =
+      tool.length === 0
+        ? new Uint8Array()
+        : concat([varintBytes((1 << 3) | 2), varintBytes(tool.length), tool])
+    return concat([
+      toolField,
+      str(2, this.actionId),
+      str(3, this.toolInvocationId),
+      str(4, this.correlatedInvocationsId),
+    ])
+  }
+
+  /**
+   * `GetCapabilities`. `execEnabled` is what decides whether this server can
+   * take an `executor` at all — a cache-only deployment (bazel-remote)
+   * advertises no execution capability, and offering it work would hang a run
+   * on a server that will never answer.
+   */
+  async capabilities(): Promise<ServerCapabilities> {
+    const res = await this.unary<{
+      cache_capabilities?: {
+        digest_functions?: string[]
+        max_batch_total_size_bytes?: string
+        action_cache_update_capabilities?: { update_enabled?: boolean }
+        supported_compressors?: string[]
+        supported_batch_update_compressors?: string[]
+        symlink_absolute_path_strategy?: string
+        split_blob_support?: boolean
+        splice_blob_support?: boolean
+      }
+      execution_capabilities?: { exec_enabled?: boolean; digest_function?: string }
+    }>(
+      this.svc.caps,
+      'getCapabilities',
+      { instance_name: this.instance },
+      this.meta(),
+      this.boundedMeta(),
+    )
+    const cc = res.cache_capabilities
+    return {
+      digestFunctions: cc?.digest_functions ?? [],
+      // CLAMPED, not trusted. `max_batch_total_size_bytes` is what the
+      // server's CAS logic will accept in one Batch call; it says nothing
+      // about what its gRPC layer will carry, and grpc's default caps a
+      // single message at 4 MiB. Buildbarn advertises its configured message
+      // size here, so a generous config produced batches it then refused —
+      // `batchUpdateBlobs` rejected at 4 356 859 vs 4 194 304. Anything
+      // larger than the safe bound goes by ByteStream anyway, which chunks.
+      maxBatchBytes: this.rememberBatchBytes(Number(cc?.max_batch_total_size_bytes ?? 0)),
+      acUpdateEnabled: cc?.action_cache_update_capabilities?.update_enabled === true,
+      execEnabled: res.execution_capabilities?.exec_enabled === true,
+      supportedCompressors: cc?.supported_compressors ?? [],
+      supportedBatchCompressors: cc?.supported_batch_update_compressors ?? [],
+      symlinkAbsolutePathStrategy: cc?.symlink_absolute_path_strategy ?? 'UNKNOWN',
+      splitBlobSupport: cc?.split_blob_support === true,
+      spliceBlobSupport: cc?.splice_blob_support === true,
+    }
+  }
+
+  /**
+   * Negotiate once against the server's advertised capabilities: the digest
+   * function to hash with, and whether blobs may ride compressed. Mixing
+   * digest functions within an action is invalid, so this is a per-client
+   * decision, not a per-call one.
+   */
+  async negotiate(prefer?: {
+    digestFunction?: DigestFunctionName
+    compression?: boolean
+  }): Promise<void> {
+    const caps = await this.capabilities()
+    const wanted = prefer?.digestFunction
+    if (wanted !== undefined) {
+      if (!caps.digestFunctions.includes(wanted)) {
+        throw new Error(
+          `@vzn/vx-reapi: server does not support digest function ${wanted} (has ${caps.digestFunctions.join(', ')})`,
+        )
+      }
+      if (!canDigest(wanted))
+        throw new Error(`@vzn/vx-reapi: this runtime cannot compute ${wanted}`)
+      this.digestFunction = wanted
+    } else {
+      // Default stays SHA256 even when the server advertises stronger
+      // functions: the Merkle/action encoders digest with the SAME function
+      // as every blob upload, and auto-upgrading here while a caller still
+      // hashes trees with sha256 would mix functions inside one action —
+      // which servers reject at best and mis-address at worst. Opting into
+      // another function is `negotiate({ digestFunction: 'SHA512' })`, a
+      // caller-level decision made where the tree hashing can follow it.
+      this.digestFunction = 'SHA256'
+    }
+    this.compression =
+      prefer?.compression !== false &&
+      caps.supportedCompressors.includes('ZSTD') &&
+      typeof Bun.zstdCompressSync === 'function'
+    this.batchCompression = this.compression && caps.supportedBatchCompressors.includes('ZSTD')
+    this.negotiated = caps
+  }
+
+  /** The negotiated digest function; SHA256 until `negotiate()` says otherwise. */
+  get digest(): DigestFunctionName {
+    return this.digestFunction
+  }
+
+  /** Whether ByteStream transfers will be zstd-compressed. */
+  get compressionEnabled(): boolean {
+    return this.compression
+  }
+
+  /** Digest a payload under the negotiated function. */
+  digestOf(data: Uint8Array): Digest {
+    return digestWith(this.digestFunction, data)
+  }
+
+  /**
+   * `QueryWriteStatus` — how much of a resource the server already holds, so
+   * an interrupted upload resumes instead of restarting. Returns null when the
+   * server has no record of it (a fresh upload).
+   */
+  async queryWriteStatus(
+    resourceName: string,
+  ): Promise<{ committedSize: number; complete: boolean } | null> {
+    try {
+      const res = await this.unary<{ committed_size?: string; complete?: boolean }>(
+        this.svc.bs,
+        'queryWriteStatus',
+        { resource_name: resourceName },
+        this.meta(),
+        this.boundedMeta(),
+      )
+      return { committedSize: Number(res.committed_size ?? 0), complete: res.complete === true }
+    } catch (err) {
+      if ((err as grpc.ServiceError).code === NOT_FOUND) return null
+      throw err
+    }
+  }
+
+  /**
+   * Upload many small blobs in ONE round trip. The server caps the total
+   * (`max_batch_total_size_bytes`, 0 = unspecified → assume the 4 MB gRPC
+   * default), so callers must partition; `uploadBlobs` does that and falls
+   * back to ByteStream for anything too large on its own.
+   */
+  async batchUpdateBlobs(
+    blobs: ReadonlyArray<{ digest: Digest; data: Uint8Array }>,
+  ): Promise<void> {
+    if (blobs.length === 0) return
+    const res = await this.unary<{
+      responses?: Array<{ digest: Digest; status?: { code?: number; message?: string } }>
+    }>(
+      this.svc.cas,
+      'batchUpdateBlobs',
+      {
+        instance_name: this.instance,
+        requests: blobs.map((b) => ({
+          digest: b.digest,
+          data: this.batchCompression ? Bun.zstdCompressSync(b.data) : b.data,
+          ...(this.batchCompression ? { compressor: 'ZSTD' } : {}),
+        })),
+        ...(this.digestFunction === 'SHA256' ? {} : { digest_function: this.digestFunction }),
+      },
+      this.meta(),
+      this.bounded(),
+    )
+    // A batch call succeeds at the RPC layer while individual blobs fail; a
+    // silently dropped input blob would surface later as an unexplained
+    // remote execution failure, so surface it here.
+    for (const r of res.responses ?? []) {
+      const code = r.status?.code ?? 0
+      if (code !== 0) {
+        throw new Error(
+          `reapi: BatchUpdateBlobs rejected ${r.digest?.hash}: code ${code} ${r.status?.message ?? ''}`,
+        )
+      }
+    }
+  }
+
+  /**
+   * Fetch many small blobs, partitioned to the server's batch budget so one
+   * call can never exceed the message cap. Missing entries are omitted. When
+   * compression was negotiated the request declares ZSTD acceptable and each
+   * response is decompressed per its OWN `compressor` field — a server is
+   * free to answer some entries compressed and others not.
+   */
+  async batchReadBlobs(
+    digests: readonly Digest[],
+    maxBatchBytes = 0,
+  ): Promise<Map<string, Uint8Array>> {
+    const out = new Map<string, Uint8Array>()
+    if (digests.length === 0) return out
+    const budget =
+      maxBatchBytes > 0
+        ? Math.min(maxBatchBytes, SAFE_BATCH_BYTES)
+        : this.negotiatedBatchBytes || SAFE_BATCH_BYTES
+    let group: Digest[] = []
+    let grouped = 0
+    const flush = async (): Promise<void> => {
+      if (group.length === 0) return
+      const res = await this.unary<{
+        responses?: Array<{
+          digest: Digest
+          data?: Uint8Array
+          compressor?: string | number
+          status?: { code?: number }
+        }>
+      }>(
+        this.svc.cas,
+        'batchReadBlobs',
+        {
+          instance_name: this.instance,
+          digests: group,
+          ...(this.compression ? { acceptable_compressors: ['ZSTD'] } : {}),
+          ...(this.digestFunction === 'SHA256' ? {} : { digest_function: this.digestFunction }),
+        },
+        this.meta(),
+        this.bounded(),
+      )
+      // Each entry is held to the digest ASKED for: the response's own
+      // digest is the server's word, and a bound read from it bounds nothing.
+      const asked = new Map(group.map((d) => [d.hash, d]))
+      for (const r of res.responses ?? []) {
+        if ((r.status?.code ?? 0) !== 0 || r.data === undefined) continue
+        const digest = asked.get(r.digest?.hash)
+        if (digest === undefined) continue
+        const zstd = r.compressor === 'ZSTD' || r.compressor === 1
+        const body = zstd ? await unzstdBounded(r.data, digest) : r.data
+        assertBlobIntegrity(body, digest, this.digestFunction)
+        out.set(digest.hash, body)
+      }
+      group = []
+      grouped = 0
+    }
+    for (const d of digests) {
+      // Same encoding charge as the upload side: the RESPONSE carries a
+      // digest and framing per blob on top of the bytes, so counting payload
+      // alone overshoots the server's ceiling — observed as
+      // `Attempted to read a total of at least 2 291 516 bytes, while a
+      // maximum of 2 097 152 bytes is permitted`.
+      const cost = d.size_bytes + BATCH_ENTRY_OVERHEAD
+      // A blob too large for ANY batch has to go by ByteStream, which chunks.
+      // The upload side always did this; the read side did not, so one large
+      // blob was put in a group of its own and the request still exceeded the
+      // ceiling no matter how the rest were grouped.
+      if (cost > budget) {
+        const bytes = await this.readBlob(d)
+        if (bytes !== null) out.set(d.hash, bytes)
+        continue
+      }
+      if (grouped + cost > budget && group.length > 0) await flush()
+      group.push(d)
+      grouped += cost
+    }
+    await flush()
+    return out
+  }
+
+  /**
+   * Upload blobs, choosing the transport per blob: batched while they fit the
+   * server's batch budget, ByteStream for the rest. Only what
+   * `FindMissingBlobs` reports absent is sent at all.
+   */
+  async uploadBlobs(
+    blobs: ReadonlyArray<{ digest: Digest; data: Uint8Array }>,
+    maxBatchBytes = 0,
+  ): Promise<void> {
+    if (blobs.length === 0) return
+    const missing = new Set(
+      (await this.findMissingBlobs(blobs.map((b) => b.digest))).map((d) => d.hash),
+    )
+    const todo = blobs.filter((b) => missing.has(b.digest.hash))
+    // 0 means the server did not say; the gRPC default max message is 4 MB and
+    // the request carries framing on top, so leave headroom rather than
+    // discovering the limit as a RESOURCE_EXHAUSTED mid-run.
+    const budget =
+      maxBatchBytes > 0
+        ? Math.min(maxBatchBytes, SAFE_BATCH_BYTES)
+        : this.negotiatedBatchBytes || SAFE_BATCH_BYTES
+    const jobs: Array<() => Promise<void>> = []
+    let batch: Array<{ digest: Digest; data: Uint8Array }> = []
+    let batched = 0
+    for (const b of todo) {
+      // Charge the ENCODING, not just the payload. Each entry also carries a
+      // 64-character hash, a size, and several layers of field tags and
+      // length prefixes; summing raw sizes alone under-counts by ~100 bytes
+      // per blob, which for a few thousand small files is hundreds of
+      // kilobytes — enough to push a batch that "fits" over the wire limit
+      // and have the server refuse it (observed: 4 356 859 sent against a
+      // 4 194 304 ceiling).
+      const cost = b.digest.size_bytes + BATCH_ENTRY_OVERHEAD
+      if (cost > budget) {
+        jobs.push(() => this.writeBlob(b.digest, b.data))
+        continue
+      }
+      if (batched + cost > budget) {
+        const full = batch
+        jobs.push(() => this.batchUpdateBlobs(full))
+        batch = []
+        batched = 0
+      }
+      batch.push(b)
+      batched += cost
+    }
+    if (batch.length > 0) jobs.push(() => this.batchUpdateBlobs(batch))
+    // UPLOAD_CONCURRENCY at once, not one after another: a grpc-go server
+    // grows its receive window from what it measures arriving, and one
+    // stream at a time held four 8 MB writes to 10.2 s through 15 ms each
+    // way, 0.49 s at once (F-34). The first failure stops the queue.
+    let next = 0
+    let failed = false
+    const worker = async (): Promise<void> => {
+      while (!failed && next < jobs.length) {
+        const job = jobs[next++]!
+        await job().catch((err: unknown) => {
+          failed = true
+          throw err
+        })
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(UPLOAD_CONCURRENCY, jobs.length) }, worker))
+  }
+
+  private rememberBatchBytes(advertised: number): number {
+    this.negotiatedBatchBytes = Math.min(advertised || SAFE_BATCH_BYTES, SAFE_BATCH_BYTES)
+    return this.negotiatedBatchBytes
+  }
+
+  /** The subset of `digests` the server does NOT have — the upload-minimality primitive. */
+  async findMissingBlobs(digests: readonly Digest[]): Promise<Digest[]> {
+    if (digests.length === 0) return []
+    // One request per SAFE_BATCH_BYTES of digests: a server's receive limit
+    // (4 MiB by default) refused an input tree of 70 000 files in one
+    // message, RESOURCE_EXHAUSTED on every attempt.
+    const groups: Digest[][] = [[]]
+    let size = 0
+    for (const d of digests) {
+      const cost = d.hash.length + FIND_MISSING_ENTRY_OVERHEAD
+      if (size + cost > SAFE_BATCH_BYTES && groups.at(-1)!.length > 0) {
+        groups.push([])
+        size = 0
+      }
+      groups.at(-1)!.push(d)
+      size += cost
+    }
+    const answers = await Promise.all(
+      groups.map((group) =>
+        this.unary<{ missing_blob_digests?: Digest[] }>(
+          this.svc.cas,
+          'findMissingBlobs',
+          { instance_name: this.instance, blob_digests: group },
+          this.meta(),
+          this.boundedMeta(),
+        ),
+      ),
+    )
+    return answers.flatMap((res) => res.missing_blob_digests ?? [])
+  }
+
+  /**
+   * `GetActionResult`; `null` on NOT_FOUND — a miss is not an error.
+   * `inline` asks the server to return stdout and the named output files in
+   * the reply. The spec lets it decline (and requires it past the message
+   * limit), so a caller reads `stdout_raw` / `contents` when present and
+   * fetches otherwise.
+   */
+  async getActionResult(
+    action: Digest,
+    inline?: { stdout: boolean; files: readonly string[] },
+  ): Promise<ActionResult | null> {
+    try {
+      return await this.unary<ActionResult>(
+        this.svc.ac,
+        'getActionResult',
+        {
+          instance_name: this.instance,
+          action_digest: action,
+          ...(inline === undefined
+            ? {}
+            : { inline_stdout: inline.stdout, inline_output_files: inline.files }),
+        },
+        this.meta(),
+        this.boundedMeta(),
+      )
+    } catch (err) {
+      if ((err as grpc.ServiceError).code === NOT_FOUND) return null
+      throw err
+    }
+  }
+
+  async updateActionResult(action: Digest, result: ActionResult): Promise<void> {
+    await this.unary(
+      this.svc.ac,
+      'updateActionResult',
+      { instance_name: this.instance, action_digest: action, action_result: result },
+      this.meta(),
+      this.boundedMeta(),
+    )
+  }
+
+  /**
+   * Upload a blob via ByteStream, chunked at `chunkBytes`, RESUMING an
+   * interrupted identity upload from the server's committed offset
+   * (`QueryWriteStatus`) instead of restarting. A compressed upload restarts
+   * under a fresh resource name — compressed write offsets count compressed
+   * bytes, and mid-stream resumption of a zstd frame is not a thing a server
+   * can honour.
+   *
+   * A `Blob` past the batch limit is sent from its own stream and never held
+   * whole: a file-backed one (the vx artifact) is read from disk message by
+   * message as the channel drains. It goes identity-encoded — re-compressing
+   * it would need the bytes in hand, and the one Blob this carries is a
+   * zstd artifact already. A Blob under the limit is small enough to read.
+   */
+  async writeBlob(digest: Digest, source: Uint8Array | Blob): Promise<void> {
+    const streamed =
+      source instanceof Blob && source.size > (this.negotiatedBatchBytes || SAFE_BATCH_BYTES)
+    const body = source instanceof Blob && !streamed ? await source.bytes() : source
+    const compressed = this.compression && body instanceof Uint8Array
+    // REAPI carries compression in the RESOURCE NAME:
+    //   uploads/{uuid}/compressed-blobs/{compressor}/{hash}/{uncompressed_size}
+    // The digest and size stay those of the UNCOMPRESSED bytes — the server
+    // decompresses and verifies against them — so only the wire payload
+    // changes. vx artifacts are already-compressed tarballs, but source input
+    // trees are not, and those are the bulk of a remote-execution upload.
+    let chunk = this.chunkBytes
+    for (let attempt = 0; ; attempt++) {
+      const wire = compressed ? Bun.zstdCompressSync(body) : body
+      const wireBytes = wire instanceof Blob ? wire.size : wire.length
+      const segment = compressed
+        ? `compressed-blobs/zstd/${digest.hash}/${digest.size_bytes}`
+        : `blobs/${digest.hash}/${digest.size_bytes}`
+      const resource = `${this.instance ? `${this.instance}/` : ''}uploads/${crypto.randomUUID()}/${segment}`
+      const bounds = this.bounded()
+      try {
+        await this.writeResource(resource, wire, digest, 0, chunk, compressed, bounds)
+        return
+      } catch (err) {
+        const code = (err as grpc.ServiceError).code
+        // ADAPTIVE DOWNGRADE. The Bun node:http2 flow-control defect is a
+        // RACE, not a boundary: chunk sizes above the RFC default initial
+        // window (65535) usually work and occasionally wedge — observed as a
+        // one-off DEADLINE_EXCEEDED at 128 KB on the same Bun that passed it
+        // hundreds of times. A deadline on a multi-message write therefore
+        // retries ONCE at SAFE_CHUNK_BYTES, the size never observed hanging,
+        // instead of failing the task over a lost coin-flip.
+        // Only a MULTI-message write can be the chunk race — a body that fit
+        // one message never exercised flow control between messages, so its
+        // deadline is the server's problem and re-chunking cannot help.
+        // The deadline has TWO spellings: this client's own timer
+        // (DEADLINE_EXCEEDED), or the server's. A grpc-go server (bazel-remote)
+        // arms a timer at the call's `grpc-timeout` and ends the stream with
+        // RST_STREAM(CANCEL), which grpc-js reports as `CANCELLED: Call
+        // cancelled`; whichever lands first names the error, and on a stalled
+        // write the server's usually does (item 1017: 5 of 6 against a grpc-go
+        // server that stopped reading). This client never cancels a write it
+        // reports — its own `cancel()` rethrows the error that caused it — so
+        // a CANCELLED at or past this attempt's deadline IS the deadline. The
+        // header carries `ceil(deadline - now)`, so the server's timer cannot
+        // fire before ours: no slack. An earlier CANCELLED is the server's own.
+        if (
+          (code === grpc.status.DEADLINE_EXCEEDED ||
+            (code === grpc.status.CANCELLED && Date.now() >= deadlineOf(bounds))) &&
+          chunk > SAFE_CHUNK_BYTES &&
+          wireBytes > chunk
+        ) {
+          this.onWarn(
+            `vx/reapi: chunked write of ${digest.hash.slice(0, 12)} hit the ${chunk}-byte chunk stall (Bun http2 flow control); retrying at ${SAFE_CHUNK_BYTES}`,
+          )
+          chunk = SAFE_CHUNK_BYTES
+          continue
+        }
+        const delay = this.retryDelay(attempt, code)
+        if (delay === undefined) throw err
+        if (!compressed) {
+          // Identity path: ask how far the server got and resume there.
+          const status = await this.queryWriteStatus(resource).catch(() => null)
+          if (status?.complete === true) return
+          if (status !== null && status.committedSize > 0 && status.committedSize < wireBytes) {
+            try {
+              await this.writeResource(
+                resource,
+                wire,
+                digest,
+                status.committedSize,
+                chunk,
+                false,
+                this.bounded(),
+              )
+              return
+            } catch {
+              // fall through to a fresh attempt
+            }
+          }
+        }
+        await Bun.sleep(delay)
+      }
+    }
+  }
+
+  /**
+   * One ByteStream `Write` from `startOffset`. Each message waits for the
+   * channel to drain before the next is read, so a streamed `Blob` holds at
+   * most a few messages in memory however large it is.
+   */
+  private async writeResource(
+    resource: string,
+    body: Uint8Array | Blob,
+    digest: Digest,
+    startOffset: number,
+    chunkBytes: number,
+    compressed: boolean,
+    bounds: grpc.CallOptions,
+  ): Promise<void> {
+    const total = body instanceof Blob ? body.size : body.length
+    let stream!: {
+      write(m: unknown): boolean
+      end(): void
+      cancel(): void
+      on(e: string, f: (x: unknown) => void): void
+      once(e: string, f: () => void): void
+    }
+    const done = new Promise<void>((resolve, reject) => {
+      stream = (this.svc.bs as unknown as Record<string, Function>)['write']!(
+        this.meta(),
+        bounds,
+        (err: grpc.ServiceError | null, res: { committed_size?: string }) => {
+          if (err) return reject(err)
+          const committed = Number(res.committed_size ?? 0)
+          // For a compressed upload the server reports the COMPRESSED byte
+          // count it accepted, so the equality only holds on the identity
+          // path; on the compressed path a non-zero commit is the signal.
+          // A server that already holds the blob ends a compressed write
+          // with `-1` (the spec's word for it); read as a short write, it
+          // failed the upload of an input two actions share (F-44).
+          const expected = compressed ? total : digest.size_bytes
+          if (committed !== expected && !(compressed && (committed > 0 || committed === -1))) {
+            return reject(
+              new Error(`reapi: short write for ${digest.hash}: ${committed}/${expected}`),
+            )
+          }
+          resolve()
+        },
+      )
+      stream.on('error', reject)
+    })
+    // Raced against every drain wait and awaited at the end; a failure that
+    // lands between the two is not an unhandled rejection.
+    done.catch(() => undefined)
+    let offset = startOffset
+    let first = true
+    try {
+      for await (const data of messagesOf(body, startOffset, chunkBytes)) {
+        const end = offset + data.length
+        const flowing = stream.write({
+          resource_name: first ? resource : '',
+          write_offset: offset,
+          finish_write: end === total,
+          data,
+        })
+        first = false
+        offset = end
+        if (!flowing) await Promise.race([new Promise<void>((r) => stream.once('drain', r)), done])
+      }
+      // Empty blobs still need one message so the server sees finish_write.
+      if (first) {
+        stream.write({
+          resource_name: resource,
+          write_offset: offset,
+          finish_write: true,
+          data: new Uint8Array(0),
+        })
+      }
+    } catch (err) {
+      // The source failed mid-write (a pruned artifact) or the call did:
+      // either way the half-sent write must not be left open on the channel.
+      stream.cancel()
+      throw err
+    }
+    stream.end()
+    await done
+  }
+
+  /**
+   * Read a blob via ByteStream; `null` on NOT_FOUND. A transient status is
+   * retried as a unary call's is (the read is whole and idempotent): one
+   * UNAVAILABLE reading a finished action's stdout or outputs failed the
+   * task after the action succeeded (item 919).
+   */
+  async readBlob(digest: Digest): Promise<Uint8Array | null> {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const blob = await this.readBlobOnce(digest)
+        this.unreachable = false
+        return blob
+      } catch (err) {
+        const delay = this.retryDelay(attempt, (err as grpc.ServiceError).code)
+        if (delay === undefined) throw err
+        await Bun.sleep(delay)
+      }
+    }
+  }
+
+  private readBlobOnce(digest: Digest): Promise<Uint8Array | null> {
+    const segment = this.compression
+      ? `compressed-blobs/zstd/${digest.hash}/${digest.size_bytes}`
+      : `blobs/${digest.hash}/${digest.size_bytes}`
+    const resource = `${this.instance ? `${this.instance}/` : ''}${segment}`
+    const compressed = this.compression
+    // Refused as the bytes pass the bound, not once the server stops: a
+    // body that never ends held every chunk it sent (L-3).
+    const bound = compressed ? wireBound(Number(digest.size_bytes)) : Number(digest.size_bytes)
+    return new Promise((resolve, reject) => {
+      const chunks: Uint8Array[] = []
+      let received = 0
+      let over = false
+      const stream = (this.svc.bs as unknown as Record<string, Function>)['read']!(
+        { resource_name: resource, read_offset: 0, read_limit: 0 },
+        this.meta(),
+        this.bounded(),
+      ) as { on(e: string, f: (x: never) => void): void; cancel(): void }
+      stream.on('data', (m: { data: Uint8Array }) => {
+        if (over) return
+        received += m.data.length
+        if (received > bound) {
+          over = true
+          chunks.length = 0
+          reject(overServed(digest))
+          stream.cancel()
+          return
+        }
+        chunks.push(m.data)
+      })
+      stream.on('error', (err: grpc.ServiceError) =>
+        err.code === NOT_FOUND ? resolve(null) : reject(err),
+      )
+      stream.on('end', async () => {
+        if (over) return
+        const total = chunks.reduce((n, c) => n + c.length, 0)
+        const out = new Uint8Array(total)
+        let at = 0
+        for (const c of chunks) {
+          out.set(c, at)
+          at += c.length
+        }
+        try {
+          const body = compressed ? await unzstdBounded(out, digest) : out
+          assertBlobIntegrity(body, digest, this.digestFunction)
+          resolve(body)
+        } catch (err) {
+          reject(err)
+        }
+      })
+    })
+  }
+
+  /**
+   * `readBlob` as a stream: each ByteStream message is taken from the call
+   * only when the reader asks for the next, so a blob of any size costs the
+   * call's small read-ahead in memory. `null` on NOT_FOUND, known from the
+   * first message before the stream is handed over. The digest is checked as
+   * the bytes pass and a mismatch errors the stream at its end, so no reader
+   * reaches the end of a blob that is not the one asked for.
+   * Identity-encoded, as `writeBlob` streams: the blob this reads is a zstd
+   * artifact already.
+   */
+  async readBlobStream(digest: Digest): Promise<ReadableStream<Uint8Array> | null> {
+    const resource = `${this.instance ? `${this.instance}/` : ''}blobs/${digest.hash}/${digest.size_bytes}`
+    type Message = { data: Uint8Array }
+    let call: AsyncIterable<Message> & { cancel(): void }
+    let messages: AsyncIterator<Message>
+    const open = (offset: number): void => {
+      call = (this.svc.bs as unknown as Record<string, Function>)['read']!(
+        { resource_name: resource, read_offset: offset, read_limit: 0 },
+        this.meta(),
+        this.bounded(),
+      ) as AsyncIterable<Message> & { cancel(): void }
+      messages = call[Symbol.asyncIterator]()
+    }
+    const hasher = hasherFor(this.digestFunction)
+    let size = 0
+    let attempt = 0
+    // A transient status is retried as `readBlob`'s is, and not only before
+    // the first message: a cut past it (a proxy's RST, a server's GOAWAY)
+    // re-opens the Read at `read_offset` = the bytes the reader already has,
+    // so the hash carries on over the same byte sequence. The budget is one
+    // for the whole blob. Before the first message a NOT_FOUND is a miss.
+    const take = async (): Promise<IteratorResult<Message>> => {
+      for (;;) {
+        try {
+          return await messages.next()
+        } catch (err) {
+          const code = (err as grpc.ServiceError).code
+          const delay = this.retryDelay(attempt++, code)
+          if (delay === undefined) throw err
+          await Bun.sleep(delay)
+          open(size)
+        }
+      }
+    }
+    open(0)
+    let next: IteratorResult<Message> | undefined
+    try {
+      next = await take()
+    } catch (err) {
+      if ((err as grpc.ServiceError).code === NOT_FOUND) return null
+      throw err
+    }
+    return new ReadableStream<Uint8Array>({
+      pull: async (controller) => {
+        const got = next ?? (await take())
+        next = undefined
+        if (got.done) {
+          assertServed(size, hasher && (() => hasher.digest('hex')), digest)
+          controller.close()
+          return
+        }
+        size += got.value.data.length
+        if (size > Number(digest.size_bytes)) {
+          call.cancel()
+          throw overServed(digest)
+        }
+        hasher?.update(got.value.data)
+        controller.enqueue(got.value.data)
+      },
+      cancel: () => {
+        call.cancel()
+      },
+    })
+  }
+
+  /**
+   * `Execute` — a SERVER-STREAMING call yielding `Operation`s until one is
+   * `done`. Resolves with the terminal operation. If the stream drops
+   * mid-flight with a transient status, or ends before the operation is
+   * done, the call RE-ATTACHES to the same operation through
+   * `WaitExecution` instead of re-running the action — that is exactly what
+   * the RPC exists for.
+   *
+   * `skip_cache_lookup` is TRUE by design: vx has already decided this is a
+   * miss (it owns the cache key and consulted its own layers), so letting the
+   * server re-check its ActionCache would be a second, differently-keyed
+   * cache deciding whether the user's task runs.
+   */
+  async execute(
+    actionDigest: Digest,
+    opts: ExecuteOptions = {},
+    signal?: AbortSignal,
+  ): Promise<Operation> {
+    const req = {
+      instance_name: this.instance,
+      action_digest: actionDigest,
+      skip_cache_lookup: opts.skipCacheLookup ?? true,
+      // Ask the server to INLINE stdout/stderr in the ActionResult. Without
+      // this every finished action costs two extra CAS round trips just to
+      // read what it printed.
+      inline_stdout: opts.inlineStdout ?? true,
+      inline_stderr: opts.inlineStderr ?? true,
+      ...(opts.inlineOutputFiles === undefined
+        ? {}
+        : { inline_output_files: opts.inlineOutputFiles }),
+      ...(opts.priority === undefined ? {} : { execution_policy: { priority: opts.priority } }),
+      ...(opts.resultsCachePriority === undefined
+        ? {}
+        : { results_cache_policy: { priority: opts.resultsCachePriority } }),
+      ...(this.digestFunction === 'SHA256' ? {} : { digest_function: this.digestFunction }),
+    }
+    let operationName = ''
+    for (let attempt = 0; ; attempt++) {
+      let failure: unknown
+      try {
+        const op =
+          operationName === ''
+            ? await this.operationStream('execute', req, signal, opts.onStage, (n) => {
+                operationName = n
+                opts.onOperation?.(n)
+              })
+            : await this.operationStream(
+                'waitExecution',
+                { name: operationName },
+                signal,
+                opts.onStage,
+              )
+        if (op.done) return op
+        // A stream can END cleanly on an operation still QUEUED or EXECUTING
+        // (a server or proxy cutting long streams); the operation lives on,
+        // so it is re-attached as a dropped stream is, on the same budget.
+        // An unnamed one cannot be re-attached, and a plain Error is not
+        // retried.
+        if (operationName === '') {
+          throw new Error('reapi: execution stream closed before the operation finished')
+        }
+        failure = new Error(
+          `reapi: execution stream for ${operationName} closed before the operation finished`,
+        )
+      } catch (err) {
+        const code = (err as grpc.ServiceError).code
+        // WaitExecution's NOT_FOUND: the server no longer knows the operation
+        // (a restart lost it). Nothing is running to re-attach to, and the
+        // action is the same bytes, so it is executed again, on the same
+        // budget — as Bazel's executor does.
+        if (code === NOT_FOUND && operationName !== '') operationName = ''
+        else if (!isRetryable(code)) throw err
+        failure = err
+      }
+      const delay = RETRY_DELAYS_MS[attempt]
+      if (delay === undefined) throw failure
+      await abortableSleep(delay, signal)
+    }
+  }
+
+  /**
+   * `Operations.CancelOperation`: closing the Execute stream leaves a queued
+   * action to the server, which may still run it. One attempt on the
+   * control-plane deadline: a cancel is a courtesy, and a server without
+   * the service answers UNIMPLEMENTED.
+   */
+  cancelOperation(name: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      ;(this.svc.ops as unknown as Record<string, Function>)['cancelOperation']!(
+        { name },
+        this.meta(),
+        this.boundedMeta(),
+        (err: grpc.ServiceError | null) => (err ? reject(err) : resolve()),
+      )
+    })
+  }
+
+  /** Re-attach to an in-flight operation after a disconnect. */
+  waitExecution(
+    operationName: string,
+    signal?: AbortSignal,
+    onStage?: (stage: string) => void,
+  ): Promise<Operation> {
+    return this.operationStream('waitExecution', { name: operationName }, signal, onStage)
+  }
+
+  private operationStream(
+    method: string,
+    req: unknown,
+    signal?: AbortSignal,
+    onStage?: (stage: string) => void,
+    onName?: (name: string) => void,
+  ): Promise<Operation> {
+    return new Promise((resolve, reject) => {
+      // An aborted signal never fires `abort` again, and the stream has no
+      // deadline of its own (time QUEUED is unbounded), so a listener added
+      // after the abort would wait on a wedged server forever.
+      if (signal?.aborted === true) return reject(executionAborted())
+      const stream = (this.svc.exec as unknown as Record<string, Function>)[method]!(
+        req,
+        this.meta(),
+      ) as { on(e: string, f: (x: never) => void): void; cancel(): void }
+      let last: Operation | undefined
+      const onAbort = (): void => {
+        stream.cancel()
+        reject(executionAborted())
+      }
+      signal?.addEventListener('abort', onAbort, { once: true })
+      stream.on('data', (op: Operation) => {
+        last = op
+        if (op.name !== '' && op.name !== undefined && onName !== undefined) onName(op.name)
+        // ExecuteOperationMetadata carries the action's STAGE
+        // (QUEUED / EXECUTING / COMPLETED). Surfacing it is the difference
+        // between "vx is hung" and "the action is queued behind 40 others".
+        if (onStage !== undefined && op.metadata?.value !== undefined) {
+          const stage = decodeStage(op.metadata.value)
+          if (stage !== undefined) onStage(stage)
+        }
+      })
+      stream.on('error', (err: grpc.ServiceError) => {
+        signal?.removeEventListener('abort', onAbort)
+        reject(err)
+      })
+      stream.on('end', () => {
+        signal?.removeEventListener('abort', onAbort)
+        if (last === undefined)
+          return reject(new Error('reapi: execution stream closed with no operation'))
+        resolve(last)
+      })
+    })
+  }
+
+  /**
+   * `SplitBlob` — ask the server to content-defined-chunk a blob and return
+   * the chunk digests. With `FindMissingBlobs` over those chunks, a client
+   * transfers only the parts of a large blob it does not already hold. Gated
+   * by `split_blob_support`; experimental, so callers must check first.
+   */
+  async splitBlob(blobDigest: Digest): Promise<{ chunks: Digest[]; chunkingFunction: string }> {
+    const res = await this.unary<{ chunk_digests?: Digest[]; chunking_function?: string }>(
+      this.svc.cas,
+      'splitBlob',
+      {
+        instance_name: this.instance,
+        blob_digest: blobDigest,
+        ...(this.digestFunction === 'SHA256' ? {} : { digest_function: this.digestFunction }),
+      },
+      this.meta(),
+      this.bounded(),
+    )
+    return { chunks: res.chunk_digests ?? [], chunkingFunction: res.chunking_function ?? 'UNKNOWN' }
+  }
+
+  /**
+   * `SpliceBlob` — the inverse: hand the server an ordered chunk list and it
+   * reassembles the blob in CAS, so the client never uploads the parts it
+   * already knows are there. Gated by `splice_blob_support`.
+   */
+  async spliceBlob(chunkDigests: readonly Digest[], expected?: Digest): Promise<Digest> {
+    const res = await this.unary<{ blob_digest?: Digest }>(
+      this.svc.cas,
+      'spliceBlob',
+      {
+        instance_name: this.instance,
+        chunk_digests: chunkDigests,
+        ...(expected === undefined ? {} : { blob_digest: expected }),
+        ...(this.digestFunction === 'SHA256' ? {} : { digest_function: this.digestFunction }),
+      },
+      this.meta(),
+      this.bounded(),
+    )
+    return res.blob_digest ?? { hash: '', size_bytes: 0 }
+  }
+
+  /**
+   * `GetTree` — every Directory under `rootDigest`. The RPC is
+   * SERVER-STREAMING: one call carries every page, and `next_page_token`
+   * only names where a later call would resume. It went through the unary
+   * helper before (item 824), whose callback a streaming stub never calls,
+   * so every call hung until its deadline passed unheard.
+   */
+  async getTree(rootDigest: Digest): Promise<Directory[]> {
+    const call = (this.svc.cas as unknown as Record<string, Function>)['getTree']!(
+      { instance_name: this.instance, root_digest: rootDigest, page_token: '' },
+      this.meta(),
+      this.bounded(),
+    ) as AsyncIterable<{ directories?: Directory[] }>
+    const out: Directory[] = []
+    for await (const page of call) out.push(...(page.directories ?? []))
+    return out
+  }
+
+  /**
+   * Closing the channel-owning stub tears the connection down; the others
+   * borrow it, so closing them too would double-close one channel.
+   */
+  close(): void {
+    this.svc.cas.close()
+  }
+}
+
+/** google.longrunning.Operation, narrowed to what Execute returns. */
+export interface Operation {
+  name: string
+  done: boolean
+  /** `google.rpc.Status` when the EXECUTION ITSELF failed (not a non-zero exit). */
+  error?: { code?: number; message?: string }
+  /** `ExecuteResponse`, packed in an Any. */
+  response?: { type_url?: string; value?: Uint8Array }
+  /** `ExecuteOperationMetadata`, packed in an Any. */
+  metadata?: { type_url?: string; value?: Uint8Array }
+}
+
+export interface ExecuteOptions {
+  /** The operation's name, once the server has given one. */
+  onOperation?: (name: string) => void
+  /** Default TRUE: vx owns the cache decision, so the server must not re-check its own AC. */
+  skipCacheLookup?: boolean
+  inlineStdout?: boolean
+  inlineStderr?: boolean
+  /** Output files the server should inline in the result, sparing a fetch. */
+  inlineOutputFiles?: readonly string[]
+  /** `ExecutionPolicy.priority` — lower runs sooner. */
+  priority?: number
+  /** `ResultsCachePolicy.priority` — retention hint for the result. */
+  resultsCachePriority?: number
+  /** QUEUED / EXECUTING / COMPLETED as the operation progresses. */
+  onStage?: (stage: string) => void
+}
+
+const EXEC_STAGE = ['UNKNOWN', 'CACHE_CHECK', 'QUEUED', 'EXECUTING', 'COMPLETED'] as const
+
+/** `ExecuteOperationMetadata { stage = 1 (enum), action_digest = 2, ... }` */
+function decodeStage(buf: Uint8Array): string | undefined {
+  let i = 0
+  while (i < buf.length) {
+    let key = 0
+    let shift = 0
+    for (;;) {
+      const b = buf[i++]
+      if (b === undefined) return undefined
+      key |= (b & 0x7f) << shift
+      if ((b & 0x80) === 0) break
+      shift += 7
+    }
+    const field = key >>> 3
+    const wire = key & 7
+    if (wire === 0) {
+      let v = 0
+      let sh = 0
+      for (;;) {
+        const b = buf[i++]
+        if (b === undefined) return undefined
+        v |= (b & 0x7f) << sh
+        if ((b & 0x80) === 0) break
+        sh += 7
+      }
+      if (field === 1) return EXEC_STAGE[v] ?? `STAGE_${v}`
+    } else if (wire === 2) {
+      let len = 0
+      let sh = 0
+      for (;;) {
+        const b = buf[i++]
+        if (b === undefined) return undefined
+        len |= (b & 0x7f) << sh
+        if ((b & 0x80) === 0) break
+        sh += 7
+      }
+      i += len
+    } else break
+  }
+  return undefined
+}
+
+export interface ExecuteResponse {
+  result?: ActionResult
+  cached_result?: boolean
+  status?: { code?: number; message?: string }
+  message?: string
+}
+
+/** The subset of REAPI's ActionResult a cache entry uses. */
+export interface ActionResult {
+  exit_code?: number
+  output_files?: Array<{
+    path: string
+    digest: Digest
+    is_executable?: boolean
+    contents?: Uint8Array
+  }>
+  output_directories?: Array<{ path: string; tree_digest: Digest }>
+  output_symlinks?: Array<{ path: string; target: string }>
+  /** Servers MAY normalise inline stdout/stderr into CAS and return digests instead. */
+  stdout_digest?: Digest
+  stdout_raw?: Uint8Array
+  stderr_digest?: Digest
+  stderr_raw?: Uint8Array
+  execution_metadata?: {
+    worker?: string
+    execution_start_timestamp?: unknown
+    execution_completed_timestamp?: unknown
+  }
+}