@vzn/vx 0.0.636 → 0.0.638

package/src/orchestrator/prepare.ts

@@ -13,11 +13,19 @@ import { beginRun, mark, nearest, UserError } from '../util/index.js'
 import {
   Cache,
   type CacheLayer,
+  applyCacheFlags,
   type CachePolicy,
   FULL_CACHE_POLICY,
-  scopeCachePolicy,
+  parseCachePolicy,
   GitFilesCache,
   LayeredCache,
+  absentPluginCache,
+  pluginCache,
+  putRunEntry,
+  writesRunStore,
+  type PluginCache,
+  type PluginCacheRemote,
+  ScopedCache,
   applyGitEnumeration,
   gitPathspecs,
   MAX_SCOPED_PATHSPECS,
@@ -27,15 +35,11 @@ import {
 import {
   buildPackageGraph,
   computeNestedProjectDirs,
-  computeWorkspaceFingerprints,
   findWorkspaceRoot,
   cacheScopeEnvError,
   isCacheScope,
   type LoadReads,
-  loadWorkspace,
-  FROZEN_WITHOUT_LOCK,
-  type Lockfile,
-  readLockfile,
+  readClaimedFiles,
   resolveCacheDir,
   resolveStoreRoot,
   type ProjectEntry,
@@ -44,6 +48,7 @@ import {
   buildTaskGraph,
   excludeDependencies,
   expandRequested,
+  type GraphRules,
   isGroupTask,
   type TaskNode,
   undeclaredDepsError,
@@ -64,6 +69,8 @@ import {
   isDefaultBuild,
   loadProjects,
   loadWorkspacePlugins,
+  lockOfDiscovery,
+  lockReader,
   type LoadedProjects,
 } from './projects.js'
 import { keptByAffected } from './affected-tasks.js'
@@ -71,10 +78,12 @@ import { applyGraphStage } from './graph-stage.js'
 import { keyExcludedDependencies } from './excluded-keys.js'
 import { FingerprintWatch } from './fingerprint-watch.js'
 import type { VxPlugin } from './plugin.js'
+import { currentBranch } from './run-context.js'
 import { createHashCache, type HashCache } from './task-hash.js'
 import type { Logger } from './logger.js'
 import type { RunOptions } from './options.js'
 import { refuseFiltersThroughGroups } from './upstream.js'
+import { runRules } from '../settings.js'
 
 export interface PreparedRun {
   workspaceRoot: string
@@ -97,7 +106,7 @@ export interface PreparedRun {
    * would be saved still cleans its outputs before executing.
    */
   hasRemoteLayer: boolean
-  /** `--cache` with the workspace's `cacheScope` applied: what the layers were built under. */
+  /** `--cache-policy` with the workspace's `cacheScope` applied: what the layers were built under. */
   cachePolicy: CachePolicy
   /**
    * Scheduling priorities from plugins' `schedule` stage (task id → weight,
@@ -107,6 +116,19 @@ export interface PreparedRun {
    * nothing-changed run never dispatches. Runs the stage once.
    */
   priorities: () => Promise<ReadonlyMap<string, number>>
+  /**
+   * The run's branch (`run.branch`, else git's, else the CI provider's):
+   * what its history records and the timings a forecast reads first.
+   * Learned on first ask, once per run.
+   */
+  branch: () => string | null
+  /** Each plugin's `ctx.cache`: the run's local store and remotes, under its policy and scope. */
+  cacheFor: (plugin: string) => PluginCache
+  /**
+   * Keep `bytes` of this run under `name` (run-store.ts); undefined when no
+   * remote takes the run's writes, and so core keeps nothing.
+   */
+  keepRunEntry: ((name: string, bytes: Uint8Array) => Promise<boolean>) | undefined
   nodes: Map<string, TaskNode>
   /**
    * The tasks `--exclude-dependencies` took out of the schedule: keyed as a
@@ -135,8 +157,7 @@ export interface PreparedRun {
    * mistaken for a workspace vx was never set up in.
    */
   anyProjectConfig: boolean
-  workspaceFingerprint: string
-  /** Whether a task has since rewritten what that fingerprint folded (fingerprint-watch.ts). */
+  /** The claimed root files, and whether a task has since rewritten one (fingerprint-watch.ts). */
   fingerprintWatch: FingerprintWatch
   nestedDirsByProject: Map<string, string[]>
   /**
@@ -149,11 +170,9 @@ export interface PreparedRun {
   /** Every project discovery found, in or out of scope — header scope bar. */
   workspaceProjectCount: number
   /**
-   * Per-run memo for derived hashes — project package.json bytes
-   * keyed by projectDir, task-config hash keyed by config object
-   * identity. Shared across every task's `computeTaskHash` call so
-   * the same project's package.json (and the same task config
-   * object) aren't re-hashed on every task in that project.
+   * Per-run memo for derived hashes — task-config hash keyed by config
+   * object identity, resolved file lists. Shared across every task's
+   * `computeTaskHash` call so the same config object isn't re-hashed.
    */
   hashCache: HashCache
   /**
@@ -188,22 +207,19 @@ export interface PreparedRun {
 export async function prepareRun(options: RunOptions, log: Logger): Promise<PreparedRun> {
   beginRun()
   mark('startup')
-  // The root manifest is read once for the root, the globs and the
-  // fingerprint. A watch cycle is a new run and reads it afresh.
+  // A claimed root file is read once. A watch cycle is a new run and reads
+  // them afresh.
   const reads: LoadReads = new Map()
-  const workspaceRoot = await findWorkspaceRoot(options.cwd, reads)
-  // A frozen run with nothing staged reads the lock whatever discovery
-  // finds, so the read (1.1 MB at 1,000 projects, ~10 ms to read and
-  // parse) starts here and overlaps discovery's I/O instead of following
-  // the cache open (X-181). A missing or malformed lock still refuses at
-  // the config load, after any earlier refusal.
-  let lockRead: Promise<Lockfile> | undefined
-  const readLock = (): Promise<Lockfile> =>
-    (lockRead ??= readLockfile(workspaceRoot).then((read) => {
-      if (read === null) throw new UserError(FROZEN_WITHOUT_LOCK)
-      return read
-    }))
-  if (options.frozen === true && options.staged === undefined) void readLock().catch(() => {})
+  const workspaceRoot = await findWorkspaceRoot(options.cwd)
+  // The lock is where a run's projects come from, so the read (1.1 MB at
+  // 1,000 projects, ~10 ms to read and parse) starts here and overlaps the
+  // workspace config's evaluation (X-181). A missing or malformed lock
+  // refuses at discovery, after any earlier refusal.
+  const reused = options.discovered?.root === workspaceRoot ? options.discovered : undefined
+  const readLock =
+    (reused !== undefined ? lockOfDiscovery(reused.projects) : undefined) ??
+    lockReader(workspaceRoot)
+  if (reused === undefined) void readLock().catch(() => {})
   // An UNSCOPED run (no explicit scope, at least one bare task name)
   // enumerates the whole tree whatever the configs say, so git starts
   // HERE — the walk needs only the root — and overlaps the workspace
@@ -221,18 +237,21 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // whole-tree enumeration a scoped run would otherwise scope later, here or
   // in the CLI's selection pass; the run reuses it instead of walking the
   // tree twice (G-75).
-  const reused = options.discovered?.root === workspaceRoot ? options.discovered : undefined
   const git =
     (reused !== undefined ? gitOfDiscovery(reused.projects) : undefined) ??
     lazyGitEnumeration(workspaceRoot)
   if (wholeTree) void git.start()
-  const workspace = await loadWorkspace(workspaceRoot, reads)
   const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, (m) =>
     log.status(m),
   )
   mark('workspace config')
+  let learnedBranch: string | null | undefined
+  const branch = (): string | null =>
+    learnedBranch === undefined
+      ? (learnedBranch = currentBranch(workspaceRoot, workspaceConfig, options.branch))
+      : learnedBranch
   // `--cache-dir <path>` (RunOptions.cacheDir) overrides the workspace
-  // `cacheDir` field + the `.vx/cache` default; resolved relative to cwd.
+  // `cache.dir` + 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
@@ -244,7 +263,14 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   const projectMetas =
     reused !== undefined
       ? reused.projects
-      : await discoverProjects(workspace, plugins, cacheDir, (m) => log.status(m), git)
+      : await discoverProjects(
+          workspaceRoot,
+          readLock,
+          plugins,
+          cacheDir,
+          (m) => log.status(m),
+          git,
+        )
   mark('discover projects')
 
   // SCOPED config loading: configs are programs, and evaluating 1090
@@ -264,7 +290,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // anchors alone are the scope and nothing else needs its config
   // evaluated.
   // `vx run //#lint` is Turbo's `turbo run //#lint`: the root project's
-  // task, the root named by its package.json name here (D-39).
+  // task, under the name it has when something names it (D-39).
   const root = path.resolve(workspaceRoot)
   const rootName = projectMetas.find((m) => path.resolve(m.dir) === root)?.name
   const tasks =
@@ -282,20 +308,26 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     options.projects !== undefined ? [...options.projects, ...anchored] : hasBare ? 'all' : anchored
   // Its own mark: the package graph is the bulk of what used to be charged
   // to `open cache` (measured on a 1,000-project tree, 2026-09-20 — the
-  // graph 3-8 ms against the cache open's ~1 ms and the fingerprints' ~0.3),
+  // graph 3-8 ms against the cache open's ~1 ms and the root files' ~0.3),
   // so a reader profiling that stage was sent to the wrong code.
   mark('package graph')
 
-  // The local cache opens BEFORE the configs load: it is also where their
-  // cached evaluations live.
   // `--cache-scope`, then `VX_CACHE_SCOPE`, win over the workspace (and `github()`'s guess):
   // a CI job that knows its trust level says so without editing config.
   const envScope = process.env['VX_CACHE_SCOPE'] || undefined
   if (envScope !== undefined && !isCacheScope(envScope)) throw cacheScopeEnvError()
-  const policy: CachePolicy = scopeCachePolicy(
-    options.cache ?? FULL_CACHE_POLICY,
-    options.cacheScope ?? envScope ?? workspaceConfig?.cacheScope ?? options.defaultCacheScope,
-  )
+  const workspacePolicy = workspaceCachePolicy(workspaceConfig)
+  const cacheScope = options.cacheScope ?? envScope ?? workspaceConfig?.cache?.scope
+  const asked =
+    options.cache ?? applyCacheFlags(workspacePolicy ?? FULL_CACHE_POLICY, options.cacheFlags)
+  // A laptop reads the shared cache and does not write it unless a policy
+  // names the remote (owner, 2026-10-03; Security F1, 2026-10-14): a key
+  // holds only declared inputs, so a laptop's write could be replayed on CI.
+  // A workspace policy naming the remote asks to write it, as `--cache-policy` does.
+  const readOnly =
+    options.remoteReadOnlyByDefault === true &&
+    !(options.cache === undefined && namesRemote(workspaceConfig?.cache?.policy))
+  const policy: CachePolicy = readOnly ? { ...asked, remoteWrite: false } : asked
   const localCache = new Cache(
     cacheDir,
     { read: policy.localRead, write: policy.localWrite },
@@ -305,29 +337,20 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     await storeRoot,
   )
   localCache.assertWritable()
-  // Two digests from one read: the config-evaluation cache keys on every
-  // file (a config may import a dependency), the task keys on the files no
-  // plugin claims (`VxPlugin.fingerprint`).
+  // The root files the plugins claim (`VxPlugin.fingerprint`), whose bytes
+  // their claimants fold: read now so a task that rewrites one is caught.
   const fingerprintsAt = Date.now()
-  const fingerprints = await computeWorkspaceFingerprints(
-    workspaceRoot,
-    new Set(fingerprintClaims(plugins).keys()),
-    reads,
-  )
-  const workspaceFingerprint = fingerprints.unclaimed
+  const claimed = [...fingerprintClaims(plugins).keys()]
+  const claimedBytes = await readClaimedFiles(workspaceRoot, claimed, reads)
   mark('open cache')
 
-  // Frozen mode (--frozen, CI): configs load FROM vx-lock.json with no
-  // evaluation and no check of the config bytes (`vx lock --check`
-  // compares `configHash`; a run does not); env-dependent configs keep
-  // their locked values. Default (local) runs ALWAYS evaluate live:
-  // a byte hash can't see a config's import closure (shared presets),
-  // so consuming the lock by default would silently serve stale
-  // freezes. `vx lock --check` is the full re-evaluation audit.
+  // Configs load FROM .vx/projects.lock.json with no evaluation and no check of
+  // the configs (`vx lock --check` re-evaluates them; a run does not):
+  // only `vx lock` evaluates (owner, 2026-10-14).
   // See docs/design/config-lock-2026-06.md.
   // Read once, and only when a config is to be read from it: the CLI's
   // selection pass may have staged every config (`options.staged`), and
-  // its load refused a frozen run without a lock. A 1,000-project lock is
+  // its load refused a run without a lock. A 1,000-project lock is
   // 1.1 MB of JSON (I-27); a run with nothing staged started its read
   // beside discovery, above.
   const staged = options.staged
@@ -336,8 +359,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     projectMetas.every(
       (m) => typeof m.configPath !== 'string' || m.configPath === '' || staged.has(m.name),
     )
-  if (options.frozen === true && !allStaged) await readLock()
-  const lock = options.frozen === true ? readLock : null
+  if (!allStaged) await readLock()
 
   const loadArgs = {
     workspaceRoot,
@@ -345,8 +367,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     plugins,
     projectMetas,
     packageGraph,
-    lock,
-    evalCache: { store: localCache, workspaceRoot, workspaceFingerprint: fingerprints.all },
+    configs: readLock,
     warn: (m: string) => log.status(m),
   }
   let loaded: LoadedProjects
@@ -358,8 +379,8 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       ...(options.staged !== undefined ? { staged: options.staged } : {}),
     })
   } catch (err) {
-    // The cache opened before the configs loaded (it holds their cached
-    // evaluations); a config error must not leak the handle.
+    // The cache opened before the configs loaded; a config error must not
+    // leak the handle.
     localCache.close()
     throw err
   }
@@ -443,6 +464,11 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // winning prevents double-wrapping when the workspace also declares a
   // cache plugin.
   let cache: CacheLayer
+  const remotes: PluginCacheRemote[] = []
+  if (options.remoteCache) {
+    const { remoteCache } = options
+    remotes.push({ remote: remoteCache, read: policy.remoteRead, write: policy.remoteWrite })
+  }
   try {
     cache = options.remoteCache
       ? new LayeredCache(localCache, options.remoteCache, {
@@ -453,8 +479,10 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
           workspaceRoot,
           cacheDir,
           warn: (m) => log.status(m),
+          scope: cacheScope,
           localCache,
           policy,
+          remotes,
         })
   } catch (err) {
     // A cache plugin that throws or returns something off-contract is
@@ -465,6 +493,8 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     localCache.close()
     throw err
   }
+  // One scoping rule above every layer, local and remote alike.
+  if (cacheScope !== undefined) cache = new ScopedCache(cache, cacheScope)
   // Ask the LAYER, don't infer. Identity against `localCache` answers a
   // DIFFERENT question — "did the plugin hand back something other than the
   // handle I passed in?" — which an ordinary pass-through decorator (a
@@ -480,9 +510,14 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
   // returns.
   try {
     const hashCache = createHashCache()
-    const fingerprintWatch = new FingerprintWatch(workspaceRoot, fingerprints, fingerprintsAt)
+    const fingerprintWatch = new FingerprintWatch(
+      workspaceRoot,
+      claimed,
+      claimedBytes,
+      fingerprintsAt,
+    )
 
-    // Empty-cases bookkeeping. We still construct the cache + fingerprint
+    // Empty-cases bookkeeping. We still construct the cache + watch
     // so the caller's try/finally pattern can close it uniformly.
     const emptyRun = (reason?: 'none-affected'): PreparedRun => ({
       workspaceRoot,
@@ -493,7 +528,10 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       localCache,
       hasRemoteLayer,
       cachePolicy: policy,
+      keepRunEntry: undefined,
       priorities: () => Promise.resolve(new Map()),
+      branch,
+      cacheFor: () => absentPluginCache,
       nodes: new Map(),
       keyOnly: new Map(),
       unresolvedTasks,
@@ -501,7 +539,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       projects,
       hintProjects,
       anyProjectConfig: projectsWithConfigs.length > 0,
-      workspaceFingerprint,
       fingerprintWatch,
       nestedDirsByProject,
       gitFilesCache: new GitFilesCache(),
@@ -521,6 +558,10 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
     // the whole workspace: a `^name` nothing loaded declares may be declared
     // by a config the scope left out, so the builder hands it back instead of
     // refusing it, and the rest decide.
+    // A run never checks the graph rules: `vx lock` and `vx lock --check`
+    // do (owner, 2026-10-14). `exclusiveOutputs: false` still asks the walk
+    // for its addition marks.
+    const graphRules: GraphRules = { ...runRules(workspaceConfig), locked: true }
     const unproven: Array<[taskId: string, name: string]> = []
     const graphOf = (req: typeof requested) =>
       buildTaskGraph({
@@ -528,7 +569,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         packageGraph,
         requested: req,
         workspaceRoot,
-        rules: workspaceConfig?.rules,
+        rules: graphRules,
         ...(partialLoad
           ? { undeclaredDeps: (id: string, name: string) => void unproven.push([id, name]) }
           : {}),
@@ -541,7 +582,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         cacheDir,
         projectMetas,
         warn: (m) => log.status(m),
-        rules: workspaceConfig?.rules,
+        rules: graphRules,
       })
     // `--affected` selects over the FINAL graph: an edge or an input a
     // `graph` hook adds moves a key, so the hooks run first, over every
@@ -681,7 +722,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
           dropped,
           cache,
           workspaceRoot,
-          workspaceFingerprint,
           forwardArgs: options.forwardArgs,
           nestedDirsByProject,
           gitFilesCache,
@@ -689,15 +729,35 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         })
       }
     }
+    const pluginCaches = new Map<string, PluginCache>()
+    const cacheFor = (plugin: string): PluginCache => {
+      let own = pluginCaches.get(plugin)
+      if (own === undefined) {
+        own = pluginCache(plugin, {
+          db: localCache.dbHandle(),
+          policy,
+          remotes,
+          scope: cacheScope,
+        })
+        pluginCaches.set(plugin, own)
+      }
+      return own
+    }
     let scheduled: Promise<ReadonlyMap<string, number>> | undefined
     const priorities = (): Promise<ReadonlyMap<string, number>> =>
       (scheduled ??= hasHook(plugins, 'schedule')
-        ? applyScheduleHooks(plugins, nodes, {
-            workspaceRoot,
-            cacheDir,
-            warn: (m) => log.status(m),
-            localCache,
-          })
+        ? applyScheduleHooks(
+            plugins,
+            nodes,
+            {
+              workspaceRoot,
+              cacheDir,
+              warn: (m) => log.status(m),
+              localCache,
+              branch: branch(),
+            },
+            cacheFor,
+          )
         : Promise.resolve(new Map()))
 
     return {
@@ -710,6 +770,11 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       hasRemoteLayer,
       cachePolicy: policy,
       priorities,
+      branch,
+      cacheFor,
+      keepRunEntry: writesRunStore(remotes)
+        ? (name, bytes) => putRunEntry(remotes, cacheScope, name, bytes)
+        : undefined,
       nodes,
       keyOnly,
       unresolvedTasks,
@@ -717,7 +782,6 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
       projects,
       hintProjects,
       anyProjectConfig: projectsWithConfigs.length > 0,
-      workspaceFingerprint,
       fingerprintWatch,
       nestedDirsByProject,
       gitFilesCache,
@@ -771,7 +835,7 @@ function undeclaredIn(
 
 /**
  * Refuses the first `^name` in `unproven` that no project in the whole
- * workspace declares. `load` evaluates the configs a scoped run left out;
+ * workspace declares. `load` reads the locked configs a scoped run left out;
  * it is reached only when a `^name` found no holder and nothing loaded
  * declares it, so a run that names only declared tasks never pays for it.
  * The rest failing to load leaves the names unjudged: an out-of-scope
@@ -815,3 +879,24 @@ function pruneToClosure(nodes: Map<string, TaskNode>, roots: ReadonlySet<string>
     else if (!roots.has(id)) n.requested = false
   }
 }
+
+const namesRemote = (spec: string | undefined): boolean =>
+  spec !== undefined && /remote:[rw]/.test(spec)
+
+/**
+ * The workspace's `cache.policy`, parsed: the schema checks only its shape,
+ * since the grammar lives in the cache module the workspace module may not
+ * import. Undefined when it names none.
+ */
+function workspaceCachePolicy(config: WorkspaceConfig | null | undefined): CachePolicy | undefined {
+  const spec = config?.cache?.policy
+  if (spec === undefined) return undefined
+  try {
+    return parseCachePolicy(spec)
+  } catch (err) {
+    throw new UserError(
+      `.vx/workspace: \`cache.policy\`: ${err instanceof Error ? err.message : String(err)}`,
+      'VX_E_CONFIG',
+    )
+  }
+}