@vzn/vx 0.0.16 → 0.0.21

package/src/cache/layered-cache.ts

@@ -23,6 +23,7 @@ import type {
   CacheLayer,
   CachePolicy,
   CacheStats,
+  CacheStatsOptions,
   IngestMeta,
   InvocationRecord,
   OutputFileRow,
@@ -31,7 +32,7 @@ import type {
   RunRecord,
   SaveArgs,
 } from './cache.js'
-import { FULL_CACHE_POLICY } from './cache.js'
+import { FULL_CACHE_POLICY, type OutputDirRow } from './cache.js'
 
 /**
  * What a remote cache layer must provide — THE plugin seam for remote
@@ -41,8 +42,9 @@ import { FULL_CACHE_POLICY } from './cache.js'
  * policy gating, in-flight dedup, remote provenance, and the never-fail
  * contract (implementations THROW on failure; LayeredCache degrades every
  * throw to a cache miss via `onRemoteError`). The artifact bytes are the
- * local `<hash>.tar.zst` verbatim. See
- * docs/design/native-cache-wire-2026-07.md.
+ * local `<hash>.tar.zst` verbatim. The wires live in plugin packages
+ * (`@vzn/vx-migrate`'s `turboCache()` and `nxCache()`, `@vzn/vx-reapi`); see
+ * docs/modules/layered-cache.md.
  */
 export interface RemoteCacheLayer {
   /** Existence probe (drives the plan path's `--dry` remote prediction). */
@@ -82,6 +84,9 @@ export interface LayeredCacheOptions {
 }
 
 export class LayeredCache implements CacheLayer {
+  /** A remote layer is composed in by construction — see `CacheLayer.hasRemote`. */
+  readonly hasRemote = true
+
   /**
    * In-flight remote pulls keyed by hash. `prefetch` and `get` both go
    * through here, so a key probed concurrently by both resolves a
@@ -118,21 +123,25 @@ export class LayeredCache implements CacheLayer {
   private readonly policy: CachePolicy
 
   constructor(
-    private readonly local: Cache,
+    readonly local: Cache,
     private readonly remote: RemoteCacheLayer,
     private readonly options: LayeredCacheOptions = {},
   ) {
     this.policy = options.policy ?? FULL_CACHE_POLICY
   }
 
-  async key(input: CacheKeyInput): Promise<string> {
-    return await this.local.key(input)
+  key(input: CacheKeyInput): Promise<string> {
+    return this.local.key(input)
   }
 
   async prefetch(hash: string, ctx?: CacheGetContext): Promise<boolean> {
     // No-op when remote reads are off — there's nothing to warm from.
     if (!this.policy.remoteRead) return false
-    return await this.pullFromRemote(hash, ctx)
+    // The local-first skip lives in doPullFromRemote (the shared choke
+    // point): pullFromRemote registers the `inflight` entry SYNCHRONOUSLY,
+    // so a concurrent markRemoteAbsent can't clobber a pending pull — a
+    // guard done here (behind an async local.has) would reopen that race.
+    return this.pullFromRemote(hash, ctx)
   }
 
   /**
@@ -146,6 +155,8 @@ export class LayeredCache implements CacheLayer {
   async remoteHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
     if (!this.policy.remoteRead || this.remote.hasMany === undefined) return null
     try {
+      // `return await`, deliberately: the catch below is the never-fail
+      // contract, and a returned promise's rejection would sail past it.
       return await this.remote.hasMany(hashes)
     } catch (err) {
       this.reportRemoteError(err)
@@ -188,11 +199,23 @@ export class LayeredCache implements CacheLayer {
     const ingested = await this.pullFromRemote(hash, ctx)
     if (!ingested) return null
 
-    // The artifact is now in local, but this *lookup* was a remote
-    // hit — flip the source so callers can distinguish "saved work
-    // via the remote cache" from "saved work via a prior local run".
-    const materialized = await this.local.get(hash, ctx)
-    return materialized ? { ...materialized, source: 'remote' } : null
+    // Read past the local READ gate: `ingest` is deliberately ungated, so
+    // the artifact + index row this pull just wrote exist regardless of
+    // policy, and the gate ("don't serve hits from the pre-existing local
+    // cache") must not discard them. Going through the gated `get` here
+    // made `--cache=local:,remote:rw` download the artifact, throw the hit
+    // away, re-execute and re-upload — on every run, forever.
+    const materialized = await this.local.getIngested(hash)
+    if (!materialized) return null
+
+    // `remoteSourced` — not merely "the pull returned true" — is what says
+    // the remote cache saved this work. `doPullFromRemote` also returns true
+    // for its local-first skip, which issues NO remote GET: when a run
+    // sharing this cache dir ingests the artifact between the local read
+    // above and that skip's `local.has`, stamping 'remote' here reported a
+    // purely-local hit as `cache-hit-remote` and inflated the remote
+    // hit-rate. Whatever provenance the entry has is the truth.
+    return this.remoteSourced.has(hash) ? { ...materialized, source: 'remote' } : materialized
   }
 
   // Existence probe: local first, then a remote HEAD — no body
@@ -226,6 +249,16 @@ export class LayeredCache implements CacheLayer {
   }
 
   private async doPullFromRemote(hash: string, ctx?: CacheGetContext): Promise<boolean> {
+    // Local-first, mirroring get()/has(): if local ALREADY holds the artifact
+    // there is nothing to pull — skip the remote GET (a warm-local run would
+    // otherwise re-download every artifact it already has) and DON'T mark it
+    // `remoteSourced` (that would mislabel a purely-local warm hit as
+    // cache-hit-remote and inflate the remote hit-rate). Returning `true` is
+    // correct for a get() read-through too: "the artifact is in local" — the
+    // caller re-reads it, keeping whatever provenance it already had (local,
+    // or remote if a concurrent prefetch set it).
+    if ((await this.local.has(hash)) === 'local') return true
+
     let remoteResult
     try {
       remoteResult = await this.remote.get(hash)
@@ -265,8 +298,8 @@ export class LayeredCache implements CacheLayer {
     return this.local.outputsPath(hash)
   }
 
-  async hashFile(filePath: string): Promise<string> {
-    return await this.local.hashFile(filePath)
+  hashFile(filePath: string): Promise<string> {
+    return this.local.hashFile(filePath)
   }
 
   async restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
@@ -274,32 +307,48 @@ export class LayeredCache implements CacheLayer {
   }
 
   async save(args: SaveArgs): Promise<void> {
-    // Local write honors its own gate inside Cache.save (no-op when
-    // local writes are disabled).
+    // Local write honors its own gates inside Cache.save (no-op when local
+    // writes are disabled, or when ChainedCache marked this a duplicate save
+    // to a shared local handle — see `skipLocalWrite` on the contract).
     await this.local.save(args)
     if (!this.policy.remoteWrite) return
-    // Write-through upload, OFF the task's critical path. The bytes are
-    // captured NOW — read from the artifact the local layer just wrote
-    // (same format on both sides, no repacking), or, when local writes
-    // are disabled (`--cache=local:,remote:rw`), packed in memory while
-    // the output files are guaranteed still on disk. The PUT itself then
-    // runs in the bounded background pool so the task's worker slot is
-    // released immediately; `run()` awaits `drainUploads()` before
-    // closing the cache. Errors are logged, not propagated: the task
-    // already succeeded; we don't fail it on cache-server issues.
-    let bytes: Uint8Array
-    try {
-      bytes = this.local.localWritesEnabled
-        ? await Bun.file(this.local.outputsPath(args.hash)).bytes()
-        : await this.local.packArtifactBytes(args)
-    } catch (err) {
-      this.reportRemoteError(err)
-      return
-    }
+    // Write-through upload, OFF the task's critical path: the PUT runs in
+    // the bounded background pool so the task's worker slot is released
+    // immediately, and `run()` awaits `drainUploads()` before closing the
+    // cache. Errors are logged, not propagated: the task already
+    // succeeded; we don't fail it on cache-server issues.
+    //
+    // The artifact bytes are read INSIDE the job, not here.
+    // UPLOAD_CONCURRENCY bounds sockets, not memory: a queued closure
+    // holding its own artifact keeps the WHOLE backlog resident, so peak
+    // RSS scaled with a run's total miss artifact bytes rather than with
+    // the pool — any cold monorepo run whose remote uploads slower than the
+    // build produces artifacts held every pending one at once. Reading in
+    // the job caps resident artifact bytes at UPLOAD_CONCURRENCY. The
+    // artifact is content-addressed and immutable, so a deferred read sees
+    // the same bytes; if a concurrent `vx cache prune` removed it first the
+    // read throws and this upload is skipped — the never-fail contract.
+    const hash = args.hash
     const durationMs = args.entry.durationMs
+    // Local writes disabled (`--cache=local:,remote:rw`): there is no
+    // on-disk artifact to read later, so the bytes must be packed NOW,
+    // while this task's output files are still on disk. Deferring THIS
+    // read would pack whatever the tree happens to hold when the job
+    // runs. Such a run keeps the old memory profile by necessity — the
+    // bytes exist nowhere else.
+    let packed: Uint8Array | undefined
+    if (!this.local.localWritesEnabled) {
+      try {
+        packed = await this.local.packArtifactBytes(args)
+      } catch (err) {
+        this.reportRemoteError(err)
+        return
+      }
+    }
     this.enqueueUpload(async () => {
       try {
-        await this.remote.put(args.hash, bytes, { durationMs })
+        const bytes = packed ?? (await Bun.file(this.local.outputsPath(hash)).bytes())
+        await this.remote.put(hash, bytes, { durationMs })
       } catch (err) {
         this.reportRemoteError(err)
       }
@@ -352,24 +401,28 @@ export class LayeredCache implements CacheLayer {
     return this.local.isOutputsCurrent(projectDir, expected)
   }
 
-  recordRun(run: RunRecord): void {
-    this.local.recordRun(run)
+  recordOutputDirs(hash: string, projectDir: string, prefixes: readonly string[]): Promise<void> {
+    return this.local.recordOutputDirs(hash, projectDir, prefixes)
+  }
+
+  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
+    return this.local.loadOutputDirsBatch(hashes)
   }
 
-  recordRuns(runs: readonly RunRecord[]): void {
-    this.local.recordRuns(runs)
+  outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
+    return this.local.outputDirsCurrent(projectDir, rows)
   }
 
   recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void {
     this.local.recordRunBundle(bundle)
   }
 
-  stats(): CacheStats {
-    return this.local.stats()
+  stats(opts?: CacheStatsOptions): CacheStats {
+    return this.local.stats(opts)
   }
 
-  async prune(options: PruneOptions): Promise<PruneResult> {
-    return await this.local.prune(options)
+  prune(options: PruneOptions): Promise<PruneResult> {
+    return this.local.prune(options)
   }
 
   close(): void {

package/src/cache/output-index.ts

@@ -0,0 +1,224 @@
+// The output fingerprint index: per-entry `output_files` rows (size, mode,
+// millisecond mtime) 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
+// transaction.
+
+/** `mtime_ms` of a recorded output prefix that did not exist when the snapshot was taken. */
+const ABSENT_DIR_MTIME = -1
+
+import type { Database, SQLQueryBindings } from 'bun:sqlite'
+import { lstatSync, statSync } from 'node:fs'
+import { lstat, readdir } from 'node:fs/promises'
+import path from 'node:path'
+import {
+  OUTPUT_DIRS_CAP,
+  OUTPUT_DIRS_RACY_MS,
+  type OutputDirRow,
+  type OutputFileRow,
+} from './layer.js'
+
+export class OutputIndex {
+  private readonly insertOutputFile: ReturnType<Database['prepare']>
+  private readonly deleteOutputFiles: ReturnType<Database['prepare']>
+  private readonly insertOutputDir: ReturnType<Database['prepare']>
+  private readonly deleteOutputDirs: ReturnType<Database['prepare']>
+
+  constructor(private readonly db: Database) {
+    this.insertOutputFile = this.db.prepare(`
+      INSERT INTO output_files(entry_hash, path, size_bytes, mode, mtime_ms)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(entry_hash, path) DO UPDATE SET
+        size_bytes = excluded.size_bytes,
+        mode       = excluded.mode,
+        mtime_ms   = excluded.mtime_ms
+    `)
+    this.deleteOutputFiles = this.db.prepare('DELETE FROM output_files WHERE entry_hash = ?')
+    this.insertOutputDir = this.db.prepare(
+      'INSERT INTO output_dirs(entry_hash, path, mtime_ms) VALUES (?, ?, ?)',
+    )
+    this.deleteOutputDirs = this.db.prepare('DELETE FROM output_dirs WHERE entry_hash = ?')
+  }
+
+  /**
+   * Replace an entry's file rows. Called INSIDE the store's save transaction,
+   * so an entry and its fingerprints land together (an UPDATE on the same
+   * hash refreshes rather than appends).
+   */
+  replaceFileRows(hash: string, rows: ReadonlyArray<[string, number, number, number]>): void {
+    this.deleteOutputFiles.run(hash)
+    for (const [rel, size, mode, mtime] of rows) {
+      this.insertOutputFile.run(hash, rel, size, mode, mtime)
+    }
+  }
+
+  loadOutputFilesBatch(hashes: readonly string[]): Map<string, OutputFileRow[]> {
+    const out = new Map<string, OutputFileRow[]>()
+    if (hashes.length === 0) return out
+    // Inline placeholders for an IN-list — bun:sqlite doesn't ship
+    // rarray, but `IN (?, ?, …)` with N≤~999 is fast and avoids per-
+    // hash select.get() overhead. `db.query` (not `db.prepare`) caches the
+    // compiled statement keyed by the SQL text — so the dominant single-hash
+    // warm-hit path (called up to 3× per hit) reuses one statement instead of
+    // recompiling on every call.
+    const placeholders = hashes.map(() => '?').join(',')
+    const stmt = this.db.query(
+      `SELECT entry_hash, path, size_bytes, mode, mtime_ms FROM output_files WHERE entry_hash IN (${placeholders})`,
+    )
+    const rows = stmt.all(...(hashes as readonly SQLQueryBindings[])) as Array<{
+      entry_hash: string
+      path: string
+      size_bytes: number
+      mode: number
+      mtime_ms: number
+    }>
+    for (const r of rows) {
+      let list = out.get(r.entry_hash)
+      if (!list) {
+        list = []
+        out.set(r.entry_hash, list)
+      }
+      list.push({ path: r.path, size: r.size_bytes, mode: r.mode, mtimeMs: r.mtime_ms })
+    }
+    return out
+  }
+
+  async isOutputsCurrent(projectDir: string, expected: readonly OutputFileRow[]): Promise<boolean> {
+    // Empty manifest case (a task produced no outputs) → trivially
+    // current; the on-disk tree under projectDir is whatever it was,
+    // and nothing was supposed to land there.
+    if (expected.length === 0) return true
+    // statSync, deliberately. The async form measured faster on 2026-09-02,
+    // when a hit walked its whole output tree; since the directory
+    // short-circuit (`outputDirsCurrent`) a warm hit stats a handful of
+    // paths, and each async stat costs a thread-pool round trip the
+    // scheduler cannot overlap away (its concurrency is the worker count).
+    // Re-measured 2026-09-09, 1,000 warm hits, interleaved A/B: the run
+    // graph stage 100 → 54 ms, the whole process 422 → 368 ms.
+    const results = expected.map((e) => {
+      try {
+        const s = statSync(path.join(projectDir, e.path))
+        return (
+          s.size === e.size &&
+          (s.mode & 0o777) === (e.mode & 0o777) &&
+          // 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,
+          // so equality holds exactly in steady state; legacy
+          // second-precision rows converge on their first restore.
+          // Residual blind spot: a same-size edit landing in the SAME
+          // millisecond as the recorded write, or a deliberately
+          // forged mtime (touch -r) — the trade every mtime-based
+          // skip check accepts.
+          Math.abs(s.mtimeMs - e.mtimeMs) < 1
+        )
+      } catch {
+        return false
+      }
+    })
+    return results.every(Boolean)
+  }
+
+  /**
+   * Snapshot every directory under each of `prefixes` for `hash`. Called
+   * after a save and after a restore, when the tree is known to equal the
+   * entry's set. Symlinked directories are not descended (the output walk
+   * refuses them too). Over `OUTPUT_DIRS_CAP` directories, or on any
+   * error, the rows are cleared and the next hit keeps the walk.
+   */
+  async recordOutputDirs(
+    hash: string,
+    projectDir: string,
+    prefixes: readonly string[],
+  ): Promise<void> {
+    const rows: Array<[string, number]> = []
+    const walk = async (rel: string, isPrefix = false): Promise<boolean> => {
+      const abs = path.join(projectDir, rel)
+      let st
+      try {
+        st = await lstat(abs)
+      } catch {
+        // A declared prefix the task never produced (`build/**` beside
+        // `dist/**`, medusa's `.medusa/**`) is recorded ABSENT: the check
+        // then asks that it still not exist. Refusing the snapshot instead
+        // made every such task re-glob its outputs on every warm hit — all
+        // 83 of medusa's, 210 ms of a 2.5 s no-op (2026-09-11).
+        if (isPrefix) {
+          rows.push([rel, ABSENT_DIR_MTIME])
+          return true
+        }
+        return false
+      }
+      if (!st.isDirectory()) return false
+      rows.push([rel, st.mtimeMs])
+      if (rows.length > OUTPUT_DIRS_CAP) return false
+      let entries
+      try {
+        entries = await readdir(abs, { withFileTypes: true })
+      } catch {
+        return false
+      }
+      for (const e of entries) {
+        if (e.isDirectory() && !e.isSymbolicLink()) {
+          if (!(await walk(`${rel}/${e.name}`))) return false
+        }
+      }
+      return true
+    }
+    let ok = true
+    for (const prefix of prefixes) {
+      if (!(await walk(prefix, true))) {
+        ok = false
+        break
+      }
+    }
+    // All or nothing: a racy directory dropped alone would leave its
+    // parent trusted while an addition inside it bumps only the dropped one.
+    const youngest = Date.now() - OUTPUT_DIRS_RACY_MS
+    if (rows.some(([, mtime]) => mtime > youngest)) ok = false
+    this.db.transaction(() => {
+      this.deleteOutputDirs.run(hash)
+      if (!ok) return
+      for (const [rel, mtime] of rows) this.insertOutputDir.run(hash, rel, mtime)
+    })()
+  }
+
+  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
+    const out = new Map<string, OutputDirRow[]>()
+    if (hashes.length === 0) return out
+    const placeholders = hashes.map(() => '?').join(',')
+    const rows = this.db
+      .query(
+        `SELECT entry_hash, path, mtime_ms FROM output_dirs WHERE entry_hash IN (${placeholders})`,
+      )
+      .all(...(hashes as readonly SQLQueryBindings[])) as Array<{
+      entry_hash: string
+      path: string
+      mtime_ms: number
+    }>
+    for (const r of rows) {
+      const list = out.get(r.entry_hash)
+      const row = { path: r.path, mtimeMs: r.mtime_ms }
+      if (list) list.push(row)
+      else out.set(r.entry_hash, [row])
+    }
+    return out
+  }
+
+  /** True iff every recorded directory exists with its recorded mtime (ms). Same forged-mtime trade as the file check. */
+  async outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
+    if (rows.length === 0) return false
+    const results = rows.map((r) => {
+      let st
+      try {
+        st = lstatSync(path.join(projectDir, r.path))
+      } catch {
+        return r.mtimeMs === ABSENT_DIR_MTIME
+      }
+      if (r.mtimeMs === ABSENT_DIR_MTIME) return false
+      return st.isDirectory() && Math.abs(st.mtimeMs - r.mtimeMs) < 1
+    })
+    return results.every(Boolean)
+  }
+}

package/src/cache/policy.ts

@@ -0,0 +1,84 @@
+// The run-level cache policy: four axes (local/remote × read/write) and
+// the `--cache=<spec>` grammar that sets them. Pure data + parsing; no I/O.
+
+import { UserError } from '../util/index.js'
+
+/**
+ * Independent read/write control over the two cache layers (local +
+ * remote). Replaces the old single `noCache` boolean: each axis can be
+ * toggled on its own so `--force` (re-execute but still refresh the
+ * cache) is distinct from `--no-cache` (disable everything).
+ *
+ * Only the task-artifact get/save path is gated. `recordRun`, `stats`,
+ * `prune`, key derivation, and prefetch-ingest are never affected — they
+ * are bookkeeping/analytics that a run policy has no business disabling.
+ */
+export interface CachePolicy {
+  localRead: boolean
+  localWrite: boolean
+  remoteRead: boolean
+  remoteWrite: boolean
+}
+
+/** All four axes on — the default when no cache flag is passed. */
+export const FULL_CACHE_POLICY: CachePolicy = {
+  localRead: true,
+  localWrite: true,
+  remoteRead: true,
+  remoteWrite: true,
+}
+
+/**
+ * Parse a `--cache=<spec>` value into a `CachePolicy`, starting from a
+ * base (defaults to {@link FULL_CACHE_POLICY}). The spec is a
+ * comma-separated list of `layer:flags` segments where `layer` is
+ * `local` or `remote` and `flags` is any subset of `r` (read) and `w`
+ * (write), order-independent and possibly empty.
+ *
+ * A mentioned layer is set EXACTLY to its flags (read = includes `r`,
+ * write = includes `w`); an unmentioned layer keeps its base value.
+ * So `local:rw,remote:r` = remote read-only, `remote:` = remote fully
+ * off, `local:r` = local read-only with remote untouched.
+ *
+ * Throws a {@link UserError} on an unknown layer, an unknown flag, a
+ * duplicated flag, a missing colon, or a repeated layer.
+ */
+export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_POLICY): CachePolicy {
+  const out: CachePolicy = { ...base }
+  const seen = new Set<string>()
+  for (const rawSeg of spec.split(',')) {
+    const seg = rawSeg.trim()
+    if (seg.length === 0) continue
+    const colon = seg.indexOf(':')
+    if (colon < 0) {
+      throw new UserError(`invalid --cache segment '${seg}': expected '<layer>:<flags>'`)
+    }
+    const layer = seg.slice(0, colon)
+    const flags = seg.slice(colon + 1)
+    if (layer !== 'local' && layer !== 'remote') {
+      throw new UserError(`invalid --cache layer '${layer}': expected 'local' or 'remote'`)
+    }
+    if (seen.has(layer)) {
+      throw new UserError(`--cache layer '${layer}' specified twice`)
+    }
+    seen.add(layer)
+    const flagSet = new Set<string>()
+    for (const ch of flags) {
+      if (ch !== 'r' && ch !== 'w') {
+        throw new UserError(`invalid --cache flag '${ch}' for '${layer}': expected 'r' and/or 'w'`)
+      }
+      if (flagSet.has(ch)) {
+        throw new UserError(`--cache flag '${ch}' repeated for '${layer}'`)
+      }
+      flagSet.add(ch)
+    }
+    if (layer === 'local') {
+      out.localRead = flagSet.has('r')
+      out.localWrite = flagSet.has('w')
+    } else {
+      out.remoteRead = flagSet.has('r')
+      out.remoteWrite = flagSet.has('w')
+    }
+  }
+  return out
+}