Envelope v1: cost, and closing the regression series

Historical document. Written on 2026-11-12, when the project was called zidl (later Graven). Snapshot names (t1-base, t4-head, …) refer to copies of the tree taken during the format plan.

Date: 2026-11-12 · Complements round 2 (same scenarios and same methodology). Machine: Intel Core i9-14900HX, Linux 7.3, rustc 1.94.0, --release. Noise observed between runs: ~±5%. Differences smaller than that count neither as a regression nor as a win. Machine load: 1-minute average between 0.5 and 4.5 during the runs (a browser open in the background). Number of runs per table:

• Envelope write overhead: median of 4 runs (3 from the write group and 1 from the envelope group).
• Envelope read overhead: 1 run (the envelope group), under load 0.5–4.5.
• CRC32C: 1 run.
• Comparison with round 2 (write, read_all, read_all_verified): median of 3 runs.
• A/B against snapshots: median of 3 interleaved runs in the final table of the section "Fixing the regression"; at least 2 interleaved runs in the A/B tables before the fix; at least 3 in the telemetry bisection.

Single-run numbers (envelope reading, CRC) carry more uncertainty than the medians; read them as orders of magnitude.

Commands:

• cargo bench -p zidl-bench --bench codec -- envelope
• cargo bench -p zidl-bench --bench codec -- crc32c
• cargo bench -p zidl-bench --bench codec -- write and -- read_all (includes read_all_verified), 3 times each

The envelope

An envelope is [20 B header][message][4 B CRC32C]: +24 bytes per message. The header carries the magic, the version, the schema id and the size. The CRC32C covers the header and the message.

• Writing: Builder::new_enveloped reserves 20 bytes before each message. flush_envelope(schema_id) fills the header in place, computes the CRC and returns a Bytes. The message is not copied.
• Reading: X::from_bytes(buf) decodes the envelope (checks the magic, version, size and CRC), checks the schema id and runs the full verification. It is equivalent to X::verified(payload) plus the cost of the envelope.

Cost of the envelope (ns, median)

write_owned is the fair comparison line: one owned Bytes per message (flush()), the same contract as flush_envelope(). In bank/10 both use a list with a known count.

Writing

The overhead is dominated by the CRC (crc32c of ~60 B costs ~6 ns, of 64 KiB ~1.65 µs, see below) plus writing the 20 B header. In chunk/65536 the extra cost (1.03 µs) is smaller than the bare CRC (1.65 µs): probably because the owned 64 KiB write already spends time in memcpy and the CRC overlaps part of it (not verified).

Reading (one field)

Reading (every field, bank/10)

Reading the result:

• The extra cost of reading is the CRC: zidl's full verification does not touch the data bytes (chunk/65536 verifies in 4.9 ns), but the CRC walks the whole message. That is why the overhead grows with size: ~10 ns for messages of tens of bytes, 1.7 µs for 64 KiB.
• For small messages the envelope costs 10 to 14 ns per side (writing and reading). In exchange you get integrity (CRC32C), a version and a schema check.
• For large payloads the cost is proportional to size, at ~40 GB/s (below): 1 µs per ~40 KB.

CRC32C throughput

zidl::crc32c (hardware acceleration, the SSE4.2 crc32 instruction) against crc32c_sw (slicing-by-8, used without std).

GB/s = 10⁹ bytes/s (criterion reports GiB/s: 37.1 GiB/s at 64 KiB). The hardware path is ~14× faster than the software one for large messages.

The deferred regression series (Tasks 4 and 5)

Context:

• Task 4 changed Builder::begin_msg (a prefix of 4 or 20 bytes). The ±5% write comparison was inconclusive because of machine load.
• Task 5 changed the trusted/verified read path of bank.

Since the machine's absolute speed may differ from round 2, there are controls:

1. Absolute value against the round 2 table (column "Δ abs").
2. Ratio zidl/fbs and zidl/capnp against the round 2 ratio (cancels differences in machine speed). A real regression is a ratio deviation > ~5–8% above the noise.
3. Direct A/B. The plan's snapshots (snaps/t1-base = the pre-plan code, t4-*, t5-base) were built with the same rustc and measured interleaved with the current code, in the same session. This is more reliable than comparing with a table from another day.

In this round the absolute FlatBuffers and Cap'n Proto numbers stayed within ~±5% of round 2 for writing (fbs bank/1 58 vs 56.8; frame/500 17.7 µs vs 17.7 µs) and ~+5–10% for reading. That is, the machine is close to round 2's, with fbs reads a bit slower.

The tables in this section (up to the verdict) were measured before the fix described in "Fixing the regression"; the verified bank/1 row (56 ns) is the value with the regression. The final numbers are in the fix section.

Writing: zidl, zidl_known, zidl_batched, zidl_owned

Reading every field: zidl and zidl_trusted

Verified reading (read_all_verified): zidl

Direct A/B against the pre-plan code (bank, at least 2 interleaved runs)

Small scenarios (at least 2 interleaved runs, pre-plan against now):

The telemetry step: see the section "Fixing the regression" (bisection by snapshots). The step already existed before Task 4.

Regression verdict

Notes:

• Cause of the verified bank/1 regression: see the next section. The initial attribution to Task 5 was wrong (the A/B only had the t5-base snapshot and the pre-plan, and t5-base already carried the step); the bisection by snapshots shows the step came from Task 1.
• Small inconclusive variations (≤ ~4 ns absolute, A/B without consistency between runs): read_all/zidl/frame/10 +8%, read_all_verified/zidl/chunk/64 +10% (6.3 to 6.9 ns). fbs frame/10 got faster in the same comparison, which suggests a code layout effect rather than an algorithmic change.
• Absolute differences against the doc in read_all/zidl/bank/100 (+11%): the A/B shows that the pre-plan code measures the same value today (690 vs 682 now), so it is the round 2 table that was ~9% faster. Not a regression of the plan.

Fixing the regression (verified bank/1)

Bisection by snapshots (read_all_verified/zidl/bank/1, 3 interleaved runs, ns): t1-base 45.9 · t1-head 54.2–56.4 · t2-base 55 · t3-head 55 · t4-base 54–55 · t4-head 57 · t5-base 56–58 · t5-head 57 · current 58–60. The step of ~+10 ns came in with Task 1, which only touched Error (new variants carrying data: Incomplete { needed: usize }, SchemaMismatch { expected: u64, found: u64 }, UnsupportedVersion(u8)) and the writer's list_size. Tasks 4 and 5 contribute ~+1–2 ns (noise).

Cause. With the new variants, Error went from 1 byte (an enum without data) to 24 bytes. No Result<_, Error> fit in registers anymore. The verify functions of the schema types (Transaction::verify, FromTable::verify of Transaction and Entry, ListR::verify) were called out of line (without #[inline]), so each message paid for the call and for returning the Result<(), Error> through memory. Evidence from an isolated experiment (a copy of the code, no repository file touched): with Error back at 1 byte the time drops from 57 to 45 ns (equal to the pre-plan 44); with a 12-byte Error (u32 fields) it does not change (57). Only #[inline] on the verify functions, keeping the 24-byte Error, brings the time to 39.5 ns.

Change. #[inline] on the 11 verify functions in crates/zidl-schemas/src/{bank,game,iot,stream,lib}.rs (FromTable::verify of each table, the public verify of each root, ListR::verify). No change to unsafe code, to Error or to the structure of the views (buildable only via verify). Coverage: the existing tests (verified.rs, equivalence, conformance and the required-mask proptest) exercise these same paths; cargo test --workspace still has 174 passing, 0 failing. There was no behavior change, so no new test was needed.

Result (interleaved A/B, median of 3 runs, ns):

(The "t5-base" column is the post-Task 4 / pre-Task 5 snapshot, which already carried the Task 1 step.) No regression above 5% of the pre-plan, except zidl_trusted bank/1: +0.8 ns (6.5 → 7.3 ns, +12%), a known and accepted deviation from the ±5% criterion (~1 ns absolute); in t5-base it already measured 7.2 ns. The gains of 0.88–0.92x (for example read_all/zidl_trusted/bank/10 and bank/100) are not wins of the plan: they suggest code layout noise, since no change optimized those paths.

Telemetry writing: a known and accepted deviation from the ±5% criterion (~1 ns absolute). write/zidl/telemetry, at least 3 interleaved runs, ns: t1-base 5.44 · t1-head 5.99 · t2-base 5.96 · t3-head 5.95 · t4-base 5.99 · t4-head 6.15 · current 6.47. The main step (+0.55 ns) came in with Task 1, not Task 4 (+0.15 ns, within the noise). The likely cause (not tested) is the same as for verified bank/1: the larger Error in the Result of finished(). Reference value: +0.7 ns (5.4 → 6.1 ns), measured in two sessions with the code before the #[inline] fix (5.3 → 6.1 in the small-scenario A/B; 5.4 → 6.1 in the t4 series). The sessions differ because the measurements were taken at different times and loads; the last session, with the code after the #[inline] fix, measured 6.47 ns (+1.0 ns relative to 5.44), at the 1 ns limit. The ~0.3 ns difference between 6.1 and 6.47 may be code layout (the #[inline] fix in zidl-schemas changes code generation) or load; it was not isolated. It was not optimized.

Wrap-up (Step 4)

• cargo test --workspace: 174 tests pass, 0 fail (also after the #[inline] fix).
• cargo build -p zidl --no-default-features: ok, 0 warnings.
• cargo clippy --workspace --all-targets: 5 warnings, all pre-existing (files identical to the pre-plan snapshot): zidl-bench/src/data.rs lines 73, 85 and 97 (is_multiple_of), zidl/src/pool.rs:57 (collapsible if) and zidl/tests/fuzz_props.rs:78 (unneeded if let). One new warning in zidl/tests/envelope.rs (a match with a single pattern, in a test of this feature) was fixed to if let. The envelope test still passes (23/23).