From 347a0e2408571a8bd89ceb23e965a379667e03b1 Mon Sep 17 00:00:00 2001
From: Ray Liu <raydatray@gmail.com>
Date: Mon, 7 Sep 2026 19:49:50 -0400
Subject: [PATCH] [1/1][docs] link mirrored layouts to Tsavorite sources

---
 src/address.rs            |  6 ++++++
 src/hash.rs               |  5 +++++
 src/index/bucket.rs       | 10 ++++++++++
 src/record/data_header.rs |  6 ++++++
 src/record/info.rs        |  6 ++++++
 5 files changed, 33 insertions(+)

diff --git a/src/address.rs b/src/address.rs
index 1519370..3c8c2bb 100644
--- a/src/address.rs
+++ b/src/address.rs
@@ -1,3 +1,9 @@
+//! Absolute address range and sentinels follow Tsavorite's `LogAddress`.
+//! Grossular does not yet represent the read-cache marker in bit 47.
+//!
+//! Reference: `Tsavorite/cs/src/core/Index/Common/LogAddress.cs`
+//! at Garnet commit `c9607605baa4`.
+
 use std::fmt;
 
 #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
diff --git a/src/hash.rs b/src/hash.rs
index e45af15..b43b943 100644
--- a/src/hash.rs
+++ b/src/hash.rs
@@ -1,3 +1,8 @@
+//! Port of Tsavorite's `Utility.HashBytes`.
+//!
+//! Reference: `Tsavorite/cs/src/core/Utilities/Utility.cs`
+//! at Garnet commit `c9607605baa4`.
+
 const HASH_MULTIPLIER: u64 = 40_343;
 
 pub(crate) fn hash(key: &[u8]) -> u64 {
diff --git a/src/index/bucket.rs b/src/index/bucket.rs
index 4b33a93..86beed9 100644
--- a/src/index/bucket.rs
+++ b/src/index/bucket.rs
@@ -1,3 +1,13 @@
+//! Tag positions and cache-line bucket shape mirror Tsavorite's hash index.
+//! Grossular currently reserves, but does not represent, the read-cache address bit.
+//!
+//! References:
+//! - `Tsavorite/cs/src/core/Index/Tsavorite/HashBucketEntry.cs`
+//! - `Tsavorite/cs/src/core/Index/Tsavorite/HashBucket.cs`
+//! - `Tsavorite/cs/src/core/Index/Tsavorite/Constants.cs`
+//!
+//! Garnet commit: `c9607605baa4`.
+
 use crate::address::Address;
 
 pub(super) const ENTRIES_PER_BUCKET: usize = 7;
diff --git a/src/record/data_header.rs b/src/record/data_header.rs
index 6a55f07..d51a8b3 100644
--- a/src/record/data_header.rs
+++ b/src/record/data_header.rs
@@ -1,3 +1,9 @@
+//! Uses the bit positions from Tsavorite's `RecordDataHeader`.
+//! Grossular currently implements only inline keys, inline values, and filler.
+//!
+//! Reference: `Tsavorite/cs/src/core/Allocator/RecordDataHeader.cs`
+//! at Garnet commit `c9607605baa4`.
+
 use super::{ALIGNMENT, HEADER_SIZE};
 
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
diff --git a/src/record/info.rs b/src/record/info.rs
index 0646401..ca36436 100644
--- a/src/record/info.rs
+++ b/src/record/info.rs
@@ -1,3 +1,9 @@
+//! Bit positions mirror Tsavorite's `RecordInfo`.
+//! Grossular currently uses previous address, tombstone, and valid state only.
+//!
+//! Reference: `Tsavorite/cs/src/core/Index/Common/RecordInfo.cs`
+//! at Garnet commit `c9607605baa4`.
+
 use crate::address::Address;
 
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]