From 529784960023471e73e1170a22c7f15f1b123cb8 Mon Sep 17 00:00:00 2001
From: Nelson Dominguez <ekkolon@proton.me>
Date: Fri, 27 Feb 2026 22:39:32 +0100
Subject: [PATCH] Add crate-level re-exports to minikv_core lib

---
 minikv-core/src/lib.rs | 48 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/minikv-core/src/lib.rs b/minikv-core/src/lib.rs
index ac90eed..bab190f 100644
--- a/minikv-core/src/lib.rs
+++ b/minikv-core/src/lib.rs
@@ -1,3 +1,42 @@
+//! `minikv_core`
+//!
+//! Core library for a deterministic, replicated object metadata layer.
+//!
+//! This crate provides the hashing, volume selection, record encoding,
+//! replication, rebuild, and rebalance logic required to maintain
+//! a consistent mapping between object keys and storage volumes.
+//!
+//! The system is designed around the following principles:
+//!
+//! - Deterministic key → path mapping (`key_to_path`)
+//! - Deterministic key → replica selection (`key_to_volume`)
+//! - Explicit, auditable record encoding (`Record`)
+//! - Metadata recovery from storage volumes (`rebuild_all`)
+//! - Convergence to ideal replica placement (`rebalance_all`)
+//!
+//! The crate does not implement an HTTP server. It focuses strictly on:
+//!
+//! - Metadata representation and storage abstraction (`MetadataStore`)
+//! - Volume interaction primitives (`remote_get`, `remote_put`, etc.)
+//! - Replica placement and reconciliation logic
+//!
+//! All replica selection and ordering is deterministic. Any change to
+//! hashing or volume selection logic will change placement and is therefore
+//! considered a breaking behavioural change.
+//!
+//! # High-Level Architecture
+//!
+//! - `hashing`   — Key-to-path and volume scoring primitives.
+//! - `volumes`   — Replica selection and rebalance detection.
+//! - `record`    — On-disk metadata encoding format.
+//! - `storage`   — Metadata storage abstraction.
+//! - `replication` — HTTP primitives for volume interaction.
+//! - `rebuild`   — Metadata reconstruction from volumes.
+//! - `rebalance` — Migration to ideal replica sets.
+//! - `locking`   — Per-key concurrency control.
+//!
+//! This crate is intended to be embedded in a higher-level service.
+
 pub mod error;
 pub mod hashing;
 pub mod locking;
@@ -10,3 +49,12 @@ pub mod storage;
 pub mod volumes;
 
 pub use error::Error;
+pub use hashing::{key_to_path, volume_score};
+pub use locking::{KeyGuard, KeyLock};
+pub use rebalance::{rebalance_all, rebalance_key};
+pub use rebuild::{AutoindexEntry, rebuild_all};
+pub use record::{Deleted, Record};
+pub use replication::{build_volume_client, remote_delete, remote_get, remote_head, remote_put};
+pub use state::AppState;
+pub use storage::{KeyValuePair, MetadataStore};
+pub use volumes::{key_to_volume, needs_rebalance};