Skip to content
EN FR

ABI marshalling and value kinds

Documentation status: reference — see Maturity and evidence.

Two levels must be distinguished

The ABI has a descriptor vocabulary and an implemented execution subset. They are not currently identical.

The descriptor vocabulary can name:

null, boolean, integer, float, string, handle, array, record, void,
pointer, callback, i8/u8, i16/u16, i32/u32, i64/u64, f32/f64, bytes

This vocabulary lets manifests describe the intended public shape. The current generic argument builder and executor, however, certify a smaller subset end to end.

Current certified argument subset

i32

An i32 input is range-checked before being copied into the packed argument record. Its descriptor size must equal four bytes.

Pointer

A pointer input must match the host pointer size. It may be null only when the descriptor marks it nullable.

Handle

A handle follows the same physical pointer-size rule but remains semantically distinct from a raw pointer. A handle identifies an ABI-managed runtime object and therefore participates in ownership and release.

Null

The generic argument representation contains an explicit null kind. In the current builder it is accepted for nullable pointer or handle parameters.

Current certified result subset

The generic executor currently decodes:

  • void;
  • i32;
  • pointer;
  • handle.

Other descriptor kinds should not be documented as working through this generic executor until their packing, decoding, ownership, and tests are implemented.

Parameter directions

The manifest vocabulary accepts in, out, and inout, but the current generic argument builder accepts only in. Attempting to execute another direction fails before entering the native module.

This is a useful compatibility rule: parsing a manifest is deliberately broader than claiming an executable binding.

Strings and arrays

Strings, arrays, records, bytes, and callbacks are already represented in the ABI type vocabulary, which is useful for the generator roadmap. They are not yet certified by the current generic marshalling implementation inspected for this documentation pass.

The next certification increment is specified in UTF-8 strings and byte buffers. Arrays remain a separate, later contract.

A future implementation should define, for every such kind:

  • physical representation;
  • encoding;
  • null semantics;
  • length/count representation;
  • allocator ownership;
  • release function;
  • nested object ownership where applicable;
  • local/RPC projection rules;
  • contract tests.

Generated SDK code should never infer support solely from the presence of a value-kind enum. Generation should consume a capability-certified manifest or fail when a public signature contains a value kind that the selected runtime/binding pair cannot marshal.

That keeps the public SDK honest while the ABI vocabulary evolves ahead of individual execution backends.