docs(comments): add 5 why-comments to the encryption code

[Xof]

Summary

A constructive commenting pass (/comment-run) over the on-disk encryption code (#85) — the complement to the wrong-comment fixes in #87. Additive only: ADD/EXTEND per the standard, no existing comment text deleted or rewritten. Comments only, no behavior change.

Each of the five explains a non-obvious why a first-time reader could not infer from the code:

File	What it now explains
crypto/mod.rs	Argon2id's Version::V0x13 + 32-byte output are format-critical — changing either silently breaks unwrap of every existing Argon2id slot (data loss on a careless library bump).
superblock/mod.rs	The four bootstrap fields must stay cleartext because they are the AAD, and slot selection + AAD derivation run before any DEK exists — sealing them would be a chicken-and-egg deadlock.
page_cache.rs	The encrypted cold-load DecryptionFailed is fatal/poisoning, a peer of ChecksumMismatch, not a retryable operational error.
page_io.rs	set_stride swallows a seek error to 0 because its signature is infallible (bootstrap call site) and 0 makes reads fail closed (InvalidPageId).
spillway.rs	Spill writes are deliberately not fsynced — spillway content never crosses a transaction boundary, so a durability barrier would be wasted I/O.

Method & findings

Reviewed the 11 encryption production modules one agent at a time, each self-applying a strict why-not-what filter (rejecting anything that merely restates the code). 6 of 11 modules needed nothing added — the encryption code was already well-commented from its per-task review gates. The pass found 0 wrong comments (those were fixed in #87) and 0 bugs.

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

✅ No regressions detected

Scenario	Mode	Δ throughput	Worst Δ
document-store	chisel-mem	+2.6%	—
document-store	chisel-strict	+5.1%	—
document-store	redb-strict	+3.6%	—
document-store	sqlite-strict	+0.5%	—
mutation-log	chisel-mem	+0.2%	—
mutation-log	chisel-strict	+0.3%	—
mutation-log	redb-strict	-0.3%	—
mutation-log	sqlite-strict	-0.0%	—
ycsb-a	chisel-mem	-0.8%	—
ycsb-a	chisel-strict	+0.8%	—
ycsb-a	redb-strict	+0.1%	—
ycsb-a	sqlite-strict	-0.2%	—
ycsb-b	chisel-mem	+1.2%	—
ycsb-b	chisel-strict	-0.0%	—
ycsb-b	redb-strict	-1.1%	—
ycsb-b	sqlite-strict	-1.1%	—

Per-scenario detail (4 metrics × cells)

document-store

Mode	Throughput	p50	p95	p99
chisel-mem	32114 ops/s → 32937 ops/s (+2.6%)	5.6 µs → 5.5 µs (-1.8%)	70.0 µs → 68.7 µs (-1.9%)	308.5 µs → 296.8 µs (-3.8%)
chisel-strict	3007 ops/s → 3160 ops/s (+5.1%)	14.7 µs → 14.1 µs (-4.1%)	814.3 µs → 749.5 µs (-8.0%)	2.06 ms → 1.96 ms (-4.5%)
redb-strict	4000 ops/s → 4144 ops/s (+3.6%)	13.0 µs → 12.5 µs (-4.2%)	460.8 µs → 436.0 µs (-5.4%)	1.39 ms → 1.30 ms (-6.0%)
sqlite-strict	5123 ops/s → 5147 ops/s (+0.5%)	21.6 µs → 21.5 µs (-0.2%)	337.3 µs → 343.2 µs (+1.8%)	1.33 ms → 1.32 ms (-1.0%)

mutation-log

Mode	Throughput	p50	p95	p99
chisel-mem	53907 ops/s → 54010 ops/s (+0.2%)	23.3 µs → 23.3 µs (-0.2%)	26.6 µs → 26.5 µs (-0.3%)	35.9 µs → 35.7 µs (-0.3%)
chisel-strict	1774 ops/s → 1779 ops/s (+0.3%)	294.7 µs → 292.2 µs (-0.8%)	638.0 µs → 624.7 µs (-2.1%)	19.18 ms → 19.84 ms (+3.5%)
redb-strict	1805 ops/s → 1799 ops/s (-0.3%)	142.2 µs → 143.2 µs (+0.6%)	221.7 µs → 221.2 µs (-0.2%)	35.09 ms → 34.98 ms (-0.3%)
sqlite-strict	5032 ops/s → 5031 ops/s (-0.0%)	96.5 µs → 95.3 µs (-1.2%)	268.8 µs → 265.8 µs (-1.1%)	361.6 µs → 355.9 µs (-1.6%)

ycsb-a

Mode	Throughput	p50	p95	p99
chisel-mem	40092 ops/s → 39767 ops/s (-0.8%)	41.4 µs → 42.0 µs (+1.3%)	56.5 µs → 56.8 µs (+0.6%)	78.9 µs → 79.8 µs (+1.2%)
chisel-strict	2257 ops/s → 2275 ops/s (+0.8%)	254.1 µs → 253.2 µs (-0.4%)	726.2 µs → 703.5 µs (-3.1%)	1.66 ms → 1.20 ms (-27.9%)
redb-strict	2680 ops/s → 2682 ops/s (+0.1%)	115.2 µs → 116.6 µs (+1.2%)	198.0 µs → 199.0 µs (+0.5%)	302.0 µs → 307.8 µs (+1.9%)
sqlite-strict	131357 ops/s → 131039 ops/s (-0.2%)	7.7 µs → 7.7 µs (+0.0%)	10.3 µs → 10.3 µs (+0.1%)	13.2 µs → 12.3 µs (-7.0%)

ycsb-b

Mode	Throughput	p50	p95	p99
chisel-mem	270209 ops/s → 273549 ops/s (+1.2%)	1.6 µs → 1.4 µs (-9.0%)	41.5 µs → 41.3 µs (-0.4%)	47.2 µs → 47.6 µs (+0.9%)
chisel-strict	22125 ops/s → 22121 ops/s (-0.0%)	3.7 µs → 3.6 µs (-3.5%)	258.7 µs → 262.0 µs (+1.3%)	641.0 µs → 662.4 µs (+3.3%)
redb-strict	27054 ops/s → 26744 ops/s (-1.1%)	3.1 µs → 3.1 µs (-2.9%)	119.4 µs → 115.7 µs (-3.1%)	192.4 µs → 180.1 µs (-6.4%)
sqlite-strict	160466 ops/s → 158775 ops/s (-1.1%)	6.3 µs → 6.4 µs (+1.6%)	8.5 µs → 8.5 µs (+0.5%)	10.8 µs → 10.7 µs (-0.7%)

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