@vzn/vx-migrate 0.0.644 → 0.0.646

package/src/turbo-cache/index.ts

@@ -16,16 +16,17 @@ import { unlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import {
+  type ArtifactInfo,
   definePlugin,
+  type LentAccess,
   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 +83,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 +137,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))
@@ -409,6 +429,9 @@ async function boundedText(res: Response, max: number): Promise<string | null> {
  */
 const MAX_SIGNED_BODY = 2 * 1024 ** 3 + ((2 * 1024 ** 3) >> 8) + 64 * 1024
 
+/** A lent token ending sooner than this is exchanged again first, so an agent's request never carries a spent one. */
+const LEND_MARGIN_MS = 5 * 60_000
+
 /**
  * The seam implementation: `has` is HEAD, `hasMany` is the batch query,
  * `get`/`put` carry `x-artifact-duration` (and the tag when signing). An
@@ -445,11 +468,19 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   private token: string | undefined
   /** Set by `open` when the token came from the keychain: a refusal deletes it. */
   private forget: (() => Promise<void>) | undefined
-  /** The token an OIDC exchange gave, revoked when the run ends. */
-  private exchanged: string | undefined
+  /** The tokens OIDC exchanges gave, the last one current, each revoked when the run ends. */
+  private exchanged: string[] = []
+  /** When the current exchanged token ends (epoch ms), when the server said. */
+  private expiresAt: number | undefined
+  /** Set by `open` when this machine has a lent token and no token of its own: read per request. */
+  private borrowed: (() => string | undefined) | undefined
+  /** The token a run running its tasks here lent (`CacheContext.lent`). */
+  lent: (() => string | undefined) | undefined
   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,
@@ -470,26 +501,59 @@ export class TurboRemoteCache implements RemoteCacheLayer {
   }
 
   async open(ctx: RemoteOpenContext): Promise<void> {
-    if (this.config.oidcMissing)
+    const lent = this.lent?.() === undefined ? undefined : this.lent
+    if (this.config.oidcMissing && lent === undefined)
       ctx.warn(
         'oidc: GitHub gave this job no OIDC token: it needs `permissions: id-token: write` (a fork or Dependabot pull request never gets one)',
       )
     if (this.token !== undefined) return
+    // A lent token beats this machine's own OIDC: the server files a write
+    // by the token, so an agent's own (another workflow, another ref)
+    // filed the task where its run could not read it.
+    if (lent !== undefined) {
+      this.borrowed = lent
+      return
+    }
     if (this.config.oidc !== undefined) {
       try {
-        this.token = await exchangeOidc(this.config.oidc, this.fetchImpl, this.wait)
+        await this.exchange()
       } catch (err) {
         throw new Error(
           `oidc: ${err instanceof Error ? err.message : String(err)}; local cache only this run`,
         )
       }
-      this.exchanged = this.token
       return
     }
     this.token = await keychainToken(ctx, this.keychainRemote)
     this.forget = () => ctx.forgetSecret({ key: this.keychainRemote.key })
   }
 
+  private async exchange(): Promise<void> {
+    const got = await exchangeOidc(this.config.oidc!, this.fetchImpl, this.wait)
+    this.token = got.token
+    this.expiresAt = got.expiresAt
+    this.exchanged.push(got.token)
+  }
+
+  /**
+   * The token an OIDC exchange gave this run, for a machine that runs its
+   * tasks (`RemoteCacheLayer.lend`); exchanged again when it ends within
+   * five minutes. A token of any other kind is never lent.
+   */
+  async lend(): Promise<LentAccess | undefined> {
+    if (this.exchanged.length === 0) return undefined
+    if (this.expiresAt !== undefined && this.expiresAt - Date.now() < LEND_MARGIN_MS)
+      await this.exchange()
+    return {
+      token: this.token!,
+      ...(this.expiresAt === undefined ? {} : { expiresAt: this.expiresAt }),
+    }
+  }
+
+  private bearer(): string | undefined {
+    return this.borrowed?.() ?? this.token
+  }
+
   private url(pathname: string): string {
     const u = new URL(`${this.config.apiUrl}/v8/artifacts${pathname}`)
     // Turbo sends a team id only in Vercel's `team_` form (its API client's
@@ -502,7 +566,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
 
   private headers(extra: Record<string, string> = {}, auth = true): Record<string, string> {
     return {
-      ...(auth ? { Authorization: `Bearer ${this.token}` } : {}),
+      ...(auth ? { Authorization: `Bearer ${this.bearer()}` } : {}),
       'x-artifact-client-interactive': process.stdout.isTTY ? '1' : '0',
       ...extra,
     }
@@ -529,7 +593,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     const res = await this.fetchImpl(url, {
       method: 'OPTIONS',
       headers: {
-        Authorization: `Bearer ${this.token}`,
+        Authorization: `Bearer ${this.bearer()}`,
         'Access-Control-Request-Method': method === 'HEAD' ? 'GET' : method,
         'Access-Control-Request-Headers': ['Authorization', ...Object.keys(headers)].join(', '),
       },
@@ -558,7 +622,7 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     pathname: string,
     init: { body?: Blob | string; headers?: Record<string, string>; timeoutMs?: number } = {},
   ): Promise<Response | undefined> {
-    if (this.token === undefined) return undefined
+    if (this.bearer() === undefined) return undefined
     const timeoutMs = init.timeoutMs ?? this.config.timeoutMs
     // 0 is Turbo's "no deadline".
     const signal = () => (timeoutMs === 0 ? undefined : deadline(timeoutMs))
@@ -608,49 +672,33 @@ export class TurboRemoteCache implements RemoteCacheLayer {
     return res
   }
 
-  /** Revoke the token `open` exchanged, once; a throw is the caller's warning. */
+  /** Revoke each token this run exchanged, once; a throw is the caller's warning. */
   async revoke(): Promise<void> {
-    const token = this.exchanged
-    if (token === undefined) return
-    this.exchanged = undefined
-    await revokeOidc(this.config.oidc!, token, this.fetchImpl, this.wait)
+    const tokens = this.exchanged.splice(0)
+    for (const token of tokens)
+      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 +709,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 +784,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 +801,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 +870,7 @@ const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
   retries: 'number',
   preflight: 'boolean',
   oidc: 'any',
+  scope: 'string',
 }
 
 /**
@@ -837,6 +884,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 +900,10 @@ 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)
+      layer.lent = ctx.lent
       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/oidc.ts

@@ -111,12 +111,18 @@ async function field(res: Response, name: string, what: string): Promise<string>
   return value
 }
 
+/** An exchanged token, and when it ends (epoch ms) when the server says. */
+export interface Exchanged {
+  readonly token: string
+  readonly expiresAt?: number
+}
+
 /** The job's OIDC token, exchanged for the cache's access token. Errors never quote a token. */
 export async function exchangeOidc(
   cfg: OidcConfig,
   fetchImpl: typeof fetch = fetch,
   wait: (ms: number) => Promise<void> = Bun.sleep,
-): Promise<string> {
+): Promise<Exchanged> {
   const idUrl = new URL(cfg.idTokenUrl)
   if (cfg.audience !== undefined) idUrl.searchParams.set('audience', cfg.audience)
   const idToken = await field(
@@ -129,22 +135,31 @@ export async function exchangeOidc(
     'value',
     `GitHub's OIDC endpoint (${where(cfg.idTokenUrl)})`,
   )
-  return field(
-    await send(
-      fetchImpl,
-      cfg.tokenUrl,
-      form({
-        grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
-        subject_token: idToken,
-        subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
-        requested_token_type: 'urn:ietf:params:oauth:token-type:access_token',
-        ...cfg.params,
-      }),
-      wait,
-    ),
-    'access_token',
-    `the token exchange (${where(cfg.tokenUrl)})`,
+  const res = await send(
+    fetchImpl,
+    cfg.tokenUrl,
+    form({
+      grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+      subject_token: idToken,
+      subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
+      requested_token_type: 'urn:ietf:params:oauth:token-type:access_token',
+      ...cfg.params,
+    }),
+    wait,
   )
+  const what = `the token exchange (${where(cfg.tokenUrl)})`
+  if (!res.ok) {
+    await res.body?.cancel()
+    throw new Error(`${what} answered HTTP ${res.status}`)
+  }
+  const body = (await res.json().catch(() => null)) as Record<string, unknown> | null
+  const token = body?.['access_token']
+  if (typeof token !== 'string' || token === '') throw new Error(`${what} sent no access_token`)
+  const ttl = body?.['expires_in']
+  return {
+    token,
+    ...(typeof ttl === 'number' && ttl > 0 ? { expiresAt: Date.now() + ttl * 1000 } : {}),
+  }
 }
 
 /** Revoke the exchanged token; a throw is the caller's warning. */

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' }
-}