Build controller

External build controller service.

A build controller is a separate process that the node connects to via a Unix socket. The node calls GetInfo once at startup to learn the controller's name (which must match the workspace's build_controller: value), then calls Build once per generation (including once per watch-mode iteration).

Service builder.controller.v1.BuildController, 4 rpcs.

GetInfo(GetInfoRequest) -> GetInfoResponse

Return controller metadata so the node can register it under the right name.

Request: GetInfoRequest

message GetInfoRequest {
  // no fields
}

Response: GetInfoResponse

message GetInfoResponse {
  optional string name = 1;
  optional string version = 2;
  repeated string capabilities = 3;
}

Build(BuildRequest) -> stream BuildControllerEvent

Execute one build generation. Streams events (progress, task-tree nodes, and a terminal output or error event) back to the node.

Request: BuildRequest

message BuildRequest {
  optional string input_cid = 1;
  repeated string args = 2;
  optional string owner_kind = 3;
  optional string owner_id = 4;
  repeated string node_capabilities = 5;
  optional map<string, string> option_overrides = 6;
}

Response: BuildControllerEvent

One event streamed from the controller back to the node during a build. The stream ends after exactly one terminal event (output or error).

message BuildControllerEvent {
  oneof event {
    ControllerTaskEvent task = 2;
    ControllerOutputEvent output = 3;
    ControllerErrorEvent error = 4;
    ControllerTargetsEvent targets = 5;
    ControllerDiagnosticsEvent diagnostics = 6;
  }
}

StreamLanguageServerProtocol(stream ControllerLspMessage) -> stream ControllerLspMessage

Serve LSP for the workspace's build code — .bldr.ts and .bldr/**/*.ts.

Those files are TypeScript, but not TypeScript a general language server can make sense of: their imports resolve through the build runtime's own rules (bare member specifiers, .bldr/ as an implicit source root, a generated ambient module per member), and the types they are checked against are generated from this daemon's function registry. The controller is the only thing that knows all of that — it already type-checks these files on every build, with exactly the virtual filesystem and paths map a language service needs. So the node routes build-code LSP here rather than reimplementing the resolution.

Its own RPC rather than messages multiplexed into Build: an editor session is long-lived and has no build, while a Build stream belongs to one generation and ends with it. Sharing one would tie the lifetime of a developer's editor to the lifetime of a build.

Request: ControllerLspMessage

One message of an LSP session with the controller.

The first client message must be the header; every later one carries a JSON-RPC payload. The payload is deliberately just a string: the node is a conduit here, not a participant — it routes and rewrites paths, and giving it a typed view of LSP would mean teaching it the protocol twice.

message ControllerLspMessage {
  oneof message {
    ControllerLspHeader header = 1;
    string jsonrpc = 2;
  }
}

Response: ControllerLspMessage

The same message as ControllerLspMessage.

ExecuteGraph(stream GraphNodeMessage) -> stream GraphControllerMessage

Declare one build generation as a graph and answer for its inputs.

The controller declares nodes; the node executes them. The controller's only other part is to say, for a node whose dependencies have resolved, what that node's input is. Scheduling, caching, node state and failure belong to the node (specs/concepts/build-graph.yml).

The node's first message is the start; the controller answers with the root graph. From then on the node sends one PrepareInput per node that has an input mapper and the controller answers each with one InputPrepared. The node ends the generation by closing its stream.

A controller that implements this advertises the build.graph capability; the node uses Build for one that does not.

Request: GraphNodeMessage

One message from the node to the controller during ExecuteGraph.

message GraphNodeMessage {
  oneof message {
    BuildRequest start = 1;
    PrepareInput prepare_input = 2;
  }
}

Response: GraphControllerMessage

One message from the controller to the node during ExecuteGraph.

message GraphControllerMessage {
  oneof message {
    ControllerGraph graph = 1;
    InputPrepared input_prepared = 2;
    ControllerDiagnosticsEvent diagnostics = 3;
    ControllerErrorEvent error = 4;
  }
}

Types used above

ControllerTaskEvent

A snapshot of one node in the controller's progress tree. Consumers key by id; link children via parent; render state. Each event is a full snapshot of that node (idempotent to replay).

message ControllerTaskEvent {
  optional uint64 id = 1;
  optional string label = 3;
  optional ControllerTaskState state = 4;
  optional map<string, string> labels = 10;
  repeated uint64 waiting_for = 11;
  oneof _parent {
    uint64 parent = 2;
  }
  oneof _output {
    string output = 5;
  }
  oneof _progress_update {
    ControllerTaskProgress progress_update = 6;
  }
  oneof _log_stream_id {
    string log_stream_id = 7;
  }
  oneof _log_cid {
    string log_cid = 8;
  }
  oneof _pod_id {
    string pod_id = 9;
  }
  oneof _input {
    string input = 12;
  }
  oneof _wait {
    ControllerTaskWait wait = 13;
  }
}

ControllerTaskProgress

message ControllerTaskProgress {
  optional uint64 current = 1;
  optional uint64 total = 2;
}

ControllerTaskWait

Why a node is not making progress. Mirrors builder.TaskWaiting and builder.TaskWaitingForResources so the node's translation is a copy.

message ControllerTaskWait {
  optional string reason = 1;
  optional string resource = 2;
  optional uint64 needed = 3;
  optional uint64 available = 4;
}

ControllerOutputEvent

message ControllerOutputEvent {
  optional string output_cid = 1;
}

ControllerErrorEvent

message ControllerErrorEvent {
  optional string message = 1;
}

ControllerTargetsEvent

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

Sent as its own event rather than folded into the terminal output because it is known long before the build finishes — the code declares everything by the time its members have been imported — and because a build that fails still has a useful answer to "what could this workspace build". A list that only arrived with a successful output would be missing exactly when it is most wanted.

message ControllerTargetsEvent {
  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;
}

ControllerDiagnosticsEvent

Diagnostics the build's tooling produced, as they are found.

Its own repeatable event rather than something attached to the terminal result, because the value here is timeliness: a typecheck that runs for two minutes should report its first error at three seconds, and a build that fails is exactly the one whose diagnostics matter most — a payload that only rode a successful output would be missing whenever it was wanted. The node appends each event to what it already has; an event is never the complete set, and a controller that has nothing new to say sends nothing.

message ControllerDiagnosticsEvent {
  repeated CodeDiagnostic diagnostics = 1;
}

CodeDiagnostic

One thing a build's tooling said about one place in the source.

Mirrored field-for-field from builder.CodeDiagnostic rather than imported, exactly as BuildTarget and TargetKind above are: this file is the whole contract a controller binary compiles against, and making it depend on the node's own API proto would drag the entire client surface along with it. The node translates one to the other verbatim.

Every positional field is optional in the sense that 0 means "not reported". A tool that knows only the file must still be able to say so — a diagnostic with no line is worth strictly more than no diagnostic.

message CodeDiagnostic {
  optional string member = 1;
  optional string path = 2;
  optional uint32 line = 3;
  optional uint32 column = 4;
  optional uint32 end_line = 5;
  optional uint32 end_column = 6;
  optional DiagnosticLevel level = 7;
  optional string title = 8;
  optional string description = 9;
  optional string snippet = 10;
  optional uint32 snippet_start_line = 11;
  optional string code = 12;
  optional string tool = 13;
  optional string target = 14;
  repeated RelatedDiagnostic related = 15;
  repeated DiagnosticFix fixes = 16;
  optional map<string, string> labels = 17;
  optional string root = 18;
  optional uint64 offset = 19;
  optional uint64 end_offset = 20;
}

RelatedDiagnostic

Mirrors builder.RelatedDiagnostic.

message RelatedDiagnostic {
  optional string message = 1;
  optional DiagnosticSpan location = 2;
}

DiagnosticSpan

Mirrors builder.DiagnosticSpan.

message DiagnosticSpan {
  optional string member = 1;
  optional string path = 2;
  optional uint32 line = 3;
  optional uint32 column = 4;
  optional uint32 end_line = 5;
  optional uint32 end_column = 6;
  optional uint64 offset = 7;
  optional uint64 end_offset = 8;
  optional string root = 9;
}

DiagnosticFix

Mirrors builder.DiagnosticFix.

message DiagnosticFix {
  optional string message = 1;
  optional string applicability = 2;
}

ControllerLspHeader

What an LSP session over build code needs before it can answer anything.

The controller resolves a workspace's members from a BuildInput — that is how it learns which members exist, where their .bldr/ sources are, and what paths map their imports resolve through. A build carries one; an editor session does not, so the node supplies the workspace's current input here.

It is not a build. Nothing is executed, no pods start: the input is used only to index the build code the language service then answers about. When the workspace changes on disk the node syncs a new input and sends a fresh header, which is what keeps an editing session current.

message ControllerLspHeader {
  optional string input_cid = 1;
}

PrepareInput

Call a node's input mapper with the outputs of its dependencies.

message PrepareInput {
  optional uint64 call_id = 1;
  optional string node_id = 2;
  optional uint64 mapper_id = 3;
  optional map<string, string> dependency_outputs = 4;
}

ControllerGraph

A set of nodes declared together, and the targets that point at them.

message ControllerGraph {
  repeated GraphNode nodes = 1;
  repeated GraphTarget targets = 2;
}

GraphNode

One declared node: everything about it except its input.

message GraphNode {
  optional string id = 1;
  optional string function = 2;
  optional string label = 3;
  optional map<string, string> labels = 4;
  repeated string dependencies = 5;
  oneof input {
    uint64 mapper_id = 6;
    ConstantBlock constant_input = 7;
  }
  oneof _target_prefix {
    string target_prefix = 8;
  }
}

ConstantBlock

A block the controller authored, for the node to store: a JSON value in the form of InputPrepared, and the type to mint its CID with (a DataType label such as "deployment"; empty for generic DAG-CBOR).

message ConstantBlock {
  optional string json = 1;
  optional string data_type = 2;
}

GraphTarget

A named pointer at a node.

message GraphTarget {
  optional BuildTarget target = 1;
  optional string select = 3;
  oneof artifact {
    string node_id = 2;
    ConstantBlock constant = 4;
  }
}

InputPrepared

What an input mapper produced.

message InputPrepared {
  optional uint64 call_id = 1;
  oneof result {
    string input_json = 2;
    ControllerSubgraph subgraph = 3;
    string error = 4;
  }
}

ControllerSubgraph

The subgraph an execute-graph node's mapper returned.

message ControllerSubgraph {
  optional ControllerGraph graph = 1;
  optional string result_node_id = 2;
}

ControllerTaskState

enum ControllerTaskState {
  CONTROLLER_TASK_RUNNING = 0;
  CONTROLLER_TASK_COMPLETED = 1;
  CONTROLLER_TASK_FAILED = 2;
  CONTROLLER_TASK_QUEUED = 3;
  CONTROLLER_TASK_CANCELLED = 4;
  CONTROLLER_TASK_WAITING = 5;
  CONTROLLER_TASK_WAITING_FOR_RESOURCES = 6;
}

TargetListStatus

How much to trust the target list.

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 is run for its verdict, a runnable is 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;
}

DiagnosticLevel

Mirrors builder.DiagnosticLevel, numerically identical so the node's translation is a copy and never a lookup table that can drift.

enum DiagnosticLevel {
  DIAGNOSTIC_LEVEL_UNSPECIFIED = 0;
  DIAGNOSTIC_LEVEL_ERROR = 1;
  DIAGNOSTIC_LEVEL_WARNING = 2;
  DIAGNOSTIC_LEVEL_INFO = 3;
}