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 N is rfc9162::leaf_hash over the bytes of line N without its newline. A head is the size and root over the first size leaves, signed with Ed25519 under DOMAIN. 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): append writes both, head signs both, and verify checks 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_id for 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 as serde_json writes 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. id and index are not checked here.

fn leaves(entries: &[Entry]) -> Vec<[u8; 32]>

The leaves of entries.

fn parse_log(text: &str) -> Result<Vec<Entry>>

Parse log text. Every line is checked: it is canonical, its index is its line number, its id recomputes, its fields are the ledger’s, and its stack is the stack of the first line.

fn read_log(path: &Path) -> Result<Vec<Entry>>

Read and check a log file.

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 without id and sig. index is 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 carries index or id must carry the values the ledger would write; ts is 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 verify checks.

Inclusion

Record record is in the signed head head.

record: usize

Leaf number.

head: PathBuf

Head file.

Consistency

The signed head to extends the signed head from.

from: PathBuf

The earlier head file.

to: PathBuf

The later head file.

Structs and Unions

struct AppendReport

What ledger append wrote.

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.

tiles: crate::ledger_tiles::SyncReport

The tile log after the 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 append needs.

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

impl Entry

Functions

fn leaf(&self) -> [u8; 32]

The RFC 9162 leaf hash of this record.

fn module(&self) -> &str

The record’s module.

struct HeadReport

What ledger head signed.

head: SignedHead

The signed head over the JSON Lines log.

tiles: crate::ledger_tiles::SyncReport

The tile log after its sync.

checkpoint: Option<crate::ledger_tiles::CheckpointReport>

The tile log’s checkpoint. None for an empty log signed without --origin: a size-0 head has no record to derive an origin from and nothing to checkpoint.

struct HeadRequest

What ledger head needs.

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 show found.

records: Vec<Value>

Matching records, newest first.

stdout: String

What the command prints.

struct ShowRequest

What ledger show needs.

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 size leaves, 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::material under DOMAIN, a tab, and ts.

fn read(path: &Path) -> Result<Self>

Read a head file.

fn sign(entries: &[Entry], key: &SigningKey, ts: &str) -> Self

Sign the head over entries.

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 path is refused rather than replaced or followed.

struct VerifyReport

A proof that checked.

kind: String

inclusion or consistency.

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

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.