Creel

The local rack of loaded bobbins — a content-addressed store keyed by BobbinHash.

A bobbin is an immutable kernel: opaque bytes (later a .wasm blob) that a peer fetches once and caches. The creel is the peer's local collection of those bytes, indexed by their content hash so that any fetch can be verified before use.

Content-addressing makes merge trivial. Because key = hash(bytes), any two peers that hold the same BobbinHash hold byte-identical bytes. The value lattice is the one-step Absent ⊏ Present: two stores are merged by taking the union of their keys — no conflict is possible. BobbinExchange is the gossip layer above: it advertises a GSet<BobbinMeta> manifest eagerly and fetches the bytes lazily; this class is the local byte-cache that sits beneath it.

A null result from get is legitimate. It means the bobbin has not been fetched yet — the ordinary "bobbin not loaded yet" state on the lazy-fetch path. It is not an invariant violation; callers must handle it as a real case (mirrors the OpRegistry.resolve → null contract).

Thread-safety. The backing map is guarded by an explicit kotlinx.atomicfu.locks.ReentrantLock; no suspend calls are made inside the lock. This type is correct under a multi-threaded dispatcher.

See also

Samples

val creel = Creel()

// Storing bytes yields their content address; storing them again is a no-op.
val kernel = byteArrayOf(0x00, 0x61, 0x73, 0x6d)
val hash: BobbinHash = creel.put(kernel)
check(creel.put(kernel) == hash)

// Bytes that arrived from a neighbour are re-hashed before being cached — a mismatch throws.
creel.putVerified(hash, kernel)
check(creel.contains(hash))
check(hash in creel.loaded)          // the fragment this peer can serve to neighbours

// A miss is the legitimate "not fetched yet" state, not an error.
check(creel.get(BobbinHash("deadbeef")) == null)

// The capability bundle a WarpNode needs to run an op it has never seen.
val lazyFetch = WarpLazyFetch(
    creel = creel,
    runtime = runtime,
    opToBobbin = { op -> if (op == OpId("reverse")) hash else null },
)
check(lazyFetch.opToBobbin(OpId("reverse")) == hash)
check(lazyFetch.opToBobbin(OpId("unknown")) == null) // nothing to fetch — the task stands by