Fsck and WAL

Purpose

Policy-aware strand vault with sessions, permissions, storage backends, WAL, fsck, snapshots, and replication.

This page follows the real source shape for Strand Vault 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.

Primary types to know

• AgentPermissions — libs/strand-vault/src/permissions.rs
• AppendGuard — libs/strand-vault/src/vault.rs
• Atom — libs/strand-vault/src/vault.rs
• CreateOptions — libs/strand-vault/src/config.rs
• DefaultPolicy — libs/strand-vault/src/policy.rs
• FileMetadataStorage — libs/strand-vault/src/storage/filesystem.rs
• FileSystemStorage — libs/strand-vault/src/storage/filesystem.rs
• FileSystemStorageFactory — libs/strand-vault/src/storage/filesystem.rs
• FileStrandStorage — libs/strand-vault/src/storage/filesystem.rs
• FsckReport — libs/strand-vault/src/fsck.rs
• IndexingConfig — libs/strand-vault/src/config.rs
• LruStoragePool — libs/strand-vault/src/storage/mod.rs

Example shape

use strand_vault::wal::{Wal, WalEntry};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // The Wal lives at `<dir>/wal.log`. Every vault mutation appends a length-
    // prefixed bincode WalEntry; replay re-applies them after a crash.
    let dir = tempfile::tempdir()?;
    let wal = Wal::new(dir.path());

    wal.append(&WalEntry::SetNamespace("auditors".into())).await?;
    wal.append(&WalEntry::Append {
        strand: "audit-log".into(),
        seq: 0,
        size: 128,
    }).await?;
    wal.append(&WalEntry::Append {
        strand: "audit-log".into(),
        seq: 1,
        size: 96,
    }).await?;

    // replay() yields each WalEntry in order so the vault can rebuild its state.
    let mut applied = 0u32;
    wal.replay(|_entry| { applied += 1; Ok(()) }).await?;
    println!("wal_entries_replayed={applied}");
    Ok(())
}