@vzn/vx 0.0.635 → 0.0.637

package/src/workspace/config-schema.ts

@@ -1,5 +1,5 @@
 // What a config may SAY — the schema validators for `vx.config.*` and
-// `vx.workspace.*`, split from the loader (which decides HOW a file is
+// `.vx/workspace.*`, split from the loader (which decides HOW a file is
 // evaluated) on 2026-09-10. Every object level refuses a key it does not
 // know (tests/schema-unknown-keys), every message names the level and what
 // it accepts, and `validateProjectConfig` is the one boundary the loader,
@@ -10,13 +10,13 @@ import {
   PLUGIN_FUNCTION_HOOKS,
   PLUGIN_HOOKS,
   PLUGIN_PACKAGE,
+  type InputStability,
   type Plugin,
   type ProjectConfig,
   type WorkspaceConfig,
 } from '../config.js'
 import {
   CORE_VERBS,
-  MAX_TIMEOUT_MS,
   nearest,
   normalizeGlob,
   parseDuration,
@@ -28,6 +28,14 @@ import {
   asTrees,
   isLiteralPattern,
 } from '../util/index.js'
+import {
+  parseSettingValue,
+  setting,
+  SETTING_GROUPS,
+  SETTINGS,
+  settingEnv,
+  settingRefusal,
+} from '../settings.js'
 import { compileNameGlob, parseFilter } from './filter.js'
 import { nonJsonMessage, nonJsonPaths } from './json-data.js'
 
@@ -36,54 +44,173 @@ import { nonJsonMessage, nonJsonPaths } from './json-data.js'
 // declared no plugins and ran the workspace bare, `cacheDirectory` left the
 // cache where it was — a config that loads and quietly does nothing it says.
 const CACHE_SCOPE_RULE =
-  "must be 'trusted', 'read-only', or a scope name of letters, digits and . _ - / @ (at most 128), like 'pr-123'"
+  "must be a scope name of letters, digits and . _ - / @ (at most 128), like 'pr-123'"
 
-/** `cacheScope`'s rule, shared with `VX_CACHE_SCOPE`. */
+/** `cache.scope`'s rule, shared with `VX_CACHE_SCOPE`. */
 export function isCacheScope(v: unknown): v is string {
   return typeof v === 'string' && /^[\w.@/-]{1,128}$/.test(v)
 }
 
-/** Why `VX_CACHE_SCOPE` is refused, in `cacheScope`'s words. */
+/** Why a `VX_CACHE_SCOPE` or `--cache-scope` value is refused, in `cache.scope`'s words. */
+export function cacheScopeError(source = 'VX_CACHE_SCOPE'): string {
+  return `${source} ${CACHE_SCOPE_RULE}`
+}
+
+/** Why `VX_CACHE_SCOPE` is refused, as the run's error. */
 export function cacheScopeEnvError(): UserError {
-  return new UserError(`VX_CACHE_SCOPE ${CACHE_SCOPE_RULE}`)
+  return new UserError(cacheScopeError())
 }
 
-const WORKSPACE_FIELDS = new Set([
-  'concurrency',
-  'cacheDir',
-  'timeout',
-  'cacheRetention',
-  'affectedBase',
-  'cacheScope',
-  'rules',
-  'schedule',
-  'plugins',
-])
+const STRATEGIES = ['immutable', 'mutable', 'unchecked'] as const
+const SEVERITIES = ['warn', 'error'] as const
+const INPUT_STABILITY_FIELDS = new Set(['strategy', 'severity'])
+const oneOf = (values: readonly string[]): string =>
+  `must be ${values
+    .map((v) => `'${v}'`)
+    .join(', ')
+    .replace(/, ([^,]*)$/, ' or $1')}`
 
-type Schedule = NonNullable<WorkspaceConfig['schedule']>
-const SCHEDULES = {
-  'most-work': true,
-  'critical-path': true,
-  'direct-dependents': true,
-  'ready-order': true,
-} satisfies Record<Schedule, true>
+function validateInputStability(stability: unknown, at: string): void {
+  if (typeof stability !== 'object' || stability === null || Array.isArray(stability)) {
+    throw new UserError(`${at} must be an object — \`inputStability: { strategy: 'mutable' }\``)
+  }
+  assertKnownFields(stability, INPUT_STABILITY_FIELDS, at)
+  const { strategy, severity } = stability as Record<string, unknown>
+  if (strategy !== undefined && !STRATEGIES.includes(strategy as never)) {
+    throw new UserError(`${at}.strategy ${oneOf(STRATEGIES)}`)
+  }
+  if (severity !== undefined && !SEVERITIES.includes(severity as never)) {
+    throw new UserError(`${at}.severity ${oneOf(SEVERITIES)}`)
+  }
+}
 
-const RULE_FIELDS = new Set(['exclusiveOutputs', 'upfrontKeys'])
+/**
+ * `VX_CACHE_INPUT_STABILITY_STRATEGY` and `_SEVERITY`, which override every
+ * task's `cache.inputStability` for the run: each undefined when unset or
+ * empty, refused when it names no value.
+ */
+export function inputStabilityEnv(): InputStability {
+  const strategy = settingEnv('cache.inputStability.strategy') as InputStability['strategy']
+  const severity = settingEnv('cache.inputStability.severity') as InputStability['severity']
+  return {
+    ...(strategy !== undefined ? { strategy } : {}),
+    ...(severity !== undefined ? { severity } : {}),
+  }
+}
 
-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 }`)
+const WORKSPACE_FIELDS = new Set<string>([...SETTING_GROUPS, 'plugins'])
+
+/**
+ * `.vx/workspace`'s settings, as `src/settings.ts` lists them: each group's
+ * fields, and the nested objects (`run.rules`) with theirs.
+ */
+const GROUP_FIELDS = new Map<string, Set<string>>()
+for (const s of SETTINGS) {
+  if (s.config === false) continue
+  const parts = s.path.split('.')
+  for (let i = 1; i < parts.length; i++) {
+    const at = parts.slice(0, i).join('.')
+    if (!GROUP_FIELDS.has(at)) GROUP_FIELDS.set(at, new Set())
+    GROUP_FIELDS.get(at)!.add(parts[i]!)
   }
-  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`)
+}
+// A list of objects, so no setting: no variable or flag can say it.
+GROUP_FIELDS.get('run.rules')!.add('dependencies')
+
+/** A setting's value or the level holding it, held to the schema. */
+function validateSettingsAt(value: unknown, at: string, configPath: string): void {
+  const where = `${configPath}: \`${at}\``
+  const fields = GROUP_FIELDS.get(at)
+  if (fields !== undefined) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      if (at === 'cache')
+        // Turbo's and Nx's workspace `cache: true` is a task's own `cache` in vx (D-98).
+        throw new UserError(
+          `${where} must be an object like { dir, policy, scope }; a task caches through its own \`cache\` in its project's vx.config`,
+        )
+      throw new UserError(`${where} must be an object (fields: ${[...fields].join(', ')})`)
+    }
+    assertKnownFields(value, fields, where)
+    for (const [k, v] of Object.entries(value)) {
+      if (v !== undefined) validateSettingsAt(v, `${at}.${k}`, configPath)
     }
+    return
   }
+  if (at === 'run.rules.dependencies') validateDependencyRules(value, where)
+  else validateSettingValue(value, at, where)
 }
 
-const RETENTION_FIELDS = new Set(['olderThan', 'maxSize'])
+const RULE_FIELDS = new Set(['from', 'allow', 'deny'])
+
+function validateDependencyRules(value: unknown, where: string): void {
+  const shape = `an array of { from, allow?, deny? }, each a selector like 'tag:app' or '@acme/*'`
+  if (!Array.isArray(value)) throw new UserError(`${where} must be ${shape}`)
+  const selector = (v: unknown) => typeof v === 'string' && v.trim() !== '' && v !== 'tag:'
+  for (const [i, rule] of (value as unknown[]).entries()) {
+    const at = `${where}[${i}]`
+    if (typeof rule !== 'object' || rule === null || Array.isArray(rule))
+      throw new UserError(`${at} must be { from, allow?, deny? }`)
+    assertKnownFields(rule, RULE_FIELDS, at)
+    const { from, allow, deny } = rule as Record<string, unknown>
+    if (!selector(from)) throw new UserError(`${at}.from must be a selector like 'tag:app'`)
+    for (const [k, list] of [
+      ['allow', allow],
+      ['deny', deny],
+    ] as const) {
+      if (list !== undefined && (!Array.isArray(list) || !list.every(selector)))
+        throw new UserError(`${at}.${k} must be an array of selectors like 'tag:lib'`)
+    }
+    // A rule that says nothing reads as a constraint and checks nothing.
+    if (allow === undefined && deny === undefined)
+      throw new UserError(`${at} names neither \`allow\` nor \`deny\``)
+  }
+}
+
+/** `value` as the setting at `path` takes it, refused in `where`'s words. */
+function validateSettingValue(value: unknown, path: string, where: string): void {
+  const { kind } = setting(path)
+  // The bound `vx cache clean` refuses too: each run would empty the cache,
+  // the entries it just saved included, so nothing ever hits (item 969).
+  if (
+    path === 'cache.retention.olderThan' &&
+    typeof value === 'string' &&
+    parseDuration(value) === 0
+  ) {
+    throw new UserError(`${where} of 0 evicts every entry after every run`)
+  }
+  // A file's values are typed: a count or a switch is no string (only a
+  // share of the cores is), as a variable's or a flag's must be.
+  const untyped =
+    (kind.type === 'concurrency' && typeof value === 'string' && !value.endsWith('%')) ||
+    (kind.type === 'int' && typeof value !== 'number') ||
+    (kind.type === 'bool' && typeof value !== 'boolean')
+  if (untyped || parseSettingValue(kind, value) === null) {
+    throw new UserError(settingRefusal(path, where, value, shown(value)))
+  }
+}
+
+/** The rules a setting's kind cannot say. */
+function validateSettingsExtra(config: WorkspaceConfig, configPath: string): void {
+  const dir = config.cache?.dir
+  if (dir !== undefined && dir.includes('\0')) {
+    // No path can carry one: the mkdir's argument error was reported as an
+    // unwritable workspace.
+    throw new UserError(`${configPath}: \`cache.dir\` holds a NUL, which no path can carry`)
+  }
+  const base = config.run?.affectedBase
+  // A leading '-' would reach git as an option, not a ref; a NUL fails the
+  // spawn with an argument error naming nothing in this file.
+  if (base !== undefined && !/^[^-\s\0][^\s\0]*$/.test(base)) {
+    throw new UserError(`${configPath}: \`run.affectedBase\` must be a git ref like 'origin/main'`)
+  }
+  // `policy`'s grammar is the cache module's (`parseCachePolicy`), which
+  // this module may not import: the run parses it before any task (prepare.ts).
+  const scope = config.cache?.scope
+  if (scope !== undefined && !isCacheScope(scope)) {
+    throw new UserError(`${configPath}: \`cache.scope\` ${CACHE_SCOPE_RULE}`)
+  }
+  if (config.cache?.retention !== undefined) validateRetention(config.cache.retention, configPath)
+}
 
 /**
  * A refused value as a message quotes it. A workspace file is evaluated
@@ -95,43 +222,26 @@ function shown(v: unknown): string {
   return typeof v === 'bigint' ? `${v}n` : (JSON.stringify(v) ?? String(v))
 }
 
-function validateRetention(retention: unknown, configPath: string): void {
-  const where = `${configPath}: \`cacheRetention\``
-  const field = (key: string) => `${configPath}: \`cacheRetention.${key}\``
-  if (retention === null || typeof retention !== 'object' || Array.isArray(retention)) {
-    throw new UserError(`${where} must be { olderThan?: '30d', maxSize?: '10G' }`)
-  }
-  assertKnownFields(retention as Record<string, unknown>, RETENTION_FIELDS, where)
-  const { olderThan, maxSize } = retention as { olderThan?: unknown; maxSize?: unknown }
+function validateRetention(
+  retention: NonNullable<NonNullable<WorkspaceConfig['cache']>['retention']>,
+  configPath: string,
+): void {
+  const { olderThan, maxSize } = retention
   // An empty object would load and evict nothing, which reads as a policy.
   if (olderThan === undefined && maxSize === undefined) {
-    throw new UserError(`${where} names neither \`olderThan\` nor \`maxSize\``)
-  }
-  if (
-    olderThan !== undefined &&
-    (typeof olderThan !== 'string' || parseDuration(olderThan) === null)
-  ) {
     throw new UserError(
-      `${field('olderThan')} must be a duration like '30d', '12h', '90m' or '45s' (got ${shown(olderThan)})`,
+      `${configPath}: \`cache.retention\` names neither \`olderThan\` nor \`maxSize\``,
     )
   }
-  if (maxSize !== undefined && (typeof maxSize !== 'string' || parseSize(maxSize) === null)) {
+  // As for olderThan (item 969).
+  if (maxSize !== undefined && parseSize(maxSize) === 0) {
     throw new UserError(
-      `${field('maxSize')} must be a size like '10G', '500MB' or '64KB' (got ${shown(maxSize)})`,
+      `${configPath}: \`cache.retention.maxSize\` of 0 evicts every entry after every run`,
     )
   }
-  // The bounds `vx cache prune` refuses, for the same reason: each evicts
-  // every entry, and here it would do so at the end of every run, the
-  // entries that run just saved included, so nothing ever hits (item 969).
-  if (olderThan !== undefined && parseDuration(olderThan) === 0) {
-    throw new UserError(`${field('olderThan')} of 0 evicts every entry after every run`)
-  }
-  if (maxSize !== undefined && parseSize(maxSize) === 0) {
-    throw new UserError(`${field('maxSize')} of 0 evicts every entry after every run`)
-  }
   if (maxSize !== undefined && /^\d+$/.test(maxSize)) {
     throw new UserError(
-      `${field('maxSize')} '${maxSize}' reads as ${maxSize} bytes — give a unit (e.g. '${maxSize}M', '${maxSize}G')`,
+      `${configPath}: \`cache.retention.maxSize\` '${maxSize}' reads as ${maxSize} bytes — give a unit (e.g. '${maxSize}MB', '${maxSize}GB')`,
     )
   }
 }
@@ -146,65 +256,10 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
   // objects of functions by design, the file is evaluated in-process on
   // every load (never through the config worker), and no key folds its JSON.
   assertKnownFields(config, WORKSPACE_FIELDS, configPath)
-  if (config.concurrency !== undefined) {
-    if (
-      typeof config.concurrency !== 'number' ||
-      !Number.isFinite(config.concurrency) ||
-      config.concurrency < 1 ||
-      !Number.isInteger(config.concurrency)
-    ) {
-      throw new UserError(`${configPath}: \`concurrency\` must be a positive integer`)
-    }
-  }
-  if (config.cacheDir !== undefined && typeof config.cacheDir !== 'string') {
-    throw new UserError(`${configPath}: \`cacheDir\` must be a string`)
-  }
-  // `'   '` made a directory named three spaces at the root, hidden by the
-  // cache's own `.gitignore` (X-22).
-  if (
-    typeof config.cacheDir === 'string' &&
-    config.cacheDir !== '' &&
-    config.cacheDir.trim() === ''
-  ) {
-    throw new UserError(`${configPath}: \`cacheDir\` is only whitespace — name a directory`)
-  }
-  // No path can carry one: the mkdir's argument error was reported as an
-  // unwritable workspace.
-  if (typeof config.cacheDir === 'string' && config.cacheDir.includes('\0')) {
-    throw new UserError(`${configPath}: \`cacheDir\` holds a NUL, which no path can carry`)
-  }
-  if (config.timeout !== undefined) {
-    if (
-      typeof config.timeout !== 'number' ||
-      !Number.isInteger(config.timeout) ||
-      config.timeout <= 0
-    ) {
-      throw new UserError(`${configPath}: \`timeout\` must be a positive integer (milliseconds)`)
-    }
-    assertTimeoutInRange(config.timeout, `${configPath}: \`timeout\``)
-  }
-  if (config.cacheRetention !== undefined) validateRetention(config.cacheRetention, configPath)
-  if (config.affectedBase !== undefined) {
-    // A leading '-' would reach git as an option, not a ref; a NUL fails the
-    // spawn with an argument error naming nothing in this file.
-    if (
-      typeof config.affectedBase !== 'string' ||
-      !/^[^-\s\0][^\s\0]*$/.test(config.affectedBase)
-    ) {
-      throw new UserError(`${configPath}: \`affectedBase\` must be a git ref like 'origin/main'`)
-    }
-  }
-  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.schedule !== undefined && !Object.hasOwn(SCHEDULES, config.schedule)) {
-    throw new UserError(
-      `${configPath}: \`schedule\` must be one of ${Object.keys(SCHEDULES)
-        .map((k) => `'${k}'`)
-        .join(', ')}`,
-    )
+  for (const group of SETTING_GROUPS) {
+    if (config[group] !== undefined) validateSettingsAt(config[group], group, configPath)
   }
+  validateSettingsExtra(config, configPath)
   if (config.plugins !== undefined) {
     if (!Array.isArray(config.plugins)) {
       throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)
@@ -227,7 +282,7 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
       }
       // The loose schema's shape (unknown-typed hooks) plus the one retired
       // key this loader still refuses by name.
-      const plug = p as Partial<Plugin> & { name?: unknown; backend?: unknown }
+      const plug = p as Partial<Plugin> & { name?: unknown }
       // A plugin's name is its package name and nothing else. `definePlugin`
       // reads it and stamps it under a registry symbol; a plain object, or
       // one whose `name` was overwritten after the stamp, is refused here —
@@ -250,21 +305,6 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
           `${configPath}: \`plugins[${i}].name\` overrides the package name ('${String(plug.name)}' over '${pkg}') — a plugin's name is its package name; drop the field`,
         )
       }
-      // The whole-run `backend` seam was REMOVED on 2026-08-23 with vx
-      // cloud: a run always executes in the `vx run` process. Nothing
-      // consults `.backend` any more, so leaving it in `caps` below meant a
-      // plugin declaring ONLY `backend` — a third-party one written against
-      // the old API, say — validated as "contributes a capability" and was
-      // then silently ignored. Refuse it by name and point at the seam that
-      // replaced it; a silent no-op is the failure this validation exists
-      // to prevent.
-      if (plug.backend !== undefined) {
-        throw new UserError(
-          `${configPath}: \`plugins[${i}].backend\` is no longer a capability — the whole-run ` +
-            `backend seam was removed in 2026-08. Use \`executor\` to change where a single ` +
-            `task's command runs (see docs/architecture.md § plugin capabilities).`,
-        )
-      }
       // A misspelled hook (`excutor`, `setUp`) was never called and never
       // said: tasks ran here with the plugin's executor unheard (X-19).
       for (const key of Object.keys(plug)) {
@@ -351,11 +391,10 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
           )
         }
         for (const file of claim.files as unknown[]) {
-          // A bare name at the workspace root: a lockfile core folds (taken
-          // out of the fingerprint), or a root file the plugin's stages read
-          // (`turbo.json`: nothing to take out; `--affected` and `vx watch`
-          // ask the claimant about it, item 961). A path is refused: the
-          // root arm `vx watch` keeps is not recursive.
+          // A bare name at the workspace root the plugin reads: a lockfile it
+          // folds, or a file its stages read (`turbo.json`; `--affected` and
+          // `vx watch` ask the claimant about it, item 961). A path is
+          // refused: the root arm `vx watch` keeps is not recursive.
           if (
             typeof file !== 'string' ||
             file === '' ||
@@ -400,9 +439,15 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
  * typechecked (plain .js, or TS with errors ignored). Catch the worst
  * shape problems early with a clear message rather than letting them
  * crash deeper in the orchestrator. Also applied to configs loaded
- * back from `vx-lock.json` (a hand-editable file — same boundary).
+ * back from `.vx/projects.lock.json` (a hand-editable file — same boundary).
+ * `ownConfig` is the config file outputs may not cover (null: none), apart
+ * from `configPath` when that is a label (`<path> (after plugin 'x')`).
  */
-export function validateProjectConfig(config: ProjectConfig, configPath: string): void {
+export function validateProjectConfig(
+  config: ProjectConfig,
+  configPath: string,
+  ownConfig: string | null = configPath,
+): void {
   // Before the schema, on the object as it stands: the key folds its JSON,
   // so a value JSON cannot carry is refused here and in the config worker
   // alike (json-data.ts). A plugin's `project` edit and a lock entry cross
@@ -412,6 +457,15 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
   // The top level too: `task:` (singular) loaded as a project with no
   // tasks and every request against it said "no projects declare".
   assertKnownFields(config, PROJECT_FIELDS, configPath)
+  const name: unknown = config.name
+  if (name !== undefined) {
+    // A task is `<project>#<task>`, split at the first `#`.
+    if (typeof name !== 'string' || name === '' || name.trim() !== name || name.includes('#')) {
+      throw new UserError(
+        `${configPath}: \`name\` must be a non-empty string with no surrounding whitespace and no "#" (a task is <name>#<task>)`,
+      )
+    }
+  }
   const tags: unknown = config.tags
   if (
     tags !== undefined &&
@@ -473,10 +527,7 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
       }
       const timeout = (exec as { timeout?: unknown }).timeout
       if (timeout !== undefined) {
-        if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout <= 0) {
-          throw new UserError(`${where}.exec.timeout must be a positive integer (milliseconds)`)
-        }
-        assertTimeoutInRange(timeout, `${where}.exec.timeout`)
+        validateSettingValue(timeout, 'run.timeout', `${where}.exec.timeout`)
       }
       const retries = (exec as { retries?: unknown }).retries
       if (retries !== undefined) {
@@ -668,10 +719,9 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         )
       }
       assertKnownFields(cache, CACHE_FIELDS, `${where}.cache`)
-      const rewritten = (cache as { rewrittenInputs?: unknown }).rewrittenInputs
-      if (rewritten !== undefined && rewritten !== 'withhold' && rewritten !== 'compare') {
-        throw new UserError(`${where}.cache.rewrittenInputs must be 'withhold' or 'compare'`)
-      }
+      const stability = (cache as { inputStability?: unknown }).inputStability
+      if (stability !== undefined)
+        validateInputStability(stability, `${where}.cache.inputStability`)
       const inputs = (cache as { inputs?: unknown }).inputs
       const outputs = (cache as { outputs?: unknown }).outputs
       // A present field of the wrong shape (`outputs: 'dist'`) was told it
@@ -726,6 +776,10 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         )
       }
       assertKnownFields(outputs, CACHE_OUTPUT_FIELDS, `${where}.cache.outputs`)
+      const clean = (outputs as { clean?: unknown }).clean
+      if (clean !== undefined && typeof clean !== 'boolean') {
+        throw new UserError(`${where}.cache.outputs.clean must be true or false`)
+      }
       const outFiles = (outputs as { files?: unknown }).files
       if (!Array.isArray(outFiles)) {
         throw new UserError(`${where}.cache.outputs.files must be an array of glob strings`)
@@ -774,12 +828,12 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
         // Taken back by a `!`, the file is never cleaned or restored.
         const own = g.startsWith('!')
           ? undefined
-          : ownFilesCovered(g, configPath).find((f) => !takenBack(outFiles as unknown[], f))
+          : ownFilesCovered(g, ownConfig).find((f) => !takenBack(outFiles as unknown[], f))
         if (own !== undefined) {
           throw new UserError(
             `${where}.cache.outputs.files: "${g}" covers the project's own ${own} — vx deletes a ` +
               `task's outputs before it runs and restores them on a hit, so the project would lose ` +
-              `its manifest and config. Name the directory the task writes, such as "dist/**", ` +
+              `its config. Name the directory the task writes, such as "dist/**", ` +
               `or take the file back with "!${own}".`,
           )
         }
@@ -894,7 +948,7 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
 // encodes. A new field must be added here deliberately.
 // `tasks` first: `nearest` breaks a tie by order, and `taks` is one edit
 // from both.
-const PROJECT_FIELDS = new Set(['tasks', 'tags'])
+const PROJECT_FIELDS = new Set(['name', 'tasks', 'tags'])
 const TASK_FIELDS = new Set(['description', 'exec', 'dependsOn', 'cache'])
 const EXEC_FIELDS = new Set([
   'command',
@@ -908,7 +962,7 @@ const EXEC_FIELDS = new Set([
 ])
 const PERSISTENT_FIELDS = new Set(['readyWhen'])
 const ENV_FIELDS = new Set(['passThrough', 'define', 'secret'])
-const CACHE_FIELDS = new Set(['inputs', 'outputs', 'rewrittenInputs'])
+const CACHE_FIELDS = new Set(['inputs', 'outputs', 'inputStability'])
 const CACHE_INPUT_FIELDS = new Set([
   'files',
   'workspaceFiles',
@@ -917,41 +971,7 @@ const CACHE_INPUT_FIELDS = new Set([
   'runtime',
   'workspaceRuntime',
 ])
-const CACHE_OUTPUT_FIELDS = new Set(['files', 'workspaceFiles'])
-
-/** A field a release took out of the schema, and what took its place. */
-interface Removal {
-  /** The vx version whose schema first refused it. */
-  removedIn: string
-  /** What to write instead, as a sentence fragment after "use". */
-  use: string
-}
-
-/**
- * Fields the schema once accepted, by the level that held them (keyed by
- * that level's field set). A removed field is refused naming its
- * replacement and the version that removed it, never as an unknown field a
- * reader must research (docs/design/versioning-1.0.md § Deprecation). An
- * entry stays for good: a config written against an old release meets it
- * whenever it upgrades.
- */
-export const REMOVED_FIELDS: ReadonlyMap<
-  ReadonlySet<string>,
-  Readonly<Record<string, Removal>>
-> = new Map([
-  [
-    EXEC_FIELDS,
-    {
-      // Reservations left core with the `admit` seam (item 157).
-      resources: {
-        removedIn: '0.0.19',
-        use:
-          "`@vzn/vx-schedule-history`, which learns each task's reservation from its run " +
-          "history (declare one by hand with its `reservations: { 'pkg#task': { cpus, memory } }`)",
-      },
-    },
-  ],
-])
+const CACHE_OUTPUT_FIELDS = new Set(['files', 'workspaceFiles', 'clean'])
 
 /**
  * Another runner's spelling of a field vx has under another name, by the
@@ -983,7 +1003,7 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
       with: '`dependsOn` on each task it runs beside: a persistent one stays up, and this task starts once it is ready',
       cwd: '`cd <dir> && …` in `exec.command`: a task runs in its project directory',
       parallelism:
-        '`concurrency: 1` in vx.workspace or `--concurrency 1` on the run: no task runs alone beside others',
+        '`run.concurrency: 1` in .vx/workspace or `--concurrency 1` on the run: no task runs alone beside others',
       configurations:
         'one task per configuration (`build:production`, with its own `exec.command`)',
     },
@@ -1040,14 +1060,13 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
       targets: '`tasks` (a target is a task: `exec.command`, `dependsOn`, `cache`)',
       extends: 'an imported module spread into `tasks` (a vx.config is code; nothing is inherited)',
       implicitDependencies: 'a `dependsOn` entry `pkg#task`, or a package.json dependency',
-      name: 'the package.json `name` (a project is named by its package)',
       // A package.json's, turbo.json's and project.json's keys, and a
       // task's fields one level too high (D-99).
       scripts:
         "`tasks` (a script is a task's `exec.command`; `vx init` writes them from package.json)",
       pipeline: '`tasks` (`bunx @vzn/vx-migrate` writes them from turbo.json)',
       namedInputs: 'a module the vx.config imports, spread into `cache.inputs.files`',
-      root: "no field: a project's directory is where its package.json sits",
+      root: "no field: a project's directory is where its vx.config sits",
       sourceRoot: "a task's `cache.inputs.files`",
       projectType: 'no field: vx runs every project alike',
       ...Object.fromEntries(
@@ -1061,7 +1080,7 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
       env: '`tasks.<name>.cache.inputs.env` (to key a task on it) or `tasks.<name>.exec.env`',
     },
   ],
-  // Turbo's turbo.json and Nx's nx.json keys, written into vx.workspace
+  // Turbo's turbo.json and Nx's nx.json keys, written into .vx/workspace
   // (D-38).
   [
     WORKSPACE_FIELDS,
@@ -1077,33 +1096,47 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
       globalDependencies: '`cache.inputs.workspaceFiles` on the tasks it keys',
       remoteCache:
         'a cache plugin in `plugins` (`turboCache()` or `nxCache()` from `@vzn/vx-migrate`)',
-      parallel: '`concurrency`',
-      cacheDirectory: '`cacheDir`',
-      defaultBase: '`affectedBase`',
+      parallel: '`run.concurrency`',
+      cacheDirectory: '`cache.dir`',
+      defaultBase: '`run.affectedBase`',
       tasksRunnerOptions: 'a cache plugin in `plugins` (`nxCache()` from `@vzn/vx-migrate`)',
       globalPassThroughEnv: '`exec.env.passThrough` on the tasks it passes to',
       // pnpm-workspace.yaml's, Lerna's and the package.json's own keys
-      // pasted into vx.workspace: refused with no word on where vx reads
+      // pasted into .vx/workspace: refused with no word on where vx reads
       // them (D-98).
-      packages:
-        "`workspaces` in package.json or pnpm-workspace.yaml's `packages`, where vx reads the members",
-      workspaces:
-        "`workspaces` in package.json or pnpm-workspace.yaml's `packages`, where vx reads the members",
-      projects:
-        "`workspaces` in package.json or pnpm-workspace.yaml's `packages`, where vx reads the members",
+      packages: 'a `vx.config` in each project directory: a project is a directory holding one',
+      workspaces: 'a `vx.config` in each project directory: a project is a directory holding one',
+      projects: 'a `vx.config` in each project directory: a project is a directory holding one',
       ignore:
-        'a `!` pattern in the workspace globs (package.json `workspaces` or pnpm-workspace.yaml)',
+        "no field: a directory with no `vx.config` is no project, and git's ignore rules apply",
       catalog:
         "pnpm-workspace.yaml's or package.json's `catalog`, where the package manager reads it",
       npmClient: "no field: a task's command runs as written, with no package manager in between",
-      cache:
-        "each task's `cache` in its project's vx.config (a task caches only when it declares one)",
       remote: 'a cache plugin in `plugins`',
       env: '`cache.inputs.env` on the tasks it keys, or `exec.env` on the tasks it passes to',
     },
   ],
 ])
 
+/**
+ * A top-level typo of a grouped setting, as its path: by its last name
+ * (`concurency`) or its path run together (`cachedir`).
+ */
+function nearestSetting(key: string): string | undefined {
+  const byName = new Map<string, string>()
+  for (const s of SETTINGS) {
+    if (s.config === false) continue
+    const parts = s.path.split('.')
+    byName.set(parts.at(-1)!, s.path)
+    byName.set(
+      parts.map((p, i) => (i === 0 ? p : p[0]!.toUpperCase() + p.slice(1))).join(''),
+      s.path,
+    )
+  }
+  const name = nearest(key, byName.keys())
+  return name === undefined ? undefined : `\`${byName.get(name)}\``
+}
+
 function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: string): void {
   // `typeof [] === 'object'`, so an array reaches here and its indices read
   // as fields: `outputs: ['dist/**']` (Turbo's spelling) was refused as
@@ -1116,16 +1149,11 @@ function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: s
   }
   for (const key of Object.keys(value)) {
     if (!allowed.has(key)) {
-      const removal = REMOVED_FIELDS.get(allowed)?.[key]
-      if (removal !== undefined) {
-        throw new UserError(
-          `${where} has field "${key}", which vx ${removal.removedIn} removed — use ${removal.use}`,
-        )
-      }
       // The nearest accepted spelling first: the list says what the level
       // takes, the hint says which one was meant.
       const foreign = FOREIGN_FIELDS.get(allowed)?.[key]
-      const near = nearest(key, allowed)
+      const near =
+        nearest(key, allowed) ?? (allowed === WORKSPACE_FIELDS ? nearestSetting(key) : undefined)
       throw new UserError(
         `${where} has unknown field "${key}" (allowed: ${[...allowed].sort().join(', ')})` +
           (foreign !== undefined
@@ -1139,35 +1167,17 @@ function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: s
 }
 
 /**
- * A millisecond delay past `MAX_TIMEOUT_MS` does not mean "effectively never" —
- * `setTimeout` silently reduces it to 1 ms, so the task is killed the instant it
- * spawns and reported `failed`. That is the exact inverse of the declaration,
- * and the only clue is a `TimeoutOverflowWarning` on stderr.
- *
- * Refused rather than clamped, because this is a value the user WROTE and reads
- * back: silently substituting ~24.8 days for the 317 years they asked for would
- * trade one surprise for a quieter one. Costs nothing — such a config never
- * worked, it killed the task in milliseconds, so refusing reports a state that
- * already existed.
- */
-function assertTimeoutInRange(ms: number, where: string): void {
-  if (ms <= MAX_TIMEOUT_MS) return
-  throw new UserError(
-    `${where}: ${ms} ms exceeds the maximum timer delay (${MAX_TIMEOUT_MS} ms, ~24.8 days). ` +
-      `Timers larger than this do NOT mean "no limit" — the platform reduces them to 1 ms, so ` +
-      `the task would be killed the moment it starts. Omit \`timeout\` for no limit.`,
-  )
-}
-
-/**
- * The project file an output glob would take, or null. `outputs: ['**']`
- * loaded, and the clean before the run deleted the project's source,
- * `package.json` and `vx.config` while the run reported success (item
- * 1002); the message for `'.'` had even suggested `**`.
+ * The project's config file if an output glob would take it. `outputs:
+ * ['**']` loaded, and the clean before the run deleted the project's
+ * source and `vx.config` while the run reported success (item 1002); the
+ * message for `'.'` had even suggested `**`. Core names no other project
+ * file: a file a plugin keys on is an input, and an output takes it out of
+ * the input set like any other.
  */
-function ownFilesCovered(glob: string, configPath: string): string[] {
-  const g = new Bun.Glob(normalizeGlob(glob))
-  return ['package.json', path.basename(configPath)].filter((f) => g.match(f))
+function ownFilesCovered(glob: string, ownConfig: string | null): string[] {
+  if (ownConfig === null) return []
+  const own = path.basename(ownConfig)
+  return new Bun.Glob(normalizeGlob(glob)).match(own) ? [own] : []
 }
 
 function takenBack(globs: readonly unknown[], file: string): boolean {