@vzn/vx 0.0.651 → 0.0.652

package/src/config.ts

@@ -28,6 +28,10 @@ export interface WorkspaceConfig {
   baseBranch?: string
   run?: RunSettings
   cache?: CacheSettings
+  /** Input defaults for every task. */
+  inputs?: WorkspaceInputs
+  /** Output defaults for every task. */
+  outputs?: WorkspaceOutputs
   lock?: LockSettings
   watch?: WatchSettings
   /**
@@ -76,6 +80,18 @@ export interface RunSettings {
   rules?: WorkspaceRules
 }
 
+/** `WorkspaceConfig.inputs`. */
+export interface WorkspaceInputs {
+  /** The `inputs.stability` of every task that does not set its own. */
+  stability?: InputStability
+}
+
+/** `WorkspaceConfig.outputs`. */
+export interface WorkspaceOutputs {
+  /** The `outputs.clean` of every task that does not set its own. */
+  clean?: boolean
+}
+
 /** `WorkspaceConfig.cache`: where the cache lives and what a run does with it. */
 export interface CacheSettings {
   /**
@@ -93,10 +109,6 @@ export interface CacheSettings {
   policy?: string
   /** Which remote hits land on disk: `all` (the default), only the requested tasks' (`toplevel`), or `none`. */
   download?: 'all' | 'toplevel' | 'none'
-  /** The `cache.inputStability` of every task that does not set its own. */
-  inputStability?: InputStability
-  /** The `cache.outputs.clean` of every task that does not set its own. */
-  outputs?: { clean?: boolean }
   /**
    * Which runs keep a failed task's log and the files its outputs left in
    * the remote: CI runs (`'ci'`, the default), runs off CI (`'local'`), or
@@ -305,13 +317,15 @@ export interface TaskConfig {
    * keyed group: its inputs are a key its dependents fold, with no process.
    */
   inputs?: InputsConfig
+  /** What the task produces: saved on a miss, restored on a hit. Needs `cache: true`. */
+  outputs?: TaskOutputs
   /**
-   * Caching configuration. **Caching is opt-in.** If this field is omitted,
-   * the task always runs and nothing is read from or written to the cache.
-   * Requires `exec` and `inputs`: the key is the task's inputs, and a group
-   * runs nothing to cache.
+   * `true` caches the task. **Caching is opt-in.** Omitted or `false`, the
+   * task always runs and nothing is read from or written to the cache.
+   * Requires `exec`, `inputs` and `outputs`: the key is the task's inputs,
+   * and a group runs nothing to cache.
    */
-  cache?: CacheConfig
+  cache?: boolean
 }
 
 /**
@@ -335,7 +349,7 @@ export interface TaskConfig {
  * from the other coupled them both ways — a declaration added for
  * caching silently widened the sandbox, and a path the task needed had
  * to be laundered through the cache key to get it (2026-09-05).
- * A declared `cache.outputs` is NOT a write grant; the request
+ * A declared `outputs` is NOT a write grant; the request
  * `sandbox-request.ts` builds carries no write of its own and binds
  * `allow.write` alone. This comment claimed the opposite — here and on
  * both grant fields — while the file beside it and `schema.md` both said
@@ -391,6 +405,13 @@ export interface SandboxConfig {
   weakerWhenNested?: boolean
   /** Accept weaker network isolation (host proxy) for lower overhead. */
   weakerNetworkIsolation?: boolean
+  /**
+   * Refuse every read outside the workspace too (`/usr`, `~/.cache`, the
+   * system toolchain), not only the workspace's other projects. A path
+   * outside it is readable only when `allow.read` names it; the shell a
+   * task runs in stays readable, so a task can start.
+   */
+  hermetic?: boolean
 }
 
 /** The denials `sandbox.ignore` can leave out of the report: patterns per class. */
@@ -410,9 +431,9 @@ export interface SandboxGrants {
   read?: readonly string[]
   /**
    * Writable paths or globs. The task can write NOTHING without these:
-   * declaring `cache.outputs.files` grants no write, and a task whose
+   * declaring `outputs.files` grants no write, and a task whose
    * only declaration is its outputs writes into a tmpfs that evaporates
-   * (vx then warns that `cache.outputs` matched no files).
+   * (vx then warns that `outputs` matched no files).
    */
   write?: readonly string[]
   /**
@@ -585,17 +606,6 @@ export interface ExecEnv {
   secret?: readonly string[]
 }
 
-export interface CacheConfig {
-  /** What this task produces. Captured for restore on a cache hit. */
-  outputs: CacheOutputs
-  /**
-   * What a write to an input while the command runs means. Each field,
-   * highest first: its env var, this, the workspace's `inputStability`,
-   * the default (`'immutable'`, `'warn'`).
-   */
-  inputStability?: InputStability
-}
-
 export interface InputStability {
   /**
    * `'immutable'` (the default): any write to an input during the command
@@ -615,7 +625,7 @@ export interface InputStability {
   severity?: 'warn' | 'error'
 }
 
-export interface CacheOutputs {
+export interface TaskOutputs {
   /**
    * Files produced by this task, as project-relative globs. Pass `[]`
    * when the task has no files to capture (e.g. `lint`, `typecheck`).
@@ -640,7 +650,7 @@ export interface CacheOutputs {
    * (tsc's `.tsbuildinfo`) instead of removing them first. A run that
    * leaves a file it found untouched saves nothing, so an entry holds only
    * what a clean run would leave. A retry still starts clean. Omitted →
-   * the workspace's `cache.outputs.clean`, else `true`.
+   * the workspace's `outputs.clean`, else `true`.
    */
   clean?: boolean
 }
@@ -716,6 +726,13 @@ export interface InputsConfig {
    * tool versions, OS info, etc.
    */
   workspaceRuntime?: readonly string[]
+  /**
+   * What a write to an input while the command runs means for the save.
+   * Each field, highest first: its env var, this, the workspace's
+   * `inputs.stability`, the default (`'immutable'`, `'warn'`). Needs
+   * `cache: true`.
+   */
+  stability?: InputStability
 }
 
 /**
@@ -785,9 +802,7 @@ export function defineProject<const T extends ProjectConfig>(
           dependsOn?: readonly DependsOnEntry<Extract<keyof NonNullable<T['tasks']>, string>>[]
           exec?: Known<At<NonNullable<T['tasks']>[K], 'exec'>, ExecConfig>
           inputs?: Known<At<NonNullable<T['tasks']>[K], 'inputs'>, InputsConfig>
-          cache?: Known<At<NonNullable<T['tasks']>[K], 'cache'>, CacheConfig> & {
-            outputs?: Known<At<At<NonNullable<T['tasks']>[K], 'cache'>, 'outputs'>, CacheOutputs>
-          }
+          outputs?: Known<At<NonNullable<T['tasks']>[K], 'outputs'>, TaskOutputs>
         }
       }
     },
@@ -801,9 +816,11 @@ export function defineWorkspace<T extends WorkspaceConfig>(
       run?: Known<At<T, 'run'>, RunSettings> & {
         rules?: Known<At<At<T, 'run'>, 'rules'>, WorkspaceRules>
       }
-      cache?: Known<At<T, 'cache'>, CacheSettings> & {
-        inputStability?: Known<At<At<T, 'cache'>, 'inputStability'>, InputStability>
+      cache?: Known<At<T, 'cache'>, CacheSettings>
+      inputs?: Known<At<T, 'inputs'>, WorkspaceInputs> & {
+        stability?: Known<At<At<T, 'inputs'>, 'stability'>, InputStability>
       }
+      outputs?: Known<At<T, 'outputs'>, WorkspaceOutputs>
       lock?: Known<At<T, 'lock'>, LockSettings>
       watch?: Known<At<T, 'watch'>, WatchSettings>
     },

package/src/exec/executor.ts

@@ -43,6 +43,11 @@ export interface ExecuteSandbox {
    * machine's paths and platform, hands `sandboxRequestFor`.
    */
   readonly keyed?: readonly string[]
+  /**
+   * The dependencies' outputs it may read (absolute), which an executor
+   * that builds the request again hands `sandboxRequestFor` too.
+   */
+  readonly dependencyReads?: readonly string[]
 }
 
 /** One declared input file, as the cache key saw it. */
@@ -108,7 +113,7 @@ export interface ExecuteRequest {
   /** `${project}#${task}` — for executors that route or log by task. */
   readonly taskId: string
   readonly workspaceRoot: string
-  /** Present for cacheable tasks (the miss path); absent when the task declares no `cache`. */
+  /** Present for cacheable tasks (the miss path); absent for a task without `cache: true`. */
   readonly inputs?: TaskInputs
   /**
    * The task's cache key (present when the task is cacheable). An executor
@@ -145,6 +150,12 @@ export interface ExecuteRequest {
    * executor's `platforms`: its key includes it. Absent when the task names none.
    */
   readonly platform?: string
+  /**
+   * Which attempt of the task this is, from 2 when it retries; absent on
+   * the first. An executor that can, runs a retry somewhere other than
+   * the attempt before it, so the machine is not the flake.
+   */
+  readonly attempt?: number
   /**
    * Whether this task's outputs must land on the submitter's disk now.
    * 'eager' (or absent) = materialise as today. 'deferred' = leave them
@@ -377,6 +388,13 @@ export interface TaskExecutor {
    * anything but a finite number, reports none.
    */
   idealMs?(): number | undefined
+  /**
+   * The workers that would have run the run best, judged after it from
+   * what each task took: for the run summary, so its reader can change
+   * how many workers the executor may start and of what size. Asked once
+   * at the end, only when a sink is on. A throw reports none.
+   */
+  advice?(): readonly WorkerAdvice[]
   /**
    * Its own Chrome-trace events for `vx run --profile` (the machines it ran
    * tasks on, in time), asked once at the end, only when the flag is set.
@@ -423,6 +441,27 @@ export interface MachineReport {
   startMs?: number
 }
 
+/**
+ * Workers that would have run the run best (`TaskExecutor.advice`): `of`
+ * says on what. `declared`: as many of each size the executor may start
+ * as end it soonest; `more`: past each size's limit, when that ends it
+ * sooner; `any`: one shape a platform, of any cores, ending as soon for
+ * the least core time.
+ */
+export interface WorkerAdvice {
+  of: 'declared' | 'more' | 'any'
+  /** The run's end on them, from its start. */
+  endMs: number
+  workers: readonly {
+    count: number
+    cores: number
+    memoryBytes: number
+    platform?: string
+    /** The size it is, for `declared` and `more`. */
+    size?: string
+  }[]
+}
+
 /**
  * What a remote executor rejects with when it gives a task back: core runs
  * the same request on the local floor and says `reason` once (a remote that

package/src/exec/index.ts

@@ -64,6 +64,7 @@ export {
   type ExecuteSandbox,
   type InputFile,
   type MachineReport,
+  type WorkerAdvice,
   type ServerSpec,
   type TaskExecutor,
   type TaskInputs,

package/src/exec/sandbox-paths.ts

@@ -102,6 +102,8 @@ export function sandboxReads(
     readonly config: {
       readonly allowRead: readonly string[]
       readonly allowWrite: readonly string[]
+      /** Denies the whole host, not only `baseDenyRead`: only a grant reads. */
+      readonly hermetic?: boolean
     }
   },
   file: string,
@@ -109,7 +111,7 @@ export function sandboxReads(
   const real = toRealPath(file)
   const under = (g: string): boolean => atOrUnder(real, toRealPath(g))
   return (
-    !sandbox.baseDenyRead.some(under) ||
+    (sandbox.config.hermetic !== true && !sandbox.baseDenyRead.some(under)) ||
     [...sandbox.baseAllowRead, ...sandbox.config.allowRead, ...sandbox.config.allowWrite].some(
       under,
     )