Skip to content
EN FR

Byte buffers and binary payloads

Documentation status: architecture — see Maturity and evidence.

Current evidence

bytes already exists in the ABI descriptor vocabulary and is accepted by the manifest loader. The generic argument buffer itself is implemented as a host-side byte array, but that implementation detail must not be confused with support for a public bytes method parameter or result.

The current generic argument builder does not yet pack bytes, and the generic executor does not decode bytes results.

Public semantic contract

A byte buffer represents opaque binary data. The ABI must not reinterpret the content as text, infer an encoding, or require a terminating byte.

The minimum useful contract is:

binary payload = data pointer + byte length + explicit null state

The same physical slice concept can be shared with UTF-8 strings; the descriptor kind determines whether the bytes are interpreted as UTF-8 text or remain opaque binary data.

Input buffers

The first certified input form should be call-scoped and caller-owned:

host byte array
 -> stable call-scoped storage
 -> ABI byte view
 -> invoke
 -> host releases temporary storage

A module receiving this form must not retain the pointer after the call.

Result buffers

The first certified result form should favor copy-and-free semantics:

module allocates result bytes
 -> module writes data pointer and length into result view
 -> host copies bytes
 -> host calls module free

This is deliberately stricter than exposing a raw native pointer. It makes the binding deterministic and keeps allocator ownership at the module boundary.

Limits and validation

Before copying, the host should validate that:

  • null state is compatible with descriptor nullability;
  • non-null data has a coherent length;
  • length can be represented safely by the host runtime;
  • configured maximum payload limits are not exceeded;
  • pointer arithmetic cannot overflow.

An ABI descriptor describes layout and ownership, not an unlimited allocation entitlement.

Arrays are a separate contract

A byte buffer is not the generic array ABI. Arrays need element kind/type, count, nested ownership, and possibly per-element release semantics. bytes should therefore be implemented and certified independently before the more general array contract.

Binding projection

For .NET, the default projection should be a managed byte sequence such as byte[], ReadOnlyMemory<byte>, or another generated contract appropriate to the call shape. Public APIs should not require callers to manipulate the native data pointer directly.

Certification gate

The bytes kind should move to reference only after tests cover:

  • null, empty, and non-empty input;
  • binary values containing zero bytes;
  • result copying and moduleFree release;
  • payload-limit failures;
  • repeated calls without leaks;
  • FPL conversion;
  • generated binding conversion;
  • local/RPC parity where applicable.