writeonce/docs
shoney.arickathil 882c1f7d24 feat(db2-keys): task 7 — measure resident: keys against swapping
- two tables identical except the annotation, 200k rows, 40k reads in
  one key order, WAL on ext4 (not /tmp, which is tmpfs here and would
  have put the log in RAM), rootless cgroup v2 cap
- WIDE shape, 2.55x smaller resident set: 34.4 MB vs 87.5 MB. That is
  the real win and the thing the mode was built for
- under a 48 MB cap (between the two resident sets): keys 19635 ops/s
  vs all 12854 — only 1.53x faster than letting the kernel swap
- degradation is far gentler though: all collapses 105x from its own
  uncapped throughput, keys 16x
- costs 4.2x read throughput when memory is not tight, and writes are
  markedly slower — the keys fill did not finish in 2 min where the
  resident fill plus 40k reads did. No design doc had costed writes
- THE UNANTICIPATED FINDING: cgroup limits charge the PAGE CACHE, so
  moving rows to a file does not escape a container memory limit. WAL
  37 MB + RSS 34 MB cannot both live under a 48 MB cap, so every pread
  reaches disk. The premise "the page cache will hold the hot rows"
  fails in exactly the deployment this targets
- first attempt used Int-only rows and showed parity; recorded, because
  drop_payload frees a field's VALUE and an Int's value is its inline
  slot word, so that shape cannot benefit and would have condemned the
  feature for the wrong reason
- verdict: keep it, to fit ~2.5x more data in given RAM — not to make
  an over-capacity table fast

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
(cherry picked from commit 7cba9b1174b0bf581314b3147e25cc49e6f49464)
2026-08-30 20:38:03 +02:00
..
examples feat(db2-keys): task 7 — measure resident: keys against swapping 2026-08-30 20:38:03 +02:00
guides docs(db2-delta): guide to log-structured rows for a new reader 2026-08-30 20:38:03 +02:00
plan Merge master into db-residency-doctrine — and close the two half-exposed features 2026-08-29 10:14:25 +02:00
stories feat(db2-keys): task 7 — measure resident: keys against swapping 2026-08-30 20:38:03 +02:00
superpowers docs(db2-chains): spec + story for bounding a row's delta chain 2026-08-30 20:38:03 +02:00
00-code-review.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
00-databasev2-chain-review.md fix(db2-keys): delete on a keys-resident table was memory corruption 2026-08-30 20:37:27 +02:00
00-dependency-graph.md docs(24): T10 closeout — stories done, board, graph, ledger, CODE-LOGIC 2026-08-28 00:06:31 +02:00
00-doc-audit.md refactor(porch): name the web framework porch, fix the wo.toml identifier claim 2026-08-26 19:36:34 +02:00
00-link-audit.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
00-principles.md docs: amend principle 7 — the log is authoritative, residency is declared 2026-08-26 22:42:27 +02:00
01-problem.md docs: remove stale old-runtime docs; abandon the ##ui frontend track 2026-08-17 20:06:36 +02:00
08-project-structure.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
2026-08-27-chat-drain-finding.md fix(chat gate): every leg starts its own server — and it found a real bug 2026-08-27 23:27:46 +02:00