Module reference

One markdown per module under src/; a slice or helper is documented with the module that owns it (the cache slices in cache.md, the sandbox helpers in sandbox-runtime.md), and the CLI verb parsers in docs/cli.md. Each documents:

• Purpose — what the module exists to do.
• Public surface — exported types + functions consumed by other modules. The seam for forks / replacements.
• Algorithm / construction rules — how it works at a high level.
• What it does NOT do — explicit non-features (helps prevent scope creep on future PRs).
• Tests — where coverage lives.
• Replacing this module — what to swap to extend or fork.

Internal helpers are not part of the contract; they can change.

For the high-level data flow, read ../architecture.md first.

Root files

File	Topic
bin.md	src/bin.ts — shebang entry; wires process.argv to cli run.
config.md	src/config.ts — public schema types + defineProject helpers.
index.md	src/index.ts — public package façade (re-exports only).
version.md	src/version.ts — the VERSION constant (cycle-free leaf).

CLI

File	Topic
cli.md	src/cli/index.ts — module contract: dispatcher + re-exports for tests.
	src/cli/workspace-config.ts — the workspace as every verb sees it: config stage applied, cache dir, staged projects (see cli.md).
cli-run.md	src/cli/run.ts — the vx run parser and verb; src/cli/select.ts — scope, affected owners, picker.
cli-watch.md	src/cli/watch.ts — vx watch <task>: re-run on FS change; src/cli/watch-fs.ts — the OS watcher, its poller fallback, the mtime clock. src/cli/watch-filter.ts — which events matter; src/cli/watch-set.ts — what is watched; src/cli/watch-judge.ts — which settled paths are changes.
cli-cache.md	src/cli/cache.ts — vx cache prune, duration / size parsers.
cli-help.md	src/cli/help.ts — static help text; src/cli/core-alias.ts — the @vzn/vx virtual module bin.ts registers (see bin.md); src/cli/completions.ts — the vx completions script over the verb table and each verb’s help cut.
plugin-commands.md	src/cli/plugin-commands.ts — plugin-contributed verbs (VxPlugin.commands).
cli-format.md	src/cli/format.ts — formatBytes and other shared formatters.
plan-format.md	src/cli/plan-format.ts — plan → text / JSON / DOT.
upgrade.md	src/cli/upgrade.ts — vx upgrade binary self-update.

The remaining subcommand parsers — src/cli/{lock,show,info,last,why,init}.ts — are user-facing commands documented in docs/cli.md rather than as module pages; src/cli/run-id.ts resolves the run id last and why take, whole or a unique prefix; src/cli/plugin-templates.ts is the generated copy of the example plugins vx init --plugin writes. tests/doc-references.test.ts holds this index to the tree: every src/**/*.ts except the index.ts files is named here, itself or in a brace group.

Orchestrator

File	Topic
orchestrator.md	src/orchestrator/{index,run}.ts — module contract + run() / planRun() entry.
	src/orchestrator/run-records.ts — the runs rows, invocation header and telemetry mirror from one pass (see orchestrator.md).
	src/orchestrator/persistent.ts — keep-alive selection and bounded shutdown of persistent children (see orchestrator.md).
	src/orchestrator/run-lock.ts — one run at a time per workspace on this machine; runs in one process share it (see orchestrator.md).
options.md	src/orchestrator/options.ts — RunOptions / RunSummary declarations.
execute-task.md	src/orchestrator/execute-task.ts — per-task: hash → cache lookup → spawn → save.
sandbox-request.md	src/orchestrator/sandbox-request.ts — arming the runtime for a run; the sandbox half of an ExecuteRequest: grants, binds.
keyed-projects.md	src/orchestrator/keyed-projects.ts — the projects a task’s key answers for, which bound a cached task’s linked-package grant.
execute-task.md § Verdict	src/orchestrator/shell-verdict.ts — the frame line for exit 126, 127 and 128 + n: the PATH rule, the file, the signal.
miss-save.md	src/orchestrator/miss-save.ts — what a miss leaves behind: resolve outputs, save, mark git.
miss-save.md § The save lane	src/orchestrator/save-lane.ts — the bounded off-slot save queue run() drains before the upload drain.
lockfile-claim.md	src/orchestrator/lockfile-claim.ts — the claimant’s shell a lockfile plugin wraps its parser in, and reachDigests.
hit-restore.md	src/orchestrator/hit-restore.ts — what a hit leaves behind: the two proofs, clean + restore, mark git, replay stdout.
task-hash.md	src/orchestrator/task-hash.ts — cache-key derivation (computeTaskHash & co.).
upstream.md	src/orchestrator/upstream.ts — which upstream a key folds, by cache.inputs.tasks (selectFoldedDeps, one matcher for both paths).
excluded-keys.md	src/orchestrator/excluded-keys.ts — the key of a dependency --exclude-dependencies keeps from running, and the taint it seeds.
logger.md	src/orchestrator/logger.ts — default logger (flow-aware policy, frames, replay).
status-line.md	src/orchestrator/status-line.ts — serialized writer + dynamic bottom status line.
framed-output.md	src/orchestrator/framed-output.ts — ┌─ task ─┐ border helpers + one-liners.
failure-recap.md	src/orchestrator/failure-recap.ts — the bounded tail the run’s last block repeats for each failed task.
colors.md	src/orchestrator/colors.ts — ANSI gate + truecolor helpers.
summary.md	src/orchestrator/summary.ts — the footer: projects / tasks / cache meters, info and time rows.
plan.md	src/orchestrator/plan.ts — --dry / --graph planning (no exec).
placement.md	src/orchestrator/placement.ts — where each task runs: pins, executor order, 'only', pools, the --dry view.
signals.md	src/orchestrator/signals.ts — SIGINT/SIGTERM/SIGHUP forwarded, as a group signal, to every child, then exit 128+signo.
admission.md	src/orchestrator/admission.ts — between scheduler and task: in-flight dedup (an embedder’s registry) and continue-taint.
run-artifacts.md	src/orchestrator/run-artifacts.ts — --summarize JSON + --profile trace writers.
prepare.md	src/orchestrator/prepare.ts — shared run / planRun setup (workspace, graph, cache).
projects.md	src/orchestrator/projects.ts — the staged project-config load runs and vx show share.
tally.md	src/orchestrator/tally.ts — shared outcome tally for summary + summarize JSON.
events.md	src/orchestrator/events.ts — run event bus + serializable WireEvent contract.
plugin.md	src/orchestrator/plugin.ts — VxPlugin capabilities + installer.
plugin-host.md	src/orchestrator/plugin-host.ts — capability consultation + end-of-run teardown/flush.
telemetry.md	src/orchestrator/telemetry.ts — versioned telemetry export contract.
telemetry-host.md	src/orchestrator/telemetry-host.ts — sink consultation (zero-sink = zero cost).
run-context.md	src/orchestrator/run-context.ts — git / CI / host capture (≤1 spawn).
stable-keys.md	src/orchestrator/stable-keys.ts — shared stable-key derivation + stability gate.
fingerprint-watch.md	src/orchestrator/fingerprint-watch.ts — has a task rewritten the lockfile mid-run? Re-checked only after one that may.
download-policy.md	src/orchestrator/download-policy.ts — --download modes + the deferral eligibility gate.
deferred-outputs.md	src/orchestrator/deferred-outputs.ts — deferred-output registry + lazy materialise/converge.
local-shortcircuit.md	src/orchestrator/local-shortcircuit.ts — restore-ahead classify (two-tier schedule).
remote-prefetch.md	src/orchestrator/remote-prefetch.ts — background remote GETs (LayeredCache only).
history.md	src/orchestrator/history.ts — per-task duration history behind --dry predictions.
	src/orchestrator/failure-mode.ts — the flakiness verdict, in one place (see history.md).
metrics.md	src/orchestrator/metrics.ts — run-history queries behind vx last / vx why / the MCP.
doctor.md	src/orchestrator/doctor.ts — the workspace doctor’s facts behind vx info and the MCP’s getWorkspaceInfo.
task-log-buffer.md	src/orchestrator/task-log-buffer.ts — bounded per-task log capture for telemetry sinks.
run-report.md	src/orchestrator/run-report.ts — --report=markdown table.

Workspace + discovery

File	Topic
workspace.md	src/workspace/{workspace,load-reads}.ts — findWorkspaceRoot, listProjects, cacheDir; the root files a load reads once.
project-loader.md	src/workspace/project-loader.ts — vx.config.* / vx.workspace.* evaluation.
config-schema.md	src/workspace/config-schema.ts — what a config may say: the validators, every level.
	src/workspace/json-data.ts — a config is JSON data: the one rule the loader, the config worker and the playground run (see config-schema.md).
package-graph.md	src/workspace/package-graph.ts — workspace dep graph from package.json.
filter.md	src/workspace/filter.ts — pnpm-style --filter DSL parser + applier.
affected.md	src/workspace/affected.ts — git-relative project selection.
config-imports.md	src/workspace/config-imports.ts — the config-import selection channel.
config-cache.md	src/workspace/config-cache.ts — cached evaluations of provably-pure configs.
nested-dirs.md	src/workspace/nested-dirs.ts — boundary set (other projects rooted under each).
fingerprint.md	src/workspace/fingerprint.ts — workspace fingerprint (lockfile + workspace yaml).
lockfile.md	src/workspace/lockfile.ts — vx-lock.json freeze / trust / audit.
migration.md	src/workspace/{migration,migrate-scripts}.ts — the plan → files seam vx init and @vzn/vx-migrate share; the scripts mapper.
	src/workspace/config-eval.ts — fresh re-evaluation in a Worker (see project-loader.md).

Graph + scheduler

File	Topic
task-graph.md	src/graph/task-graph.ts — TaskNode DAG builder + cycle detection.
scheduler.md	src/graph/scheduler.ts — parallel topological executor.
	src/graph/priorities.ts — the ready-queue ranking (see scheduler.md).
dependency-spec.md	src/graph/dependency-spec.ts — shared Turbo/Nx micro-syntax parser.

Cache cluster

File	Topic
cache.md	src/cache/cache.ts — local cache: bun:sqlite index + tar.zst artifacts.
	src/cache/{layer,policy,zstd,schema,file-hashes,config-evals,output-index,run-history,key-fold}.ts — the slices Cache composes (cache.md § Files); src/cache/{archive,tar-stream}.ts — pack / scan / extract (cache.md, caching.md § Storage layout).
layered-cache.md	src/cache/layered-cache.ts — local + remote composition + RemoteCacheLayer seam.
inputs.md	src/cache/inputs.ts — glob resolution, boundary enforcement, cleanOutputs.
git-inputs.md	src/cache/git-inputs.ts — the git enumeration (ls-files, status, check-attr) the resolver trusts.

Exec (process primitives)

File	Topic
runner.md	src/exec/runner.ts — runCommand, runPersistent, shellQuote.
kill-tree.md	src/exec/kill-tree.ts — killTree: a task’s process group dies with it (timeout, signal, shutdown).
env.md	src/exec/env.ts — child env composition + essential allowlist.
sandbox-runtime.md	src/exec/sandbox-runtime.ts — runSandboxed + violation tracking via @anthropic-ai/sandbox-runtime.
	src/exec/sandbox-violations.ts — strace pass, seatbelt record description, report filters (see sandbox-runtime.md).
	src/exec/sandbox-binds.ts — bwrap-honourable write grants, read-grant punching, the SRT custom config.
	src/exec/sandbox-paths.ts — toRealPath, absolutize, isUnderAny, unique.
executor.md	src/exec/executor.ts — TaskExecutor contract + selectExecutor.
	src/exec/local-executor.ts — the floor: run it here (see executor.md, plugins.md).

Plugins

File	Topic
plugins.md	Core ships no plugin: the floor (run here, cache here) and where plugins live (packages/vx-*).
chained-cache.md	src/cache/chained-cache.ts — several declared cache layers, chained in order.

Utilities

File	Topic
util-paths.md	src/util/paths.ts — POSIX-path normaliser for stable cache keys.
util-hash.md	src/util/hash.ts — xxHash3 helpers shared by every key-derivation site.
util-ulid.md	src/util/ulid.ts — run-id generator (Bun.randomUUIDv7 wrapper).
util-errors.md	src/util/errors.ts — UserError class for stack-less error reporting.
timing.md	src/util/timing.ts — the VX_TIMING=1 stage table + per-task spans.
util-edit-distance.md	src/util/edit-distance.ts — the one “did you mean” rule.
util-bun-version.md	src/util/bun-version.ts — the Bun floor, read at run time, and what breaks below it.
util-num.md	src/util/num.ts — MAX_TIMEOUT_MS, clampInt, parseDecimalInt.
util-settle.md	src/util/settle.ts — the end-of-run settle bound for plugin teardown.
util-tail.md	src/util/tail.ts — head-evicting tail for a persistent task’s output.
util-secret-mask.md	src/util/secret-mask.ts — masks secret-named variables’ values in what vx shows.
util-which.md	src/util/which.ts — executablePath: a tool’s absolute path on vx’s own PATH, found once.
util-procfs.md	src/util/procfs.ts — procfsIsOwn: is /proc this pid namespace’s view, asked once.
util-cgroup.md	src/util/cgroup.ts — the cores and memory this process may use, as its cgroup bounds them.
	src/util/{size,verbs}.ts — parseSize, parseDuration (cli-cache.md) and the core verb list (cli.md).
	src/util/task-id.ts — splitTaskId, the first-# inverse of taskId (task-graph.md).

For the public package surface (what import('@vzn/vx') resolves to) see index.md.