Struct ObjectStore 

pub struct ObjectStore { /* private fields */ }

Local content-addressed object store backed by the filesystem.

Implementations

impl ObjectStore

pub fn open(layout: &RepoLayout) -> StoreResult<Self>

Open the existing repository described by layout. Returns StoreError::NotAMkitRepository if the layout’s objects/ directory does not exist. The object store is common-dir (shared) state — see crate::layout.

pub fn init(layout: &RepoLayout) -> StoreResult<Self>

Initialise a fresh common dir for the repository described by layout. Returns StoreError::AlreadyInitialized if the common dir 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 read_unverified(&self, h: &Hash) -> StoreResult<Vec<u8>>

Read raw bytes for h WITHOUT the BLAKE3 integrity check that Self::read performs — a StoreError::HashMismatch can therefore never come out of this path.

Policy — display-only paths ONLY (#625)

This exists for hot read-only rendering (diff/show/commit summaries formatting a diffstat or patch preview). It is the same “cheap read” tradeoff Self::object_type already makes for shape checks (see its doc and Self::verify_object_type, which is the verifying twin used by tree-publication paths) — extended here to the full object body.

NEVER use this for publication (commit/merge/rebase tree writes), dedup, fetch/apply, or any path whose output is consumed as data rather than displayed and discarded. mkit never feeds unverified bytes into state that mkit itself writes, or into output that mkit’s own tooling round-trips (e.g. format-patch piped into git am). On corruption, callers of read get a loud, typed error before anything downstream can act on bad bytes; callers of read_unverified get whatever a decoder makes of the corrupt bytes — a decode error, or in the worst case garbage in the rendered output — but never durable state, because display paths write nothing back to the store.

Prefer wrapping the source with DisplaySource at the render call site over calling this directly; that keeps the verify/ no-verify choice at the boundary instead of threading a flag through render code.

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_unverified(&self, h: &Hash) -> StoreResult<Vec<u8>>

Read h without integrity verification, for display-only rendering — see ObjectStore::read_unverified for the full policy (#625). Defaults to the fully-verifying Self::read, so every existing and third-party ObjectSource stays verifying unless it explicitly opts in by overriding this method.

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

Read and decode h into a typed Object.