tigerbeetle-node 0.10.0 → 0.11.1

package/src/tigerbeetle/src/lsm/manifest_log.zig

@@ -28,11 +28,20 @@ const log = std.log.scoped(.manifest_log);
 
 const config = @import("../config.zig");
 const vsr = @import("../vsr.zig");
+const util = @import("../util.zig");
 
 const SuperBlockType = vsr.SuperBlockType;
 const GridType = @import("grid.zig").GridType;
+const BlockType = @import("grid.zig").BlockType;
+const tree = @import("tree.zig");
 const RingBuffer = @import("../ring_buffer.zig").RingBuffer;
 
+/// ManifestLog block schema:
+/// │ vsr.Header                  │ operation=BlockType.manifest
+/// │ [entry_count_max]Label      │ level index, insert|remove
+/// │ [≤entry_count_max]TableInfo │
+/// │ […]u8{0}                    │ padding (to end of block)
+/// Label and TableInfo entries correspond.
 pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
     return struct {
         const ManifestLog = @This();
@@ -40,8 +49,10 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
         const SuperBlock = SuperBlockType(Storage);
         const Grid = GridType(Storage);
 
-        const BlockPtr = *align(config.sector_size) [config.block_size]u8;
-        const BlockPtrConst = *align(config.sector_size) const [config.block_size]u8;
+        pub const Block = ManifestLogBlockType(Storage, TableInfo);
+        const BlockPtr = Grid.BlockPtr;
+        const BlockPtrConst = Grid.BlockPtrConst;
+        const Label = Block.Label;
 
         pub const Callback = fn (manifest_log: *ManifestLog) void;
 
@@ -51,11 +62,6 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             table: *const TableInfo,
         ) void;
 
-        pub const Label = packed struct {
-            level: u7,
-            event: enum(u1) { insert, remove },
-        };
-
         const alignment = 16;
 
         comptime {
@@ -71,72 +77,92 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             // However, we still store Label ahead of TableInfo to save space on the network.
             // This means we store fewer entries per manifest block, to gain less padding,
             // since we must store entry_count_max of whichever array is first in the layout.
-            // For a better understanding of this decision, see block_size() below.
+            // For a better understanding of this decision, see Block.size() below.
             assert(@sizeOf(TableInfo) % alignment == 0);
         }
 
-        const block_body_size = config.block_size - @sizeOf(vsr.Header);
-        const entry_size = @sizeOf(Label) + @sizeOf(TableInfo);
-        const entry_count_max_unaligned = @divFloor(block_body_size, entry_size);
-        const entry_count_max = @divFloor(entry_count_max_unaligned, alignment) * alignment;
+        /// The maximum number of table updates to the manifest by a half-measure of table
+        /// compaction (not including manifest log compaction).
+        ///
+        /// Input tables are updated in the manifest (snapshot_max is reduced).
+        /// Input tables are removed from the manifest (if not held by a persistent snapshot).
+        /// Output tables are inserted into the manifest.
+        // TODO If insert-then-remove can update in-memory, then we can only count input tables once.
+        pub const compaction_appends_max = tree.compactions_max *
+            (tree.compaction_tables_input_max + // Update snapshot_max.
+            tree.compaction_tables_input_max + // Remove.
+            tree.compaction_tables_output_max);
+
+        const blocks_count_appends = util.div_ceil(compaction_appends_max, Block.entry_count_max);
+
+        /// The upper-bound of manifest log blocks we must buffer.
+        ///
+        /// `blocks` must have sufficient capacity for:
+        /// - a manifest log compaction (+1 block in the worst case)
+        /// - a leftover open block from the previous ops (+1 block)
+        /// - table updates from a half bar of compactions
+        ///   (This is typically +1 block, but may be more when the block size is small).
+        ///   TODO(Beat compaction): blocks_count_appends only needs enough for 1 beat.
+        const blocks_count_max = 1 + 1 + blocks_count_appends;
 
         comptime {
-            assert(entry_count_max > 0);
-            assert((entry_count_max * @sizeOf(Label)) % alignment == 0);
-            assert((entry_count_max * @sizeOf(TableInfo)) % alignment == 0);
+            assert(blocks_count_max >= 3);
+            assert(blocks_count_max == 3 or config.block_size < 64 * 1024);
         }
 
         superblock: *SuperBlock,
         grid: *Grid,
+        grid_reservation: ?Grid.Reservation = null,
         tree_hash: u128,
 
         /// The head block is used to accumulate a full block, to be written at the next flush.
         /// The remaining blocks must accommodate all further appends.
-        // TODO Assert the relation between the number of blocks, and flush/compact/append.
-        blocks: RingBuffer(BlockPtr, 3, .array),
+        blocks: RingBuffer(BlockPtr, blocks_count_max, .array),
 
         /// The number of blocks that have been appended to, filled up, and then closed.
         blocks_closed: u8 = 0,
 
         /// The number of entries in the open block.
+        ///
+        /// Invariants:
+        /// - When `entry_count = 0`, there is no open block.
+        /// - `entry_count < entry_count_max`. When `entry_count` reaches the maximum, the open
+        ///   block is closed, and `entry_count` resets to 0.
         entry_count: u32 = 0,
 
         opened: bool = false,
         open_event: OpenEvent = undefined,
         open_iterator: SuperBlock.Manifest.IteratorReverse = undefined,
 
+        /// Set for the duration of `compact`.
         reading: bool = false,
         read: Grid.Read = undefined,
-        read_callback: Callback = undefined,
+        read_callback: ?Callback = null,
         read_block_reference: ?SuperBlock.Manifest.BlockReference = null,
 
+        /// Set for the duration of `flush` and `checkpoint`.
         writing: bool = false,
         write: Grid.Write = undefined,
-        write_callback: Callback = undefined,
+        write_callback: ?Callback = null,
 
         pub fn init(allocator: mem.Allocator, grid: *Grid, tree_hash: u128) !ManifestLog {
             // TODO RingBuffer for .pointer should be extended to take care of alignment:
 
-            const a = try allocator.alignedAlloc(u8, config.sector_size, config.block_size);
-            errdefer allocator.free(a);
+            var blocks: [blocks_count_max]BlockPtr = undefined;
+            for (blocks) |*block, i| {
+                errdefer for (blocks[0..i]) |b| allocator.free(b);
 
-            const b = try allocator.alignedAlloc(u8, config.sector_size, config.block_size);
-            errdefer allocator.free(b);
-
-            const c = try allocator.alignedAlloc(u8, config.sector_size, config.block_size);
-            errdefer allocator.free(b);
+                const block_slice =
+                    try allocator.alignedAlloc(u8, config.sector_size, config.block_size);
+                block.* = block_slice[0..config.block_size];
+            }
+            errdefer for (blocks) |b| allocator.free(b);
 
             return ManifestLog{
                 .superblock = grid.superblock,
                 .grid = grid,
                 .tree_hash = tree_hash,
-                .blocks = .{
-                    .buffer = .{
-                        a[0..config.block_size],
-                        b[0..config.block_size],
-                        c[0..config.block_size],
-                    },
-                },
+                .blocks = .{ .buffer = blocks },
             };
         }
 
@@ -154,6 +180,11 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             assert(!manifest_log.opened);
             assert(!manifest_log.reading);
             assert(!manifest_log.writing);
+            assert(manifest_log.read_callback == null);
+
+            assert(manifest_log.blocks.count == 0);
+            assert(manifest_log.blocks_closed == 0);
+            assert(manifest_log.entry_count == 0);
 
             manifest_log.open_event = event;
             manifest_log.open_iterator = manifest_log.superblock.manifest.iterator_reverse(
@@ -171,6 +202,10 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             assert(manifest_log.reading);
             assert(!manifest_log.writing);
 
+            assert(manifest_log.blocks.count == 0);
+            assert(manifest_log.blocks_closed == 0);
+            assert(manifest_log.entry_count == 0);
+
             manifest_log.read_block_reference = manifest_log.open_iterator.next();
 
             if (manifest_log.read_block_reference) |block| {
@@ -182,15 +217,16 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
                     &manifest_log.read,
                     block.address,
                     block.checksum,
+                    .manifest,
                 );
             } else {
                 manifest_log.opened = true;
                 manifest_log.open_event = undefined;
                 manifest_log.open_iterator = undefined;
 
-                const callback = manifest_log.read_callback;
+                const callback = manifest_log.read_callback.?;
                 manifest_log.reading = false;
-                manifest_log.read_callback = undefined;
+                manifest_log.read_callback = null;
                 assert(manifest_log.read_block_reference == null);
 
                 callback(manifest_log);
@@ -206,9 +242,9 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             const block_reference = manifest_log.read_block_reference.?;
             verify_block(block, block_reference.checksum, block_reference.address);
 
-            const entry_count = block_entry_count(block);
-            const labels_used = labels_const(block)[0..entry_count];
-            const tables_used = tables_const(block)[0..entry_count];
+            const entry_count = Block.entry_count(block);
+            const labels_used = Block.labels_const(block)[0..entry_count];
+            const tables_used = Block.tables_const(block)[0..entry_count];
 
             const manifest: *SuperBlock.Manifest = &manifest_log.superblock.manifest;
 
@@ -229,6 +265,10 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
                 }
             }
 
+            if (Block.entry_count(block) < Block.entry_count_max) {
+                manifest.queue_for_compaction(block_reference.address);
+            }
+
             log.debug("{}: opened: checksum={} address={} entries={}", .{
                 manifest_log.tree_hash,
                 block_reference.checksum,
@@ -243,12 +283,14 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
         /// A move is only recorded as an insert, there is no remove from the previous level, since
         /// this is safer (no potential to get the event order wrong) and reduces fragmentation.
         pub fn insert(manifest_log: *ManifestLog, level: u7, table: *const TableInfo) void {
+            assert(!manifest_log.writing);
             manifest_log.append(.{ .level = level, .event = .insert }, table);
         }
 
         /// Appends the removal of a table from a level.
         /// The table must have previously been inserted to the manifest log.
         pub fn remove(manifest_log: *ManifestLog, level: u7, table: *const TableInfo) void {
+            assert(!manifest_log.writing);
             manifest_log.append(.{ .level = level, .event = .remove }, table);
         }
 
@@ -259,17 +301,14 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             assert(table.snapshot_min > 0);
             assert(table.snapshot_max > table.snapshot_min);
 
-            if (manifest_log.blocks.empty()) {
-                manifest_log.acquire_block();
-            } else if (manifest_log.entry_count == entry_count_max) {
-                assert(manifest_log.blocks.count > 0);
-                manifest_log.close_block();
+            if (manifest_log.entry_count == 0) {
+                assert(manifest_log.blocks.count == manifest_log.blocks_closed);
                 manifest_log.acquire_block();
             } else if (manifest_log.entry_count > 0) {
                 assert(manifest_log.blocks.count > 0);
             }
 
-            assert(manifest_log.entry_count < entry_count_max);
+            assert(manifest_log.entry_count < Block.entry_count_max);
             assert(manifest_log.blocks.count - manifest_log.blocks_closed == 1);
 
             log.debug(
@@ -288,11 +327,11 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
 
             const block: BlockPtr = manifest_log.blocks.tail().?;
             const entry = manifest_log.entry_count;
-            labels(block)[entry] = label;
-            tables(block)[entry] = table.*;
+            Block.labels(block)[entry] = label;
+            Block.tables(block)[entry] = table.*;
 
             const manifest: *SuperBlock.Manifest = &manifest_log.superblock.manifest;
-            const address = block_address(block);
+            const address = Block.address(block);
             if (manifest.update_table_extent(table.address, address, entry)) |previous_block| {
                 manifest.queue_for_compaction(previous_block);
                 if (label.event == .remove) manifest.queue_for_compaction(address);
@@ -302,12 +341,17 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             }
 
             manifest_log.entry_count += 1;
+            if (manifest_log.entry_count == Block.entry_count_max) {
+                manifest_log.close_block();
+                assert(manifest_log.entry_count == 0);
+            }
         }
 
-        pub fn flush(manifest_log: *ManifestLog, callback: Callback) void {
+        fn flush(manifest_log: *ManifestLog, callback: Callback) void {
             assert(manifest_log.opened);
             assert(!manifest_log.reading);
             assert(!manifest_log.writing);
+            assert(manifest_log.write_callback == null);
 
             manifest_log.writing = true;
             manifest_log.write_callback = callback;
@@ -316,6 +360,26 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
                 manifest_log.tree_hash,
                 manifest_log.blocks_closed,
             });
+
+            // The manifest is updated synchronously relative to the beginning of compact() and
+            // checkpoint() so that the SuperBlock.Manifest.append()s are deterministic relative
+            // to other trees' manifest logs.
+            const manifest: *SuperBlock.Manifest = &manifest_log.superblock.manifest;
+            var i: usize = 0;
+            while (i < manifest_log.blocks_closed) : (i += 1) {
+                const block = manifest_log.blocks.get_ptr(i).?.*;
+                verify_block(block, null, null);
+
+                const header = mem.bytesAsValue(vsr.Header, block[0..@sizeOf(vsr.Header)]);
+                const address = Block.address(block);
+                assert(address > 0);
+
+                manifest.append(manifest_log.tree_hash, header.checksum, address);
+                if (Block.entry_count(block) < Block.entry_count_max) {
+                    manifest.queue_for_compaction(address);
+                }
+            }
+
             manifest_log.write_block();
         }
 
@@ -329,11 +393,11 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
                     assert(manifest_log.entry_count == 0);
                 } else {
                     assert(manifest_log.blocks.count == 1);
-                    assert(manifest_log.entry_count < entry_count_max);
+                    assert(manifest_log.entry_count < Block.entry_count_max);
                 }
 
-                const callback = manifest_log.write_callback;
-                manifest_log.write_callback = undefined;
+                const callback = manifest_log.write_callback.?;
+                manifest_log.write_callback = null;
                 manifest_log.writing = false;
 
                 callback(manifest_log);
@@ -344,15 +408,16 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             verify_block(block, null, null);
 
             const header = mem.bytesAsValue(vsr.Header, block[0..@sizeOf(vsr.Header)]);
-            const address = block_address(block);
+            const address = Block.address(block);
             assert(address > 0);
 
-            const entry_count = block_entry_count(block);
+            const entry_count = Block.entry_count(block);
 
             if (manifest_log.blocks_closed == 1 and manifest_log.blocks.count == 1) {
+                // This might be the last block of a checkpoint, which can be a partial block.
                 assert(entry_count > 0);
             } else {
-                assert(entry_count == entry_count_max);
+                assert(entry_count == Block.entry_count_max);
             }
 
             log.debug("{}: write_block: checksum={} address={} entries={}", .{
@@ -375,18 +440,6 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             assert(manifest_log.opened);
             assert(manifest_log.writing);
 
-            const block = manifest_log.blocks.head().?;
-            verify_block(block, null, null);
-
-            const header = mem.bytesAsValue(vsr.Header, block[0..@sizeOf(vsr.Header)]);
-            const address = block_address(block);
-            assert(address > 0);
-
-            const manifest: *SuperBlock.Manifest = &manifest_log.superblock.manifest;
-
-            manifest.append(manifest_log.tree_hash, header.checksum, address);
-            if (block_entry_count(block) < entry_count_max) manifest.queue_for_compaction(address);
-
             manifest_log.blocks_closed -= 1;
             manifest_log.blocks.advance_head();
             assert(manifest_log.blocks_closed <= manifest_log.blocks.count);
@@ -394,42 +447,82 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             manifest_log.write_block();
         }
 
+        pub fn reserve(manifest_log: *ManifestLog) void {
+            assert(manifest_log.opened);
+            assert(!manifest_log.reading);
+            assert(!manifest_log.writing);
+            assert(manifest_log.read_callback == null);
+            assert(manifest_log.write_callback == null);
+            assert(manifest_log.grid_reservation == null);
+            // reserve() is called at the start of compaction, so we have:
+            // - at most 1 closed block, and
+            // - at most 1 open block
+            // due to the last log compaction plus a leftover partial block.
+            assert(manifest_log.blocks_closed <= 1);
+            assert(manifest_log.blocks.count <= manifest_log.blocks_closed + 1);
+
+            // TODO Make sure this cannot fail — before compaction begins verify that enough free
+            // blocks are available for all reservations.
+            // +1 for the manifest log block compaction, which acquires at most one block.
+            manifest_log.grid_reservation = manifest_log.grid.reserve(1 + blocks_count_appends).?;
+        }
+
+        /// `compact` does not close a partial block; that is only necessary during `checkpoint`.
         pub fn compact(manifest_log: *ManifestLog, callback: Callback) void {
+            assert(manifest_log.opened);
             assert(!manifest_log.reading);
+            assert(!manifest_log.writing);
+            assert(manifest_log.read_callback == null);
+            assert(manifest_log.write_callback == null);
+            assert(manifest_log.grid_reservation != null);
+
+            const free_set = manifest_log.grid.superblock.free_set;
+            assert(free_set.count_free_reserved(manifest_log.grid_reservation.?) >= 1);
+
             manifest_log.read_callback = callback;
-            manifest_log.flush(flush_callback);
+            manifest_log.flush(compact_flush_callback);
         }
 
-        fn flush_callback(manifest_log: *ManifestLog) void {
-            const callback = manifest_log.read_callback;
-            manifest_log.read_callback = undefined;
+        fn compact_flush_callback(manifest_log: *ManifestLog) void {
+            const callback = manifest_log.read_callback.?;
 
             assert(manifest_log.opened);
             assert(!manifest_log.reading);
             assert(!manifest_log.writing);
+            assert(manifest_log.blocks_closed == 0);
+            assert(manifest_log.grid_reservation != null);
 
             const manifest: *SuperBlock.Manifest = &manifest_log.superblock.manifest;
 
+            // Compact a single manifest block — to minimize latency spikes, we want to do the bare
+            // minimum of compaction work required.
+            // TODO Compact more than 1 block if fragmentation is outstripping the compaction rate.
+            // (Make sure to update the grid block reservation to account for this).
+            // Or assert that compactions cannot update blocks fast enough to outpace manifest
+            // log compaction (relative to the number of updates that fit in a manifest log block).
             if (manifest.oldest_block_queued_for_compaction(manifest_log.tree_hash)) |block| {
                 assert(block.tree == manifest_log.tree_hash);
                 assert(block.address > 0);
 
                 manifest_log.reading = true;
-                manifest_log.read_callback = callback;
                 manifest_log.read_block_reference = block;
 
                 manifest_log.grid.read_block(
-                    compact_callback,
+                    compact_read_block_callback,
                     &manifest_log.read,
                     block.address,
                     block.checksum,
+                    .manifest,
                 );
             } else {
+                manifest_log.read_callback = null;
+                manifest_log.grid.forfeit(manifest_log.grid_reservation.?);
+                manifest_log.grid_reservation = null;
                 callback(manifest_log);
             }
         }
 
-        fn compact_callback(read: *Grid.Read, block: BlockPtrConst) void {
+        fn compact_read_block_callback(read: *Grid.Read, block: BlockPtrConst) void {
             const manifest_log = @fieldParentPtr(ManifestLog, "read", read);
             assert(manifest_log.opened);
             assert(manifest_log.reading);
@@ -438,9 +531,9 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             const block_reference = manifest_log.read_block_reference.?;
             verify_block(block, block_reference.checksum, block_reference.address);
 
-            const entry_count = block_entry_count(block);
-            const labels_used = labels_const(block)[0..entry_count];
-            const tables_used = tables_const(block)[0..entry_count];
+            const entry_count = Block.entry_count(block);
+            const labels_used = Block.labels_const(block)[0..entry_count];
+            const tables_used = Block.tables_const(block)[0..entry_count];
 
             const manifest: *SuperBlock.Manifest = &manifest_log.superblock.manifest;
             assert(manifest.tables.count() > 0);
@@ -479,7 +572,7 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
 
             // Blocks may be compacted if they contain frees, or are not completely full.
             // For example, a partial block may be flushed as part of a checkpoint.
-            assert(frees > 0 or entry_count < entry_count_max);
+            assert(frees > 0 or entry_count < Block.entry_count_max);
 
             assert(manifest.queued_for_compaction(block_reference.address));
             manifest.remove(
@@ -489,11 +582,13 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             );
             assert(!manifest.queued_for_compaction(block_reference.address));
 
-            manifest_log.superblock.free_set.release_at_checkpoint(block_reference.address);
+            manifest_log.grid.release(block_reference.address);
+            manifest_log.grid.forfeit(manifest_log.grid_reservation.?);
+            manifest_log.grid_reservation = null;
 
-            const callback = manifest_log.read_callback;
+            const callback = manifest_log.read_callback.?;
             manifest_log.reading = false;
-            manifest_log.read_callback = undefined;
+            manifest_log.read_callback = null;
             manifest_log.read_block_reference = null;
 
             callback(manifest_log);
@@ -503,9 +598,8 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             assert(manifest_log.opened);
             assert(!manifest_log.reading);
             assert(!manifest_log.writing);
-
-            manifest_log.writing = true;
-            manifest_log.write_callback = callback;
+            assert(manifest_log.write_callback == null);
+            assert(manifest_log.grid_reservation == null);
 
             if (manifest_log.entry_count > 0) {
                 manifest_log.close_block();
@@ -514,12 +608,13 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
                 assert(manifest_log.blocks_closed == manifest_log.blocks.count);
             }
 
-            log.debug("checkpoint: writing {} block(s)", .{manifest_log.blocks_closed});
-            manifest_log.write_block();
+            manifest_log.flush(callback);
         }
 
         fn acquire_block(manifest_log: *ManifestLog) void {
+            assert(manifest_log.opened);
             assert(manifest_log.entry_count == 0);
+            assert(manifest_log.blocks.count == manifest_log.blocks_closed);
             assert(!manifest_log.blocks.full());
 
             manifest_log.blocks.advance_tail();
@@ -529,27 +624,29 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             const header = mem.bytesAsValue(vsr.Header, block[0..@sizeOf(vsr.Header)]);
             header.* = .{
                 .cluster = manifest_log.superblock.working.cluster,
-                .op = manifest_log.superblock.free_set.acquire().?,
+                .op = manifest_log.grid.acquire(manifest_log.grid_reservation.?),
                 .size = undefined,
                 .command = .block,
+                .operation = BlockType.manifest.operation(),
             };
         }
 
         fn close_block(manifest_log: *ManifestLog) void {
-            const block: BlockPtr = manifest_log.blocks.tail().?;
+            assert(manifest_log.blocks.count == manifest_log.blocks_closed + 1);
 
+            const block: BlockPtr = manifest_log.blocks.tail().?;
             const entry_count = manifest_log.entry_count;
             assert(entry_count > 0);
-            assert(entry_count <= entry_count_max);
+            assert(entry_count <= Block.entry_count_max);
 
             const header = mem.bytesAsValue(vsr.Header, block[0..@sizeOf(vsr.Header)]);
             assert(header.cluster == manifest_log.superblock.working.cluster);
             assert(header.op > 0);
-            header.size = block_size(entry_count);
             assert(header.command == .block);
+            header.size = Block.size(entry_count);
 
             // Zero unused labels:
-            mem.set(u8, mem.sliceAsBytes(labels(block)[entry_count..]), 0);
+            mem.set(u8, mem.sliceAsBytes(Block.labels(block)[entry_count..]), 0);
 
             // Zero unused tables, and padding:
             mem.set(u8, block[header.size..], 0);
@@ -558,21 +655,23 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
             header.set_checksum();
 
             verify_block(block, null, null);
-            assert(block_entry_count(block) == entry_count);
+            assert(Block.entry_count(block) == entry_count);
 
             log.debug("{}: close_block: checksum={} address={} entries={}", .{
                 manifest_log.tree_hash,
                 header.checksum,
-                block_address(block),
+                Block.address(block),
                 entry_count,
             });
 
             manifest_log.blocks_closed += 1;
             manifest_log.entry_count = 0;
+            assert(manifest_log.blocks.count == manifest_log.blocks_closed);
         }
 
         fn verify_block(block: BlockPtrConst, checksum: ?u128, address: ?u64) void {
             const header = mem.bytesAsValue(vsr.Header, block[0..@sizeOf(vsr.Header)]);
+            assert(BlockType.from(header.operation) == .manifest);
 
             if (config.verify) {
                 assert(header.valid_checksum());
@@ -581,63 +680,92 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
 
             assert(checksum == null or header.checksum == checksum.?);
 
-            assert(block_address(block) > 0);
-            assert(address == null or block_address(block) == address.?);
+            assert(Block.address(block) > 0);
+            assert(address == null or Block.address(block) == address.?);
 
-            const entry_count = block_entry_count(block);
+            const entry_count = Block.entry_count(block);
             assert(entry_count > 0);
         }
+    };
+}
+
+fn ManifestLogBlockType(comptime Storage: type, comptime TableInfo: type) type {
+    return struct {
+        const Grid = GridType(Storage);
+        const BlockPtr = Grid.BlockPtr;
+        const BlockPtrConst = Grid.BlockPtrConst;
+
+        const block_body_size = config.block_size - @sizeOf(vsr.Header);
+        const entry_size = @sizeOf(Label) + @sizeOf(TableInfo);
+        const entry_count_max_unaligned = @divFloor(block_body_size, entry_size);
+        pub const entry_count_max = @divFloor(
+            entry_count_max_unaligned,
+            @alignOf(TableInfo),
+        ) * @alignOf(TableInfo);
 
-        fn block_address(block: BlockPtrConst) u64 {
+        comptime {
+            assert(entry_count_max > 0);
+            assert((entry_count_max * @sizeOf(Label)) % @alignOf(TableInfo) == 0);
+            assert((entry_count_max * @sizeOf(TableInfo)) % @alignOf(TableInfo) == 0);
+        }
+
+        pub const Label = packed struct {
+            level: u7,
+            event: enum(u1) { insert, remove },
+        };
+
+        pub fn address(block: BlockPtrConst) u64 {
             const header = mem.bytesAsValue(vsr.Header, block[0..@sizeOf(vsr.Header)]);
             assert(header.command == .block);
 
-            const address = header.op;
-            assert(address > 0);
-            return address;
+            const block_address = header.op;
+            assert(block_address > 0);
+            return block_address;
         }
 
-        fn block_checksum(block: BlockPtrConst) u128 {
+        pub fn checksum(block: BlockPtrConst) u128 {
             const header = mem.bytesAsValue(vsr.Header, block[0..@sizeOf(vsr.Header)]);
             assert(header.command == .block);
 
             return header.checksum;
         }
 
-        fn block_entry_count(block: BlockPtrConst) u32 {
+        pub fn entry_count(block: BlockPtrConst) u32 {
             const header = mem.bytesAsValue(vsr.Header, block[0..@sizeOf(vsr.Header)]);
             assert(header.command == .block);
 
             const labels_size = entry_count_max * @sizeOf(Label);
             const tables_size = header.size - @sizeOf(vsr.Header) - labels_size;
 
-            const entry_count = @intCast(u32, @divExact(tables_size, @sizeOf(TableInfo)));
-            assert(entry_count > 0);
-            assert(entry_count <= entry_count_max);
-            return entry_count;
+            const entry_count_ = @intCast(u32, @divExact(tables_size, @sizeOf(TableInfo)));
+            assert(entry_count_ > 0);
+            assert(entry_count_ <= entry_count_max);
+            return entry_count_;
         }
 
-        fn block_size(entry_count: u32) u32 {
-            assert(entry_count > 0);
-            assert(entry_count <= entry_count_max);
+        pub fn size(entry_count_: u32) u32 {
+            assert(entry_count_ > 0);
+            assert(entry_count_ <= entry_count_max);
 
             // Encode the smaller type first because this will be multiplied by entry_count_max.
             const labels_size = entry_count_max * @sizeOf(Label);
-            const tables_size = entry_count * @sizeOf(TableInfo);
+            assert(labels_size == labels_size_max);
+            assert((@sizeOf(vsr.Header) + labels_size) % @alignOf(TableInfo) == 0);
+            const tables_size = entry_count_ * @sizeOf(TableInfo);
 
             return @sizeOf(vsr.Header) + labels_size + tables_size;
         }
 
         const labels_size_max = entry_count_max * @sizeOf(Label);
 
-        fn labels(block: BlockPtr) *[entry_count_max]Label {
+        pub fn labels(block: BlockPtr) *[entry_count_max]Label {
             return mem.bytesAsSlice(
                 Label,
                 block[@sizeOf(vsr.Header)..][0..labels_size_max],
             )[0..entry_count_max];
         }
 
-        fn labels_const(block: BlockPtrConst) *const [entry_count_max]Label {
+        pub fn labels_const(block: BlockPtrConst) *const [entry_count_max]Label {
             return mem.bytesAsSlice(
                 Label,
                 block[@sizeOf(vsr.Header)..][0..labels_size_max],
@@ -646,259 +774,18 @@ pub fn ManifestLogType(comptime Storage: type, comptime TableInfo: type) type {
 
         const tables_size_max = entry_count_max * @sizeOf(TableInfo);
 
-        fn tables(block: BlockPtr) *[entry_count_max]TableInfo {
+        pub fn tables(block: BlockPtr) *[entry_count_max]TableInfo {
             return mem.bytesAsSlice(
                 TableInfo,
-                block[@sizeOf(vsr.Header) + entry_count_max ..][0..tables_size_max],
+                block[@sizeOf(vsr.Header) + labels_size_max ..][0..tables_size_max],
             )[0..entry_count_max];
         }
 
-        fn tables_const(block: BlockPtrConst) *const [entry_count_max]TableInfo {
+        pub fn tables_const(block: BlockPtrConst) *const [entry_count_max]TableInfo {
             return mem.bytesAsSlice(
                 TableInfo,
-                block[@sizeOf(vsr.Header) + entry_count_max ..][0..tables_size_max],
+                block[@sizeOf(vsr.Header) + labels_size_max ..][0..tables_size_max],
             )[0..entry_count_max];
         }
     };
 }
-
-// TODO This is a manual runner to be replaced with a fuzz test.
-fn ManifestLogTestType(
-    comptime Storage: type,
-    comptime TableInfo: type,
-) type {
-    return struct {
-        const ManifestLogTest = @This();
-        const ManifestLog = ManifestLogType(Storage, TableInfo);
-
-        const SuperBlock = SuperBlockType(Storage);
-        const Grid = GridType(Storage);
-
-        superblock: *SuperBlock,
-        superblock_context: SuperBlock.Context = undefined,
-        manifest_log: ManifestLog,
-        pending: usize = 0,
-
-        fn init(allocator: mem.Allocator, grid: *Grid) !ManifestLogTest {
-            const tree_hash: u128 = std.math.maxInt(u128);
-
-            var manifest_log = try ManifestLog.init(allocator, grid, tree_hash);
-            errdefer manifest_log.deinit(allocator);
-
-            return ManifestLogTest{
-                .superblock = grid.superblock,
-                .manifest_log = manifest_log,
-            };
-        }
-
-        fn deinit(t: *ManifestLogTest, allocator: mem.Allocator) void {
-            t.manifest_log.deinit(allocator);
-        }
-
-        fn format_superblock(t: *ManifestLogTest) void {
-            t.pending += 1;
-            t.superblock.format(format_superblock_callback, &t.superblock_context, .{
-                .cluster = 10,
-                .replica = 0,
-                .size_max = 512 * 1024 * 1024,
-            });
-        }
-
-        fn format_superblock_callback(context: *SuperBlock.Context) void {
-            const t = @fieldParentPtr(ManifestLogTest, "superblock_context", context);
-            t.pending -= 1;
-            t.open_superblock();
-        }
-
-        fn open_superblock(t: *ManifestLogTest) void {
-            t.pending += 1;
-            t.superblock.open(open_superblock_callback, &t.superblock_context);
-        }
-
-        fn open_superblock_callback(context: *SuperBlock.Context) void {
-            const t = @fieldParentPtr(ManifestLogTest, "superblock_context", context);
-            t.pending -= 1;
-
-            t.open();
-        }
-
-        fn open(t: *ManifestLogTest) void {
-            t.pending += 1;
-            t.manifest_log.open(open_event, open_callback);
-        }
-
-        fn open_event(manifest_log: *ManifestLog, level: u7, table: *const TableInfo) void {
-            log.debug(
-                "{}: open_event: level={} checksum={} address={} flags={} snapshot={}..{}",
-                .{
-                    manifest_log.tree_hash,
-                    level,
-                    table.checksum,
-                    table.address,
-                    table.flags,
-                    table.snapshot_min,
-                    table.snapshot_max,
-                },
-            );
-        }
-
-        fn open_callback(manifest_log: *ManifestLog) void {
-            const t = @fieldParentPtr(ManifestLogTest, "manifest_log", manifest_log);
-            t.pending -= 1;
-
-            t.manifest_log.insert(2, &TableInfo{
-                .checksum = 123,
-                .address = 7,
-                .flags = 0,
-                .snapshot_min = 42,
-                .key_min = 50,
-                .key_max = 100,
-            });
-
-            t.flush();
-        }
-
-        fn flush(t: *ManifestLogTest) void {
-            t.pending += 1;
-            t.manifest_log.flush(flush_callback);
-        }
-
-        fn flush_callback(manifest_log: *ManifestLog) void {
-            const t = @fieldParentPtr(ManifestLogTest, "manifest_log", manifest_log);
-            t.pending -= 1;
-            t.checkpoint();
-        }
-
-        fn checkpoint(t: *ManifestLogTest) void {
-            t.pending += 1;
-            t.manifest_log.checkpoint(checkpoint_callback);
-        }
-
-        fn checkpoint_callback(manifest_log: *ManifestLog) void {
-            const t = @fieldParentPtr(ManifestLogTest, "manifest_log", manifest_log);
-            t.pending -= 1;
-
-            t.manifest_log.insert(2, &TableInfo{
-                .checksum = 123,
-                .address = 7,
-                .flags = 0,
-                .snapshot_min = 42,
-                .snapshot_max = 50,
-                .key_min = 50,
-                .key_max = 100,
-            });
-
-            t.manifest_log.remove(2, &TableInfo{
-                .checksum = 123,
-                .address = 7,
-                .flags = 0,
-                .snapshot_min = 42,
-                .snapshot_max = 50,
-                .key_min = 50,
-                .key_max = 100,
-            });
-
-            t.checkpoint_again();
-        }
-
-        fn checkpoint_again(t: *ManifestLogTest) void {
-            t.pending += 1;
-            t.manifest_log.checkpoint(checkpoint_again_callback);
-        }
-
-        fn checkpoint_again_callback(manifest_log: *ManifestLog) void {
-            const t = @fieldParentPtr(ManifestLogTest, "manifest_log", manifest_log);
-            t.pending -= 1;
-            t.compact();
-        }
-
-        fn compact(t: *ManifestLogTest) void {
-            t.pending += 1;
-            t.manifest_log.compact(compact_callback);
-        }
-
-        fn compact_callback(manifest_log: *ManifestLog) void {
-            const t = @fieldParentPtr(ManifestLogTest, "manifest_log", manifest_log);
-            t.pending -= 1;
-
-            const tree = t.manifest_log.tree_hash;
-            if (t.manifest_log.superblock.manifest.oldest_block_queued_for_compaction(tree)) |_| {
-                t.compact();
-            } else {
-                t.checkpoint_superblock();
-            }
-        }
-
-        fn checkpoint_superblock(t: *ManifestLogTest) void {
-            t.pending += 1;
-            t.superblock.checkpoint(checkpoint_superblock_callback, &t.superblock_context);
-        }
-
-        fn checkpoint_superblock_callback(context: *SuperBlock.Context) void {
-            const t = @fieldParentPtr(ManifestLogTest, "superblock_context", context);
-            t.pending -= 1;
-        }
-    };
-}
-
-pub fn main() !void {
-    const testing = std.testing;
-    const allocator = testing.allocator;
-
-    testing.log_level = .debug;
-
-    const os = std.os;
-    const IO = @import("../io.zig").IO;
-    const Storage = @import("../storage.zig").Storage;
-    const SuperBlock = SuperBlockType(Storage);
-    const Grid = @import("grid.zig").GridType(Storage);
-
-    const dir_path = ".";
-    const dir_fd = os.openZ(dir_path, os.O.CLOEXEC | os.O.RDONLY, 0) catch |err| {
-        std.debug.print("failed to open directory '{s}': {}", .{ dir_path, err });
-        return;
-    };
-
-    const size_max = 2 * 1024 * 1024 * 1024;
-    const storage_fd = try IO.open_file(dir_fd, "test_manifest_log", size_max, true);
-    defer std.fs.cwd().deleteFile("test_manifest_log") catch {};
-
-    var io = try IO.init(128, 0);
-    defer io.deinit();
-
-    var storage = try Storage.init(&io, storage_fd);
-    defer storage.deinit();
-
-    var superblock = try SuperBlock.init(allocator, &storage);
-    defer superblock.deinit(allocator);
-
-    var grid = try Grid.init(allocator, &superblock);
-    defer grid.deinit(allocator);
-
-    const TableInfo = extern struct {
-        checksum: u128,
-        address: u64,
-        flags: u64 = 0,
-
-        /// The minimum snapshot that can see this table (with exclusive bounds).
-        /// This value is set to the current snapshot tick on table creation.
-        snapshot_min: u64,
-
-        /// The maximum snapshot that can see this table (with exclusive bounds).
-        /// This value is set to the current snapshot tick on table deletion.
-        snapshot_max: u64 = math.maxInt(u64),
-
-        key_min: u128,
-        key_max: u128,
-    };
-    assert(@sizeOf(TableInfo) == 48 + 16 * 2);
-    assert(@alignOf(TableInfo) == 16);
-
-    const ManifestLogTest = ManifestLogTestType(Storage, TableInfo);
-
-    var t = try ManifestLogTest.init(allocator, &grid);
-    defer t.deinit(allocator);
-
-    t.format_superblock();
-    while (t.pending > 0) try io.run_for_ns(100);
-}