@vzn/vx 0.0.18 → 0.0.21

package/src/orchestrator/placement.ts

@@ -0,0 +1,182 @@
+// Where each task runs: the placement of a graph over the resolved
+// executors, and the plan-mode view of it. Split from run.ts on 2026-09-10
+// (pure motion). A task is pinned to this machine when it is persistent,
+// depends on a persistent task, or says `exec.remote: false`; everything
+// else asks the executors in declaration order, and the local floor takes
+// what nothing claimed.
+
+import { machineParallelism } from '../util/index.js'
+import { selectExecutor, type TaskExecutor } from '../exec/index.js'
+import { isGroupTask, type TaskNode } from '../graph/index.js'
+import { resolveDownloadModes } from './download-policy.js'
+import type { Logger } from './logger.js'
+import { resolveExecutors } from './plugin-host.js'
+import type { prepareRun } from './prepare.js'
+
+/**
+ * A task is pinned to this machine when it is persistent, transitively
+ * depends on a persistent task (a worker cannot reach a port on the
+ * submitter), or declares `exec.remote: false`.
+ */
+export function pinnedLocalSet(nodes: Map<string, TaskNode>): Set<string> {
+  const pinned = new Set<string>()
+  const memo = new Map<string, boolean>()
+  const visit = (id: string): boolean => {
+    const known = memo.get(id)
+    if (known !== undefined) return known
+    const node = nodes.get(id)
+    if (node === undefined) return false
+    memo.set(id, false) // cycle guard; the graph builder already rejects cycles
+    const result =
+      node.config.exec?.persistent !== undefined ||
+      node.config.exec?.remote === false ||
+      node.deps.some((d) => visit(d))
+    memo.set(id, result)
+    if (result) pinned.add(id)
+    return result
+  }
+  for (const id of nodes.keys()) visit(id)
+  return pinned
+}
+
+export interface Placements {
+  executors: Map<string, TaskExecutor>
+  /**
+   * `exec.remote: 'only'` tasks that no REMOTE executor took — a NO-OP on
+   * this machine: never executed, declared outputs never cleaned or
+   * restored. The task exists to produce a remote input tree; without a
+   * remote pool, dependents use the machine's ambient state exactly as they
+   * did before the field existed.
+   */
+  remoteOnlyNoop: Set<string>
+  /** `'only'` tasks a remote executor DID take — executed remotely, outputs stay remote. */
+  remoteOnly: Set<string>
+}
+
+export function placeTasks(
+  nodes: Map<string, TaskNode>,
+  executors: readonly TaskExecutor[],
+  pinAllLocal = false,
+): Placements {
+  const pinned = pinnedLocalSet(nodes)
+  const placements: Placements = {
+    executors: new Map(),
+    remoteOnlyNoop: new Set(),
+    remoteOnly: new Set(),
+  }
+  for (const node of nodes.values()) {
+    if (isGroupTask(node) || node.config.exec?.persistent !== undefined) continue
+    const executor = selectExecutor(executors, {
+      taskId: node.id,
+      projectName: node.projectName,
+      projectDir: node.projectDir,
+      command: node.config.exec!.command,
+      pinnedLocal: pinAllLocal || pinned.has(node.id),
+      cacheable: node.config.cache !== undefined,
+    })
+    placements.executors.set(node.id, executor)
+    if (node.config.exec?.remote === 'only') {
+      // A pinned 'only' task (it transitively depends on a persistent one)
+      // lands here too: pinning wins, so it noops rather than shipping.
+      if (executor.remote === true) placements.remoteOnly.add(node.id)
+      else placements.remoteOnlyNoop.add(node.id)
+    }
+  }
+  return placements
+}
+
+/**
+ * `executorOf` for `planRun`, or nothing. Declining plugins, a single
+ * executor, or a resolution error all yield nothing: `--dry` is an
+ * inspection command and must not fail over a label. The error is still
+ * said, on the status line, in the plugin's name: the run this plan
+ * previews would refuse on it, and a plan that hid that would read as
+ * "everything lands locally".
+ */
+export async function planExecutorOf(
+  prepared: Awaited<ReturnType<typeof prepareRun>>,
+  log: Logger,
+  policy: 'all' | 'toplevel' | 'none',
+): Promise<{
+  executorOf?: (id: string) => string | undefined
+  downloadOf?: (id: string) => 'eager' | 'deferred' | 'never' | undefined
+  downloadDowngrades?: ReadonlyArray<{ taskId: string; reason: string }>
+}> {
+  let executors: readonly TaskExecutor[]
+  try {
+    executors = await resolveExecutors(prepared.plugins, {
+      workspaceRoot: prepared.workspaceRoot,
+      cacheDir: prepared.cacheDir,
+      warn: (m: string) => log.status(m),
+      concurrency: machineParallelism(),
+    })
+  } catch (err) {
+    log.status(
+      `[vx] placement not shown — ${err instanceof Error ? err.message : String(err)} (the run would refuse on it)`,
+    )
+    return {}
+  }
+  const placements = placeTasks(prepared.nodes, executors)
+  // Download modes need placement regardless of how many executors there
+  // are (a single REMOTE one still defers); executor LABELS only earn their
+  // column when there is a choice to report.
+  const download =
+    policy === 'all'
+      ? undefined
+      : resolveDownloadModes({
+          nodes: prepared.nodes,
+          policy,
+          localPlaced: new Set(
+            [...prepared.nodes.keys()].filter(
+              (id) => placements.executors.get(id)?.remote !== true,
+            ),
+          ),
+          remoteOnly: placements.remoteOnly,
+        })
+  return {
+    ...(executors.length < 2
+      ? {}
+      : {
+          executorOf: (id: string) =>
+            placements.remoteOnlyNoop.has(id) ? 'noop' : placements.executors.get(id)?.name,
+        }),
+    ...(download === undefined
+      ? {}
+      : {
+          downloadOf: (id: string) => download.modeOf.get(id),
+          downloadDowngrades: [...download.downgrades].map(([taskId, reason]) => ({
+            taskId,
+            reason,
+          })),
+        }),
+  }
+}
+
+/**
+ * Stands in for the executor of a task that was never placed — a group task
+ * (runs nothing) or a persistent one (`executePersistentTask` owns it and
+ * never reads this field). It THROWS rather than silently picking some
+ * executor from the list, so a refactor that routes such a task through the
+ * exec path fails loudly instead of shipping a localhost server to a worker.
+ */
+export const UNPLACED_EXECUTOR: TaskExecutor = {
+  name: 'unplaced',
+  execute: (req) => {
+    throw new Error(`internal error: ${req.taskId} reached an executor without being placed`)
+  },
+}
+
+export function hasPooledExecutor(executors: readonly TaskExecutor[]): boolean {
+  return executors.some((e) => e.capacity !== undefined)
+}
+
+export function poolOfPlacement(
+  placements: Placements,
+): (id: string) => { name: string; capacity: number } | undefined {
+  return (id) => {
+    const executor = placements.executors.get(id)
+    return executor?.capacity === undefined
+      ? undefined
+      : { name: executor.name, capacity: executor.capacity }
+  }
+}

package/src/orchestrator/plugin-host.ts

@@ -1,20 +1,22 @@
 // Plugin consultation for the run-level extension points (cache / executor).
-// Each function asks the plugins in order. Nothing is applied by default:
-// core's own executor and cache are plugins under src/plugins/ that a
-// workspace declares like any other, so a list with no provider for a
-// load-bearing capability fails fast with MISSING_PLUGIN_HINT.
+// Each function asks the plugins in order, and CORE IS THE TAIL: running
+// here and caching here are what those words mean in the absence of a
+// plugin placing work elsewhere or storing it somewhere else. A plugin
+// goes in front — it takes what it accepts, and what it declines lands on
+// the floor. No plugin is required for a plain local run.
 //
-// See docs/design/core-cloud-split-2026-06.md §5.1.
+// See docs/design/pipeline-2026-09.md.
 
 import { ChainedCache, type CacheLayer } from '../cache/index.js'
-import type { TaskExecutor } from '../exec/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 { detectCycle, type TaskNode } from '../graph/index.js'
-import { MISSING_PLUGIN_HINT } from './missing-plugin.js'
 import type {
   CacheContext,
   ExecutorContext,
+  FingerprintChange,
+  FingerprintContext,
   GraphHookContext,
   KeyHookContext,
   ProjectHookContext,
@@ -25,11 +27,57 @@ import type {
 
 /**
  * Run a capability factory with crash isolation. A throw becomes a clean
- * `UserError` naming the plugin + hook for the load-bearing capabilities
- * (`cache`/`executor`/`setup`) — a broken cache or executor must abort with
- * a clear message, never silently degrade. For `eventSink` the caller
- * logs-and-skips instead (observability must never break a run).
+ * `UserError` naming the plugin + hook: every stage and capability resolved
+ * here is load-bearing, so a broken one must abort with a clear message,
+ * never silently degrade. (Telemetry sinks are the observe-only exception,
+ * and telemetry-host.ts logs-and-skips them instead.)
  */
+/** `a string`, `an array`, `null`, `a number` — for a refusal that names what came back. */
+function describeValue(v: unknown): string {
+  if (v === null) return 'null'
+  if (Array.isArray(v)) return 'an array'
+  const t = typeof v
+  return t === 'object' ? 'an object' : `a ${t}`
+}
+
+/** What a capability hook handed back must be what the seam runs. */
+/** Every method `CacheLayer` requires (the optional ones are probed with `?.`). */
+export const CACHE_LAYER_METHODS: readonly string[] = [
+  'key',
+  'get',
+  'has',
+  'prefetch',
+  'loadOutputFilesBatch',
+  'isOutputsCurrent',
+  'restoreOutputs',
+  'save',
+  'ingest',
+  'recordRunBundle',
+  'stats',
+  'hashFile',
+  'outputsPath',
+  'prune',
+  'close',
+]
+
+function assertShape(
+  plugin: VxPlugin,
+  hook: string,
+  value: unknown,
+  methods: readonly string[],
+  what: string,
+): void {
+  const missing =
+    value === null || typeof value !== 'object'
+      ? methods
+      : methods.filter((m) => typeof (value as Record<string, unknown>)[m] !== 'function')
+  if (missing.length === 0) return
+  throw new UserError(
+    `plugin '${plugin.name}' returned from ${hook} something that is not ${what}: ` +
+      `missing ${missing.map((m) => `${m}()`).join(', ')}`,
+  )
+}
+
 async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>): Promise<T> {
   try {
     return await fn()
@@ -49,7 +97,7 @@ async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>)
 
 export function hasHook(
   plugins: readonly VxPlugin[],
-  hook: 'config' | 'project' | 'graph' | 'key' | 'schedule',
+  hook: 'config' | 'project' | 'graph' | 'key' | 'schedule' | 'admit',
 ): boolean {
   for (const p of plugins) if (p[hook] !== undefined) return true
   return false
@@ -72,18 +120,23 @@ export async function applyProjectHooks(
   plugins: readonly VxPlugin[],
   config: ProjectConfig,
   ctx: ProjectHookContext,
+  /** Runs after EACH plugin's edit, so a refusal can name the plugin that made it. */
+  afterEach?: (plugin: VxPlugin) => void,
 ): Promise<void> {
   for (const plugin of plugins) {
     if (plugin.project === undefined) continue
     await safe(plugin, 'project', () => plugin.project!(config, ctx))
+    afterEach?.(plugin)
   }
 }
 
 /**
  * `graph` stage: every plugin edits the task graph in place, then the graph
- * is checked the way the builder checks its own output — every dep names a
- * node in the graph, and there is no cycle. A violation is reported against
- * the LAST plugin that ran, which is the one whose edit made it so.
+ * is checked ONCE the way the builder checks its own output — every dep
+ * names a node in the graph, and there is no cycle. A violation is reported
+ * against the LAST plugin that ran: usually the one whose edit made it so,
+ * but an earlier plugin's edit that a later one left in place is blamed on
+ * the later one, since nothing is checked between plugins.
  */
 export async function applyGraphHooks(
   plugins: readonly VxPlugin[],
@@ -125,6 +178,14 @@ export async function applyKeyHooks(
       if (plugin.key === undefined) continue
       const material = await safe(plugin, 'key', () => plugin.key!(node, ctx))
       if (material === undefined) continue
+      // `Object.entries` over a string yields its characters as string
+      // values, so a plugin returning `'v22'` used to fold parts named
+      // '0', '1', '2' into every key — silently, and permanently.
+      if (typeof material !== 'object' || material === null || Array.isArray(material)) {
+        throw new UserError(
+          `plugin '${plugin.name}' failed in key: returned ${describeValue(material)}, not a record of string values`,
+        )
+      }
       for (const [name, value] of Object.entries(material)) {
         if (typeof value !== 'string') {
           throw new UserError(
@@ -141,6 +202,50 @@ export async function applyKeyHooks(
   }
 }
 
+/**
+ * The fingerprint files the plugins claim (`VxPlugin.fingerprint`), each
+ * with its one claimant. The schema refused a second claimant and an
+ * unknown name, so this only indexes.
+ */
+export function fingerprintClaims(plugins: readonly VxPlugin[]): ReadonlyMap<string, VxPlugin> {
+  const claims = new Map<string, VxPlugin>()
+  for (const p of plugins) {
+    if (p.fingerprint === undefined) continue
+    for (const f of p.fingerprint.files) claims.set(f, p)
+  }
+  return claims
+}
+
+/**
+ * Ask a claimed file's plugin which projects a change to it affects.
+ * `undefined` is "every project" — the claimant could not tell — and a
+ * non-iterable answer is refused by name, so a plugin returning `'all'`
+ * cannot select the projects spelled a, l, l.
+ */
+export async function claimedAffected(
+  plugin: VxPlugin,
+  change: FingerprintChange,
+  ctx: FingerprintContext,
+): 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) {
+    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>) {
+    if (typeof name !== 'string') {
+      throw new UserError(
+        `plugin '${plugin.name}' failed in fingerprint: affected project ${describeValue(name)} is not a name`,
+      )
+    }
+    names.add(name)
+  }
+  return names
+}
+
 /**
  * `schedule` stage: the merged priorities map (a later plugin's weight for
  * a task overrides an earlier one's). Empty when no plugin answered.
@@ -155,6 +260,14 @@ export async function applyScheduleHooks(
     if (plugin.schedule === undefined) continue
     const weights = await safe(plugin, 'schedule', () => plugin.schedule!(nodes, ctx))
     if (weights === undefined) continue
+    // Iterating a string destructures its characters into `[id, w]` pairs
+    // that match no task — a plugin returning `'fast'` used to be a no-op
+    // with no word said.
+    if (!(weights instanceof Map)) {
+      throw new UserError(
+        `plugin '${plugin.name}' failed in schedule: returned ${describeValue(weights)}, not a Map of task id → weight`,
+      )
+    }
     for (const [id, w] of weights) {
       if (!nodes.has(id)) continue
       if (typeof w !== 'number' || !Number.isFinite(w)) {
@@ -168,13 +281,51 @@ export async function applyScheduleHooks(
   return merged
 }
 
+/**
+ * `admit` stage, built once per run into the predicate the scheduler asks
+ * at every local dispatch: every plugin that answers must admit. A plugin
+ * that throws is reported once and admits from then on — a policy never
+ * breaks a run — so the predicate is never the reason a task hangs.
+ * Undefined when no plugin answers, which keeps the scheduler on its
+ * count-only path.
+ */
+export function buildAdmission(
+  plugins: readonly VxPlugin[],
+  nodes: ReadonlyMap<string, TaskNode>,
+  concurrency: number,
+  warn: (message: string) => void,
+): ((id: string, running: ReadonlySet<string>) => boolean) | undefined {
+  const answering = plugins.filter((p) => p.admit !== undefined)
+  if (answering.length === 0) return undefined
+  const broken = new Set<VxPlugin>()
+  return (id, running) => {
+    const task = nodes.get(id)
+    if (task === undefined) return true
+    const ctx = {
+      running: [...running].flatMap((r) => nodes.get(r) ?? []),
+      concurrency,
+    }
+    for (const plugin of answering) {
+      if (broken.has(plugin)) continue
+      try {
+        if (plugin.admit!(task, ctx) === false) return false
+      } catch (err) {
+        broken.add(plugin)
+        const m = err instanceof Error ? err.message : String(err)
+        warn(`plugin '${plugin.name}' failed in admit: ${m}; admitting every task from here on`)
+      }
+    }
+    return true
+  }
+}
+
 /**
  * Collect every plugin's `cache` layer in declaration order. One layer is
  * used as is; two or more are chained (lookup walks them, save reaches all;
  * see ChainedCache). A bare local layer that another declared layer already
  * wraps (`layer.local === ctx.localCache`) is dropped, so a remote plugin
- * that layers over the local handle composes with `localCachePlugin()`
- * instead of writing the local store twice. No layer at all is a named error.
+ * that layers over the local handle does not also write the local store
+ * directly. A plugin declaring nothing leaves that store, unwrapped.
  */
 export async function resolveCache(
   plugins: readonly VxPlugin[],
@@ -184,25 +335,30 @@ export async function resolveCache(
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
     const layer = await safe(plugin, 'cache', () => plugin.cache!(ctx))
-    if (layer !== undefined) layers.push(layer)
-  }
-  if (layers.length === 0) {
-    const declined = plugins.filter((p) => p.cache !== undefined).map((p) => `${p.name} declined`)
-    throw new UserError(
-      `no cache plugin declared${declined.length > 0 ? ` (${declined.join(', ')})` : ''}. ${MISSING_PLUGIN_HINT}`,
-    )
+    if (layer === undefined) continue
+    // The seam's WHOLE contract, checked once here: a layer missing a
+    // method otherwise failed at the first task that reached it — an
+    // internal TypeError deep in the chain, naming neither the plugin nor
+    // the hook. Five names were checked before, so a layer with those five
+    // passed and died at its first hit inside restoreOutputs.
+    assertShape(plugin, 'cache', layer, CACHE_LAYER_METHODS, 'a cache layer')
+    layers.push(layer)
   }
+  // Core's own store is the TAIL of the chain — the floor under every
+  // lookup, not a plugin a workspace has to declare. A layer that WRAPS
+  // the local handle subsumes it below, so a remote plugin does not write
+  // the local store twice.
+  if (!layers.includes(ctx.localCache)) layers.push(ctx.localCache)
   const wrapsLocal = layers.some((l) => l !== ctx.localCache && l.local === ctx.localCache)
   const distinct = wrapsLocal ? layers.filter((l) => l !== ctx.localCache) : layers
   return distinct.length === 1 ? distinct[0]! : new ChainedCache(distinct)
 }
 
 /**
- * Collect every plugin's `executor`, in declaration order. Unlike
- * `cache` this is a LIST: per task, `selectExecutor` takes the first
- * that accepts. An empty list is the same authoring error as a missing
- * cache provider and fails the same way. A broken factory aborts — an
- * executor is load-bearing, not observational.
+ * Collect every plugin's `executor`, in declaration order, with core's
+ * own appended at the tail: per task, `selectExecutor` takes the first
+ * that accepts, and what every plugin declines runs here. A broken
+ * factory aborts — an executor is load-bearing, not observational.
  */
 export async function resolveExecutors(
   plugins: readonly VxPlugin[],
@@ -212,16 +368,17 @@ export async function resolveExecutors(
   for (const plugin of plugins) {
     if (plugin.executor === undefined) continue
     const executor = await safe(plugin, 'executor', () => plugin.executor!(ctx))
-    if (executor !== undefined) executors.push(executor)
-  }
-  if (executors.length === 0) {
-    const declined = plugins
-      .filter((p) => p.executor !== undefined)
-      .map((p) => `${p.name} declined`)
-    throw new UserError(
-      `no executor plugin declared${declined.length > 0 ? ` (${declined.join(', ')})` : ''}. ${MISSING_PLUGIN_HINT}`,
-    )
+    if (executor === undefined) continue
+    assertShape(plugin, 'executor', executor, ['execute'], 'an executor')
+    if (typeof executor.name !== 'string' || executor.name.length === 0) {
+      throw new UserError(`plugin '${plugin.name}' returned an executor with no name`)
+    }
+    executors.push(executor)
   }
+  // Core's own executor is the TAIL of every list, so a plugin executor
+  // that declines a task hands it back to this machine rather than
+  // failing the run.
+  executors.push(localExecutor())
   return executors
 }