ADR 0004 — Encoding strategy

Document status: provisional. Canonical source.

Define serialization independently of the logical model. Prototype a canonical text form and deterministic CBOR binary form. Benchmark schema-based alternatives before ratification.

Opaque extensions are explicit NUIF values/bytes so preservation does not depend on a codec’s unknown-field implementation.

Current experimental outcome

nuif-text-0 and nuif-cbor-0 are executable profile-0 encodings. The codec decision gate measures both only after semantic, canonical and opaque-data fixpoints pass. Deterministic CBOR materially reduces file size, but its current typed decoder is not faster than canonical text, so performance alone does not ratify it as the only future binary profile.

Schema codecs must present a complete NUIF mapping before benchmark admission. Protobuf is presently excluded because its own specification says deterministic binary serialization is not canonical. FlatBuffers offers direct access but permits multiple byte layouts for equal values and does not prove retention through an old-schema edit. Cap’n Proto is the next candidate because it specifies schema-agnostic canonicalization and traversal limits; it remains unadmitted until cross-version retentive editing and two canonical writers pass.

The decision report is generated by cargo xtask codec-benchmark; transient host timings are evidence artifacts, not normative limits.