@vzn/vx 0.0.578 → 0.0.580

package/package.json

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

package/src/config.ts

@@ -46,6 +46,12 @@ export interface WorkspaceConfig {
    * folded into a cache key.
    */
   cacheScope?: string
+  /**
+   * Graph rules a run checks before it schedules anything. Each is on unless
+   * set to `false`; turning one off allows a shape vx handles correctly but
+   * more slowly. Never folded into a cache key.
+   */
+  rules?: WorkspaceRules
   /**
    * Plugins registered for this workspace, consulted in this order once
    * per `vx run`: each fills any of the pipeline stages and capabilities
@@ -55,6 +61,23 @@ export interface WorkspaceConfig {
   plugins?: readonly Plugin[]
 }
 
+/** `WorkspaceConfig.rules`. */
+export interface WorkspaceRules {
+  /**
+   * Refuse two tasks whose declared outputs overlap even when a `dependsOn`
+   * edge orders them. Off, the dependant adds to its upstream's tree and
+   * owns only what its run added (`caching.md` § Additive outputs). Two
+   * overlapping tasks with no edge are refused either way.
+   */
+  exclusiveOutputs?: boolean
+  /**
+   * Refuse a task whose input globs can match another task's declared
+   * outputs, so every key is derived before any task runs. Off, such a key
+   * waits for its producer (`caching.md` § Local restore tier).
+   */
+  upfrontKeys?: boolean
+}
+
 /**
  * The runtime brand `definePlugin` stamps on a plugin: the name of the
  * package it was defined in. The workspace loader accepts a plugin only

package/src/graph/index.ts

@@ -26,6 +26,7 @@ export {
   isGroupTask,
   markSurfacedDeps,
   outputsOverlap,
+  outputTakenBack,
   splitTaskId,
   type TaskNode,
   undeclaredDepsError,

package/src/graph/task-graph.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import type { ProjectConfig, TaskConfig } from '../config.js'
+import type { ProjectConfig, TaskConfig, WorkspaceRules } from '../config.js'
 import {
   asTrees,
   isLiteralPattern,
@@ -267,6 +267,8 @@ export interface BuildGraphOptions {
    * with other root-anchored ones.
    */
   workspaceRoot?: string
+  /** The workspace's `rules`; each is on unless set to `false`. */
+  rules?: WorkspaceRules | undefined
 }
 
 /**
@@ -519,7 +521,7 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
     }
   }
 
-  checkGraph(nodes, options.workspaceRoot)
+  checkGraph(nodes, options.workspaceRoot, options.rules)
   return nodes
 }
 
@@ -534,7 +536,11 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
  * marks are derived here, so they are cleared first and follow the edges
  * the graph has now.
  */
-export function checkGraph(nodes: Map<string, TaskNode>, workspaceRoot?: string): void {
+export function checkGraph(
+  nodes: Map<string, TaskNode>,
+  workspaceRoot?: string,
+  rules?: WorkspaceRules,
+): void {
   for (const [key, node] of nodes) {
     if (node.id !== key) {
       throw new Error(`the task ${node.id} is stored under '${key}', not its own id`)
@@ -548,7 +554,8 @@ export function checkGraph(nodes: Map<string, TaskNode>, workspaceRoot?: string)
     delete node.outputsAddedToBy
   }
   detectCycle(nodes)
-  detectOutputCollisions(nodes, workspaceRoot)
+  detectOutputCollisions(nodes, workspaceRoot, rules?.exclusiveOutputs !== false)
+  if (rules?.upfrontKeys !== false) detectInputOverlaps(nodes, workspaceRoot)
 }
 
 /**
@@ -770,7 +777,11 @@ function covers(tree: string, glob: string): boolean {
  * project boundaries by design, so ANY two tasks can. No cache key changes —
  * this only refuses a graph that was already destroying files.
  */
-function detectOutputCollisions(nodes: Map<string, TaskNode>, workspaceRoot?: string): void {
+function detectOutputCollisions(
+  nodes: Map<string, TaskNode>,
+  workspaceRoot: string | undefined,
+  exclusive: boolean,
+): void {
   // Does `from` reach `to` through deps? Asked only for a colliding pair,
   // so the walk is rare; memoised per source across the detector's calls.
   const reachMemo = new Map<string, Set<string>>()
@@ -834,14 +845,14 @@ function detectOutputCollisions(nodes: Map<string, TaskNode>, workspaceRoot?: st
     for (const [i, j] of overlapCandidates(bucket, filesOf)) {
       const a = bucket[i]!
       const b = bucket[j]!
-      collide(a, b, filesOf(a), filesOf(b), 'files', reaches)
+      collide(a, b, filesOf(a), filesOf(b), 'files', reaches, exclusive)
     }
   }
   if (wsDeclarers.length >= 2) {
     for (const [i, j] of overlapCandidates(wsDeclarers, wsFilesOf)) {
       const a = wsDeclarers[i]!
       const b = wsDeclarers[j]!
-      collide(a, b, wsFilesOf(a), wsFilesOf(b), 'workspaceFiles', reaches)
+      collide(a, b, wsFilesOf(a), wsFilesOf(b), 'workspaceFiles', reaches, exclusive)
     }
   }
   // A root-anchored output that reaches into ANOTHER project's `files`
@@ -870,7 +881,7 @@ function detectOutputCollisions(nodes: Map<string, TaskNode>, workspaceRoot?: st
     const y = entries[j]!
     if ((x.rel === undefined) === (y.rel === undefined) || x.node === y.node) continue
     const [ws, files] = x.rel === undefined ? [x, y] : [y, x]
-    collideAcross(ws.node, ws.globs, files.node, files.globs, files.rel!, reaches)
+    collideAcross(ws.node, ws.globs, files.node, files.globs, files.rel!, reaches, exclusive)
   }
 }
 
@@ -889,11 +900,20 @@ function collideAcross(
   rebased: readonly string[],
   rel: string,
   reaches: (from: string, to: string) => boolean,
+  exclusive: boolean,
 ): void {
   if (neverWritesLocally(ws) || neverWritesLocally(files)) return
   for (const ga of wsGlobs) {
     for (const gb of rebased) {
       if (!outputsOverlap(ga, gb)) continue
+      const head =
+        `${ws.id} declares the output ${JSON.stringify(ga)} in cache.outputs.workspaceFiles, ` +
+        `inside ${files.id}'s ${JSON.stringify(gb.slice(rel === '' ? 0 : rel.length + 1))} in ` +
+        `cache.outputs.files — vx cleans a task's declared outputs before it runs and before a ` +
+        `cache-hit restore, so whichever of these runs second DELETES the other's output`
+      if (exclusive && (reaches(files.id, ws.id) || reaches(ws.id, files.id))) {
+        throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`)
+      }
       if (reaches(files.id, ws.id)) {
         ;(files.addsToOutputsOf ??= []).push(ws.id)
         ;(ws.outputsAddedToBy ??= []).push(...rebased)
@@ -910,12 +930,8 @@ function collideAcross(
         }
       }
       throw new UserError(
-        `${ws.id} declares the output ${JSON.stringify(ga)} in cache.outputs.workspaceFiles, ` +
-          `inside ${files.id}'s ${JSON.stringify(gb.slice(rel === '' ? 0 : rel.length + 1))} in ` +
-          `cache.outputs.files — vx cleans a task's declared outputs before it runs and before a ` +
-          `cache-hit restore, so whichever of these runs second DELETES the other's output and ` +
-          `the run still reports success. Give each task its own output path, or make one ` +
-          `depend on the other.`,
+        `${head} and the run still reports success. Give each task its own output path` +
+          (exclusive ? '.' : ', or make one depend on the other.'),
       )
     }
   }
@@ -1039,6 +1055,15 @@ function neverWritesLocally(n: TaskNode): boolean {
   return n.config.exec?.remote === 'only'
 }
 
+/**
+ * The way out of an edge-ordered overlap under `rules.exclusiveOutputs`: an
+ * ordered pair is correct (the addition shape, item 588), only slower to
+ * clean and restore, so the rule may be turned off.
+ */
+const EXCLUSIVE_OUTPUTS_FIX =
+  'Give each task its own output path, or set rules: { exclusiveOutputs: false } in ' +
+  "vx.workspace.ts to let a dependant add to its upstream's outputs."
+
 function collide(
   a: TaskNode,
   b: TaskNode,
@@ -1046,17 +1071,26 @@ function collide(
   bGlobs: readonly string[] | undefined,
   field: 'files' | 'workspaceFiles',
   reaches: (from: string, to: string) => boolean,
+  exclusive: boolean,
 ): void {
   if (neverWritesLocally(a) || neverWritesLocally(b)) return
   for (const ga of aGlobs ?? []) {
     for (const gb of bGlobs ?? []) {
       if (!outputsOverlap(ga, gb)) continue
+      const head =
+        `${a.id} and ${b.id} both declare the output ${JSON.stringify(ga)}` +
+        (ga === gb ? '' : ` / ${JSON.stringify(gb)}`) +
+        ` in cache.outputs.${field} — vx cleans a task's declared outputs before it runs and ` +
+        `before a cache-hit restore, so whichever of these runs second DELETES the other's ` +
+        `output`
       // An overlap WITH an edge is the addition shape (item 588): the
       // dependant runs after its upstream and adds to that tree, so the
       // order is fixed and the dependant's own set can be told apart from
-      // what it found. Marked on both, and the pair is allowed. Without an
-      // edge the two run in either order, and the refusal below stands.
+      // what it found. Marked on both, and the pair is allowed when
+      // `rules.exclusiveOutputs` is off (X-53). Without an edge the two run
+      // in either order, and the refusal below stands.
       const [up, down] = reaches(b.id, a.id) ? [a, b] : reaches(a.id, b.id) ? [b, a] : []
+      if (up !== undefined && exclusive) throw new UserError(`${head}. ${EXCLUSIVE_OUTPUTS_FIX}`)
       if (up !== undefined && down !== undefined) {
         const downGlobs = splitNegations(
           (field === 'files'
@@ -1068,11 +1102,137 @@ function collide(
         return
       }
       throw new UserError(
-        `${a.id} and ${b.id} both declare the output ${JSON.stringify(ga)}` +
-          (ga === gb ? '' : ` / ${JSON.stringify(gb)}`) +
-          ` in cache.outputs.${field} — vx cleans a task's declared outputs before it runs and ` +
-          `before a cache-hit restore, so whichever of these runs second DELETES the other's ` +
-          `output and the run still reports success. Give each task its own output path.`,
+        `${head} and the run still reports success. Give each task its own output path.`,
+      )
+    }
+  }
+}
+
+/**
+ * Does the `!` set `negatives` take back every path the output glob
+ * `output` can select? Each of the output's `asTrees` forms must be one of
+ * the negatives' forms, sit inside a negative whole subtree (`covers`), or,
+ * as a literal, be matched by one. Sound and no more: an output only partly
+ * taken back answers false.
+ */
+export function outputTakenBack(output: string, negatives: readonly string[]): boolean {
+  if (negatives.length === 0) return false
+  const neg = asTrees(negatives)
+  return asTrees([output]).every((t) =>
+    neg.some((n) => n === t || covers(n, t) || (isLiteralPattern(t) && taskGlob(n).match(t))),
+  )
+}
+
+/** One task's inputs (`reads`) or outputs in one namespace, for `detectInputOverlaps`. */
+interface Side {
+  node: TaskNode
+  globs: readonly string[]
+  reads: boolean
+  /** The project's root-relative dir for a rebased `files` output. */
+  rel?: string
+}
+
+/**
+ * `rules.upfrontKeys` (X-54): refuse a task whose input globs can match
+ * another task's declared outputs. Such a key reads bytes a producer writes
+ * this run, so it is not known until the producer ran (`stable-keys.ts`
+ * keeps it waiting); refused, every key reads only what no task writes and
+ * can be derived before anything runs (M, 2026-10-07: "hash ahead of time,
+ * not waterfall"). A dependency's own key already cascades through
+ * `dependsOn`, so the bytes it wrote add nothing a key needs.
+ *
+ * Proven overlaps only (`outputsOverlap`), as for outputs: a pair the rule
+ * cannot decide passes, and the stability gate still keeps it waiting. The
+ * scope mirrors `detectOutputCollisions`: `inputs.files` against another
+ * same-project task's `outputs.files`; root-anchored `inputs.workspaceFiles`
+ * against every other task's `outputs.workspaceFiles` and, with the root
+ * known, its `outputs.files` rebased to the root. A task's own outputs are
+ * already subtracted from its inputs, and an output the reader's `!` entries
+ * take back whole is no overlap. A keyed group is exempt: the default
+ * `build` reads `**` of a config-less dependency and runs nothing, and its
+ * key waits as before.
+ */
+function detectInputOverlaps(nodes: Map<string, TaskNode>, workspaceRoot?: string): void {
+  const byProject = new Map<string, Side[]>()
+  const rooted: Side[] = []
+  const filesWriters: TaskNode[] = []
+  let projectReaders = false
+  let rootReaders = false
+  const bucket = (name: string): Side[] => {
+    let list = byProject.get(name)
+    if (list === undefined) byProject.set(name, (list = []))
+    return list
+  }
+  for (const n of nodes.values()) {
+    const cache = n.config.cache
+    if (cache === undefined) continue
+    const outFiles = splitNegations(cache.outputs.files).positive
+    const outWs = splitNegations(cache.outputs.workspaceFiles ?? []).positive
+    if (outFiles.length > 0) {
+      bucket(n.projectName).push({ node: n, globs: outFiles, reads: false })
+      filesWriters.push(n)
+    }
+    if (outWs.length > 0) rooted.push({ node: n, globs: outWs, reads: false })
+    if (isGroupTask(n)) continue
+    const inFiles = splitNegations(cache.inputs.files).positive
+    const inWs = splitNegations(cache.inputs.workspaceFiles ?? []).positive
+    if (inFiles.length > 0) {
+      bucket(n.projectName).push({ node: n, globs: inFiles, reads: true })
+      projectReaders = true
+    }
+    if (inWs.length > 0) {
+      rooted.push({ node: n, globs: inWs, reads: true })
+      rootReaders = true
+    }
+  }
+  if (projectReaders) {
+    for (const sides of byProject.values()) {
+      if (sides.length < 2) continue
+      for (const [i, j] of overlapCandidates(sides, (s) => s.globs)) {
+        readsOutputs(sides[i]!, sides[j]!, 'files')
+      }
+    }
+  }
+  if (!rootReaders) return
+  if (workspaceRoot !== undefined) {
+    for (const node of filesWriters) {
+      const rel = path.relative(workspaceRoot, node.projectDir).split(path.sep).join('/')
+      const globs = splitNegations(node.config.cache!.outputs.files).positive.map((g) =>
+        rel === '' ? g : `${rel}/${g}`,
+      )
+      rooted.push({ node, globs, reads: false, rel })
+    }
+  }
+  for (const [i, j] of overlapCandidates(rooted, (s) => s.globs)) {
+    readsOutputs(rooted[i]!, rooted[j]!, 'workspaceFiles')
+  }
+}
+
+function readsOutputs(x: Side, y: Side, field: 'files' | 'workspaceFiles'): void {
+  if (x.reads === y.reads || x.node === y.node) return
+  const [reader, writer] = x.reads ? [x, y] : [y, x]
+  const cache = reader.node.config.cache!
+  // What the reader's key never reads: its `!` entries and its own outputs.
+  const takeBack = [
+    ...splitNegations(field === 'files' ? cache.inputs.files : (cache.inputs.workspaceFiles ?? []))
+      .negative,
+    ...splitNegations(
+      field === 'files' ? cache.outputs.files : (cache.outputs.workspaceFiles ?? []),
+    ).positive,
+  ]
+  for (const go of writer.globs) {
+    if (outputTakenBack(go, takeBack)) continue
+    for (const gi of reader.globs) {
+      if (!outputsOverlap(gi, go)) continue
+      const shown =
+        writer.rel === undefined || writer.rel === '' ? go : go.slice(writer.rel.length + 1)
+      throw new UserError(
+        `${reader.node.id} reads ${JSON.stringify(gi)} in cache.inputs.${field}, which matches ` +
+          `${writer.node.id}'s output ${JSON.stringify(shown)} — a task's key must not read ` +
+          `another task's outputs (the dependency's key already cascades through dependsOn). ` +
+          `Exclude it: add ${JSON.stringify(`!${go}`)} to ${reader.node.id}'s ` +
+          `cache.inputs.${field}, or set rules: { upfrontKeys: false } in vx.workspace.ts to ` +
+          `let it wait for its producer.`,
       )
     }
   }

package/src/orchestrator/plugin-host.ts

@@ -10,7 +10,7 @@
 import { ChainedCache, type CacheLayer } from '../cache/index.js'
 import { localExecutor, type TaskExecutor } from '../exec/index.js'
 import { settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
-import type { ProjectConfig, WorkspaceConfig } from '../config.js'
+import type { ProjectConfig, WorkspaceConfig, WorkspaceRules } from '../config.js'
 import { checkGraph, type TaskNode } from '../graph/index.js'
 import type {
   CacheContext,
@@ -178,6 +178,7 @@ export async function applyGraphHooks(
   ctx: GraphHookContext,
   /** Runs after EACH plugin's edit, so a refused task config names the plugin that wrote it. */
   afterEach?: (plugin: VxPlugin) => void,
+  rules?: WorkspaceRules,
 ): Promise<void> {
   let last: VxPlugin | undefined
   for (const plugin of plugins) {
@@ -188,7 +189,7 @@ export async function applyGraphHooks(
     last = plugin
   }
   if (last === undefined) return
-  await safe(last, 'graph', () => checkGraph(nodes, ctx.workspaceRoot))
+  await safe(last, 'graph', () => checkGraph(nodes, ctx.workspaceRoot, rules))
 }
 
 /**

package/src/orchestrator/prepare.ts

@@ -515,6 +515,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
         packageGraph,
         requested: req,
         workspaceRoot,
+        rules: workspaceConfig?.rules,
         ...(projects.size < projectsWithConfigs.length
           ? { undeclaredDeps: (id: string, name: string) => void unproven.push([id, name]) }
           : {}),
@@ -628,6 +629,7 @@ export async function prepareRun(options: RunOptions, log: Logger): Promise<Prep
             )
           }
         },
+        workspaceConfig?.rules,
       )
     }
     // Args after `--` go to requested commands only; with none among them

package/src/orchestrator/stable-keys.ts

@@ -11,7 +11,7 @@
 // fall back to lazy read-through in execute-task, which is always
 // correct. The check is conservative: when unsure, treat as unstable.
 
-import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import { isGroupTask, outputTakenBack, type TaskNode, type TaskOutcome } from '../graph/index.js'
 import type { CacheLayer, GitFilesCache } from '../cache/index.js'
 import { isLiteralPattern, normalizeGlob, relPosix } from '../util/index.js'
 import { commandWriteReach, mayWriteFingerprint, undeclaredWriteReach } from './sandbox-request.js'
@@ -458,7 +458,13 @@ export function dependsOnSiblingOutputs(
     const inputs = cache.inputs?.files
     const outputs = sameProject.outputsOf.get(node.projectName) ?? []
     if (inputs === undefined || outputs.length === 0) return true
-    if (workspaceInputsReach(inputs, outputs.map(literalPrefix))) return true
+    // An output the reader's own `!` inputs take back whole is not in its
+    // key: `['**/*', '!dist/**']` beside a `dist/**` producer keys the same
+    // before and after it, which is what `rules.upfrontKeys` asks a config
+    // to write (X-54).
+    const back = inputs.filter((g) => g.startsWith('!')).map((g) => g.slice(1))
+    const reach = back.length === 0 ? outputs : outputs.filter((o) => !outputTakenBack(o, back))
+    if (reach.length > 0 && workspaceInputsReach(inputs, reach.map(literalPrefix))) return true
     // Nor where it WRITES inside another task's tree: restored ahead of
     // that producer, its restore raced the producer's clean and extract
     // (M-5; invariant 2 of docs/design/overlapping-outputs-2026-09.md).

package/src/workspace/config-schema.ts

@@ -54,9 +54,25 @@ const WORKSPACE_FIELDS = new Set([
   'cacheRetention',
   'affectedBase',
   'cacheScope',
+  'rules',
   'plugins',
 ])
 
+const RULE_FIELDS = new Set(['exclusiveOutputs', 'upfrontKeys'])
+
+function validateRules(rules: unknown, configPath: string): void {
+  const where = `${configPath}: \`rules\``
+  if (rules === null || typeof rules !== 'object' || Array.isArray(rules)) {
+    throw new UserError(`${where} must be { exclusiveOutputs?: boolean; upfrontKeys?: boolean }`)
+  }
+  assertKnownFields(rules as Record<string, unknown>, RULE_FIELDS, where)
+  for (const [name, value] of Object.entries(rules)) {
+    if (value !== undefined && typeof value !== 'boolean') {
+      throw new UserError(`${where}.${name} must be true or false`)
+    }
+  }
+}
+
 const RETENTION_FIELDS = new Set(['olderThan', 'maxSize'])
 
 function validateRetention(retention: unknown, configPath: string): void {
@@ -142,6 +158,7 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
   if (config.cacheScope !== undefined && !isCacheScope(config.cacheScope)) {
     throw new UserError(`${configPath}: \`cacheScope\` ${CACHE_SCOPE_RULE}`)
   }
+  if (config.rules !== undefined) validateRules(config.rules, configPath)
   if (config.plugins !== undefined) {
     if (!Array.isArray(config.plugins)) {
       throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)