Builds

── Builds ────────────────────────────────────────────────────────────────

A Build turns a BuildInput (identified by CID) into an output artifact DAG (also a CID), emitting progress events along the way. Builds are independent of one another (any number may exist at once).

Builds are purely in-memory runtime objects (like FUSE mounts): they do NOT survive a node restart and are not persisted to local storage.

Implementation note (current): the transform is a PASS-THROUGH — output_cid == input_cid. The lifecycle, event stream, target-ref/mount, and input-watching surface defined here is the real contribution; the actual build step is a placeholder to be filled in later.

Input source (CreateBuildRequest.input oneof) — three resulting kinds: • Explicit CID (explicit_input_cid): a standalone, one-shot build of a fixed BuildInput CID. NOT bound to any workspace; it never changes and runs once. • Workspace, not watching (workspace.watch = false): bound to a registered workspace; pins a snapshot of that workspace's current BuildInput CID at create time and runs once. • Workspace, watching / interactive (workspace.watch = true): bound to a registered workspace and follows its BuildInput — every workspace sync that produces a new BuildInput CID is adopted automatically and triggers an incremental re-run that continues from the build's current state.

A workspace-bound build is tied to that workspace's lifetime: deregistering the workspace cancels and removes its builds, ending any open Watch/Attach streams. Explicit-CID builds are unaffected by workspace changes.

Detached vs attached lifecycle: • Detached: CreateBuild → (GetBuild | WatchBuild) → StopBuild / DeleteBuild. The build runs server-side independent of any client; closing a WatchBuild stream does NOT stop or delete it. • Attached: CreateBuildAttached (create + stream in one call) or AttachBuild (bind to an existing build). The build's run is tied to the stream: if the client cancels/closes the RPC, the server STOPS the build and KEEPS its record (state BUILD_STATE_CANCELLED). DetachBuild severs that binding so the build keeps running.

Detach, stop and remove are three independent operations, each able to cascade to the next by an explicit flag: • DetachBuild — stop watching. stop also stops it. • StopBuild — cancel the build's in-flight invocations and reap its pods. remove also removes it. • DeleteBuild — discard the record. Removing implies stopping: a record may be discarded, but the workloads it started may not be left running with nobody watching them. A disconnect therefore stops rather than deletes — the moment right after a failure is when the record is worth the most, and it used to be destroyed exactly then.

Finished records are retained up to the daemon's builds.retain_finished bound, evicting the least valuable first (failures outrank successes). A retained record holds no GC pins; its log CIDs stay readable because the log streams themselves are what pin their blocks.

Service builder.Builds, 16 rpcs.

CreateBuild(CreateBuildRequest) -> CreateBuildResponse

Create a detached build and return its initial snapshot. The build is queued and runs in the background. INVALID_ARGUMENT if the workspace path is non-canonical; NOT_FOUND if it is not registered.

Request: CreateBuildRequest

message CreateBuildRequest {
  optional bool refetch = 3;
  optional map<string, string> labels = 8;
  oneof input {
    string explicit_input_cid = 1;
    WorkspaceInput workspace = 2;
  }
  oneof mode {
    RunBuild run = 6;
    FetchOnly fetch_only = 7;
  }
}

Response: CreateBuildResponse

message CreateBuildResponse {
  optional Build build = 1;
}

CreateBuildAttached(CreateBuildRequest) -> stream BuildEvent

Create a build and immediately attach to it. The response stream carries the build's events (a snapshot first, then live events). Cancelling or closing this stream deletes the build, unless it was first detached via DetachBuild.

Request: CreateBuildRequest

The same message as CreateBuildRequest.

Response: BuildEvent

Streamed by WatchBuild / AttachBuild / CreateBuildAttached.

The first message on every stream is a snapshot carrying the full current Build; subsequent messages are incremental events. Every non-snapshot event carries the generation it belongs to so clients can ignore stale events after an incremental re-run.

message BuildEvent {
  oneof event {
    Build snapshot = 1;
    BuildStarted started = 2;
    BuildProgress progress = 3;
    BuildSucceeded succeeded = 4;
    BuildFailed failed = 5;
    BuildInputUpdated input_updated = 6;
    BuildAttachment attachment = 7;
    TaskEvent task = 8;
    BuildDeleted deleted = 9;
  }
}

ListBuilds(ListBuildsRequest) -> ListBuildsResponse

All builds, newest first. Optionally restricted to one workspace.

Request: ListBuildsRequest

message ListBuildsRequest {
  oneof _workspace_canonical_path {
    string workspace_canonical_path = 1;
  }
}

Response: ListBuildsResponse

message ListBuildsResponse {
  repeated Build builds = 1;
}

WatchBuilds(WatchBuildsRequest) -> stream ListBuildsResponse

Watch the whole build list live. Yields the current list first, then a fresh full snapshot whenever any build is created, deleted, or changes state — same Build entries as ListBuilds (status + metadata, not the per-build progress tree). Detached: cancelling has no effect on any build.

Request: WatchBuildsRequest

message WatchBuildsRequest {
  oneof _workspace_canonical_path {
    string workspace_canonical_path = 1;
  }
}

Response: ListBuildsResponse

The same message as ListBuildsResponse.

GetBuild(GetBuildRequest) -> GetBuildResponse

Snapshot of a single build. NOT_FOUND if the id is unknown.

Request: GetBuildRequest

message GetBuildRequest {
  optional string build_id = 1;
}

Response: GetBuildResponse

message GetBuildResponse {
  optional Build build = 1;
}

GetBuildTests(GetBuildTestsRequest) -> GetBuildTestsResponse

The full per-case test breakdown for a build, aggregated across every test target in its output. Computed on demand by the daemon (fetching the BuildOutput + each TestResults DAG); clients never download the raw blocks. NOT_FOUND if the id is unknown. A running build (no output yet) yields an empty, incomplete summary.

Request: GetBuildTestsRequest

message GetBuildTestsRequest {
  optional string build_id = 1;
}

Response: GetBuildTestsResponse

The full per-case test breakdown for a build, aggregated across all of its test targets. Cheap counts live in summary; targets carries the cases.

message GetBuildTestsResponse {
  optional string build_id = 1;
  optional BuildState state = 2;
  optional TestSummary summary = 3;
  repeated TestTarget targets = 4;
}

GetBuildMetrics(GetBuildMetricsRequest) -> GetBuildMetricsResponse

The parsed metric rows of every metrics target the build produced (see OutputKind::Metrics: a target whose payload is InfluxDB line-protocol rows). Each row carries its target's name as the target tag, so one response spans all targets and stays filterable. By default every row is returned verbatim; query can filter (measurement / tag equality / field subset) and aggregate (group_by tags + one of sum|avg|min|max|count|last). Rows that fail to parse are reported per line in errors, never dropped silently. Beside the targets' rows come the node's own for the build — its pods' sccache traffic (measurements sccache, sccache_build, sccache_not_cached, tagged target=sccache; see docs/sccache.md) — which exist while the build runs. A running build with neither yields an empty, incomplete response.

Request: GetBuildMetricsRequest

message GetBuildMetricsRequest {
  optional string build_id = 1;
  optional MetricsQuery query = 2;
}

Response: GetBuildMetricsResponse

message GetBuildMetricsResponse {
  optional string build_id = 1;
  optional BuildState state = 2;
  repeated MetricRowView rows = 3;
  repeated MetricsParseError errors = 4;
  optional bool complete = 5;
}

WatchBuildMetrics(GetBuildMetricsRequest) -> stream GetBuildMetricsResponse

Like GetBuildMetrics, but a stream: emits the current state immediately, then a fresh snapshot whenever the build's metrics change: when its output lands, and — at most once a second — while its pods use sccache. Ends when the build reaches a terminal state.

Request: GetBuildMetricsRequest

The same message as GetBuildMetricsRequest.

Response: GetBuildMetricsResponse

The same message as GetBuildMetricsResponse.

GetBuildProblems(GetBuildProblemsRequest) -> GetBuildProblemsResponse

Everything a build's tooling said about code: type errors, lints, deprecations — the build's problems.

Two sources, one list. A controller reports diagnostics as its tooling finds them, and any target the build declared as diagnostics (see OutputKind::DIAGNOSTICS) is read out of its stored block chain and folded in when the build produces it. A caller does not have to know which tool took which route.

Its own RPC rather than a field on Build because a Build is re-sent on every list change, per retained build: diagnostics there had to be capped at 100 to keep that stream deliverable, which lost exactly the findings of the workspace that stopped compiling. Here the cost is paid by whoever asks, so nothing is dropped — the response pages instead.

NOT_FOUND if the id is unknown. A build with no findings yields an empty page, which is an answer rather than an absence.

Request: GetBuildProblemsRequest

message GetBuildProblemsRequest {
  optional string build_id = 1;
  optional uint32 page_size = 2;
  optional string page_token = 3;
}

Response: GetBuildProblemsResponse

message GetBuildProblemsResponse {
  repeated CodeDiagnostic problems = 1;
  optional string next_page_token = 2;
  optional ProblemCounts counts = 3;
  optional bool complete = 4;
}

WatchBuildProblems(WatchBuildProblemsRequest) -> stream BuildProblemsEvent

Like GetBuildProblems, but live: the findings so far, then each new batch as it is found, so a long typecheck reports its first error immediately rather than at the end.

The leading snapshot is sent before the subscription can miss anything, so a client that joins late sees the same set as one that was there from the start. A diagnostic may therefore arrive twice — once in the snapshot and again live — which a client dedupes on (path, line, column, code); the other way round would lose one in the gap, and lose it undetectably.

Ends when the build reaches a terminal state and its last batch is sent.

Request: WatchBuildProblemsRequest

message WatchBuildProblemsRequest {
  optional string build_id = 1;
}

Response: BuildProblemsEvent

One batch of a build's problems.

message BuildProblemsEvent {
  optional uint64 generation = 1;
  repeated CodeDiagnostic problems = 2;
  optional bool reset = 3;
  optional ProblemCounts counts = 4;
  optional bool complete = 5;
}

WatchBuild(WatchBuildRequest) -> stream BuildEvent

Subscribe to a build's events WITHOUT binding its lifecycle. Yields the current snapshot first, then live events. The stream ends cleanly when the build is deleted or its workspace is deregistered; cancelling it has no effect on the build (detached watch).

Request: WatchBuildRequest

message WatchBuildRequest {
  optional string build_id = 1;
}

Response: BuildEvent

The same message as BuildEvent.

AttachBuild(AttachBuildRequest) -> stream BuildEvent

Attach to an existing (typically detached) build: same stream semantics as WatchBuild, but cancelling/closing the stream STOPS the build (its record is kept). Use DetachBuild to sever the binding while leaving the build running.

Request: AttachBuildRequest

message AttachBuildRequest {
  optional string build_id = 1;
}

Response: BuildEvent

The same message as BuildEvent.

DetachBuild(DetachBuildRequest) -> DetachBuildResponse

Sever the lifecycle binding of an attached build so a later cancellation of its attach stream no longer stops it. The build keeps running; any active attach stream stays open as a plain watch. applied = false if the build was already detached. With stop, cascades to StopBuild.

Request: DetachBuildRequest

message DetachBuildRequest {
  optional string build_id = 1;
  optional bool stop = 2;
}

Response: DetachBuildResponse

message DetachBuildResponse {
  optional bool applied = 1;
  optional bool was_stopped = 2;
}

StopBuild(StopBuildRequest) -> StopBuildResponse

Stop a build: cancel its in-flight invocations (so a running pod.dag op — e.g. a cloud-hypervisor VM — is torn down rather than left running) and reap its pods. The record is KEPT and stays inspectable via GetBuild / ListBuilds in state BUILD_STATE_CANCELLED, subject to retention. Open Watch/Attach streams stay open and see the terminal snapshot. Idempotent: was_running = false if the build had already finished. NOT_FOUND is not returned — an unknown id yields was_running = false. With remove, cascades to DeleteBuild.

Request: StopBuildRequest

message StopBuildRequest {
  optional string build_id = 1;
  optional bool remove = 2;
}

Response: StopBuildResponse

message StopBuildResponse {
  optional bool was_running = 1;
  optional bool was_removed = 2;
}

DeleteBuild(DeleteBuildRequest) -> DeleteBuildResponse

Remove a build's record. Implies StopBuild: any FUSE mounts the build created (from its mount_targets) are unmounted and removed, its pods are reaped, and open Watch/Attach streams for it end cleanly. was_deleted = false if the id was unknown.

Request: DeleteBuildRequest

message DeleteBuildRequest {
  optional string build_id = 1;
}

Response: DeleteBuildResponse

message DeleteBuildResponse {
  optional bool was_deleted = 1;
}

SetBuildTargets(SetBuildTargetsRequest) -> SetBuildTargetsResponse

Replace a build's targets spec, resuming the build under it. A live watching build regenerates at once (same input, next generation — newly selected targets build, deselected ones are no longer forced). A finished, failed or cancelled build goes back to RUNNING: its driver is respawned, so a failed build can succeed with fewer targets and a cancelled one can resume. A one-shot build still mid-run keeps its current generation (generations are serial; there is no preemption) and the spec applies if it is later resumed. FAILED_PRECONDITION if the build cannot be resumed (removed, or its workspace deregistered).

Request: SetBuildTargetsRequest

message SetBuildTargetsRequest {
  optional string build_id = 1;
  optional BuildTargetsSpec targets = 2;
}

Response: SetBuildTargetsResponse

message SetBuildTargetsResponse {
  optional Build build = 1;
}

Types used above

WorkspaceInput

Take the build input from a registered workspace's BuildInput.

message WorkspaceInput {
  optional string workspace_canonical_path = 1;
  optional bool watch = 2;
}

RunBuild

A normal build: run the (workspace's) build controller over the input.

message RunBuild {
  repeated BuildRefTarget ref_targets = 2;
  repeated BuildMountTarget mount_targets = 3;
  repeated BuildExportTarget export_targets = 4;
  repeated BuildDeployTarget deploy_targets = 5;
  optional bool profile_pods = 6;
  repeated string cache_read = 7;
  repeated string cache_write = 8;
  optional bool no_cache_read = 9;
  optional bool no_cache_write = 10;
  optional bool no_targets = 11;
  optional BuildTargetsSpec targets_spec = 12;
  repeated string run_targets = 13;
  optional DistributedBuildPolicy distributed_policy = 14;
  optional map<string, string> options = 15;
  optional bool no_cache = 16;
  optional SingleItemTarget single_item = 17;
}

BuildRefTarget

Write (part of) the build output as a local ref on every successful run.

message BuildRefTarget {
  optional string ref_name = 1;
}

BuildMountTarget

FUSE-mount (part of) the build output on success, reusing the same machinery as CreateMount. The mount is refreshed to the new sub-DAG CID on each successful incremental re-run (like UpdateMount), is reported by ListMounts with its owning build_id, and is removed automatically when the build is deleted (DeleteBuild) or its workspace is deregistered.

message BuildMountTarget {
  optional string path = 1;
  optional uint32 fetch_timeout_secs = 3;
  optional string name = 4;
  repeated BuildResolvedPath resolved = 5;
}

BuildResolvedPath

One target an export or a mount placed, and the path its template resolved to for it.

message BuildResolvedPath {
  optional string target = 1;
  optional string path = 2;
}

BuildExportTarget

Materialise build outputs to paths on the server filesystem on every successful run (--export FILTER:PATH).

message BuildExportTarget {
  optional string name = 1;
  optional string host_path = 2;
  repeated BuildResolvedPath resolved = 3;
}

BuildDeployTarget

Invoke the build's deployments after a successful run (--deploy FILTER).

message BuildDeployTarget {
  optional string name = 1;
}

BuildTargetsSpec

How a build chooses which declared targets to force.

message BuildTargetsSpec {
  optional TargetsMode mode = 1;
  repeated string filters = 2;
}

SingleItemTarget

One registered item of one member, as bldr build <member>:<item> names it. item is a path within the member (tests/unit); the colon on the command line only says where the member's name — itself a path — ends.

message SingleItemTarget {
  optional string member = 1;
  optional string item = 2;
}

FetchOnly

A fetch-only "build": fetch the workspace's members (streaming their progress as BuildEvent.task) and finish without running a build controller. Requires a workspace input.

message FetchOnly {
  // no fields
}

Build

The build resource. Returned by Create/Get/List and carried as the leading snapshot event on Watch/Attach streams.

message Build {
  optional string id = 1;
  optional string workspace_canonical_path = 2;
  optional BuildState state = 3;
  optional string input_cid = 4;
  optional string output_cid = 6;
  optional bool attached = 7;
  optional bool watch_input = 8;
  repeated BuildRefTarget ref_targets = 9;
  repeated BuildMountTarget mount_targets = 10;
  repeated BuildRefResult ref_results = 11;
  repeated BuildMountResult mount_results = 12;
  optional int64 created_at_seconds = 13;
  optional int64 started_at_seconds = 14;
  optional int64 finished_at_seconds = 15;
  optional string error = 16;
  optional uint64 generation = 17;
  optional string last_progress = 18;
  repeated BuildExportTarget export_targets = 19;
  repeated BuildExportResult export_results = 20;
  repeated BuildDeployTarget deploy_targets = 21;
  repeated BuildDeployResult deploy_results = 22;
  optional string revision_cid = 23;
  optional BuildOwner owner = 24;
  optional TestSummary test_summary = 25;
  repeated string target_members = 26;
  repeated string produced_outputs = 27;
  optional map<string, string> labels = 28;
  optional bool deleted = 29;
  optional TargetList targets = 30;
  optional bool profile_pods = 31;
  repeated string cache_read = 32;
  repeated string cache_write = 33;
  optional bool no_cache_read = 34;
  optional bool no_cache_write = 35;
  optional bool no_targets = 38;
  optional BuildTargetsSpec targets_spec = 39;
  repeated BuildAction actions = 40;
  repeated string run_targets = 41;
  optional DistributedBuildPolicy distributed_policy = 42;
  optional BuildTaskCounts task_counts = 43;
  optional map<string, string> option_overrides = 44;
  optional bool no_cache = 45;
  optional SingleItemTarget single_item = 46;
  optional BuildSccacheSummary sccache = 47;
}

BuildRefResult

Outcome of one BuildRefTarget after a successful run.

message BuildRefResult {
  optional string ref_name = 1;
  optional string cid = 2;
  optional string previous_cid = 3;
}

BuildMountResult

Outcome of one BuildMountTarget after a successful run.

message BuildMountResult {
  optional string mount_id = 1;
  optional string path = 2;
  optional string cid = 3;
}

BuildExportResult

Outcome of one exported target after a successful run.

message BuildExportResult {
  optional string name = 1;
  optional string host_path = 2;
  optional string cid = 3;
}

BuildDeployResult

Outcome of one invoked deployment after a successful run.

message BuildDeployResult {
  optional string name = 1;
  optional string function = 2;
  optional string output = 3;
}

BuildOwner

The resource managing a build. A run (and, in future, a deployment or FUSE mount) can back itself with a build; this points from the build to that owner so the UI can link them and lifecycle can cascade.

message BuildOwner {
  optional string kind = 1;
  optional string id = 2;
}

TestSummary

message TestSummary {
  optional uint32 total = 1;
  optional uint32 passed = 2;
  optional uint32 failed = 3;
  optional uint32 skipped = 4;
  optional uint32 targets = 5;
  optional bool complete = 6;
}

TargetList

The targets a build's workspace declares, and how much to trust the list.

message TargetList {
  optional TargetListStatus status = 1;
  repeated BuildTarget targets = 2;
  optional string error = 3;
}

BuildTarget

One thing a workspace can build, run, deploy or test.

message BuildTarget {
  optional string name = 1;
  optional TargetKind kind = 2;
  optional map<string, string> labels = 3;
  optional bool selected = 4;
  optional TargetBuildStatus status = 5;
  optional string output_cid = 6;
}

BuildAction

One post-build action: something the build does with a target once that target is built — write it somewhere, deploy it, run it.

Actions belong to targets, not to the build as a whole: an action waits for its own target and runs the moment that target lands, so a build with a slow target does not hold up an export of a fast one. Every round re-runs them against the new output, cancelling whatever the previous round still had in flight.

message BuildAction {
  optional BuildActionKind kind = 1;
  optional string target = 2;
  optional string argument = 3;
  optional BuildActionState state = 4;
  optional string detail = 5;
  optional string cid = 6;
  optional string resource_id = 7;
  optional string filter = 8;
}

BuildTaskCounts

A build's tasks by state. Every task is counted in exactly one field, so the fields sum to total.

message BuildTaskCounts {
  optional uint32 total = 1;
  optional uint32 running = 2;
  optional uint32 waiting = 3;
  optional uint32 waiting_for_resources = 4;
  optional uint32 queued = 5;
  optional uint32 retrying = 6;
  optional uint32 completed = 7;
  optional uint32 cached = 8;
  optional uint32 failed = 9;
  optional uint32 cancelled = 10;
  optional uint32 skipped = 11;
}

BuildSccacheSummary

Aggregate case counts over one or more test targets. total == passed + failed + skipped. complete is false while results are still being computed or the build is mid-run (partial); true once the aggregate is final. A build's sccache traffic, summed over every pod of the build that asked for sccache. Server-side counts (lookups, transfers, wall time) are measured by the node as it answers; the compile counts are what the pods' sccache wrappers reported back (RecordStats).

message BuildSccacheSummary {
  optional uint32 pods = 1;
  optional uint64 lookups = 2;
  optional uint64 hits = 3;
  optional uint64 misses = 4;
  optional uint64 puts = 5;
  optional uint64 put_failures = 6;
  optional uint64 bytes_downloaded = 7;
  optional uint64 bytes_uploaded = 8;
  optional double lookup_seconds = 9;
  optional double download_seconds = 10;
  optional double upload_seconds = 11;
  optional uint64 preprocessor_hits = 12;
  optional uint64 preprocessor_misses = 13;
  optional uint64 preprocessor_puts = 14;
  optional uint64 compile_requests = 15;
  optional uint64 not_cacheable = 16;
  optional uint64 compilations = 17;
  optional uint64 compile_fails = 18;
  optional map<string, uint64> not_cached_reasons = 19;
}

BuildStarted

message BuildStarted {
  optional uint64 generation = 1;
  optional string input_cid = 2;
  optional int64 started_at_seconds = 3;
}

BuildProgress

A free-form progress event emitted while RUNNING (a build log line, a step transition, etc.).

message BuildProgress {
  optional uint64 generation = 1;
  optional string message = 2;
  optional map<string, string> fields = 3;
}

BuildSucceeded

message BuildSucceeded {
  optional uint64 generation = 1;
  optional string output_cid = 2;
  optional int64 finished_at_seconds = 3;
  repeated BuildRefResult ref_results = 4;
  repeated BuildMountResult mount_results = 5;
  repeated BuildExportResult export_results = 6;
  repeated BuildDeployResult deploy_results = 7;
}

BuildFailed

message BuildFailed {
  optional uint64 generation = 1;
  optional string error = 2;
  optional int64 finished_at_seconds = 3;
}

BuildInputUpdated

Emitted on a watch_input build when the workspace it follows produces a new BuildInput CID (i.e. after a workspace sync), immediately before the resulting incremental run's BuildStarted.

message BuildInputUpdated {
  optional uint64 generation = 1;
  optional string input_cid = 2;
}

BuildAttachment

Emitted when a build's attachment flips (e.g. DetachBuild was called, or a new client attached). attached mirrors Build.attached.

message BuildAttachment {
  optional bool attached = 1;
}

BuildDeleted

The build was removed from the node: no snapshot, log or progress tree for it can be fetched again.

message BuildDeleted {
  optional string reason = 1;
}

TestTarget

One test target's result: its name, the CID of its TestResults DAG (empty if the target produced no TestResults — it "passes by building"), a per-target summary, and the cases themselves.

message TestTarget {
  optional string name = 1;
  optional string cid = 2;
  optional TestSummary summary = 3;
  repeated TestCaseView cases = 4;
  optional bool truncated = 5;
}

MetricsQuery

Row selection and aggregation for build metrics. Selection criteria AND together; aggregation applies after selection.

message MetricsQuery {
  optional string measurement = 1;
  optional map<string, string> tags = 2;
  repeated string fields = 3;
  optional string agg = 4;
  repeated string group_by = 5;
}

MetricRowView

One metric sample: measurement + indexed tags + value fields (+ optional sample time). The line-protocol row, parsed.

message MetricRowView {
  optional string measurement = 1;
  optional map<string, string> tags = 2;
  optional map<string, MetricValue> fields = 3;
  oneof _timestamp_ns {
    int64 timestamp_ns = 4;
  }
}

MetricValue

message MetricValue {
  oneof kind {
    double f = 1;
    int64 i = 2;
    uint64 u = 3;
    bool b = 4;
    string s = 5;
  }
}

MetricsParseError

A line of a metrics target that failed to parse: which target, which line, and why. Reported alongside the rows that did parse.

message MetricsParseError {
  optional string target = 1;
  optional uint32 line = 2;
  optional string error = 3;
}

ProblemCounts

Totals over the whole set, not over the page in hand.

On every page on purpose. A reader deciding whether to page on wants to know what is left, and a client that had to sum pages to learn the total could only ever know it after fetching all of them — which is the thing paging exists to avoid.

message ProblemCounts {
  optional uint32 errors = 1;
  optional uint32 warnings = 2;
  optional uint32 infos = 3;
  optional uint32 total = 4;
}

TargetsMode

Where a build's target selection comes from.

enum TargetsMode {
  TARGETS_MODE_UNSPECIFIED = 0;
  TARGETS_MODE_WORKSPACE_DEFAULTS = 1;
  TARGETS_MODE_NONE = 2;
  TARGETS_MODE_EXPLICIT = 3;
}

DistributedBuildPolicy

Where a build's invocations are allowed to execute.

A build's work is a tree of function invocations, and every one of them can in principle run on this node or on a peer that provides the same function. This is the build's say in that choice. It applies to the whole tree — the pod.dag calls a controller makes and everything nested under them — because "this build stays here" is not a statement you can make about half a build.

The local invocation cache is not execution and is always consulted: a hit returns a CID without running anything, anywhere.

enum DistributedBuildPolicy {
  DISTRIBUTED_BUILD_POLICY_LOCAL_EXCEPT_UNSUPPORTED = 0;
  DISTRIBUTED_BUILD_POLICY_LOCAL_ONLY = 1;
  DISTRIBUTED_BUILD_POLICY_LOCAL_EXCEPT_QUEUED = 2;
  DISTRIBUTED_BUILD_POLICY_NON_LOCAL = 3;
}

BuildState

enum BuildState {
  BUILD_STATE_UNSPECIFIED = 0;
  BUILD_STATE_PENDING = 1;
  BUILD_STATE_RUNNING = 2;
  BUILD_STATE_SUCCEEDED = 3;
  BUILD_STATE_FAILED = 4;
  BUILD_STATE_CANCELLED = 5;
}

TargetListStatus

How much to trust a [TargetList].

enum TargetListStatus {
  TARGET_LIST_STATUS_UNSPECIFIED = 0;
  TARGET_LIST_STATUS_GENERATING = 1;
  TARGET_LIST_STATUS_FAILED = 2;
  TARGET_LIST_STATUS_DONE = 3;
  TARGET_LIST_STATUS_STALE = 4;
}

TargetKind

What a target is. Decides which verb applies to it: an output is exported, a test run for its verdict, a runnable started, a deployment invoked.

enum TargetKind {
  TARGET_KIND_UNSPECIFIED = 0;
  TARGET_KIND_OUTPUT_DIRECTORY = 1;
  TARGET_KIND_CONTAINER_IMAGE = 2;
  TARGET_KIND_TEST = 3;
  TARGET_KIND_RUNNABLE = 4;
  TARGET_KIND_DEPLOYMENT = 5;
  TARGET_KIND_COVERAGE = 6;
  TARGET_KIND_METRICS = 7;
  TARGET_KIND_DIAGNOSTICS = 8;
  TARGET_KIND_PIPELINE = 9;
}

TargetBuildStatus

One selected target's build progress. Deliberately coarse: targets share a DAG, so most of a target's work happens inside tasks shared with others — there is no meaningful per-target queue position. A selected target carries no status until its own resolution starts; only DONE/FAILED are final.

enum TargetBuildStatus {
  TARGET_BUILD_STATUS_UNSPECIFIED = 0;
  TARGET_BUILD_STATUS_BUILDING = 1;
  TARGET_BUILD_STATUS_DONE = 2;
  TARGET_BUILD_STATUS_FAILED = 3;
  TARGET_BUILD_STATUS_NOT_FOUND = 4;
}

BuildActionKind

enum BuildActionKind {
  BUILD_ACTION_KIND_UNSPECIFIED = 0;
  BUILD_ACTION_KIND_REF = 1;
  BUILD_ACTION_KIND_EXPORT = 2;
  BUILD_ACTION_KIND_DEPLOY = 3;
  BUILD_ACTION_KIND_RUN = 4;
  BUILD_ACTION_KIND_MOUNT = 5;
}

BuildActionState

enum BuildActionState {
  BUILD_ACTION_STATE_UNSPECIFIED = 0;
  BUILD_ACTION_STATE_SCHEDULED = 1;
  BUILD_ACTION_STATE_RUNNING = 2;
  BUILD_ACTION_STATE_DONE = 3;
  BUILD_ACTION_STATE_FAILED = 4;
  BUILD_ACTION_STATE_CANCELLED = 5;
  BUILD_ACTION_STATE_NO_TARGET = 6;
}