Struct ObjectStore 

pub struct ObjectStore { /* private fields */ }

Local content-addressed object store backed by the filesystem.

Implementations

impl ObjectStore

pub fn open(root: &Path) -> StoreResult<Self>

Open an existing repository rooted at root. Returns StoreError::NotAMkitRepository if <root>/.mkit/objects does not exist.

pub fn init(root: &Path) -> StoreResult<Self>

Initialise a fresh .mkit/ directory under root. Returns StoreError::AlreadyInitialized if .mkit/ already exists.

pub fn set_sync_policy(&mut self, policy: SyncPolicy)

Select the SyncPolicy that Self::batch hands out. The CLI wires the repo config key durability.objects here so deployments on filesystems where they prefer the strict per-object schedule can opt into it (SPEC-OBJECTS §10.1).

pub fn batch(&self) -> WriteBatch<'_>

Start a batched write with the store’s configured policy (default SyncPolicy::Batch): objects staged by the batch become durable and visible together at WriteBatch::commit, with O(1) full flushes per batch instead of per object.

pub fn batch_with_policy(&self, policy: SyncPolicy) -> WriteBatch<'_>

Start a batched write with an explicit SyncPolicy.

pub fn is_repo_root(root: &Path) -> bool

Returns true when root contains a .mkit/objects directory.

pub fn objects_root(&self) -> &Path

Absolute path to the objects/ directory.

pub fn contains(&self, h: &Hash) -> bool

Returns true when the object h is present in the store. Does not verify integrity — use Self::read for that.

pub fn write(&self, bytes: &[u8]) -> StoreResult<Hash>

Write bytes to the store, returning their BLAKE3 hash. Atomic: writes to a sibling temp file, fsyncs, then renames into place. Idempotent — re-writing the same bytes is a no-op (the temp file is unlinked on the early-return path).

Panics

Panics only if the internal hash-to-path mapping produces a path without a parent directory, which is impossible by construction.

pub fn bulk_writer(&self) -> BulkWriter<'_>

Begin a bulk-write session: each new object is written durable-before-visible (contents fsynced, then renamed), and BulkWriter::commit batches the directory fsyncs (rename durability) plus a content fsync of any re-used pre-existing objects once at the end, instead of fsyncing a dir per write.

Because content is durable before the rename, the session upholds the store’s global invariant even under concurrent readers: an object another process can contains()-dedup against is always backed by durable bytes.

Crash-safety contract (deliberately weaker than Self::write only for the rename/dirent half, for callers whose whole operation is idempotent — e.g. the deterministic git-import, which re-runs from a retained source mirror): after a crash BEFORE commit, a just-renamed object’s dirent may be lost (the shard dir is not yet fsynced), so objects may be missing — never torn, since contents were fsynced first. Existing paths are VERIFIED (byte compare) rather than blindly rewritten or blindly trusted: a matching file is left untouched (it may be durable and referenced by native history — replacing it with an unsynced inode would put it at risk), a torn one is healed by rewrite, and reads always BLAKE3-verify. Callers MUST gate bulk sessions behind their own crash marker and re-run on detection.

pub fn read(&self, h: &Hash) -> StoreResult<Vec<u8>>

Read raw bytes for h. Verifies that BLAKE3 of the on-disk bytes equals h and returns StoreError::HashMismatch on failure (the bytes are still discarded so callers cannot accidentally use corrupt data).

pub fn object_type(&self, h: &Hash) -> StoreResult<ObjectType>

The object’s type tag, from its 6-byte prologue — without reading or hash-verifying the body. Backs cheap shape checks (e.g. “is this staged hash blob-like?”) that previously paid a full read+BLAKE3 of every staged blob per status/commit; the real read path still integrity-verifies at use time.

Errors

StoreError::ObjectNotFound if absent; StoreError::Decode for a short file, bad magic/version, or unknown tag.

pub fn read_object(&self, h: &Hash) -> StoreResult<Object>

Convenience: read raw bytes and decode into a typed Object.

pub fn verify_object_type(&self, h: &Hash) -> StoreResult<ObjectType>

Hash-verifying variant of object_type: reads the whole object and confirms its content hashes to h before returning the declared type. This is the integrity guard for tree-publication paths (commit, merge, rebase, …) — object_type alone reads only the 6-byte prologue, so a staged object corrupted after add would otherwise be published into a durable tree and only fail at later read time. Use object_type on hot read-only paths (status/diff snapshots) where nothing durable is published.

pub fn iter_object_hashes(&self) -> StoreResult<Vec<Hash>>

Enumerate every object hash currently in the store by walking objects/<2-hex>/<62-hex>. Entries whose names are not the expected hex shape (stray files, atomic-write temp files, unknown dirs) are skipped — they are not objects. Used by gc to find prune candidates.

Errors

StoreError::Io if a directory cannot be read (gc must then fail closed rather than prune against a partial enumeration).

pub fn object_metadata(&self, h: &Hash) -> StoreResult<Metadata>

Filesystem metadata for object h (size + mtime), for gc’s grace-window check.

Errors

StoreError::ObjectNotFound if absent, else StoreError::Io.

pub fn remove_object(&self, h: &Hash) -> StoreResult<()>

Delete object h from the store. Idempotent: a missing object is not an error (it may have been pruned already).

Errors

StoreError::Io on a filesystem failure other than not-found.

Trait Implementations

impl Clone for ObjectStore

fn clone(&self) -> ObjectStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ObjectStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ObjectSink for ObjectStore

fn put(&self, bytes: &[u8]) -> StoreResult<Hash>

Store bytes as one object, returning its BLAKE3 hash.

fn put_parts(&self, parts: &[&[u8]]) -> StoreResult<Hash>

Store the concatenation of parts as one object without the caller having to materialise the concatenated buffer.

fn has(&self, h: &Hash) -> bool

True when the object is already present (or staged) in this sink.

impl ObjectSource for ObjectStore

fn read(&self, h: &Hash) -> StoreResult<Vec<u8>>

Read and integrity-verify the raw bytes of h.

fn read_object(&self, h: &Hash) -> StoreResult<Object>

Read and decode h into a typed Object.