docs: sync ARCHITECTURE.md and python/README.md with the I143-I146 fixes

[Xof]

Summary

Ran a /codebase-docs pass to bring README/ARCHITECTURE/THEORY back in sync with the code after PR #89 (I143-I146 bug fixes). Both changed files are "Update" disposition — no restructuring, targeted factual corrections and additions only.

• ARCHITECTURE.md

  • Fixed the "Recovery on open" sequence diagram, which still depicted the pre-I143 (racy) create-vs-open flow: deciding create-vs-open from a pre-lock file_exists stat. It now shows the actual post-fix order — PageIo::open (flock) first, then the branch decided from post-lock page_count().
  • Added three landmines, each in the section a future editor would need it: the TOCTOU create-vs-open hazard (I143), the unvalidated/forgeable crypto-header stride field (I144), and the "every TransactionManager fatal-error path must route through poison_on_fatal" rule that I145 violated.
  • Everything else cross-checked against the diff (fsync count, DecryptionFailed-is-fatal, superblock byte ranges) was already correct — the stale bits were code comments, not the docs.

• python/README.md

  • Added DecryptionFailedError to the Fatal error table (new class from PR fix: four BUG-severity findings from the 2026-07-02 deep review (I143–I146) #89).
  • Added five pre-existing encryption operational-error classes that were never documented when encryption shipped: NoEncryptionKeyError, InvalidEncryptionKeyError, EncryptionNotSupportedError, NoFreeKeySlotError, LastKeySlotError.

Top-level README.md and THEORY.md were checked and need no changes (README's I146 fix already landed in #89; THEORY's narrative doesn't contradict anything in the recent diff).

Test plan

• Docs-only change; no code touched.
• Diagram and prose cross-checked against current source (src/lib.rs, src/transaction/recovery.rs, src/transaction/freemap.rs, python/src/errors.rs, src/error.rs).
• Build/test commands in README verified against .github/workflows/*.yml.

[github-actions]

🚦 Bench results: PR vs main

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

Scenario	Mode	Δ throughput	Worst Δ
ycsb-b	chisel-mem	-4.8%	p50 +15.6% ⚠️
ycsb-b	chisel-strict	+3.3%	p50 +7.9% ⚠️
document-store	chisel-strict	+4.1%	p50 +6.6% ⚠️
document-store	chisel-mem	-3.2%	—
document-store	redb-strict	+3.3%	—
document-store	sqlite-strict	+0.1%	—
mutation-log	chisel-mem	-1.4%	—
mutation-log	chisel-strict	+1.1%	—
mutation-log	redb-strict	+0.1%	—
mutation-log	sqlite-strict	-0.0%	—
ycsb-a	chisel-mem	-0.9%	—
ycsb-a	chisel-strict	+4.3%	—
ycsb-a	redb-strict	+0.0%	—
ycsb-a	sqlite-strict	-1.2%	—
ycsb-b	redb-strict	-0.7%	—
ycsb-b	sqlite-strict	-1.5%	—

Per-scenario detail (4 metrics × cells)

document-store

Mode	Throughput	p50	p95	p99
chisel-mem	33106 ops/s → 32058 ops/s (-3.2%)	5.4 µs → 5.6 µs (+4.7%)	68.1 µs → 69.9 µs (+2.7%)	296.5 µs → 309.8 µs (+4.5%)
chisel-strict	3051 ops/s → 3177 ops/s (+4.1%)	13.7 µs → 14.6 µs (+6.6%) ⚠️	764.7 µs → 741.5 µs (-3.0%)	1.98 ms → 2.03 ms (+2.6%)
redb-strict	4003 ops/s → 4134 ops/s (+3.3%)	12.4 µs → 12.9 µs (+4.0%)	441.7 µs → 416.2 µs (-5.8%)	1.31 ms → 1.28 ms (-2.2%)
sqlite-strict	5122 ops/s → 5126 ops/s (+0.1%)	21.3 µs → 21.1 µs (-1.3%)	333.7 µs → 338.8 µs (+1.5%)	1.37 ms → 1.36 ms (-0.6%)

mutation-log

Mode	Throughput	p50	p95	p99
chisel-mem	53139 ops/s → 52376 ops/s (-1.4%)	23.5 µs → 23.7 µs (+1.0%)	28.5 µs → 28.8 µs (+1.2%)	35.9 µs → 35.9 µs (+0.2%)
chisel-strict	1781 ops/s → 1799 ops/s (+1.1%)	284.6 µs → 285.3 µs (+0.2%)	606.0 µs → 594.7 µs (-1.9%)	20.34 ms → 19.75 ms (-2.9%)
redb-strict	1804 ops/s → 1806 ops/s (+0.1%)	138.3 µs → 139.2 µs (+0.7%)	213.5 µs → 217.3 µs (+1.8%)	35.52 ms → 35.17 ms (-1.0%)
sqlite-strict	5080 ops/s → 5080 ops/s (-0.0%)	91.2 µs → 91.1 µs (-0.1%)	250.4 µs → 252.8 µs (+1.0%)	328.5 µs → 331.8 µs (+1.0%)

ycsb-a

Mode	Throughput	p50	p95	p99
chisel-mem	39508 ops/s → 39133 ops/s (-0.9%)	41.2 µs → 41.7 µs (+1.1%)	59.4 µs → 58.6 µs (-1.5%)	75.4 µs → 80.4 µs (+6.7%)
chisel-strict	2271 ops/s → 2368 ops/s (+4.3%)	248.7 µs → 249.7 µs (+0.4%)	730.4 µs → 678.3 µs (-7.1%)	1.01 ms → 890.6 µs (-11.6%)
redb-strict	2679 ops/s → 2680 ops/s (+0.0%)	114.2 µs → 113.0 µs (-1.0%)	191.9 µs → 188.7 µs (-1.7%)	301.4 µs → 330.2 µs (+9.5%)
sqlite-strict	130634 ops/s → 129130 ops/s (-1.2%)	7.8 µs → 7.8 µs (+0.4%)	10.3 µs → 10.4 µs (+1.0%)	12.0 µs → 12.9 µs (+7.3%)

ycsb-b

Mode	Throughput	p50	p95	p99
chisel-mem	272627 ops/s → 259581 ops/s (-4.8%)	1.4 µs → 1.6 µs (+15.6%) ⚠️	41.4 µs → 41.7 µs (+0.8%)	47.7 µs → 50.6 µs (+6.1%)
chisel-strict	22400 ops/s → 23148 ops/s (+3.3%)	3.4 µs → 3.7 µs (+7.9%) ⚠️	252.2 µs → 254.1 µs (+0.8%)	565.5 µs → 576.5 µs (+2.0%)
redb-strict	27244 ops/s → 27064 ops/s (-0.7%)	3.1 µs → 3.2 µs (+2.9%)	114.5 µs → 117.6 µs (+2.7%)	177.3 µs → 181.4 µs (+2.3%)
sqlite-strict	159264 ops/s → 156942 ops/s (-1.5%)	6.3 µs → 6.5 µs (+2.0%)	8.5 µs → 8.6 µs (+1.7%)	10.9 µs → 11.0 µs (+1.2%)

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