docs(comments): fix 10 stale/wrong comments on the encryption surface

[Xof]

Summary

An adversarial commenting pass over the on-disk encryption surface (the code merged in #85, which never had a dedicated comment review). Comments only — no behavior change. Ten findings, each surfaced by a per-module reviewer and then confirmed by a second agent that tried to refute it, so false positives were dropped before reaching this diff.

Fixes

Wrong facts (would mislead a reader):

• crypto/mod.rs — derive_kek's # Errors said BadKeyLength fires "if kdf == Hkdf and the raw key bytes are empty," but the empty-key check runs unconditionally, before the KDF match and applies to both Raw and Passphrase.
• superblock/mod.rs (×2) — the sealed-superblock comments said sensitive scalars at 16..52 are zeroed, but page_size is written in cleartext at 48..52; the zeroed range is 16..48. (The serialize code and the plaintext-leak test were already correct — only the comments were off by 4.)
• python/src/db.rs — the key-coercion doc claimed an empty/wrong raw key "raises BadKeyLength via to_py_err," but every CryptoError maps to ChiselError::InvalidEncryptionKey → InvalidEncryptionKeyError; there is no BadKeyLength Python error.
• transaction/recovery.rs — "Slot 0 was written last in the loop" — it's written first (i=0, at the highest counter superblock_count-1).
• transaction/keys.rs (test) — a test comment computed txn_counter=3 after fresh_encrypted; it's actually 2 (create leaves superblock_count-1 = 1, one commit bumps to 2).

Stale (drifted from the code):

• page_io.rs — module header still said "Two fsyncs per commit"; the commit protocol does three (I28 pre-drain + data + superblock), as the same file's own fsync doc already states. (This is the header docs: fix 7 wrong comments from the commenting pass (stale facts from the freemap rewrite + extraction) #84 missed.)
• transaction/commit.rs + transaction/lifecycle.rs — CommitCtx is described as bundling "ten pieces of manager state"; the encryption work added cipher and crypto_header, making it twelve.
• python/src/errors.rs — the exception-hierarchy comment omitted DecryptionFailedError from the FatalError tier.

Not fixed (transparency)

Three further candidate findings could not be adversarially verified (their verify agents hit a transient rate limit). On manual inspection none was clearly wrong — two describe an unexercised "unknown crypto algorithm id" error path, one is accurate phase-language — so they were left as-is rather than rewritten on an unverified claim.

Verification

Comment-only; cargo build, full cargo test, cargo clippy --workspace -- -D warnings, and cargo fmt --check all clean.

[github-actions]

🚦 Bench results: PR vs main

⚠️ 4 regression(s) detected across 2 scenario/mode pair(s)

Scenario	Mode	Δ throughput	Worst Δ
ycsb-a	redb-strict	-0.1%	p99 +74.6% ⚠️
ycsb-a	chisel-mem	-13.4%	p50 +24.7% ⚠️
document-store	chisel-mem	-4.9%	—
document-store	chisel-strict	+46.7%	—
document-store	redb-strict	+4.8%	—
document-store	sqlite-strict	+23.1%	—
mutation-log	chisel-mem	-1.5%	—
mutation-log	chisel-strict	+0.2%	—
mutation-log	redb-strict	+0.0%	—
mutation-log	sqlite-strict	+16.8%	—
ycsb-a	chisel-strict	-3.6%	—
ycsb-a	sqlite-strict	+1.9%	—
ycsb-b	chisel-mem	+0.9%	—
ycsb-b	chisel-strict	+17.7%	—
ycsb-b	redb-strict	-0.2%	—
ycsb-b	sqlite-strict	+2.2%	—

Per-scenario detail (4 metrics × cells)

document-store

Mode	Throughput	p50	p95	p99
chisel-mem	31091 ops/s → 29557 ops/s (-4.9%)	5.5 µs → 5.5 µs (+0.2%)	71.3 µs → 75.5 µs (+5.9%)	330.5 µs → 329.5 µs (-0.3%)
chisel-strict	1670 ops/s → 2450 ops/s (+46.7%)	15.1 µs → 13.9 µs (-8.2%)	2.51 ms → 1.52 ms (-39.4%)	4.07 ms → 2.75 ms (-32.3%)
redb-strict	3945 ops/s → 4134 ops/s (+4.8%)	19.3 µs → 19.4 µs (+0.5%)	877.2 µs → 710.6 µs (-19.0%)	2.21 ms → 1.94 ms (-12.1%)
sqlite-strict	4133 ops/s → 5088 ops/s (+23.1%)	21.9 µs → 21.4 µs (-2.5%)	894.8 µs → 597.1 µs (-33.3%)	2.57 ms → 1.59 ms (-37.9%)

mutation-log

Mode	Throughput	p50	p95	p99
chisel-mem	48089 ops/s → 47388 ops/s (-1.5%)	26.4 µs → 26.7 µs (+1.1%)	29.9 µs → 30.6 µs (+2.3%)	39.4 µs → 40.0 µs (+1.4%)
chisel-strict	1084 ops/s → 1086 ops/s (+0.2%)	856.2 µs → 850.7 µs (-0.6%)	2.21 ms → 2.26 ms (+2.2%)	4.18 ms → 4.35 ms (+4.0%)
redb-strict	1805 ops/s → 1806 ops/s (+0.0%)	264.1 µs → 252.2 µs (-4.5%)	631.3 µs → 581.0 µs (-8.0%)	19.21 ms → 20.42 ms (+6.3%)
sqlite-strict	2876 ops/s → 3359 ops/s (+16.8%)	199.5 µs → 177.6 µs (-11.0%)	821.4 µs → 653.5 µs (-20.4%)	1.38 ms → 1.27 ms (-8.5%)

ycsb-a

Mode	Throughput	p50	p95	p99
chisel-mem	39601 ops/s → 34294 ops/s (-13.4%) ⚠️	39.2 µs → 48.8 µs (+24.7%) ⚠️	61.3 µs → 71.4 µs (+16.6%) ⚠️	91.1 µs → 90.0 µs (-1.2%)
chisel-strict	1437 ops/s → 1386 ops/s (-3.6%)	413.5 µs → 420.1 µs (+1.6%)	2.21 ms → 2.25 ms (+1.8%)	3.70 ms → 3.83 ms (+3.4%)
redb-strict	2679 ops/s → 2676 ops/s (-0.1%)	197.2 µs → 198.7 µs (+0.8%)	464.1 µs → 498.1 µs (+7.3%)	1.49 ms → 2.61 ms (+74.6%) ⚠️
sqlite-strict	146108 ops/s → 148896 ops/s (+1.9%)	6.9 µs → 6.9 µs (-0.4%)	9.0 µs → 8.7 µs (-3.2%)	11.3 µs → 10.2 µs (-9.4%)

ycsb-b

Mode	Throughput	p50	p95	p99
chisel-mem	244976 ops/s → 247218 ops/s (+0.9%)	1.6 µs → 1.6 µs (+1.3%)	49.2 µs → 41.4 µs (-15.7%)	54.8 µs → 54.2 µs (-1.1%)
chisel-strict	11913 ops/s → 14024 ops/s (+17.7%)	3.5 µs → 3.1 µs (-11.3%)	464.3 µs → 458.9 µs (-1.2%)	1.98 ms → 1.73 ms (-12.5%)
redb-strict	27028 ops/s → 26982 ops/s (-0.2%)	3.0 µs → 3.0 µs (+1.7%)	196.7 µs → 195.2 µs (-0.8%)	397.7 µs → 398.3 µs (+0.2%)
sqlite-strict	177542 ops/s → 181366 ops/s (+2.2%)	5.6 µs → 5.5 µs (-1.1%)	8.0 µs → 7.5 µs (-6.3%)	11.0 µs → 9.7 µs (-11.9%)

_{Generated by chisel-bench-diff at 2026-07-01T19:23:56Z. Compares PR HEAD against main. Never blocks merge — signal, not gate. Thresholds: throughput 5%, p50 5%, p95 10%, p99 10%.}