@vzn/vx 0.0.18 → 0.0.21

package/src/index.ts

@@ -3,20 +3,33 @@
 // This is the stable cross-package contract — any plugin or integration
 // package imports everything it needs from here via the bare
 // `'@vzn/vx'` specifier (never a deep `src/...` path). The surface is pinned
-// by tests/package-boundaries.test.ts; a widening updates that snapshot
-// deliberately. See docs/design/core-cloud-split-2026-06.md §3.5.
+// by tests/package-boundaries.unsafe.test.ts; a widening updates that snapshot
+// deliberately. The boundary law: docs/architecture.md § Repository shape.
 
 export { VERSION } from './version.js'
 
 // Clean error type — user-input failures print a message without a stack.
-// `clampInt` and `parseDecimalInt` ride along for the same reason the status
-// predicates do: without them on the façade an integration package writes its
-// own, and both had already happened. A bounds helper whose floor is
-// load-bearing (a fractional SQL LIMIT is a datatype mismatch, not a smaller
-// page) should have one implementation — and so should the ONE strict integer
-// parser, whose entire purpose is that `Number()` silently accepts `0x10` and
-// `1e3` at a boundary where a typo must be an error, not a different number.
-export { clampInt, parseDecimalInt, parseSize, UserError, isUserError } from './util/index.js'
+// `clampInt` rides along for the same reason the status predicates do:
+// without it on the façade an integration package writes its own, and that
+// had already happened. A bounds helper whose floor is load-bearing (a
+// fractional SQL LIMIT is a datatype mismatch, not a smaller page) should
+// have one implementation.
+export { clampInt, UserError, isUserError } from './util/index.js'
+// "Did you mean": the hint core's own verbs give for a near-miss name, for a
+// plugin verb to give the same one.
+export { nearMatches } from './util/index.js'
+// Every hook a plugin may fill, in pipeline order — the one list the
+// loader, the host and `vx info` read; exported so a doc pin outside core
+// (the site's guides) holds its tables to the same list.
+export { PLUGIN_HOOKS, type PluginHook } from './config.js'
+// The workspace doctor's facts (`vx info`), for a host that answers the
+// same question over another surface — `@vzn/vx-mcp`'s `getWorkspaceInfo`.
+export { collectInfo, type CollectInfoOptions, type InfoFacts } from './orchestrator/index.js'
+// The machine as this process may use it — cores and memory capped by the
+// cgroup a container runs under. Core's default worker count reads the
+// first; a policy that budgets memory (`@vzn/vx-schedule-history`) reads
+// the second, so the cgroup walk has one implementation.
+export { machineMemoryBytes, machineParallelism } from './util/index.js'
 
 // Schema types and helpers (used by user vx.config files and presets).
 export type {
@@ -28,36 +41,26 @@ export type {
   CacheConfig,
   CacheInputs,
   CacheOutputs,
-  ResourcesConfig,
   SandboxConfig,
-  SandboxNetworkConfig,
+  SandboxGrants,
+  SandboxDenials,
 } from './config.js'
 export { defineProject, defineWorkspace } from './config.js'
+export { definePlugin } from './orchestrator/index.js'
 
-// Programmatic engine API (run / plan / prepare) + the graph primitives a
-// distribution submitter/agent reasons over + the cache-key hashing seam.
-// `deriveStableKeys` is THE shared stable-key derivation (remote-prefetch,
-// the local short-circuit, and the distributed submitter must never drift
-// on the stability gate); `captureGitContext`/`captureWorkspaceIdentity`
-// give agents + the submitter identity before/without a telemetry run.
+// Programmatic engine API: run / plan / prepare (docs/cli.md § Programmatic
+// API). The graph primitives, the cache-key hashing seam and the git / host
+// context capture used to sit beside these for a distributed submitter that
+// left the repo (2026-08); they went with it (2026-09-10) — a seam with no
+// consumer is re-added when one appears, shaped by its use.
 export { run, planRun, prepareRun } from './orchestrator/index.js'
-// The per-task duration history a `schedule` plugin learns from (see
-// src/plugins/schedule-history — core's own plugins import core only via
-// this façade, which is what put these here).
-export { EmptyHistoryProvider, LocalHistoryProvider } from './orchestrator/index.js'
+// The per-task duration history a `schedule` plugin learns from
+// (`@vzn/vx-schedule-history` does; a plugin package reaches core only
+// through this façade, which is what put these here).
+export { LocalHistoryProvider } from './orchestrator/index.js'
 export type { HistoryProvider, HistoryTable, TaskHistory } from './orchestrator/index.js'
 export type { PreparedRun } from './orchestrator/index.js'
-export { computeTaskHash, createHashCache, deriveStableKeys } from './orchestrator/index.js'
-export type { DeriveStableKeysArgs, HashCache, StableKey } from './orchestrator/index.js'
-export {
-  captureDefaultBranch,
-  captureGitContext,
-  captureHostContext,
-  captureWorkspaceIdentity,
-  detectCi,
-} from './orchestrator/index.js'
 export type { CiContext, GitContext, HostContext, WorkspaceIdentity } from './orchestrator/index.js'
-export { FULL_CACHE_POLICY, parseCachePolicy } from './orchestrator/index.js'
 export type {
   CachePolicy,
   Logger,
@@ -65,84 +68,95 @@ export type {
   RunOptions,
   RunSummary,
 } from './orchestrator/index.js'
-export { defaultLogger, resolveOutputView } from './orchestrator/index.js'
 // `splitTaskId` is on the façade because the alternative is what happened:
 // with only `taskId()` to JOIN an id and nothing exported to SPLIT one,
 // consumers roll their own `split('#', 2)` and drift from the graph, which
 // splits on the FIRST '#'.
-export {
-  buildTaskGraph,
-  expandRequested,
-  isGroupTask,
-  markSurfacedDeps,
-  splitTaskId,
-} from './graph/index.js'
-export type {
-  OutputFingerprint,
-  TaskNode,
-  TaskOutcome,
-  TaskStatus,
-  VerifyVerdict,
-} from './graph/index.js'
-// The one output-tree diff implementation (verify verdicts + a serve's
-// cross-machine fingerprint diff both name rels through it).
-export { diffOutputTrees } from './orchestrator/index.js'
+export { splitTaskId } from './graph/index.js'
+export type { TaskNode, TaskOutcome, TaskStatus } from './graph/index.js'
 
-// Cache classes + the layer interface (the `cache` capability's currency)
-// and input-output resolution. The blob-CAS/digest substrate
-// (cas-backend.ts / digest.ts) stays module-internal until it has a
-// consumer — no speculative public API. `cleanOutputs` is public for the
-// distributed submitter's targeted output materialization (wipe declared
-// outputs, then `restoreOutputs` the artifact — never a naive re-run).
-export {
-  Cache,
-  LayeredCache,
-  GitFilesCache,
-  cleanOutputs,
-  resolveInputs,
-  resolveOutputs,
-} from './cache/index.js'
+// Cache classes + the layer interface (the `cache` capability's currency).
+export { Cache, LayeredCache } from './cache/index.js'
 export type { CacheLayer, RemoteCacheLayer, RunRecord, InvocationRecord } from './cache/index.js'
 
 // Workspace discovery + the project/config catalog surface — an
-// out-of-process service/CLI needs these. `readLockfile` is THE one reader
-// of vx-lock.json (the format carries its own version sentinel; a second
-// parser in a sibling package would drift), and the loader chain
-// (`loadWorkspace` → `listProjectMetas` → `loadProjectConfig`) is the same
-// one `vx show` uses. Workspace's `listProjects` re-exports as
-// `listProjectMetas` (the bare name once belonged to a metrics query).
-export { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from './workspace/index.js'
-export { readLockfile, LOCKFILE_NAME } from './workspace/index.js'
-export type { Lockfile, LockfileEntry } from './workspace/index.js'
+// out-of-process service/CLI needs these. `loadProjectConfig` is the RAW
+// per-file load (`vx lock` freezes exactly that); the resolved view a run
+// or `vx show` sees — plugin stages applied — is `loadResolvedProjects`
+// below. Workspace's `listProjects` re-exports as `listProjectMetas` (the
+// bare name once belonged to a metrics query).
+export { findWorkspaceRoot } from './workspace/index.js'
 export {
   loadWorkspace,
   loadProjectConfig,
   listProjects as listProjectMetas,
 } from './workspace/index.js'
 export type { ProjectMeta } from './workspace/index.js'
+// The package graph as a run sees it (workspace deps by manifest), for a tool
+// that needs a project's transitive closure the way `vx run` computes it.
+export { buildPackageGraph } from './workspace/index.js'
+// The run path's RESOLVED view — plugin `config` and `project` stages
+// applied, cached evaluations served — for a reader outside the CLI (the
+// MCP server's `listTasks`, an embedder's task catalog). What `vx show`
+// prints.
+export { loadResolvedProjects } from './orchestrator/index.js'
+export type { ProjectEntry } from './workspace/index.js'
+// The migration seam: how a generated config is planned, rendered, guarded
+// and written. `vx init` (package.json scripts) uses it in core;
+// `@vzn/vx-migrate` (Turbo, Nx) and any other adoption tool use it from here.
+export {
+  applyMigration,
+  PERSISTENT_TASK_NAMES,
+  PERSISTENT_TODO,
+  quoteTsLiteral,
+} from './workspace/index.js'
+export type {
+  ApplyMigrationArgs,
+  MigrationFormat,
+  GeneratedProject,
+  GeneratedTask,
+  MigrationPlan,
+  RawExpr,
+} from './workspace/index.js'
 
 // Plugin API — the run-level extension points. Behavior capabilities
 // (executor / cache) change WHAT/HOW work runs; the observe-only `telemetry`
 // capability is the canonical data-export path and cannot change behavior.
 // A plugin is declared in vx.workspace.ts via defineWorkspace({ plugins }).
 // See docs/design/observability-architecture-2026-06.md.
+// The claimant's shell for a lockfile plugin (`@vzn/vx-lockfile`):
+// the claim, the per-project key, the memo and the `--affected` diff around
+// a parser; `reachDigests` is the Merkle-over-components digest both use.
+export {
+  lockfileClaim,
+  reachDigests,
+  type LockfileClaimHooks,
+  type LockfileClaimOptions,
+  type ReachGraph,
+} from './orchestrator/index.js'
 export type {
   VxPlugin,
+  PluginHooks,
+  PluginOrigin,
   CacheContext,
   ExecutorContext,
   CommandContext,
+  FingerprintChange,
+  FingerprintClaim,
+  FingerprintContext,
   GraphHookContext,
   KeyHookContext,
   PluginCommand,
   ProjectHookContext,
   ScheduleHookContext,
+  AdmitContext,
   WorkspaceHookContext,
   PluginSetupContext,
 } from './orchestrator/index.js'
-// Process primitives — what an executor plugin builds on. `@vzn/vx/plugins/local-executor`
-// is the reference implementation and imports exactly these.
-export { runCommand, runSandboxed } from './exec/index.js'
 // The per-task execution contract a plugin's `executor` capability returns.
+// (`runCommand` / `runSandboxed`, the local executor's own primitives, left
+// the façade 2026-09-10: no executor plugin built on them — `@vzn/vx-reapi`
+// speaks a wire — and a seam with no consumer is a special case in waiting.)
 export type {
   ExecuteRequest,
   ExecuteResult,
@@ -166,7 +180,6 @@ export type {
 // plugin that renders a run as a markdown table takes the same unvalidated
 // task names core does, and the cloud job summary shipped without the escape.
 export {
-  assembleRunSummary,
   escapeMarkdownCell,
   TELEMETRY_SCHEMA_VERSION,
   deriveCacheSource,
@@ -192,29 +205,11 @@ export type {
   TelemetrySink,
 } from './orchestrator/index.js'
 
-// The serializable event projection.
-export { projectNode, projectOutcome } from './orchestrator/index.js'
-export type { RunResult } from './orchestrator/index.js'
-
-// Event bus + wire form — adapters (otel-bridge, custom subscribers) ride this.
-export { createEventBus, wireForwarder, toWireEvent } from './orchestrator/index.js'
-export type {
-  EventBus,
-  RunEvent,
-  RunEventSubscriber,
-  WireEvent,
-  TaskView,
-  OutcomeView,
-} from './orchestrator/index.js'
+// The serializable run result and its per-task views (what `run()` returns).
+export type { RunResult, TaskView, OutcomeView } from './orchestrator/index.js'
 
-// Run-history queries over cache.db — what `vx why` / `vx last` read. An
-// out-of-process surface (an MCP server, a dashboard plugin) reads the same.
-export {
-  cacheKeyDiff,
-  explainCacheKeyQuery,
-  getInvocation,
-  getRun,
-  listInvocations,
-  listRuns,
-  whyDidThisRerunQuery,
-} from './orchestrator/index.js'
+// The one run-history query a reader outside the CLI takes today: `vx why`'s
+// answer, which `@vzn/vx-mcp` serves. The event bus / wire form and the
+// other history readers (`listRuns`, `getRun`, …) left the façade 2026-09-10
+// with no consumer; the telemetry seam above is the canonical export path.
+export { whyDidThisRerunQuery } from './orchestrator/index.js'

package/src/orchestrator/admission.ts

@@ -0,0 +1,137 @@
+// What stands between the scheduler's `execute` callback and executeTask:
+// two rules that decide whether a ready task runs NOW and whether its
+// result may be SAVED. Neither changes what the task is.
+//
+// - In-flight dedup: an embedder running concurrent delegated runs in one
+//   process (a daemon built on the façade; core ships none) supplies an
+//   `inflight` registry; a task whose key
+//   a sibling is already computing waits for it and cache-hits on what it
+//   saved. A stateless `vx run` passes none and takes the untouched path.
+// - Continue-taint: under `continueMode: 'always'` a task runs although an
+//   upstream failed. Its key is the healthy one (pure-input hashing) but
+//   its bytes are not, so the taint is tracked here and propagates through
+//   every success built on it — or a grand-dependent would cache the same
+//   partial tree one hop later. Only that mode ever executes a task behind
+//   a failure; the other modes skip it, so a default run carries no check.
+//
+// Split from `run.ts` on 2026-09-10 (pure motion).
+
+import type { CachePolicy } from '../cache/index.js'
+import { isGroupTask, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import { executeTask, type ExecuteArgs } from './execute-task.js'
+import type { ShortCircuit } from './local-shortcircuit.js'
+import { computeTaskHash, type ComputeHashArgs } from './task-hash.js'
+
+/**
+ * Records which tasks ran behind a failure and answers, per task, whether
+ * this one does. Disabled (always `false`, nothing recorded) unless the
+ * run's `continueMode` is `'always'`.
+ */
+export function taintTracker(
+  enabled: boolean,
+): (node: TaskNode, upstream: TaskOutcome[]) => boolean {
+  if (!enabled) return () => false
+  const tainted = new Set<string>()
+  return (node, upstream) => {
+    const taint = upstream.some(
+      // A restore-tier task may run before its deps and see holes here;
+      // it never saves anyway (a hit restores), so a hole is not taint.
+      (u) =>
+        u !== undefined &&
+        (u.status === 'failed' ||
+          u.status === 'aborted' ||
+          u.status === 'skipped' ||
+          tainted.has(u.node.id)),
+    )
+    if (taint) tainted.add(node.id)
+    return taint
+  }
+}
+
+export interface AdmissionArgs {
+  /** The shared registry, or undefined for a stateless run (no dedup). */
+  inflight: Map<string, Promise<void>> | undefined
+  policy: CachePolicy
+  shortCircuit: ShortCircuit
+  /** Everything `computeTaskHash` needs besides the node and its upstream. */
+  hashArgs: Omit<ComputeHashArgs, 'node' | 'upstream' | 'nestedProjectDirs'> & {
+    nestedDirsByProject: ReadonlyMap<string, string[]>
+  }
+  /**
+   * The run's execute-args builder. `reuseProbe: false` drops the up-front
+   * probe: a task joining a sibling must let executeTask probe fresh,
+   * because the probe predates the sibling's save.
+   */
+  buildExecuteArgs: (node: TaskNode, upstream: TaskOutcome[], reuseProbe?: boolean) => ExecuteArgs
+}
+
+/** The scheduler's `execute` callback: dedup when it can help, else executeTask. */
+export function admitTasks(
+  args: AdmissionArgs,
+): (node: TaskNode, upstream: TaskOutcome[]) => Promise<TaskOutcome> {
+  const { inflight, policy, shortCircuit, hashArgs, buildExecuteArgs } = args
+  return async (node, upstream) => {
+    // Dedup only helps when the sibling will WRITE the artifact and this
+    // task can READ it back — i.e. both axes effectively on.
+    const canRead = policy.localRead || policy.remoteRead
+    const canWrite = policy.localWrite || policy.remoteWrite
+    const cacheable =
+      !isGroupTask(node) &&
+      node.config.exec?.persistent === undefined &&
+      node.config.cache !== undefined &&
+      canRead &&
+      canWrite
+    // A restore-tier task (confirmed local hit, may run before its deps)
+    // needs no dedup — it's a restore, not an executor, and its live
+    // `upstream` is incomplete, so the dedup hash recompute would be
+    // wrong. Route it straight to executeTask, which reuses the up-front
+    // probe.
+    const restorable = shortCircuit.restoreTier.has(node.id)
+    if (inflight === undefined || !cacheable || restorable) {
+      return executeTask(buildExecuteArgs(node, upstream))
+    }
+    const { nestedDirsByProject, ...rest } = hashArgs
+    const hash = await computeTaskHash({
+      ...rest,
+      node,
+      upstream,
+      nestedProjectDirs: nestedDirsByProject.get(node.projectName) ?? [],
+    })
+    const existing = inflight.get(hash)
+    if (existing !== undefined) {
+      // Join a sibling already computing this exact task: wait, then
+      // executeTask cache-hits on the artifact it just saved.
+      await existing.catch(() => {})
+      return executeTask(buildExecuteArgs(node, upstream, false))
+    }
+    // Become the executor: register a barrier siblings await. get→set has
+    // no await between, so registration is atomic — at most one executor
+    // per hash. Released on every exit (success / failure / throw).
+    let release!: () => void
+    inflight.set(
+      hash,
+      new Promise<void>((resolve) => {
+        release = resolve
+      }),
+    )
+    const execArgs = buildExecuteArgs(node, upstream)
+    try {
+      // `return await`, deliberately: the finally must run after the task
+      // settles, not when its promise is handed back.
+      return await executeTask(execArgs)
+    } finally {
+      // The barrier lifts when the ENTRY is there, not when the task is:
+      // the save runs off the slot (save-lane.ts), and a sibling released
+      // before it landed would probe a miss and run the task again. The
+      // executor's own return is not held — only the joiners wait.
+      const landed = execArgs.deferredSaves?.get(node.id)
+      const lift = (): void => {
+        execArgs.deferredSaves?.delete(node.id)
+        inflight.delete(hash)
+        release()
+      }
+      if (landed !== undefined) void landed.then(lift, lift)
+      else lift()
+    }
+  }
+}

package/src/orchestrator/deferred-outputs.ts

@@ -101,6 +101,9 @@ export class DeferredOutputs {
   private async run(taskId: string): Promise<void> {
     const entry = this.entries.get(taskId)!
     const producer = this.args.nodes.get(taskId)!
+    // Project outputs only: a task declaring `outputs.workspaceFiles` is
+    // never deferred (`deferralEligibility` forces it eager), so nothing
+    // workspace-anchored can reach this path.
     const outputs = producer.config.cache?.outputs.files ?? []
     const nestedProjectDirs = this.args.nestedDirsByProject.get(producer.projectName) ?? []
     const cleanArgs = { projectDir: producer.projectDir, outputs, nestedProjectDirs }