FlexBuffers: October performance and stability review

The 3 October 2026 review confirms that generated FlexBuffers are a strong binary codec for jointly deployed models, especially numeric vectors and partial reads. It also reproduces four correctness defects that block broad adoption. Browser object encoding remains a major weakness. Android has large measured bulk-transfer opportunities that are not implemented in the production kernels.

This is the current measurement ledger. The implementation guide retains the July campaign as historical evidence. The complete wire-format and mutable-memory book supplies design input for a separate mutable engine. Neither codec microbenchmarks nor the book establish an end-to-end FFI latency result.

Evidence and protocol

• Source: b587950324baba646bf8b3341db55611ae2d5d02. The reviewed reaktor-flexbuffer and compiler sources were unchanged when documentation was refreshed on 4 October.
• Host: Apple M4 Pro, 14 cores, 48 GB; Temurin Java 25.0.2.
• JVM: JMH 1.37, two fresh forks, three 500 ms warmups, five 500 ms measurements, one thread, fixed 1 GiB heap, GC profiler. Tables report means with JMH's 99.9% error estimate and allocated bytes per operation. This schedule differs from July; the two campaigns are not a paired optimization A/B.
• Android: physical Samsung Galaxy S23 Ultra SM-S918B, Snapdragon 8 Gen 2, Android 16/API 36, warm ART instrumentation APK. These are not release-APK numbers.
• iOS: physical iPhone 14 Pro, A16, iOS 26.7.1, optimized Kotlin/Native release executable; cases launched separately.
• Browser: Chrome 154 on the same M4 Pro, production Kotlin/JS module, measured in an actual browser. This is distinct from July's Node/V8 run.
• Cross-platform harness: 10,000 codec primes, 5,000 per-operation warmups, median of seven batches of 3,000 operations, escaped results and equality/checksum guards. These medians have less statistical rigor than the JVM JMH results.
• Baselines: kotlinx.serialization JSON and ProtoBuf, encodeDefaults=true. Main JSON encode returns a String; a separate measurement includes UTF-8 output. kotlinx ProtoBuf uses default unpacked numeric repeated fields. A supplementary Google Java Protobuf comparison uses packed numeric fields.
• Adversarial cases: the existing minimum-of-three smoke harness gives directional evidence. It is not interchangeable with JMH.

Download the full machine-readable ledger. It includes samples, ranges, wire sizes, adversarial cases, profiles and test totals. The retained local source artifacts are in reaktor-context/flexbuffer-review-2026-10-03/: jvm-jmh.json, browser-results.json, Android/iOS logs, google-proto/, cpp-native.log, profiles, and test XML. No simulator or emulator was used for this review's mobile results.

JVM encoding and decoding

Microseconds per operation, mean ± 99.9% error estimate. Generated encode copies the finished result into a returned ByteArray; caller-owned encode returns a borrowed view. Decode reconstructs the requested Kotlin model. Accessor rows read encoded fields without full reconstruction.

Generated decode wins each of these three cells against both kotlinx baselines. Numeric TimeSeries is the strongest case. Caller-owned encoding reduces bytes allocated, but is slower than copying encode for UserProfile in this run (0.612 versus 0.487 µs). Removing a copy does not guarantee a runtime win.

Allocated bytes per operation, GC profiler; tiny residual values are profiler noise, not a literal fractional allocation:

Full generated decode still allocates model objects, strings and collections. Caller-owned output only avoids the final byte copy. Borrowed views expire when the builder is cleared or reused; asynchronous consumers require ownership transfer or a copy. Do not describe either API as universally allocation-free.

Matched cross-platform codec results

All values are median µs/op. Flex encode returns copied bytes. JSON E returns a String, JSON UTF-8 E returns transport bytes, and JSON D reconstructs a Kotlin model. ProtoBuf also returns bytes and reconstructs a Kotlin model. These fixtures passed equality/checksum guards; the ChatThread validator rejects a valid empty map inside the fixture, discussed below.

JVM supplemental harness

Physical Android

Physical iOS

Chrome browser

The ranking is workload- and direction-specific. Android UserProfile JSON encoding beats generated Flex encoding; Android ApiResponse ProtoBuf encoding is marginally faster than Flex in this harness. In Chrome, JSON encodes the three object-heavy fixtures faster, and UserProfile JSON decoding is roughly tied/slightly faster. July's statement that generated decode wins every Node cell does not describe this browser campaign. TimeSeries remains a clear Flex strength across targets.

Native browser JSON is a separate representation

These medians measure native JSON.stringify/JSON.parse on JavaScript objects. They do not reconstruct Kotlin classes or perform Kotlin collection/Long conversion. UTF-8 variants include TextEncoder/TextDecoder; the fixture integers fit JavaScript's safe integer range. They demonstrate the browser's native object-path advantage, but are not a substitute for the typed-model comparison above.

Wire sizes

Bytes per fixture. JVM, Android and iOS agree on all three formats. Browser JSON number formatting changes the two indicated sizes; Flex and ProtoBuf sizes agree.

Flex is not always smaller than JSON: UserProfile is 833 versus 710 bytes. All four kotlinx ProtoBuf fixtures are smaller than Flex. Generated shared-key blocks improve repeated maps; they do not establish universal size superiority.

Packed Google Java Protobuf

The supplemental Java harness measures two fresh forks, seven measured batches per fork, warmed operations and escaped results. Each cell below lists fork 1 / fork 2 median µs/op. It reruns Flex in the same harness; compare within this table rather than against JMH. Google Protobuf's native model and Kotlin-model conversion are separate rows.

Protoc 33.1 and Google Java runtime 4.36.1 produced 473-byte UserProfile and 3,651-byte packed TimeSeries (versus Flex's 833 / 4,340 bytes). Native Google UserProfile encoding can beat Flex; conversion to/from Kotlin adds work. Packing reduces the numeric baseline's size and avoids attributing an unpacked-kotlinx ProtoBuf limitation to Protobuf as a format. This comparison covers only the two explicitly modeled fixtures, not mobile or browser Google runtimes.

In-memory access and validation

Median µs/op. Projection consumes selected fields; Object starts from an already materialized model. It excludes the cost of decoding that model and does not serve as a serialization baseline. Very short operations have limited timer resolution.

Encoded access avoids paying full decode when a consumer needs a few fields. It does not usually beat direct field access on an object that already exists. Repeated vector wrapper construction/traversal can dominate an accessor; generate count/element/cursor operations and benchmark the actual traversal.

Validation is material work: Chrome ApiResponse validation costs 34.300 µs versus 14.400 µs for trusted generated decode. Validate once at a defined ingress, cache that result only while bytes remain immutable, and independently check schema/layout. ChatThread validation exits on a defect, so its short validation time is not successful full validation throughput.

Android primitive bulk transfer: measured experiment

The current Android PrimitiveArrayCopy.android.kt implementations all return false; production readers/writers fall back to scalar loops. The following 4,096-element A/B measures standalone scalar versus java.nio ByteBuffer bulk views on the physical S23. It supports a proposed kernel policy, not a shipped optimization or an equivalent whole-model speedup.

ART exposes Unsafe in this run but not object-to-object copyMemory. Use public bulk views rather than assuming HotSpot intrinsics transfer to ART. Measure crossover sizes per type and direction before choosing thresholds. The historical suggestion to keep all Shorts scalar needs reevaluation: the October large-Short result also improves. Small arrays can still lose to wrapper/setup overhead. Preserve compact wire-width and endianness rules; a natural-width copy is not legal for narrowed data.

Adversarial and profiling findings

The complete ledger retains all 11 smoke cases per target, including unsupported generated cells as -1 rather than silently omitting them. Those minimum-of-three timings identify targets for better measurements:

• Chrome string-heavy and graph/object-heavy encode still loses to JSON. Unicode and StringFlood decode also lose in the browser; do not claim universal decode wins.
• Unicode encoding is a recurring weakness across platforms. Measure single-pass UTF-8 generation, safe capacity slack and removal of temporary arrays before selecting a kernel. A native crossing per string can erase any local gain.
• Raw ApiResponse CPU samples include Map.keyEquals (17.6% of leaf samples) and FlexDecoderV2.decodeElementIndex (10.8%); its allocation samples include byte arrays (48.7%) and strings (12.4%). Sample shares depend on the profiled workload and are not percentages of universal codec cost.
• The native C++ smoke harness passes checksum guards, but its index/key/partial reads do not reconstruct Kotlin objects. Fixed-order binary, raw POD and raw-array counter-baselines can beat Flex while giving up self-description. Do not divide their timings by full Kotlin decode and call the result a language comparison.
• C++ unique-string sharing is 126.246 µs versus 57.799 µs without sharing in the native smoke run, trading bytes (33,852 versus 37,128) for hashing work. Reuse defaults need fixture-specific A/Bs rather than universal interning.

Reproduced stability defects

The dedicated review probe suite ran five tests: four failures and one pass. These are distinct from the normal test suite totals retained in the JSON ledger.

The required-field failure crosses field values (street=Zip, zip=Wrong street). It is data corruption, not a performance tradeoff. Structural validation cannot prevent reading a structurally valid but semantically incompatible schema.

Other source risks remain: unsynchronized cold writes to the raw decoder's field index cache, retained giant pooled buffers, registry writes that must remain startup only, unsupported KSP shapes reaching runtime TODO/error branches, and incomplete upstream reader parity. Fingerprinting and a versioned production FFI transport are still absent. No documentation refresh fixes these implementation defects.

Optimization and adoption plan

1. Correctness and lifetime gate. Fix the four repros, cache concurrency and pool retention; fail compilation for unsupported shapes. Add deterministic wire and model semantics tests, malformed-input probes and native sanitizer coverage.
2. Compile the layout contract. Extend KSP first: stable schema fingerprints, required/default/null semantics, keyed fallback, one-time validation/layout proof, generated traversal and no descriptor/key work on the trusted hot path. Investigate a compiler plugin when KSP cannot expose or specialize the required language shape; account for compile time, generated size, incremental builds and supported targets.
3. Ship the measured Android opportunity. Implement public bulk-view kernels, benchmark thresholds and release APKs on physical devices, and verify narrowed widths, offsets, endianness and boundary sizes. Keep the measured experiment distinct from the eventual production A/B.
4. Fix JS object encode and UTF-8. Use 32-bit offset/length metadata where wire bounds permit it; reserve true 64-bit handling for values. Measure native typed-array views, direct byte output and single-pass string encoding. Include browser and Worker runtimes, safe-integer/BigInt semantics and actual transport conversion.
5. Optimize actual consumers. Use borrowed buffers and generated partial traversal only with explicit lifetimes. Measure allocation, retained memory, cold/warm latency, p95/p99 and throughput, including validation, queueing and scheduling where relevant.
6. Move bounded work to C++ when it wins end to end. Candidate work includes large UTF-8/vector batches, scan/filter kernels and SIMD. Cross once per batch or operation; include JNI/cinterop/JSI setup, copies, pinning, ownership, cancellation, code size and platform fallback. Neither this run nor current FFI code proves a blanket C++ win.
7. Prototype mutable execution memory separately. Use the book's chapters 24–30 as a design input: cells, descriptors, handles, slabs, SIMD layouts, transactions, snapshots and concurrency. Measure pointer/object graphs, packed arrays and Flex views against the prototype. Serialize an immutable FlexBuffer snapshot at the boundary; do not treat borrowed wire bytes as an arbitrary growable mutable heap.

Performance is judged per workload across encode, full decode, partial read, in-memory mutation/traversal, bytes, allocations and retained memory. The mutable engine has no measured implementation yet; its performance is an experiment to run, not a number to infer from this codec ledger.

Related documentation

• FlexBuffers implementation: APIs, source map, ownership and historical July evidence.
• From Bytes to Mutable Memory: the entire supplied book and C++ listings.
• Reaktor FFI: current native proof and proposed typed frames, ownership and acceptance gates.