docs: fix 7 wrong comments from the commenting pass (stale facts from the freemap rewrite + extraction)

[Xof]

Follow-up to #83 (the commenting pass), fixing the 7 actively-wrong comments it surfaced. These are almost all comment-rot from the multi-page-freemap rewrite and the transaction.rs extraction — the code is correct, the prose drifted to describe the old single-page-freemap / two-fsync world.

Fix	What was wrong
page_io.rs PageIo::fsync (×2)	"twice per commit" → three fsyncs (I28 pre-drain + data + superblock)
page_cache.rs flush Phase-1b	"two-fsync commit cost" → three-fsync
defrag.rs steps 3 & 6	"net drop in data-page count" → set difference of page-ID snapshots (the file header already said so)
freemap_tree.rs is_free	"only #[cfg(test)] consumers" was false — reclaim_orphans is a production caller; also dropped the now-incorrect #[allow(dead_code)]
freemap.rs header	current_freemap → the COW freemap tree (that flat-bitmap name no longer exists)
page_cache.rs new_page (×2)	freed pages reclaimed by the freemap reuse path, not only defrag; rollback is discard_all_dirty+truncate, not the dead discard()
python/errors.rs (×2)	"matches is_fatal() exactly" → note PoisonedError is a deliberate FatalError subclass even though is_fatal() excludes Poisoned

Verified: 578 Rust / 119 pytest green; clippy --all-targets clean (confirms the is_free #[allow(dead_code)] removal is safe — it's genuinely used); fmt clean.

One agent-flagged item (page_cache.rs:515 "second of three fsyncs") was a false positive — already correct — so it was left untouched.

[github-actions]

🚦 Bench results: PR vs main

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

Scenario	Mode	Δ throughput	Worst Δ
mutation-log	chisel-strict	+1.2%	p99 +14.0% ⚠️
mutation-log	sqlite-strict	-2.2%	p99 +11.4% ⚠️
document-store	chisel-mem	-2.5%	—
document-store	chisel-strict	-0.2%	—
document-store	redb-strict	+2.9%	—
document-store	sqlite-strict	+0.0%	—
mutation-log	chisel-mem	+0.1%	—
mutation-log	redb-strict	-0.0%	—
ycsb-a	chisel-mem	-4.6%	—
ycsb-a	chisel-strict	+1.9%	—
ycsb-a	redb-strict	+0.1%	—
ycsb-a	sqlite-strict	+8.5%	—
ycsb-b	chisel-mem	-1.7%	—
ycsb-b	chisel-strict	+2.9%	—
ycsb-b	redb-strict	+0.1%	—
ycsb-b	sqlite-strict	+0.4%	—

Per-scenario detail (4 metrics × cells)

document-store

Mode	Throughput	p50	p95	p99
chisel-mem	19685 ops/s → 19198 ops/s (-2.5%)	13.4 µs → 13.7 µs (+2.1%)	135.2 µs → 138.6 µs (+2.5%)	606.6 µs → 630.6 µs (+4.0%)
chisel-strict	2623 ops/s → 2617 ops/s (-0.2%)	21.7 µs → 21.6 µs (-0.2%)	1.24 ms → 1.24 ms (+0.2%)	2.88 ms → 2.91 ms (+1.1%)
redb-strict	3995 ops/s → 4112 ops/s (+2.9%)	18.5 µs → 18.9 µs (+2.2%)	686.2 µs → 644.2 µs (-6.1%)	1.80 ms → 1.71 ms (-5.2%)
sqlite-strict	5095 ops/s → 5097 ops/s (+0.0%)	20.1 µs → 20.9 µs (+3.9%)	497.0 µs → 493.3 µs (-0.8%)	1.52 ms → 1.51 ms (-1.0%)

mutation-log

Mode	Throughput	p50	p95	p99
chisel-mem	47152 ops/s → 47196 ops/s (+0.1%)	25.8 µs → 25.9 µs (+0.5%)	31.2 µs → 30.7 µs (-1.5%)	39.7 µs → 39.5 µs (-0.6%)
chisel-strict	1596 ops/s → 1614 ops/s (+1.2%)	581.7 µs → 570.3 µs (-2.0%)	1.08 ms → 1.04 ms (-4.0%)	4.69 ms → 5.35 ms (+14.0%) ⚠️
redb-strict	1802 ops/s → 1801 ops/s (-0.0%)	226.8 µs → 225.1 µs (-0.7%)	411.3 µs → 420.9 µs (+2.3%)	26.29 ms → 26.17 ms (-0.5%)
sqlite-strict	4284 ops/s → 4189 ops/s (-2.2%)	140.9 µs → 141.9 µs (+0.7%)	414.5 µs → 425.4 µs (+2.6%)	651.4 µs → 725.9 µs (+11.4%) ⚠️

ycsb-a

Mode	Throughput	p50	p95	p99
chisel-mem	33204 ops/s → 31677 ops/s (-4.6%)	40.4 µs → 42.4 µs (+4.9%)	69.8 µs → 70.6 µs (+1.2%)	94.7 µs → 94.6 µs (-0.1%)
chisel-strict	1983 ops/s → 2021 ops/s (+1.9%)	372.2 µs → 356.1 µs (-4.3%)	1.18 ms → 1.14 ms (-3.1%)	2.88 ms → 3.11 ms (+8.2%)
redb-strict	2677 ops/s → 2679 ops/s (+0.1%)	191.3 µs → 188.3 µs (-1.6%)	334.8 µs → 328.2 µs (-2.0%)	1.08 ms → 994.4 µs (-8.1%)
sqlite-strict	136583 ops/s → 148256 ops/s (+8.5%)	7.0 µs → 6.9 µs (-1.3%)	12.1 µs → 8.8 µs (-26.9%)	17.8 µs → 12.5 µs (-29.7%)

ycsb-b

Mode	Throughput	p50	p95	p99
chisel-mem	165601 ops/s → 162787 ops/s (-1.7%)	4.2 µs → 4.3 µs (+2.9%)	48.1 µs → 48.2 µs (+0.1%)	54.2 µs → 56.0 µs (+3.2%)
chisel-strict	18424 ops/s → 18966 ops/s (+2.9%)	6.0 µs → 5.9 µs (-1.2%)	383.9 µs → 367.0 µs (-4.4%)	1.02 ms → 995.5 µs (-2.5%)
redb-strict	27081 ops/s → 27121 ops/s (+0.1%)	2.8 µs → 2.8 µs (+1.8%)	188.7 µs → 184.5 µs (-2.2%)	291.7 µs → 282.9 µs (-3.0%)
sqlite-strict	180328 ops/s → 181025 ops/s (+0.4%)	5.5 µs → 5.5 µs (+0.5%)	7.7 µs → 7.5 µs (-2.5%)	10.3 µs → 9.8 µs (-5.3%)

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