binwire

Typed binary primitives

The candidate runtime formats use static generated field codecs, without JSON or runtime reflection. Runtime format types carry no JSON tags or custom MarshalJSON/UnmarshalJSON methods; the SDK policy tests enforce this. internal/codegen/binary reads Go declarations at build time; generated files remain checked into Git. Run mise exec -- go generate ./format/world after changing an owned contract. The regeneration test checks world, lightmap and material snapshots together.

Each payload begins with 16 little-endian bytes: four-byte magic, uint16 binary version 1, uint16 zero flags, uint32 exact payload byte length and uint32 zero reserved. Readers reject unsupported versions, nonzero reserved fields, truncation and trailing bytes before publication. Owning packages retain their encoded limits and semantic validation.

Fields follow public Go declaration order. int uses signed int32; explicit unsigned integers keep their widths. Floats use finite IEEE float32/float64; negative zero is encoded as positive zero and rejected by the reader. Booleans and pointer presence use one byte, exactly 0 or 1. Strings use uint32 byte lengths followed by valid UTF-8. Slices use uint32 length+1, reserving zero for nil; an explicit empty slice encodes count 1. Fixed arrays omit counts.

Generated scanners traverse the complete payload without allocating strings or arrays. Count checks bound each field, its minimum encoded footprint and the aggregate conservative 32 MiB allocation estimate before typed reads. The estimate includes pointed records, slices and strings. Generated writers stop on bounds failures. Browser Wasm scans/reads/writes yield after bounded byte intervals; native code has no scheduling change. Full authored validation still runs after decoding. A binary header never substitutes for semantic checks.

Magic values are KWR1 world, KLM1 lightmap layout, KPB1 prebake manifest and KMA1 material layout. Internal digest identities use the same primitives with separate domains: KWG1 geometry, KDI1 selected direct lights, KOI1 offline controls, KRA1 reflectance assignments, KLQ1 liquid geometry and KSI1 shadow selection. These are explicit replacements for the released JSON identities; compiled artifacts and bake caches must be rebuilt. Semantic capability versions and lightmap algorithms retain their own independent gates.