Crate turbovault_git 

turbovault-git — git-native write substrate

Every vault mutation is a git commit built from plumbing — blobs written to the object DB, a tree assembled in an isolated/ephemeral index (never the shared .git/index), a commit-tree, and a compare-and-swap ref advance — then materialized into the working tree. Git history is the rollback/audit log; update-ref CAS is the cross-process serialization primitive.

Design: git-write-substrate-architecture.md. This crate replaces the legacy VaultManager write path (mutators, batch executor, path-lock registry, audit/snapshot rollback).

Layers (built bottom-up):

• VaultRepo — repo handle + detection + branch/HEAD resolution (GWS.1).
• TreeChange + build_tree/commit_tree — object-DB plumbing (GWS.2).
• cas_ref/commit_with_retry — ref compare-and-swap + optimistic rebuild-on-conflict (GWS.3).
• (next) per-file precondition, materialization, changesets (GWS.4+).

Structs

Changeset

A unit of change applied as a single commit.

ChangesetResult

Outcome of a committed changeset.

CommitLocks

A process-wide registry of per-worktree commit mutexes. Share one Arc across every VaultRepo so handles to the same worktree serialize.

FanoutInfo

Stateless handle to an open fan-out scratch worktree — everything needed to merge OR abandon the fan-out later, without holding a borrowed FanoutWorktree across the wait (e.g. between MCP tool calls).

FanoutWorktree

An open fan-out scratch worktree. Hold txns through worktree_repo(); finalize via commit_fanout (merge back) or abandon_fanout (discard).

MergeBackResult

Result of a successful merge-back.

Oid

Re-exported so substrate consumers (e.g. turbovault-tools) can talk about blob/commit oids without taking a direct git2 dep — preserves the substrate’s role as the only crate that knows about libgit2. Unique identity of any object (commit, tree, blob, tag).

OrphanFanout

One fan-out artifact (wip-<id> worktree + wip/<id> branch) found on disk by VaultRepo::list_orphan_fanouts. Whether a given entry is truly “orphan” — i.e. not tracked by a live caller — is a server-layer concern; the substrate just enumerates.

Precondition

A precondition on one path: the blob oid the caller expects to find in the base tree. expected == None asserts the path is absent (a create).

VaultRepo

A handle to the git repository backing a vault.

Enums

Error

Errors from the git write substrate.

MergeStrategy

How a fan-out merges back into main.

TreeChange

A single change to apply to a tree. Moves are modeled at the op-mapping layer (GWS.8) as Remove(old) + Upsert(new).

Type Aliases

CommitHook

Callback fired by VaultRepo::commit_changeset after a successful commit + materialize, inside the commit lock. Arguments are the commit’s first-parent oid (or None for the initial commit on an unborn branch) and the new commit oid.

Result

Result alias for the git write substrate.