writeonce/docs/superpowers/specs
shoney.arickathil 75aedf1216 docs(spec): WAL group commit — databasev2 4 part A
Brainstormed 2026-08-28. The iteration is split: part A batches, part B
(io_uring submission) is deferred until A's measurement says whether the
blocking boundary still dominates.

The story's premise needed correcting first:

- it says "replace fsync-per-commit with io_uring group-commit", but the
  engine commits per STATEMENT — db.c calls wo_wal_commit right after
  every append, all six sites, so each row change is one pwrite + one
  fdatasync
- so two independent wins were being carried as one, and only the second
  needs io_uring. The staging buffer already holds any number of records;
  today it never holds more than one. Part A is mostly deleting calls
- iteration 22's numbers say A is where the payoff is: durable writes
  4460 ops/s, mixwrite 1023 ops/s p99 664us, against 1.28M ops/s reads

Forks settled:

- batch boundary is QUEUE-DRAIN, not the tick this story had recorded: a
  tick adds latency to a lone writer, taxing an idle system to serve a
  busy one. Queue-drain self-tunes and needs no knob
- shard 0 holds each reply envelope instead of sending it, commits once
  when the queue empties, then releases all — so a writer is acked after
  the barrier carrying ITS record, which today is true only because
  every batch has one member
- a failure between "RAM mutated" and "record durable" is a FATAL,
  diagnosed abort. This replaces uneven behaviour that already exists:
  insert rolls back, update and delete do not and say so in a comment
  ("RAM ahead of disk"). Batching would have multiplied that
- consequence stated, not slipped in: WO_T_IO leaves the write path
- no batch cap initially; peak staged bytes is measured so the question
  is settled by a number

One gap disclosed rather than hidden: forcing a real fdatasync failure
needs mount privileges, so the unit test proves the error is DETECTED and
the abort itself stays covered by inspection.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-28 07:48:11 +02:00
..
2026-08-01-oop-compiler-vm-design.md docs: iteration 7b migration — amend the normative docs (Phase 4) 2026-08-19 17:11:35 +02:00
2026-08-01-systems-track-design.md docs: status board at docs/00-status.md; gap-closure spec applied; recover lost doc 2026-08-10 23:42:26 +02:00
2026-08-03-blue-green-vm-design.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
2026-08-07-logwatcher-sample-and-principles-design.md docs: compiler front-end specifications and plans (Tasks 2-6) 2026-08-10 09:11:04 +02:00
2026-08-10-logwatcher-gap-closure-design.md docs: status board moved to docs/stories/00-status.md 2026-08-21 10:07:20 +02:00
2026-08-11-inferred-gc-mark-sweep-design.md feat: milestone 1 complete — .wob emitter, conformance corpus, single binary; GC redesign specced 2026-08-11 19:31:26 +02:00
2026-08-15-table-relations-query-design.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
2026-08-18-web-framework-design.md docs: sync superpowers specs/plans to hold decision 2026-08-21 05:00:56 +02:00
2026-08-20-library-kind-internal-design.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
2026-08-20-memory-db-features-design.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
2026-08-20-shard-fiber-arc-design.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
2026-08-21-db-bench-design.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
2026-08-23-chat-websocket-actor-lifecycle-design.md docs: audit all markdown against the code, fix findings, flatten status folders 2026-08-26 19:20:22 +02:00
2026-08-23-net-seams-park-design.md feat: iteration 35 — net seams + the serving slice (fiber-per-connection) 2026-08-23 08:04:32 +02:00
2026-08-28-wal-group-commit-design.md docs(spec): WAL group commit — databasev2 4 part A 2026-08-28 07:48:11 +02:00