High-performance binary CBOR serialization of heterogeneous and homogeneous polytropos open records and variants via cborg / serialise, without intermediate tree boxing.

Architectural Overview & Rationale

Binary Wire Format

• A record encodes as a standard CBOR array: one length header (the row's arity) followed by the flat payload field encodings in row order.
• A variant encodes as a CBOR array consisting of the constructor's Word tag followed by that constructor's payload field encodings.

Positional & Allocation-Free

Because field names exist only at the type level in row polymorphism, the binary encoder is purely positional: no string keys are written to the wire. Encoding and decoding are executed as single unrolled passes directly over the flat Rep payload array with no intermediate allocations.

Truly Heterogeneous Row Support

Unlike satellites restricted to homogeneous types, polytropos-cbor provides genuine heterogeneous serialization across open rows via AllSerialise: every field requires Serialise at its own concrete type, so rows mixing String, Int, Word, custom types, or nested rows serialize and deserialize directly.

When to Use This Module

• When network bandwidth, binary storage size, and serialization speed are critical.
• For inter-service RPC, binary logs, and compact caching.

Worked Example

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE TypeApplications #-}
{-# OPTIONS_GHC -fplugin=Polytropos.Plugin #-}

import Codec.Serialise (serialise, deserialise)
import Polytropos
import Polytropos.CBOR

-- A genuinely heterogeneous record:
type Packet = Record '["id" ':= Int, "payload" ':= String, "flags" ':= Word]

pkt :: Packet
pkt = REC { id = 101, payload = "sensor-ok", flags = 0 }

-- Serializes to compact positional CBOR binary:
bytes = serialise pkt

-- Deserializes back to Packet:
pkt' :: Packet
pkt' = deserialise bytes

Homogeneity Evidence and Introspection Helpers

In addition to the primary heterogeneous codecs (AllSerialise, AllCtorsSerialise), this module provides closed type families and reflection classes for inspecting row metadata and enforcing uniform payload types.