mod ledger¶
- module ledger¶
Per-stack software ledger: one append-only JSON Lines file of install, rebuild, retire, move, access, removal, finding and correction events, hashed as an RFC 9162 Merkle log.
Each line is the canonical JSON of one record: keys sorted by their UTF-8 bytes, no whitespace outside strings, integers only. The leaf of record
Nisrfc9162::leaf_hashover the bytes of lineNwithout its newline. A head is the size and root over the firstsizeleaves, signed with Ed25519 underDOMAIN. An inclusion proof shows one record is in a signed head; a consistency proof shows a later head extends an earlier one, which a rewritten log cannot.The signing key is a path the writer passes on each call. A key inside the log’s directory is refused, so the key never travels with the log.
Every line is also an entry of the tile log beside the file (
crate::ledger_tiles):appendwrites both,headsigns both, andverifychecks that the tile log extends the signed head and holds the same lines.Variables
- const ACTIONS: &[&str]¶
The events a record can carry.
- const DOMAIN: &str¶
The name a head signature covers, so a head of this log is not a head of any other log that signs RFC 9162 heads.
- const STAGES: &[&str]¶
Stages of an operation that runs in steps.
Functions
- fn append(request: &AppendRequest) -> Result<AppendReport>¶
Append one record to the log under an exclusive lock on the log file.
A producer can persist a unique
build.event_idfor each event packet. An identical retry acknowledges the existing entry and writes a current signed head without appending another record. A reused identifier with different content is refused. An expected head must match the history; only an acknowledged retry can accept a matching prefix instead of the tip.
- fn canonical(value: &Value) -> Result<String>¶
The canonical JSON of
value: object keys sorted by their UTF-8 bytes, no whitespace outside strings, strings escaped asserde_jsonwrites them. A number that is not an integer is refused, because two writers can print the same float two ways.
- fn check_fields(record: &Map<String, Value>) -> Result<()>¶
Check a record’s fields against the ledger format.
idandindexare not checked here.
- fn parse_log(text: &str) -> Result<Vec<Entry>>¶
Parse log text. Every line is checked: it is canonical, its
indexis its line number, itsidrecomputes, its fields are the ledger’s, and itsstackis the stack of the first line.
- fn read_public_key(path: &Path) -> Result<VerifyingKey>¶
Read an Ed25519 public key: SubjectPublicKeyInfo PEM, as openssl pkey -pubout writes it, or the 64 hex characters a head file carries.
- fn read_signing_key(path: &Path) -> Result<SigningKey>¶
Read an Ed25519 private key: PKCS#8 PEM, as openssl genpkey -algorithm ed25519 writes it.
- fn record_id(record: &Map<String, Value>) -> Result<String>¶
The record
id: SHA-256 of the canonical JSON of the record withoutidandsig.indexis inside it, so a record moved to another position has another id.
- fn seal_record(record: &Value, index: usize, now: &str) -> Result<Entry>¶
Turn a record into the log line for position
index. A record that already carriesindexoridmust carry the values the ledger would write;tsis filled with the current UTC time when absent.
- fn show(request: &ShowRequest) -> Result<ShowReport>¶
List records, newest first, optionally for one package.
- fn sign_head(request: &HeadRequest) -> Result<HeadReport>¶
Sign the log’s current head, and the tile log’s checkpoint with the same key. The log is read and the head written under the signer’s side of the writer lock, so the head is the log between two appends and a head an append wrote is never replaced by an older one. The signer opens the log and its record lock for reading only.
- fn verify(request: &VerifyRequest) -> Result<VerifyReport>¶
Check an inclusion or consistency proof computed from the log against signed heads, then that the tile log extends the head and holds the same lines. Any failure is an error.
Enums
- enum VerifyMode¶
Which proof
ledger verifychecks.
Structs and Unions
- struct AppendReport¶
What
ledger appendwrote.- index: usize¶
The appended record’s leaf number.
- id: String¶
The appended record’s id.
- line: String¶
The canonical line written.
- head: rfc9162::Head¶
The head after the append.
- signed: Option<SignedHead>¶
The signed head, when a key was given.
- replayed: bool¶
Whether this acknowledges an identical event that is in the log.
- quarantined: Option<(usize, PathBuf)>¶
The byte count and quarantine file of an interrupted tail that was cut from the log before this append.
- checkpoint: Option<crate::ledger_tiles::CheckpointReport>¶
The tile log’s checkpoint, when a key was given.
Implementations
- impl AppendReport¶
Functions
- fn summary(&self) -> String¶
One line for stdout.
- struct AppendRequest¶
What
ledger appendneeds.- log: PathBuf¶
The JSON Lines log. Created when absent.
- record: PathBuf¶
The record, a JSON object file.
- expect_head: Option<PathBuf>¶
A head the log must still be at: a writer passes the head it last saw, so two writers cannot both append on the same head unnoticed.
- key: Option<PathBuf>¶
Ed25519 PKCS#8 PEM key to sign the new head with.
- head_out: Option<PathBuf>¶
Where to write the new signed head. Needs
key.
- tiles: Option<PathBuf>¶
The tile log, else the log’s path with
.tiles.
- origin: Option<String>¶
The checkpoint origin, else derived from the log. Used with
key.
- struct Entry¶
One line of the log.
- index: usize¶
Leaf number, which is also the record’s
index.
- id: String¶
The record’s
id.
- line: String¶
The canonical line, without its newline. Its bytes are the leaf.
- record: Map<String, Value>¶
The parsed record.
Implementations
- struct HeadReport¶
What
ledger headsigned.- head: SignedHead¶
The signed head over the JSON Lines log.
- struct HeadRequest¶
What
ledger headneeds.- log: PathBuf¶
The JSON Lines log.
- key: PathBuf¶
Ed25519 PKCS#8 PEM key.
- out: PathBuf¶
The head file to write.
- ts: Option<String>¶
Signing time, RFC 3339 UTC. Defaults to now.
- tiles: Option<PathBuf>¶
The tile log, else the log’s path with
.tiles.
- origin: Option<String>¶
The checkpoint origin, else eb-stack-ledger/<stack>/<year>.
- struct ShowReport¶
What
ledger showfound.- records: Vec<Value>¶
Matching records, newest first.
- stdout: String¶
What the command prints.
- struct ShowRequest¶
What
ledger showneeds.- log: PathBuf¶
The JSON Lines log.
- package: Option<String>¶
A module (
PETSc/3.25.0-foss-2026.1) or a software name (PETSc).
- json: bool¶
Print the records as JSON instead of a table.
- struct SignedHead¶
A signed tree head, as written to a head file.
- domain: String¶
Always
DOMAIN.
- size: usize¶
Number of records the root covers.
- root: String¶
Merkle root over the first
sizeleaves, lower-case hex.
- ts: String¶
UTC time the head was signed, RFC 3339.
- public_key: String¶
Ed25519 public key of the signer, lower-case hex.
- signature: String¶
Ed25519 signature over
SignedHead::material, lower-case hex.
Implementations
- impl SignedHead¶
Functions
- fn check(&self, trusted: &VerifyingKey) -> Result<()>¶
Check the domain, that the signer is
trusted, and the signature.
- fn material(size: usize, root: &str, ts: &str) -> Vec<u8>¶
The bytes the signature covers:
rfc9162::Head::materialunderDOMAIN, a tab, andts.
- fn read(path: &Path) -> Result<Self>¶
Read a head file.
- fn write(&self, path: &Path) -> Result<()>¶
Write a head file: the head as JSON, one line. The file is replaced atomically, so a reader sees the previous head or this one and a failed write leaves the previous head in place. A symbolic link at
pathis refused rather than replaced or followed.
- struct VerifyReport¶
A proof that checked.
- kind: String¶
inclusionorconsistency.
- proof: Vec<String>¶
The proof nodes, lower-case hex, innermost first.
- tiles_size: u64¶
Entries in the tile log, which extends the head.
- tiles_root: String¶
The tile log’s root, lower-case hex.
- stdout: String¶
What the command prints.
- struct VerifyRequest¶
What
ledger verifyneeds.- log: PathBuf¶
The JSON Lines log.
- public_key: PathBuf¶
The public key heads must be signed by.
- mode: VerifyMode¶
The proof to check.
- tiles: Option<PathBuf>¶
The tile log, else the log’s path with
.tiles.
- origin: Option<String>¶
The checkpoint origin, else derived from the log.