@vzn/vx 0.0.578 → 0.0.579

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.578",
+  "version": "0.0.579",
   "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.579",
+    "@vzn/vx-linux-arm64": "0.0.579",
+    "@vzn/vx-darwin-x64": "0.0.579",
+    "@vzn/vx-darwin-arm64": "0.0.579"
   },
   "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,17 @@ 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
+}
+
 /**
  * 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/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,7 @@ export function checkGraph(nodes: Map<string, TaskNode>, workspaceRoot?: string)
     delete node.outputsAddedToBy
   }
   detectCycle(nodes)
-  detectOutputCollisions(nodes, workspaceRoot)
+  detectOutputCollisions(nodes, workspaceRoot, rules?.exclusiveOutputs !== false)
 }
 
 /**
@@ -770,7 +776,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 +844,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 +880,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 +899,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 +929,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 +1054,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 +1070,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 +1101,7 @@ 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.`,
       )
     }
   }

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/workspace/config-schema.ts

@@ -54,9 +54,25 @@ const WORKSPACE_FIELDS = new Set([
   'cacheRetention',
   'affectedBase',
   'cacheScope',
+  'rules',
   'plugins',
 ])
 
+const RULE_FIELDS = new Set(['exclusiveOutputs'])
+
+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 }`)
+  }
+  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`)