Crate nub 

Nub: the JAR v3 microkernel substrate — uniform caller-facing handle.

The Nub handle hides the choice of substrate behind a single publish/invoke surface, generic over a kernel Personality P (the pluggable semantics layer: what published objects mean, how invocations resolve a root object). Two backends:

• Local: the personality’s in-process kernel (Personality::Local, a LocalKernel impl). Used for tests, deterministic replay, and any host that doesn’t need real ring-0 isolation.
• Hyperlight: ships invocations as RPCs into a bare-metal guest binary (the personality’s guest crate over the generic nub-arch-x86 kernel lib) running inside a Hyperlight sandbox. The wire protocol is personality-agnostic: opaque bytes + 32-byte ObjHash keys.

Nub itself owns no guest blob and no singleton policy — a personality entrypoint crate (e.g. rust/javm for JAVM) builds its guest blob, defines the typed publish surface, and constructs handles via Nub::new_local / Nub::create_hyperlight.

Re-exports

pub use personality::LocalKernel;

pub use personality::Personality;

Modules

personality

Host-side kernel-personality abstraction.

Structs

InstanceRef

Opaque, 32-byte handle to an Instance held by an Arch.

InvocationResult

Invocation result. Both backends produce this shape on completion; rkyv-archived on the wire from the cached path’s response.

InvokeJob

InvokeJobId

InvokeOptions

Per-invocation knobs. Empty for the skeleton; fields will land as the kernel grows (gas budget overrides, quota budget, tracing, reentrancy depth limits, …).

InvokeOutcome

Result of a successful invocation. Extensible — fields land as needed (gas remaining, post-invocation cap hash, host-call trace, …). For the skeleton we expose only the JAVM HALT return value and gas used.

InvokeRequest

Nub

Uniform handle to the nub microkernel substrate, generic over the kernel personality.

NubOptions

Options used when constructing a Hyperlight-backed Nub.

Constants

MAX_HYPERLIGHT_VCPUS

SCRATCHPAD_HEAD_LEN

Bytes of the running Instance’s scratchpad (slot[0]) region surfaced at the top-level HALT — a fixed-size head of the returned DataCap’s effective content. The guest writes its result into the scratchpad-mapped memory region during the run (CoW into the cap); at top HALT the engine reads the region’s effective bytes back out here, so the host observes the full, uncompressed result without a separate data-flow event.

Type Aliases

AbiCapHash

32-byte content hash of a published state object (the legacy name from when the only personality was the JAVM cap system — matches nub_kernel::ObjHash and, byte-wise, javm_cap::CapHash; kept as a local alias so this crate stays dependency-free).

CapHash

Legacy alias for ObjHash from when the only personality was the JAVM capability system. Prefer ObjHash in new code.

ObjHash

32-byte content hash of a published state object. The personality defines the hash function (JAVM: SSZ hash_tree_root); nub treats the value as an opaque content-addressed key.