@vzn/vx 0.0.636 → 0.0.637

package/src/cache/policy.ts

@@ -1,5 +1,5 @@
 // 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.
+// the `--cache-policy=<spec>` grammar that sets them. Pure data + parsing; no I/O.
 
 import { UserError } from '../util/index.js'
 
@@ -10,8 +10,7 @@ import { UserError } from '../util/index.js'
  * cache) is distinct from `--no-cache` (disable everything).
  *
  * The task-artifact get/save path is gated, and the local axes also gate
- * the local store's config-evaluation reads and writes and its file-hash
- * writes (`cache.ts`). `recordRun`, `stats`, `prune`, key derivation, and
+ * the local store's file-hash writes (`cache.ts`). `recordRun`, `stats`, `prune`, key derivation, and
  * prefetch-ingest are never affected — they are bookkeeping/analytics
  * that a run policy has no business disabling.
  */
@@ -20,12 +19,6 @@ export interface CachePolicy {
   localWrite: boolean
   remoteRead: boolean
   remoteWrite: boolean
-  /**
-   * An untrusted scope (`cacheScope: 'pr-123'`): remote reads try this
-   * scope's keys, then the trusted ones; remote writes go to this scope's
-   * keys only. Absent = trusted. See {@link scopeCachePolicy}.
-   */
-  remoteScope?: string
 }
 
 /** All four axes on — the default when no cache flag is passed. */
@@ -36,13 +29,13 @@ export const FULL_CACHE_POLICY: CachePolicy = {
   remoteWrite: true,
 }
 
-/** No axis on (`--no-cache`, `--cache=local:`): no cache answers for any task. */
+/** No axis on (`--no-cache`, `--cache-policy=local:`): no cache answers for any task. */
 export function cachesNothing(p: CachePolicy): boolean {
   return !(p.localRead || p.localWrite || p.remoteRead || p.remoteWrite)
 }
 
 /**
- * Parse a `--cache=<spec>` value into a `CachePolicy`, starting from a
+ * Parse a `--cache-policy=<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`
@@ -53,7 +46,8 @@ export function cachesNothing(p: CachePolicy): boolean {
  * 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
+ * Throws a {@link UserError}, whose message the caller prefixes with the
+ * spec's source (`--cache-policy`, `VX_CACHE_POLICY`, `cache.policy`), 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 {
@@ -64,24 +58,24 @@ export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_PO
     if (seg.length === 0) continue
     const colon = seg.indexOf(':')
     if (colon < 0) {
-      throw new UserError(`invalid --cache segment '${seg}': expected '<layer>:<flags>'`)
+      throw new UserError(`invalid 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'`)
+      throw new UserError(`invalid layer '${layer}': expected 'local' or 'remote'`)
     }
     if (seen.has(layer)) {
-      throw new UserError(`--cache layer '${layer}' specified twice`)
+      throw new UserError(`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'`)
+        throw new UserError(`invalid flag '${ch}' for '${layer}': expected 'r' and/or 'w'`)
       }
       if (flagSet.has(ch)) {
-        throw new UserError(`--cache flag '${ch}' repeated for '${layer}'`)
+        throw new UserError(`flag '${ch}' repeated for '${layer}'`)
       }
       flagSet.add(ch)
     }
@@ -96,16 +90,18 @@ export function parseCachePolicy(spec: string, base: CachePolicy = FULL_CACHE_PO
   return out
 }
 
-/**
- * Apply a workspace's `cacheScope` to the run's policy. `'trusted'` (or
- * none) changes nothing; `'read-only'` turns remote writes off; any other
- * name is an untrusted scope. A clamp, never a widening: `--cache` still
- * decides which axes are on. A client-side convention, not a boundary —
- * any run holding a write credential can write a trusted key; only the
- * cache server, by token, can refuse it (docs/security.md).
- */
-export function scopeCachePolicy(policy: CachePolicy, scope: string | undefined): CachePolicy {
-  if (scope === undefined || scope === 'trusted') return policy
-  if (scope === 'read-only') return { ...policy, remoteWrite: false }
-  return { ...policy, remoteScope: scope }
+/** `--no-cache` and `--force`, which still apply over whichever spec set the base. */
+export interface CacheFlags {
+  /** `--no-cache`: every axis off. Beats `force`. */
+  noCache?: boolean
+  /** `--force`: both reads off, writes kept. */
+  force?: boolean
+}
+
+export function applyCacheFlags(policy: CachePolicy, flags: CacheFlags | undefined): CachePolicy {
+  if (flags?.noCache === true) {
+    return { localRead: false, localWrite: false, remoteRead: false, remoteWrite: false }
+  }
+  if (flags?.force === true) return { ...policy, localRead: false, remoteRead: false }
+  return policy
 }

package/src/cache/run-history.ts

@@ -31,8 +31,13 @@ function insertRunsSql(n: number): string {
  */
 const RUNS_PER_INSERT = 40
 
+/** Rows per `task_durations` INSERT: 6 variables each, under 999. */
+const DURATIONS_PER_INSERT = 160
+
+/** A local run's `task_durations.source`: its branch, `''` when it had none. */
+export const branchSource = (branch: string | null): string => `branch:${branch ?? ''}`
+
 export class RunHistory {
-  private readonly insertRun: ReturnType<Database['prepare']>
   private readonly insertInvocation: ReturnType<Database['prepare']>
 
   constructor(
@@ -40,7 +45,6 @@ export class RunHistory {
     /** The store's salted value digest (L-4). */
     private readonly digestValue: (value: string) => string,
   ) {
-    this.insertRun = lazyStatement(this.db, insertRunsSql(1))
     this.insertInvocation = lazyStatement(
       this.db,
       `
@@ -60,18 +64,34 @@ export class RunHistory {
   }
 
   recordRun(run: RunRecord): void {
-    this.insertRun.run(...bindRun(run, this.digestValue))
+    this.recordRuns([run])
   }
 
   recordRuns(runs: readonly RunRecord[]): void {
     if (runs.length === 0) return
-    if (runs.length === 1) {
-      this.insertRun.run(...bindRun(runs[0]!, this.digestValue))
-      return
-    }
     // One transaction, one fsync: for a 200-task run, one instead of 200.
     // IMMEDIATE, as `recordRunBundle` explains.
-    this.db.transaction(() => this.insertRuns(runs)).immediate()
+    this.db
+      .transaction(() => {
+        this.insertRuns(runs)
+        this.insertDurations(runs, branchSource(null), null)
+      })
+      .immediate()
+  }
+
+  /** One `task_durations` row per executed success: what a forecast reads. */
+  private insertDurations(runs: readonly RunRecord[], source: string, sha: string | null): void {
+    const done = runs.filter((r) => r.status === 'success' && r.cacheHit !== true)
+    for (let i = 0; i < done.length; i += DURATIONS_PER_INSERT) {
+      const block = done.slice(i, i + DURATIONS_PER_INSERT)
+      const params: SQLQueryBindings[] = []
+      for (const r of block) params.push(r.project, r.task, source, sha, r.durationMs, r.endedAt)
+      this.db
+        .query(
+          `INSERT INTO task_durations(project, task, source, sha, duration_ms, recorded_at) VALUES ${Array(block.length).fill('(?, ?, ?, ?, ?, ?)').join(', ')}`,
+        )
+        .run(...params)
+    }
   }
 
   /** `runs` as few INSERTs; each distinct forward-args list digested once. */
@@ -109,6 +129,11 @@ export class RunHistory {
       .transaction(() => {
         this.insertRuns(bundle.runs)
         this.insertInvocation.run(...bindInvocation(bundle.invocation))
+        this.insertDurations(
+          bundle.runs,
+          branchSource(bundle.invocation.branch),
+          bundle.invocation.commitSha,
+        )
       })
       .immediate()
   }
@@ -116,21 +141,18 @@ export class RunHistory {
   /**
    * Retention: the runs table grows by one row per executed task per
    * invocation — a 2000-task repo accretes ~20k rows in days. 30 days
-   * covers `vx stats` (24 h windows) and CI-side consumers. The
+   * covers `vx info` (24 h windows) and CI-side consumers. The
    * `invocations` header is pruned on the SAME window, or a header would
    * outlive its rows and `vx last` would list a run whose detail is gone.
    */
   pruneOlderThan(cutoff: number): void {
     this.db.prepare('DELETE FROM runs WHERE started_at < ?').run(cutoff)
     this.db.prepare('DELETE FROM invocations WHERE started_at < ?').run(cutoff)
+    this.db.prepare('DELETE FROM task_durations WHERE recorded_at < ?').run(cutoff)
   }
 }
 
-/**
- * Bind a RunRecord to the positional parameters expected by the
- * `insertRun` prepared statement (22 columns). Shared between the
- * single and batched record paths.
- */
+/** Bind a RunRecord to one `RUN_TUPLE`'s 22 positional parameters. */
 function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
   return [
     // The ONE place the no-key sentinel is applied, so the column's

package/src/cache/schema.ts

@@ -1,7 +1,7 @@
 // The index's tables, one concern: what a cache.db holds. `Cache` opens the
 // file, checks `SCHEMA_VERSION` and creates these; every statement against
-// them lives in the store that owns the table (file-hashes, config-evals,
-// output-index, history) or in cache.ts for `entries`, `entry_inputs` and
+// them lives in the store that owns the table (file-hashes, output-index,
+// history) or in cache.ts for `entries`, `entry_inputs` and
 // `artifacts`.
 
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
@@ -22,7 +22,8 @@ export function lazyStatement(db: Database, sql: string): ReturnType<Database['p
 
 /**
  * Create every table. `store` names the schema holding the ENTRY tables
- * (`entries`, `entry_stdout`, `output_files`, `entry_inputs`, `store_meta`):
+ * (`entries`, `entry_stdout`, `output_files`, `entry_inputs`, `store_meta`)
+ * and the task timings (`task_durations`):
  * `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
@@ -30,17 +31,6 @@ export function lazyStatement(db: Database, sql: string): ReturnType<Database['p
  * 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 main.config_evals (
-      key        TEXT PRIMARY KEY,
-      json       TEXT NOT NULL,
-      created_at INTEGER NOT NULL
-    );
-  `)
-
   db.exec(`
     -- The queryable index: command, exit_code, duration, size and
     -- timestamps; stdout in entry_stdout below.
@@ -197,15 +187,6 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       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 main.config_closures (
-      config_path TEXT PRIMARY KEY,
-      files_json  TEXT NOT NULL,
-      created_at  INTEGER NOT NULL
-    );
     -- Every directory under a whole-subtree output glob, with its mtime
     -- as of the last save/restore on THIS machine (2026-09-03). On a warm
     -- hit, unchanged mtimes prove the output SET is unchanged, replacing
@@ -277,6 +258,23 @@ export function createTables(db: Database, store: 'main' | 'store' = 'main'): vo
       key   TEXT PRIMARY KEY,
       value TEXT NOT NULL
     );
+    -- What a duration forecast reads (orchestrator/history.ts), one row per
+    -- executed success, shared by every worktree of the repo so a new one
+    -- forecasts on its first run (owner, 2026-10-14). Append-only: never
+    -- updated, pruned by age with the run history. \`source\` tags a local
+    -- run 'branch:<name>' ('branch:' detached or outside git); \`sha\` is its
+    -- commit. A forecast reads a task's newest rows of one source.
+    CREATE TABLE IF NOT EXISTS ${store}.task_durations (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      project     TEXT NOT NULL,
+      task        TEXT NOT NULL,
+      source      TEXT NOT NULL,
+      sha         TEXT,
+      duration_ms INTEGER NOT NULL,
+      recorded_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS ${store}.task_durations_task
+      ON task_durations(project, task, source, id);
     ${artifactTables(store)}
   `)
 }

package/src/cache/scoped-cache.ts

@@ -0,0 +1,224 @@
+// The run's `cache.scope` over every layer at once (owner, 2026-10-14): a
+// scoped run reads the default key, then the scope's, and writes only the
+// scope's, in the local store and every remote alike. Below this wrapper no
+// layer knows a scope exists: the scope's key is a key like any other.
+
+import { xxh3hex } from '../util/index.js'
+import type {
+  CacheEntry,
+  CacheGetContext,
+  CacheLayer,
+  IngestMeta,
+  InvocationRecord,
+  OutputDirRow,
+  RunRecord,
+  SaveArgs,
+} from './layer.js'
+
+/** The key a scope stores `hash` under: task-key shaped, 16 hex, so every wire stores it unchanged. */
+function scopedKey(scope: string, hash: string): string {
+  return xxh3hex(`vx-cache-scope\0${scope}\0${hash}`)
+}
+
+/**
+ * A layer as a scoped run sees it. Callers speak task keys; each answer is
+ * remembered under the key that served it (the default key on a default hit,
+ * the scope's on a scope hit or a save), so the restore, the output index and
+ * the run's history all reach the entry that answered. An artifact records
+ * the key it was packed under and ingest refuses another, so a derived-key
+ * collision degrades to a miss. A default artifact a remote ingest refuses is
+ * a miss there, and the scope's key is asked next (Security F6).
+ */
+export class ScopedCache implements CacheLayer {
+  readonly local?: CacheLayer['local']
+  readonly hasRemote?: boolean
+  readonly drainUploads?: () => Promise<void>
+  readonly remoteHasMany?: (hashes: readonly string[]) => Promise<Set<string> | null>
+  readonly getMany?: (
+    hashes: readonly string[],
+    ctx?: (hash: string) => CacheGetContext,
+  ) => Promise<Map<string, CacheEntry>>
+  /** Task key → the key that answers for it this run. */
+  private readonly served = new Map<string, string>()
+
+  constructor(
+    private readonly inner: CacheLayer,
+    private readonly scope: string,
+  ) {
+    if (inner.local !== undefined) this.local = inner.local
+    if (inner.hasRemote !== undefined) this.hasRemote = inner.hasRemote
+    if (inner.drainUploads !== undefined) this.drainUploads = () => inner.drainUploads!()
+    if (inner.remoteHasMany !== undefined) this.remoteHasMany = (h) => this.scopedHasMany(h)
+    if (inner.getMany !== undefined) this.getMany = (h, ctx) => this.scopedGetMany(h, ctx)
+  }
+
+  private own(hash: string): string {
+    return scopedKey(this.scope, hash)
+  }
+
+  private keyOf(hash: string): string {
+    return this.served.get(hash) ?? hash
+  }
+
+  /** A batch keyed by served keys, keyed back by task key. */
+  private batch<T>(
+    hashes: readonly string[],
+    read: (keys: string[]) => Map<string, T>,
+  ): Map<string, T> {
+    const keys = hashes.map((h) => this.keyOf(h))
+    const found = read(keys)
+    const out = new Map<string, T>()
+    for (let i = 0; i < hashes.length; i++) {
+      const v = found.get(keys[i]!)
+      if (v !== undefined) out.set(hashes[i]!, v)
+    }
+    return out
+  }
+
+  private async scopedHasMany(hashes: readonly string[]): Promise<Set<string> | null> {
+    const scoped = hashes.map((h) => this.own(h))
+    const [plain, own] = await Promise.all([
+      this.inner.remoteHasMany!(hashes),
+      this.inner.remoteHasMany!(scoped),
+    ])
+    if (plain == null || own == null) return null
+    const found = new Set(plain)
+    const scopeOnly: string[] = []
+    for (let i = 0; i < hashes.length; i++) {
+      if (plain.has(hashes[i]!) || !own.has(scoped[i]!)) continue
+      found.add(hashes[i]!)
+      scopeOnly.push(hashes[i]!)
+    }
+    // Their default key is known absent: its GET is skipped.
+    this.inner.markRemoteAbsent?.(scopeOnly)
+    return found
+  }
+
+  markRemoteAbsent(hashes: Iterable<string>): void {
+    const all: string[] = []
+    for (const h of hashes) all.push(h, this.own(h))
+    this.inner.markRemoteAbsent?.(all)
+  }
+
+  key(input: Parameters<CacheLayer['key']>[0]): Promise<string> {
+    return this.inner.key(input)
+  }
+
+  async get(hash: string, ctx?: CacheGetContext): Promise<CacheEntry | null> {
+    for (const key of [hash, this.own(hash)]) {
+      const entry = await this.inner.get(key, ctx)
+      if (entry === null) continue
+      this.served.set(hash, key)
+      return key === hash ? entry : { ...entry, hash }
+    }
+    return null
+  }
+
+  private async scopedGetMany(
+    hashes: readonly string[],
+    ctx?: (hash: string) => CacheGetContext,
+  ): Promise<Map<string, CacheEntry>> {
+    const out = await this.inner.getMany!(hashes, ctx)
+    for (const h of out.keys()) this.served.set(h, h)
+    const rest = hashes.filter((h) => !out.has(h))
+    if (rest.length === 0) return out
+    const byOwn = new Map(rest.map((h) => [this.own(h), h]))
+    const scoped = await this.inner.getMany!(
+      [...byOwn.keys()],
+      ctx === undefined ? undefined : (key) => ctx(byOwn.get(key)!),
+    )
+    for (const [key, entry] of scoped) {
+      const hash = byOwn.get(key)!
+      this.served.set(hash, key)
+      out.set(hash, { ...entry, hash })
+    }
+    return out
+  }
+
+  async has(hash: string): Promise<'local' | 'remote' | null> {
+    return (await this.inner.has(hash)) ?? (await this.inner.has(this.own(hash)))
+  }
+
+  async prefetch(hash: string, ctx?: CacheGetContext): Promise<boolean> {
+    return (await this.inner.prefetch(hash, ctx)) || this.inner.prefetch(this.own(hash), ctx)
+  }
+
+  loadOutputFilesBatch(hashes: readonly string[]): ReturnType<CacheLayer['loadOutputFilesBatch']> {
+    return this.batch(hashes, (keys) => this.inner.loadOutputFilesBatch(keys))
+  }
+
+  isOutputsCurrent(
+    ...args: Parameters<CacheLayer['isOutputsCurrent']>
+  ): ReturnType<CacheLayer['isOutputsCurrent']> {
+    return this.inner.isOutputsCurrent(...args)
+  }
+
+  async recordOutputDirs(
+    hash: string,
+    projectDir: string,
+    prefixes: readonly string[],
+    holds?: (files: readonly string[]) => boolean,
+  ): Promise<void> {
+    await this.inner.recordOutputDirs?.(this.keyOf(hash), projectDir, prefixes, holds)
+  }
+
+  recordOutputStamps(hash: string, projectDir: string, workspaceRoot: string): void {
+    this.inner.recordOutputStamps?.(this.keyOf(hash), projectDir, workspaceRoot)
+  }
+
+  loadOutputDirsBatch(hashes: readonly string[]): Map<string, OutputDirRow[]> {
+    return this.batch(hashes, (keys) => this.inner.loadOutputDirsBatch?.(keys) ?? new Map())
+  }
+
+  async outputDirsCurrent(projectDir: string, rows: readonly OutputDirRow[]): Promise<boolean> {
+    return (await this.inner.outputDirsCurrent?.(projectDir, rows)) ?? false
+  }
+
+  restoreOutputs(hash: string, projectDir: string, workspaceRoot?: string): Promise<void> {
+    return this.inner.restoreOutputs(this.keyOf(hash), projectDir, workspaceRoot)
+  }
+
+  save(args: SaveArgs): Promise<void> {
+    const key = this.own(args.hash)
+    this.served.set(args.hash, key)
+    return this.inner.save({ ...args, hash: key })
+  }
+
+  ingest(hash: string, body: Blob | Response, meta: IngestMeta): Promise<void> {
+    const key = this.own(hash)
+    this.served.set(hash, key)
+    return this.inner.ingest(key, body, meta)
+  }
+
+  /** History names the key that answered, so `vx why` reads that entry's components. */
+  recordRunBundle(bundle: { runs: readonly RunRecord[]; invocation: InvocationRecord }): void {
+    this.inner.recordRunBundle({
+      ...bundle,
+      runs: bundle.runs.map((r) => (r.hash === undefined ? r : { ...r, hash: this.keyOf(r.hash) })),
+    })
+  }
+
+  stats(...args: Parameters<CacheLayer['stats']>): ReturnType<CacheLayer['stats']> {
+    return this.inner.stats(...args)
+  }
+
+  hashFile(filePath: string): Promise<string> {
+    return this.inner.hashFile(filePath)
+  }
+
+  outputsPath(hash: string): string {
+    return this.inner.outputsPath(this.keyOf(hash))
+  }
+
+  artifactSize(hash: string): number | undefined {
+    return this.inner.artifactSize?.(this.keyOf(hash))
+  }
+
+  prune(...args: Parameters<CacheLayer['prune']>): ReturnType<CacheLayer['prune']> {
+    return this.inner.prune(...args)
+  }
+
+  close(): void {
+    this.inner.close()
+  }
+}