@vzn/vx 0.0.636 → 0.0.637

package/src/orchestrator/plugin-host.ts

@@ -8,11 +8,17 @@
 // See docs/design/pipeline-2026-09.md.
 
 import path from 'node:path'
-import { ChainedCache, type CacheLayer } from '../cache/index.js'
+import {
+  type Cache,
+  ChainedCache,
+  type CacheLayer,
+  type CachePolicy,
+  LayeredCache,
+} 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, WorkspaceRules } from '../config.js'
-import { checkGraph, type TaskNode } from '../graph/index.js'
+import type { ProjectConfig, WorkspaceConfig } from '../config.js'
+import { checkGraph, type GraphRules, type TaskNode } from '../graph/index.js'
 import type {
   CacheContext,
   DiscoverContext,
@@ -21,7 +27,7 @@ import type {
   FingerprintContext,
   GraphHookContext,
   KeyHookContext,
-  NamedProject,
+  DiscoveredProject,
   ProjectHookContext,
   ScheduleHookContext,
   VxPlugin,
@@ -46,24 +52,8 @@ function isRecord(v: unknown): v is Record<string, unknown> {
   return proto === Object.prototype || proto === null
 }
 
-/** 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',
-]
+/** Every method a `cache` hook's `RemoteCacheLayer` requires (`hasMany` is optional). */
+export const REMOTE_CACHE_METHODS: readonly string[] = ['has', 'get', 'put']
 
 /** What a capability hook handed back must be what the seam runs. */
 function assertShape(
@@ -96,7 +86,7 @@ async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>)
     return await fn()
   } catch (err) {
     // Masked here, not by whoever prints it: an embedder of `run()` and
-    // `vx mcp` print it as they get it, and the throw quotes what the
+    // 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).
     throw new UserError(
       maskedLine(
@@ -158,15 +148,21 @@ export async function applyConfigHooks(
 
 /**
  * `discover` stage: each plugin names directories to add to `projects`,
- * seeing the ones earlier plugins added. `add` turns one name into a meta
- * (null: already there) or refuses it.
+ * seeing the ones earlier plugins added. `add` turns one entry into the
+ * project it names, `added` when it is new, or refuses it. Returns every
+ * entry's edges with the project and plugin they came from, for the caller
+ * to resolve once every plugin has run.
  */
 export async function applyDiscoverHooks(
   plugins: readonly VxPlugin[],
   projects: ProjectMeta[],
   ctx: Omit<DiscoverContext, 'projects'>,
-  add: (named: NamedProject, plugin: VxPlugin) => Promise<ProjectMeta | null>,
-): Promise<void> {
+  add: (
+    entry: DiscoveredProject,
+    plugin: VxPlugin,
+  ) => Promise<{ meta: ProjectMeta; added: boolean }>,
+): Promise<DiscoveredEdges[]> {
+  const edges: DiscoveredEdges[] = []
   for (const plugin of plugins) {
     if (plugin.discover === undefined) continue
     const named = await safe(plugin, 'discover', () => plugin.discover!({ ...ctx, projects }))
@@ -175,11 +171,23 @@ export async function applyDiscoverHooks(
         `plugin '${plugin.name}' failed in discover: expected an array, got ${describeValue(named)}`,
       )
     }
-    for (const n of named as readonly NamedProject[]) {
-      const meta = await add(n, plugin)
-      if (meta !== null) projects.push(meta)
+    for (const entry of named as readonly DiscoveredProject[]) {
+      const { meta, added } = await add(entry, plugin)
+      if (added) projects.push(meta)
+      if (entry.deps !== undefined || entry.reach !== undefined) {
+        edges.push({ by: plugin.name, meta, deps: entry.deps, reach: entry.reach ?? [] })
+      }
     }
   }
+  return edges
+}
+
+export interface DiscoveredEdges {
+  readonly by: string
+  readonly meta: ProjectMeta
+  /** Absent when the entry carried none; `[]` still makes the workspace an edge source. */
+  readonly deps: readonly string[] | undefined
+  readonly reach: readonly string[]
 }
 
 /** `project` stage: every plugin edits one project's config in place. */
@@ -215,7 +223,7 @@ export async function applyGraphHooks(
   ctx: GraphHookContext,
   /** Runs after EACH plugin's edit, so a refused task config names the plugin that wrote it. */
   afterEach?: (plugin: VxPlugin) => void,
-  rules?: WorkspaceRules,
+  rules?: GraphRules,
 ): Promise<void> {
   let last: VxPlugin | undefined
   for (const plugin of plugins) {
@@ -466,58 +474,74 @@ export function buildAdmission(
   }
 }
 
+/** What `resolveCache` needs beyond a hook's context: the store and policy core owns. */
+export interface CacheHost extends CacheContext {
+  readonly localCache: Cache
+  readonly policy: CachePolicy
+}
+
 /**
- * Collect every plugin's `cache` layer in declaration order, with the local
- * store at the tail, and chain them (lookup walks them, save reaches all;
- * see ChainedCache). The local store is dropped when a declared layer wraps
- * it (`layer.local === ctx.localCache`), so a remote plugin that layers over
- * the local handle does not also write it directly. Only a single layer
- * left is used as is: the local store when no plugin declares one, or the
- * one layer that wraps it.
+ * 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, narrowed by a remote's `access`, and its scope
+ * gate each remote; a remote's throw is a miss and a warning naming its
+ * plugin. No remote → the local store alone.
  */
 export async function resolveCache(
   plugins: readonly VxPlugin[],
-  ctx: CacheContext,
+  host: CacheHost,
 ): Promise<CacheLayer> {
+  const { localCache, policy, ...ctx } = host
   const layers: CacheLayer[] = []
-  const owners = new Map<CacheLayer, string>()
+  const owners: string[] = []
   for (const plugin of plugins) {
     if (plugin.cache === undefined) continue
-    const layer = await safe(plugin, 'cache', () => plugin.cache!(ctx))
-    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)
-    if (!owners.has(layer)) owners.set(layer, `plugin '${plugin.name}'`)
+    const remote = await safe(plugin, 'cache', () => plugin.cache!(ctx))
+    if (remote === undefined) continue
+    // The hook returned a whole layer until 0.0.637: name the fix, not the
+    // three methods such a layer happens to have.
+    if (isRecordLike(remote) && typeof remote['restoreOutputs'] === 'function') {
+      throw new UserError(
+        `plugin '${plugin.name}' returned a cache layer from cache: since vx 0.0.637 the hook ` +
+          'returns the remote alone (a RemoteCacheLayer: has, get, put) and core layers it over ' +
+          'the local cache — return the remote you passed to LayeredCache',
+      )
+    }
+    assertShape(plugin, 'cache', remote, REMOTE_CACHE_METHODS, 'a remote cache layer')
+    const access = remote.access
+    const own: CachePolicy = {
+      ...policy,
+      remoteRead: policy.remoteRead && access?.read !== false,
+      remoteWrite: policy.remoteWrite && access?.write !== false,
+    }
+    layers.push(
+      new LayeredCache(localCache, remote, {
+        policy: own,
+        onRemoteError: (err) => ctx.warn(`[vx] plugin '${plugin.name}': ${err.message}`),
+      }),
+    )
+    owners.push(`the cache layer of plugin '${plugin.name}'`)
   }
-  // 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
-  if (distinct.length === 1) return distinct[0]!
+  if (layers.length === 0) return localCache
+  if (layers.length === 1) return layers[0]!
   // One line per layer and method: a layer that throws on every lookup
   // would otherwise print once per task.
   const told = new Set<string>()
-  return new ChainedCache(distinct, (i, method, err) => {
-    const layer = distinct[i]!
-    const who =
-      layer === ctx.localCache ? 'the local cache' : (owners.get(layer) ?? 'a cache layer')
+  return new ChainedCache(layers, (i, method, err) => {
     if (told.has(`${i}\0${method}`)) return
     told.add(`${i}\0${method}`)
     const m = err instanceof Error ? err.message : String(err)
     const then =
       method === 'save' ? 'the other layers still save' : 'a miss there; the next layer answers'
-    ctx.warn(`[vx] ${who} failed in cache ${method}: ${m}; ${then}`)
+    ctx.warn(`[vx] ${owners[i]} failed in cache ${method}: ${m}; ${then}`)
   })
 }
 
+function isRecordLike(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null
+}
+
 /** The plugin each resolved executor came from, so a hook of it that throws is named. */
 const executorPlugin = new WeakMap<TaskExecutor, string>()
 

package/src/orchestrator/plugin.ts

@@ -11,7 +11,7 @@
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { Cache, CacheLayer, CachePolicy } from '../cache/index.js'
+import type { Cache, RemoteCacheLayer } from '../cache/index.js'
 import { PLUGIN_PACKAGE, type ProjectConfig, type WorkspaceConfig } from '../config.js'
 import type { TaskExecutor } from '../exec/index.js'
 import type { TaskNode, TaskOutcome } from '../graph/index.js'
@@ -19,13 +19,14 @@ import { maskedLine, nearest, UserError } from '../util/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
 import type { EventBus, RunStartInfo } from './events.js'
 import type { TelemetryContext, TelemetrySink } from './telemetry.js'
+import type { Logger } from './logger.js'
 
 /**
  * A vx plugin. Contributes any subset of the run-level capabilities —
  * where work runs (executor), which cache is used (cache), who
  * observes the run (telemetry). It never changes WHAT a task is (the
  * command string — principle #3), only where and how that command is
- * executed. Registered explicitly in vx.workspace.ts via
+ * executed. Registered explicitly in .vx/workspace.ts via
  * defineWorkspace({ plugins: [...] }). No auto-discovery.
  *
  * Made by `definePlugin(import.meta, hooks)` only: the loader refuses a
@@ -59,24 +60,32 @@ export interface VxPlugin {
   config?(workspace: WorkspaceConfig, ctx: WorkspaceHookContext): void | Promise<void>
 
   /**
-   * Directories to make projects beyond the package manager's members, as
-   * `{ dir, name }` (`dir` absolute or relative to the workspace root): a
-   * runner's root tasks, a project no member glob lists. Runs once per
-   * discovery, before any project config loads; each plugin sees core's
-   * projects and the ones earlier plugins named. A named directory keeps
-   * a `package.json` of the same name, if it has one; a name or directory
-   * already taken otherwise, or one outside the root, is refused.
+   * Projects beyond the directories holding a vx.config, their names, and
+   * edges between projects, as `DiscoveredProject`s (each directory
+   * absolute or relative to the workspace root): a lockfile's importers,
+   * their package names and the dependencies it records; a runner's root
+   * tasks. Runs once per discovery, before any project config loads; each
+   * plugin sees the locked projects and the ones earlier plugins added,
+   * without their edges. A directory that is not a project becomes one
+   * (with no config; named by `name`, else its path). A project named by
+   * its path takes `name`; one its config names keeps that name, and a
+   * different name from an earlier plugin is refused, as is a directory
+   * outside the root. Two projects of one name are refused once the stage
+   * ends. `deps` and `reach` from every plugin union then; a target that is
+   * no project is refused.
    */
-  discover?(ctx: DiscoverContext): readonly NamedProject[] | Promise<readonly NamedProject[]>
+  discover?(
+    ctx: DiscoverContext,
+  ): readonly DiscoveredProject[] | Promise<readonly DiscoveredProject[]>
 
   /**
    * One project's validated config, right after it loaded and before the
    * graph is built. Add, remove or edit tasks. Runs for every loaded project
-   * on every run — a config's cached evaluation is the user's file, and the
-   * hook is applied on top of it live. A package with NO config file is
-   * loaded too, as `{ tasks: {} }`, so a plugin can give tasks to packages
-   * that never wrote one (`ctx.packageJson` carries their scripts); with no
-   * `project` plugin such a package is never visited.
+   * on every run — a locked config is the user's file, and the hook is
+   * applied on top of it live. A project with NO config file (a
+   * `discover` plugin added it) is loaded too, as `{ tasks: {} }`, so a
+   * plugin can give it tasks; with no `project` plugin such a project is
+   * never visited.
    */
   project?(config: ProjectConfig, ctx: ProjectHookContext): void | Promise<void>
 
@@ -105,22 +114,14 @@ export interface VxPlugin {
     | Promise<Readonly<Record<string, string>> | undefined>
 
   /**
-   * Workspace-root files this plugin keys on its own, taken OUT of the
-   * workspace fingerprint. Core folds every lockfile it knows into every
-   * task's key, so one `pnpm install` re-keys the whole workspace. A plugin
-   * that reads the lockfile and folds each project's own dependency
-   * closure through `key` claims the file here: core leaves it out of the
-   * fingerprint every key sees (the config-evaluation cache still keys on
-   * it — a config may import a dependency), and `--affected` asks
-   * `affected` which projects a change to it touches instead of selecting
-   * every project. A file has one claimant.
-   *
-   * A root file core does NOT fold is claimed the same way when the
-   * plugin's stages read it: `turbo()` shapes every task from
-   * `turbo.json`, so an edit to it re-keys tasks through their resolved
-   * configs while no project owns the path. Nothing is taken out;
-   * `--affected` asks `affected` (undefined: every project) and `vx watch`
-   * re-runs on an edit (item 961). A claim is a bare name at the root.
+   * Workspace-root files this plugin keys on: core folds no root file into
+   * any key, so a plugin that reads one (a lockfile it folds per project
+   * through `key`, `turbo.json` that shapes every task through its
+   * `project` stage) claims it here. `--affected` asks `affected` which
+   * projects a change to it touches (undefined: every project), `vx watch`
+   * re-runs on an edit (item 961), and a task that rewrites one during the
+   * run withholds every later save. A claim is a bare name at the root; a
+   * file has one claimant.
    */
   readonly fingerprint?: FingerprintClaim
 
@@ -167,14 +168,14 @@ export interface VxPlugin {
   // --- BEHAVIOR capabilities (change WHAT/HOW work runs — opt-in) -----------
 
   /**
-   * Contribute a cache layer. Returns a CacheLayer wrapping (or replacing)
-   * the local Cache, or undefined to decline. Consulted ONCE per prepareRun.
-   * Every contributed layer is kept and chained in declaration order,
-   * ahead of core's own `.vx/cache` handle at the tail: a lookup walks
-   * them until one hits, a save reaches each. A layer that WRAPS the local
-   * handle subsumes that tail, so it is not written twice.
+   * Contribute a remote cache: the wire (`has`, `get`, `put`, optional
+   * `hasMany`), or undefined to decline. Consulted ONCE per prepareRun.
+   * Core layers each one behind its own local cache and owns the rest:
+   * the local store is asked first, then each remote in declaration order;
+   * the run's policy and scope gate every remote; a remote's throw is a
+   * miss and a warning naming the plugin, never a failed run.
    */
-  cache?(ctx: CacheContext): CacheLayer | undefined | Promise<CacheLayer | undefined>
+  cache?(ctx: CacheContext): RemoteCacheLayer | undefined | Promise<RemoteCacheLayer | undefined>
 
   /**
    * Contribute a task executor — WHERE one task's command runs. Consulted
@@ -206,6 +207,16 @@ export interface VxPlugin {
     | undefined
     | Promise<TelemetrySink | TelemetrySink[] | undefined>
 
+  /**
+   * Take the terminal for this run: return the `Logger` that renders it
+   * (the contract `run({ log })` takes), or `undefined` to leave core's
+   * renderer in place. The first plugin, in declaration order, that
+   * returns one renders the run; the rest are not asked. Not consulted
+   * when an embedder passed its own `log`. A logger that throws hands the
+   * rest of the run back to core's renderer with one warning.
+   */
+  output?(ctx: OutputContext): Logger | undefined | Promise<Logger | undefined>
+
   /**
    * Optional one-time setup per run (validate the workspace, open a
    * connection, read a token). Throwing aborts the run with a clean
@@ -248,7 +259,7 @@ export interface PluginCommand {
 export interface CommandContext extends BaseContext {
   /**
    * The worker count a `vx run` here uses unless `--concurrency` says
-   * otherwise: `vx.workspace`'s `concurrency`, else what the machine allows.
+   * otherwise: `.vx/workspace`'s `concurrency`, else what the machine allows.
    * A verb that budgets a run (`vx history`) reads it here; its own
    * `machineParallelism()` said 4 cores beside `concurrency: 1` (item 1068).
    */
@@ -256,7 +267,7 @@ export interface CommandContext extends BaseContext {
   /**
    * The argv that runs this vx again: the binary alone when compiled, the
    * runtime and its entry script from source. A verb that runs tasks
-   * (`vx mcp`'s `runTasks`) spawns `[...vx, 'run', …]` rather than guess
+   * spawns `[...vx, 'run', …]` rather than guess
    * which `vx` a PATH holds.
    */
   readonly vx: readonly string[]
@@ -271,7 +282,7 @@ export interface WorkspaceHookContext {
 export interface DiscoverContext extends WorkspaceHookContext {
   /** Where vx's cache lives: a plugin may keep what it read to answer here. */
   readonly cacheDir: string
-  /** The projects found so far: core's, then earlier plugins'. */
+  /** The projects found so far: the lock's, then earlier plugins'. */
   readonly projects: readonly ProjectMeta[]
   /**
    * What `git status` lists in the workspace, workspace-relative: modified,
@@ -283,24 +294,33 @@ export interface DiscoverContext extends WorkspaceHookContext {
   worktreeChanges(): Promise<readonly string[] | null>
 }
 
-export interface NamedProject {
+/** What a `discover` hook returns per directory — see `VxPlugin.discover`. */
+export interface DiscoveredProject {
+  /** Absolute or relative to the workspace root. */
   readonly dir: string
-  readonly name: string
+  /**
+   * Its name, when its config names none: replaces a path name, never a
+   * config's; a different name from an earlier plugin is refused. Unset on
+   * a new directory: its root-relative path.
+   */
+  readonly name?: string
+  /** Directories this project builds after: `^task` order, and reach for `--filter` and `--affected`. */
+  readonly deps?: readonly string[]
+  /** Directories a change reaches this project through (`--filter`, `--affected`), with no order. */
+  readonly reach?: readonly string[]
 }
 
 export interface ProjectHookContext extends BaseContext {
-  /** The package name (`package.json#name`). */
+  /** The project's name (`ProjectMeta.name`). */
   readonly name: string
   /** The project's directory, absolute. */
   readonly dir: string
-  /** The parsed `package.json`, read-only. */
-  readonly packageJson: Readonly<Record<string, unknown>>
   /**
-   * Every package the workspace discovered — the one being visited, the
-   * rest of the run's scope and the packages outside it, config file or
-   * not — as core read them at startup. A plugin whose mapping needs the
-   * whole workspace (a `dependsOn` is only valid against every package's
-   * scripts at once) reads it here instead of walking the workspace a
+   * Every project the workspace discovered — the one being visited, the
+   * rest of the run's scope and the projects outside it, config file or
+   * not — as the `discover` stage left them. A plugin whose mapping needs
+   * the whole workspace (a `dependsOn` is only valid against every
+   * package's scripts at once) reads it here instead of walking the workspace a
    * second time. The same array is handed to every visit of a run and a
    * new one to the next run — a plugin instance outlives a run under `vx
    * watch`, so a per-run memo keys on this array's identity, never on the
@@ -320,16 +340,16 @@ export interface GraphHookContext extends BaseContext {
 
 export interface KeyHookContext extends BaseContext {}
 
-/** A plugin's claim on workspace fingerprint files — see `VxPlugin.fingerprint`. */
+/** A plugin's claim on workspace-root files — see `VxPlugin.fingerprint`. */
 export interface FingerprintClaim {
-  /** Bare names at the workspace root: a lockfile core folds (`pnpm-lock.yaml`) or a file the plugin reads (`turbo.json`). */
+  /** Bare names at the workspace root the plugin reads: a lockfile (`pnpm-lock.yaml`), a settings file, `turbo.json`. */
   readonly files: readonly string[]
   /**
-   * The projects (package names) a change to a claimed file affects. Called
+   * The projects (by name) a change to a claimed file affects. Called
    * by `--affected` with the file's bytes at the base ref and in the
    * working tree (`null` where it does not exist). Return `undefined` to
    * select every project — the answer a claimant gives when it cannot
-   * tell, and what core does for an unclaimed file.
+   * tell.
    */
   affected(
     change: FingerprintChange,
@@ -345,7 +365,7 @@ export interface FingerprintChange {
 }
 
 export interface FingerprintContext extends BaseContext {
-  /** Every project in the workspace: package name and absolute directory. */
+  /** Every project in the workspace: name and absolute directory. */
   readonly projects: ReadonlyArray<{ readonly name: string; readonly dir: string }>
 }
 
@@ -364,13 +384,27 @@ export interface AdmitContext {
 export interface ScheduleHookContext extends BaseContext {
   /** The run's local cache handle — its `dbHandle()` holds the run history a policy can learn from. */
   readonly localCache: Cache
+  /** The run's branch (`currentBranch`), the timings a forecast reads first: pass it to `LocalHistoryProvider`. */
+  readonly branch: string | null
 }
 
+/** A `cache` hook's context: the workspace and the run's scope, never the local store or the policy, which core owns. */
 export interface CacheContext extends BaseContext {
-  /** The local Cache handle the plugin may wrap (LayeredCache(local, remote)). */
-  readonly localCache: Cache
-  /** The run's cache policy (the 4 read/write axes). */
-  readonly policy: CachePolicy
+  /**
+   * The run's `cache.scope` (`'pr-123'`), `undefined` when none. Core already keys a scoped run's
+   * writes apart; a remote reads it to pick a credential or check a token's
+   * claims (an OIDC branch) for every call it makes.
+   */
+  readonly scope: string | undefined
+}
+
+export interface OutputContext extends BaseContext {
+  /** Core would write to a terminal: stdout (stderr under `json`) is a TTY. */
+  readonly isTTY: boolean
+  /** The run is on CI (`CI` set, or a provider core detects). */
+  readonly ci: boolean
+  /** `--format json`: stdout carries the machine-readable result. */
+  readonly json: boolean
 }
 
 export interface ExecutorContext extends BaseContext {