Module yield_cap 

YieldSender / YieldReceiver kernel-assisted cap helpers + the reserved kernel:* yield-key namespace.

A yield_key is a ≤MAX_KEY_LEN-byte Key — the same byte-string key type used for cnode slots. It is the routing key for host_yield: the kernel walks the call stack and the nearest snapshotted YieldReceiver containing the key catches the yield. Keys whose first byte is KERNEL_YIELD_NS are reserved kernel:* syscalls, caught by the kernel as the implicit ROOT YieldReceiver (bottom of the stack); chain/user yield_keys must not use that namespace.

The two per-Instance kernel-assisted variants:

• YieldSender{yield_key} — the EMIT right. The yield_key is packed into the handle’s regs[0..1] (same packing as Gas{meter_key}; see key_to_regs).
• YieldReceiver{Set<Key>} — the CATCH right. The catch-set is serialized into the handle’s mem DataCap so the kernel can short-circuit it during routing. Wire form: u16 count then, per key, u8 len + len bytes (the page-pad tail is ignored).

Constants

KERNEL_YIELD_NS

Namespace marker (first byte) of a reserved kernel:* yield_key.

YK_ATTEST

kernel:attest — attestation request (§15).

YK_MERGE_YIELD_RECEIVER

kernel:merge_yield_receiver — union two YieldReceiver catch-sets.

YK_MINT_GAS

kernel:mint_gas — mint a Gas{meter_key} handle.

YK_MINT_QUOTA

kernel:mint_quota — mint a Quota{quota_key} handle.

YK_MINT_YIELD

kernel:mint_yield — mint a (YieldSender, YieldReceiver) pair for a key.

YK_OOG

kernel:oog — kernel-injected on gas exhaustion.

YK_SET_GAS_METER

kernel:set_gas_meter — set a meter, return previous.

YK_SET_STORAGE_QUOTA

kernel:set_storage_quota — set a quota, return previous.

YK_STORAGE_EXHAUSTED

kernel:storage_exhausted — kernel-injected on quota exhaustion.

Functions

gas_handle

Build a Gas{meter_key} unit handle: a Cap::Instance with the well-known Gas image-hash chain and the meter_key packed into regs[0..1] (same packing as yield_sender). The kernel reads these handles from an Instance’s ordered gas_slots to index the gas-meter mapping; minted by the kernel:mint_gas syscall.

gas_meter_key

Read the meter_key from a Gas handle. None if inst is not a Gas handle.

is_kernel_yield_key

True iff key is in the reserved kernel:* namespace (caught by the kernel as the implicit root receiver).

merge_yield_receivers

Union the catch-sets of two YieldReceiver handles (the kernel:merge_yield_receiver operation). None if either is not a YieldReceiver.

quota_handle

Build a Quota{quota_key} unit handle (storage-quota analogue of gas_handle); minted by the kernel:mint_quota syscall.

quota_key

Read the quota_key from a Quota handle. None if inst is not a Quota handle.

yield_receiver

Build a YieldReceiver{keys} unit handle: a Cap::Instance with the well-known YieldReceiver image-hash chain and the catch-set serialized into its mem DataCap. The set is normalized (sorted, deduped).

yield_receiver_keys

Read the catch-set from a YieldReceiver handle (normalized: sorted, deduped). None if inst is not a YieldReceiver; an empty/short mem decodes to an empty set.

yield_sender

Build a YieldSender{yield_key} unit handle: a Cap::Instance with the well-known YieldSender image-hash chain and the yield_key packed into regs[0..1].

yield_sender_key

Read the yield_key from a YieldSender handle. None if inst is not a YieldSender.