@vzn/vx 0.0.651 → 0.0.653

package/src/exec/executor.ts

@@ -43,6 +43,16 @@ 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[]
+  /**
+   * The heads of those outputs (absolute): a refused read under one is a
+   * file beside them, reported. Handed `sandboxRequestFor` with them.
+   */
+  readonly dependencyReported?: readonly string[]
 }
 
 /** One declared input file, as the cache key saw it. */
@@ -74,8 +84,9 @@ export interface TaskInputs {
    * Dependencies whose cache keys are folded. `outputs` lists each one's
    * declared output files (workspace-relative POSIX, as stored with its cache
    * entry) — restored on disk before this task runs, so an input-shipping
-   * executor can include them in the input root. Empty when the upstream's
-   * entry is not in the local index (a non-cacheable dependency).
+   * executor can include them in the input root. A non-cacheable
+   * dependency's are its declared outputs found on disk; a cacheable one
+   * with no entry in the local index lists none.
    */
   readonly upstream: ReadonlyArray<{
     readonly taskId: string
@@ -104,11 +115,17 @@ export interface ServerSpec {
   readonly sandbox?: { readonly config: SandboxConfig; readonly nested: readonly string[] }
 }
 
+/**
+ * One task's command, as core hands it to an executor. A plugin
+ * executor's `outputs`, `envDefine` and `forwardArgs` are frozen copies:
+ * core saves the outputs after the command, and a config or the run's
+ * args are shared with other tasks.
+ */
 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 +162,18 @@ export interface ExecuteRequest {
    * executor's `platforms`: its key includes it. Absent when the task names none.
    */
   readonly platform?: string
+  /**
+   * The worker type to run it on, one of the executor's `workers`: the
+   * task's `exec.worker`, else the first type with one of its platforms.
+   * Absent when the executor names no types.
+   */
+  readonly worker?: 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
@@ -179,7 +208,8 @@ export interface ExecuteRequest {
   readonly onStderr: (chunk: string) => void
   /**
    * Aborted when the run stops (Ctrl-C, SIGTERM, SIGHUP or an embedder's
-   * `RunOptions.signal`) or when `timeoutMs` elapses. An executor ends its
+   * `RunOptions.signal`), when `timeoutMs` elapses, or when fail-fast
+   * withdraws a task `running` says is not begun. An executor ends its
    * work and returns: a child an executor spawned is not one core can
    * reach (H-10, H-12). One already aborted is work not to start (B-55).
    * Any exit after the timeout's abort, a 0 included, is a timeout. Core
@@ -225,10 +255,11 @@ export interface ExecuteResult extends RunResult {
    */
   readonly outputs?: { kind: 'disk' } | { kind: 'deferred'; materialize: () => Promise<void> }
   /**
-   * Tracked files the command changed where it ran, workspace-relative
-   * POSIX: an executor that runs it elsewhere says so, as this disk shows
-   * none of it. One the key read withholds the save under the key, as an
-   * input changed here does.
+   * Tracked files the command changed where it ran, and untracked ones it
+   * found there, workspace-relative POSIX: an executor that runs it
+   * elsewhere says so, as this disk shows none of it. One the key read, or
+   * one its inputs declare, withholds the save under the key, as an input
+   * changed here does.
    */
   readonly changed?: readonly string[]
   /**
@@ -280,9 +311,12 @@ export interface TaskExecutor {
   /** Runs the command somewhere else. Never offered a `pinnedLocal` task. */
   readonly remote?: boolean
   /**
-   * A `remote` executor that enforces `ExecuteRequest.sandbox` where it
-   * runs the command, as the local one does. It is offered sandboxed tasks
-   * and their dependants; the request's violations come back on the result.
+   * Enforces `ExecuteRequest.sandbox` where it runs the command, as the
+   * local one does; the request's violations come back on the result. Only
+   * such an executor is offered a task that declares `exec.sandbox`, here
+   * or remote: one that ran it unsandboxed passed a boundary it never
+   * checked and cached the output. A `remote` one is offered the
+   * dependants of a sandboxed task too.
    */
   readonly sandbox?: boolean
   /**
@@ -327,6 +361,14 @@ export interface TaskExecutor {
    * declares none is never offered such a task off this machine.
    */
   readonly platforms?: readonly string[]
+  /**
+   * Its worker types in order of preference, each with the platforms its
+   * machines run (`@vzn/vx-dte`'s `workers`). A task naming `exec.worker`
+   * is offered it only when it has that type on one of the task's
+   * platforms; any other task goes to the first type that fits, on
+   * `ExecuteRequest.worker`. Its `platforms` must list every one of them.
+   */
+  readonly workers?: ReadonlyArray<readonly [name: string, platforms: readonly string[]]>
   /**
    * How many tasks this executor runs at once. Its tasks then occupy a pool
    * of this size instead of the local worker slots, so a remote pool is not
@@ -334,7 +376,11 @@ export interface TaskExecutor {
    * is refused when the executor is resolved. Absent = the local pool.
    */
   readonly capacity?: number
-  /** Per-task opt-out at placement time. Absent = accepts every task it is offered. */
+  /**
+   * Per-task opt-out at placement time. Absent = accepts every task it is
+   * offered. `false` or `undefined` declines; any other non-boolean is
+   * refused, naming the plugin.
+   */
   accepts?(task: TaskPlacement): boolean
   /**
    * The tasks placed here that will run and have NOT finished yet — called
@@ -377,6 +423,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.
@@ -388,8 +441,17 @@ export interface TaskExecutor {
    * Where a task it was handed runs (`small#2`), for the live row; asked
    * per frame. `null` while it holds the task for a machine to begin it:
    * the row says `waiting`, and its clock starts when a machine begins it.
+   * Under `--continue=never` a failure aborts the `signal` of each task it
+   * answers `null` for, and the task is skipped, never started.
    */
   running?(taskId: string): string | null | undefined
+  /**
+   * A `servers` executor's: no task left in the run uses persistent task
+   * `taskId`, so each copy it started beside a dependant stops now, not at
+   * teardown. Core asks once, as the run stops its own copy (`schema.md`,
+   * "Stopped once nothing needs it"). A throw is ignored.
+   */
+  unneeded?(taskId: string): void
   execute(req: ExecuteRequest): Promise<ExecuteResult>
 }
 
@@ -413,7 +475,11 @@ export interface MachineReport {
   /** Bytes in use at once, at the most and on average. */
   memoryPeakBytes: number
   memoryAvgBytes: number
-  /** Core-time its tasks used over the core-time it had, 0 to 1. */
+  /**
+   * Its machine's busy core-time over the core-time it had, from its first
+   * task's send to its last one's end, 0 to 1 (its tasks' own where its
+   * machine said none): whether cores were left idle.
+   */
   utilization: number
   /** Cores the executor booked for the tasks it ran, on average over its time online. */
   bookedAvg?: number
@@ -423,6 +489,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
@@ -535,8 +622,8 @@ export function assertExecuteResult(
 
 /**
  * Place one task: the first executor, in declaration order, that may take
- * it — a `remote` executor is skipped for a `pinnedLocal` task, then
- * `accepts()` decides. Decided once per task before scheduling. The local
+ * it — a `remote` executor is skipped for a `pinnedLocal` task, any one
+ * `barred` names is skipped, then `accepts()` decides. Decided once per task before scheduling. The local
  * executor accepts everything, so with it declared the only throw is an
  * `accepts()` that threw: refused as `label` names that executor, where it
  * surfaced as a bare stack naming no plugin (item 1022).
@@ -547,10 +634,12 @@ export function selectExecutor(
   label: (executor: TaskExecutor) => string = (e) => `executor '${e.name}'`,
   /** `task.pinnedLocal` as `executor` sees it: one that enforces the sandbox or carries servers lifts some pins. */
   pinnedFor: (executor: TaskExecutor) => boolean = () => task.pinnedLocal,
+  /** Never offered the task: a sandboxed one is barred from an executor that does not enforce it. */
+  barred: (executor: TaskExecutor) => boolean = () => false,
 ): TaskExecutor {
   for (const executor of executors) {
     const pinned = pinnedFor(executor)
-    if (pinned && executor.remote === true) continue
+    if ((pinned && executor.remote === true) || barred(executor)) continue
     if (executor.accepts === undefined) return executor
     let taken: unknown
     try {
@@ -563,6 +652,17 @@ export function selectExecutor(
         taken.catch(() => {})
         throw new Error('returned a Promise; accepts is synchronous')
       }
+      // `'no'` was truthy and took the task; admit refuses the same answer.
+      if (taken !== undefined && typeof taken !== 'boolean') {
+        const t = typeof taken
+        const what =
+          taken === null
+            ? 'null'
+            : Array.isArray(taken)
+              ? 'an array'
+              : `${t === 'object' ? 'an' : 'a'} ${t}`
+        throw new Error(`returned ${what}, not true or false`)
+      }
     } catch (err) {
       const m = thrownMessage(err)
       throw new UserError(`${label(executor)} failed in accepts for ${task.taskId}: ${m}`)

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/kill-tree.ts

@@ -151,7 +151,7 @@ function stopGuard(): void {
 
 function guardWrite(line: string): void {
   if (typeof guardFd !== 'number') return
-  let deadline = Date.now() + GUARD_STALL_MS
+  let deadline = performance.now() + GUARD_STALL_MS
   // A turn's batch can be more than the queue takes at once: it goes in
   // pieces as the guard drains it, and only a guard that takes nothing for
   // the whole stall is gone. With one deadline for the batch, 2000 strikes
@@ -162,9 +162,9 @@ function guardWrite(line: string): void {
       const n = writeSync(guardFd, bytes, 0, Math.min(bytes.length, GUARD_PIECE))
       if (n === bytes.length) return
       bytes = bytes.subarray(n)
-      deadline = Date.now() + GUARD_STALL_MS
+      deadline = performance.now() + GUARD_STALL_MS
     } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'EAGAIN' || Date.now() >= deadline) break
+      if ((err as NodeJS.ErrnoException).code !== 'EAGAIN' || performance.now() >= deadline) break
       Bun.sleepSync(1)
     }
   }
@@ -414,7 +414,7 @@ export async function untilGroupsGone(
   children: readonly Child[],
   graceMs: number,
 ): Promise<Child[]> {
-  const deadline = Date.now() + graceMs
+  const deadline = performance.now() + graceMs
   let timer: ReturnType<typeof setTimeout> | undefined
   // Not unref'd: it is what guarantees progress when every other handle
   // has drained, and the grace is bounded either way.
@@ -426,8 +426,8 @@ export async function untilGroupsGone(
   ])
   if (timer !== undefined) clearTimeout(timer)
   let left = children.filter(groupAlive)
-  while (left.length > 0 && Date.now() < deadline) {
-    await Bun.sleep(Math.min(GROUP_POLL_MS, deadline - Date.now()))
+  while (left.length > 0 && performance.now() < deadline) {
+    await Bun.sleep(Math.min(GROUP_POLL_MS, deadline - performance.now()))
     left = left.filter(groupAlive)
   }
   return left
@@ -443,7 +443,7 @@ export async function untilGroupsGone(
  * and a group that ignored the SIGTERM went un-killed; there the group
  * signal is the answer and the grace ends the wait.
  */
-function groupAlive(child: Child): boolean {
+export function groupAlive(child: Child): boolean {
   if (!(child.pid > 0) || goneGroups.has(child)) return false
   try {
     process.kill(-child.pid, 0)