[Explicit Transaction P1-2] Reframe TP WAL into per-commit frames with validated recovery

[zhanglei1949]

Background

The current TP WAL writes one 8-byte header per append (timestamp | type | length). This has several structural weaknesses for the explicit-transaction work:

• No whole-commit integrity. A commit spans multiple appends; a torn write or bit flip in the middle of a commit is indistinguishable from valid data, and checksums do not exist at all.
• Fragile EOF semantics. The file is preallocated to 1 GiB and recovery must guess where the logical end is; mid-file inconsistency cannot be reliably separated from crash residue at the tail.
• Untyped recovery errors. Corruption surfaces as generic IO exceptions without path/offset/timestamp context.

Goal

Reframe the TP WAL so that one commit = one complete, self-describing frame with end-to-end integrity, and make crash recovery validate before replay with typed errors. This is P1-2 of the explicit transaction support track; the sync/durability policy split (pre/post marker) is deliberately left to P1-3.

Scope

• Framed format v1
  • 24B file header per WAL file; checkpoint ownership derived from the checkpoint's wal directory, not header fields.
  • 24B frame header (magic, record kind, commit timestamp, payload length) + payload + 8B trailer (commit marker + CRC32C over header, payload and marker). The marker is written last, so a present trailer proves the frame was fully persisted.
  • Record kinds: kInsert / kCowUpdate / kCompact. AP and embedded paths write no WAL.
• Writer
  • Marker-last commit protocol; a failed frame is rolled back to the clean logical EOF.
  • Real logical EOF: no preallocation / zero padding.
• Parser / recovery
  • Validate-first protocol: parse and checksum all files of the current checkpoint up front, merge frames by commit timestamp, replay in global order.
  • Typed WalRecoveryErrorKind (unsupported format / corrupted frame / duplicate timestamp / unknown record kind) with path+offset+timestamp context.
  • Only an incomplete trailing frame (an uncommitted, crashed transaction) is discarded; any earlier inconsistency is a hard error.
• Tests (codec unit tests, crash-injection subprocess tests, replay e2e incl. post-compaction commits) and user documentation.

Out of scope

• Pre/post-marker sync policy and group commit (P1-3).
• Recovery throughput optimizations (parallel validation, hardware-accelerated CRC path).

[github-actions]

🤖 Auto-triage: linked as sub-issue of #86 — Refactor UpdateTransaction (confidence: high).

Reason: The issue is a deep refactor of the WAL mechanics, commit framing, and crash recovery validation, which squarely falls under the UpdateTransaction umbrella (#86) scope for WAL and transaction durability.

Auto-applied: type → Task; labels → transaction, store

If this is wrong, please unlink and re-assign — your correction improves this bot.