server/paged_table library

Self-contained out-of-core typed table built on PagedHeap + PagedBTree.

A PagedTable is a primary-keyed, column-typed table whose rows live in a paged heap on disk and whose primary-key index lives in a paged B+-tree. Both files use the LRU page cache from PagedFile, so a table whose total size dwarfs RAM stays bounded by the configured cacheCapacity.

This API is intentionally separate from the SQL executor. The in-memory Database / Table classes in database.dart are untouched; this is a parallel storage layer that callers can use directly when they need true out-of-core behaviour. A future refactor may wire it behind CREATE TABLE … USING paged(…).

On-disk layout

Three sibling files share a common base path <base>:

• <base>.heap — row storage (PagedHeap)
• <base>.idx — primary-key index (PagedBTree)
• <base>.meta.json— schema (column names + types + PK column)

Each .heap and .idx file owns its own <…>.journal for crash safety. The schema file is rewritten atomically (.tmp + rename) via the same protocol used elsewhere in the engine.

Row encoding

Rows are encoded into a compact length-prefixed binary format:

  [u8 columnCount]
  for each column, in declared order:
    [u8 typeTag]
    value bytes (depends on tag)

Type tags: 0 = NULL (no payload), 1 = INT (8 bytes little-endian signed), 2 = REAL (8 bytes IEEE 754), 3 = TEXT (u32 utf8-byte length + bytes), 4 = BLOB (u32 length + bytes), 5 = BOOL (1 byte 0/1).

Primary key

Exactly one column is the primary key. The PK is serialised the same way as row values but without the type tag (so it sorts purely on its bytes); ints are written as 8-byte big-endian with the sign bit flipped so negative values sort before positives, and reals as the IEEE 754 bit pattern with the same flip. This matches the bytewise lexicographic order used by PagedBTree.