Struct ApprovalLedger 

pub struct ApprovalLedger { /* private fields */ }

An append-only ledger of human-in-the-loop decisions, keyed by fingerprint (last decision wins). Optionally persisted as JSONL so the approval state survives restarts — HITL decisions are durable harness state, not transient prompts.

Concurrency: a single writer per journal file is assumed. The stateless FFI opens a fresh ledger per call, so a product that drives approvals from multiple processes against one journal must serialize those writes itself (e.g. route them through the daemon). Reads tolerate the writer appending concurrently; a torn final line is skipped on load and counted in ApprovalLedger::skipped_on_load.

Implementations

impl ApprovalLedger

pub fn new() -> ApprovalLedger

pub fn with_journal(path: impl Into<PathBuf>) -> Result<ApprovalLedger, Error>

Create a ledger backed by a JSONL journal at path, loading any existing decisions. Each line is one ApprovalRecord; the last line for a fingerprint wins, so a later rejection overrides an earlier approval.

pub fn with_private_journal( path: impl Into<PathBuf>, ) -> Result<ApprovalLedger, Error>

with_journal for a journal CAR keeps in its own state root, such as the daemon’s ~/.car/approvals.jsonl. The load and every record go through the owner-private opens: the file is created 0600, an existing looser file is tightened in place, and a symlink at the path or in a parent directory, or a parent the user does not own, is an error rather than followed (#3403). A missing journal loads empty. Refusing at load matters as much as at write: a symlink to a file holding an Approved row would otherwise authorize an operation nobody approved. Records are written exactly as with_journal writes them, so fingerprints keep matching.

Caller-chosen journal paths (the FFI ledger_path) stay on with_journal: the private open also makes the parent directory 0700 and refuses one the user does not own, which a journal placed directly in /tmp would fail.

pub fn skipped_on_load(&self) -> usize

Number of unparseable lines skipped during the load. Nonzero means the journal is corrupt or was torn by a concurrent writer.

pub fn record( &mut self, record: ApprovalRecord, ) -> Result<&ApprovalRecord, Error>

Record a decision, persisting it to the journal when configured. Returns the stored record.

A journal write failure is an error, not best-effort (review A7): callers emit ApprovalRecorded audit events on the strength of this call, so a decision that only landed in memory must not be reported as durable. On Err the decision is NOT stored (memory and journal stay consistent — both lack it) and the caller must surface the failure. An in-memory ledger (no journal) cannot fail.

pub fn lookup(&self, fingerprint: &str) -> Option<&ApprovalRecord>

The current decision for a fingerprint, if any.

pub fn all(&self) -> impl Iterator<Item = &ApprovalRecord>

pub fn record_decision( &mut self, fingerprint: &str, required_tier: PermissionTier, decision: ApprovalDecision, reviewer: &str, reason: &str, evidence: Option<String>, ) -> Result<ApprovalRecord, Error>

Build and record a decision against an explicit fingerprint — the ledger-level twin of PermissionGate::record_for_fingerprint, for callers that share ONE ledger across many gates/sessions (e.g. the daemon’s shared approval substrate) and so must not route the write through any single session’s gate. Errs when the journal write fails (the decision is then NOT recorded — see Self::record).

Trait Implementations

impl Debug for ApprovalLedger

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for ApprovalLedger

fn default() -> ApprovalLedger

Returns the “default value” for a type.