MESH ONLINE│CODENAME: Start Me Up
v0.47

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.

▸ 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

▸ go
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 one

Fetch / 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

▸ go
// 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

▸ go
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 parity

A 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:

▸ go
_ = 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

▸ go
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.

§ parity · Dataforts — blobsfrom the capability record
Rust supportedNode / TS supportedPython supportedGo supportedC supported