weave-loom · repo — Weave Docs

Source: sigil/weave/tools/loom/src/repo.rs. SHA-256: d1d5ec68a7dae5f76ab2b0f732f53fc7dba6e0c9bc74cb69f12912535af1c33d.

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.

repo::RepoConfig

Persisted repository configuration.

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RepoConfig {
/// Schema version.

pub version: u32,
/// Repo-stable id (used for resource naming + replication discovery).

pub repo_id: String,
/// Agent DID that signs commits in this repo.

pub agent_did: String,
/// Default branch name (the branch HEAD points at on init).

pub default_branch: String,
/// Optional human-readable description.

#[serde(default)]
pub description: Option<String>,
/// Encryption-at-rest for blobs. When `true`, every blob written to

/// the locus is sealed with a per-blob ChaCha20-Poly1305 key derived

/// from the agent identity + repo_id (see `loom-encrypt`). The

/// blob_hash remains the plaintext BLAKE3 so dedup, merge, and the

/// transpiler still work; only the bytes on disk and over the wire

/// are opaque.

#[serde(default)]
pub private: bool
}

Source line: 27.

repo::RepoConfig::path_in

Path to the config file inside .loom/.

pub fn path_in(workdir: &Path) -> PathBuf;

Source line: 51.

repo::RepoConfig::load

Read config from .loom/config.toml.

pub fn load(workdir: &Path) -> Result<Self>;

Source line: 56.

repo::RepoConfig::save

Persist config to .loom/config.toml.

pub fn save(&self, workdir: &Path) -> Result<()>;

Source line: 63.

repo::Repo

Open repository — workdir + lazily-built [WeaveNode].

pub struct Repo {

}

Source line: 76.

repo::RepoMutationGuard

Process-scoped ownership of a repository mutation lease.

pub struct RepoMutationGuard(File);

Source line: 85.

repo::Repo::open

Open the repo rooted at workdir. Loads the config and identity from disk but does not start the WeaveNode (call [Repo::node] for that).

pub fn open(workdir: impl Into<PathBuf>) -> Result<Self>;

Source line: 96.

repo::Repo::discover

Discover the repo by walking up from the current directory.

pub fn discover() -> Result<Self>;

Source line: 144.

repo::Repo::workdir

Workdir root.

pub fn workdir(&self) -> &Path;

Source line: 150.

repo::Repo::config

Repository configuration.

pub fn config(&self) -> &RepoConfig;

Source line: 155.

repo::Repo::identity

Signing identity for this repo.

pub fn identity(&self) -> &WeaveIdentity;

Source line: 160.

repo::Repo::lock_mutation

Serialize every local operation that can mutate repository history, refs, the staging index, HEAD, or the materialized worktree. The lease is filesystem-backed and therefore coordinates independent Loom processes sharing this checkout.

pub fn lock_mutation(&self) -> Result<RepoMutationGuard>;

Source line: 168.

repo::Repo::node

Build (or return cached) WeaveNode for this repo.

The node is parameterized by the repo identity and storage dir so that commits land on the same Strand and refs/index live in the same Lens across runs. DHT port and bootstrap peers are read from the environment so multi-device tests can wire two nodes together without changing the porcelain:

LOOM_DHT_PORT: integer port for libp2p (default: SDK chooses).
LOOM_BOOTSTRAP: comma-separated peer multiaddrs/DIDs.

pub async fn node(&mut self) -> Result<Arc<WeaveNode>>;

Source line: 196.

repo::Repo::resources

Read the canonical name of the resources used by this repo.

pub fn resources(&self) -> RepoResources;

Source line: 362.

repo::Repo::commit_strands_for_replication

Commit strands this repo should track and announce for sparse sync.

pub fn commit_strands_for_replication(&self) -> Result<Vec<String>>;

Source line: 504.

repo::Repo::ensure_resources

Ensure the per-repo Weave resources exist (idempotent). Called on init and on first use of an existing repo whose backing dir was reset.

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

Source line: 523.

repo::Repo::master_key

Open the current master encryption key for this repo. Private repositories require a complete signed access profile and a keyring wrapped to the local encryption identity.

pub fn master_key(&self) -> Result<Option<loom_encrypt::MasterKey>>;

Source line: 587.

repo::Repo::master_keys

Open every local master key epoch newest-first. This lets readers decrypt old ciphertext after a member revocation rotates future keys.

pub fn master_keys(&self) -> Result<Vec<loom_encrypt::MasterKey>>;

Source line: 611.

repo::Repo::write_blob

Write a blob to the repo's blobs locus. Encrypts in-place when config.private. The /blobs directory is created lazily.

pub async fn write_blob(&mut self, blob_hash: &str, plaintext: &[u8]) -> Result<()>;

Source line: 636.

repo::Repo::read_blob

Read a blob from the repo's blobs locus. Decrypts in-place when config.private. Returns plaintext bytes.

Currently unused at the call sites — the read paths (restore, switch, diff, merge, reset, export_git) still go through node.locus_read_file directly; iteration 14 routes them through this helper so private repos decrypt transparently everywhere.

#[allow(dead_code)]
pub async fn read_blob(&mut self, blob_hash: &str) -> Result<Vec<u8>>;

Source line: 661.

repo::Repo::read_head

Read the current HEAD value: either a branch name (ref: refs/heads/main) or a detached commit id (commit:<hex>).

pub fn read_head(&self) -> Result<HeadRef>;

Source line: 672.

repo::Repo::write_head

Write HEAD to point at head.

pub fn write_head(&self, head: &HeadRef) -> Result<()>;

Source line: 679.

repo::RepoResources

Names of the canonical Weave resources used by a single repo.

pub struct RepoResources {
/// Strand that records commits.

pub commits_strand: String,
/// Locus drive that holds blob contents.

pub blobs_drive: String,
/// Lens DB that holds refs (HEAD, branches, tags).

pub refs_lens: String,
/// Lens DB that holds the staging index.

pub index_lens: String
}

Source line: 686.

repo::CommitRef

A globally-addressable commit position. Legacy Loom refs stored only a sequence number because every repo had exactly one commit strand. Multi- writer Loom stores need the strand name too.

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct CommitRef {
/// Commit strand name.

pub strand: String,
/// Sequence number within `strand`.

pub seq: CommitSeq
}

Source line: 886.

repo::CommitRef::new

Construct a new commit ref.

pub fn new(strand: String, seq: CommitSeq) -> Self;

Source line: 895.

repo::CommitRef::legacy

Construct a legacy single-writer commit ref.

pub fn legacy(seq: CommitSeq) -> Self;

Source line: 900.

repo::CommitRef::encode

Encode for storage in the refs lens.

pub fn encode(&self) -> Result<Vec<u8>>;

Source line: 905.

repo::CommitRef::decode

Decode a refs-lens payload. Plain integers are accepted for existing repos and mapped to the canonical single-writer commit strand.

pub fn decode(payload: &[u8]) -> Result<Self>;

Source line: 911.

repo::HeadRef

What HEAD points at.

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HeadRef {
    /// Symbolic ref to a branch (e.g. `refs/heads/main`).
    Symbolic(String),
    /// Detached HEAD pointing at a commit id directly.
    Detached(String),
}

Source line: 927.

repo::HeadRef::serialize

On-disk representation.

pub fn serialize(&self) -> String;

Source line: 936.

repo::HeadRef::parse

Parse the .loom/HEAD contents.

pub fn parse(text: &str) -> Result<Self>;

Source line: 944.

repo::HeadRef::branch_name

Branch name component (e.g. main) for symbolic HEADs.

pub fn branch_name(&self) -> Option<&str>;

Source line: 958.

repo::branch_tip

Look up the commit sequence number of a branch. Returns None if the branch has no commits yet (newly initialized repo).

#[allow(dead_code)]
pub async fn branch_tip(
    node: &WeaveNode,
    refs_lens: &str,
    branch: &str,
) -> Result<Option<CommitSeq>>;

Source line: 969.

repo::branch_tip_ref

Look up the global commit ref of a branch. Returns None if the branch has no commits yet.

pub async fn branch_tip_ref(
    node: &WeaveNode,
    refs_lens: &str,
    branch: &str,
) -> Result<Option<CommitRef>>;

Source line: 981.

repo::branch_heads_ref

Resolve all currently-known heads for a branch by combining the local refs lens with branch metadata found in replicated writer commit strands.

Private Loom repos are multi-writer: each writer appends to their own signed strand. The local loom.refs lens is still useful for local commands, but it cannot be the only source of branch truth after sparse peer replication because remote writers do not mutate this device's lens.

pub async fn branch_heads_ref(
    node: &WeaveNode,
    refs_lens: &str,
    branch: &str,
    candidate_strands: &[String],
) -> Result<Vec<CommitRef>>;

Source line: 1008.

repo::resolved_branch_tip_ref

Resolve the newest currently-known head for a branch.

pub async fn resolved_branch_tip_ref(
    node: &WeaveNode,
    refs_lens: &str,
    branch: &str,
    candidate_strands: &[String],
) -> Result<Option<CommitRef>>;

Source line: 1080.

repo::effective_branch_tip_ref

Resolve the effective branch tip under the repository visibility profile.

Public repositories are single-writer and retain mutable local Lens refs. Private repositories derive heads from authenticated append-only writer strands; local Lens state is only a cache and never overrides replication.

pub async fn effective_branch_tip_ref(
    node: &WeaveNode,
    refs_lens: &str,
    branch: &str,
    candidate_strands: &[String],
    private: bool,
) -> Result<Option<CommitRef>>;

Source line: 1097.

repo::resolve_head_tip_ref

Resolve the effective commit that HEAD points at, including replicated private writer strands that have not updated this device's refs lens.

pub async fn resolve_head_tip_ref(
    node: &WeaveNode,
    refs_lens: &str,
    head: &HeadRef,
    candidate_strands: &[String],
    private: bool,
) -> Result<Option<CommitRef>>;

Source line: 1113.

repo::resolve_commitish_ref

Resolve a user-facing commit-ish value.

Supports HEAD, branch names, numeric sequence numbers on the current effective head's strand, and unique commit hash prefixes reachable from the current effective branch heads.

pub async fn resolve_commitish_ref(
    node: &WeaveNode,
    refs_lens: &str,
    head: &HeadRef,
    target: &str,
    candidate_strands: &[String],
    private: bool,
) -> Result<Option<CommitRef>>;

Source line: 1139.

repo::commit_parent_refs

Parent refs for a commit, filling legacy same-strand parents when needed.

pub fn commit_parent_refs(current: &CommitRef, commit: &Commit) -> Vec<CommitRef>;

Source line: 1309.

repo::set_branch_tip

Update a branch ref to point at seq.

#[allow(dead_code)]
pub async fn set_branch_tip(
    node: &WeaveNode,
    refs_lens: &str,
    branch: &str,
    seq: CommitSeq,
) -> Result<()>;

Source line: 1327.

repo::set_branch_tip_ref

Update a branch ref to point at reference.

pub async fn set_branch_tip_ref(
    node: &WeaveNode,
    refs_lens: &str,
    branch: &str,
    reference: &CommitRef,
) -> Result<()>;

Source line: 1337.

repo::delete_branch_tip_ref

Delete a single-writer branch without allowing history scans to resurrect the branch. The tombstone is written first, so a failed ref deletion remains safely hidden.

pub async fn delete_branch_tip_ref(node: &WeaveNode, refs_lens: &str, branch: &str) -> Result<()>;

Source line: 1368.

repo::open_user_node

Open (or create) the user-wide WeaveNode at ~/.loom/weave/. This node is **shared across every loom repo for a single human user and holds the global namespaces:

loom.registry — every repo this user has published
loom.mandates — every mandate this user has been issued (or has issued to others)
loom.mars — cached MARS anchors for repos the user has seen

Per-repo state (commits strand, refs lens, index lens, blobs locus, PR store) still lives in each repo's own WeaveNode under <workdir>/.loom/weave/. The user-wide node and the per-repo node share the same WeaveIdentity (loaded from ~/.loom/identity/) so a single agent DID can author commits in any repo and own the global registry simultaneously.

First call generates a fresh user identity if one isn't already on disk; subsequent calls re-use it.

pub async fn open_user_node() -> Result<Arc<WeaveNode>>;

Source line: 1397.

repo::read_blob_via

Read a blob from the locus, decrypting if mek is Some. This free function exists so command modules that already hold a &WeaveNode (and not a &mut Repo) can transparently support private repos without restructuring their borrows.

#[allow(dead_code)]
pub async fn read_blob_via(
    node: &WeaveNode,
    blobs_drive: &str,
    mek: Option<&loom_encrypt::MasterKey>,
    blob_hash: &str,
) -> Result<Vec<u8>>;

Source line: 1429.

repo::read_blob_via_keys

Read a blob from the locus, decrypting with any local repo-key epoch.

pub async fn read_blob_via_keys(
    node: &WeaveNode,
    blobs_drive: &str,
    meks: &[loom_encrypt::MasterKey],
    blob_hash: &str,
) -> Result<Vec<u8>>;

Source line: 1440.

repo::read_blob_via_keys_or_commits

Read a blob from the local Locus drive, falling back to sparse payloads embedded in replicated commit strands. The fallback is what lets private multi-writer repos materialize remote commits without mixing unrelated writers into one Locus writer key.

pub async fn read_blob_via_keys_or_commits(
    node: &WeaveNode,
    blobs_drive: &str,
    commit_strands: &[String],
    meks: &[loom_encrypt::MasterKey],
    blob_hash: &str,
) -> Result<Vec<u8>>;

Source line: 1455.

repo::read_commit

Read a commit object from the strand.

pub async fn read_commit(node: &WeaveNode, commits_strand: &str, seq: CommitSeq) -> Result<Commit>;

Source line: 1529.

repo::read_commit_ref

Read a commit object from a global commit ref.

pub async fn read_commit_ref(node: &WeaveNode, reference: &CommitRef) -> Result<Commit>;

Source line: 1546.

weave-loom · repo

On this page