Module cache 

CacheDirectory<S> — two-tier cap store.

• blobs: HashMap<CapHash, Arc<C>> — content-addressed immutable resident 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<C>)> — 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<C>; if that was the last strong ref to the resident cap, the Cap drops. Caps no longer hold Ref(CapRef) slot targets (a cnode slot is a Hash or an inline Owned cap), so a drop never cascades into other instance entries — the sweep is a single self-contained pass per orphan. The loop is retained as a cheap fixed-point guard.

The instances tier is currently dormant: the recompiler keeps sub-VMs inline as Owned caps and never publishes a CapRef. The tier (and CapRef) survive as the host-side key for the future deferred-persist path.

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

CapHasRefError

Error returned by <CapHashOrRef as rkyv::Serialize<_>>::serialize when the cap graph still holds a runtime-only target — a CapHashOrRef::Owned. Callers must settle (or otherwise rewrite the target to a hash) before rkyv-encoding the cap.

CapRef

Cache-local lifetime handle to a working Cap::Instance in CacheDirectory.instances.

Enums

CacheError

CapHashOrRef

Slot/field reference: a content-addressed blob in cache.blobs (Hash), or a single-owner cap held inline by the running kernel frame (Owned).

Traits

ResidentCap

Payload stored by a CacheDirectory. The public/wire directory stores plain Cap; engines may store a resident wrapper that carries derived runtime caches while still exposing the underlying wire cap for hashing and inspection.

WireOwned

Marker for CapHashOrRef::Owned payloads that participate in the content-addressed wire form. Implemented only for Box<Cap> (the default payload).