Struct Repository 

pub struct Repository { /* private fields */ }

A Heddle repository.

Implementations

impl Repository

pub fn merge_state_manager(&self) -> MergeStateManager

impl Repository

pub fn suggest_context_targets( &self, state: &State, limit: usize, ) -> Result<Vec<ContextSuggestion>, Error>

impl Repository

pub fn get_context_blob( &self, context_root: &ContentHash, target: &ContextTarget, ) -> Result<Option<ContextBlob>, HeddleError>

Get the context blob for a target from the given state’s context tree.

pub fn set_context_blob( &self, context_root: Option<&ContentHash>, target: &ContextTarget, blob: &ContextBlob, ) -> Result<ContentHash, HeddleError>

Store a context blob at a target, returning the new context tree root hash.

If context_root is None, creates a new context tree from scratch.

pub fn remove_context_at_target( &self, context_root: &ContentHash, target: &ContextTarget, scope: Option<&AnnotationScope>, ) -> Result<Option<ContentHash>, HeddleError>

Remove context at a target (optionally filtered by scope).

Returns the new context tree root, or None if the tree is now empty.

pub fn remove_context_target( &self, context_root: &ContentHash, target: &ContextTarget, ) -> Result<Option<ContentHash>, HeddleError>

pub fn list_context_entries( &self, context_root: &ContentHash, prefix: Option<&Path>, ) -> Result<Vec<ContextEntry>, HeddleError>

List all context entries in the tree, optionally filtered by file prefix.

pub fn find_annotation( &self, context_root: &ContentHash, annotation_id: &str, ) -> Result<Option<(ContextTarget, ContextBlob, usize)>, HeddleError>

pub fn inherit_parent_context(parent: &State) -> Option<ContentHash>

Carry a single parent state’s context tree forward onto a new snapshot. Because context trees are content-addressed, this is a pointer copy: the new state’s context field gets the same ContentHash as the parent. Annotations attached upstream remain active at the new state, and the existing on-demand staleness check (which compares the stored source_hash against the current bytes at the anchor) naturally reports drift caused by the new tree.

Returns None when the parent has no context tree.

pub fn union_parent_contexts( &self, parents: &[&State], ) -> Result<Option<ContentHash>, HeddleError>

Build a unioned context tree across multiple parent states for a merge snapshot. Annotations from every parent appear in the result; when the same annotation_id is present on more than one parent the revision with the latest created_at wins (with a stable tiebreak on revision_id so the merge stays deterministic).

Targets that only exist on one side propagate unchanged (single-blob pointer copy via the existing tree). Targets present on both sides are merged blob-by-blob: annotations are deduped by id, the per-id revisions are picked by latest-created_at, and the resulting blob is rewritten via set_context_blob.

Returns None when none of the parents has any context.

impl Repository

pub fn diff_trees( &self, from: &ContentHash, to: &ContentHash, ) -> Result<FileChangeSet, HeddleError>

Get the difference between two trees.

impl Repository

pub fn goto(&self, target: &ChangeId) -> Result<(), HeddleError>

Move worktree to a different state.

pub fn fast_forward_attached( &self, target: &ChangeId, ) -> Result<(), HeddleError>

Fast-forward the current checkout to target.

If HEAD was attached to a thread, advance that thread’s ref so the thread now points at target and re-attach HEAD. If HEAD was detached, advance to target while remaining detached.

Use this anywhere you’d previously call Repository::goto from a context where HEAD was potentially attached (merge/rebase fast-forward, pull/fetch, etc). The low-level goto unconditionally writes Head::Detached, which silently strands the attached thread at its pre-op state — this helper preserves attached-HEAD semantics so the thread’s ref and metadata advance with the worktree.

pub fn goto_verified_clean(&self, target: &ChangeId) -> Result<(), HeddleError>

pub fn goto_verified_clean_without_record( &self, target: &ChangeId, ) -> Result<(), HeddleError>

pub fn goto_without_record(&self, target: &ChangeId) -> Result<(), HeddleError>

impl Repository

pub fn query_history( &self, query: &HistoryQuery, ) -> Result<Vec<State>, HeddleError>

Walk first-parent history and return states matching the query.

impl Repository

pub fn inspect_performance( &self, ) -> Result<RepositoryPerformanceInspectionReport, HeddleError>

pub fn inspect_performance_with_options( &self, options: &WorktreeStatusOptions, ) -> Result<RepositoryPerformanceInspectionReport, HeddleError>

pub fn run_maintenance( &self, ) -> Result<RepositoryMaintenanceRunReport, HeddleError>

pub fn run_maintenance_with_options( &self, options: &WorktreeStatusOptions, ) -> Result<RepositoryMaintenanceRunReport, HeddleError>

impl Repository

pub fn warm_canonical_store_for_state( &self, state_id: &ChangeId, ) -> Result<WarmCanonicalStoreStats, HeddleError>

Promote every reachable blob from state_id’s tree(s) into the canonical loose-uncompressed store, so a subsequent materialize_tree (or N parallel materializations) can reflink from the canonical store without paying the decompress-on-first-clone tax.

Returns counts of work done. Errors per blob are accumulated rather than bubbled up so a single corrupt or missing object doesn’t poison the whole warm pass — the lazy path inside materialize_blob will surface that loudly when it actually matters.

pub fn warm_canonical_store_for_states( &self, state_ids: &[ChangeId], ) -> Result<WarmCanonicalStoreStats, HeddleError>

Multi-state variant. Walks each state’s tree once, dedupes the union of reachable blob hashes across all of them, and promotes them. Useful when materializing several sibling states from the same parent in quick succession (the heddle delegate-style flow).

pub fn materialize_tree( &self, tree: &Tree, dir: &Path, ) -> Result<(), HeddleError>

Materialize a tree to the filesystem.

impl Repository

pub fn state_origin(&self, state: &State) -> Origin

pub fn get_state_provenance_root( &self, state: &State, ) -> Result<Option<ContentHash>, HeddleError>

pub fn get_file_provenance_for_state( &self, state: &State, path: &Path, ) -> Result<Option<FileProvenance>, HeddleError>

impl Repository

pub fn resolve_state(&self, spec: &str) -> Result<Option<ChangeId>, HeddleError>

Resolve a state specifier (HEAD, thread, marker, full/short ID, HEAD~N).

pub fn resolve_agent(&self) -> Option<Agent>

impl Repository

pub fn sign_state( &self, state_id: &ChangeId, signer: &dyn Signer, ) -> Result<(), HeddleError>

Sign a state with the given signer.

This loads the state, signs it, and stores the updated state.

Arguments

• state_id - The change ID of the state to sign
• signer - The signer to use

Errors

Returns an error if the state is not found or signing fails.

pub fn sign_state_with_key( &self, state_id: &ChangeId, key_path: &Path, algorithm: Option<&str>, ) -> Result<(), HeddleError>

Sign a state using a key file.

Arguments

• state_id - The change ID of the state to sign
• key_path - Path to the private key file
• algorithm - Optional algorithm hint (auto-detected if not specified)

pub fn verify_state_signature( &self, state_id: &ChangeId, ) -> Result<SignatureStatus, HeddleError>

Verify a state’s signature.

Returns the signature status:

• SignatureStatus::Valid if the signature is valid
• SignatureStatus::Invalid if the signature is invalid
• SignatureStatus::Unsigned if the state has no signature

Arguments

• state_id - The change ID of the state to verify

pub fn get_state_signature( &self, state_id: &ChangeId, ) -> Result<Option<StateSignature>, HeddleError>

Get the signature of a state.

Returns None if the state is not found or has no signature.

impl Repository

pub fn snapshot( &self, intent: Option<String>, confidence: Option<f32>, ) -> Result<State, HeddleError>

Create a snapshot of the current worktree.

pub fn snapshot_with_attribution( &self, intent: Option<String>, confidence: Option<f32>, attribution: Attribution, ) -> Result<State, HeddleError>

Create a snapshot with explicit attribution.

pub fn snapshot_with_attribution_profiled( &self, intent: Option<String>, confidence: Option<f32>, attribution: Attribution, ) -> Result<SnapshotExecution, HeddleError>

Create a snapshot with profiling details for the hot path.

pub fn snapshot_merge_with_attribution( &self, merge_parent: &ChangeId, intent: Option<String>, confidence: Option<f32>, attribution: Attribution, merge_base: Option<ChangeId>, ) -> Result<State, HeddleError>

Create a merge state with two parents.

impl Repository

pub fn build_tree(&self, dir: &Path) -> Result<Tree, HeddleError>

Build a tree from a directory.

pub fn build_tree_profiled( &self, dir: &Path, ) -> Result<(Tree, TreeBuildProfile), HeddleError>

pub fn compare_worktree_cached( &self, tree: &Tree, ) -> Result<WorktreeStatus, HeddleError>

Compare the worktree against a tree using the persisted binary index.

pub fn compare_worktree_cached_detailed( &self, tree: &Tree, ) -> Result<WorktreeStatusDetailed, HeddleError>

pub fn compare_worktree_cached_with_options( &self, tree: &Tree, options: &WorktreeStatusOptions, ) -> Result<WorktreeStatus, HeddleError>

Compare the worktree against a tree using the persisted binary index.

pub fn compare_worktree_cached_detailed_with_options( &self, tree: &Tree, options: &WorktreeStatusOptions, ) -> Result<WorktreeStatusDetailed, HeddleError>

pub fn compare_worktree_cached_profiled_with_options( &self, tree: &Tree, options: &WorktreeStatusOptions, ) -> Result<(WorktreeStatus, WorktreeCompareProfile), HeddleError>

pub fn compare_worktree_cached_detailed_profiled_with_options( &self, tree: &Tree, options: &WorktreeStatusOptions, ) -> Result<(WorktreeStatusDetailed, WorktreeCompareProfile), HeddleError>

pub fn worktree_is_clean_cached(&self, tree: &Tree) -> Result<bool, HeddleError>

Return whether the worktree matches the provided tree.

pub fn worktree_is_clean_cached_with_options( &self, tree: &Tree, options: &WorktreeStatusOptions, ) -> Result<bool, HeddleError>

Return whether the worktree matches the provided tree.

pub fn inspect_change_monitor_with_options( &self, options: &WorktreeStatusOptions, ) -> Result<ChangeMonitorReport, HeddleError>

impl Repository

pub fn remove_tracked_descendants(&self, path: &Path) -> Result<(), HeddleError>

Remove only the heddle-tracked descendants beneath path, preserving any heddle-ignored siblings (.git/, target/, node_modules/, …).

This exists so commands that mutate the worktree at the top-level tree-entry granularity (merge, cherry-pick, revert) can drop a tracked directory without recursively destroying the user’s local build artifacts, dependencies, or co-located git state. The shape matches remove_existing_path in this module: tracked content is removed, then the directory itself is removed if empty; if ignored content keeps it occupied, the dir is left in place. That keeps disk in lock-step with the new tree (no stale tracked file under the dir) without nuking work the user expects to survive.

Ignore-pattern based variant. Uses the current .heddleignore to decide which children to preserve. This is unsafe for the merge/cherry-pick/revert flow when a tracked path is also matched by a current ignore rule: the file would silently survive on disk after HEAD advances. Prefer Self::remove_tracked_descendants_with_source in those flows so removal is driven by the source-tree’s actual tracked set.

path must be inside the repository root. If it doesn’t exist, this is a no-op. If it’s a regular file or symlink, it is removed.

pub fn remove_tracked_descendants_with_source( &self, path: &Path, source_subtree: &Tree, ) -> Result<(), HeddleError>

Tree-driven variant of Self::remove_tracked_descendants.

Removal is driven by source_subtree — the subtree at path in the state we’re transitioning AWAY from. Every blob/symlink it lists is removed; nested directory entries are recursed into using the matching child subtree. This is intentionally independent of the current ignore rules: a .heddleignore (or config-level) rule that newly matches a previously-tracked path must NOT silently preserve that path on disk. Doing so would let HEAD advance past a tree where the path is gone while the worktree still holds the stale content, hidden from heddle status by the same ignore rule. Tracked-tree membership is the only source of truth here.

path must be inside the repository root. If it doesn’t exist, this is a no-op. If it’s a regular file or symlink, it is removed.

pub fn resolve_subtree( &self, root_tree: &Tree, rel_path: &Path, ) -> Result<Option<Tree>, HeddleError>

Look up the subtree at rel_path within root_tree. Returns None if the path isn’t reachable as a Tree-typed entry (missing entry, blob entry, or unresolved hash). Used by Self::remove_tracked_descendants_with_source callers to derive the source subtree from a top-level tree entry.

impl Repository

pub fn from_parts( root: PathBuf, heddle_dir: PathBuf, store: Box<dyn ObjectStore>, refs: Box<dyn RefBackend<Error = HeddleError>>, oplog: Box<dyn OpLogBackend>, config: RepoConfig, shallow: ShallowInfo, ) -> Repository

Expert-only constructor for callers that already own the repository’s component backends and invariant state.

Callers must ensure all backends point at the same repository root, the heddle_dir exists and is canonical for that root, and shallow matches the on-disk shallow metadata. Prefer Repository::init, Repository::open, or Repository::open_with_store unless a cross-crate integration genuinely needs to assemble the pieces manually.

pub fn init(path: impl AsRef<Path>) -> Result<Repository, HeddleError>

Initialize a new bare repository at the given path.

Creates the on-disk .heddle structure and an attached main HEAD, but does not seed any threads or states. Callers that want a ready-to-use repository (with a main thread pointing at an empty-tree snapshot) should use Repository::init_default. Callers that intend to populate the repository from an external source (e.g. git import) should use init directly so the imported refs become the sole source of truth.

pub fn init_default(path: impl AsRef<Path>) -> Result<Repository, HeddleError>

Initialize a new repository with a seeded main thread.

Convenience wrapper: equivalent to Repository::init followed by Repository::seed_default_thread. This is the normal entry point for fresh, user-created repositories where main should exist immediately.

pub fn bootstrap_git_overlay( path: impl AsRef<Path>, ) -> Result<Repository, HeddleError>

Initialize Heddle sidecar storage in an existing Git repository.

Unlike Repository::init_default, this keeps the repo unseeded and mirrors the current Git branch attachment into Heddle’s HEAD so commands like heddle status can immediately reflect the user’s current branch and dirty worktree.

pub fn open_with_store( heddle_dir: impl AsRef<Path>, store: Box<dyn ObjectStore>, ) -> Result<Repository, HeddleError>

Open an existing Heddle repository using a custom object store backend.

pub fn open(path: impl AsRef<Path>) -> Result<Repository, HeddleError>

Open an existing repository.

Searches for .heddle/ in the given path and its ancestors. .heddle/ is always a directory; its contents distinguish a main repo from a worktree pointer:

• Main repo: .heddle/objects/, .heddle/refs/, .heddle/HEAD, .heddle/state/, etc.
• Worktree: .heddle/objectstore (text pointer to the shared .heddle/), .heddle/HEAD (per-checkout), .heddle/state/ (per-checkout cached state).

pub fn root(&self) -> &Path

pub fn heddle_dir(&self) -> &Path

pub fn capability(&self) -> RepositoryCapability

pub fn capability_label(&self) -> &'static str

pub fn storage_model_label(&self) -> &'static str

pub fn hosted_enabled(&self) -> bool

pub fn current_lane(&self) -> Result<Option<String>, HeddleError>

pub fn operation_status( &self, ) -> Result<Option<RepositoryOperationStatus>, HeddleError>

pub fn git_remote_tracking_status( &self, ) -> Result<Option<GitRemoteTrackingStatus>, HeddleError>

pub fn git_overlay_import_hint( &self, ) -> Result<Option<GitOverlayImportHint>, HeddleError>

pub fn git_overlay_branch_tips( &self, ) -> Result<Vec<GitOverlayBranchTip>, HeddleError>

pub fn git_overlay_tag_tips(&self) -> Result<Vec<GitOverlayTagTip>, HeddleError>

pub fn git_overlay_branch_tip( &self, name: &str, ) -> Result<Option<GitOverlayBranchTip>, HeddleError>

pub fn git_overlay_tag_tip( &self, name: &str, ) -> Result<Option<GitOverlayTagTip>, HeddleError>

pub fn git_overlay_worktree_status( &self, ) -> Result<Option<WorktreeStatus>, HeddleError>

pub fn git_overlay_current_branch(&self) -> Result<Option<String>, HeddleError>

pub fn list_git_checkpoints( &self, ) -> Result<Vec<GitCheckpointRecord>, HeddleError>

pub fn latest_git_checkpoint_for_change( &self, change_id: &ChangeId, ) -> Result<Option<GitCheckpointRecord>, HeddleError>

pub fn record_git_checkpoint( &self, change_id: &ChangeId, git_commit: impl Into<String>, summary: impl Into<String>, ) -> Result<GitCheckpointRecord, HeddleError>

pub fn store(&self) -> &dyn ObjectStore

pub fn init_worktree( path: impl AsRef<Path>, shared_galeed_dir: impl AsRef<Path>, ) -> Result<(), HeddleError>

pub fn refs(&self) -> &dyn RefBackend<Error = HeddleError>

pub fn oplog(&self) -> &dyn OpLogBackend

pub fn op_scope(&self) -> String

pub fn repo_config(&self) -> &RepoConfig

pub fn config(&self) -> &RepoConfig

pub fn get_tree_for_state( &self, state_id: &ChangeId, ) -> Result<Option<Tree>, HeddleError>

pub fn ignore_patterns(&self) -> Result<Vec<String>, HeddleError>

pub fn nested_thread_worktree_exclusions( &self, walk_root: &Path, ) -> Result<Vec<PathBuf>, HeddleError>

Canonical absolute paths of other threads’ worktrees that are strict descendants of walk_root. The walker uses these to avoid scanning a sibling thread’s files into the current thread’s tree (a common shape when an agent worktree is materialized inside the parent repo, e.g. --path-prefix ./agents). Computed once per scan, not once per file.

Returns paths that

• are strict descendants of canonical walk_root, and
• are NOT equal to walk_root itself (each thread can scan its own worktree without excluding itself).

Threads with no recorded worktree, or worktrees that no longer exist on disk, are skipped without error.

pub fn head(&self) -> Result<Option<ChangeId>, HeddleError>

pub fn head_ref(&self) -> Result<Head, HeddleError>

pub fn active_worktree_path(&self) -> Result<PathBuf, HeddleError>

Resolve the on-disk worktree path for the active thread.

This is the canonical “where does the current thread live on disk” lookup. It reads HEAD, looks up the attached thread’s metadata (via crate::ThreadManager), and returns the recorded execution_path (or materialized_path if unset). When no thread has a recorded path — main, threads created without a separate worktree, or HEAD::Detached — this falls back to Self::root.

Worktree-mutating commands (merge, rebase, goto, ship) should resolve their target via this helper so that heddle thread switch X && heddle merge Y lands the merge into thread X’s dedicated worktree, not into whichever directory the operator happened to invoke heddle from. Snapshot/capture intentionally stay CWD-based: the agent inside their worktree captures that worktree.

pub fn current_state(&self) -> Result<Option<State>, HeddleError>

pub fn get_principal(&self) -> Result<Principal, HeddleError>

pub fn get_attribution(&self) -> Result<Attribution, HeddleError>

pub fn is_shallow(&self, id: &ChangeId) -> bool

pub fn set_shallow( &self, state_id: &ChangeId, _parents: &[ChangeId], ) -> Result<(), HeddleError>

pub fn record_missing_blob(&self, hash: ContentHash) -> Result<(), HeddleError>

pub fn seed_default_thread(&self) -> Result<(), HeddleError>

Seed a main thread pointing at an empty-tree root state.

The seeded state is written to the object store and pointed at by the main thread ref, but is deliberately NOT recorded in the oplog: init is a point-of-creation event, not user work, and should not be undoable. No-op if main already exists.

The seed state uses a stable Heddle <init@heddle> attribution instead of the user’s principal because the user’s principal may not yet be configured at init time (e.g. the user writes .heddle/config.toml after heddle init). Falling back to Unknown <unknown@example.com> would surface in heddle log as a state owned by no one. The genesis state is also filtered out of user-facing log output (see repository_history::is_synthetic_root).

pub fn clear_missing_blob(&self, hash: &ContentHash) -> Result<(), HeddleError>

pub fn missing_blobs(&self) -> Result<Vec<ContentHash>, HeddleError>

pub fn clear_all_missing_blobs(&self) -> Result<bool, HeddleError>

pub fn is_missing_blob(&self, hash: &ContentHash) -> Result<bool, HeddleError>

pub fn require_blob(&self, hash: &ContentHash) -> Result<Blob, HeddleError>

pub fn shallow(&self) -> RwLockReadGuard<'_, ShallowInfo>

impl Repository

pub fn put_redaction(&self, redaction: Redaction) -> Result<ContentHash, Error>

Append a redaction. Returns the redaction’s content-addressed id.

Idempotent: if a redaction with the same canonical bytes already exists on the blob, no second entry is written and the existing id is returned.

pub fn get_redactions_for_blob( &self, blob: &ContentHash, ) -> Result<RedactionsBlob, Error>

Load all redactions targeting blob. Returns an empty RedactionsBlob (not an error) when none exist — callers can treat the result uniformly.

pub fn list_all_redactions( &self, ) -> Result<Vec<(ContentHash, RedactionsBlob)>, Error>

Walk every redactions file in the repo. Used by heddle redact list and the GC’s “never collect a redaction” guard. Returns (blob_hash, blob) pairs so callers can correlate.

pub fn get_redaction( &self, redaction_id: &ContentHash, ) -> Result<Option<(ContentHash, Redaction)>, Error>

Look up a single redaction by its id. Returns Some((blob_hash, redaction)) if found; None if no redaction by that id exists.

Today this walks every redactions file — operators rarely have more than a handful of redactions in a repo, and the operation is interactive (heddle redact show). If listings become frequent enough to matter, a flat <heddle_dir>/redactions/index.bin can be added without changing the public signature.

pub fn purge_blob( &self, blob: &ContentHash, _purger: &Principal, ) -> Result<PurgeOutcome, Error>

Mark every redaction on blob as purged and physically remove the blob bytes from the local loose object store. The Redaction records stay in place; only the bytes are gone.

Refuses if no redaction exists on the blob — operators must redact before purge. This is the contract from the build brief: “Refuses unless a Redaction already exists on the blob.”

_purger is recorded by the caller in the oplog Purge entry; it’s accepted here so the helper can be extended (e.g. to embed the purger in a purge record) without changing the signature.

pub fn redaction_stub_for_blob( &self, blob: &ContentHash, ) -> Result<Option<String>, Error>

If blob has any active redaction, return the stub text the materialize path should write to disk in place of the blob content. Returns None when no redaction exists — callers should then proceed with normal materialization.

Picks the latest redaction (by redacted_at) to source the stub. Multiple redactions on the same blob converge to the most-recent message; the older ones remain in the audit trail.

pub fn reachable_states(&self) -> Result<Vec<ChangeId>, Error>

Enumerate every state reachable from any thread tip or marker by walking parent pointers transitively. Used by --all-states redaction propagation so a leaked secret can be scrubbed from every state in which its blob hash appears.

The walk is breadth-first and dedups by ChangeId, so a state reached from multiple tips appears once. Missing states (broken parent links) are skipped silently — redaction propagation is best-effort across the reachable graph, not a graph-integrity check.

pub fn paths_to_blob_in_state( &self, state: &ChangeId, target: &ContentHash, ) -> Result<Vec<String>, Error>

Find every path under state whose terminal blob hashes to target. Used by --all-states propagation: a leaked secret may live at different paths across history (renames, copies), so we propagate by blob hash, not by path.

Returns paths as forward-slash strings, lexicographically stable thanks to Tree entry ordering.

impl Repository

pub fn stash_manager(&self) -> StashManager

Trait Implementations

impl RepositoryLockExt for Repository

fn locker(&self) -> RepoLock