Journal and Governance
Journal and governance in Locus — append-only change journal, governance hooks, and per-drive policy enforcement.
Purpose
File and directory model with metadata, mounts, streams, watchers, journals, permission modes, and governance.
This page follows the real source shape for Locus and explains the workflow a developer is likely to use first.
Developer workflow
Start from the smallest constructor or builder, perform one meaningful operation, inspect the returned state, then add the relevant policy, storage, or network integration. The examples below should be expanded whenever the crate API changes.
Governance changes (rotating roots, adjusting thresholds) are themselves journal entries and require the current governance threshold to sign. Plan rotations carefully — losing the current signers locks the drive.
Primary types to know
AllowAllLocusPolicy— models/locus/src/policy.rsCreateOptions— models/locus/src/ops.rsFileEntry— models/locus/src/entry.rsFileMetadata— models/locus/src/entry.rsJournalRecord— models/locus/src/journal.rsJournalStore— models/locus/src/journal.rsLocus— models/locus/src/locus.rsLocusConfig— models/locus/src/config.rsMountOptions— models/locus/src/config.rsMountPoint— models/locus/src/mount.rsMountTable— models/locus/src/mount.rsOpenOptions— models/locus/src/ops.rs
Example shape
use locus::{GovernanceType, JournalOp, JournalRecord, JournalState};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// GovernanceType describes who may sign writes against a Locus drive.
// HumanRoot is a single-identity root; MultiHumanRoot requires `threshold`
// out of `roots` signers to commit governance-bearing operations.
let solo = GovernanceType::HumanRoot("did:l1fe:alice".into());
let council = GovernanceType::MultiHumanRoot {
roots: vec![
"did:l1fe:alice".into(),
"did:l1fe:bob".into(),
"did:l1fe:carol".into(),
],
threshold: 2,
};
// The journal records every mutation in Prepared -> Applied -> Committed
// states. JournalRecord::new starts a record in Prepared.
let mut record = JournalRecord::new(JournalOp::WriteFile {
path: "/docs/README.md".into(),
size: 64,
});
assert_eq!(record.state, JournalState::Prepared);
// The Locus engine transitions the record as the operation makes progress;
// fsck and rollback observe these states to repair partial writes.
record.state = JournalState::Applied;
record.state = JournalState::Committed;
let threshold = match &council {
GovernanceType::MultiHumanRoot { threshold, .. } => Some(*threshold),
GovernanceType::HumanRoot(_) => None,
};
println!(
"solo={:?} council_threshold={:?} journal_op={:?} final_state={:?}",
solo, threshold, record.op, record.state,
);
Ok(())
}