@vzn/vx 0.0.645 → 0.0.648

package/src/orchestrator/plugin-host.ts

@@ -18,8 +18,15 @@ import {
   type ResolvedRemote,
 } from '../cache/index.js'
 import { localExecutor, type TaskExecutor } from '../exec/index.js'
-import { maskedLine, settleWithin, teardownTimeoutMs, UserError } from '../util/index.js'
-import type { ProjectConfig, WorkspaceConfig } from '../config.js'
+import {
+  errorCode,
+  maskedLine,
+  settleWithin,
+  teardownTimeoutMs,
+  thrownMessage,
+  UserError,
+} from '../util/index.js'
+import { PLATFORMS, type ProjectConfig, type WorkspaceConfig } from '../config.js'
 import { checkGraph, type GraphRules, type TaskNode } from '../graph/index.js'
 import type {
   CacheContext,
@@ -58,6 +65,8 @@ function isRecord(v: unknown): v is Record<string, unknown> {
 /** Every method a `cache` hook's `RemoteCacheLayer` requires (`hasMany` is optional). */
 export const REMOTE_CACHE_METHODS: readonly string[] = ['has', 'get', 'put']
 
+const OPTIONAL_REMOTE_METHODS = ['open', 'lend', 'hasMany', 'missing'] as const
+
 /** What a capability hook handed back must be what the seam runs. */
 function assertShape(
   plugin: VxPlugin,
@@ -91,10 +100,11 @@ async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>)
     // Masked here, not by whoever prints it: an embedder of `run()` and
     // a plugin's verb print it as they get it, and the throw quotes what the
     // plugin was told (a remote's reply, a header) (L-11).
+    // A plugin's own code survives (cli.md § Error codes): an agent
+    // branches on it.
     throw new UserError(
-      maskedLine(
-        `plugin '${plugin.name}' failed in ${hook}: ${err instanceof Error ? err.message : String(err)}`,
-      ),
+      maskedLine(`plugin '${plugin.name}' failed in ${hook}: ${thrownMessage(err)}`),
+      errorCode(err) === 'VX_E_INTERNAL' ? 'VX_E_REFUSED' : errorCode(err),
     )
   }
 }
@@ -267,6 +277,14 @@ function checkNodeShapes(nodes: Map<string, TaskNode>): void {
         throw new Error(`${key}'s ${field} is ${shown(fields[field])}, not a name`)
       }
     }
+    // A node copied under a new id kept the old taskName: the key read
+    // the id, `--exclude-dependencies` the name, and the two disagreed.
+    const id = (node as { id?: unknown }).id
+    if (id !== `${fields.projectName as string}#${fields.taskName as string}`) {
+      throw new Error(
+        `${key}'s id is ${shown(id)}, not its projectName#taskName (${fields.projectName as string}#${fields.taskName as string})`,
+      )
+    }
     const dir = fields.projectDir
     if (typeof dir !== 'string' || !path.isAbsolute(dir)) {
       throw new Error(`${key}'s projectDir is ${shown(dir)}, not an absolute path`)
@@ -274,6 +292,10 @@ function checkNodeShapes(nodes: Map<string, TaskNode>): void {
   }
 }
 
+// With `u`, a well-formed pair is one code point, so `Cs` matches only a lone half.
+const LONE_SURROGATE = /\p{Cs}/u
+const LONE_SURROGATES = /\p{Cs}/gu
+
 /**
  * `key` stage: every plugin may add `{ name: value }` material to every
  * task. Stored on the node as sorted `[plugin/name, value]` pairs so the
@@ -313,6 +335,13 @@ export async function applyKeyHooks(
             `plugin '${plugin.name}' failed in key: a name on ${node.id} holds a NUL, the fold's delimiter`,
           )
         }
+        // The fold hashes a part's UTF-8, which writes every lone surrogate
+        // as U+FFFD: `'\ud800'` and `'\ud801'` folded one key.
+        if (LONE_SURROGATE.test(name) || LONE_SURROGATE.test(value)) {
+          throw new UserError(
+            `plugin '${plugin.name}' failed in key: part '${name.replace(LONE_SURROGATES, '�')}' on ${node.id} holds a lone UTF-16 surrogate, which the key cannot tell from another`,
+          )
+        }
         parts.push([`${plugin.name}/${name}`, value])
       }
     }
@@ -364,18 +393,35 @@ export async function claimedAffected(
 ): Promise<Set<string> | undefined> {
   const answer = await safe(plugin, 'fingerprint', () => plugin.fingerprint!.affected(change, ctx))
   if (answer === undefined) return undefined
-  if (typeof answer === 'string' || typeof answer !== 'object' || answer === null) {
+  // A plain object is no list: `for…of` threw "is not iterable", naming
+  // neither the plugin nor the hook.
+  if (
+    typeof answer === 'string' ||
+    typeof answer !== 'object' ||
+    answer === null ||
+    typeof (answer as Partial<Iterable<unknown>>)[Symbol.iterator] !== 'function'
+  ) {
     throw new UserError(
       `plugin '${plugin.name}' failed in fingerprint: returned ${describeValue(answer)}, not a list of project names`,
     )
   }
   const names = new Set<string>()
-  for (const name of answer as Iterable<unknown>) {
+  // A name no project carries selected nothing, and the tasks it meant to
+  // select did not run, with no word said.
+  const known = new Set(ctx.projects.map((p) => p.name))
+  // A lazy list (a generator) runs the plugin's code as it is read.
+  const read = await safe(plugin, 'fingerprint', () => [...(answer as Iterable<unknown>)])
+  for (const name of read) {
     if (typeof name !== 'string') {
       throw new UserError(
         `plugin '${plugin.name}' failed in fingerprint: affected project ${describeValue(name)} is not a name`,
       )
     }
+    if (!known.has(name)) {
+      throw new UserError(
+        `plugin '${plugin.name}' failed in fingerprint: affected project ${JSON.stringify(name)} is not a project in this workspace`,
+      )
+    }
     names.add(name)
   }
   return names
@@ -386,21 +432,20 @@ export async function claimedAffected(
  * (`FingerprintClaim.extraFiles`); `undefined` when it names none it can
  * answer for, and a plugin that throws is refused by its name.
  */
-export function claimedExtraFiles(
+export async function claimedExtraFiles(
   plugin: VxPlugin,
   file: string,
   bytes: Uint8Array,
-): readonly string[] | undefined {
+  ctx: FingerprintContext,
+): Promise<readonly string[] | undefined> {
   const read = plugin.fingerprint?.extraFiles
   if (read === undefined) return undefined
   let names: unknown
   try {
-    names = read.call(plugin.fingerprint, file, bytes)
+    names = await read.call(plugin.fingerprint, file, bytes, ctx)
   } catch (err) {
     throw new UserError(
-      maskedLine(
-        `plugin '${plugin.name}' failed in fingerprint: ${err instanceof Error ? err.message : String(err)}`,
-      ),
+      maskedLine(`plugin '${plugin.name}' failed in fingerprint: ${thrownMessage(err)}`),
     )
   }
   if (!Array.isArray(names) || names.some((n) => typeof n !== 'string')) {
@@ -427,11 +472,16 @@ export interface ScheduleRun {
 export async function applyScheduleHooks(
   plugins: readonly VxPlugin[],
   nodes: ReadonlyMap<string, TaskNode>,
-  ctx: Omit<ScheduleHookContext, 'cache' | 'refine'>,
+  ctx: Omit<ScheduleHookContext, 'cache' | 'refine' | 'onRefine' | 'refining'>,
   cacheFor: (plugin: string) => PluginCache = () => absentPluginCache,
   run: ScheduleRun = {},
 ): Promise<ReadonlyMap<string, number>> {
   const sets: (ReadonlyMap<string, number> | undefined)[] = []
+  const listeners: { plugin: VxPlugin; i: number; listener: () => void }[] = []
+  const promised = new Set<Promise<void>>()
+  const refining = async (): Promise<void> => {
+    while (promised.size > 0) await Promise.all(promised)
+  }
   const merged = (): ReadonlyMap<string, number> => {
     const out = new Map<string, number>()
     for (const set of sets) if (set !== undefined) for (const [id, w] of set) out.set(id, w)
@@ -439,17 +489,43 @@ export async function applyScheduleHooks(
   }
   for (const [i, plugin] of plugins.entries()) {
     if (plugin.schedule === undefined) continue
-    const refine = (weights: ReadonlyMap<string, number>): void => {
+    const refine = (
+      weights: ReadonlyMap<string, number> | Promise<ReadonlyMap<string, number> | undefined>,
+    ): void => {
+      if (weights instanceof Promise) {
+        const p: Promise<void> = weights
+          .then(
+            (w) => {
+              if (w !== undefined) refine(w)
+            },
+            (err: unknown) =>
+              ctx.warn(`[vx] plugin '${plugin.name}' failed to refine: ${thrownMessage(err)}`),
+          )
+          .finally(() => promised.delete(p))
+        promised.add(p)
+        return
+      }
       if (run.refined === undefined) return
       try {
         sets[i] = scheduleWeights(plugin, weights, nodes)
       } catch (err) {
-        ctx.warn(`[vx] ${err instanceof Error ? err.message : String(err)}; refine ignored`)
+        ctx.warn(`[vx] ${thrownMessage(err)}; refine ignored`)
         return
       }
       run.refined(merged())
+      for (const l of listeners) {
+        if (l.i === i) continue
+        try {
+          l.listener()
+        } catch (err) {
+          ctx.warn(`[vx] plugin '${l.plugin.name}' failed in onRefine: ${thrownMessage(err)}`)
+        }
+      }
     }
-    const own = { ...ctx, cache: cacheFor(plugin.name), refine }
+    const onRefine = (listener: () => void): void => {
+      if (run.refined !== undefined) listeners.push({ plugin, i, listener })
+    }
+    const own = { ...ctx, cache: cacheFor(plugin.name), refine, onRefine, refining }
     const call = (): Promise<ReadonlyMap<string, number> | undefined> =>
       safe(plugin, 'schedule', () => plugin.schedule!(nodes, own))
     const weights = await (run.step === undefined
@@ -529,6 +605,11 @@ export function buildAdmission(
           verdict.catch(() => {})
           throw new Error('returned a Promise; admit is synchronous')
         }
+        // `0` or `42` admitted beside a running task with no word: a policy
+        // answering a count enforced nothing.
+        if (verdict !== undefined && typeof verdict !== 'boolean') {
+          throw new Error(`returned ${describeValue(verdict)}, not true or false`)
+        }
         if (verdict !== false) continue
         if (running.size > 0) return false
         if (!overridden.has(plugin)) {
@@ -539,7 +620,7 @@ export function buildAdmission(
         }
       } catch (err) {
         broken.add(plugin)
-        const m = err instanceof Error ? err.message : String(err)
+        const m = thrownMessage(err)
         warn(
           `[vx] plugin '${plugin.name}' failed in admit: ${m}; admitting every task from here on`,
         )
@@ -557,13 +638,15 @@ export interface CacheHost extends CacheContext {
   readonly remotes?: ResolvedRemote[]
   /** Uploads at once, per remote (`cache.concurrency.upload`). */
   readonly uploadConcurrency?: number
+  /** What another machine's run lent, by plugin: each plugin's `ctx.lent`. */
+  readonly lentBy?: () => Readonly<Record<string, string>> | undefined
 }
 
 /**
  * Collect every plugin's remote (`cache` hook) in declaration order and
  * layer each over the local store: a lookup asks the local store first,
- * then each remote in order (owner, 2026-10-13), and a save reaches every
- * remote. The run's policy alone gates each remote (M, 2026-10-16: a
+ * then each remote in order (2026-10-13), and a save reaches every
+ * remote. The run's policy alone gates each remote (2026-10-16: a
  * plugin moves bytes, it never decides reads or writes); a remote's throw is a miss and a warning naming its plugin. No
  * remote → the local store alone.
  */
@@ -571,13 +654,26 @@ export async function resolveCache(
   plugins: readonly VxPlugin[],
   host: CacheHost,
 ): Promise<CacheLayer> {
-  const { localCache, policy, remotes, uploadConcurrency, ...ctx } = host
+  const { localCache, policy, remotes, uploadConcurrency, lentBy, ...base } = host
   const resolved: ResolvedRemote[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
+    const ctx: CacheContext =
+      lentBy === undefined ? base : { ...base, lent: () => lentBy()?.[plugin.name] }
     const remote = await safe(plugin, 'cache', () => plugin.cache!(ctx))
     if (remote === undefined) continue
     assertShape(plugin, 'cache', remote, REMOTE_CACHE_METHODS, 'a remote cache layer')
+    // `hasMany: true` failed every batch probe, and `missing: true` every
+    // upload, each said per call as the remote's own fault.
+    const odd = OPTIONAL_REMOTE_METHODS.filter(
+      (m) => remote[m] !== undefined && typeof remote[m] !== 'function',
+    )
+    if (odd.length > 0) {
+      throw new UserError(
+        `plugin '${plugin.name}' returned from cache something that is not a remote cache layer: ` +
+          `${odd.join(', ')} ${odd.length === 1 ? 'not a function' : 'not functions'}`,
+      )
+    }
     const entry: ResolvedRemote = {
       remote,
       plugin: plugin.name,
@@ -608,9 +704,7 @@ const executorPlugin = new WeakMap<TaskExecutor, string>()
  */
 export function nameExecutorFailure(executor: TaskExecutor, err: unknown): unknown {
   if (!executorPlugin.has(executor)) return err
-  const named = new UserError(
-    `${executorLabel(executor)} failed in execute: ${err instanceof Error ? err.message : String(err)}`,
-  )
+  const named = new UserError(`${executorLabel(executor)} failed in execute: ${thrownMessage(err)}`)
   named.cause = err
   return named
 }
@@ -623,23 +717,47 @@ export function executorLabel(executor: TaskExecutor): string {
     : `plugin '${plugin}' (executor '${executor.name}')`
 }
 
+/** What `executorDemand` returns: the run's three calls into it. */
+export interface ExecutorDemand {
+  /** Whether any executor asked: with none, every call does nothing. */
+  readonly any: boolean
+  /** A task finished: dropped, and its executor told once demand settled. */
+  finished(id: string): void
+  /**
+   * The placed tasks the run's cache answers: dropped, and each executor
+   * told its demand for the first time. Before it a finish narrows
+   * silently, so an executor never sizes for what restores. The first
+   * call counts; the rest do nothing.
+   */
+  settle(hits: Iterable<string>, missed?: Iterable<string>): void
+  /** A task about to execute: back in if `settle` dropped it (its artifact was gone). */
+  executing(id: string): void
+}
+
+const NO_DEMAND: ExecutorDemand = {
+  any: false,
+  finished: () => {},
+  settle: () => {},
+  executing: () => {},
+}
+
 /**
  * Demand: what each executor still has left to run. An executor that
  * provisions per task (a container, an allocation, a pod) otherwise has to
  * guess from `capacity` alone and hold everything until teardown. Built
  * ONLY for executors that asked: with none declared there is no map, no
- * set, and the returned narrower does nothing.
+ * set, and every call does nothing.
  *
  * The SAME set is handed back every time, narrowed in place: a consumer
  * reading it later sees the truth rather than a stale snapshot. A hint,
  * as `admit` is: one that throws is named once and asked no more, where
  * it surfaced as a bare stack, or mid-run from the completion path
- * (item 1022). Returns the call that drops a finished task's id.
+ * (item 1022).
  */
 export function executorDemand(
   placed: ReadonlyMap<string, TaskExecutor>,
   warn: (message: string) => void,
-): (id: string) => void {
+): ExecutorDemand {
   const demandOf = new Map<TaskExecutor, Set<string>>()
   for (const [id, executor] of placed) {
     if (executor.demand === undefined) continue
@@ -647,31 +765,72 @@ export function executorDemand(
     if (remaining === undefined) demandOf.set(executor, (remaining = new Set()))
     remaining.add(id)
   }
-  if (demandOf.size === 0) return () => {}
+  if (demandOf.size === 0) return NO_DEMAND
+  // Of the placed tasks, those the cache was asked and holds nowhere.
+  const missed = new Set<string>()
   const tell = (executor: TaskExecutor, remaining: ReadonlySet<string>): void => {
     const failed = (err: unknown): void => {
       if (!demandOf.delete(executor)) return
-      const m = err instanceof Error ? err.message : String(err)
+      const m = thrownMessage(err)
       warn(`[vx] ${executorLabel(executor)} failed in demand: ${m}; not asked again this run`)
     }
     try {
       // An `async demand` that rejects did so where no one listened: an
       // unhandled rejection, a stack, the run killed. Its rejection is a
       // throw like any other.
-      const ret: unknown = executor.demand!(remaining)
+      const ret: unknown = executor.demand!(remaining, missed)
       if (ret instanceof Promise) ret.catch(failed)
     } catch (err) {
       failed(err)
     }
   }
-  for (const [executor, remaining] of demandOf) tell(executor, remaining)
-  return (id) => {
-    for (const [executor, remaining] of demandOf) {
-      if (remaining.delete(id)) tell(executor, remaining)
-    }
+  let settled = false
+  const done = new Set<string>()
+  const ran = new Set<string>()
+  const dropped = new Set<string>()
+  return {
+    any: true,
+    finished(id) {
+      done.add(id)
+      missed.delete(id)
+      for (const [executor, remaining] of demandOf) {
+        if (remaining.delete(id) && settled) tell(executor, remaining)
+      }
+    },
+    settle(hits, misses = []) {
+      if (settled) return
+      settled = true
+      for (const id of misses) if (placed.has(id) && !done.has(id)) missed.add(id)
+      for (const id of hits) {
+        if (ran.has(id) || done.has(id)) continue
+        const executor = placed.get(id)
+        if (executor !== undefined && demandOf.get(executor)?.delete(id)) dropped.add(id)
+      }
+      for (const [executor, remaining] of demandOf) tell(executor, remaining)
+    },
+    executing(id) {
+      ran.add(id)
+      if (!dropped.delete(id)) return
+      const executor = placed.get(id)!
+      const remaining = demandOf.get(executor)
+      if (remaining === undefined) return
+      remaining.add(id)
+      tell(executor, remaining)
+    },
   }
 }
 
+const EXECUTOR_FLAGS = ['remote', 'sandbox', 'servers', 'runtime', 'exclusive', 'timeouts'] as const
+const EXECUTOR_HOOKS = [
+  'accepts',
+  'demand',
+  'footer',
+  'machines',
+  'idealMs',
+  'profile',
+  'running',
+] as const
+
 /**
  * Collect every plugin's `executor`, in declaration order, with core's
  * own appended at the tail: per task, `selectExecutor` takes the first
@@ -698,6 +857,35 @@ export async function resolveExecutors(
         `plugin '${plugin.name}' returned executor '${executor.name}' with capacity ${typeof capacity === 'number' ? String(capacity) : JSON.stringify(capacity)}: it must be a positive integer`,
       )
     }
+    // Read as `=== true`: `remote: 'yes'` ran a remote executor as a local one.
+    for (const flag of EXECUTOR_FLAGS) {
+      const v: unknown = executor[flag]
+      if (v !== undefined && typeof v !== 'boolean') {
+        throw new UserError(
+          `plugin '${plugin.name}' returned executor '${executor.name}' with ${flag} ${typeof v === 'string' ? JSON.stringify(v) : typeof v === 'object' && v !== null ? describeValue(v) : String(v as number)}: it must be true or false`,
+        )
+      }
+    }
+    const platforms: unknown = executor.platforms
+    if (
+      platforms !== undefined &&
+      !(
+        Array.isArray(platforms) &&
+        platforms.length > 0 &&
+        platforms.every((p) => (PLATFORMS as readonly unknown[]).includes(p))
+      )
+    ) {
+      throw new UserError(
+        `plugin '${plugin.name}' returned executor '${executor.name}' with platforms ${JSON.stringify(platforms)}: it must be a non-empty array of ${PLATFORMS.join(', ')}`,
+      )
+    }
+    for (const hook of EXECUTOR_HOOKS) {
+      const v: unknown = executor[hook]
+      if (v !== undefined && typeof v !== 'function')
+        throw new UserError(
+          `plugin '${plugin.name}' returned executor '${executor.name}' with ${hook} that is not a function`,
+        )
+    }
     executorPlugin.set(executor, plugin.name)
     executors.push(executor)
   }
@@ -710,7 +898,10 @@ export async function resolveExecutors(
 
 /**
  * End-of-run plugin lifecycle: each plugin's optional `teardown()`, in
- * declaration order. Crash-isolated — a throwing teardown is logged and
+ * declaration order, a plugin that supplies a remote cache after every
+ * other: a teardown may write through the cache (`RunReport`), and one
+ * that revoked its token first refused the write (main 7bdbf01: the
+ * schedule's timings, put after the Vercel token's revoke). Crash-isolated — a throwing teardown is logged and
  * skipped, never propagated — and each call is time-bounded by
  * {@link teardownTimeoutMs}. Runs on every exit of a run once its plugins'
  * factories ran, and of a plan (item 1021); the finally-path disposers
@@ -731,7 +922,8 @@ export async function teardownPlugins(
   report?: RunReport,
   step: <T>(id: string, work: () => Promise<T>) => Promise<T> = (_id, work) => work(),
 ): Promise<void> {
-  for (const plugin of plugins) {
+  const last = (p: VxPlugin): number => (p.cache === undefined ? 0 : 1)
+  for (const plugin of plugins.toSorted((a, b) => last(a) - last(b))) {
     if (plugin.teardown === undefined) continue
     const ms = teardownTimeoutMs()
     try {
@@ -745,9 +937,7 @@ export async function teardownPlugins(
         warn(`[vx] plugin '${plugin.name}' teardown timed out after ${ms}ms; it did not complete`)
       }
     } catch (err) {
-      warn(
-        `[vx] plugin '${plugin.name}' failed in teardown: ${err instanceof Error ? err.message : String(err)}`,
-      )
+      warn(`[vx] plugin '${plugin.name}' failed in teardown: ${thrownMessage(err)}`)
     }
   }
 }