Module image 

Image: the smallest unit of program specification.

An Image is content-addressed (its image_id is the hash of its serialized content). An Instance’s image_hash is the cumulative chain hash tracking the lineage of set_image / host_derive_spawn extensions from genesis.

genesis (host_derive_spawn from no source):
    image_hash = hash(image)

after set_image(new):
    image_hash = hash(prev_chain || hash(new))

after host_derive_spawn(new, cnode) by a spawner:
    spawned.image_hash = hash(spawner.image_hash || hash(new))

after MGMT_COPY of a Cap::Instance:
    copy.image_hash = source.image_hash   (preserved)

This module provides the pure data structures + the chain-hash computations. Image content hashing is done by serializing the Image canonically and feeding the bytes to H::hash; we provide a simple deterministic encoder here so the v3 implementation has one canonical form.

Structs

ArenaPageRef

One non-zero page of a DataDesc: logical page page_index is backed by the arena window arena[arena_off .. arena_off + len], zero-padded to PAGE_SIZE when materialized. len (1..=PAGE_SIZE) stores only the page’s meaningful prefix — trailing zeros within the page are dropped, so a sub-page-dense region costs len bytes, not a full page. Windows are packed tightly (no arena_off alignment). Pages not named by any ArenaPageRef are the canonical zero page (PageSlot::Empty).

CodeRef

A slice of the Image arena holding the contiguous code region: arena[arena_off .. arena_off + len] are the raw RV+C+custom-0 bytes, mapped RO at crate::layout::CODE_BASE. len is the exact (non-page-rounded) code length — the recompiler and alloc_page_aligned_code iterate exactly len bytes — while the arena window itself is page-rounded. CodeRef::default() ({0, 0}) is a codeless image.

DataDesc

Page-granular sparse content of a data cap. size is the full logical extent in bytes (a PAGE_SIZE multiple); pages names only the non-zero pages, sorted by page_index (strictly ascending, unique), each backed by an arena window of its non-zero prefix (zero-padded back to PAGE_SIZE at decode) — see ArenaPageRef.

EndpointDef

Endpoint definition: entry PC + register conventions.

Image

Image: the program spec (code, endpoints, memory layout, slot declarations, pinned ro caps).

ImageBuilder

Canonical Image assembler. Callers supply logical content (code + per-slot contiguous bytes + size, exactly as before the arena redesign); build packs a single page-granular arena deterministically: code laid contiguously at offset 0, then each data cap (pinned then initial, in Key order) page-split with all-zero pages elided and byte-identical pages deduplicated. The packing is a pure function of the logical content, so equal logical Images produce equal arenas and equal image_content_hashes regardless of builder call order.

MemoryMapping

One mapped region. The kernel resolves source (a cnode slot path to a Cap::Data) at instance start and lays the bytes at [start, start + size) in the address space. RO vs RW is derived from whether the target slot is in Image.pinned_slots.

Enums

DataDescError

Structural faults in a DataDesc relative to the Image arena, surfaced eagerly at deblob (per the strict-interface rule: fail loud).

PinnedCap

Pinned slot content. Only content-addressed cap kinds can be pinned (Data or Image). Cap::Data bytes are inlined in the Image; a future optimisation can add a hash-only variant for content that lives in σ.data_payloads.

Functions

chain_extend

Extend an image-hash chain with a new image: result = H(prev_chain || image_content_hash(new_image)).

chain_genesis

Genesis image-hash chain: a freshly-derived Instance (with no prior chain) has image_hash = image_content_hash.

image_content_hash

Content hash of an Image: SSZ hash_tree_root (SHA-256 merkleization of the derived SSZ container). The canonical encoding/merkleization is defined by Image’s ssz-derive impl.

Type Aliases

InitialDataCap

Initial Cap::Data content for a non-pinned mutable slot. Used at standalone (root) Instance bootstrap to seed the cnode. A parented Instance receives its slots from the spawner and ignores this field.