strand-vault · vault

Reviewed implementation boundary: Vault construction does not automatically replay WAL entries. Snapshotting is a best-effort directory copy; replication mode/live settings are not implemented as runtime controls, and the capability preamble is not ACT authorization verification. See /libraries/strand-vault/overview.

Source: sigil/weave/libs/strand-vault/src/vault.rs. SHA-256: b4715ae737c80fd0eaec560ff36c59f62c5004d6c81d9d6173ff7e09f03093bc.

This reference follows declared source modules, retains conditional attributes, and includes public declarations and implementation methods. Private-module re-exports and trait resolution require the compiler; this is a source reference, not a claim that every listed item is a root import. Function bodies and constant values are omitted.

vault::StrandId

Strand identifier types

#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
pub enum StrandId {
    /// Identified by public key
    PublicKey([u8; 32]),
    /// Identified by name
    Name(String),
    /// Identified by index
    Index(u32),
    /// Agent-namespaced strand (opaque namespace string)
    AgentStrand {
        agent_namespace: String,
        strand_name: String,
    },
}

Source line: 26.

vault::StrandVault

Main StrandVault structure

pub struct StrandVault {

}

Source line: 57.

vault::VaultMetrics::cache_hits

pub fn cache_hits(&self) -> u64;

Source line: 114.

vault::VaultMetrics::policy_denied_read

pub fn policy_denied_read(&self) -> u64;

Source line: 117.

vault::VaultMetrics::policy_denied_delete

pub fn policy_denied_delete(&self) -> u64;

Source line: 121.

vault::VaultMetrics::divergence_detected

pub fn divergence_detected(&self) -> u64;

Source line: 125.

vault::VaultMetrics::replication_lag_high

#[allow(dead_code)]
pub fn replication_lag_high(&self) -> u64;

Source line: 130.

vault::VaultHealth

#[derive(Debug, Clone)]
pub struct VaultHealth {
pub strands_cached: usize,
pub authorized_agents: usize,
pub cache_hits: u64,
pub policy_denied_read: u64,
pub policy_denied_delete: u64,
pub divergence_detected: u64,
pub replication_lag_high: u64,
pub io_permits_available: usize,
pub repl_permits_available: usize
}

Source line: 137.

vault::AppendGuard

pub struct AppendGuard {
pub agent_namespace: String,
pub strand_id: StrandId
}

Source line: 149.

vault::StrandVault::new

Create a new vault

pub async fn new(config: VaultConfig) -> Result<Self>;

Source line: 160.

vault::StrandVault::derive_keypair

Derive a keypair for an agent's named strand

pub fn derive_keypair(&self, agent_namespace: &str, name: &str) -> Result<KeyPair>;

Source line: 252.

vault::StrandVault::authorize_agent

Authorize an agent to create strands

pub async fn authorize_agent(
        &self,
        agent_id: String,
        permissions: AgentPermissions,
    ) -> Result<()>;

Source line: 266.

vault::StrandVault::revoke_agent

Revoke an agent's authorization

pub async fn revoke_agent(&self, agent_id: &str) -> Result<()>;

Source line: 284.

vault::StrandVault::get_agent_strand

Get or create a strand for a specific agent

pub async fn get_agent_strand(&self, agent_namespace: &str, name: &str) -> Result<Arc<Strand>>;

Source line: 295.

vault::StrandVault::get

Get a strand by public key (must verify agent ownership)

pub async fn get(&self, public_key: &[u8; 32]) -> Result<Arc<Strand>>;

Source line: 334.

vault::StrandVault::create_for_agent

Create a new strand for an agent

pub async fn create_for_agent(
        &self,
        agent_namespace: &str,
        opts: CreateOptions,
    ) -> Result<Arc<Strand>>;

Source line: 359.

vault::StrandVault::get_by_name

Get a strand by name

pub async fn get_by_name(&self, name: &str) -> Result<Arc<Strand>>;

Source line: 398.

vault::StrandVault::get_by_index

Get a strand by index

pub async fn get_by_index(&self, index: u32) -> Result<Arc<Strand>>;

Source line: 409.

vault::StrandVault::list

List all strands

pub async fn list(&self) -> Result<Vec<StrandId>>;

Source line: 420.

vault::StrandVault::delete

Delete a strand

pub async fn delete(&self, id: &StrandId, requesting_agent: &str) -> Result<()>;

Source line: 436.

vault::StrandVault::check_headroom

Check if appending bytes would exceed quotas or headroom

pub fn check_headroom(&self, agent_namespace: &str, additional_bytes: u64) -> Result<()>;

Source line: 526.

vault::StrandVault::record_append

Record an append after it succeeds to update namespace byte accounting

pub fn record_append(&self, agent_namespace: &str, delta_bytes: u64);

Source line: 550.

vault::StrandVault::health

Health snapshot summarizing internal state

pub fn health(&self) -> VaultHealth;

Source line: 559.

vault::StrandVault::reindex

Trigger reindex for a strand's KV index.

Fail-closed until a real index builder ships — never silent success.

pub async fn reindex(&self, _id: &StrandId) -> Result<()>;

Source line: 591.

vault::StrandVault::export_prometheus_text

Export Prometheus-style metrics text for quick scraping

pub fn export_prometheus_text(&self) -> String;

Source line: 596.

vault::StrandVault::health_json

Export a simple health JSON snapshot

pub fn health_json(&self) -> serde_json::Value;

Source line: 628.

vault::StrandVault::snapshot

Create a filesystem snapshot for a set of strands under a label

pub async fn snapshot(
        &self,
        set: &[StrandId],
        label: &str,
        dst_root: &std::path::Path,
    ) -> Result<crate::snapshot::SnapshotRef>;

Source line: 644.

vault::StrandVault::restore

Restore a snapshot into the storage root for the strands present

pub async fn restore(&self, snapshot: &crate::snapshot::SnapshotRef) -> Result<()>;

Source line: 667.

vault::StrandVault::begin_append

Begin an append: enforce headroom and acquire an IO permit. Call complete_append when done.

#[instrument(skip(self))]
pub async fn begin_append(
        &self,
        agent_namespace: &str,
        _strand_id: &StrandId,
        additional_bytes: u64,
    ) -> Result<AppendGuard>;

Source line: 682.

vault::StrandVault::complete_append

Complete an append: record accounting and write WAL entry if configured

#[instrument(skip(self, guard))]
pub async fn complete_append(&self, guard: AppendGuard, actual_bytes: u64) -> Result<()>;

Source line: 705.

vault::StrandVault::shutdown

Shutdown the vault

pub async fn shutdown(&self) -> Result<()>;

Source line: 725.

vault::StrandVault::get_strand_by_discovery_key

Find a cached strand by discovery key (if present)

pub fn get_strand_by_discovery_key(&self, key: &[u8; 32]) -> Option<Arc<Strand>>;

Source line: 736.

vault::StrandVault::resolve_id_by_discovery_key

Resolve a strand id by its discovery key (if present in cache)

pub fn resolve_id_by_discovery_key(&self, key: &[u8; 32]) -> Option<StrandId>;

Source line: 747.

vault::StrandVault::append_with_repl_permit

Append to an existing strand using replication semaphore and tracing

#[instrument(skip(self, strand, data))]
pub async fn append_with_repl_permit(&self, strand: &mut Strand, data: &[u8]) -> Result<u64>;

Source line: 759.

vault::StrandVault::ingest_block_with_repl_permit

Ingest a verified remote block with replication backpressure and quota enforcement. This is idempotent: if the block sequence was already applied, it is treated as success.

pub async fn ingest_block_with_repl_permit(
        &self,
        discovery_key: &[u8; 32],
        seq: u64,
        header: &Header,
        data: &[u8],
    ) -> Result<()>;

Source line: 775.

vault::StrandVault::checkout_by_discovery_key

Checkout by discovery key for receiver-side exclusive writes

pub fn checkout_by_discovery_key(
        &self,
        key: &[u8; 32],
        mode: SessionMode,
    ) -> Result<SessionHandle>;

Source line: 841.

vault::StrandVault::record_divergence_detected

Metrics helpers for replication receiver

pub fn record_divergence_detected(&self);

Source line: 863.

vault::StrandVault::record_replication_lag_high

pub fn record_replication_lag_high(&self);

Source line: 869.

vault::StrandVault::begin_atom

Begin a multi-strand atom (WAL-backed)

pub async fn begin_atom(&self, strands: &[StrandId]) -> Result<Atom>;

Source line: 876.

vault::StrandVault::agent_namespace

Create a namespaced view of the vault for a specific agent

pub fn agent_namespace(&self, agent_namespace: &str, namespace: &str) -> String;

Source line: 897.

vault::StrandVault::replay_wal

Run WAL replay on startup applying entries to storage and in-memory state

pub async fn replay_wal(&self, wal_dir: &std::path::Path) -> Result<()>;

Source line: 907.

vault::StrandVault::checkout

Session checkout modes

pub fn checkout(&self, agent: &str, id: &StrandId, mode: SessionMode) -> Result<SessionHandle>;

Source line: 935.

vault::Atom

Atom representing a multi-strand batch

pub struct Atom {

}

Source line: 1009.

vault::Atom::append

Schedule an append to a strand within this atom

pub fn append(&mut self, id: StrandId, bytes: Vec<u8>);

Source line: 1019.

vault::Atom::commit

Commit the atom: write WAL, then apply appends

pub async fn commit(mut self) -> Result<()>;

Source line: 1024.

vault::Atom::rollback

Rollback: no-op since we only WAL on commit; drop the batch

pub fn rollback(self);

Source line: 1050.

vault::SessionMode

Session modes for checkout

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SessionMode {
    Read,
    WriteExclusive,
}

Source line: 1055.

vault::SessionHandle

Session handle RAII

#[derive(Debug)]
pub struct SessionHandle {

}

Source line: 1062.

vault::SessionHandle::read

pub fn read() -> Self;

Source line: 1078.

vault::SessionHandle::write

pub fn write(key: [u8; 32], permit: OwnedSemaphorePermit) -> Self;

Source line: 1085.

strand-vault · vault

On this page