Generated code (zidlc) against the hand-written code

Historical document. Written on 2026-11-13, when the project was called zidl (later Graven, with the compiler gravenc).

Date: 2026-11-13 · Plan 2 (the compiler), Task 8: zidl-schemas drops the hand-written code and includes the code generated by zidlc via build.rs. Machine: Intel Core i9-14900HX, Linux 7.3, rustc 1.94.0, --release ([profile.bench] with debug = true). Machine load: 1-minute average between 1.7 and 4.6 during the runs (a browser open in the background).

The plan's criterion: within ±5% of the pre-plan state, measured with interleaved A/B runs.

Methodology

• A (pre-plan): the pre-plan snapshot, the tree before Task 1 of this plan (hand-written code, already with the #[inline] fix from the envelope report). The snapshot has no Cargo.lock. I used the current Cargo.lock, so the third-party dependencies (criterion, bytes, flatbuffers, capnp) have the same versions on both sides.
• B (generated): the current tree.
• C (t8-base, control): the t8-base snapshot, that is, the end of Task 7: hand-written code over the current runtime. It is the control that isolates Task 8 (C → B) from Tasks 1–7 (A → C).
• The bench binaries (cargo bench -p zidl-bench --bench codec --no-run) were built once per side, each with its own CARGO_TARGET_DIR, and then run directly. The zidl-bench crate is identical on all three sides.
• Interleaved: in each round, each group runs first on one side and right after on the other. The order of the sides alternates between rounds. Each value is the median of 3 rounds.
• Reduced times, equal on both sides: --warm-up-time 1 --measurement-time 3 --noplot. The criterion default is 3 s and 5 s; I reduced them to fit in the time available.
• Filters: only the zidl rows. ^write/zidl, ^read_all/zidl, ^read_one/zidl, ^read_all_verified/zidl and ^envelope/ (this whole group is zidl).

Commands (equivalent): cargo bench -p zidl-bench --bench codec -- <group> --warm-up-time 1 --measurement-time 3 for write, read_all, read_one, read_all_verified and envelope.

First measurement: two real code differences

In the first A/B round (the generated code as Task 7 left it), two groups of rows were consistently outside ±5%: the 3 measurements of B were above the 3 of A.

A 3-sided A/B (A, C and B, interleaved, median of 3) showed that these differences came from Task 8, that is, from generated against hand-written code over the same runtime. Examples: envelope/read_verified_one/bank/10 measured C 87.3 and B 101.6 (+16%); read_all_verified/zidl/chunk/64 measured C 4.7 and B 5.3 (+14%).

Bisection (binaries with a single generated file swapped into t8-base, interleaved, median of 3, ns):

Causes and fixes, both in the codegen (crates/zidl-compiler/src/codegen/read.rs):

1. The verify order of bank.Transaction. The generated code verified the fields in ID order (entries @5 and only then note @6). The hand-written code verified note first and then the list. Just swapping the order in a generated bank.rs brings back the hand-written time (table above). Fix: the generated FromTable::verify now visits the leaf data first (string, bytes, lists without tables) and then the fields that descend (a nested table, a union, [Table]), in ID order within each group. The helper function is descends(). This changes no result: the precedence between errors is not normative (spec §7.5) and the budget's sum does not depend on the order (§7.3). The gates still pass: conformance vectors, budget_totals_unchanged and the mutation gate.
2. The shape of the charge for a required string/bytes (stream.Chunk.data). The generated code emitted if let Some(b) = self.0.bytes(..)? { ctx.charge(4 + b.len())?; }. The hand-written code emitted ctx.charge(4 + data.len())? unconditionally. LLVM orders the blocks differently in the two cases. Fix: for a required field, the generated code now emits ctx.charge(4 + self.0.bytes(..)?.unwrap_or(&[]).len())? (and the equivalent with str). The unwrap_or arm is unreachable, because from_ref already rejected the absent pointer with Missing. With that, the machine code of read_all_chunk_verified is identical to the hand-written one.

The snapshots in crates/zidl-compiler/tests/snapshots were re-recorded. The diff contains only these two changes, plus the sentence in the verify doc.

Proof that the code is the same

I disassembled (objdump -d) the 116 functions with zidl in their name from the bench binary (the zidl_bench::zidl_impl::* ones with everything inlined into them, plus the runtime functions that were not inlined). I compared the final binary (B) with the hand-written t8-base (C), normalizing addresses and the numbers of anonymous symbols.

• 111 of 116 functions are identical instruction for instruction, among them every bank, frame and chunk path: write, read_all, read_one, verified, trusted, envelope.
• The 5 that differ are the telemetry ones (read_all_telemetry, read_all_telemetry_verified, read_one_telemetry, verified_one_telemetry, from_bytes_one_telemetry), with +2 instructions each. The cause is the order of TELEMETRY_REQ: the generated code lists the required fields in ID order, the same order as the conformance interpreter, per a Task 3 decision. The hand-written code put the Req::Slot of humidity first. It only changes where the Truncated check of the partial slot sits. I did not change it. The measured effect is ~0.1–0.2 ns, with a sign that varies between rounds (final table: read_one/telemetry −2.4%, read_all_verified/telemetry +14%, write/telemetry −11%).

The rest is code layout

With identical machine code, the remaining differences come from layout (the address and alignment of the functions and hot loops in the binary). Evidence:

• Same code, different binaries. In the bisection, the "only bank generated" binary (K) has a read_all_chunk_verified byte-for-byte identical to C's, and it still measured 5.34 ns against 4.82 (+11%). Only the function's address changed (0x139730 vs 0x1396c0).
• Same code, same address, different sessions. read_all_bank_verified is identical (and at the same address) in the binary after fix 1 and in the final binary, and it is also identical to the hand-written one. Against the pre-plan measured in the same session, it measured −2.8% (bank/10) in one round and +12.4% in the other. Between the two binaries only the stream code changed.
• Rows nothing changed. Between the round after fix 1 and the previous one, read_all/zidl/frame/500 went from +18% to +42% against the pre-plan. The game code did not change in that swap.
• Aligned loops. With RUSTFLAGS="-C llvm-args=-align-loops=64" on both sides (pre-plan and generated, before fix 2), read_all/zidl/frame/500 dropped from +38–42% to +7%, read_all_verified/zidl/frame/500 to +5%, read_one/zidl/frame/* stayed at −16% and read_all_verified/zidl/bank/* at −4 to −6%.

So the remaining differences against the pre-plan mix two things: (a) the runtime changes of Tasks 1–7 (A → C, different machine code, outside the scope of this measurement) and (b) layout. In Task 8 (C → B) the machine code is the same, except for telemetry.

Final table (pre-plan × generated, after both fixes)

Final binary, interleaved A/B, median of 3 rounds, ns. ⚠ = outside ±5%. See the previous sections: in the bank, frame and chunk rows, the generated machine code is identical to the hand-written one (t8-base).

Verdict

The next plan that wants stable numbers against snapshots should pin the layout. Options: build both sides with -C llvm-args=-align-loops=64 (or -align-all-functions), or compare instruction counts (perf stat -e instructions) instead of time. This kind of measurement can be off by ±10–40% because of layout in this binary.

Note: the final 5-sided round (A, C, B and A/B with aligned loops, every group) was cut short by the machine-time limit. The final table comes from the last complete 2-sided round. The control numbers (C, K, aligned loops) come from the focused rounds described above.