mod ledger_tiles¶
- module ledger_tiles¶
The tile log beside a ledger: the same canonical lines as the JSON Lines file, stored as a C2SP tlog-tiles log with key sidecars through the
rfc9162-tilescrate.The JSON Lines file is the canonical ledger. The tile log follows it: a sync appends the lines the tile log does not hold yet, and a tile log whose entries disagree with the ledger is moved aside and rebuilt. Each entry’s lookup keys come from
keys_of, soledger findanswerspkg=PETScorroute=kvmfrom the sidecars instead of a scan.The head of the tile log is a C2SP checkpoint under the origin eb-stack-ledger/<stack>/<year>, signed with the same Ed25519 key as the ledger’s JSON head. A find opens the log at its tree state, checks that the signed checkpoint is a prefix of it, and checks the inclusion proof of every record it prints. A verify checks that the tile log extends the signed JSON head and holds the same lines.
The tile log holds exactly the ledger’s lines, so its root is the ledger’s. The sorted runs a lookup goes through, and the manifests that describe them, live in a second tile log inside it, the index log at <tiles>/index (see
index_dir), with its own checkpoint under <origin>/index signed by the same key. Each logged manifest carries the size and root of the tile log it indexed. A find proves a record in the tile log’s checkpoint and the run that located it in the index log’s.Variables
- const ROUTES: &[&str]¶
The values
routecan take: where the build ran.
Functions
- fn audit(entries: &[Entry], dir: &Path, size: usize, root: &str, origin: &str, trusted: &VerifyingKey) -> Result<(u64, String)>¶
Check that the tile log at
dirextends the signed head ofsizeandrootand holds the ledger’s lines for those entries, and that a checkpoint it holds is signed bytrustedasoriginand is a prefix of it too. Returns the tile log’s size and root.
- fn checkpoint(entries: &[Entry], dir: &Path, key: &SigningKey, origin: &str) -> Result<(SyncReport, CheckpointReport)>¶
Sync the tile log and sign its tree state as a C2SP checkpoint under
originwithkey.
- fn find(request: &FindRequest) -> Result<FindReport>¶
Records carrying every key, read from the sidecars and proven in the signed checkpoint.
- fn index_dir(dir: &Path) -> PathBuf¶
The index log inside the tile log at
dir: the run files and the logged run manifests, with their own checkpoint. It lives under the tile log so that moving or copying the tile log takes its index along.
- fn index_origin(origin: &str) -> String¶
The origin the index log’s checkpoint is signed under.
- fn key_fn() -> KeyFn¶
The key function the tile log is written and read with.
- fn keys_arc() -> Keys¶
The same keys for the run store.
- fn keys_of(entry: &[u8]) -> Vec<Vec<u8>>¶
The lookup keys of one entry, the bytes of a canonical ledger line: module=<module>`,
pkg=<software name before the slash>`, and ``target=,action=,route=,actor=andid=for each of those fields the record carries, plus job=<build.job>` whenbuild` is an object with a string ``job. Bytes that are not a JSON object have no keys beyond the identity hash the crate adds.
- fn origin(first: Option<&Entry>, given: Option<&str>) -> Result<String>¶
The checkpoint origin of a log:
--originwhen given, else eb-stack-ledger/<stack>/<year>` from the first record’sstack` and the year of its ``ts. The year of the first record keeps the origin the same for the life of the log.
- fn origin_from_log(log: &Path, given: Option<&str>) -> Result<String>¶
The origin from the first line of the log file alone, for a find that does not read the whole ledger.
- fn sync(entries: &[Entry], dir: &Path) -> Result<SyncReport>¶
Bring the tile log at
dirto the ledger’s lines: append what it lacks, or move it aside and rebuild it when its entries disagree.
- fn tiles_dir(log: &Path, tiles: Option<&Path>) -> PathBuf¶
Where the tile log of
loglives:tileswhen given, else the log’s path with.tilesappended (ledger/2026.06.jsonl.tiles).
Structs and Unions
- struct CheckpointReport¶
The checkpoint a head published.
- origin: String¶
The origin line.
- size: u64¶
Entries the checkpoint covers.
- root: String¶
Root at that size, lower-case hex.
- path: PathBuf¶
The checkpoint file.
- note: String¶
The signed note, as written.
- index: Option<Box<CheckpointReport>>¶
The index log’s checkpoint, signed with the same key under <origin>/index, once a run has been sealed.
Implementations
- impl CheckpointReport¶
Functions
- fn summary(&self) -> String¶
One line for stdout, two once the index log has a checkpoint.
- struct FindReport¶
What
ledger findfound.- unsigned: u64¶
Matching records past the checkpoint, which are not printed.
- checkpoint_size: u64¶
Entries the checkpoint covers.
- checkpoint_root: String¶
The checkpoint root, lower-case hex.
- stdout: String¶
What the command prints.
- struct FindRequest¶
What
ledger findneeds.- log: PathBuf¶
The JSON Lines log; its first line gives the origin.
- tiles: Option<PathBuf>¶
The tile log, else the log’s path with
.tiles.
- keys: Vec<String>¶
field=valuekeys; a record matches when it carries every one.
- public_key: PathBuf¶
The public key the checkpoint must be signed by.
- origin: Option<String>¶
The checkpoint origin, else derived from the log.
- json: bool¶
Print the records as a JSON array instead of index and line.
- struct Found¶
One record a find returned.
- index: u64¶
Leaf number.
- record: Value¶
The record.
- run: Option<u64>¶
Leaf number, in the index log, of the run manifest the lookup went through, or none when the record sits in the unsealed tail and was found by scan.
- struct SyncReport¶
What a sync left the tile log at.
- dir: PathBuf¶
The tile log directory.
- size: u64¶
Entries in the tile log after the sync.
- root: String¶
Root over them, lower-case hex.
- appended: u64¶
Entries this sync appended.
- rebuilt_from: Option<PathBuf>¶
Where a tile log that disagreed with the ledger was moved before the rebuild.
- runs: u64¶
Sorted runs a lookup goes through after the sync.
- sealed: bool¶
Whether this sync sealed the unsealed tail into a run.
Implementations
- impl SyncReport¶
Functions
- fn summary(&self) -> String¶
One line for stdout.
- fn warning(&self) -> Option<String>¶
The warning a rebuild earns, for stderr.