@vzn/vx 0.0.641 → 0.0.643

package/src/cache/layer.ts

@@ -576,6 +576,8 @@ export interface CacheLayer {
    * `hasRemote`.
    */
   probeBeforeUpload?(hashes: Promise<readonly string[]>): void
+  /** `taskId`'s key is `hash`: a scoped run picks each remote key by its task (`BranchScope`). */
+  noteKey?(taskId: string, hash: string): void
   /**
    * Resolve once every background write-through upload settles. The
    * orchestrator awaits it before `close()` — an upload reading layer state
@@ -698,6 +700,8 @@ export interface CacheLayer {
     entry: Omit<CacheEntry, 'hash' | 'storedAt' | 'outputFiles' | 'exitCode'>
     projectDir: string
     outputFiles: string[]
+    /** The empty directories under the outputs (absolute), kept so a hit makes them. */
+    outputDirs?: string[]
     /**
      * Resolved `outputs.workspaceFiles` (absolute paths) + the root
      * they're relative to. Packed under `workspace-outputs/<rel>`.
@@ -714,12 +718,6 @@ export interface CacheLayer {
      * Only computed on the miss/save path — never on a hit.
      */
     inputComponents?: readonly TaskInputRow[]
-    /**
-     * For a sandboxed task: whether it could read a canonical path. A
-     * symlinked output is packed as its target's bytes, outside the
-     * sandbox, so one whose target the task could not read is refused.
-     */
-    readable?: ((real: string) => boolean) | undefined
   }): Promise<void>
   /**
    * Adopt an artifact produced elsewhere — the remote-hit path. Streams

package/src/cache/layered-cache.ts

@@ -36,6 +36,55 @@ import type {
 } from './cache.js'
 import type { OutputDirRow } from './cache.js'
 import { RemoteLane, type ResolvedRemote } from './remote-lane.js'
+import type { BranchScope } from './scoped-cache.js'
+import type { PluginSecrets } from '../util/index.js'
+
+const STOPPED: unique symbol = Symbol('stopped')
+
+/**
+ * A response body that errors once the run stops, so the ingest reading it
+ * fails at once, removes its temp, and releases the connection; the cache
+ * then closes under no write.
+ */
+function endsOnStop(body: Blob | Response, stopped: Promise<typeof STOPPED>): Blob | Response {
+  if (body instanceof Blob || body.body === null) return body
+  const reader = body.body.getReader()
+  let stop = false
+  // Once, not raced per chunk: a cancel ends the pending read as `done`,
+  // which the flag turns into an error rather than a short body.
+  void stopped.then(() => {
+    stop = true
+    void reader.cancel().catch(() => undefined)
+  })
+  const stream = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const next = await reader.read()
+      if (stop) controller.error(new Error('the run was stopped'))
+      else if (next.done) controller.close()
+      else controller.enqueue(next.value)
+    },
+    cancel: (reason) => reader.cancel(reason),
+  })
+  return new Response(stream, { headers: body.headers })
+}
+
+/** What a remote's `open` is handed: the run's CI verdict and its plugin's keychain. */
+export interface RemoteOpenContext extends PluginSecrets {
+  /** The run is on CI: nobody may be asked. */
+  readonly ci: boolean
+  /** One line naming the plugin, for a fact that leaves the remote on. */
+  warn(message: string): void
+}
+
+/**
+ * Where a remote call's key lives: `scope` names the branch scope a scoped
+ * key was derived in (`scopedKey`), absent for a task's own key. The key
+ * alone is enough; a backend that keeps one store per scope may use it to
+ * go straight to that store. turboCache(), nxCache() and vx-reapi ignore it.
+ */
+export interface RemoteKey {
+  readonly scope?: string
+}
 
 /**
  * What a remote cache layer must provide — THE plugin seam for remote
@@ -62,17 +111,28 @@ export interface RemoteCacheLayer {
    * dropped before it is printed.
    */
   readonly endpoint?: string
+  /**
+   * Optional: make the layer ready (read a credential, ask for one).
+   * Called once per run, in declared order, before the status line and the
+   * first task, and only when the run's policy lets this remote read or
+   * write: a `--cache-policy=remote:` run, `--no-cache` and a plan
+   * (`--dry`, `vx show`) never call it, so the other methods may be asked
+   * without it. A throw is a warning naming the plugin and turns the
+   * remote off for the run; the run goes on. `ctx.secret` reads the
+   * plugin's keychain and may ask on the terminal.
+   */
+  open?(ctx: RemoteOpenContext): Promise<void>
   /** Existence probe: `--dry` and `--force` ask it per key when the remote cannot batch. */
-  has(hash: string): Promise<boolean>
+  has(hash: string, at?: RemoteKey): Promise<boolean>
   /**
    * Optional batch existence probe: given N hashes, return the subset stored
    * remotely in ONE round-trip. Its presence says the wire can batch: a run
    * asks it once for its keys, `--dry` before its per-key answers, and
    * `--force` in the background to skip uploads of held keys. Without it a
    * run GETs each key directly (no `has`). Never throws for control flow:
-   * `null` means "no batch info; use per-hash".
+   * `null` means "no batch info; use per-hash". `at[i]` is `hashes[i]`'s.
    */
-  hasMany?(hashes: readonly string[]): Promise<Set<string> | null>
+  hasMany?(hashes: readonly string[], at?: readonly RemoteKey[]): Promise<Set<string> | null>
   /**
    * Fetch an artifact; `null` = miss. `body` is read once, by core,
    * straight into the local cache — an HTTP wire returns its `fetch`
@@ -82,7 +142,10 @@ export interface RemoteCacheLayer {
    * nothing and the read is a miss, so a layer can check bytes as they pass
    * (a digest, a signature) and refuse at the end.
    */
-  get(hash: string): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
+  get(
+    hash: string,
+    at?: RemoteKey,
+  ): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
   /**
    * Store an artifact (fire-and-forget from LayeredCache's perspective).
    * `body` is file-backed (`Bun.file`) when the local store holds the
@@ -91,7 +154,7 @@ export interface RemoteCacheLayer {
    * key the remote holds keeps the stored bytes. Core never asks `has`
    * first; a wire that would overwrite checks inside.
    */
-  put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void>
+  put(hash: string, body: Blob, meta: { durationMs: number } & RemoteKey): Promise<void>
 }
 
 export class LayeredCache implements CacheLayer {
@@ -99,7 +162,6 @@ export class LayeredCache implements CacheLayer {
   readonly hasRemote = true
 
   private readonly lanes: readonly RemoteLane[]
-  private readonly readable: readonly RemoteLane[]
 
   /**
    * In-flight remote pulls keyed by hash. `prefetch` and `get` both go
@@ -128,9 +190,21 @@ export class LayeredCache implements CacheLayer {
   constructor(
     readonly local: Cache,
     remotes: readonly ResolvedRemote[],
+    /** The run's branch scope: it picks each remote key; the local store never sees it. */
+    private readonly branch?: BranchScope,
   ) {
-    this.lanes = remotes.map((r) => new RemoteLane(r, local.traffic))
-    this.readable = this.lanes.filter((l) => l.read)
+    this.lanes = remotes.map(
+      (r) => new RemoteLane(r, local.traffic, branch?.remote(r.remote) ?? r.remote),
+    )
+  }
+
+  noteKey(taskId: string, hash: string): void {
+    this.branch?.noteKey(taskId, hash)
+  }
+
+  // Asked, not kept: a remote whose `open` failed leaves the run after this is built.
+  private get readable(): RemoteLane[] {
+    return this.lanes.filter((l) => l.read)
   }
 
   key(input: CacheKeyInput): Promise<string> {
@@ -280,7 +354,17 @@ export class LayeredCache implements CacheLayer {
 
   private async pullFrom(lane: RemoteLane, hash: string, ctx?: CacheGetContext): Promise<boolean> {
     const fetchStart = performance.now()
-    const remoteBody = await lane.get(hash)
+    // A stopped run waits on no read, as on no upload: a lookup or download
+    // in flight held a Ctrl-C until its last byte (M, 2026-10-17). The
+    // plugin's request is left to the exit, and its body is cancelled.
+    const stopped = lane.whenStopped.then((): typeof STOPPED => STOPPED)
+    const pending = lane.get(hash)
+    const remoteBody = await Promise.race([pending, stopped])
+    if (remoteBody === STOPPED) {
+      // A late answer's body would hold its connection to the exit.
+      void pending.then((r) => (r?.body instanceof Response ? r.body.body?.cancel() : undefined))
+      return false
+    }
     if (remoteBody === null) return false
 
     // Ingest the remote body into local using the caller-supplied
@@ -301,7 +385,9 @@ export class LayeredCache implements CacheLayer {
       ...(ctx?.outputs !== undefined ? { outputs: ctx.outputs } : {}),
     }
     try {
-      await this.local.ingest(hash, remoteBody.body, meta)
+      const ingest = this.local.ingest(hash, endsOnStop(remoteBody.body, stopped), meta)
+      ingest.catch(() => undefined)
+      if ((await Promise.race([ingest, stopped])) === STOPPED) return false
     } catch (err) {
       // The bytes came off the network — a corrupt/truncated remote
       // artifact must degrade to a cache miss (task re-executes), not

package/src/cache/output-index.ts

@@ -17,7 +17,8 @@ const FILE_PREFIX_MTIME = -2
 
 import type { Database } from 'bun:sqlite'
 import { inHashes, lazyStatement } from './schema.js'
-import { lstatSync, statSync } from 'node:fs'
+import { modeMatches } from './umask.js'
+import { lstatSync, readlinkSync, statSync } from 'node:fs'
 import { lstat, readdir } from 'node:fs/promises'
 import path from 'node:path'
 import {
@@ -30,6 +31,19 @@ import {
   WORKSPACE_OUTPUT_PREFIX,
 } from './layer.js'
 
+/**
+ * The mode a symlink output's row carries (S_IFLNK): its size is the
+ * target's byte length and its mtime the target's CRC-32.
+ */
+export const LINK_MODE = 0o120000
+
+/** A link row is current while a link with that target stands there; never followed. */
+function linkCurrent(abs: string, e: { size: number; mtimeMs: number }): boolean {
+  if (!lstatSync(abs).isSymbolicLink()) return false
+  const to = readlinkSync(abs, 'buffer')
+  return to.byteLength === e.size && Bun.hash.crc32(to) === e.mtimeMs
+}
+
 export class OutputIndex {
   private readonly insertOutputFile: ReturnType<Database['prepare']>
   private readonly deleteOutputFiles: ReturnType<Database['prepare']>
@@ -206,10 +220,13 @@ export class OutputIndex {
     // graph stage 100 → 54 ms, the whole process 422 → 368 ms.
     const results = expected.map((e) => {
       try {
+        if (e.mode === LINK_MODE) return linkCurrent(path.join(projectDir, e.path), e)
         const s = statSync(path.join(projectDir, e.path))
+        // An empty output directory: current while a directory stands there.
+        if (e.path.endsWith('/')) return s.isDirectory()
         return (
           s.size === e.size &&
-          (s.mode & 0o777) === (e.mode & 0o777) &&
+          modeMatches(s.mode, e.mode) &&
           // MILLISECOND comparison (sub-ms tolerance for the float
           // round-trip through utimes). Save rows carry stat-ms and
           // restoreOutputs re-syncs restored files to the row value,
@@ -324,6 +341,7 @@ export class OutputIndex {
     const rows = this.rowsOf(hash)
     const stamps: Array<[string, number, number]> = []
     for (const e of rows) {
+      if (e.path.endsWith('/') || e.mode === LINK_MODE) continue
       const ws = e.path.startsWith(WORKSPACE_OUTPUT_PREFIX)
       const abs = ws
         ? path.join(workspaceRoot, e.path.slice(WORKSPACE_OUTPUT_PREFIX.length))
@@ -332,7 +350,7 @@ export class OutputIndex {
         const s = statSync(abs)
         if (
           s.size === e.size &&
-          (s.mode & 0o777) === (e.mode & 0o777) &&
+          modeMatches(s.mode, e.mode) &&
           Math.abs(s.mtimeMs - e.mtimeMs) < 1
         ) {
           stamps.push([e.path, s.ino, Math.floor(s.ctimeMs)])
@@ -415,10 +433,13 @@ export class OutputIndex {
     const results = rows.map((r) => {
       let st
       try {
-        st = lstatSync(path.join(projectDir, r.path))
+        // No throw for a missing dir: every restore after a clean asks
+        // about one, and an exception per hit cost more than the stat.
+        st = lstatSync(path.join(projectDir, r.path), { throwIfNoEntry: false })
       } catch {
         return r.mtimeMs === ABSENT_DIR_MTIME
       }
+      if (st === undefined) return r.mtimeMs === ABSENT_DIR_MTIME
       if (r.mtimeMs === ABSENT_DIR_MTIME) return false
       if (r.mtimeMs === FILE_PREFIX_MTIME) return st.isFile()
       return st.isDirectory() && Math.abs(st.mtimeMs - r.mtimeMs) < 1

package/src/cache/plugin-cache.ts

@@ -8,6 +8,7 @@
 
 import type { Database } from 'bun:sqlite'
 import { xxh3hex } from '../util/index.js'
+import type { RemoteKey } from './layered-cache.js'
 import type { CachePolicy } from './policy.js'
 import type { ResolvedRemote } from './remote-lane.js'
 import { scopedKey } from './scoped-cache.js'
@@ -85,13 +86,17 @@ async function capped(body: unknown, max = PLUGIN_ENTRY_MAX_BYTES): Promise<Uint
 }
 
 /**
- * `plugin`'s view of the cache. A scoped run reads the default key, then
- * the scope's, and writes only the scope's, as tasks do (`ScopedCache`).
+ * `plugin`'s view of the cache. The local store never knows a scope
+ * (owner, 2026-10-17): it keeps every entry under its name's key. A scoped
+ * run reads a remote under the default key, then the scope's, and writes
+ * a remote only under the scope's.
  */
 export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache {
   const { db, policy, scope } = host
   const readers = host.remotes.filter((r) => r.read)
   const writers = host.remotes.filter((r) => r.write)
+  const at: RemoteKey = scope === undefined ? {} : { scope }
+  const atOf = (key: string, name: string): RemoteKey => (key === entryKey(plugin, name) ? {} : at)
   const reads = (name: string): string[] => {
     const key = entryKey(plugin, name)
     return scope === undefined ? [key] : [key, scopedKey(scope, key)]
@@ -139,19 +144,18 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
 
   return {
     async get(name) {
+      const local = entryKey(plugin, name)
+      const hit = localGet(local)
+      if (hit !== null) return hit
       const keys = reads(name)
-      for (const key of keys) {
-        const hit = localGet(key)
-        if (hit !== null) return hit
-      }
       for (const { remote } of readers) {
         for (const key of keys) {
           try {
-            const got = await remote.get(key)
+            const got = await remote.get(key, atOf(key, name))
             if (got === null) continue
             const bytes = await capped(got.body)
             if (bytes === null) continue
-            if (policy.localWrite) localPut(key, bytes)
+            if (policy.localWrite) localPut(local, bytes)
             return bytes
           } catch {
             // a failing remote is a miss there
@@ -164,10 +168,10 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
     async put(name, bytes) {
       if (bytes.byteLength === 0 || bytes.byteLength > PLUGIN_ENTRY_MAX_BYTES) return
       const key = writeKey(name)
-      if (policy.localWrite) localPut(key, bytes)
+      if (policy.localWrite) localPut(entryKey(plugin, name), bytes)
       for (const { remote } of writers) {
         try {
-          await remote.put(key, new Blob([bytes]), { durationMs: 0 })
+          await remote.put(key, new Blob([bytes]), { durationMs: 0, ...at })
         } catch {
           // the other layers still keep it
         }
@@ -175,13 +179,13 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
     },
 
     async has(name) {
+      if (localHas([entryKey(plugin, name)]).size > 0) return true
       const keys = reads(name)
-      if (localHas(keys).size > 0) return true
       let answered = policy.localRead
       for (const { remote } of readers) {
         for (const key of keys) {
           try {
-            if (await remote.has(key)) return true
+            if (await remote.has(key, atOf(key, name))) return true
             answered = true
           } catch {
             // no answer from this remote
@@ -196,13 +200,16 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
       for (const name of names) for (const key of reads(name)) byKey.set(key, name)
       const keys = [...byKey.keys()]
       const found = new Set<string>()
-      for (const key of localHas(keys)) found.add(byKey.get(key)!)
+      for (const key of localHas(names.map((n) => entryKey(plugin, n)))) found.add(byKey.get(key)!)
       for (const { remote } of readers) {
         const ask = keys.filter((k) => !found.has(byKey.get(k)!))
         if (ask.length === 0) break
         if (remote.hasMany === undefined) return null
         try {
-          const got: unknown = await remote.hasMany(ask)
+          const got: unknown = await remote.hasMany(
+            ask,
+            ask.map((k) => atOf(k, byKey.get(k)!)),
+          )
           if (!(got instanceof Set)) return null
           for (const key of got) if (byKey.has(key as string)) found.add(byKey.get(key as string)!)
         } catch {
@@ -214,9 +221,9 @@ export function pluginCache(plugin: string, host: PluginCacheHost): PluginCache
 
     async getRun(name) {
       for (const { remote } of readers) {
-        for (const key of runReadKeys(name, scope)) {
+        for (const [i, key] of runReadKeys(name, scope).entries()) {
           try {
-            const got = await remote.get(key)
+            const got = await remote.get(key, i === 0 ? {} : at)
             if (got === null) continue
             const bytes = await capped(got.body, Infinity)
             if (bytes !== null) return bytes

package/src/cache/remote-lane.ts

@@ -10,8 +10,11 @@ import type { RemoteCacheLayer } from './layered-cache.js'
 /** One remote, resolved: its wire and what the run's policy and its `access` let it do. */
 export interface ResolvedRemote {
   readonly remote: RemoteCacheLayer
-  readonly read: boolean
-  readonly write: boolean
+  /** The plugin that supplied it, whose keychain its `open` reads; none for an injected layer. */
+  readonly plugin?: string
+  /** Cleared, with `write`, when the remote's `open` fails: off for the rest of the run. */
+  read: boolean
+  write: boolean
   /** Told of each failure this remote degrades to a miss; the default writes stderr. */
   readonly onError?: (err: Error) => void
 }
@@ -89,8 +92,7 @@ function batchOf(hashes: readonly string[]): { batch: string } {
 }
 
 export class RemoteLane {
-  readonly read: boolean
-  readonly write: boolean
+  private readonly resolved: ResolvedRemote
   private readonly remote: RemoteCacheLayer
   private readonly endpoint: string | undefined
   private readonly onError: ((err: Error) => void) | undefined
@@ -131,14 +133,23 @@ export class RemoteLane {
   constructor(
     resolved: ResolvedRemote,
     private readonly traffic: RemoteTraffic,
+    /** The wire as this run asks it: a branch scope's view of `resolved.remote`. */
+    remote: RemoteCacheLayer = resolved.remote,
   ) {
-    this.remote = resolved.remote
-    this.read = resolved.read
-    this.write = resolved.write
+    this.resolved = resolved
+    this.remote = remote
     this.onError = resolved.onError
     this.endpoint = printableEndpoint(resolved.remote.endpoint)
   }
 
+  get read(): boolean {
+    return this.resolved.read
+  }
+
+  get write(): boolean {
+    return this.resolved.write
+  }
+
   /**
    * Existence probe; a failure is a miss. A key a `hasMany` this run
    * answered for is not asked again: `--dry` batches its keys first.
@@ -280,6 +291,11 @@ export class RemoteLane {
     this.pump()
   }
 
+  /** Settles when the run is stopped. */
+  get whenStopped(): Promise<void> {
+    return this.stopping
+  }
+
   /** Resolves once every queued and in-flight upload has settled, or the run was stopped. */
   async drain(): Promise<void> {
     // A probe no upload waited on still runs: settled before the run tears
@@ -292,7 +308,8 @@ export class RemoteLane {
   /**
    * The run was stopped (Ctrl-C, SIGTERM, an embedder's abort): queued
    * uploads never start and the drain stops waiting on the ones in flight,
-   * which a plugin cannot be asked to cancel. A slow remote held a stopped
+   * which a plugin cannot be asked to cancel. Reads in flight are given up
+   * the same way (`LayeredCache.pullFrom`). A slow remote held a stopped
    * run past the signal's exit bound, which then exited with no footer.
    */
   stop(): void {

package/src/cache/run-store.ts

@@ -44,7 +44,10 @@ export async function putRunEntry(
   for (const { remote, write } of remotes) {
     if (!write) continue
     try {
-      await remote.put(key, new Blob([bytes]), { durationMs: 0 })
+      await remote.put(key, new Blob([bytes]), {
+        durationMs: 0,
+        ...(scope === undefined ? {} : { scope }),
+      })
       kept = true
     } catch {
       // the other remotes still keep it

package/src/cache/schema.ts

@@ -140,6 +140,14 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       content_hash TEXT NOT NULL,
       seen_at      INTEGER NOT NULL
     );
+    -- v42: each task's last key by its fold up to the files and a token of
+    -- the files' git records (fold-memo.ts). A memo: the KEY is unchanged.
+    CREATE TABLE IF NOT EXISTS main.fold_memo (
+      task_id TEXT PRIMARY KEY,
+      probe   TEXT NOT NULL,
+      key     TEXT NOT NULL,
+      seen_at INTEGER NOT NULL
+    );
     -- The size of each index blob the enumeration checked against the
     -- worktree size git recorded (A-60). Fixed for its OID, so a warm
     -- run asks git for none; swept with file_hashes by seen_at, the
@@ -317,8 +325,10 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
  * the artifact is the record and the entries only its inventory, so a reset
  * drops the rows and keeps these, as it keeps the files. `artifacts_meta`
  * holds the table's own layout version (`'layout'`), the one thing that may
- * drop it. `at` is the last use a row-less sweep judges, as a file's mtime;
- * it sits before `bytes` so reading it never walks a blob's overflow pages.
+ * drop it. `at` is the last use a row-less sweep judges, as a file's mtime.
+ * A rowid table, not WITHOUT ROWID: there the blob sits in the key's b-tree,
+ * so every probe of a hash reads overflow pages; 10 000 lookups took 312 ms
+ * against 8.5 (a2, 2026-10-17).
  */
 export function createArtifactTables(db: Database, store: 'main' | 'store'): void {
   db.exec(artifactTables(store))
@@ -331,7 +341,7 @@ function artifactTables(store: 'main' | 'store'): string {
       hash  TEXT PRIMARY KEY,
       at    INTEGER NOT NULL,
       bytes BLOB NOT NULL
-    ) WITHOUT ROWID;
+    );
     CREATE TABLE IF NOT EXISTS ${store}.artifacts_meta (
       key   TEXT PRIMARY KEY,
       value TEXT NOT NULL