Vault Lifecycle

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.

Storage contract

Document persistence format, integrity checks, read/write ordering, idempotency, compaction or repair behavior, and how callers recover from partial failures. This section should answer what data is durable and what can be reconstructed.

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::{CreateOptions, StrandVault, VaultConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // VaultConfig owns the storage factory, quotas, and indexing config.
    // Default() gives an on-disk vault under a temp namespace.
    let cfg = VaultConfig::default();
    cfg.validate()?;
    let vault = StrandVault::new(cfg).await?;

    // Authorize an agent namespace, then create a named strand for it.
    vault.authorize_agent("agent-namespace", "ops-bot").await?;
    let strand_arc = vault
        .create_for_agent(
            "agent-namespace",
            "audit-log",
            CreateOptions {
                name: Some("audit-log".into()),
                ..CreateOptions::default()
            },
        )
        .await?;

    let strands = vault.list().await?;
    println!(
        "vault_health={:?} strand_count={} pubkey={}",
        vault.health(),
        strands.len(),
        hex::encode(strand_arc.public_key()),
    );

    vault.shutdown().await?;
    Ok(())
}