Skip to content
vx vx

src/index.ts — public package surface

Purpose

Section titled “Purpose”

The single entry point for import x from '@vzn/vx'. Everything in this file is the public API; everything else under src/ is internal. Since the core/service split this is the cross-package contract: the service package, @vzn/vx-otel, and any third-party plugin import everything they need from here via the bare '@vzn/vx' specifier — never a deep src/... path. The exact symbol set (~80 exports) is pinned by tests/package-boundaries.test.ts; widening it is a deliberate snapshot update.

Public surface (by group)

Section titled “Public surface (by group)”
GroupKey exports
Version + errorsVERSION, UserError
SchemadefineProject, defineWorkspace; types WorkspaceConfig, ProjectConfig, TaskConfig, ExecConfig, ExecEnv, CacheConfig, CacheInputs, CacheOutputs, SandboxConfig, SandboxNetworkConfig
Enginerun, planRun, prepareRun; computeTaskHash, createHashCache, deriveStableKeys; captureGitContext, captureWorkspaceIdentity; FULL_CACHE_POLICY, parseCachePolicy; types RunOptions, RunSummary, CachePolicy, PreparedRun, HashCache, StableKey, GitContext, WorkspaceIdentity, Logger, OutputView; defaultLogger, resolveOutputView
GraphbuildTaskGraph, expandRequested, isGroupTask, markSurfacedDeps; types TaskNode, TaskOutcome, TaskStatus
CacheCache, LayeredCache, GitFilesCache, cleanOutputs, resolveInputs, resolveOutputs; types CacheLayer, RemoteCacheLayer, RunRecord, InvocationRecord (the CAS seam — CASBackend/Digest — is internal until the artifact store lands)
WorkspacefindWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir
Plugin APItypes VxPlugin, EventSink, BackendContext, CacheContext, EventSinkContext, PluginSetupContext
TelemetryTELEMETRY_SCHEMA_VERSION, deriveCacheSource; types TelemetrySink, TelemetryContext, TelemetryRecord, RunSummaryRecord, RunContextRecord, TaskTelemetry, CacheSource
Wire / backendoptionsToRequest, requestToOptions, projectNode, projectOutcome, createWireRenderer; types RunBackend, RunRequest, RunResult, ClientMessage, ServerMessage
Event buscreateEventBus, wireForwarder, toWireEvent, createVxSurface; types EventBus, RunEvent, RunEventSubscriber, WireEvent, TaskView, OutcomeView
JSON-RPC envelopemakeRequest / makeResponse / makeError / makeNotification, encodeForWS/SSE/NDJSON, decodeEnvelope, isEnvelope + the Envelope types, WIRE_CHANNELS, WIRE_PROTOCOL_VERSION
Metrics querieslistRuns, getRun, getRunTrends, getBottlenecks, cacheKeyDiff, compareRuns, whyDidThisRerunQuery, explainCacheKeyQuery, listInvocations, getHitRateSplit, … (the full /v1/* query layer)

Conventions

Section titled “Conventions”
  • Types are exported with export type so a downstream TypeScript project can import them without paying any runtime cost.
  • Everything routes through module contracts — index.ts imports only from each module’s index.ts (boundary-test rule 2).
  • Widening is deliberate. Adding an export means updating the package-boundaries snapshot; that friction is the point.

Versioning

Section titled “Versioning”

VERSION is a string constant. Pre-alpha — currently '0.0.0'. Bump on every release via the release workflow (gh release create v0.x.y triggers .github/workflows/release.yml which builds the cross- target binaries and attaches them).

Tests

Section titled “Tests”

tests/package-boundaries.test.ts pins the export snapshot and the cross-package import law. tests/config.test.ts imports the schema helpers; tests/orchestrator.test.ts imports run.