@vzn/vx 0.0.511 → 0.0.512

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.511",
+  "version": "0.0.512",
   "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.511",
-    "@vzn/vx-linux-arm64": "0.0.511",
-    "@vzn/vx-darwin-x64": "0.0.511",
-    "@vzn/vx-darwin-arm64": "0.0.511"
+    "@vzn/vx-linux-x64": "0.0.512",
+    "@vzn/vx-linux-arm64": "0.0.512",
+    "@vzn/vx-darwin-x64": "0.0.512",
+    "@vzn/vx-darwin-arm64": "0.0.512"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/cache.ts

@@ -20,6 +20,12 @@
 // for the user to see — but on a cache hit there's nothing to replay
 // (the original run was successful and stderr typically empty).
 //
+// With a shared store (v32, the default: `docs/design/shared-store-2026-10.md`)
+// the entries and their artifacts live in `<store>/store.db` and
+// `<store>/<hash>.tar.zst`, attached to the workspace's own `cache.db`,
+// which keeps the history and the memos: every workspace of one user hits
+// what another saved, and none reads another's runs.
+//
 // This is core's FLOOR, not a module to replace: remote storage is a
 // `RemoteCacheLayer` (has / get / put) that `LayeredCache` wraps around
 // this handle, declared by a plugin's `cache` hook. The contract every
@@ -31,6 +37,7 @@ import {
   closeSync,
   constants,
   existsSync,
+  lstatSync,
   mkdirSync,
   openSync,
   renameSync,
@@ -163,6 +170,17 @@ function outOfFdsAtOpen(dbFile: string, err: unknown): UserError | undefined {
 
 /** Say once, on the channel the opener has, that an upgrade emptied the index. */
 export function noteSchemaReset(cache: Cache, warn: (message: string) => void): void {
+  if (cache.storeFallback !== null) {
+    warn(
+      `[vx] shared cache store ${cache.storeFallback} is not usable; entries stay in ${cache.storeDir ?? 'this workspace'}, where no other workspace hits them`,
+    )
+  }
+  if (cache.storeMoved !== null) {
+    const { from, to } = cache.storeMoved
+    warn(
+      `[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.formatChange !== null) {
     const { from, to } = cache.formatChange
     warn(
@@ -237,7 +255,15 @@ export function noteSchemaReset(cache: Cache, warn: (message: string) => void):
 //        restored_remote counts — a hit that restored outputs apart from
 //        one that found them in place, for every reader after the run.
 //        The cache KEY is unchanged.
-export const SCHEMA_VERSION = 'v31'
+//   v32: the entry tables (entries, entry_stdout, output_files,
+//        entry_inputs) may live in a shared store attached as `store`;
+//        output_files' ino + ctime_ms moved to the workspace's own
+//        output_stamps, output_dirs lost its foreign key, and the value
+//        salt moved to store_meta. The cache KEY is unchanged.
+export const SCHEMA_VERSION = 'v32'
+
+/** The tables a store holds: dropped from a workspace index that held them itself. */
+const STORE_TABLES = ['entry_inputs', 'output_files', 'entry_stdout', 'store_meta', 'entries']
 
 /** An entry row with its stdout, which lives apart (v29); none stored reads as ''. */
 const SELECT_ENTRY =
@@ -403,6 +429,39 @@ function openCacheDir(cacheDir: string): string | null {
   return null
 }
 
+/** `openCacheDir` for the shared store: why it cannot be used, or null. Never throws. */
+function storeBlocked(storeDir: string, storeRoot: string | null): string | null {
+  try {
+    if (storeRoot !== null) {
+      // `~/.vx`, `~/.vx/<id>`, `~/.vx/<id>/cache`: owner-only, each level
+      // made alone and re-checked, as Nx makes `~/.nx/<id>`. Artifacts are
+      // replayed into the workspace, so nobody else may write them.
+      const vxHome = path.dirname(path.dirname(storeRoot))
+      for (const dir of [vxHome, path.dirname(storeRoot), storeRoot]) {
+        const refused = ensurePrivateDir(dir)
+        if (refused !== null) return refused
+      }
+    }
+    return openCacheDir(storeDir)
+  } catch (err) {
+    return errorText(err)
+  }
+}
+
+function ensurePrivateDir(dir: string): string | null {
+  try {
+    mkdirSync(dir, { mode: 0o700 })
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return errorText(err)
+  }
+  const st = lstatSync(dir)
+  if (!st.isDirectory()) return `${dir} is not a directory`
+  const uid = process.getuid?.()
+  if (uid !== undefined && st.uid !== uid) return `${dir} belongs to another user`
+  if ((st.mode & 0o077) !== 0) return `${dir} is open to other users (chmod 700 it)`
+  return null
+}
+
 // Make the cache dir invisible to git, every time it is created: a `*`
 // .gitignore inside it (the Cargo / Nx convention). Two reasons, both
 // measured. A cache nobody ignored gets COMMITTED by the next `git add -A`;
@@ -482,6 +541,21 @@ export class Cache implements CacheLayer {
   /** Why this process cannot write into `cacheDir`, or `null`; decided at open. */
   private readonly writeBlocked: string | null
   private readonly dbFile: string
+  /** Where the artifacts live: the shared store, or `cacheDir` itself. */
+  private readonly artifactDir: string
+
+  /** The shared store this index attached, or undefined when it holds its entries itself. */
+  readonly storeDir: string | undefined
+
+  /**
+   * The store this open was asked for and could not use, with why: the
+   * entries went to a store inside `cacheDir` instead. Said once by
+   * `noteSchemaReset`.
+   */
+  readonly storeFallback: string | null = null
+
+  /** Set when this open moved a workspace index's own entries out for a shared store. */
+  readonly storeMoved: { from: string; to: string } | null = null
 
   /**
    * Set when THIS open found an index written by another `SCHEMA_VERSION`
@@ -557,6 +631,15 @@ export class Cache implements CacheLayer {
      * and left as it was.
      */
     mode: 'open' | 'inspect' = 'open',
+    /**
+     * 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
+     * `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.
+     */
+    storeRoot?: string | null,
   ) {
     this.inspecting = mode === 'inspect'
     this.read = localPolicy.read
@@ -693,8 +776,11 @@ export class Cache implements CacheLayer {
               return null
             }
             if (found === SCHEMA_VERSION) return null
+            // `main.` on every name: unqualified, a table the index lacks
+            // resolves to an attached store's (none is attached yet; this
+            // keeps it so).
             this.db.exec(
-              'DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS runs; DROP TABLE IF EXISTS file_hashes; DROP TABLE IF EXISTS blob_sizes; DROP TABLE IF EXISTS blob_verdicts; DROP TABLE IF EXISTS output_files; DROP TABLE IF EXISTS invocations; DROP TABLE IF EXISTS run_task_inputs; DROP TABLE IF EXISTS entry_inputs; DROP TABLE IF EXISTS config_evals; DROP TABLE IF EXISTS config_closures; DROP TABLE IF EXISTS output_dirs; DROP TABLE IF EXISTS entry_stdout;',
+              'DROP TABLE IF EXISTS main.entries; DROP TABLE IF EXISTS main.runs; DROP TABLE IF EXISTS main.file_hashes; DROP TABLE IF EXISTS main.blob_sizes; DROP TABLE IF EXISTS main.blob_verdicts; DROP TABLE IF EXISTS main.output_files; DROP TABLE IF EXISTS main.output_stamps; DROP TABLE IF EXISTS main.invocations; DROP TABLE IF EXISTS main.run_task_inputs; DROP TABLE IF EXISTS main.entry_inputs; DROP TABLE IF EXISTS main.config_evals; DROP TABLE IF EXISTS main.config_closures; DROP TABLE IF EXISTS main.output_dirs; DROP TABLE IF EXISTS main.entry_stdout; DROP TABLE IF EXISTS main.store_meta;',
             )
             this.db
               .prepare("UPDATE schema_meta SET value = ? WHERE key = 'version'")
@@ -712,7 +798,71 @@ export class Cache implements CacheLayer {
       }
     }
 
-    createTables(this.db)
+    // Where the entry tables live (v32): `store_dir` names the shared store
+    // this index was last opened with; absent, the index holds them itself.
+    const recorded = readable(
+      () =>
+        (
+          this.db.prepare("SELECT value FROM schema_meta WHERE key = 'store_dir'").get() as {
+            value: string
+          } | null
+        )?.value,
+    )
+    let storeDir =
+      mode === 'inspect' || storeRoot === undefined
+        ? recorded
+        : storeRoot === null
+          ? undefined
+          : storeRoot
+    if (storeDir !== undefined && mode === 'open' && this.writeBlocked === null) {
+      const blocked = storeBlocked(storeDir, typeof storeRoot === 'string' ? storeRoot : null)
+      if (blocked !== null) {
+        // A home this user cannot write (a container, a read-only mount):
+        // the entries stay in this workspace rather than fail the run.
+        const fallback = cacheDir
+        if (fallback !== storeDir) {
+          // Said by the open that falls back; the ones after it find it recorded.
+          if (recorded !== fallback) this.storeFallback = `${storeDir} (${blocked})`
+          storeDir = fallback
+          openCacheDir(fallback)
+        }
+      }
+    }
+    if (storeDir !== undefined && mode === 'open' && this.writeBlocked === null) {
+      // An index that held its entries itself would shadow the store's:
+      // SQLite resolves an unqualified name in `main` first. Its history
+      // and memos stay; its entries' artifacts are orphans `prune` reaps.
+      const holds = readable(
+        () =>
+          this.db
+            .prepare("SELECT 1 FROM main.sqlite_master WHERE type = 'table' AND name = 'entries'")
+            .get() != null,
+      )
+      if (holds) {
+        const had = this.db.prepare('SELECT 1 FROM main.entries LIMIT 1').get() != null
+        this.db
+          .transaction(() => {
+            for (const t of STORE_TABLES) this.db.exec(`DROP TABLE IF EXISTS main.${t}`)
+          })
+          .immediate()
+        if (had) this.storeMoved = { from: cacheDir, to: storeDir }
+      }
+    }
+    this.storeDir = storeDir
+    this.artifactDir = storeDir ?? cacheDir
+    if (storeDir !== undefined) this.attachStore(storeDir, mode === 'inspect')
+
+    createTables(this.db, storeDir === undefined ? 'main' : 'store')
+    if (mode === 'open' && this.writeBlocked === null && storeDir !== recorded) {
+      if (storeDir === undefined)
+        this.db.prepare("DELETE FROM schema_meta WHERE key = 'store_dir'").run()
+      else
+        this.db
+          .prepare(
+            "INSERT INTO schema_meta(key, value) VALUES ('store_dir', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+          )
+          .run(storeDir)
+    }
 
     this.deleteEntryRow = lazyStatement(this.db, 'DELETE FROM entries WHERE hash = ?')
     this.insertEntry = lazyStatement(
@@ -800,6 +950,33 @@ export class Cache implements CacheLayer {
     }
   }
 
+  /**
+   * Attach the shared store as `store`, with the pragmas the index takes:
+   * WAL for both, so a workspace's run and another's share the store as
+   * two runs on one `--cache-dir` share an index. A reading verb over a
+   * store with no file yet reads an empty one in memory.
+   */
+  private attachStore(storeDir: string, inspecting: boolean): void {
+    const storeFile = path.join(storeDir, 'store.db')
+    const absent = inspecting && !existsSync(storeFile)
+    try {
+      this.db.prepare('ATTACH DATABASE ? AS store').run(absent ? ':memory:' : storeFile)
+      this.db.exec('PRAGMA store.journal_mode = WAL')
+      if (!absent) this.db.fileControl('store', SQLITE_FCNTL_PERSIST_WAL, 1)
+      this.db.exec('PRAGMA store.journal_size_limit = 67108864')
+      this.db.exec('PRAGMA store.synchronous = NORMAL')
+    } catch (err) {
+      try {
+        closeDb(this.db)
+      } catch {
+        // The refusal below is the error worth reporting.
+      }
+      throw unreadableIndex(err)
+        ? unreadableIndexError(storeFile, err)
+        : (outOfFdsAtOpen(storeFile, err) ?? err)
+    }
+  }
+
   // --- config evaluations: `ConfigEvalStore`, delegated to `ConfigEvalTable` ---
   getConfigEval(key: string): string | null {
     return this.guard(() => this.configEvals.getConfigEval(key))
@@ -908,7 +1085,7 @@ export class Cache implements CacheLayer {
   private loadValueSalt(): string {
     const read = (): string | undefined =>
       (
-        this.db.prepare("SELECT value FROM schema_meta WHERE key = 'value_salt'").get() as {
+        this.db.prepare("SELECT value FROM store_meta WHERE key = 'value_salt'").get() as {
           value: string
         } | null
       )?.value
@@ -921,7 +1098,7 @@ export class Cache implements CacheLayer {
     // Two processes opening one new store: the first salt stands.
     this.db
       .prepare(
-        "INSERT INTO schema_meta(key, value) VALUES ('value_salt', ?) ON CONFLICT(key) DO NOTHING",
+        "INSERT INTO store_meta(key, value) VALUES ('value_salt', ?) ON CONFLICT(key) DO NOTHING",
       )
       .run(salt)
     return read() ?? salt
@@ -1079,11 +1256,15 @@ export class Cache implements CacheLayer {
   /** Remove one entry: its artifact first, then its rows (as `prune` orders them). */
   private async dropEntry(hash: string): Promise<void> {
     await rm(this.tarPath(hash), { force: true })
-    try {
+    const drop = this.db.transaction(() => {
       this.deleteEntryRow.run(hash)
+      this.outputs.forget([hash])
+    })
+    try {
+      drop()
     } catch (err) {
       if (!isIndexFull(err)) throw err
-      this.deleteEntryRow.run(hash)
+      drop()
     }
   }
 
@@ -1921,6 +2102,7 @@ export class Cache implements CacheLayer {
       const { test, params } = inHashes(rows)
       const deleteRows = this.db.transaction(() => {
         this.db.prepare(`DELETE FROM entries WHERE hash ${test}`).run(...params)
+        this.outputs.forget(rows)
       })
       try {
         deleteRows()
@@ -1930,6 +2112,13 @@ export class Cache implements CacheLayer {
       }
     }
 
+    // This workspace's rows for entries another workspace pruned from a
+    // shared store: never read (a lookup starts at the entry), only kept.
+    try {
+      this.outputs.forgetGone()
+    } catch (err) {
+      if (!isIndexFull(err)) throw err
+    }
     const orphans = await this.reapOrphans()
     return { evicted: victims.size, bytesFreed, ...orphans }
   }
@@ -1994,7 +2183,7 @@ export class Cache implements CacheLayer {
     }>
     let names: string[]
     try {
-      names = await readdir(this.cacheDir)
+      names = await readdir(this.artifactDir)
     } catch {
       return { phantoms: new Map(), stale: [] }
     }
@@ -2019,8 +2208,8 @@ export class Cache implements CacheLayer {
 
   /** Row-less artifacts and temps past the in-flight grace window: one readdir, one stat per candidate. */
   private async scanOrphans(): Promise<Array<{ file: string; size: number }>> {
-    return scanOrphanFiles(
-      this.cacheDir,
+    const found = await scanOrphanFiles(
+      this.artifactDir,
       () =>
         new Set(
           (this.db.prepare('SELECT hash FROM entries').all() as Array<{ hash: string }>).map(
@@ -2028,6 +2217,10 @@ export class Cache implements CacheLayer {
           ),
         ),
     )
+    // With a shared store, no artifact in `cacheDir` is indexed: they are
+    // what this workspace saved before its entries moved out.
+    if (this.artifactDir === this.cacheDir) return found
+    return [...found, ...(await scanOrphanFiles(this.cacheDir, () => new Set()))]
   }
 
   close(): void {
@@ -2070,7 +2263,7 @@ export class Cache implements CacheLayer {
   }
 
   private tarPath(hash: string): string {
-    return path.join(this.cacheDir, `${hash}.tar.zst`)
+    return path.join(this.artifactDir, `${hash}.tar.zst`)
   }
 }
 

package/src/cache/output-index.ts

@@ -1,5 +1,6 @@
 // The output fingerprint index: per-entry `output_files` rows (size, mode,
-// millisecond mtime) and `output_dirs` rows (directory mtimes), and the two
+// millisecond mtime), this workspace's `output_stamps` (inode and ctime) and
+// `output_dirs` rows (directory mtimes), and the two
 // proofs a cache hit runs against the tree before deciding not to restore.
 // Owns its statements over the store's handle; `Cache` delegates, and
 // writes the file rows through `replaceFileRows` inside its own save
@@ -30,6 +31,7 @@ export class OutputIndex {
   private readonly deleteOutputDirs: ReturnType<Database['prepare']>
   private readonly entryExists: ReturnType<Database['prepare']>
   private readonly stampOutputFile: ReturnType<Database['prepare']>
+  private readonly deleteStamps: ReturnType<Database['prepare']>
   /**
    * Snapshots taken and not yet written, the last per hash. A snapshot is
    * read by the NEXT run's hit check, never by the task that took it, so
@@ -63,8 +65,34 @@ export class OutputIndex {
     this.entryExists = lazyStatement(this.db, 'SELECT 1 FROM entries WHERE hash = ?')
     this.stampOutputFile = lazyStatement(
       this.db,
-      'UPDATE output_files SET ino = ?, ctime_ms = ? WHERE entry_hash = ? AND path = ?',
+      'INSERT INTO output_stamps(entry_hash, path, ino, ctime_ms) VALUES (?, ?, ?, ?) ON CONFLICT(entry_hash, path) DO UPDATE SET ino = excluded.ino, ctime_ms = excluded.ctime_ms',
     )
+    this.deleteStamps = lazyStatement(this.db, 'DELETE FROM output_stamps WHERE entry_hash = ?')
+  }
+
+  /**
+   * Drop this workspace's stamps and snapshots of `hashes`, whose entries
+   * are gone: they live apart from the entry (it may be another database's),
+   * so no cascade takes them.
+   */
+  forget(hashes: readonly string[]): void {
+    if (hashes.length === 0) return
+    for (const h of hashes) {
+      this.pendingStamps.delete(h)
+      this.pendingDirs.delete(h)
+    }
+    const { test, params } = inHashes(hashes)
+    this.db.prepare(`DELETE FROM output_stamps WHERE entry_hash ${test}`).run(...params)
+    this.db.prepare(`DELETE FROM output_dirs WHERE entry_hash ${test}`).run(...params)
+  }
+
+  /** `forget` every entry no longer stored: another workspace's prune of a shared store. */
+  forgetGone(): void {
+    this.db.transaction(() => {
+      this.db.exec(
+        'DELETE FROM output_stamps WHERE entry_hash NOT IN (SELECT hash FROM entries); DELETE FROM output_dirs WHERE entry_hash NOT IN (SELECT hash FROM entries)',
+      )
+    })()
   }
 
   /**
@@ -76,6 +104,7 @@ export class OutputIndex {
     // A stamp taken for the rows this replaces describes their files, not these.
     this.pendingStamps.delete(hash)
     this.deleteOutputFiles.run(hash)
+    this.deleteStamps.run(hash)
     for (const [rel, size, mode, mtime] of rows) {
       this.insertOutputFile.run(hash, rel, size, mode, mtime)
     }
@@ -93,7 +122,7 @@ export class OutputIndex {
     // reads its rows twice.
     const { test, params } = inHashes(hashes)
     const stmt = this.db.query(
-      `SELECT entry_hash, path, size_bytes, mode, mtime_ms, ino, ctime_ms FROM output_files WHERE entry_hash ${test}`,
+      `SELECT f.entry_hash, f.path, f.size_bytes, f.mode, f.mtime_ms, s.ino, s.ctime_ms FROM output_files f LEFT JOIN output_stamps s ON s.entry_hash = f.entry_hash AND s.path = f.path WHERE f.entry_hash ${test}`,
     )
     const rows = stmt.all(...params) as Array<{
       entry_hash: string
@@ -296,7 +325,9 @@ export class OutputIndex {
       this.pendingStamps.clear()
       this.db.transaction(() => {
         for (const [hash, rows] of stamps) {
-          for (const [rel, ino, ctime] of rows) this.stampOutputFile.run(ino, ctime, hash, rel)
+          // A stamp outlives nothing: an entry pruned since has no rows to vouch for.
+          if (this.entryExists.get(hash) === null) continue
+          for (const [rel, ino, ctime] of rows) this.stampOutputFile.run(hash, rel, ino, ctime)
         }
       })()
     }
@@ -306,9 +337,8 @@ export class OutputIndex {
     this.db.transaction(() => {
       for (const [hash, rows] of pending) {
         this.deleteOutputDirs.run(hash)
-        // The rows reference the entry: one pruned by another process
-        // between the snapshot and this flush has nothing to describe,
-        // and its insert would fail the whole transaction on the FK.
+        // The rows describe the entry: one pruned by another process
+        // between the snapshot and this flush has nothing to describe.
         if (rows === null || this.entryExists.get(hash) === null) continue
         for (const [rel, mtime] of rows) this.insertOutputDir.run(hash, rel, mtime)
       }

package/src/cache/schema.ts

@@ -19,12 +19,21 @@ export function lazyStatement(db: Database, sql: string): ReturnType<Database['p
   } as unknown as ReturnType<Database['prepare']>
 }
 
-export function createTables(db: Database): void {
+/**
+ * Create every table. `store` names the schema holding the ENTRY tables
+ * (`entries`, `entry_stdout`, `output_files`, `entry_inputs`, `store_meta`):
+ * `main` when one `cache.db` holds everything (a `cacheDir`), `store` when
+ * they live in the shared store attached beside it (v32). The rest is the
+ * workspace's own: its history, its memos, and what its disk looked like
+ * after a save or restore. A store table is never named with its schema in
+ * a statement; SQLite finds it in `main` or in `store`, whichever has it.
+ */
+export function createTables(db: Database, store: 'main' | 'store' = 'main'): void {
   // Cached config evaluations (workspace/config-cache.ts): the validated
   // config as JSON, keyed by everything the evaluation could observe. A
   // separate exec so the artifact schema stays byte-identical.
   db.exec(`
-    CREATE TABLE IF NOT EXISTS config_evals (
+    CREATE TABLE IF NOT EXISTS main.config_evals (
       key        TEXT PRIMARY KEY,
       json       TEXT NOT NULL,
       created_at INTEGER NOT NULL
@@ -34,7 +43,7 @@ export function createTables(db: Database): void {
   db.exec(`
     -- The queryable index: command, exit_code, duration, size and
     -- timestamps; stdout in entry_stdout below.
-    CREATE TABLE IF NOT EXISTS entries (
+    CREATE TABLE IF NOT EXISTS ${store}.entries (
       hash         TEXT PRIMARY KEY,
       project      TEXT NOT NULL,
       task         TEXT NOT NULL,
@@ -52,12 +61,12 @@ export function createTables(db: Database): void {
     -- carries so it survives a remote round trip; a local hit replays it
     -- from here. Its own table: an UPDATE rewrites a whole record, and the
     -- accessed_at bump rewrote up to 16 MB a hit. No row: empty stdout.
-    CREATE TABLE IF NOT EXISTS entry_stdout (
+    CREATE TABLE IF NOT EXISTS ${store}.entry_stdout (
       hash   TEXT PRIMARY KEY,
       stdout TEXT NOT NULL,
       FOREIGN KEY (hash) REFERENCES entries(hash) ON DELETE CASCADE
     );
-    CREATE TABLE IF NOT EXISTS runs (
+    CREATE TABLE IF NOT EXISTS main.runs (
       id                  INTEGER PRIMARY KEY AUTOINCREMENT,
       -- '' when the outcome derived no cache key (skipped / persistent).
       -- Every reader that must not mistake it for a key guards hash != ''.
@@ -113,23 +122,23 @@ export function createTables(db: Database): void {
     --   runs_ended (2026-09-09) served only the retention DELETE, which
     --     prunes on started_at now (a row ends after it starts, so the
     --     30-day window moves by at most one task's duration).
-    DROP INDEX IF EXISTS runs_hash;
-    DROP INDEX IF EXISTS runs_project;
-    DROP INDEX IF EXISTS runs_ended;
-    CREATE INDEX IF NOT EXISTS runs_started_at ON runs(started_at);
-    CREATE INDEX IF NOT EXISTS runs_run_id     ON runs(run_id);
+    DROP INDEX IF EXISTS main.runs_hash;
+    DROP INDEX IF EXISTS main.runs_project;
+    DROP INDEX IF EXISTS main.runs_ended;
+    CREATE INDEX IF NOT EXISTS main.runs_started_at ON runs(started_at);
+    CREATE INDEX IF NOT EXISTS main.runs_run_id     ON runs(run_id);
     -- The one keyed index, PARTIAL over failed rows: a green run's
     -- inserts only evaluate its predicate, so the append-only cost above
     -- holds, and the flakiness probe after a miss (failure-mode.ts,
     -- "did this key ever fail?") reads a handful of leaves instead of
     -- scanning the table (2026-09-10: 10–95 ms at 170k rows without it).
-    CREATE INDEX IF NOT EXISTS runs_failed ON runs(hash) WHERE status = 'failed';
+    CREATE INDEX IF NOT EXISTS main.runs_failed ON runs(hash) WHERE status = 'failed';
     -- Per-file (mtime, size, content_hash) cache. Lets Cache.key()
     -- skip the content-hash on inputs whose stat hasn't changed
     -- since the last run. Pure performance optimization; the stored
     -- hash is the exact same one content-hashing would compute now,
     -- so the cache key derivation is unchanged.
-    CREATE TABLE IF NOT EXISTS file_hashes (
+    CREATE TABLE IF NOT EXISTS main.file_hashes (
       path         TEXT PRIMARY KEY,
       mtime_ms     INTEGER NOT NULL,
       size_bytes   INTEGER NOT NULL,
@@ -142,14 +151,14 @@ export function createTables(db: Database): void {
     -- 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
     -- time the row was written.
-    CREATE TABLE IF NOT EXISTS blob_sizes (
+    CREATE TABLE IF NOT EXISTS main.blob_sizes (
       oid     TEXT PRIMARY KEY,
       size    INTEGER NOT NULL,
       seen_at INTEGER NOT NULL
     );
     -- v30: the paths an index distrusts, by a hash of the index file and the
     -- pathspecs (A-60): a warm run reads one row, not one per blob.
-    CREATE TABLE IF NOT EXISTS blob_verdicts (
+    CREATE TABLE IF NOT EXISTS main.blob_verdicts (
       digest  TEXT PRIMARY KEY,
       paths   TEXT NOT NULL,
       seen_at INTEGER NOT NULL
@@ -163,24 +172,34 @@ export function createTables(db: Database): void {
     -- ON DELETE CASCADE keeps these rows in sync with entries:
     -- a cache prune that drops an entry sweeps its output rows
     -- automatically.
-    CREATE TABLE IF NOT EXISTS output_files (
+    CREATE TABLE IF NOT EXISTS ${store}.output_files (
       entry_hash  TEXT NOT NULL,
       path        TEXT NOT NULL,
       size_bytes  INTEGER NOT NULL,
       mode        INTEGER NOT NULL,
       mtime_ms    INTEGER NOT NULL,
-      -- v28: the inode and ctime this machine saw after the save or
-      -- restore that left the file equal to the entry; NULL until then.
-      ino         INTEGER,
-      ctime_ms    INTEGER,
       PRIMARY KEY (entry_hash, path),
       FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
     );
+    -- v28, its own table since v32: the inode and ctime THIS workspace saw
+    -- after the save or restore that left the file equal to the entry. No
+    -- row: never current. Apart from output_files because the entry is
+    -- shared and the disk is not: two worktrees on one store overwrote each
+    -- other's stamps, and every switch between them restored. No foreign
+    -- key (the entry may live in another database); a prune and a re-save
+    -- delete what they orphan.
+    CREATE TABLE IF NOT EXISTS main.output_stamps (
+      entry_hash  TEXT NOT NULL,
+      path        TEXT NOT NULL,
+      ino         INTEGER NOT NULL,
+      ctime_ms    INTEGER NOT NULL,
+      PRIMARY KEY (entry_hash, path)
+    );
     -- Each config's ORDERED import closure (the config first), so a warm
     -- load keys it by stat-hashing the list (the file_hashes memo) instead
     -- of reading and scanning every file. Machine-local; pruned with
     -- config_evals (2026-09-03).
-    CREATE TABLE IF NOT EXISTS config_closures (
+    CREATE TABLE IF NOT EXISTS main.config_closures (
       config_path TEXT PRIMARY KEY,
       files_json  TEXT NOT NULL,
       created_at  INTEGER NOT NULL
@@ -190,19 +209,18 @@ export function createTables(db: Database): void {
     -- hit, unchanged mtimes prove the output SET is unchanged, replacing
     -- the glob walk that cost 0.36 ms per hit. Machine-local: a remote
     -- ingest writes none, and the first hit after it walks and records.
-    CREATE TABLE IF NOT EXISTS output_dirs (
+    CREATE TABLE IF NOT EXISTS main.output_dirs (
       entry_hash  TEXT NOT NULL,
       path        TEXT NOT NULL,
       mtime_ms    INTEGER NOT NULL,
-      PRIMARY KEY (entry_hash, path),
-      FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
+      PRIMARY KEY (entry_hash, path)
     );
     -- v22 (Tier 3): one header row per vx-run invocation. The runs
     -- table is per-task; this is the per-invocation record that
     -- carries git/CI/host context, the command, tags, and run-level
     -- counts so the dashboard never reconstructs a header with a
     -- lossy GROUP BY over runs.
-    CREATE TABLE IF NOT EXISTS invocations (
+    CREATE TABLE IF NOT EXISTS main.invocations (
       run_id            TEXT PRIMARY KEY,
       command           TEXT NOT NULL,
       requested_tasks   TEXT NOT NULL,
@@ -233,9 +251,9 @@ export function createTables(db: Database): void {
       vx_version        TEXT NOT NULL,
       tags              TEXT NOT NULL DEFAULT '{}'
     );
-    CREATE INDEX IF NOT EXISTS invocations_started ON invocations(started_at);
-    CREATE INDEX IF NOT EXISTS invocations_branch  ON invocations(branch);
-    CREATE INDEX IF NOT EXISTS invocations_ci      ON invocations(ci);
+    CREATE INDEX IF NOT EXISTS main.invocations_started ON invocations(started_at);
+    CREATE INDEX IF NOT EXISTS main.invocations_branch  ON invocations(branch);
+    CREATE INDEX IF NOT EXISTS main.invocations_ci      ON invocations(ci);
     -- v22 (Tier 3): the input-fingerprint moat. One row per cache-key
     -- component, keyed by the cache-ENTRY hash it belongs to (NOT a
     -- run id). Written inside the entry-save transaction — only on a
@@ -246,7 +264,7 @@ export function createTables(db: Database): void {
     -- SQL over (kind,name,hash); a JSON blob would force an app-side
     -- parse + compare on every probe. ON DELETE CASCADE keeps these
     -- rows in sync with entries (a prune sweeps them automatically).
-    CREATE TABLE IF NOT EXISTS entry_inputs (
+    CREATE TABLE IF NOT EXISTS ${store}.entry_inputs (
       entry_hash TEXT NOT NULL,
       kind       TEXT NOT NULL,
       name       TEXT NOT NULL,
@@ -254,6 +272,13 @@ export function createTables(db: Database): void {
       PRIMARY KEY (entry_hash, kind, name),
       FOREIGN KEY (entry_hash) REFERENCES entries(hash) ON DELETE CASCADE
     );
+    -- v32: what belongs to the entries rather than to one workspace: the
+    -- salt their value digests are taken under, so a digest an entry_inputs
+    -- row holds compares with the one another workspace's run takes.
+    CREATE TABLE IF NOT EXISTS ${store}.store_meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
   `)
 }
 

package/src/cli/info.ts

@@ -91,6 +91,7 @@ export function renderInfo(f: InfoFacts): string {
     ['workers', describeWorkers(f.workers)],
     ['memory', describeMemory(f.memory)],
     ['cache dir', f.cacheDir],
+    ['cache store', f.cacheStore ?? 'none: the cache dir holds the entries'],
     ['cache versions', `keys ${f.cacheVersion} · index schema ${f.schemaVersion}`],
     ['cache entries', `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`],
     // Only when there is something to say.

package/src/cli/workspace-config.ts

@@ -19,12 +19,15 @@ import {
   type ProjectMeta,
   readLockfile,
   resolveCacheDir,
+  resolveStoreRoot,
 } from '../workspace/index.js'
 
 export interface CliWorkspace {
   workspaceConfig: WorkspaceConfig | null
   plugins: readonly VxPlugin[]
   cacheDir: string
+  /** The shared store a run opens `cacheDir` with (`resolveStoreRoot`). */
+  storeRoot: string | null
 }
 
 export const warnToStderr = (message: string): void => {
@@ -33,7 +36,12 @@ export const warnToStderr = (message: string): void => {
 
 export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorkspace> {
   const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warnToStderr)
-  return { workspaceConfig, plugins, cacheDir: resolveCacheDir(workspaceRoot, workspaceConfig) }
+  return {
+    workspaceConfig,
+    plugins,
+    cacheDir: resolveCacheDir(workspaceRoot, workspaceConfig),
+    storeRoot: resolveStoreRoot(workspaceRoot, workspaceConfig),
+  }
 }
 
 /**
@@ -131,7 +139,14 @@ export async function loadCliProjects(
   const cache =
     opts.noCreate === true && !existsSync(cacheDir)
       ? null
-      : new Cache(cacheDir, { read: true, write: true }, workspaceRoot)
+      : new Cache(
+          cacheDir,
+          { read: true, write: true },
+          workspaceRoot,
+          undefined,
+          'open',
+          opts.cacheDir === undefined ? ws.storeRoot : null,
+        )
   if (cache !== null) noteSchemaReset(cache, warnToStderr)
   try {
     const loaded = await loadProjects({

package/src/config.ts

@@ -3,7 +3,11 @@
 export interface WorkspaceConfig {
   /** Maximum concurrent tasks. Defaults to the number of CPUs. */
   concurrency?: number
-  /** Cache directory, relative to the workspace root. Defaults to `.vx/cache`. */
+  /**
+   * Cache directory, relative to the workspace root. Named, it holds the whole
+   * cache and shares nothing; unset, the workspace keeps its index in
+   * `.vx/cache` and its entries in the user's shared store.
+   */
   cacheDir?: string
   /**
    * Default per-task timeout (ms) — the lowest-precedence fallback for a

package/src/orchestrator/doctor.ts

@@ -28,6 +28,7 @@ import {
   lockfilePath,
   type ProjectMeta,
   resolveCacheDir,
+  resolveStoreRoot,
 } from '../workspace/index.js'
 import { flakyTasks, type FlakyTask } from './failure-mode.js'
 import type { VxPlugin } from './plugin.js'
@@ -81,6 +82,8 @@ export interface InfoFacts {
    */
   memory: { usableBytes: number; totalBytes: number; cgroupLimitBytes: number | null }
   cacheDir: string
+  /** The shared store holding the entries, or null when `cacheDir` holds them. */
+  cacheStore: string | null
   cacheVersion: string
   schemaVersion: string
   cacheEntries: number
@@ -149,6 +152,7 @@ async function collectWorkspaceInfo(
       ? resolveCacheDir(root, workspaceConfig)
       : path.resolve(cwd, opts.cacheDir)
   const metas = await discoverProjects(await loadWorkspace(root, reads), plugins, cacheDir, warn)
+  const storeRoot = opts.cacheDir === undefined ? resolveStoreRoot(root, workspaceConfig) : null
   const cache = Cache.inspect(cacheDir)
   noteSchemaReset(cache, warn)
   let stats
@@ -232,6 +236,8 @@ async function collectWorkspaceInfo(
     workers: workersFact(workspaceConfig?.concurrency),
     memory: memoryFact(),
     cacheDir,
+    // The store the index records, else the one a first run would open.
+    cacheStore: cache.storeDir ?? storeRoot,
     // The two versions a bug report needs and the reset notice names: the
     // key prefix (a bump orphans every entry) and the index schema (a
     // mismatch drops every table).

package/src/orchestrator/prepare.ts

@@ -38,6 +38,7 @@ import {
   type Lockfile,
   readLockfile,
   resolveCacheDir,
+  resolveStoreRoot,
   type ProjectEntry,
 } from '../workspace/index.js'
 import {
@@ -215,9 +216,12 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   mark('workspace config')
   // `--cache-dir <path>` (RunOptions.cacheDir) overrides the workspace
   // `cacheDir` field + the `.vx/cache` default; resolved relative to cwd.
+  // A cache dir named anywhere holds everything; the default shares its
+  // entries through the user's store.
   const cacheDir = options.cacheDir
     ? path.resolve(options.cwd, options.cacheDir)
     : resolveCacheDir(workspaceRoot, workspaceConfig)
+  const storeRoot = options.cacheDir ? null : resolveStoreRoot(workspaceRoot, workspaceConfig)
   const projectMetas =
     reused !== undefined
       ? reused.projects
@@ -278,6 +282,8 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     { read: policy.localRead, write: policy.localWrite },
     workspaceRoot,
     options.artifactCeiling,
+    'open',
+    storeRoot,
   )
   localCache.assertWritable()
   noteSchemaReset(localCache, (m) => log.status(m))

package/src/workspace/index.ts

@@ -61,6 +61,7 @@ export {
   memberBaseDirs,
   PROJECT_CONFIG_FILENAMES,
   resolveCacheDir,
+  resolveStoreRoot,
   type ProjectEntry,
   type ProjectMeta,
   type Workspace,

package/src/workspace/repo-id.ts

@@ -0,0 +1,200 @@
+// Which repository a workspace is, so its checkouts share one store under
+// `~/.vx/<id>` and other repositories keep theirs: Nx 23.2's
+// `~/.nx/<id>` (`utils/workspace-id.js`, `utils/git-utils.js`), ported
+// rule for rule (owner, 2026-10-06: "do exactly like nx"), minus the Nx
+// Cloud id. Read from the `.git` files; git is asked only when they cannot
+// settle it (no parseable remote, an `include`, an `insteadOf`).
+
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  statSync,
+} from 'node:fs'
+import path from 'node:path'
+
+/**
+ * 16 hex of sha256 of the repo key, sha256(`<identity>#<workspace path in
+ * the repo>`). The identity is the remote's `host/owner/repo` in lower
+ * case, so ssh, https and token URLs agree; with no remote, the sorted
+ * first root commit; null for a shallow clone with no remote and outside
+ * git: those share nothing.
+ */
+export function repoIdOf(root: string): string | null {
+  const located = locateGitDir(root)
+  if (located === null) return null
+  const identity = remoteIdentity(root, located.commonDir) ?? firstCommit(root)
+  if (identity === null) return null
+  const rel = path.relative(located.gitRoot, path.resolve(root)).split(path.sep).join('/')
+  const key = sha256(`${identity}#${rel}`)
+  return sha256(key).slice(0, 16)
+}
+
+const sha256 = (s: string): string => new Bun.CryptoHasher('sha256').update(s).digest('hex')
+
+interface GitDir {
+  gitRoot: string
+  commonDir: string
+}
+
+/** The repository `dir` is in: walk up to a `.git`; null past one not ours. */
+function locateGitDir(dir: string): GitDir | null {
+  let current = path.resolve(dir)
+  for (;;) {
+    const at = gitDirAt(current)
+    if (at !== undefined) return at
+    const up = path.dirname(current)
+    if (up === current) return null
+    current = up
+  }
+}
+
+/** Undefined with no `.git` here (walk on); null for one vx will not read. */
+function gitDirAt(dir: string): GitDir | null | undefined {
+  const dotGit = path.join(dir, '.git')
+  let entry
+  try {
+    entry = statSync(dotGit)
+  } catch {
+    return undefined
+  }
+  if (entry.isDirectory()) {
+    // A `.git` planted in a world-writable ancestor (`/tmp`) must not name
+    // the repository of everything under it: git's own shape and owner checks.
+    if (!existsSync(path.join(dotGit, 'HEAD')) || !existsSync(path.join(dotGit, 'objects'))) {
+      return null
+    }
+    return ownedRealDir(dotGit) ? { gitRoot: dir, commonDir: dotGit } : null
+  }
+  if (entry.isFile()) {
+    const pointer = /^gitdir:\s*(.+)$/m.exec(readOwnedFile(dotGit) ?? '')
+    if (pointer === null) return null
+    const gitDir = path.resolve(dir, pointer[1]!.trim())
+    const shared = readOwnedFile(path.join(gitDir, 'commondir'))?.trim()
+    const commonDir = shared ? path.resolve(gitDir, shared) : gitDir
+    return ownedRealDir(commonDir) ? { gitRoot: dir, commonDir } : null
+  }
+  return undefined
+}
+
+const ownUid = (): number | undefined => process.getuid?.()
+
+function ownedRealDir(p: string): boolean {
+  try {
+    const st = lstatSync(p)
+    return st.isDirectory() && (ownUid() === undefined || st.uid === ownUid())
+  } catch {
+    return false
+  }
+}
+
+/** A regular file of ours, read without following a link or blocking on a FIFO. */
+function readOwnedFile(p: string): string | null {
+  let fd: number | undefined
+  try {
+    fd = openSync(p, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+    const st = fstatSync(fd)
+    if (!st.isFile() || (ownUid() !== undefined && st.uid !== ownUid())) return null
+    return readFileSync(fd, 'utf8')
+  } catch {
+    return null
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+  }
+}
+
+/** The remote's identity from the config file, else from `git remote -v`. */
+function remoteIdentity(root: string, commonDir: string): string | null {
+  const config = readOwnedFile(path.join(commonDir, 'config'))
+  const remotes = config === null ? null : parseGitConfigRemotes(config)
+  const urls = remotes ?? remotesFromGit(root)
+  const found = new Map<string, string>()
+  let first: string | null = null
+  for (const [name, url] of urls) {
+    const info = parseRemoteUrl(url)
+    if (info !== null && !found.has(name)) {
+      found.set(name, info)
+      first ??= info
+    }
+  }
+  const picked = found.get('origin') ?? found.get('upstream') ?? found.get('base') ?? first
+  return picked === null ? null : picked.toLowerCase().replace(/\/+$/, '')
+}
+
+/**
+ * Remote name → url pairs in file order, or null when the file cannot be
+ * answered for whole: an `include`, a `url "…"` rewrite, or a value git
+ * would unescape or cut at a comment.
+ */
+export function parseGitConfigRemotes(contents: string): [string, string][] | null {
+  const remotes: [string, string][] = []
+  const seen = new Set<string>()
+  let remote: string | null = null
+  for (const raw of contents.split('\n')) {
+    const line = raw.trim()
+    if (line === '' || line.startsWith('#') || line.startsWith(';')) continue
+    if (line.startsWith('[')) {
+      const close = line.indexOf(']')
+      const section = (close === -1 ? line.slice(1) : line.slice(1, close)).trim()
+      if (/^include(If)?\b/i.test(section) || /^url\s+"/i.test(section)) return null
+      remote = /^remote\s+"(.*)"$/i.exec(section)?.[1] ?? null
+      continue
+    }
+    if (remote === null) continue
+    const eq = line.indexOf('=')
+    if (eq === -1 || line.slice(0, eq).trim().toLowerCase() !== 'url') continue
+    const value = line.slice(eq + 1).trim()
+    if (/[#;\\]/.test(value)) return null
+    const url = value.replace(/^"(.*)"$/, '$1')
+    if (url.includes('"')) return null
+    // `remote.<name>.url` is multi-valued; git fetches from the first.
+    if (!seen.has(remote)) {
+      seen.add(remote)
+      remotes.push([remote, url])
+    }
+  }
+  return remotes
+}
+
+function remotesFromGit(root: string): [string, string][] {
+  const out = git(root, ['remote', '-v'])
+  if (out === null) return []
+  const pairs: [string, string][] = []
+  for (const line of out.split('\n')) {
+    const m = /^(\w+)\s+(\S+)\s+\((fetch|push)\)$/.exec(line.trim())
+    if (m !== null) pairs.push([m[1]!, m[2]!])
+  }
+  return pairs
+}
+
+/** `host/owner/repo` for the four url shapes Nx reads; null for the rest. */
+export function parseRemoteUrl(url: string): string | null {
+  const u = url.trim()
+  const m =
+    /^git@([^:]+):([^/]+)\/(.+?)(\.git)?$/.exec(u) ??
+    /^https?:\/\/[^@]+@([^/]+)\/([^/]+)\/(.+?)(\.git)?$/.exec(u) ??
+    /^https?:\/\/([^@/]+)\/([^/]+)\/(.+?)(\.git)?$/.exec(u)
+  if (m !== null) return `${m[1]}/${m[2]}/${m[3]}`
+  const ssh = /^ssh:\/\/[^@]+@([^:/]+)(:[0-9]+)?\/([^/]+)\/(.+?)(\.git)?$/.exec(u)
+  return ssh === null ? null : `${ssh[1]}/${ssh[3]}/${ssh[4]}`
+}
+
+/** The sorted-first root commit, so every clone agrees; null when shallow. */
+function firstCommit(root: string): string | null {
+  if (git(root, ['rev-parse', '--is-shallow-repository'])?.trim() === 'true') return null
+  const roots = git(root, ['rev-list', '--max-parents=0', 'HEAD'])
+  return roots?.split(/\r?\n/).filter(Boolean).sort()[0] ?? null
+}
+
+function git(cwd: string, args: string[]): string | null {
+  try {
+    const p = Bun.spawnSync(['git', ...args], { cwd, stdout: 'pipe', stderr: 'ignore' })
+    return p.exitCode === 0 ? p.stdout.toString() : null
+  } catch {
+    return null
+  }
+}

package/src/workspace/workspace.ts

@@ -1,5 +1,6 @@
 import { constants, type Dirent } from 'node:fs'
 import { access, readdir, realpath, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
 import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
 import {
@@ -13,6 +14,7 @@ import {
   normalizeBunGlob,
 } from '../util/index.js'
 import { type LoadReads, readOnce, unreadable } from './load-reads.js'
+import { repoIdOf } from './repo-id.js'
 
 export interface PackageJson {
   name: string
@@ -349,15 +351,35 @@ function extglobRefusal(pattern: string, file: string, field: string): UserError
 }
 
 /**
- * Resolve the cache directory for a workspace. Respects the user's
- * `defineWorkspace({ cacheDir })` override (relative to the workspace
- * root) and falls back to `.vx/cache` when no config is set.
+ * The workspace's own cache directory (index, history, memos): the
+ * workspace's `cacheDir`, else `VX_CACHE_DIR`, else `.vx/cache`, relative
+ * to the workspace root.
  */
 export function resolveCacheDir(root: string, config: WorkspaceConfig | null): string {
-  const rel = config?.cacheDir ?? path.join('.vx', 'cache')
+  const rel = config?.cacheDir ?? (process.env['VX_CACHE_DIR'] || path.join('.vx', 'cache'))
   return path.resolve(root, rel)
 }
 
+/**
+ * Where this repository's shared store lives: `~/.vx/<repo id>/cache`, as
+ * Nx 23 keeps `~/.nx/<id>/cache` (owner, 2026-10-06), so every checkout of
+ * the repository hits what another saved and no other repository shares
+ * it (`repoIdOf`). Null when the workspace names its cache (`cacheDir`,
+ * `VX_CACHE_DIR`): that directory then holds everything, as one
+ * workspace's alone. Null with no repository identity or no home.
+ */
+export function resolveStoreRoot(root: string, config: WorkspaceConfig | null): string | null {
+  if (config?.cacheDir !== undefined || process.env['VX_CACHE_DIR']) return null
+  // HOME first: Bun's homedir() keeps the HOME the process started with (1.4.2).
+  const home = process.env['HOME'] || homedir()
+  if (!path.isAbsolute(home)) return null
+  let id = repoIds.get(root)
+  if (id === undefined) repoIds.set(root, (id = repoIdOf(root)))
+  return id === null ? null : path.join(home, '.vx', id, 'cache')
+}
+
+const repoIds = new Map<string, string | null>()
+
 /**
  * Read the workspace's package-glob list, supporting all common
  * package managers: