Data

Content-addressed data: GC, named refs, single-block blob/IPLD get/put, recursive network fetch, and filesystem-tree import/export.

Service builder.Data, 18 rpcs.

Gc(GcRequest) -> stream GcEvent

Run a garbage-collection pass, streaming live mark/sweep progress. The final message is a done event carrying the totals (GcResponse).

Request: GcRequest

message GcRequest {
  // no fields
}

Response: GcEvent

One message on the Data.Gc stream: incremental progress, then a terminal done with the final totals.

message GcEvent {
  oneof event {
    GcProgress progress = 1;
    GcResponse done = 2;
  }
}

ScanStorageUsage(ScanStorageUsageRequest) -> stream StorageUsageEvent

Scan the block store and report what holds its bytes: a read-only mark pass from every GC root, with no sweep. Streams live progress; the final message is a done event carrying the report (StorageUsage). Scans may run side by side, but never alongside a GC sweep or a compaction, which hold the engine's rewrite lock exclusively.

Request: ScanStorageUsageRequest

message ScanStorageUsageRequest {
  optional uint32 top_roots = 1;
}

Field
`top_roots`	How many of the largest roots to list in `StorageUsage.top_roots`. 0 → 20.

Response: StorageUsageEvent

One message on the Data.ScanStorageUsage stream: incremental progress, then a terminal done with the report.

message StorageUsageEvent {
  oneof event {
    StorageUsageProgress progress = 1;
    StorageUsage done = 2;
  }
}

GetRef(GetRefRequest) -> GetRefResponse

Request: GetRefRequest

message GetRefRequest {
  optional string name = 1;
}

Response: GetRefResponse

message GetRefResponse {
  optional bool found = 1;
  optional string cid = 2;
}

Field
`found`
`cid`	Set when found = true.

ListRefs(ListRefsRequest) -> ListRefsResponse

Request: ListRefsRequest

message ListRefsRequest {
  optional string data_type = 1;
  optional string name_prefix = 2;
}

Field
`data_type`	Only refs whose CID carries this data type, named by the label `bldr inspect` prints (`deployment`, `runnable`, `fs-node`, …). Empty → every type. An unrecognised label is an error rather than an empty list: a typo that silently matches nothing looks exactly like "you have none".
`name_prefix`	Only refs whose name starts with this. Empty → every name.

Response: ListRefsResponse

message ListRefsResponse {
  repeated RefInfo refs = 1;
}

SetRef(SetRefRequest) -> SetRefResponse

Request: SetRefRequest

SetRef covers both create and update; the condition selects which semantics.

message SetRefRequest {
  optional string name = 1;
  optional RefCondition condition = 2;
  optional string expected_cid = 3;
  optional string cid = 4;
}

Field
`name`
`condition`
`expected_cid`	For condition = IF_EQUALS: the expected current CID.
`cid`	The new CID to store.

Response: SetRefResponse

message SetRefResponse {
  optional bool applied = 1;
  optional string previous_cid = 2;
}

Field
`applied`	true if the condition was satisfied and the ref was updated.
`previous_cid`	The CID held by the ref before this call (empty if none).

DeleteRef(DeleteRefRequest) -> DeleteRefResponse

Request: DeleteRefRequest

message DeleteRefRequest {
  optional string name = 1;
  optional RefCondition condition = 2;
  optional string expected_cid = 3;
}

Field
`name`
`condition`
`expected_cid`	For condition = IF_EQUALS: the expected current CID.

Response: DeleteRefResponse

message DeleteRefResponse {
  optional bool applied = 1;
  optional string previous_cid = 2;
}

StatBlob(StatBlobRequest) -> StatBlobResponse

Return the total byte size of a Blob DAG without assembling the content.

Only the root Blob CBOR node is read — each part carries its size inline, so no chunk blocks need to be fetched. was_local in the response is true when the root block was already in local storage before this call.

local = true: fail with NOT_FOUND if the root block is absent locally. local = false: fetch the root block from the network on a cache miss.

Request: StatBlobRequest

message StatBlobRequest {
  optional string cid = 1;
  optional bool local = 2;
}

Response: StatBlobResponse

message StatBlobResponse {
  optional string cid = 1;
  optional uint64 size = 2;
  optional bool was_local = 3;
}

Field
`cid`
`size`
`was_local`	true if the root Blob block was already in local storage before this call.

GetBlob(GetBlobRequest) -> stream GetBlobResponse

Stream the byte content of a Blob DAG, with optional range selection.

The response stream carries three kinds of messages (always in this order):

A single header message with the CID and total byte count for the requested range (use it to set up a progress bar or pre-allocate).
One or more chunk messages carrying the raw bytes.
A single stats message with the number of blocks fetched from peers.

offset / until select a byte range [offset, until). Both are optional; defaults are 0 and the blob's total size respectively.

local = true: root block must be local; chunk blocks also local-only. Returns NOT_FOUND for any missing block. local = false (default): fetch missing blocks from the peer network.

Request: GetBlobRequest

message GetBlobRequest {
  optional string cid = 1;
  optional bool local = 2;
  oneof _offset {
    uint64 offset = 3;
  }
  oneof _until {
    uint64 until = 4;
  }
}

Field
`cid`
`local`
`offset`	first byte to stream (default: 0)
`until`	exclusive end byte (default: blob size)

Response: GetBlobResponse

message GetBlobResponse {
  oneof payload {
    GetBlobHeader header = 1;
    bytes chunk = 2;
    GetBlobStats stats = 3;
  }
}

GetIpld(GetIpldRequest) -> GetIpldResponse

Fetch a single DAG-CBOR block and return it as a YAML string.

cid is a CID or named ref. The YAML encoding uses tagged scalars: CID links → !cid <cid-string> Byte strings → !base64 <base64-string>

local = true: local store only; NOT_FOUND if absent.

Request: GetIpldRequest

message GetIpldRequest {
  optional string cid = 1;
  optional bool local = 2;
}

Response: GetIpldResponse

message GetIpldResponse {
  optional string yaml = 1;
  optional string cid = 2;
  optional string json = 3;
}

Field
`yaml`
`cid`
`json`	The same value as JSON with dag-json-style markers (links `{"/": cid}`, bytes `{"/": {"bytes": [...]}}`) — what the build controller's TS bridge consumes, so JS callers never parse YAML.

InspectObject(InspectObjectRequest) -> InspectObjectResponse

Inspect a CID: detect its kind (raw Blob, FsNode, ContainerImage, or generic DAG-CBOR) and return a typed, UI-friendly view plus the raw IPLD (as YAML) for DAG-CBOR objects. Drives a "clickable CID / object browser": child CIDs (dir entries, image layers) are returned so a UI can descend.

Request: InspectObjectRequest

message InspectObjectRequest {
  optional string cid = 1;
  optional bool local = 2;
}

Field
`cid`
`local`	Restrict to the local store (no network).

Response: InspectObjectResponse

message InspectObjectResponse {
  optional string cid = 1;
  optional ObjectKind kind = 2;
  optional string codec = 3;
  optional uint64 size = 4;
  optional string yaml = 5;
  optional BlobView blob = 6;
  optional FsNodeView fs = 7;
  optional ContainerImageView image = 8;
  optional BuildOutputView build_output = 9;
  optional DeploymentView deployment = 10;
  optional BuildInputView build_input = 11;
  optional HamtView hamt = 12;
  optional BuildMemberView build_member = 13;
  optional RunnableView runnable = 14;
  optional ImageIndexView image_index = 15;
  optional TestResultsView test_results = 16;
  optional CoverageReportView coverage_report = 17;
  optional CoverageMemberView coverage_member = 18;
  optional DiagnosticsView diagnostics = 19;
  optional PipelineView pipeline = 20;
}

Field
`cid`
`kind`
`codec`	Block encoding, derived from the CID's data type: "raw" (opaque bytes) or "dag-cbor" (structured). Kept under the historical field name.
`size`	Size of the root block in bytes.
`yaml`	Raw IPLD serialised as tagged YAML (DAG-CBOR objects only) — the "view raw" payload. Empty for raw blobs.
`blob`	Exactly one typed view is set, matching `kind`.
`fs`
`image`
`build_output`
`deployment`
`build_input`
`hamt`
`build_member`
`runnable`
`image_index`
`test_results`
`coverage_report`
`coverage_member`
`diagnostics`
`pipeline`

InspectRevisionSnapshot(InspectRevisionSnapshotRequest) -> InspectRevisionSnapshotResponse

Decode a WorkspaceRevisionSnapshot block (a committed workspace revision: pinned members + absolute options) into a UI-friendly view. Distinct from InspectObject because a snapshot is byte-identical to a BuildInput and can't be told apart by shape — the caller asserts the type (e.g. following a workspace's revision/parent CID).

Request: InspectRevisionSnapshotRequest

message InspectRevisionSnapshotRequest {
  optional string cid = 1;
  optional bool local = 2;
}

Field
`cid`
`local`	Restrict to the local store (no network).

Response: InspectRevisionSnapshotResponse

A committed WorkspaceRevisionSnapshot, decoded for display.

message InspectRevisionSnapshotResponse {
  repeated SnapshotMember members = 1;
  optional string options_json = 2;
}

Field
`members`
`options_json`	The snapshot's absolute workspace options, as a JSON object.

ValidateCidKind(ValidateCidKindRequest) -> ValidateCidKindResponse

Guess a CID's ObjectKind without building the full typed view — a cheap shape probe the UI delegates to (e.g. /deploy validating a Deployment CID, the object browser) instead of guessing client-side.

Request: ValidateCidKindRequest

message ValidateCidKindRequest {
  optional string cid = 1;
  optional bool local = 2;
}

Response: ValidateCidKindResponse

message ValidateCidKindResponse {
  optional ObjectKind kind = 1;
  optional bool ok = 2;
}

Field
`kind`	UNSPECIFIED if the CID could not be parsed or the block is unavailable.
`ok`	False when the CID string was malformed or the block wasn't found.

PutBlob(stream PutBlobRequest) -> PutBlobResponse

Split streamed bytes into content-addressed chunks (FastCDC) and store the resulting Blob DAG. Returns the CID of the root Blob CBOR node.

The client streams one or more messages; each carries a contiguous slice of the payload. The server reassembles, chunks with FastCDC, and stores all leaf blocks before returning. blocks_stored counts newly written blocks (already-present blocks are not re-stored and not counted).

Request: PutBlobRequest

message PutBlobRequest {
  optional bytes data = 1;
}

Response: PutBlobResponse

message PutBlobResponse {
  optional string cid = 1;
  optional uint64 blocks_stored = 2;
}

PutIpld(PutIpldRequest) -> PutIpldResponse

Parse yaml as an IPLD value, encode as DAG-CBOR, store, and return the CID. The input follows the same tagged YAML encoding as GetIpldResponse.

Request: PutIpldRequest

message PutIpldRequest {
  optional string yaml = 1;
  optional string json = 2;
  optional string data_type = 3;
}

Field
`yaml`
`json`	Alternative JSON form (same markers as GetIpldResponse.json). When both are set, `json` wins; the TS bridge sends only this.
`data_type`	The type to mint the CID with, by its label — what `bldr inspect` prints: `pipeline`, `test-results`, `build-output`, … Empty stores generic `dag-cbor`. Only structured DAG-CBOR types are accepted: a blob or an FS-model type has its own encoding and its own RPC, and an unknown label is INVALID_ARGUMENT rather than a block nobody can decode.

Response: PutIpldResponse

message PutIpldResponse {
  optional string cid = 1;
}

Fetch(FetchRequest) -> FetchResponse

Recursively download every block in the DAG rooted at cid from peers.

Blocks already present locally are not re-fetched. blocks_stored counts only newly written blocks. After a successful Fetch an FsNode tree is ready for FUSE mounting; a Blob DAG is ready for GetBlob assembly.

local = true: skip the network and verify local completeness only; returns NOT_FOUND for any missing block.

Request: FetchRequest

message FetchRequest {
  optional string cid = 1;
  optional bool local = 2;
}

Response: FetchResponse

message FetchResponse {
  optional string cid = 1;
  optional uint64 blocks_stored = 2;
}

FetchIpld(FetchRequest) -> FetchIpldResponse

Like Fetch, but also decodes the root block as YAML on completion — saves a separate GetIpld round-trip.

Request: FetchRequest

The same message as FetchRequest.

Response: FetchIpldResponse

message FetchIpldResponse {
  optional string cid = 1;
  optional uint64 blocks_stored = 2;
  optional string yaml = 3;
}

PutFs(PutFsRequest) -> PutFsResponse

Walk a path on the server filesystem, store the tree as an FsNode DAG, and return the root CID.

The server must have access to path; it is an absolute path on the machine where builder-node is running. All file content is chunked and stored as Blob DAGs; directory trees become HAMT MapNodes.

Request: PutFsRequest

message PutFsRequest {
  optional string path = 1;
}

Field
`path`	Absolute path on the server filesystem to import.

Response: PutFsResponse

message PutFsResponse {
  optional string cid = 1;
}

Field
`cid`	CID of the root FsNode.

GetFs(GetFsRequest) -> GetFsResponse

Materialise an FsNode DAG rooted at cid to path on the server filesystem.

If the blocks are not already stored locally and local is false, the node will fetch them from the peer network before materialising. When local is true, materialisation fails with NOT_FOUND if any block is missing locally. path is an absolute path on the server machine.

Request: GetFsRequest

message GetFsRequest {
  optional string cid = 1;
  optional string path = 2;
  optional bool local = 3;
}

Field
`cid`	CID or named ref of the root FsNode to materialise.
`path`	Absolute destination path on the server filesystem.
`local`	Restrict to local blocks only; do not contact the network.

Response: GetFsResponse

message GetFsResponse {
  optional string cid = 1;
}

Field
`cid`	CID of the materialised root (same as the request CID).

Types used above

GcProgress

Live progress of a GC pass, streamed by Data.Gc.

message GcProgress {
  optional uint64 refs_marked = 1;
  optional uint64 refs_total = 2;
  optional bool mark_complete = 3;
  optional uint64 shards_done = 4;
  optional uint64 shards_total = 5;
  optional uint64 blocks_kept = 6;
  optional uint64 blocks_removed = 7;
  optional bool sweep_complete = 8;
}

Field
`refs_marked`	Mark phase: how many root refs have been marked out of the total. `refs_total` can grow mid-pass as the live set expands (new pins). `mark_complete` flips true once every root has been marked and the sweep begins.
`refs_total`
`mark_complete`
`shards_done`	Sweep phase: shards processed out of the total (block store is sharded; `shards_total` is 1 for the unsharded engine), and the running counts of blocks kept / removed so far. `sweep_complete` flips true when done.
`shards_total`
`blocks_kept`
`blocks_removed`
`sweep_complete`

GcResponse

message GcResponse {
  optional uint64 removed = 1;
  optional uint64 retained = 2;
  optional uint64 cache_removed = 3;
  optional uint64 cache_kept = 4;
  optional uint64 cache_scanned = 5;
}

Field
`removed`
`retained`
`cache_removed`	Function-invocation cache GC pass (run before the block-store sweep).
`cache_kept`	unexpired cache entries kept
`cache_scanned`	total cache trie nodes scanned

StorageUsageProgress

Live progress of a scan.

message StorageUsageProgress {
  optional uint64 roots_marked = 1;
  optional uint64 roots_total = 2;
  optional uint64 blocks_marked = 3;
  optional bool counting_unreachable = 4;
}

Field
`roots_marked`	Roots submitted to the mark phase out of the total known so far.
`roots_total`
`blocks_marked`	Blocks reached so far.
`counting_unreachable`	True once marking is done and the scan is counting what nothing reached.

StorageUsage

message StorageUsage {
  optional StorageAmount total = 1;
  optional StorageAmount reachable = 2;
  optional StorageAmount unreachable = 3;
  repeated StorageUsageByClasses by_classes = 4;
  repeated StorageUsageByDataType by_data_type = 5;
  repeated StorageUsageGroup groups = 6;
  repeated StorageUsageRoot top_roots = 7;
  optional uint64 duration_ms = 8;
}

Field
`total`	every block in the store
`reachable`
`unreachable`	what the next GC would reclaim
`by_classes`	largest first
`by_data_type`	largest first
`groups`	largest first
`top_roots`	largest first
`duration_ms`

StorageAmount

message StorageAmount {
  optional uint64 blocks = 1;
  optional uint64 bytes = 2;
}

StorageUsageByClasses

Blocks held by exactly this set of classes and no other. The rows partition the reachable set, so they sum to StorageUsage.reachable.

message StorageUsageByClasses {
  repeated StorageRootClass classes = 1;
  optional StorageAmount amount = 2;
}

Field
`classes`	sorted, never empty
`amount`

StorageUsageByDataType

message StorageUsageByDataType {
  optional string data_type = 1;
  optional StorageAmount reachable = 2;
  optional StorageAmount unreachable = 3;
}

Field
`data_type`	the `DataType` label: blob, fs-node, dag-cbor, …
`reachable`
`unreachable`

StorageUsageGroup

Roots of one class sharing a label, e.g. every cached output of pod.dag/v0.0.0. charged is first-reach attribution: each reachable block is charged to exactly one root, the earliest in a fixed order (classes in enum order, roots in a stable order within a class), so the groups sum to the reachable set and a group's charge is what it holds that nothing earlier does. A block pinned after the scan read its roots is counted in the LIVE_PIN group with an empty label, charged to no root.

message StorageUsageGroup {
  optional StorageRootClass class = 1;
  optional string label = 2;
  optional uint64 roots = 3;
  optional StorageAmount charged = 4;
}

StorageUsageRoot

message StorageUsageRoot {
  optional StorageRootClass class = 1;
  optional string label = 2;
  optional string cid = 3;
  optional StorageAmount charged = 4;
}

RefInfo

message RefInfo {
  optional string name = 1;
  optional string cid = 2;
  optional string data_type = 3;
}

Field
`name`
`cid`
`data_type`	What the CID says it holds, as the label `bldr inspect` prints (`deployment`, `runnable`, `fs-node`, …); `dag-cbor` when it claims nothing in particular.

GetBlobHeader

message GetBlobHeader {
  optional string cid = 1;
  optional uint64 size = 2;
}

Field
`cid`
`size`	total bytes in the requested range

GetBlobStats

message GetBlobStats {
  optional uint64 blocks_fetched = 1;
}

BlobView

message BlobView {
  optional uint64 size = 1;
  optional bool is_text = 2;
  optional string preview = 3;
  optional bool truncated = 4;
}

Field
`size`
`is_text`	Whether the sampled bytes decode as UTF-8 text.
`preview`	First bytes of the blob (UTF-8), truncated. Empty for binary.
`truncated`	True if the blob is larger than the sampled preview.

FsNodeView

message FsNodeView {
  optional string node_kind = 1;
  optional uint32 mode = 2;
  optional uint32 uid = 3;
  optional uint32 gid = 4;
  optional uint64 size = 5;
  optional string symlink_target = 6;
  optional string preview = 7;
  optional bool preview_truncated = 8;
  repeated FsEntry entries = 9;
  optional bool entries_truncated = 10;
}

Field
`node_kind`	"directory" \| "file" \| "symlink" \| "fifo" \| "char-device" \| "block-device" \| "socket" \| "wipeout".
`mode`
`uid`
`gid`
`size`	For a file: content size in bytes.
`symlink_target`	For a symlink: the target path.
`preview`	For a file that is UTF-8 text: a truncated preview.
`preview_truncated`
`entries`	For a directory: its immediate entries (each child CID is clickable).
`entries_truncated`	True if `entries` was capped (very large directory).

FsEntry

message FsEntry {
  optional string name = 1;
  optional string kind = 2;
  optional uint32 mode = 3;
  optional uint64 size = 4;
  optional string cid = 5;
}

Field
`name`
`kind`	Same vocabulary as FsNodeView.node_kind.
`mode`
`size`
`cid`	CID of the child FsNode (open it with InspectObject).

ContainerImageView

message ContainerImageView {
  optional string architecture = 1;
  optional string os = 2;
  repeated string env = 3;
  repeated string entrypoint = 4;
  repeated string cmd = 5;
  optional string working_dir = 6;
  optional string user = 7;
  repeated string labels = 8;
  repeated ImageLayer layers = 9;
}

Field
`architecture`
`os`
`env`
`entrypoint`
`cmd`
`working_dir`
`user`
`labels`	"key=value" pairs.
`layers`

ImageLayer

message ImageLayer {
  optional string media_type = 1;
  optional uint64 size = 2;
  optional string cid = 3;
  optional string digest = 4;
}

Field
`media_type`
`size`
`cid`	CID of the layer content (a Blob or FsNode), when known — clickable.
`digest`	OCI digest string (e.g. sha256:...), for reference.

BuildOutputView

A BuildOutput: named output directories, deployments, runnables, and test targets — each a name → CID link.

message BuildOutputView {
  repeated NamedCid outputs = 1;
  repeated NamedCid deployments = 2;
  repeated NamedCid runnables = 3;
  repeated NamedCid tests = 4;
}

NamedCid

A name → CID link entry (a BuildOutput's outputs / deployments).

message NamedCid {
  optional string name = 1;
  optional string cid = 2;
  optional string kind = 3;
  optional map<string, string> labels = 4;
}

Field
`name`
`cid`
`kind`	What the CID is, for a build output: "fsnode" (a directory — the default, and what's used for deployments/runnables/tests), "container_image", or "image_index". Lets a client show/handle an image output differently from a filesystem tree.
`labels`	The output's labels, when it carries any (a BuildOutput's `output_labels`): opaque key/value pairs the controller attached to say what the tree is for, so a client can present such outputs differently without fetching them. Empty for an unlabelled output (the common case) and for deployments/runnables/tests.

DeploymentView

A standalone Deployment block: a node function + its options.

message DeploymentView {
  optional string function = 1;
  optional string options_yaml = 2;
  optional map<string, string> labels = 3;
}

Field
`function`
`options_yaml`	The options block rendered as tagged YAML (CIDs linkified by the client).
`labels`	Default labels declared with the deployment (e.g. bldr.deployment.name).

BuildInputView

A build's BuildInput: workspace members (name → content CID) + options.

message BuildInputView {
  repeated NamedCid members = 1;
  optional string options_yaml = 2;
}

Field
`members`	Inline member entries (name → member content CID). Members stored in a deeper HAMT shard appear as `hamt` links the client can drill into.
`options_yaml`

HamtView

message HamtView {
  repeated HamtEntry entries = 1;
}

HamtEntry

A HAMT (sharded map) node: each slot is either a key→value leaf or a link to a child shard node.

message HamtEntry {
  optional string key = 1;
  optional string cid = 2;
  optional bool is_subtrie = 3;
}

Field
`key`	empty for a sub-trie link
`cid`	value CID (leaf) or child-node CID (sub-trie)
`is_subtrie`

BuildMemberView

A BuildMember: a workspace member as stored in a BuildInput — a link to the member's content, the kind of content it points at, and its config options.

message BuildMemberView {
  optional string content_cid = 1;
  optional string kind = 2;
  optional map<string, string> metadata = 3;
}

Field
`content_cid`
`kind`	"directory" \| "container-image" \| "dag" \| "other".
`metadata`	Per-member options (`members.<name>.options` in the workspace config).

RunnableView

A standalone Runnable block: bridge networks + long-lived services, the docker-compose-equivalent launched by bldr run.

message RunnableView {
  repeated RunnableNetworkView networks = 1;
  repeated RunnableServiceView services = 2;
}

RunnableNetworkView

message RunnableNetworkView {
  optional string name = 1;
  optional string subnet = 2;
  optional bool internet_access = 3;
}

Field
`name`
`subnet`	empty → auto-assigned
`internet_access`

RunnableServiceView

message RunnableServiceView {
  optional string name = 1;
  optional string image_cid = 2;
  repeated string command = 3;
  optional map<string, string> env = 4;
  optional string hostname = 5;
  optional string network = 6;
  repeated RunnableMountView mounts = 7;
  repeated RunnablePortView ports = 8;
  repeated string depends_on = 9;
  optional bool internet_access = 10;
}

RunnableMountView

message RunnableMountView {
  optional string source_cid = 1;
  optional string dest = 2;
  optional bool hotswap = 3;
  optional bool mutable = 4;
}

RunnablePortView

message RunnablePortView {
  optional uint32 host_port = 1;
  optional uint32 pod_port = 2;
  optional bool udp = 3;
}

ImageIndexView

A multi-arch OCI image index: a set of per-platform image manifests. Distinct from a single-platform ContainerImage (which has layers + a config).

message ImageIndexView {
  optional string media_type = 1;
  optional string digest = 2;
  repeated ImageIndexEntry manifests = 3;
}

ImageIndexEntry

message ImageIndexEntry {
  optional string os = 1;
  optional string architecture = 2;
  optional string variant = 3;
  optional string manifest_cid = 4;
  optional string digest = 5;
  optional uint64 size = 6;
  optional string media_type = 7;
}

Field
`os`
`architecture`
`variant`	e.g. "v7" for arm/v7; empty if none
`manifest_cid`	The stored per-platform manifest block CID (drill into it), if linked.
`digest`
`size`
`media_type`

TestResultsView

A TestResults block: a build test target's cases. Counts and the pass verdict are derived from cases by the client. Pageable on the wire — one response holds this block's cases; more_results_cid links the next page (fetched separately).

message TestResultsView {
  repeated TestCaseView cases = 1;
  optional string more_results_cid = 2;
}

Field
`cases`	this page's cases
`more_results_cid`	next page's CID, empty on the last page

CoverageReportView

A CoverageReport root: what one coverage run proved. members mirrors the stored block, which holds the whole index inline (a workspace has tens of members) — so no cap and no paging here.

message CoverageReportView {
  optional string tool = 1;
  optional CoverageSummaryView summary = 2;
  repeated CoverageMemberEntryView members = 3;
  optional string more_members_cid = 4;
  optional string generated_cid = 5;
  optional string external_cid = 6;
}

Field
`tool`	What produced the data, e.g. `cargo-llvm-cov`. Explains where the numbers came from; never something to branch on.
`summary`
`members`
`more_members_cid`	Next page of the member index, empty on the last page. Populated only by a report too wide for one block; `summary` already covers the whole run.
`generated_cid`	The CoverageMember holding files that belong to no member (generated code); empty when the run produced none.
`external_cid`	The CoverageMember holding files from outside the workspace entirely (an instrumented dependency); empty when the run kept none.

CoverageSummaryView

The counters of one coverage summary, a pair per granularity (see bldr-types' CoverageSummary). A tool with no notion of a granularity reports 0/0 there; a consumer renders that pair as "not measured", never as 0%.

message CoverageSummaryView {
  optional uint64 lines_total = 1;
  optional uint64 lines_covered = 2;
  optional uint64 functions_total = 3;
  optional uint64 functions_covered = 4;
  optional uint64 regions_total = 5;
  optional uint64 regions_covered = 6;
  optional uint64 branches_total = 7;
  optional uint64 branches_covered = 8;
}

CoverageMemberEntryView

One row of a CoverageReport's member index.

message CoverageMemberEntryView {
  optional string name = 1;
  optional CoverageSummaryView summary = 2;
  optional string detail_cid = 3;
}

Field
`name`
`summary`
`detail_cid`	The member's own CoverageMember block, holding its file index.

CoverageMemberView

One member's coverage: its totals and where its file index lives.

message CoverageMemberView {
  optional string name = 1;
  optional CoverageSummaryView summary = 2;
  optional string files_cid = 3;
  optional uint64 file_count = 4;
}

Field
`name`
`summary`
`files_cid`	The files HAMT root (path-in-member → per-file entry); empty for a member with no covered files.
`file_count`	How many entries `files` holds — stored on the block because the HAMT can only answer by walking.

DiagnosticsView

A Diagnostics block: this page's findings. Counts are derived from diagnostics by the client — the TestResultsView convention, and the only honest option: one block cannot know its chain's total. member and target are empty on every entry, because a bare block carries neither a workspace nor the name of the build step that produced it.

message DiagnosticsView {
  repeated CodeDiagnostic diagnostics = 1;
  optional string more_diagnostics_cid = 2;
}

Field
`diagnostics`
`more_diagnostics_cid`	Next page's CID, empty on the last page (inspected separately).

PipelineView

A Pipeline block: a declarative pipeline definition authored by build code (scope.addPipelineTarget).

message PipelineView {
  optional string name = 1;
  optional string definition_json = 2;
}

Field

name

definition_json The whole definition, rendered as JSON with links in dag-json form ({"/": "<cid>"}). The block's shape is the contract — bldr-types/src/pipeline.rs, mirrored by the authoring API — and it is decoded before rendering, so this is always a validated definition, never arbitrary bytes. Carried as JSON rather than mirrored message by message so a grown definition never reworks this view: a consumer renders the fields it knows and shows the rest as data.

SnapshotMember

One member of a WorkspaceRevisionSnapshot (a pinned MemberRevision).

message SnapshotMember {
  optional string name = 1;
  optional string pin = 2;
  optional string kind = 3;
  optional TrackingInfo tracking = 4;
  optional map<string, string> options = 5;
}

Field
`name`
`pin`	The pinned content CID (a DAG root). Always present in a snapshot.
`kind`	What the pinned content is (e.g. `directory`, `container-image`).
`tracking`	Upstream tracking, if the snapshot member carries any.
`options`	The member's absolute per-member options.

StorageRootClass

What keeps a block alive. A block can be held by several classes at once; StorageUsage.by_classes reports each combination separately.

enum StorageRootClass {
  STORAGE_ROOT_CLASS_UNSPECIFIED = 0;
  STORAGE_ROOT_CLASS_LIVE_PIN = 1;
  STORAGE_ROOT_CLASS_NAMED_REF = 2;
  STORAGE_ROOT_CLASS_PIN_ANCHOR = 3;
  STORAGE_ROOT_CLASS_CACHE_OUTPUT = 4;
  STORAGE_ROOT_CLASS_MAP_ENTRY = 5;
  STORAGE_ROOT_CLASS_CACHE_VOLUME = 6;
}

Value
`STORAGE_ROOT_CLASS_UNSPECIFIED`
`STORAGE_ROOT_CLASS_LIVE_PIN`	Pinned in memory by something in flight (a build, an import, a mount).
`STORAGE_ROOT_CLASS_NAMED_REF`	A named ref, local or cluster-wide. Label: the ref name (empty for a cluster ref, which is listed by CID alone).
`STORAGE_ROOT_CLASS_PIN_ANCHOR`	This node's distributed-pinning anchors. Label: empty.
`STORAGE_ROOT_CLASS_CACHE_OUTPUT`	A cached function-invocation output. Label: the function name; `(nested inputs)` for the nested-call inputs a cache frontier roots.
`STORAGE_ROOT_CLASS_MAP_ENTRY`	A CID-map entry. Label: the key's first path segment (`log`, …).
`STORAGE_ROOT_CLASS_CACHE_VOLUME`	A workspace cache volume. Label: the volume name.

RefCondition

Matches local_storage::SetRefCondition — controls the atomic precondition.

enum RefCondition {
  REF_CONDITION_UNSPECIFIED = 0;
  REF_CONDITION_IF_NOT_EXISTS = 1;
  REF_CONDITION_IF_EXISTS = 2;
  REF_CONDITION_IF_EQUALS = 3;
}

Value
`REF_CONDITION_UNSPECIFIED`	Default / unset — treated as unconditional by the server.
`REF_CONDITION_IF_NOT_EXISTS`	Apply only if the ref does not currently exist.
`REF_CONDITION_IF_EXISTS`	Apply only if the ref currently exists.
`REF_CONDITION_IF_EQUALS`	Apply only if the ref's current CID matches expected_cid.

ObjectKind

The detected high-level type of a block.

enum ObjectKind {
  OBJECT_KIND_UNSPECIFIED = 0;
  OBJECT_KIND_BLOB = 1;
  OBJECT_KIND_FS_NODE = 2;
  OBJECT_KIND_CONTAINER_IMAGE = 3;
  OBJECT_KIND_DAG_CBOR = 4;
  OBJECT_KIND_BUILD_OUTPUT = 5;
  OBJECT_KIND_DEPLOYMENT = 6;
  OBJECT_KIND_BUILD_INPUT = 7;
  OBJECT_KIND_HAMT = 8;
  OBJECT_KIND_BUILD_MEMBER = 9;
  OBJECT_KIND_RUNNABLE = 10;
  OBJECT_KIND_IMAGE_INDEX = 11;
  OBJECT_KIND_TEST_RESULTS = 12;
  OBJECT_KIND_COVERAGE_REPORT = 13;
  OBJECT_KIND_COVERAGE_MEMBER = 14;
  OBJECT_KIND_COVERAGE_FILE = 15;
  OBJECT_KIND_DIAGNOSTICS = 16;
  OBJECT_KIND_PIPELINE = 17;
}

Value
`OBJECT_KIND_UNSPECIFIED`
`OBJECT_KIND_BLOB`	opaque bytes (DataType::Blob)
`OBJECT_KIND_FS_NODE`	a filesystem tree node
`OBJECT_KIND_CONTAINER_IMAGE`	an OCI image manifest
`OBJECT_KIND_DAG_CBOR`	generic DAG-CBOR (no known shape)
`OBJECT_KIND_BUILD_OUTPUT`	a build's BuildOutput (outputs + deployments)
`OBJECT_KIND_DEPLOYMENT`	a Deployment block (function + options)
`OBJECT_KIND_BUILD_INPUT`	a build's BuildInput (members + options)
`OBJECT_KIND_HAMT`	a HAMT map node (sharded map)
`OBJECT_KIND_BUILD_MEMBER`	a BuildMember (member content link + kind)
`OBJECT_KIND_RUNNABLE`	a Runnable block (networks + services)
`OBJECT_KIND_IMAGE_INDEX`	a multi-arch OCI image index (per-platform manifests)
`OBJECT_KIND_TEST_RESULTS`	a TestResults block (test cases + pass/fail)
`OBJECT_KIND_COVERAGE_REPORT`	a CoverageReport root (run totals + member index)
`OBJECT_KIND_COVERAGE_MEMBER`	one member's coverage (totals + its file index)
`OBJECT_KIND_COVERAGE_FILE`	one file's per-line counts (paged); no typed view — the raw IPLD is the view
`OBJECT_KIND_DIAGNOSTICS`	a Diagnostics page (findings + link to the next page)
`OBJECT_KIND_PIPELINE`	a Pipeline definition, authored by build code

Data

On this page