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-tiles crate.

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, so ledger find answers pkg=PETSc or route=kvm from 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 route can 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 dir extends the signed head of size and root and holds the ledger’s lines for those entries, and that a checkpoint it holds is signed by trusted as origin and 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 origin with key.

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= and id= for each of those fields the record carries, plus job=<build.job>` when build` 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: --origin when given, else eb-stack-ledger/<stack>/<year>` from the first record’s stack` 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 dir to 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 log lives: tiles when given, else the log’s path with .tiles appended (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 find found.

found: Vec<Found>

Records carrying every key, by index, each proven in the checkpoint.

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 find needs.

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=value keys; 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.