Module cache 

CacheDirectory<S> — two-tier cap store.

• blobs: HashMap<CapHash, Arc<Cap>> — content-addressed immutable caps. Pure cache: the host populates it; the kernel reads. If a lookup misses, the host hasn’t published the cap yet.

• instances: HashMap<u64, (CapRef, Arc<Cap>)> — identity-keyed mutable working state. The stored CapRef is the directory’s self-reference; its Arc::strong_count is the number of live external holders + 1.

Two callers exist: the Nub local backend (host’s Global) and the Nub Hyperlight backend (guest’s Global via talc). Both wrap CacheDirectory<S> in their own static / field; the directory’s interior is spin::Mutex-protected so every public method takes &self.

Cow + lazy promote

Promotion (blob → instance) is a cheap Arc::clone:

let arc = blobs[&hash].clone();        // RC bump; no Cap copy.
let id = self.next_ref;
self.next_ref += 1;
let capref = CapRef::new(id);
instances.insert(id, (capref.clone(), arc));   // RC bump on capref.
capref

Mutation uses Arc::make_mut:

let mut arc = cache.get_instance(&capref).unwrap();
let cap_mut = Arc::make_mut(&mut arc);   // clones iff strong > 1.
// ... mutate cap_mut ...
cache.set_instance(&capref, arc);

Arc::make_mut subsumes the legacy “sole-owner move-promote vs shared shallow-clone” branch — same decision, in fewer lines.

GC sweep

sweep_instances reclaims entries whose stored CapRef.strong_count is 1 (i.e., the directory is the sole holder). Removal drops the entry’s Arc<Cap>; if that was the last strong ref to the Cap, the Cap drops; the Cap’s Ref(CapRef) slot values drop too, decrementing more entries’ refcounts. The sweep loops until a pass finds nothing.

Cycles are structurally impossible (data-flow principle: website/content/spec/discussions/data-flow-principle.md), so the sweep is guaranteed to make forward progress.

blob retention

V0 blobs accumulate; the host pre-publishes every cap the invocation needs and lookups never miss. Future design: missing-blob lookups pause the kernel and ask the host to publish. Until that lands, get_blob returning None is treated as a hard failure by the caller.

Structs

CacheDirectory

Enums

CacheError