@vzn/vx-migrate 0.0.644 → 0.0.645

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vx contributors
+Copyright (c) 2026 VZN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -564,6 +564,7 @@ Every option falls back to the tool's own environment variable, so a self-hosted
 | `uploadTimeoutMs` | `TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT`, then `remoteCache.uploadTimeout` (seconds)                                                          | PUT deadline (default 60 s; 0 none)                                                                                                                                                                                                                                           |
 | `retries`         | —                                                                                                                                        | resends of a request answered 5xx (not 501) or never connected (default 1, Turbo's); a 429 waits out the limit; 0 turns both off                                                                                                                                              |
 | `preflight`       | `TURBO_PREFLIGHT` (1 or 0), then `remoteCache.preflight`                                                                                 | send Turbo's `OPTIONS` preflight before each artifact request and go where its `Location` points (relative to `apiUrl`); the token goes along only when the API's `Access-Control-Allow-Headers` admits `Authorization`; a redirected preflight is not followed (default off) |
+| `scope`           | —                                                                                                                                        | `RemoteScope`: `'header'` (default): every read names the run's refs, own branch first, in `x-artifact-read-scopes`; `'key'`: each entry is keyed on its ref, a read asks every ref's key in one batch (a server that ignores the header)                                     |
 
 The signature is Turbo's current scheme (`artifact-signature:v2`: prefix, hash, team id and body, each length-prefixed, under HMAC-SHA256, base64 in `x-artifact-tag`). A signed body is written to a temp file before its tag can be checked, so one past core's artifact ceiling (2 GiB, at zstd's bound) is refused as it passes it, and is a miss.
 
@@ -620,7 +621,7 @@ With no token from an option, a variable or a config file, both plugins read the
 
 ## Remote-cache behaviour (both)
 
-- Every request (`HEAD`, `GET`, `PUT`, the batch `POST`) carries `x-vx-cache-scope`: `trusted` for a task's own key, else the branch scope its key was derived in (`acme/app:feat-x`). The key is the same either way. A server that keeps one bucket per scope uses it to skip its own layering; whether a write to `trusted` is allowed stays the server's call, from the token (a CI ID token). A request without the header, from an older client, leaves the layering to the server. A batch that mixes scopes is one `POST` per scope.
+- Task keys carry no branch. `turboCache()` names the run's refs on every read (`HEAD`, `GET`, the batch `POST`) in `x-artifact-read-scopes`, own branch first (`refs/heads/feat-x, refs/heads/main`): from CI's env, else git's current branch, then the default branch. A `PUT` names none: where a write lands is the server's call, from the CI OIDC token checked against its trust policy. `scope: 'key'` folds the ref into each key instead, for a server that ignores the header. `nxCache()` sends plain requests. How a server implements the header: [Branch caches a server enforces](https://vznjs.github.io/vx/blog/branch-caches-a-server-enforces/).
 - A remote error degrades to a **miss** and a warning that names the request, the artifact and the server — `[vx] plugin '@vzn/vx-migrate': upload 32248a2a7c89e241 to https://cache.example.com/v8/artifacts failed: no answer within 60000 ms` — never the token. The run never fails because of the cache.
 - The same failure is said once per run: an unreachable server fails the probe, the download and the upload alike, and the run prints the first and, at its end, `[vx] plugin '@vzn/vx-migrate': 2 more requests failed the same way: Unable to connect. Is the computer able to access the url?` (core does the counting, for every cache plugin).
 - A request answered `5xx` (not `501`), or one that never connected (a refused port, an unresolved host), is sent again after 2 s, `retries` times. A `429` pauses every request to that remote for its `Retry-After` (capped at 10 s a wait, 2 s without one), and the request is sent again when the pause ends, for up to 20 s from its first `429`, as Turbo's client does. A spent deadline is not resent: it has already cost its wait.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-migrate",
-  "version": "0.0.644",
+  "version": "0.0.645",
   "license": "MIT",
   "description": "Adopt @vzn/vx from Turborepo, Nx or package.json scripts: run the repo unchanged, migrate it to vx.config.ts, and keep your Turbo or Nx remote cache",
   "keywords": [
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.644"
+    "@vzn/vx": "^0.0.645"
   },
   "repository": {
     "type": "git",

package/src/nx-cache/index.ts

@@ -14,14 +14,12 @@
 import {
   definePlugin,
   type RemoteCacheLayer,
-  type RemoteKey,
   type RemoteOpenContext,
   type VxPlugin,
   refuseUnknownOptions,
   type PluginOptionKinds,
 } from '@vzn/vx'
 import { deadline } from '../remote-deadline.js'
-import { scopeHeader } from '../remote-scope.js'
 import { OutageBreaker } from '../remote-breaker.js'
 import { Cooldown, withRetry } from '../remote-retry.js'
 import {
@@ -155,11 +153,10 @@ export class NxRemoteCache implements RemoteCacheLayer {
   private async request(
     method: 'GET' | 'PUT',
     hash: string,
-    at: RemoteKey | undefined,
     body?: Blob,
   ): Promise<Response | undefined> {
     if (this.token === undefined) return undefined
-    const headers: Record<string, string> = scopeHeader(at)
+    const headers: Record<string, string> = {}
     if (this.token !== '') headers['Authorization'] = `Bearer ${this.token}`
     if (body !== undefined) {
       headers['Content-Type'] = 'application/octet-stream'
@@ -212,18 +209,15 @@ export class NxRemoteCache implements RemoteCacheLayer {
     return res
   }
 
-  async get(
-    hash: string,
-    at?: RemoteKey,
-  ): Promise<{ body: Response; durationMs: number | undefined } | null> {
-    const res = await this.fetch(hash, at)
+  async get(hash: string): Promise<{ body: Response; durationMs: number | undefined } | null> {
+    const res = await this.fetch(hash)
     // The Nx wire carries no producing-task duration.
     return res === null ? null : { body: res, durationMs: undefined }
   }
 
-  private async fetch(hash: string, at: RemoteKey | undefined): Promise<Response | null> {
+  private async fetch(hash: string): Promise<Response | null> {
     if (this.disabled) return null
-    const res = await this.request('GET', hash, at)
+    const res = await this.request('GET', hash)
     if (res === undefined) return null
     if (res.status !== 200) {
       await res.body?.cancel()
@@ -233,17 +227,18 @@ export class NxRemoteCache implements RemoteCacheLayer {
     return res
   }
 
-  async has(hash: string, at?: RemoteKey): Promise<boolean> {
-    const res = await this.fetch(hash, at)
-    if (res === null) return false
+  async has(hash: string): Promise<{ size?: number } | null> {
+    const res = await this.fetch(hash)
+    if (res === null) return null
     await res.body?.cancel()
-    return true
+    const size = Number(res.headers.get('content-length') ?? NaN)
+    return Number.isFinite(size) ? { size } : {}
   }
 
-  // Nx's record carries no duration; only `meta`'s scope is sent.
-  async put(hash: string, body: Blob, meta: { durationMs: number } & RemoteKey): Promise<void> {
+  // Nx's record carries no duration.
+  async put(hash: string, body: Blob): Promise<void> {
     if (this.disabled || this.writesRefused) return
-    const res = await this.request('PUT', hash, meta, body)
+    const res = await this.request('PUT', hash, body)
     if (res === undefined) return
     if (res.status === 200 || res.status === 202 || res.status === 409) return
     throw new Error(`HTTP ${res.status}`)

package/src/turbo-cache/index.ts

@@ -16,16 +16,16 @@ import { unlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import {
+  type ArtifactInfo,
   definePlugin,
   type RemoteCacheLayer,
-  type RemoteKey,
   type RemoteOpenContext,
   type VxPlugin,
   refuseUnknownOptions,
   type PluginOptionKinds,
 } from '@vzn/vx'
 import { deadline } from '../remote-deadline.js'
-import { scopeHeader } from '../remote-scope.js'
+import { keyedByRef, readScopes, remoteScope, type RemoteScope } from './scope.js'
 import { OutageBreaker } from '../remote-breaker.js'
 import { Cooldown, withRetry } from '../remote-retry.js'
 import {
@@ -82,6 +82,14 @@ export interface TurboCacheOptions {
    * `remoteCache.preflight`; default off.
    */
   preflight?: boolean
+  /**
+   * How branches stay apart (default `'header'`): every read names the run's
+   * refs in `x-artifact-read-scopes`, for a server that files writes by the
+   * CI token. `'key'` also folds the run's ref into each key and reads each
+   * ref's key in order, for a server that ignores the header. The server's
+   * OIDC policy alone decides where a write lands.
+   */
+  scope?: RemoteScope
 }
 
 /** turbo.json's `remoteCache` block: the source below Turbo's environment, as in Turbo. */
@@ -128,6 +136,17 @@ export const MIN_SIGNATURE_KEY_LENGTH = 32
 // Bun's own hasher and the global `crypto`, not `node:crypto`: importing that
 // module cost every `@vzn/vx-migrate` user 6.6 ms at startup, remote cache
 // or not (G-121).
+/** A size and a duration as the wire spells them (a header string, a JSON number), kept when they are counts. */
+function infoOf(size: unknown, durationMs: unknown): ArtifactInfo {
+  const count = (v: unknown): number | undefined => {
+    const n = typeof v === 'string' && v !== '' ? Number(v) : v
+    return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : undefined
+  }
+  const s = count(size)
+  const d = count(durationMs)
+  return { ...(s === undefined ? {} : { size: s }), ...(d === undefined ? {} : { durationMs: d }) }
+}
+
 function updateLength(mac: Bun.CryptoHasher, byteLength: number): void {
   const len = Buffer.alloc(8)
   len.writeBigUInt64LE(BigInt(byteLength))
@@ -450,6 +469,8 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   private readonly keychainRemote: KeychainRemote
   /** The remote's rate limit, which every request of this client waits out. */
   private readonly cooldown = new Cooldown()
+  /** Headers every read carries: the refs it may be answered from (`readScopes`). */
+  reads: Record<string, string> = {}
   constructor(
     private readonly config: TurboCacheConfig,
     private readonly fetchImpl: typeof fetch = fetch,
@@ -616,41 +637,26 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     await revokeOidc(this.config.oidc!, token, this.fetchImpl, this.wait)
   }
 
-  async has(hash: string, at?: RemoteKey): Promise<boolean> {
-    if (this.disabled) return false
-    const res = await this.request('HEAD', `/${hash}`, { headers: scopeHeader(at) })
-    if (res === undefined) return false
-    if (res.status === 200) return true
+  async has(hash: string): Promise<ArtifactInfo | null> {
+    if (this.disabled) return null
+    const res = await this.request('HEAD', `/${hash}`, { headers: this.reads })
+    if (res === undefined) return null
+    if (res.status === 200)
+      return infoOf(res.headers.get('content-length'), res.headers.get('x-artifact-duration'))
     if (res.status === 404) {
       this.absent.add(hash)
-      return false
+      return null
     }
     throw new Error(`HTTP ${res.status}`)
   }
 
-  async hasMany(hashes: readonly string[], at?: readonly RemoteKey[]): Promise<Set<string> | null> {
-    if (this.disabled || hashes.length === 0) return this.disabled ? new Set() : null
-    // One query names one scope, so a batch asks once per scope in it.
-    const byScope = new Map<string | undefined, string[]>()
-    hashes.forEach((h, i) => {
-      const scope = at?.[i]?.scope
-      byScope.set(scope, [...(byScope.get(scope) ?? []), h])
-    })
-    const held = new Set<string>()
-    for (const [scope, group] of byScope) {
-      const found = await this.queryHeld(group, scope === undefined ? {} : { scope })
-      if (found === null) return null
-      for (const h of found) held.add(h)
-    }
-    return held
-  }
-
-  private async queryHeld(hashes: readonly string[], at: RemoteKey): Promise<Set<string> | null> {
+  async hasMany(hashes: readonly string[]): Promise<Map<string, ArtifactInfo> | null> {
+    if (this.disabled || hashes.length === 0) return this.disabled ? new Map() : null
     const res = await this.request('POST', '', {
       body: JSON.stringify({ hashes }),
-      headers: { 'Content-Type': 'application/json', ...scopeHeader(at) },
+      headers: { 'Content-Type': 'application/json', ...this.reads },
     })
-    if (res === undefined) return new Set()
+    if (res === undefined) return new Map()
     if (res.status !== 200) return null
     // An answer per hash is a few hundred bytes of ArtifactInfo; a reply
     // past this bound is no answer, read no further than the bound (L-9).
@@ -661,25 +667,24 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     // Each hash answers ArtifactInfo, null, or `{ error: { message } }`; an
     // error entry is not a stored artifact, and it was counted as one (a GET
     // spent on a 404, item 929).
-    const held = new Set(
-      hashes.filter((h) => {
-        const v = info[h]
-        return typeof v === 'object' && v !== null && !('error' in v)
-      }),
-    )
-    for (const h of hashes) if (!held.has(h)) this.absent.add(h)
+    const held = new Map<string, ArtifactInfo>()
+    for (const h of hashes) {
+      const v = info[h]
+      if (typeof v !== 'object' || v === null || 'error' in v) this.absent.add(h)
+      else {
+        const { size, taskDurationMs } = v as { size?: unknown; taskDurationMs?: unknown }
+        held.set(h, infoOf(size, taskDurationMs))
+      }
+    }
     return held
   }
 
-  async get(
-    hash: string,
-    at?: RemoteKey,
-  ): Promise<{ body: Response; durationMs: number | undefined } | null> {
+  async get(hash: string): Promise<{ body: Response; durationMs: number | undefined } | null> {
     if (this.disabled) return null
     // A gateway that keys binary media on Accept base64-encodes a `*/*`
     // response, and every hit read as a corrupt artifact (nx#33092's class).
     const res = await this.request('GET', `/${hash}`, {
-      headers: { Accept: 'application/octet-stream', ...scopeHeader(at) },
+      headers: { Accept: 'application/octet-stream', ...this.reads },
     })
     if (res === undefined) return null
     if (res.status !== 200) {
@@ -737,14 +742,14 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     return new Response(unlinkingStream(temp))
   }
 
-  async put(hash: string, body: Blob, meta: { durationMs: number } & RemoteKey): Promise<void> {
+  async put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void> {
     if (this.disabled || this.writesRefused) return
     if (!this.absent.has(hash)) {
       // Part of the upload, so under its deadline. Any answer but 200 or 404
       // uploads: a lost store costs more. A server the HEAD cannot reach
       // fails the put, as the PUT would.
       const head = await this.request('HEAD', `/${hash}`, {
-        headers: scopeHeader(meta),
+        headers: this.reads,
         timeoutMs: this.config.uploadTimeoutMs,
       })
       if (head === undefined || head.status === 200) return
@@ -754,7 +759,6 @@ export class TurboRemoteCache implements RemoteCacheLayer {
       'Content-Type': 'application/octet-stream',
       'Content-Length': String(body.size),
       'x-artifact-duration': String(Math.max(0, Math.round(meta.durationMs))),
-      ...scopeHeader(meta),
     }
     if (this.key !== undefined) {
       headers['x-artifact-tag'] = await artifactTag(this.key, hash, this.config.teamId ?? '', body)
@@ -824,6 +828,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
   retries: 'number',
   preflight: 'boolean',
   oidc: 'any',
+  scope: 'string',
 }
 
 /**
@@ -837,6 +842,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
  */
 export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
   refuseUnknownOptions('turboCache()', options, TURBO_CACHE_KEYS)
+  const scope = remoteScope('turbo-cache', options.scope)
   // The run's layer and warn, for `teardown` to revoke an exchanged token.
   let opened: { layer: TurboRemoteCache; warn: (m: string) => void } | undefined
   return definePlugin(import.meta, {
@@ -852,8 +858,9 @@ export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
       // cache directory, which the sandbox walls, not the shared temp dir a
       // sandboxed task may read (L-45).
       const layer = new TurboRemoteCache(config, fetch, ctx.cacheDir)
+      layer.reads = readScopes(ctx.refs)
       if (config.oidc !== undefined) opened = { layer, warn: ctx.warn }
-      return layer
+      return scope === 'key' ? keyedByRef(layer, ctx.refs) : layer
     },
     async teardown() {
       const run = opened

package/src/turbo-cache/scope.ts

@@ -0,0 +1,89 @@
+import type { ArtifactInfo, RemoteCacheLayer } from '@vzn/vx'
+
+/**
+ * How a remote keeps branches apart (2026-10-20). `'header'`: plain keys,
+ * and every read names the refs it may be answered from, in order, in
+ * `x-artifact-read-scopes`; a server that files writes by the caller's CI
+ * token reads them, any other ignores it. `'key'`: each entry's key also
+ * folds a ref, for a server that keeps one bucket; a read asks each ref's
+ * key and the first hit wins.
+ */
+export type RemoteScope = 'header' | 'key'
+
+export function remoteScope(name: string, scope: unknown): RemoteScope {
+  if (scope === undefined || scope === 'header' || scope === 'key') return scope ?? 'header'
+  throw new Error(`vx/${name}: scope must be 'header' or 'key', got ${JSON.stringify(scope)}`)
+}
+
+/** A server caps the read header at this many refs (the server rules), so vx never sends more. */
+const MAX_READ_SCOPES = 8
+
+/** The read header: the refs in order. Writes carry none: the server files them by the token. */
+export function readScopes(refs: readonly string[]): Record<string, string> {
+  return refs.length === 0
+    ? {}
+    : { 'x-artifact-read-scopes': refs.slice(0, MAX_READ_SCOPES).join(', ') }
+}
+
+/** The key `ref` stores `hash` under: 16 hex, task-key shaped, so every wire takes it. */
+export function refKey(ref: string, hash: string): string {
+  return Bun.hash.xxHash3(`vx-cache-ref\0${ref}\0${hash}`).toString(16).padStart(16, '0')
+}
+
+const QUEUE = /^refs\/heads\/gh-readonly-queue\//
+
+/**
+ * `inner` keyed by ref: a write lands under the run's own ref's key (a
+ * merge queue's, its base branch's, which its results become), a read asks
+ * each ref's key in order. A merge queue's own ref holds nothing, so it is
+ * never asked.
+ */
+export function keyedByRef(inner: RemoteCacheLayer, allRefs: readonly string[]): RemoteCacheLayer {
+  const refs = QUEUE.test(allRefs[0] ?? '') ? allRefs.slice(1) : allRefs
+  const write = refs[0]
+  if (write === undefined) return inner
+  /** Task key → the stored key a batch probe found it under. */
+  const found = new Map<string, string>()
+  const hasMany = inner.hasMany
+  const firstHeld = async (hash: string): Promise<ArtifactInfo | null> => {
+    const known = found.get(hash)
+    if (known !== undefined) return inner.has(known)
+    for (const ref of refs) {
+      const info = await inner.has(refKey(ref, hash))
+      if (info !== null) return info
+    }
+    return null
+  }
+  return {
+    ...(inner.endpoint !== undefined ? { endpoint: inner.endpoint } : {}),
+    ...(inner.open !== undefined ? { open: (ctx) => inner.open!(ctx) } : {}),
+    has: firstHeld,
+    ...(hasMany !== undefined
+      ? {
+          hasMany: async (hashes) => {
+            const keys = hashes.map((h) => refs.map((r) => refKey(r, h)))
+            const held = await hasMany.call(inner, keys.flat())
+            if (held === null) return null
+            const out = new Map<string, ArtifactInfo>()
+            hashes.forEach((h, i) => {
+              const key = keys[i]!.find((k) => held.has(k))
+              if (key === undefined) return
+              found.set(h, key)
+              out.set(h, held.get(key)!)
+            })
+            return out
+          },
+        }
+      : {}),
+    get: async (hash) => {
+      const known = found.get(hash)
+      if (known !== undefined) return inner.get(known)
+      for (const ref of refs) {
+        const hit = await inner.get(refKey(ref, hash))
+        if (hit !== null) return hit
+      }
+      return null
+    },
+    put: (hash, body, meta) => inner.put(refKey(write, hash), body, meta),
+  }
+}

package/src/remote-scope.ts

@@ -1,12 +0,0 @@
-import type { RemoteKey } from '@vzn/vx'
-
-/**
- * The bucket a request means (owner, 2026-10-18): `trusted` for a task's
- * own key, else the branch scope its key was derived in. It only states
- * intent; a server checks it against the caller's identity (a CI ID
- * token). A request without it, from an older client, leaves the layering
- * to the server. Shared by `turboCache()` and `nxCache()`.
- */
-export function scopeHeader(at: RemoteKey | undefined): Record<string, string> {
-  return { 'x-vx-cache-scope': at?.scope ?? 'trusted' }
-}