@vzn/vx 0.0.16 → 0.0.21

package/src/config.ts

@@ -14,23 +14,29 @@ export interface WorkspaceConfig {
    */
   timeout?: number
   /**
-   * Plugins registered for this workspace. Each plugin is an
-   * in-process subscriber on the run event bus, installed once per
-   * `vx run`. See `docs/design/extension-protocol-2026-06.md` §5.
+   * Plugins registered for this workspace, consulted in this order once
+   * per `vx run`: each fills any of the pipeline stages and capabilities
+   * below, and core's own executor and cache store sit at the tail of
+   * every list. See `docs/design/pipeline-2026-09.md`.
    */
   plugins?: readonly Plugin[]
-  /**
-   * Opt in to history-aware predictive scheduling. When `true` and
-   * `cache.db` has prior runs, the scheduler picks the next ready
-   * task by expected remaining critical-path duration (HistoryTable
-   * p50) instead of the static reverse-deps count.
-   */
-  predictive?: boolean
 }
 
 /**
- * Structural plugin shape — any subset of the run-level capabilities
- * (`backend`/`cache`/`telemetry`/`eventSink`) plus optional
+ * The runtime brand `definePlugin` stamps on a plugin: the name of the
+ * package it was defined in. The workspace loader accepts a plugin only
+ * when this is present and equals `name`, so a plugin's name is its
+ * package name and nothing else — no field to set, no override. A
+ * registry symbol on purpose: a plugin package imports its own copy of
+ * `@vzn/vx` beside a compiled binary's, and the two copies must stamp
+ * and check the same key.
+ */
+export const PLUGIN_PACKAGE: unique symbol = Symbol.for('vx.plugin.package')
+
+/**
+ * Structural plugin shape — any subset of the pipeline stages
+ * (`config`/`project`/`graph`/`key`/`schedule`), run-level capabilities
+ * (`cache`/`executor`/`telemetry`) and CLI `commands`, plus optional
  * `setup`/`teardown`. The fully-typed `VxPlugin` lives in
  * `src/orchestrator/plugin.ts` and is what users import; this is a
  * re-declaration with opaque function types so `config.ts` stays a leaf
@@ -38,15 +44,60 @@ export interface WorkspaceConfig {
  * before consulting capabilities.
  */
 export interface Plugin {
+  /** The package name — set by `definePlugin`, never by the plugin. */
   readonly name: string
-  backend?(ctx: unknown): unknown
+  config?(workspace: unknown, ctx: unknown): unknown
+  project?(config: unknown, ctx: unknown): unknown
+  graph?(nodes: unknown, ctx: unknown): unknown
+  key?(task: unknown, ctx: unknown): unknown
+  schedule?(nodes: unknown, ctx: unknown): unknown
+  admit?(task: unknown, ctx: unknown): unknown
+  readonly commands?: Readonly<Record<string, unknown>>
   cache?(ctx: unknown): unknown
+  executor?(ctx: unknown): unknown
   telemetry?(ctx: unknown): unknown
-  eventSink?(ctx: unknown): unknown
   setup?(ctx: unknown): void | Promise<void>
   teardown?(): void | Promise<void>
+  readonly fingerprint?: unknown
 }
 
+/**
+ * Every hook a plugin may fill, in pipeline order — THE list. The loader's
+ * "must be a function" and "at least one of" checks, the host's stage gate
+ * and `vx info`'s seam column all read it, so a stage added here is a stage
+ * everywhere: `admit` reached `vx info` a day late (2026-09-12) because
+ * that column kept its own copy, and the loader kept a third. The type
+ * pin below refuses a list that drifts from `Plugin`'s keys either way.
+ */
+export const PLUGIN_HOOKS = [
+  'config',
+  'project',
+  'graph',
+  'key',
+  'fingerprint',
+  'schedule',
+  'admit',
+  'executor',
+  'cache',
+  'telemetry',
+  'setup',
+  'commands',
+  'teardown',
+] as const
+export type PluginHook = (typeof PLUGIN_HOOKS)[number]
+/** The hooks that are functions; `commands` and `fingerprint` are objects. */
+export const PLUGIN_FUNCTION_HOOKS = PLUGIN_HOOKS.filter(
+  (h): h is Exclude<PluginHook, 'commands' | 'fingerprint'> =>
+    h !== 'commands' && h !== 'fingerprint',
+)
+type PluginHookKeys = Exclude<keyof Plugin, 'name'>
+type HooksNotListed = Exclude<PluginHookKeys, PluginHook>
+type HooksNotOnPlugin = Exclude<PluginHook, PluginHookKeys>
+// Both `never`, or this line does not compile: the list and the type agree.
+const _pluginHooksMatch: [HooksNotListed, HooksNotOnPlugin] extends [never, never] ? true : never =
+  true
+void _pluginHooksMatch
+
 export interface ProjectConfig {
   /** Tasks declared by this project, keyed by task name. */
   tasks?: Record<string, TaskConfig>
@@ -57,7 +108,13 @@ export interface TaskConfig {
    * Optional one-line description of what this task does. Surfaced in
    * the interactive task picker and the `--dry` text view so users
    * can grep for what each task does without opening every config.
-   * Pure metadata — no effect on caching, scheduling, or execution.
+   *
+   * No effect on scheduling or execution. It DOES participate in the
+   * cache key, because the key hashes the whole resolved task config
+   * (`docs/caching.md`, step 5) — deliberate: editing a description
+   * isn't a correctness change, but a one-off re-run costs little and
+   * carving exceptions out of the resolved object is what invites
+   * stale hits.
    */
   description?: string
   /**
@@ -89,128 +146,120 @@ export interface TaskConfig {
    * runs.
    */
   cache?: CacheConfig
-  /**
-   * Sandbox configuration. **Sandbox is opt-in per task.**
-   *   - omitted entirely → task runs unsandboxed.
-   *   - `sandbox: {}`    → opts in with the minimum baseline (only
-   *     resolved inputs readable, only static-prefix of outputs
-   *     writable, network blocked).
-   *   - `sandbox: { ... }` → opts in with the explicit options below.
-   *
-   * No inheritance, no workspace defaults, no built-in escapes. The
-   * sandbox sees STRICTLY the union of resolved `cache.inputs.files`
-   * + this block's `allowRead` (for reads) and the static prefix of
-   * `cache.outputs.files` + this block's `allowWrite` (for writes).
-   * If a task needs `node_modules` or `/tmp`, declare them here
-   * explicitly.
-   *
-   * **Policy: fail on violation.** If the sandbox detects an
-   * undeclared read/write (macOS log monitor) or the child returns
-   * non-zero because it couldn't reach a path it expected (Linux
-   * structural deny), the task fails. No cache is written for a
-   * failed task.
-   *
-   * Activation requires `exec` (group tasks have no command to wrap)
-   * and is silently skipped for persistent tasks (dev servers need
-   * unrestricted network + an indefinite process).
-   */
-  sandbox?: SandboxConfig
 }
 
 /**
- * Per-task sandbox config. Mirrors the user-facing surface of
- * `@anthropic-ai/sandbox-runtime`'s `SandboxRuntimeConfig`, minus
- * deployment-only fields (binary paths, proxy ports, ripgrep config).
+ * What a sandboxed task may do, declared as CAPABILITIES.
+ *
+ * One shape for the whole policy. You say what the task is allowed to
+ * touch; vx decides how each capability is realised — some become sandbox
+ * runtime config, some become rules in the OS policy, and one the platform
+ * cannot express is an error rather than a silent no-op. None of that
+ * reaches the config.
  *
- * Path-list fields (`allowRead`, `allowWrite`, `network.allowUnixSockets`)
- * accept:
- *   - relative paths     → resolved against the project dir
- *   - absolute paths     → used as-is (`/etc/passwd`, `/tmp`)
- *   - tilde paths        → expanded against the user's home (`~/.npmrc`)
+ * The baseline is always the task's own declarations: it may read its
+ * resolved `cache.inputs.files`, write the prefixes of its
+ * `cache.outputs.files`, and reach nothing else. Everything here is on top
+ * of that.
  *
- * No globs in path lists — bwrap on Linux only accepts path prefixes.
+ * Paths are project-relative, absolute, or `~`-expanded — and are path
+ * PREFIXES, never globs (a glob cannot be enforced by a mount).
  */
 export interface SandboxConfig {
-  // === Filesystem ===
-  /**
-   * Additional read-allowed paths beyond resolved `cache.inputs.files`.
-   * These are unioned with the declared inputs to form the complete
-   * allowRead set passed to the sandbox.
-   */
-  allowRead?: string[]
-  /**
-   * Additional write-allowed paths beyond the static prefix of
-   * `cache.outputs.files`. Tasks with no declared outputs and no extra
-   * `allowWrite` can write to nowhere — typical for `lint`/`typecheck`.
-   */
-  allowWrite?: string[]
-  /**
-   * Permit writes to `.git/config` files. Default `false` — most build
-   * tools should not be reconfiguring git.
-   */
-  allowGitConfig?: boolean
-
-  // === Network ===
-  /**
-   * Network policy.
-   *   - `false` (default) — block all outbound traffic.
-   *   - `true`            — allow all outbound traffic.
-   *   - object            — fine-grained control (domains / sockets / etc.).
-   */
-  network?: boolean | SandboxNetworkConfig
-
-  // === Process behavior ===
+  /** Capabilities granted on top of the task's own declarations. */
+  allow?: SandboxGrants
   /**
-   * Allow the task to acquire a pseudo-terminal. Default `false`.
-   * Needed by tasks that interact with a TTY (rare in CI).
+   * Capabilities taken away. Evaluated before `allow`, so a domain in both
+   * is denied.
    */
-  allowPty?: boolean
+  deny?: SandboxDenials
   /**
-   * Linux only. Allow nested sandboxes (a sandboxed task spawning
-   * another sandboxed task). Default `false`.
+   * Denials to leave out of the report, in the same shape as `allow`.
+   *
+   * This does NOT permit anything: the OS still denies the operation, and
+   * a command that cannot proceed without it still fails. It says "I know,
+   * and it does not affect this task's output" — for a denial you cannot
+   * grant away and do not want failing the run.
+   *
+   * Unlike `allow`, the values are GLOB PATTERNS, and they work the same
+   * on every platform: `allow` has to be expressible by the OS sandbox
+   * (bwrap mounts a path; it cannot mount a pattern), while `ignore` only
+   * has to match a line vx already holds. Relative patterns anchor at the
+   * project dir.
+   *
+   * ```ts
+   * ignore: { write: ['*.bun-build'] }   // bun --compile stages a random
+   *                                      // temp name in the cwd
+   * ```
    */
-  enableWeakerNestedSandbox?: boolean
+  ignore?: SandboxGrants
   /**
-   * macOS only. Skip the network namespace; routes traffic via the
-   * host proxy instead of unsharing networking. Lower overhead but
-   * weaker isolation. Default `false`.
+   * Accept a weaker sandbox when vx itself already runs inside one
+   * (a container, another sandbox). Without it, nesting fails fast rather
+   * than pretending to confine.
    */
-  enableWeakerNetworkIsolation?: boolean
+  weakerWhenNested?: boolean
+  /** Accept weaker network isolation (host proxy) for lower overhead. */
+  weakerNetworkIsolation?: boolean
+}
 
-  // === Violation policy ===
-  /**
-   * Map of command-substring → list of paths to ignore violations on
-   * for that command. Lets you silence known-noisy probes (e.g. a
-   * compiler that statx's many candidate header paths). Per SRT's
-   * own ignoreViolations field.
-   */
-  ignoreViolations?: Record<string, string[]>
+export interface SandboxGrants {
+  /** Readable path prefixes, beyond the resolved `cache.inputs.files`. */
+  read?: string[]
+  /** Writable path prefixes, beyond the `cache.outputs.files` prefixes. */
+  write?: string[]
+  /**
+   * Reachable domains. `true` allows all, `['*.example.com']` a pattern.
+   * Omitted means no network at all.
+   */
+  network?: true | string[]
+  /**
+   * Kernel information the task may query, by info type — the name that
+   * appears in a denial, e.g. `vfs.disk-space` (every Bun and git process
+   * probes free space at startup).
+   */
+  systemInfo?: string[]
+  /** Unix socket paths the task may connect to. `true` allows any. */
+  unixSockets?: true | string[]
+  /**
+   * Bind and reach localhost ports — a test that boots a server for
+   * itself. A port LIST additionally makes those ports reachable from
+   * outside the sandbox (a dev server another task or the developer
+   * talks to): on Linux, where a sandboxed task lives in its own network
+   * namespace, each listed port is bridged out to the host's loopback;
+   * on macOS the host already sees them and the list means `true`.
+   */
+  localBinding?: boolean | number[]
+  /** macOS: Mach service names the task may look up. */
+  machLookup?: string[]
+  /** Acquire a TTY. Rare outside interactive tools. */
+  pty?: boolean
+  /** Write to `.git/config`. Most build tools should not. */
+  gitConfig?: boolean
 }
 
-export interface SandboxNetworkConfig {
-  /**
-   * Domain patterns the task may reach. Wildcards: `*.example.com`,
-   * `*` (allow all).
-   */
-  allowedDomains?: string[]
-  /** Domains explicitly blocked, evaluated before allowedDomains. */
-  deniedDomains?: string[]
-  /** Unix socket paths the task may connect to. */
-  allowUnixSockets?: string[]
-  /** Allow any Unix socket. Use with care. */
-  allowAllUnixSockets?: boolean
-  /**
-   * Allow binding to local ports (e.g. a test that boots a server on
-   * localhost for itself to query).
-   */
-  allowLocalBinding?: boolean
-  /** macOS only. Mach service names the task may look up. */
-  allowMachLookup?: string[]
+export interface SandboxDenials {
+  /** Domains blocked even if `allow.network` would admit them. */
+  network?: string[]
 }
 
 export interface ExecConfig {
   /** Shell command to run, from the project's directory. */
   command: string
+  /**
+   * `false` pins the task to this machine: it is never offered to a remote
+   * executor (it talks to a local daemon, the network, Docker, …). Default
+   * `true`. Tasks that are persistent, or depend on one, are pinned
+   * regardless — a worker cannot reach a port on the submitter.
+   *
+   * `'only'` is the inverse pin: the task exists to produce a REMOTE input
+   * tree (the canonical case is `pnpm install` feeding remote workers) and is
+   * a NO-OP on this machine — never executed locally, its declared outputs
+   * never cleaned or restored on this disk. With no remote executor declared
+   * the task succeeds without running and dependents use whatever ambient
+   * state the machine has, exactly as they did before the field existed.
+   */
+  remote?: boolean | 'only'
   /** Environment exposed to the child process. */
   env?: ExecEnv
   /**
@@ -239,16 +288,6 @@ export interface ExecConfig {
    * default, including `retries: 0`.
    */
   retries?: number
-  /**
-   * Resource RESERVATIONS for admission control — NOT enforcement: vx
-   * does not cgroup-limit, nice, or kill the task; it only decides what
-   * to co-schedule so concurrent reservations never exceed the CPU /
-   * memory budget. Each axis defaults to 0 = reserve nothing: the task
-   * runs subject only to the concurrency-count limit. A pure scheduling
-   * hint — the whole object is stripped from the cache key, so tuning a
-   * reservation never invalidates a cached result.
-   */
-  resources?: ResourcesConfig
   /**
    * Long-running / continuous task (dev server, watcher, daemon).
    * When present, the task is spawned but the runner does NOT wait
@@ -258,32 +297,29 @@ export interface ExecConfig {
    * on ready, not on exit. The orchestrator SIGTERMs every persistent
    * subprocess once the rest of the graph has finished.
    *
-   * `cache` is silently ignored for persistent tasks — there's no
-   * exit code to cache and the work continues after vx's run notion
-   * of "done".
+   * `cache` is rejected on a persistent task — there's no exit code
+   * to cache and the work continues after vx's run notion of "done".
    */
   persistent?: PersistentConfig
-}
-
-/**
- * Per-task resource reservation (see `ExecConfig.resources`). Grouped so
- * a future axis slots in without new top-level `exec` fields; the loader
- * rejects unknown keys.
- */
-export interface ResourcesConfig {
   /**
-   * CPU units (fractional ok, e.g. `0.5`), or a `"<n>%"` string of the
-   * CPU budget (the run's `concurrency`). `cpus: "50%"` on a budget of 8
-   * reserves 4 units.
-   */
-  cpus?: number | string
-  /**
-   * Bytes, a size string (`"2GB"`, `"512MB"` — K/M/G/T, powers of 1024),
-   * or a `"<n>%"` string of the memory budget (`os.totalmem()` unless
-   * overridden with `--memory` — pass `--memory` in cgroup-limited
-   * containers, where `os.totalmem()` reports the HOST's RAM).
+   * Confine this task's process: what it may read, write and reach.
+   * Nothing is confined unless this is present.
+   *
+   * It sits in `exec` because it constrains the same spawn `env` and
+   * `resources` do — the environment the child gets, the CPU and memory it
+   * gets, the filesystem and network it gets. A group task has no process,
+   * so the field cannot be reached from one.
+   *
+   * **Policy: fail on violation.** An undeclared touch of the project's own
+   * files fails the task, and a failed task is never cached. Reaching
+   * OUTSIDE the project is denied but not reported — that is the wall
+   * doing its job, not a finding.
+   *
+   * A persistent task is confined the same way but never REPORTED on: the
+   * violation report reads the trace after the process exits, and a server
+   * exits at teardown. Enforced, not reported.
    */
-  memory?: number | string
+  sandbox?: SandboxConfig
 }
 
 export interface PersistentConfig {
@@ -337,8 +373,9 @@ export interface CacheOutputs {
    * files anywhere in the workspace, including inside other projects'
    * directories. Deliberate escape hatch — prefer project-relative
    * `files` whenever the task can write inside its own dir. Two tasks
-   * declaring overlapping workspace outputs is user responsibility;
-   * vx does not police it.
+   * whose workspace outputs provably overlap are refused at graph build,
+   * like overlapping `files` (vx cleans declared outputs before a run
+   * and before a restore, so the second would delete the first's).
    */
   workspaceFiles?: string[]
 }

package/src/exec/env.ts

@@ -8,7 +8,13 @@ import path from 'node:path'
 //   3. define: explicit name=value pairs from the task config.
 //   4. binPaths prepended to PATH (after all the above resolve PATH).
 
-const ESSENTIAL_ENV: readonly string[] = [
+/**
+ * Exported so the schema doc's enumeration of it can be PINNED against the
+ * real list: a hand-copied allowlist is how the two drift, and a reader
+ * asking "what does my build script actually see?" is asking a
+ * security-shaped question that a stale list answers wrongly.
+ */
+export const ESSENTIAL_ENV: readonly string[] = [
   'PATH',
   'HOME',
   'SHELL',
@@ -36,6 +42,17 @@ const ESSENTIAL_ENV: readonly string[] = [
   'PATHEXT',
 ]
 
+/**
+ * The two variables vx sets on every task it spawns, over the layers
+ * above: the workspace root the run is in and the `project#task` running.
+ * `run()` reads them back so a task that shells out to `vx run` in its OWN
+ * workspace is refused before it forks without bound (a different
+ * workspace — a fixture, a benchmark — is fine). Not in the allowlist:
+ * they come from this run, never from the parent environment.
+ */
+export const VX_RUN_WORKSPACE_ENV = 'VX_RUN_WORKSPACE'
+export const VX_RUN_TASK_ENV = 'VX_RUN_TASK'
+
 export interface BuildEnvOptions {
   passThrough: readonly string[]
   define: Readonly<Record<string, string>>