@vzn/vx-cache 0.0.651 → 0.0.653

package/README.md

@@ -31,7 +31,8 @@ export default {
 
 - `url` is the server's base URL (`https://cache.example.com`, without `/v1`), or `VX_CACHE_URL`.
   It must be `https://`: every request carries the CI token, so `http://`
-  is taken only to this machine (`127.0.0.1`, `::1`, `localhost`). The
+  is taken only to this machine (`127.0.0.1`, `::1`, `localhost`). It
+  takes no `?query` or `#fragment`: each route is appended to it. The
   option is checked when the config loads, `VX_CACHE_URL` when a run
   opens the cache.
 - `issuer` (the CI issuer's URL, as its tokens name it) and `repository`
@@ -86,29 +87,42 @@ its remote is off for the run.
 An upload answered with a 5xx or a 429, or whose connection reset, is sent again, three tries in
 all: a PUT names its hash, so a second one stores the same bytes.
 
+An artifact is immutable on the server: one that did not read back
+(corrupt) is not replaced. Its re-run's upload is not sent and not
+counted as landed (a DTE worker is not told it did), and the run says
+once that the remote misses the key until the bucket's lifecycle rule
+expires it (`@vzn/vx-cache-server`'s Expiry).
+
 A refused token is said once and turns the remote off for the run; a
 refused write (a job that reads only) turns off writes alone. Any other
 refusal is a warning naming the server's own words, and the task reads
-as a miss.
+as a miss. A token the request sent (the job's OIDC token, a lent one,
+`VX_CACHE_TOKEN`) that those words or any error quote is written `***`.
 
 Every read names scopes, each a ref, percent-encoded. A check names the run's refs in order (its branch, then the
 branch it merges into, then the default branch; on CI `github()` or
 `gitlab()` from `@vzn/vx-ci` names them, so declare it too: without it
 a run reads git's branch and the default branch only), and the first ref
-holding a hash answers it; its download names that ref. A ref longer
+holding a hash answers it; its download names that ref, and one the
+check has not answered yet names them all in one request. A ref longer
 than a scope may be (512 characters, percent-encoded) is said and not
-read; the others are. A run that reads no ref says so and stays local. The run asks the server's limits once
-(`/v1/capabilities`) and checks in chunks of its `maxCheckHashes`
-lookups, all at once; a run reading more refs than one check takes
-(Workers' default is 6) spreads each hash's scopes over several. It
-keeps to the limits each `/v1/artifacts` answer names, a refusal's too,
-so a server restarted with lower ones refuses one check, not the run's. Each
-upload is one artifact by `PUT`, up to four at once: its bytes reach the
+read; the others are. A run that reads no ref says so and stays local. The server is asked nothing until a
+check, a download or an upload, so a run the local cache answers sends
+it no request. Its limits are not asked apart: each `/v1/artifacts`
+answer names them, a refusal's too, and no limit is guessed. A check
+before any answer goes whole; one refused for its size is sent again,
+once, in chunks of the `maxCheckHashes` lookups its refusal names, all at
+once, so a server restarted with lower ones costs one check a round-trip,
+not the run its reads. A run reading more refs than one check takes
+(Workers' default is 6) spreads each hash's scopes over several. Each
+upload is one artifact by `PUT`, as many at once as core's
+`cache.concurrency.upload` lets (64 to 96 by default): its bytes reach the
 bucket untouched by the server's code (a batch, split by that code, ran
-out of Workers' CPU). While the server names no limits (said once),
-checks go one hash at a time: no limit is guessed. An artifact over the server's upload limit is not sent: it
-is said once. An answer is read no further than its use: 64 KiB for the
-capabilities or a token, 512 bytes a hash for a check, a refusal's first
+out of Workers' CPU). An artifact over the server's upload limit is not sent: it
+is said. Before any answer has named the limits, the first such upload
+is sent and refused `413`, which names them: it is said the same way,
+never a failed upload. An answer is read no further than its use: 64 KiB for a
+token, 1 KiB a hash for a check, a refusal's first
 2 KiB; a longer one is refused, so a server's endless answer cannot fill
 memory.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-cache",
-  "version": "0.0.651",
+  "version": "0.0.653",
   "license": "MIT",
   "description": "vxCache(): a vx cache plugin for a server that speaks the vx-cache protocol, such as @vzn/vx-cache-server.",
   "keywords": [
@@ -32,7 +32,7 @@
     "jose: the tests sign the CI tokens the server checks."
   ],
   "peerDependencies": {
-    "@vzn/vx": "^0.0.651"
+    "@vzn/vx": "^0.0.653"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -26,7 +26,7 @@ export interface VxCacheOptions {
   issuer: string
   /** The repository at that issuer, `org/name`. */
   repository: string
-  /** Per-request deadline for reads and queries (default 30 s); a download's bounds its answer, then each gap between its bytes. */
+  /** Per-request deadline for reads and queries (default 30 s); a download's bounds its answer, then its bytes must arrive at 1 MiB a second over each. */
   timeoutMs?: number
   /** … and for an upload (default 60 s): its bytes must leave at 1 MiB a second over each, then its answer come within one. */
   uploadTimeoutMs?: number
@@ -70,8 +70,6 @@ const LEND_MARGIN_MS = 5 * 60_000
 const ASK_ATTEMPTS = 3
 /** A connection that dropped, not a server that answered: an upload is sent again. */
 const RESET = new Set(['ECONNRESET', 'EPIPE', 'ECONNREFUSED'])
-/** Uploads open at once; more wait. */
-const IN_FLIGHT = 4
 
 /**
  * The names a request sets itself: one of them in `headers`, in another
@@ -146,10 +144,14 @@ async function jsonUpTo(res: Response, max: number, what: string): Promise<unkno
   return JSON.parse(text)
 }
 
-/** Capabilities and a CI token are a few hundred bytes: room to spare. */
+/** A CI token's answer is a few hundred bytes: room to spare. */
 const SMALL_ANSWER_BYTES = 64 * 1024
-/** A check's answer per hash asked: a hash, a size and a scope in JSON are under 150 bytes. */
-const CHECK_BYTES_PER_HASH = 512
+/**
+ * A check's answer per hash asked: a hash (up to 128), a size and a scope
+ * (up to 512, a long branch's) in JSON are under 700 bytes. At 512 an
+ * answer under the longest scopes was refused as too long.
+ */
+const CHECK_BYTES_PER_HASH = 1024
 
 /**
  * `s` with each C0/C1 control and DEL written as `\xNN`: a server's words
@@ -160,8 +162,22 @@ const printable = (s: string): string =>
   // oxlint-disable-next-line no-control-regex
   s.replace(/[\x00-\x1f\x7f-\x9f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`)
 
-/** A refusal, named by its status and the server's own `message`. */
-async function refusal(res: Response): Promise<Error> {
+/** Shorter values are not hidden, as core masks none under 6 characters: each would blank common words. */
+const MIN_TOKEN_CHARS = 6
+
+/** `text` with each of `tokens` written `***`. */
+function hideTokens(text: string, tokens: Iterable<string>): string {
+  let out = text
+  for (const token of tokens)
+    if (token.length >= MIN_TOKEN_CHARS) out = out.replaceAll(token, '***')
+  return out
+}
+
+/**
+ * A refusal, named by its status and the server's own `message`, each
+ * token `hide` knows written `***` before the cut, so none is left in part.
+ */
+async function refusal(res: Response, hide: (text: string) => string): Promise<Error> {
   let said = ''
   try {
     const { text } = await upTo(res, 2048)
@@ -175,7 +191,7 @@ async function refusal(res: Response): Promise<Error> {
   } catch {
     // quiet: the status alone still names the refusal
   }
-  said = printable(said.replace(/\s+/g, ' ').trim().slice(0, 200))
+  said = printable(hide(said).replace(/\s+/g, ' ').trim().slice(0, 200))
   return new Error(`HTTP ${res.status}${said === '' ? '' : `: ${said}`}`)
 }
 
@@ -311,40 +327,7 @@ function paced(
   return { body, stop: window.stop }
 }
 
-/**
- * Uploads: up to `IN_FLIGHT` at once, each one artifact by `PUT`, whose
- * bytes reach the bucket untouched (2026-10-25: no batch upload; a
- * batch passes through the server's code, which on Workers costs CPU by the
- * byte, and a 40 MB one ran out of it).
- */
-class Lane<T, R> {
-  private readonly waiting: { item: T; resolve(r: R): void; reject(err: unknown): void }[] = []
-  private open = 0
-
-  constructor(private readonly send: (item: T) => Promise<R>) {}
-
-  push(item: T): Promise<R> {
-    const { promise, resolve, reject } = Promise.withResolvers<R>()
-    this.waiting.push({ item, resolve, reject })
-    this.pump()
-    return promise
-  }
-
-  private pump(): void {
-    while (this.open < IN_FLIGHT && this.waiting.length > 0) {
-      const w = this.waiting.shift()!
-      this.open++
-      void this.send(w.item)
-        .then(w.resolve, w.reject)
-        .finally(() => {
-          this.open--
-          this.pump()
-        })
-    }
-  }
-}
-
-/** The limits a server names at `/v1/capabilities` and on each check (`vx-max-*`). */
+/** The limits a server names on each `/v1/artifacts` answer (`vx-max-*`). */
 interface Limits {
   readonly maxCheckHashes: number
   readonly maxUploadBytes: number
@@ -363,14 +346,11 @@ const chunks = <T>(all: readonly T[], size: number): T[][] =>
     all.slice(i * size, (i + 1) * size),
   )
 
-/** The limits an answer's `vx-max-*` headers name. */
-const limitsNamed = (res: Response): Limits | undefined =>
-  limitsOf((k) => Number(res.headers.get(LIMIT_HEADERS[k]) ?? NaN))
-
-/** Each limit, or undefined when one is missing or bad. */
-function limitsOf(read: (k: keyof Limits) => unknown): Limits | undefined {
-  const maxCheckHashes = count(read('maxCheckHashes'))
-  const maxUploadBytes = count(read('maxUploadBytes'))
+/** The limits an answer's `vx-max-*` headers name, or undefined when one is missing or bad. */
+function limitsNamed(res: Response): Limits | undefined {
+  const read = (k: keyof Limits) => count(Number(res.headers.get(LIMIT_HEADERS[k]) ?? NaN))
+  const maxCheckHashes = read('maxCheckHashes')
+  const maxUploadBytes = read('maxUploadBytes')
   return maxCheckHashes === undefined || maxUploadBytes === undefined
     ? undefined
     : { maxCheckHashes, maxUploadBytes }
@@ -378,7 +358,7 @@ function limitsOf(read: (k: keyof Limits) => unknown): Limits | undefined {
 
 /**
  * The seam over vx-cache v1. `has` and `hasMany` are `check`, `get` a
- * download and `put` an upload by `PUT` (`Lane`). A check names the
+ * download and `put` an upload by `PUT`. A check names the
  * scope of each ref the run reads, in order, and the first holding a hash
  * answers it; a download names the scope its check found. A refused token (401/403) throws
  * once, for core to report, and turns the layer off for the run; an
@@ -390,18 +370,25 @@ export class VxCacheLayer implements RemoteCacheLayer {
   private writesRefused = false
   /** The refs a read names, in order: the first holding a hash answers it. */
   refs: readonly string[] = []
+  private scoped: { refs: readonly string[]; scopes: readonly string[] } | undefined
+  /** `refs` as the wire names them (`scopeOf`), encoded once. */
+  private get scopes(): readonly string[] {
+    if (this.scoped?.refs !== this.refs)
+      this.scoped = { refs: this.refs, scopes: this.refs.map(scopeOf) }
+    return this.scoped.scopes
+  }
   /** The ref a check found each hash under, which its download names. */
   private readonly found = new Map<string, string>()
-  /** The limits the server named, at `/v1/capabilities` and on its last check; nothing is guessed. */
+  /**
+   * The limits the server's last answer named; none before its first.
+   * Nothing is guessed, nor asked apart: a check before any answer goes
+   * whole, and one refused for its size is sent again in the chunks its
+   * refusal names (`/v1/capabilities` cost every run a request, one
+   * round-trip before its first check, 2026-11-06).
+   */
   private limits: Limits | undefined
-  private asked: Promise<Limits | undefined> | undefined
   /** Where the layer says what is no failure of a request: core's `ctx.warn`. */
   warn: (message: string) => void = () => {}
-  private limitsMissing = false
-
-  private readonly uploads = new Lane<{ hash: string; body: Blob }, void | false>((item) =>
-    this.upload(item),
-  )
 
   /** The issuer and repository, named on every request by their hashes. */
   private readonly named: Readonly<Record<string, string>>
@@ -420,6 +407,26 @@ export class VxCacheLayer implements RemoteCacheLayer {
   }
 
   private idToken: { jwt: string; exp: number } | undefined
+  /**
+   * Every token this layer sent: a server that quoted a request's
+   * Authorization header in its refusal printed it to the CI log and
+   * cache.db, as core masks only secret-named variables.
+   */
+  private readonly sent = new Set<string>()
+  private readonly hidden = (text: string): string => hideTokens(text, this.sent)
+
+  /** `work`, each error it throws with every token sent hidden: the one way an error leaves the layer. */
+  private async guard<T>(work: Promise<T>): Promise<T> {
+    try {
+      return await work
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      const hidden = this.hidden(message)
+      if (hidden === message) throw err
+      const code = (err as { code?: unknown } | null)?.code
+      throw Object.assign(new Error(hidden), code === undefined ? {} : { code })
+    }
+  }
   /** The token a run running its tasks here lent (`CacheContext.lent`). */
   lent: (() => string | undefined) | undefined
 
@@ -459,6 +466,7 @@ export class VxCacheLayer implements RemoteCacheLayer {
    * run on every worker. A refusal (a 4xx) is final.
    */
   private async askOnce(ask: URL): Promise<Response> {
+    this.sent.add(this.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN!)
     for (let attempt = 1; ; attempt++) {
       let res: Response | undefined
       let failure: unknown
@@ -486,7 +494,7 @@ export class VxCacheLayer implements RemoteCacheLayer {
     let jwt: unknown
     try {
       const res = await this.askOnce(ask)
-      if (!res.ok) throw await refusal(res)
+      if (!res.ok) throw await refusal(res, this.hidden)
       jwt = ((await jsonUpTo(res, SMALL_ANSWER_BYTES, 'it')) as { value?: unknown } | null)?.value
       if (typeof jwt !== 'string' || jwt === '') throw new Error('no token in its answer')
     } catch (err) {
@@ -507,7 +515,11 @@ export class VxCacheLayer implements RemoteCacheLayer {
    * lends while its policy reads, and a refused token lent was refused on
    * every worker.
    */
-  async lend(): Promise<LentAccess | undefined> {
+  lend(): Promise<LentAccess | undefined> {
+    return this.guard(this.lending())
+  }
+
+  private async lending(): Promise<LentAccess | undefined> {
     if (this.disabled || this.lent?.() !== undefined) return undefined
     const jwt = await this.bearer(LEND_MARGIN_MS)
     if (jwt === '') return undefined
@@ -541,6 +553,7 @@ export class VxCacheLayer implements RemoteCacheLayer {
       this.tokenFailed = true
       throw err
     }
+    if (bearer !== '') this.sent.add(bearer)
     const ms = init.timeoutMs ?? this.config.timeoutMs
     const controller = new AbortController()
     let answer: ReturnType<typeof setTimeout> | undefined
@@ -592,7 +605,7 @@ export class VxCacheLayer implements RemoteCacheLayer {
         return undefined
       }
       throw new Error(
-        `${(await refusal(res)).message}: the write was refused (this job reads only); writes off for this run, reads go on`,
+        `${(await refusal(res, this.hidden)).message}: the write was refused (this job reads only); writes off for this run, reads go on`,
       )
     }
     if (res.status === 401 || res.status === 403) {
@@ -603,7 +616,7 @@ export class VxCacheLayer implements RemoteCacheLayer {
         return undefined
       }
       throw new Error(
-        `${(await refusal(res)).message}: ${bearer === '' ? 'a read with no token was refused' : `the token was refused (this workspace names ${this.config.repository} at ${this.config.issuer})`}; remote cache off for this run`,
+        `${(await refusal(res, this.hidden)).message}: ${bearer === '' ? 'a read with no token was refused' : `the token was refused (this workspace names ${this.config.repository} at ${this.config.issuer})`}; remote cache off for this run`,
       )
     }
     return res
@@ -616,73 +629,31 @@ export class VxCacheLayer implements RemoteCacheLayer {
     })
   }
 
-  /**
-   * The server's limits: `/v1/capabilities`, asked once and kept, then
-   * whatever each check names. Unnamed, said once: checks go one hash at
-   * a time.
-   */
-  private async limitsNow(): Promise<Limits | undefined> {
-    if (this.limits !== undefined) return this.limits
-    const asked = (this.asked ??= (async () => {
-      const res = await this.request('/v1/capabilities', { method: 'GET' })
-      if (res === undefined) return undefined
-      if (res.status !== 200) throw await refusal(res)
-      const body = (await jsonOf(res, '/v1/capabilities', SMALL_ANSWER_BYTES)) as Record<
-        string,
-        unknown
-      > | null
-      const named = limitsOf((k) => body?.[k])
-      if (named === undefined) this.limitsUnnamed(`/v1/capabilities (HTTP ${res.status})`)
-      return named
-    })())
-    // A failed ask is asked again by the next check: kept, two failures
-    // while a server restarted failed every read of the run (2026-10-26).
-    // quiet: the awaited ask rethrows it; this only forgets it
-    asked.catch(() => {
-      if (this.asked === asked) this.asked = undefined
-    })
-    this.limits ??= await asked
-    return this.limits
-  }
-
-  private limitsUnnamed(where: string): void {
-    if (this.limitsMissing) return
-    this.limitsMissing = true
-    this.warn(
-      `[vx] vx-cache: ${where} named no limits (maxCheckHashes, maxUploadBytes); checks go one hash at a time`,
-    )
-  }
-
-  /** A refusal met while starting, which no call could throw: the next check or download does. */
+  /** A token refusal met by `open`'s ask, which no call could throw: the next check or download does. */
   private unsaid: Error | undefined
-  /** Refusals a call threw: a check that waited on the start's ask threw it too. */
-  private readonly said = new WeakSet<object>()
+  /** A `replace` refused was said: it is said once a run. */
+  private saidNoReplace = false
 
-  /** Throws the refusal met while starting, once. */
+  /** Throws the refusal `open`'s ask met, once. */
   private sayUnsaid(): void {
     const err = this.unsaid
     this.unsaid = undefined
-    if (err !== undefined && !this.said.has(err)) {
-      this.said.add(err)
-      throw err
-    }
+    if (err !== undefined) throw err
   }
 
   /**
    * Core's `open`: called only when the run's policy reads or writes this
-   * remote, so a `--no-cache` run or a plan asks the server (and GitHub)
-   * nothing.
+   * remote, so a `--no-cache` run or a plan asks GitHub nothing. Starts
+   * asking for the job's token, so the first check need not wait on
+   * GitHub; the server is asked nothing until a check, a download or an
+   * upload, so a run the local cache answers sends it none.
    */
   async open(): Promise<void> {
-    this.start()
-  }
-
-  /** Starts asking for the limits, so the first check need not wait for them. */
-  start(): void {
-    this.limitsNow().catch((err: unknown) => {
-      // A refusal turned the layer off, and is said only once: the first
-      // check says it. Anything else, the first check asks again and says.
-      if (this.disabled) this.unsaid = err instanceof Error ? err : new Error(String(err))
+    this.bearer().catch((err: unknown) => {
+      // Said by the first call; the requests that shared the ask say nothing.
+      if (this.tokenFailed) return
+      this.tokenFailed = true
+      this.unsaid = err instanceof Error ? err : new Error(String(err))
     })
   }
 
@@ -696,33 +667,42 @@ export class VxCacheLayer implements RemoteCacheLayer {
    * keeps apart from "none held" (an empty map rewrote every key it asked
    * as a miss in `remote_hits`, and the next run fetched none of them).
    */
-  async hasMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
+  hasMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
+    return this.guard(this.lookup(hashes))
+  }
+
+  private async lookup(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
     const held = new Map<string, ArtifactInfo>()
     this.sayUnsaid()
     if (this.disabled || this.refs.length === 0) return null
-    const scopes = this.refs.map(scopeOf)
+    const scopes = this.scopes
     const ask = [...new Set(hashes)]
-    let limits: Limits | undefined
-    try {
-      limits = await this.limitsNow()
-    } catch (err) {
-      // A refusal turned the layer off: each waiter shares it, the first says it.
-      if (this.disabled && err instanceof Error) {
-        if (this.said.has(err)) return null
-        this.said.add(err)
-      }
-      throw err
+    const checks = (max: number, again: boolean) => {
+      // More refs than one check takes: each hash's scopes span several
+      // checks, the first in order holding it answering (a check of every
+      // scope at once was refused, every time).
+      const span = Math.min(scopes.length, max)
+      const per = Math.max(1, Math.floor(max / span))
+      const spans = chunks(scopes, span)
+      return chunks(ask, per).flatMap((some) => spans.map((s) => this.check(s, some, again)))
     }
-    const max = limits?.maxCheckHashes ?? scopes.length
-    // More refs than one check takes: each hash's scopes span several
-    // checks, the first in order holding it answering (a check of every
-    // scope at once was refused, every time).
-    const span = Math.min(scopes.length, max)
-    const per = Math.max(1, Math.floor(max / span))
-    const spans = chunks(scopes, span)
-    const parts = await Promise.all(
-      chunks(ask, per).flatMap((some) => spans.map((s) => this.check(s, some))),
+    // None named yet: one check of every lookup.
+    const first = await Promise.allSettled(
+      checks(this.limits?.maxCheckHashes ?? Math.max(1, ask.length * scopes.length), true),
     )
+    const refused = first.flatMap((r) => (r.status === 'rejected' ? [r.reason as unknown] : []))
+    const failed = refused.find((err) => !(err instanceof TooMany))
+    if (failed !== undefined) throw failed
+    const parts =
+      refused.length === 0
+        ? first.map(
+            (r) =>
+              (r as PromiseFulfilledResult<Map<string, { size: number; scope: string }>>).value,
+          )
+        : await settledAll(checks(Math.min(...refused.map((err) => (err as TooMany).max)), false))
+    // A token refused to `open`'s ask, which a check here shared.
+    this.sayUnsaid()
+    if (this.disabled) return null
     for (const part of parts)
       for (const [hash, { size, scope }] of part) {
         if (held.has(hash)) continue
@@ -732,15 +712,27 @@ export class VxCacheLayer implements RemoteCacheLayer {
     return held
   }
 
-  /** `POST /v1/artifacts` (Turbo's batch query): the size and scope of each hash held. */
+  /**
+   * `POST /v1/artifacts` (Turbo's batch query): the size and scope of each
+   * hash held. One refused for its size, its refusal naming a smaller
+   * `maxCheckHashes`, throws `TooMany` when `again`: the caller sends it
+   * in chunks.
+   */
   private async check(
     scopes: readonly string[],
     hashes: readonly string[],
+    again: boolean,
   ): Promise<Map<string, { size: number; scope: string }>> {
     const res = await this.json('/v1/artifacts', { hashes, scopes })
     if (res === undefined) return new Map()
-    if (res.status !== 200) throw await refusal(res)
-    if (limitsNamed(res) === undefined) this.limitsUnnamed(`the check (HTTP ${res.status})`)
+    if (res.status !== 200) {
+      const max = limitsNamed(res)?.maxCheckHashes
+      if (again && max !== undefined && hashes.length * scopes.length > max) {
+        await res.body?.cancel()
+        throw new TooMany(max)
+      }
+      throw await refusal(res, this.hidden)
+    }
     const body = (await jsonOf(
       res,
       '/v1/artifacts',
@@ -767,44 +759,104 @@ export class VxCacheLayer implements RemoteCacheLayer {
     return out
   }
 
-  /** The scope a check found it under, else each ref's in order until one holds it. */
-  async get(hash: string): Promise<{ body: Response; durationMs: undefined } | null> {
+  /**
+   * The scope a check found it under, else every ref's in order in one
+   * request, the first holding it answering: one by one, a branch's run
+   * paid a round-trip and a 404 for its own scope before each download of
+   * main's (2026-11-06). More refs than the server's `maxCheckHashes` go
+   * in several, in order.
+   */
+  get(hash: string): Promise<{ body: Response; durationMs: undefined } | null | undefined> {
+    return this.guard(this.download(hash))
+  }
+
+  private async download(
+    hash: string,
+  ): Promise<{ body: Response; durationMs: undefined } | null | undefined> {
     this.sayUnsaid()
     const at = this.found.get(hash)
-    for (const scope of at === undefined ? this.refs.map(scopeOf) : [at]) {
-      if (this.disabled) return null
+    const scopes = at === undefined ? this.scopes : [at]
+    for (let next = 0; next < scopes.length;) {
+      // Off, or refused: no answer, which core keeps apart from a miss (a
+      // null forgot each hit the index kept, the remote never asked).
+      if (this.disabled) return undefined
+      const some = scopes.slice(next, next + (this.limits?.maxCheckHashes ?? scopes.length))
       const res = await this.request(`/v1/artifacts/${hash}`, {
         method: 'GET',
-        headers: { 'vx-scope': scope },
+        headers: { 'vx-scope': some.join(', ') },
         streamed: true,
       })
-      if (res === undefined) return null
+      if (res === undefined) return undefined
       if (res.status === 404) {
         await res.body?.cancel()
+        next += some.length
         continue
       }
-      if (res.status !== 200) throw await refusal(res)
+      if (res.status !== 200) {
+        // Refused for its scopes: sent again in as many as the refusal names.
+        const max = limitsNamed(res)?.maxCheckHashes
+        if (max !== undefined && some.length > max) {
+          await res.body?.cancel()
+          continue
+        }
+        throw await refusal(res, this.hidden)
+      }
       return { body: res, durationMs: undefined }
     }
     return null
   }
 
   /** An artifact over the server's upload limit is not sent: it is said. */
-  async put(hash: string, body: Blob, _meta: { durationMs: number }): Promise<void | false> {
+  put(
+    hash: string,
+    body: Blob,
+    meta: { durationMs: number; replace?: true },
+  ): Promise<void | false> {
+    return this.guard(this.store(hash, body, meta))
+  }
+
+  private async store(
+    hash: string,
+    body: Blob,
+    meta: { durationMs: number; replace?: true },
+  ): Promise<void | false> {
     // With no token a job reads only: nothing is uploaded, and none counted.
     if (this.disabled || this.writesRefused || !hasCiToken(this.env, this.lent?.() !== undefined))
       return false
-    const max = this.limits?.maxUploadBytes
-    if (max !== undefined && body.size > max) {
-      this.warn(
-        `[vx] vx-cache: ${hash} is ${body.size} bytes, over the server's upload limit of ${max}: not uploaded`,
-      )
+    // The server keeps the bytes a scope holds and answers 204 unread
+    // (PROTOCOL.md): a PUT reported the corrupt copy fixed, so no run (nor
+    // DTE peer) learned it was not, and each one downloaded it again.
+    if (meta.replace === true) {
+      if (!this.saidNoReplace)
+        this.warn(
+          `[vx] vx-cache: ${hash} did not read back, and a vx-cache server never replaces an artifact it holds: not uploaded; the remote misses it until the bucket's lifecycle rule expires it`,
+        )
+      this.saidNoReplace = true
       return false
     }
-    return this.uploads.push({ hash, body })
+    if (this.overLimit(hash, body)) return false
+    return this.upload({ hash, body })
   }
 
-  /** One artifact by `PUT`: the server answers one its scope holds before reading the bytes. */
+  /** Says an artifact over the upload limit the server last named, which is not sent. */
+  private overLimit(hash: string, body: Blob): boolean {
+    const max = this.limits?.maxUploadBytes
+    if (max === undefined || body.size <= max) return false
+    this.warn(
+      `[vx] vx-cache: ${hash} is ${body.size} bytes, over the server's upload limit of ${max}: not uploaded`,
+    )
+    return true
+  }
+
+  /**
+   * One artifact by `PUT`, its bytes reaching the bucket untouched
+   * (2026-10-25: no batch upload; a batch passes through the server's code,
+   * which on Workers costs CPU by the byte, and a 40 MB one ran out of it).
+   * The server answers one its scope holds before reading the bytes. As
+   * many at once as core sends (`cache.concurrency.upload`): a cap of four
+   * here held a 1,500-task cold run 11 s past its last task on a remote
+   * 40 ms away, the setting unheard.
+   */
   private async upload(item: { hash: string; body: Blob }): Promise<void | false> {
     // Queued before the remote or its writes were turned off.
     if (this.disabled || this.writesRefused) return false
@@ -832,14 +884,39 @@ export class VxCacheLayer implements RemoteCacheLayer {
       }
       if (res === undefined) return false
       if (res.ok) return
+      // Sent before any answer named the limits: the 413 names them
+      // (PROTOCOL.md), so it is said as a later one is, never a failure.
+      if (res.status === 413 && this.overLimit(item.hash, item.body)) {
+        await res.body?.cancel()
+        return false
+      }
       if ((res.status !== 429 && res.status < 500) || attempt === ASK_ATTEMPTS)
-        throw await refusal(res)
+        throw await refusal(res, this.hidden)
       await res.body?.cancel()
       await this.wait(1000 * attempt)
     }
   }
 }
 
+/**
+ * `Promise.all` that ends only once every check has: a refused chunk
+ * rejected the lookup while its siblings were still in flight, so their
+ * requests outlived the call that sent them.
+ */
+async function settledAll<T>(ps: readonly Promise<T>[]): Promise<T[]> {
+  const done = await Promise.allSettled(ps)
+  const failed = done.find((r) => r.status === 'rejected')
+  if (failed !== undefined) throw failed.reason
+  return done.map((r) => (r as PromiseFulfilledResult<T>).value)
+}
+
+/** A check refused for its size: sent again in checks of `max` lookups. */
+class TooMany extends Error {
+  constructor(readonly max: number) {
+    super(`a check is at most ${max} lookups`)
+  }
+}
+
 /** The issuer and repository as a key names them: the issuer's URL with no trailing slash, `org/name` lowercased. */
 function namedOf(options: VxCacheOptions): { issuer: string; repository: string } {
   const { issuer, repository } = options as Partial<VxCacheOptions>
@@ -865,10 +942,12 @@ function shown(url: string): string {
  * http:// to another host sent it in clear.
  */
 function secure(url: string): boolean {
-  if (/^https:\/\/\S/.test(url)) return true
-  if (!/^http:\/\/\S/.test(url)) return false
-  const host = URL.parse(url)?.hostname
-  return host === '127.0.0.1' || host === '[::1]' || host === 'localhost'
+  // Parsed as the request will be: a scheme in any case, no url it cannot carry.
+  const u = URL.parse(url)
+  if (u === null || u.host === '') return false
+  if (u.protocol === 'https:') return true
+  if (u.protocol !== 'http:') return false
+  return u.hostname === '127.0.0.1' || u.hostname === '[::1]' || u.hostname === 'localhost'
 }
 
 /** Options over `VX_CACHE_URL`; `undefined`: no server named. */
@@ -885,6 +964,12 @@ export function resolveVxCacheConfig(
     throw new UserError(
       `vxCache(): ${from} must be https (http only to 127.0.0.1, ::1 or localhost), got ${shown(url)}`,
     )
+  // Each route is appended to the url: past a `?` or `#` it was query or
+  // fragment, and every request asked the server's root.
+  if (/[?#]/.test(url))
+    throw new UserError(
+      `vxCache(): ${from} takes no ?query or #fragment: each route is appended to it, got ${shown(url)}`,
+    )
   // Each route is the url's /v1/…: one that names /v1 asked /v1/v1/…, and every answer was a 404.
   if (url.endsWith('/v1'))
     throw new UserError(