Move Artifacts
The bus is a coordination layer, not a file transfer. When work produces something large — a model checkpoint, a video frame, a directory tree — you move it as a content-addressed blob and put only a small reference on the bus.
Reference, don't embed
The event carries a BlobRef; the bytes travel separately, on demand, to whoever
actually needs them. An event that carries the payload has turned a coordination
message into a transfer, and every subscriber pays for it whether they wanted the
bytes or not.
The address is the content
Blobs are addressed by their BLAKE3 hash. The address is the content, which has consequences worth stating rather than deriving:
- There is no canonical home to provision. Blobs live on whichever nodes have capacity and drift toward the nodes that read them.
- A reference is verifiable. Bytes that hash to the reference are the right bytes, from whichever peer served them.
- Identical content is one blob. Storing the same bytes twice does not double the storage.
Three guarantees the transfer path makes
Peak memory is one chunk (~4 MiB), regardless of total size. A blob larger than RAM transfers fine; the transfer is streamed, not buffered.
A directory fetch is all-or-nothing. It either becomes the complete tree or leaves the destination untouched. There is no partially-materialized state to clean up.
A producer reading back its own write never sees a gap. The write path returns a token the read path waits on — read-your-own-writes, so the common write-then-immediately-read sequence is not a race.
Serving must be installed before fetching
A node cannot serve chunks, and in most bindings cannot issue fetches, until blob transfer has been installed on it with a storage adapter. This is one call and it is easy to omit, because omitting it produces a fetch that fails to find a holder rather than an error naming the missing install.
Bridged tools have no artifacts
Artifacts are a native capability. Tools brought in through the
MCP bridge are mcp_bridge tier —
request/response only, no artifacts. If the work needs to move bytes, it has to be
a native capability, not a wrapped one. This is a tier boundary, not a limitation
to route around.
Where the full surface lives
This page is the entry point per binding. The storage and gravity model, the
adapter configuration, overflow behaviour and the operator CLI
(net-mesh transfer send-blob / recv-blob / send-dir / recv-dir) are in
Blob Storage (Dataforts) and the
CLI Reference.
Move it — Go
The transfer verbs are methods on the node (*net.MeshNode) and the adapter
(*net.MeshBlobAdapter), in the module github.com/ai-2070/net/go.
redex := net.NewRedex("")
defer redex.Free()
adapter, err := net.NewMeshBlobAdapter(redex, "my-node", nil)
if err != nil {
log.Fatal(err)
}
defer adapter.Close()
// Both ends install the transfer engine: a fetch needs it as much as a serve.
if err := node.ServeBlobTransfer(adapter); err != nil {
log.Fatal(err)
}The adapter is feature-gated on dataforts,netdb,redex-disk. Built without
them, the constructor returns ErrBlob and the transfer calls return
ErrFeatureNotBuilt.
Publish, then move by reference
ref, err := adapter.Publish("mesh://frames/abc123", data) // stores + mints the BlobRef
hash, err := net.BlobRefHash(ref) // the 32-byte address
// On the other peer:
got, err := node.FetchBlob(holderID, hash[:]) // from a known holder
got, err = node.FetchBlobDiscovered(hash[:]) // or let the mesh find oneFetch / Exists on the adapter are local: they read this node's own
store and never go looking. FetchBlob and FetchBlobDiscovered are the
cross-peer path, and both verify the bytes against the hash.
Whole directories
// On the holder:
manifestRef, err := adapter.StoreDir("/data/model-v3")
// On the receiver:
stats, err := node.FetchDir(holderID, manifestRef, "/srv/model-v3")
// Inspect without copying:
manifest, err := node.DirManifestRead(holderID, manifestRef)FetchDir installs the tree atomically and refuses paths that escape the
destination (ErrDirPathInvalid). A manifest the holder doesn't have is
ErrTransferNotFound; bytes that aren't a manifest are ErrDirInvalidManifest.
Large blobs: trees, erasure coding, ranges
ref, err := adapter.StoreTree(data, net.EncodingReedSolomon(4, 2))
part, err := adapter.FetchRange(ref, 0, 1<<20) // first MiB; Fetch refuses a tree ref
report, err := adapter.RepairBlob(ref) // rebuild lost data shards from parityA Reed-Solomon stripe only gets parity once k full chunks have arrived (4 MiB
each by default), so a blob smaller than k chunks is stored replicated.
RepairBlob returning nil does not mean the blob is whole: check
report.StripesUnrecoverable.
Reference, don't embed
Put the BlobRef in the event, not the bytes:
_ = bus.Ingest(map[string]any{"frame_id": "abc123", "blob": ref})Putting the bytes in an event converts a coordination message into a broadcast transfer for every subscriber, which is the failure mode this page exists to prevent.
Verify it worked
got, err := node.FetchBlobDiscovered(hash[:])
if err != nil {
log.Fatal(err)
}
if !bytes.Equal(got, data) {
log.Fatal("fetched bytes differ") // unreachable: the fetch verifies the hash
}
fmt.Println("fetched:", len(got), "bytes")A blob store written in Go goes into the process-wide registry with
net.RegisterBlobAdapter(id, a), where a implements net.BlobAdapter
(Store, Fetch, FetchRange, Exists). Methods run on substrate threads
and may overlap, so the adapter must be safe for concurrent use; return
net.ErrBlobNotFound for content it does not hold. net.UnregisterBlobAdapter(id)
removes it, and a call already in flight still completes against it. For a
plain directory, RegisterFilesystemBlobAdapter needs no Go code.
Next: Errors and recovery.