LittDB Garbage Collection Fine Control

[cody-littley]

Describe your changes and provide context

Previously, LittDB garbage collection was controlled entirely by a TTL. That is, data was deleted when it got old, and there was no other criteria.

This PR adds a new mechanism that allows additional constraints to be put on garbage collection. This will be necessary in order to precisely control the timing of deletions in the block store. We need to keep around block data until a logical block height which is only loosely coupled to wall clock time.

Note: in order to add this feature, I had to refactor how we configure LittDB tables. That refactor is responsible for the majority of the line changes in this PR.

Testing performed to validate your change

[cursor]

PR Summary

High Risk
Breaking public DB/table API plus changed restart semantics for TTL/sharding; GC now depends on filter correctness (must be monotonic) and can block segment deletion on core storage paths.

Overview
Adds optional GCFilter hooks on per-table config so TTL-expired segments are only removed after a callback approves every key (with a resumable scan cursor when the filter blocks). This supports block-store style retention beyond wall-clock TTL.

LittDB API refactor: GetTable / DropTable and DB-level Size/KeyCount are replaced by BuildTable(TableConfig) (one open per table per process), Table.Drop, and TableConfig for TTL, sharding factor, read/write cache sizes, and GCFilter. Those settings (except the table name) are in-memory only—the on-disk table.metadata file and related rebase/transfer logic are removed, so runtime SetTTL / SetShardingFactor no longer survive restarts. Call sites, benchmarks, CLI tests, and docs are updated; the in-memory memtable test implementation is dropped.

^{Reviewed by Cursor Bugbot for commit 6548cfb. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Jun 10, 2026, 2:59 PM

[codecov]

Codecov Report

❌ Patch coverage is 81.37255% with 19 lines in your changes missing coverage. Please review.
✅ Project coverage is 58.40%. Comparing base (7271641) to head (6548cfb).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
sei-db/db_engine/litt/disktable/control_loop.go	78.57%	4 Missing and 2 partials ⚠️
...ei-db/db_engine/litt/benchmark/benchmark_engine.go	0.00%	5 Missing ⚠️
sei-db/db_engine/litt/littbuilder/db_impl.go	80.76%	4 Missing and 1 partial ⚠️
sei-db/db_engine/litt/littbuilder/build_utils.go	71.42%	1 Missing and 1 partial ⚠️
sei-db/db_engine/litt/disktable/disk_table.go	94.11%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3572      +/-   ##
==========================================
- Coverage   59.22%   58.40%   -0.83%     
==========================================
  Files        2225     2152      -73     
  Lines      183636   175046    -8590     
==========================================
- Hits       108759   102227    -6532     
+ Misses      65101    63760    -1341     
+ Partials     9776     9059     -717     

Flag	Coverage Δ
sei-chain-pr	44.99% <81.37%> (?)
sei-db	70.41% <ø> (ø)
sei-db-state-db	?

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
sei-db/db_engine/litt/cli/rebase.go	59.04% <ø> (-0.70%)	⬇️
sei-db/db_engine/litt/dbcache/cached_table.go	64.77% <100.00%> (+0.81%)	⬆️
sei-db/db_engine/litt/littdb_config.go	56.86% <ø> (-2.40%)	⬇️
sei-db/db_engine/litt/table.go	100.00% <ø> (ø)
sei-db/db_engine/litt/table_config.go	100.00% <100.00%> (ø)
sei-db/db_engine/litt/disktable/disk_table.go	65.46% <94.11%> (+1.38%)	⬆️
sei-db/db_engine/litt/littbuilder/build_utils.go	50.75% <71.42%> (+1.14%)	⬆️
...ei-db/db_engine/litt/benchmark/benchmark_engine.go	0.00% <0.00%> (ø)
sei-db/db_engine/litt/littbuilder/db_impl.go	59.09% <80.76%> (+7.82%)	⬆️
sei-db/db_engine/litt/disktable/control_loop.go	67.33% <78.57%> (+2.28%)	⬆️

... and 74 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Kbhat1]

Thanks @cody-littley