Module buffer 

The WeaveFFI value-buffer protocol: the by-value serialization format records, rich enums, optionals, lists, maps, and error payloads use to cross the C ABI.

A buffered value crosses the boundary as one (const uint8_t*, size_t) slot pair containing the value serialized in this module’s format, rather than as an opaque object pointer or parallel arrays. Parameters are borrowed for the duration of the call (the consumer owns and frees its own encoding); returns are producer-allocated and released by the consumer with {prefix}_free_bytes after decoding.

Encoding

All multi-byte values are little-endian. There is no padding and no alignment; values are packed back to back.

IDL type	Encoding
bool	1 byte: 0 or 1
i8/u8	1 byte
i16/u16	2 bytes
i32/u32	4 bytes
i64/u64	8 bytes
f32	4 bytes (IEEE 754 bits)
f64	8 bytes (IEEE 754 bits)
enum (C-style)	i32 discriminant
interface	u64 object token carrying one strong reference
string	u32 byte length + UTF-8 bytes (no NUL terminator)
bytes	u32 length + raw bytes
T?	1 byte flag (0 absent, 1 present) + value
[T]	u32 count + each element
{K:V}	u32 count + alternating key, value
record	each field in declaration order
rich enum	i32 tag + active variant’s fields in order
error payload	the matched code’s fields in declaration order

Because the format is compositional, arbitrary nesting ({string:[T?]}, records containing records, objects inside lists, and so on) works with no per-shape special cases. Iterators and callback interfaces never appear inside a buffer; validation rejects them in buffered positions.

An interface object is encoded as a token (see object) that carries one strong reference: the writer clones the object before encoding and the reader adopts the reference. Because adopting is a side effect, a buffer holding object tokens must be decoded exactly once, and only from a buffer whose tokens are genuine. That’s why BufferValue::read_value and decode_value are unsafe: no safe function can turn an arbitrary u64 into an object reference. A reader built with BufferReader::token_free refuses every token instead, which makes decoding through it sound for any input.

A map’s encoding never repeats a key; decoding one that does fails, so a value can’t silently disappear between the two sides.

Encoded lengths and counts are u32, capping any single string, byte buffer, or collection at u32::MAX entries; BufferWriter panics past that bound rather than truncating.

Lists of bytes and fixed-width numbers (every integer and float type, but not bool, whose bytes must be validated) encode and decode with a single copy on little-endian targets, and encode_value sizes its allocation exactly up front from BufferValue::encoded_len.

Structs

BufferDecodeError

An error produced while decoding a value buffer.

BufferReader

Decodes values from the WeaveFFI buffer format.

BufferWriter

Serializes values into the WeaveFFI buffer format.

FixedWidth

Proof that a type’s buffer encoding is exactly its little-endian in-memory representation, which lets lists of it encode and decode with one copy.

Traits

BufferValue

A value that can serialize itself into (and decode itself from) the WeaveFFI buffer format.

ByValue

Marks a type that crosses the C ABI as a value buffer: a #[weaveffi::record] or a rich #[weaveffi::enumeration].

Functions

decode_value^⚠

Decode one BufferValue from an encoded buffer, requiring the buffer to be fully consumed.

encode_value

Encode one BufferValue into a fresh byte buffer, allocated once at the size BufferValue::encoded_len reports.