@vzn/vx 0.0.514 → 0.0.515

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.514",
+  "version": "0.0.515",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.514",
-    "@vzn/vx-linux-arm64": "0.0.514",
-    "@vzn/vx-darwin-x64": "0.0.514",
-    "@vzn/vx-darwin-arm64": "0.0.514"
+    "@vzn/vx-linux-x64": "0.0.515",
+    "@vzn/vx-linux-arm64": "0.0.515",
+    "@vzn/vx-darwin-x64": "0.0.515",
+    "@vzn/vx-darwin-arm64": "0.0.515"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/cache.ts

@@ -37,6 +37,7 @@ import {
   closeSync,
   constants,
   existsSync,
+  linkSync,
   lstatSync,
   mkdirSync,
   openSync,
@@ -181,17 +182,23 @@ export function noteSchemaReset(cache: Cache, warn: (message: string) => void):
       `[vx] cache entries now live in the shared store ${to}; the ones in ${from} miss once, and \`vx cache prune\` reclaims their artifacts`,
     )
   }
+  if (cache.storeReset !== null) {
+    const { from, to } = cache.storeReset
+    warn(
+      `[vx] shared cache store ${cache.storeDir} re-indexed: schema ${from} → ${to} (vx version changed); its artifacts stay and are indexed again as tasks hit them`,
+    )
+  }
   if (cache.formatChange !== null) {
     const { from, to } = cache.formatChange
     warn(
-      `[vx] cache format changed: ${from} → ${to} (vx upgraded); every cached task misses once and re-saves, and the old entries, never read again, age out under \`vx cache prune --older-than\` or \`cacheRetention\``,
+      `[vx] cache format changed: ${from} → ${to} (vx version changed); every cached task misses once and re-saves, and the old entries, never read again, age out under \`vx cache prune --older-than\` or \`cacheRetention\``,
     )
     return
   }
   if (cache.schemaReset === null) return
   const { from, to } = cache.schemaReset
   warn(
-    `[vx] cache index reset: schema ${from} → ${to} (vx upgraded); every cached task misses once and re-saves, and \`vx cache prune\` reclaims the old artifacts`,
+    `[vx] cache index reset: schema ${from} → ${to} (vx version changed); run history starts over, and each artifact is indexed again when its task next hits`,
   )
 }
 // SCHEMA history (drop+recreate on mismatch; pre-alpha, no migrations):
@@ -269,12 +276,6 @@ const STORE_TABLES = ['entry_inputs', 'output_files', 'entry_stdout', 'store_met
 const SELECT_ENTRY =
   "SELECT e.*, COALESCE(s.stdout, '') AS stdout FROM entries e LEFT JOIN entry_stdout s ON s.hash = e.hash"
 
-/** A schema version's number (`v28` → 28); one that is not `v<n>` is older than any. */
-function schemaOrdinal(version: string): number {
-  const m = /^v(\d+)$/.exec(version)
-  return m === null ? -1 : Number(m[1])
-}
-
 /**
  * Artifacts `indexed` does not hold, and temps, past the in-flight grace
  * window: one readdir, one stat per candidate. `indexed` is asked only
@@ -574,6 +575,13 @@ export class Cache implements CacheLayer {
    */
   readonly formatChange: SchemaReset | null = null
 
+  /**
+   * Set when THIS open found the shared store written under another
+   * `SCHEMA_VERSION` and dropped its inventory; the artifacts stay and are
+   * indexed again as they hit. Reported by `noteSchemaReset`.
+   */
+  readonly storeReset: SchemaReset | null = null
+
   /** A reading verb's open: it never resets the index (the constructor's `mode`). */
   static inspect(cacheDir: string): Cache {
     return new Cache(cacheDir, undefined, undefined, undefined, 'inspect')
@@ -607,7 +615,7 @@ export class Cache implements CacheLayer {
     } catch {
       return null
     }
-    if (found === undefined || schemaOrdinal(found) >= schemaOrdinal(SCHEMA_VERSION)) return null
+    if (found === undefined || found === SCHEMA_VERSION) return null
     const aged = await scanOrphanFiles(cacheDir, () => new Set())
     let orphanBytes = 0
     for (const o of aged) orphanBytes += o.size
@@ -634,7 +642,7 @@ export class Cache implements CacheLayer {
     /**
      * The shared store's directory, unversioned: every key is seeded with
      * `CACHE_VERSION`, so two vx versions never read each other's entries,
-     * and a store table only ever gains columns (owner, 2026-10-06). Or
+     * and the store's own schema is `store_meta.schema` (`matchStoreSchema`). Or
      * `null` for an index that holds its entries itself (a `cacheDir`).
      * Undefined follows the layout the index records: a reading verb, a
      * plugin's handle.
@@ -744,20 +752,14 @@ export class Cache implements CacheLayer {
           | { value: string }
           | undefined
       )?.value
-    // Only an EARLIER schema is reset, and only by an opener that may write
-    // it. A newer one is another vx's index and history: an older binary
-    // (a global install beside a workspace's own) dropped every table of it
-    // and announced "vx upgraded", and so did a reading verb, a dry prune
-    // among them (item 896).
+    // Any other schema is reset by an opener that may write it: the index is
+    // an inventory the artifacts rebuild, whichever vx wrote it (owner,
+    // 2026-10-06; a newer one used to be refused, item 896). A reading verb
+    // leaves it as it was.
     const refuseUnreadable = (found: string): void => {
-      if (schemaOrdinal(found) > schemaOrdinal(SCHEMA_VERSION)) {
-        throw new UserError(
-          `the cache at ${cacheDir} holds index schema ${found}, written by a newer vx; this vx reads ${SCHEMA_VERSION} and leaves it untouched. Run the newer vx, or give this one another --cache-dir`,
-        )
-      }
       if (mode === 'inspect') {
         throw new UserError(
-          `the cache at ${cacheDir} holds index schema ${found} from an earlier vx; this vx reads ${SCHEMA_VERSION}, so nothing in it is readable here, and this verb leaves it untouched. The next \`vx run\` resets it`,
+          `the cache at ${cacheDir} holds index schema ${found} from another vx version; this vx reads ${SCHEMA_VERSION}, so nothing in it is readable here, and this verb leaves it untouched. The next \`vx run\` resets it`,
         )
       }
     }
@@ -850,9 +852,19 @@ export class Cache implements CacheLayer {
     }
     this.storeDir = storeDir
     this.artifactDir = storeDir ?? cacheDir
-    if (storeDir !== undefined) this.attachStore(storeDir, mode === 'inspect')
+    if (storeDir !== undefined) {
+      this.attachStore(storeDir, mode === 'inspect')
+      this.storeReset = this.matchStoreSchema(mode === 'open' && this.writeBlocked === null)
+    }
 
     createTables(this.db, storeDir === undefined ? 'main' : 'store')
+    if (storeDir !== undefined && mode === 'open' && this.writeBlocked === null) {
+      this.db
+        .prepare(
+          "INSERT INTO store.store_meta(key, value) VALUES ('schema', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+        )
+        .run(SCHEMA_VERSION)
+    }
     if (mode === 'open' && this.writeBlocked === null && storeDir !== recorded) {
       if (storeDir === undefined)
         this.db.prepare("DELETE FROM schema_meta WHERE key = 'store_dir'").run()
@@ -977,6 +989,57 @@ export class Cache implements CacheLayer {
     }
   }
 
+  /**
+   * The store is an inventory of the artifacts beside it, and only this vx
+   * reads it: a store another `SCHEMA_VERSION` wrote has its tables dropped
+   * (owner, 2026-10-06), the artifacts kept. Each is indexed again from its
+   * own bytes on its next hit (`adopt`). A reading verb reads such a store
+   * as empty and changes nothing.
+   */
+  private matchStoreSchema(writable: boolean): SchemaReset | null {
+    const tables = new Set(
+      (
+        this.db
+          .prepare("SELECT name FROM store.sqlite_master WHERE type = 'table'")
+          .all() as Array<{
+          name: string
+        }>
+      ).map((r) => r.name),
+    )
+    if (!tables.has('entries')) return null
+    const found = tables.has('store_meta')
+      ? (
+          this.db.prepare("SELECT value FROM store.store_meta WHERE key = 'schema'").get() as {
+            value: string
+          } | null
+        )?.value
+      : undefined
+    if (found === SCHEMA_VERSION) return null
+    if (!writable) {
+      this.db.exec('DETACH DATABASE store')
+      this.db.prepare('ATTACH DATABASE ? AS store').run(':memory:')
+      return null
+    }
+    let reset: SchemaReset | null = null
+    this.db
+      .transaction(() => {
+        // Re-read under the write lock: another workspace's open may have
+        // reset it first.
+        const now = (
+          this.db.prepare("SELECT value FROM store.store_meta WHERE key = 'schema'").get() as {
+            value: string
+          } | null
+        )?.value
+        if (now === SCHEMA_VERSION) return
+        for (const t of STORE_TABLES) {
+          if (t !== 'store_meta') this.db.exec(`DROP TABLE IF EXISTS store.${t}`)
+        }
+        reset = { from: found ?? 'an earlier schema', to: SCHEMA_VERSION }
+      })
+      .immediate()
+    return reset
+  }
+
   // --- config evaluations: `ConfigEvalStore`, delegated to `ConfigEvalTable` ---
   getConfigEval(key: string): string | null {
     return this.guard(() => this.configEvals.getConfigEval(key))
@@ -1107,11 +1170,53 @@ export class Cache implements CacheLayer {
   // ctx is accepted but ignored — the local layer reads metadata from
   // the entries row. It's part of the contract so LayeredCache can
   // route metadata to `ingest()` on remote-hit without a separate API.
-  async get(hash: string, _ctx?: CacheGetContext): Promise<CacheEntry | null> {
+  async get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null> {
     // Local reads disabled (e.g. `--force` / `--cache=local:w`): report a
     // miss so the task re-executes. The artifact + index are untouched.
     if (!this.read) return null
-    return this.guard(() => this.readEntry(hash))
+    return this.guard(async () => {
+      const entry = await this.readEntry(hash)
+      if (entry !== null || ctx === undefined || !this.write) return entry
+      return (await this.adopt(hash, ctx)) ? this.readEntry(hash) : null
+    })
+  }
+
+  /**
+   * Index an artifact the index does not know, from its own bytes: the
+   * artifact is the record, the index only an inventory of it (owner,
+   * 2026-10-06). A reset index (a `SCHEMA_VERSION` change, a `cache.db` or
+   * `store.db` deleted) loses nothing a task asks for again. The artifact
+   * is checked as an ingest checks a remote's (its recorded key, its names
+   * against the declared outputs); one that fails is a miss, and the run
+   * that follows saves over it.
+   */
+  private async adopt(hash: string, ctx: CacheGetContext): Promise<boolean> {
+    const finalPath = this.tarPath(hash)
+    if (!existsSync(finalPath)) return false
+    const tmpPath = this.tempPath(hash)
+    try {
+      // A second name for the same bytes: the index step renames it over
+      // the artifact inside its write transaction, as for a save.
+      linkSync(finalPath, tmpPath)
+    } catch {
+      return false
+    }
+    try {
+      await this.writeArtifactAndIndex(
+        hash,
+        { tmpPath },
+        {
+          taskId: ctx.taskId,
+          command: ctx.command,
+          durationMs: 0,
+          ...(ctx.outputs !== undefined ? { outputs: ctx.outputs } : {}),
+        },
+      )
+      return true
+    } catch (err) {
+      if (err instanceof CorruptArtifactError || err instanceof ArchiveSecurityError) return false
+      throw err
+    }
   }
 
   /**
@@ -1160,8 +1265,21 @@ export class Cache implements CacheLayer {
    * The up-front short-circuit probe is the caller; per-hit `get` stays for
    * the lazy path.
    */
-  async getMany(hashes: readonly string[]): Promise<Map<string, CacheEntry>> {
-    return this.guard(() => this.getManyEntries(hashes))
+  async getMany(
+    hashes: readonly string[],
+    ctx?: (hash: string) => CacheGetContext,
+  ): Promise<Map<string, CacheEntry>> {
+    return this.guard(async () => {
+      const out = await this.getManyEntries(hashes)
+      if (ctx === undefined || !this.write || out.size === hashes.length) return out
+      // An artifact the index does not know is still a hit (`adopt`).
+      for (const hash of hashes) {
+        if (out.has(hash) || !(await this.adopt(hash, ctx(hash)))) continue
+        const entry = await this.readEntry(hash)
+        if (entry !== null) out.set(hash, entry)
+      }
+      return out
+    })
   }
 
   private async getManyEntries(hashes: readonly string[]): Promise<Map<string, CacheEntry>> {

package/src/cache/layer.ts

@@ -565,9 +565,12 @@ export interface CacheLayer {
   /**
    * Optional batched `get` (same answers, fewer round trips). The
    * short-circuit probe uses it when a layer offers one; a layer without it
-   * is probed hash by hash.
+   * is probed hash by hash. `ctx` is each hash's `get` context.
    */
-  getMany?(hashes: readonly string[]): Promise<Map<string, CacheEntry>>
+  getMany?(
+    hashes: readonly string[],
+    ctx?: (hash: string) => CacheGetContext,
+  ): Promise<Map<string, CacheEntry>>
   /**
    * Lightweight existence probe. `'local'` / `'remote'` names the layer
    * that holds the artifact; `null` is a miss. NEVER moves bytes: no

package/src/cli/cache.ts

@@ -176,7 +176,7 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
     const earlier = await Cache.orphansBeforeReset(dir)
     if (earlier !== null) {
       warnToStderr(
-        `[vx] the cache index is schema ${earlier.found} from an earlier vx: the prune resets it first, and every artifact past the hour's grace is then an orphan`,
+        `[vx] the cache index is schema ${earlier.found} from another vx version: the prune resets it first, and every artifact past the hour's grace is then an orphan`,
       )
       printPruned({ evicted: 0, bytesFreed: 0, ...earlier }, true, json)
       return 0

package/src/orchestrator/doctor.ts

@@ -245,9 +245,9 @@ async function collectWorkspaceInfo(
     schemaVersion: SCHEMA_VERSION,
     cacheEntries: stats.entryCount,
     cacheBytes: stats.totalBytes,
-    // The index is authoritative, so a row-less artifact is bytes nothing
-    // will ever hit — and only `vx cache prune` reclaims them (after an
-    // upgrade's schema reset, most often).
+    // A row-less artifact is indexed again only when its task asks for its
+    // key; the rest only `vx cache prune` reclaims (after an upgrade's
+    // schema reset, most often).
     orphans: { artifacts: orphans.orphans, bytes: orphans.orphanBytes },
     runs24h: stats.runCountLast24h,
     hits24h: stats.hitCountLast24h,

package/src/orchestrator/local-shortcircuit.ts

@@ -46,6 +46,7 @@ import type { CacheEntry, CacheLayer, GitFilesCache } from '../cache/index.js'
 import type { TaskNode } from '../graph/index.js'
 import { deriveStableKeys, workspaceInputsReach } from './stable-keys.js'
 import type { HashCache } from './task-hash.js'
+import { getContext } from './remote-prefetch.js'
 
 export interface ShortCircuitArgs {
   nodes: Map<string, TaskNode>
@@ -138,7 +139,14 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
   if (args.cache.getMany !== undefined) {
     try {
       const endProbe = span('probe')
-      const hits = await args.cache.getMany(candidates.map((c) => c.hash))
+      const byHash = new Map(candidates.map((c) => [c.hash, c.node]))
+      const hits = await args.cache.getMany(
+        candidates.map((c) => c.hash),
+        (hash) => {
+          const node = byHash.get(hash)!
+          return getContext(node, node.config.exec?.command ?? '')
+        },
+      )
       endProbe()
       for (const { hash, node } of candidates) {
         const hit = hits.get(hash) ?? null
@@ -157,8 +165,7 @@ export async function startLocalShortCircuit(args: ShortCircuitArgs): Promise<Sh
     while (next < candidates.length) {
       const { hash, node } = candidates[next++]!
       try {
-        const command = node.config.exec?.command ?? ''
-        const hit = await args.cache.get(hash, { taskId: node.id, command })
+        const hit = await args.cache.get(hash, getContext(node, node.config.exec?.command ?? ''))
         preProbed.set(node.id, { hash, hit })
         if (hit !== null && !keptOut.has(node.id)) restoreTier.add(node.id)
       } catch {