Artifacts and CIDs

Everything bldr stores is addressed by the hash of its content. That address is a CID, and it is the reason the rest of the system behaves the way it does.

What follows from it

Identical inputs share one object. Two members that produce the same bytes produce the same CID and occupy one place in the store. Nothing deduplicates afterwards; there was only ever one.

The cache is exact. "Have we built this" is a lookup, not an estimate. There is no invalidation to tune, because nothing can change underneath a CID: different content is a different address.

A build is traceable. What you deployed has an address, and that address was produced by inputs with their own addresses. You can ask what went in.

What you handle

In build code you rarely touch a CID directly. You handle typed handles:

These are lazy. Building a Directory describes work rather than doing it; the work happens when something forces it. That is why a build can declare far more than it produces: describing a target costs nothing until it is selected.

Seeing them

bldr inspect <CID>       # what kind of thing it is, and what it points at
bldr fs ls <CID>         # a tree's contents
bldr blob get <CID>      # a file's bytes
bldr ref set name <CID>  # give it a name
bldr ref list

bldr inspect is the one to reach for first: it detects the kind and prints a typed summary, with child CIDs you can drill into.