Documentation menu

Validation and Compatibility

Treat decoding, scene admission, and backend capability as separate checks in a versioned contract.

An incoming update must pass several checks before it can become display work. Decoding first bounds the cost of receiving the message, after which pure validators check values such as geometry and buffer metadata. Retained-scene validation then establishes structural validity and ownership, and backend admission determines whether the resulting work fits device capabilities and resource budgets.

Wire Limits

The 4 MiB encoded-payload limit bounds the message as a whole, while collection limits constrain its internal structure. A commit can contain at most 4,096 operations, a reorder can name 16,384 children, and a text run can contain 65,536 glyphs. Input collections are bounded to 64 pointer buttons or 256 touch points, and FrameDamage can list up to 64 rectangles.

Collection limits supplement the overall byte limit rather than replacing it. A vector can fit its element count and still produce a payload larger than 4 MiB. Even after decoding succeeds, scene quotas and renderer admission can impose further bounds on the work represented by those values.

Malformed Value Rejection

Decoding applies the wire contract's fixed integers, little-endian order, and trailing-byte rejection within an explicit budget. For bounded sequences, it checks an advertised length before allocating arbitrary storage, then continues enforcing the bound as elements arrive. This also protects formats that do not supply an exact length hint.

Buffer dimensions and byte spans are checked with arithmetic that cannot wrap into a smaller accepted allocation. Visual types define limits for font sizes, blur, paths, gradients, strokes, and shadows; use their validators when extending the contract.

Contract Versioning

Changes to binary enum order, field types, payload fields, or serialization settings can change what an existing peer decodes. Review the hello version with any such change, then update every consuming layer, including hera-ffi and rn_host, so negotiation and data interpretation remain consistent.

A Serde default does not by itself establish backward compatibility for this binary representation. Compatibility claims need codec fixtures and explicit version behavior.

Boundary Verification

Verification should follow the same boundaries as the change. Protocol edits need codec and validation checks together with the repository integration test; changes crossing into native code also need a rebuilt FFI library and consumer. The verification guide provides the commands and their prerequisites.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/protocol/src/limits.rs
  • crates/protocol/src/codec.rs
  • crates/protocol/src/buffers.rs
  • crates/protocol/src/scene/mod.rs