feat(pinax): implement Phase 01 pager, buffer pool, and B+tree

[forkwright]

Summary

Lands ROADMAP.md Phase 01 ("pager + buffer pool + B-tree") on top of #10's workspace + lexis scaffold. Every success criterion in that phase gets a real test: open a file, CRUD rows by integer key, survive crash-and-reopen, page-format checksums verified with corruption detected, buffer pool handles a database larger than its capacity.

Base branch is #10's feat/2-phase01-workspace-lexis, not main — this PR should merge (or be rebased) after #10.

Page format (Decision 2)

• PageSize validates the five locked sizes (4096 / 8192 / 16384 / 32768 / 65536), default 4096.
• Every page — meta, leaf, interior, overflow — carries a trailing 8-byte XxHash3-64 checksum (xxhash-rust, pure Rust, matching Turso's algorithm choice per the design-prior citation in PLAN.md).
• max_local = usable_space - 35, the SQLite formula PLAN.md names verbatim. Rows over that threshold spill into an overflow page chain (own encoding, not SQLite's varint format — Decision 1 says pinax owns its on-disk encoding).

Pager (Decision 1)

The meta/header lives in two checksummed 4 KiB slots (page ids 0 and 1) at fixed file offsets, independent of the database's configured page size — bootstrap has to learn page_size from the meta page before it can compute anything page_size-relative, so the meta region's own layout can't depend on that value.

Every mutation is copy-on-write: nothing already reachable from the active meta page is ever overwritten in place, every change targets a freshly allocated page id. Commit fsyncs the data pages, writes the other meta slot with an incremented txn_id, fsyncs again, then flips which slot is active. A crash at any point leaves the previously-committed slot intact — there's nothing to roll back because nothing reachable ever changed. This is the mechanism the crash-and-reopen test demonstrates, and it needs no WAL (that's Phase 02).

Deliberate Phase 01 scope limit: no freelist reclamation. A page retired by a transaction's copy-on-write is still referenced by the currently active meta until that transaction's own meta write lands, so reusing its id before that point would corrupt the still-authoritative pre-transaction state on a crash in between. Reusing an id retired by an earlier, already-committed transaction is safe in principle, but Phase 01's allocator is a pure bump counter that doesn't attempt it — the database grows monotonically instead. None of Phase 01's acceptance criteria require space reclamation; this is real, deferred scope, not a correctness gap.

Buffer pool

Capacity-bounded LRU cache over the pager. Because every write is copy-on-write, get only ever needs to clone a page's bytes out — nothing is ever checked out or held mutably against the pool, so eviction has no aliasing hazard and needs no pinning bookkeeping. A page evicted mid-operation is safe to flush early for the same reason a crash mid-operation is safe: it isn't reachable from the active meta yet either way.

The "buffer pool handles a database larger than RAM" test models RAM as pool capacity (8 pages), inserts 4,000 rows to produce a tree many times that size on disk, and reads every row back correctly after eviction-and-reload cycles.

B+tree

Slotted leaf and interior pages (SQLite-shape layout per Decision 1, own encoding). Insert/delete path-copy: the whole root-to-leaf path gets a fresh id chain, propagated bottom-up (apply_result_to_interior), with splits handled at both leaf and interior levels. Rows are encoded as lexis::Value tuples — lexis's own Cargo.toml names this as its Phase 01 exit criterion ("Phase 1 pager adopts lexis::Value for on-disk row encoding").

Deliberate Phase 01 scope limit: delete does not merge/rebalance underflowing nodes. delete's interior-propagation step only ever repoints an existing child pointer, it never removes a separator key, so an ancestor's key count is monotonically non-decreasing — the tree stays correct (an empty leaf is a valid leaf) but not space-optimal under a delete-heavy workload. None of Phase 01's acceptance criteria require this; general merge-on-underflow is real follow-up scope for a later phase, not silently dropped.

Testing

• tests/phase01_acceptance.rs: one test per ROADMAP.md Phase 01 criterion, named and cited against the exact wording. The corruption test flips a byte on disk and asserts a typed Corruption error — the negative case, not just the intact-page happy path. The crash test drops a Database mid-stream with no explicit shutdown and reopens.
• Every module carries colocated #[cfg(test)] mod tests for its own internals — codec bounds-checking, checksum round-trip and flip-detection, meta-slot fallback on corruption (a second, independent demonstration of crash-safety: corrupt the active meta slot directly and confirm Pager::open falls back to the still-valid prior slot), pager crash-before-commit, B+tree CRUD/split/overflow/negative-key/reopen, buffer-pool eviction-flushes-dirty and corrupted-page-surfaces-on-read.
• Every public fallible constructor and every error variant used in Phase 01 has a test that produces it.

Scope decisions worth flagging

• Row payload is lexis::Value, not a typed/schema-checked row. Per-column type checking against a TableDef is Phase 4/5 territory once CREATE TABLE exists; this crate stores a self-describing value tuple.
• Single implicit B+tree per file, matching Decision 1's "one file per database" literally. A named-table catalog is Phase 04's CREATE TABLE layered on top of this same engine.
• Synchronous, not async. Decision 12 locks async-first for the eventual pager surface, but that's phrased around WAL/tokio machinery that doesn't exist yet (Phase 02+), the scaffolded pinax crate carried no tokio dependency, and no Phase 01 acceptance criterion mentions async. Flagging as a spec gap rather than silently deciding — Phase 02 is the natural point to revisit this once the WAL trait lands.
• .kanon-ci.toml updated to the real Rust gate (fmt/check/clippy/nextest + kanon lint), replacing the docs-phase stage list — that file's own comment named this as the point to do it, since code has now landed.

Verification

metis is under heavy concurrent load from other sessions (1-min load 20-35 against an 8-thread box, vgate --status showing waiters queued 30-50+ minutes) for the duration of this work, so vgate never admitted a local cargo check/clippy/nextest run despite being queued for the whole session. cargo fmt --all (not gated) ran clean, and cargo generate-lockfile / cargo tree / cargo metadata (also not gated) confirm the dependency graph and every manifest resolve correctly with no version conflicts. The code has had an extensive manual review pass — several real issues (an as cast, a handful of PermanentError/FatalError → PinaxError conversion sites needing #[snafu(transparent)], a meta-slot encoding bug that zeroed two magic bytes, an inaccurate doc claim about root-collapse actually being live) were caught and fixed that way — but a real cargo check/clippy/nextest run has not been observed to pass locally or in CI as of this PR opening.

CI will not run on this PR yet, separately from the load issue above: gate-attestation.yml triggers only on: pull_request: branches: [main], and this PR's base is #10's branch, not main (per this task's own instruction to build on the scaffold rather than race it). No check will appear here until either #10 merges (this PR's base then follows main) or this PR is retargeted. See blocked_on in the task handoff for the full Gate-Passed trailer status.