feat: add PrivateDocumentStore element type, gated to GROVE_V4

Cargo.toml

@@ -17,6 +17,7 @@ members = [
     "grovedb-bulk-append-tree",
     "grovedb-dense-fixed-sized-merkle-tree",
     "grovedb-query",
+    "grovedb-private-document-store",
 ]
 
 [workspace.dependencies]

grovedb-element/src/element/constructor.rs

@@ -500,6 +500,57 @@ impl Element {
         Element::DenseAppendOnlyFixedSizeTree(count, height, flags)
     }
 
+    /// Set element to an empty private document store.
+    ///
+    /// Returns `InvalidInput` unless `entry_size >= 1` and `chunk_power` is
+    /// in `1..=16` (the underlying `BulkAppendTree` dense-buffer height
+    /// range). Unlike `empty_commitment_tree` / `empty_bulk_append_tree`,
+    /// the constraints are enforced eagerly here: the configuration is
+    /// committed into the state root, so an unusable config must never be
+    /// constructible.
+    pub fn empty_private_document_store(
+        entry_size: u32,
+        chunk_power: u8,
+    ) -> Result<Self, ElementError> {
+        Self::empty_private_document_store_with_flags(entry_size, chunk_power, None)
+    }
+
+    /// Set element to an empty private document store with flags.
+    ///
+    /// Same validation as [`Element::empty_private_document_store`].
+    pub fn empty_private_document_store_with_flags(
+        entry_size: u32,
+        chunk_power: u8,
+        flags: Option<ElementFlags>,
+    ) -> Result<Self, ElementError> {
+        if entry_size == 0 {
+            return Err(ElementError::InvalidInput(
+                "private document store entry_size must be non-zero",
+            ));
+        }
+        if !(1..=16).contains(&chunk_power) {
+            return Err(ElementError::InvalidInput(
+                "private document store chunk_power must be between 1 and 16",
+            ));
+        }
+        Ok(Element::PrivateDocumentStore(
+            0,
+            entry_size,
+            chunk_power,
+            flags,
+        ))
+    }
+
+    /// Set element to a private document store with all fields
+    pub fn new_private_document_store(
+        total_count: u64,
+        entry_size: u32,
+        chunk_power: u8,
+        flags: Option<ElementFlags>,
+    ) -> Self {
+        Element::PrivateDocumentStore(total_count, entry_size, chunk_power, flags)
+    }
+
     /// Set element to an empty provable sum-indexed tree without flags.
     pub fn empty_provable_sum_indexed_tree() -> Self {
         Element::ProvableSumIndexedTree(None, None, 0, None)

grovedb-element/src/element/helpers.rs

@@ -358,6 +358,7 @@ impl Element {
                 | Element::ProvableSumIndexedTree(..)
                 | Element::ProvableCountIndexedTree(..)
                 | Element::ProvableCountProvableSumIndexedTree(..)
+                | Element::PrivateDocumentStore(..)
         )
     }
 
@@ -414,6 +415,12 @@ impl Element {
         matches!(self.underlying(), Element::DenseAppendOnlyFixedSizeTree(..))
     }
 
+    /// Check if the element is a private document store. Looks through
+    /// `NonCounted`.
+    pub fn is_private_document_store(&self) -> bool {
+        matches!(self.underlying(), Element::PrivateDocumentStore(..))
+    }
+
     /// Check if the element is a tree type that stores data in the data
     /// namespace as non-Merk entries.  These tree types have an always-empty
     /// Merk (root_key = None) and never contain child subtrees. The data
@@ -430,6 +437,7 @@ impl Element {
                 | Element::MmrTree(..)
                 | Element::BulkAppendTree(..)
                 | Element::DenseAppendOnlyFixedSizeTree(..)
+                | Element::PrivateDocumentStore(..)
         )
     }
 
@@ -443,6 +451,7 @@ impl Element {
             Element::MmrTree(mmr_size, _) => Some(*mmr_size),
             Element::BulkAppendTree(count, ..) => Some(*count),
             Element::DenseAppendOnlyFixedSizeTree(count, ..) => Some(*count as u64),
+            Element::PrivateDocumentStore(count, ..) => Some(*count),
             _ => None,
         }
     }
@@ -470,6 +479,7 @@ impl Element {
                 | Element::MmrTree(..)
                 | Element::BulkAppendTree(..)
                 | Element::DenseAppendOnlyFixedSizeTree(..)
+                | Element::PrivateDocumentStore(..)
                 | Element::ProvableSumIndexedTree(Some(_), ..)
                 | Element::ProvableSumIndexedTree(_, Some(_), ..)
                 | Element::ProvableCountIndexedTree(Some(_), ..)
@@ -663,6 +673,7 @@ impl Element {
             | Element::MmrTree(.., flags)
             | Element::BulkAppendTree(.., flags)
             | Element::DenseAppendOnlyFixedSizeTree(.., flags)
+            | Element::PrivateDocumentStore(.., flags)
             | Element::ProvableSumIndexedTree(.., flags)
             | Element::ProvableCountIndexedTree(.., flags)
             | Element::ReferenceWithSumItem(.., flags) => flags,
@@ -695,6 +706,7 @@ impl Element {
             | Element::MmrTree(.., flags)
             | Element::BulkAppendTree(.., flags)
             | Element::DenseAppendOnlyFixedSizeTree(.., flags)
+            | Element::PrivateDocumentStore(.., flags)
             | Element::ProvableSumIndexedTree(.., flags)
             | Element::ProvableCountIndexedTree(.., flags)
             | Element::ReferenceWithSumItem(.., flags) => flags,
@@ -727,6 +739,7 @@ impl Element {
             | Element::MmrTree(.., flags)
             | Element::BulkAppendTree(.., flags)
             | Element::DenseAppendOnlyFixedSizeTree(.., flags)
+            | Element::PrivateDocumentStore(.., flags)
             | Element::ProvableSumIndexedTree(.., flags)
             | Element::ProvableCountIndexedTree(.., flags)
             | Element::ReferenceWithSumItem(.., flags) => flags,
@@ -758,6 +771,7 @@ impl Element {
             | Element::MmrTree(.., flags)
             | Element::BulkAppendTree(.., flags)
             | Element::DenseAppendOnlyFixedSizeTree(.., flags)
+            | Element::PrivateDocumentStore(.., flags)
             | Element::ProvableSumIndexedTree(.., flags)
             | Element::ProvableCountIndexedTree(.., flags)
             | Element::ReferenceWithSumItem(.., flags) => *flags = new_flags,
@@ -1320,6 +1334,12 @@ mod flag_accessor_tests {
         check_accessors_round_trip(e);
     }
 
+    #[test]
+    fn private_document_store_flag_accessors() {
+        let e = Element::PrivateDocumentStore(0, 64, 4, flags());
+        check_accessors_round_trip(e);
+    }
+
     #[test]
     fn dense_append_only_tree_flag_accessors() {
         let e = Element::DenseAppendOnlyFixedSizeTree(0, 0, flags());

grovedb-element/src/element/mod.rs

@@ -316,6 +316,31 @@ pub enum Element {
         Vec<(u8, Option<Vec<u8>>)>,
         Option<ElementFlags>,
     ),
+    /// Private document store: an append-only store of fixed-size opaque
+    /// entries, a thin wrapper over a `BulkAppendTree` (the same
+    /// relationship `CommitmentTree` has to it, minus the Sinsemilla
+    /// frontier). Entries are write-once — there is no per-entry delete or
+    /// update; immutability is enforced by the type.
+    ///
+    /// Fields: `(total_count, entry_size, chunk_power, flags)`
+    /// - `total_count`: Number of entries appended so far.
+    /// - `entry_size`: Committed byte length of every entry; appends of any
+    ///   other length are rejected.
+    /// - `chunk_power`: Log2 of the chunk size (actual size = `1 <<
+    ///   chunk_power`).
+    /// - `flags`: Optional per-element metadata.
+    ///
+    /// The state root
+    /// (`blake3("pds_state" || config_hash || bulk_state_root)`, where
+    /// `config_hash` commits to `{entry_size, chunk_power}`) flows through
+    /// the Merk child hash mechanism (`insert_subtree`'s
+    /// `subtree_root_hash` parameter), so the declared configuration is
+    /// consensus-visible and a proof can never be reinterpreted under a
+    /// different config.
+    ///
+    /// Variant order in this enum determines bincode's variant-index
+    /// encoding on disk. This variant gets index 24.
+    PrivateDocumentStore(u64, u32, u8, Option<ElementFlags>),
 }
 
 pub fn hex_to_ascii(hex_value: &[u8]) -> String {
@@ -583,6 +608,18 @@ impl fmt::Display for Element {
                         .map_or(String::new(), |f| format!(", flags: {:?}", f))
                 )
             }
+            Element::PrivateDocumentStore(total_count, entry_size, chunk_power, flags) => {
+                write!(
+                    f,
+                    "PrivateDocumentStore(count: {}, entry_size: {}, chunk_power: {}{})",
+                    total_count,
+                    entry_size,
+                    chunk_power,
+                    flags
+                        .as_ref()
+                        .map_or(String::new(), |f| format!(", flags: {:?}", f))
+                )
+            }
             Element::NotSummed(inner) => {
                 write!(f, "NotSummed({})", inner)
             }
@@ -660,6 +697,7 @@ impl Element {
             Element::ProvableCountProvableSumIndexedTree(..) => {
                 ElementType::ProvableCountProvableSumIndexedTree
             }
+            Element::PrivateDocumentStore(..) => ElementType::PrivateDocumentStore,
             Element::NonCounted(inner) => match inner.element_type() {
                 ElementType::Item => ElementType::NonCountedItem,
                 ElementType::Reference => ElementType::NonCountedReference,
@@ -692,6 +730,7 @@ impl Element {
                 ElementType::ProvableCountProvableSumIndexedTree => {
                     ElementType::NonCountedProvableCountProvableSumIndexedTree
                 }
+                ElementType::PrivateDocumentStore => ElementType::NonCountedPrivateDocumentStore,
                 // Inner is always a base type — nested wrappers are
                 // forbidden at construction and (de)serialization.
                 already_non_counted => already_non_counted,
@@ -885,6 +924,7 @@ mod serde_impl {
             Vec<(u8, Option<Vec<u8>>)>,
             Option<ElementFlags>,
         ),
+        PrivateDocumentStore(u64, u32, u8, Option<ElementFlags>),
     }
 
     impl From<ElementShadow> for Element {
@@ -934,6 +974,9 @@ mod serde_impl {
                 ElementShadow::ProvableCountProvableSumIndexedTree(pk, c, s, axes, f) => {
                     Element::ProvableCountProvableSumIndexedTree(pk, c, s, axes, f)
                 }
+                ElementShadow::PrivateDocumentStore(c, e, p, f) => {
+                    Element::PrivateDocumentStore(c, e, p, f)
+                }
             }
         }
     }
@@ -983,6 +1026,7 @@ mod serde_impl {
             let cases = vec![
                 Element::Item(b"abc".to_vec(), None),
                 Element::SumTree(Some(b"r".to_vec()), 42, None),
+                Element::PrivateDocumentStore(9, 64, 4, Some(vec![1])),
                 Element::new_non_counted(Element::Item(b"x".to_vec(), None)).unwrap(),
                 Element::new_not_summed(Element::SumTree(None, 100, None)).unwrap(),
                 Element::new_not_counted_or_summed(Element::CountSumTree(None, 3, 100, None))

grovedb-element/src/element/visualize.rs

@@ -176,6 +176,21 @@ impl Visualize for Element {
                     drawer = f.visualize(drawer)?;
                 }
             }
+            Element::PrivateDocumentStore(total_count, entry_size, chunk_power, flags) => {
+                drawer.write(
+                    format!(
+                        "private_document_store: count: {total_count} entry_size: {entry_size} \
+                         chunk_power: {chunk_power}",
+                    )
+                    .as_bytes(),
+                )?;
+
+                if let Some(f) = flags
+                    && !f.is_empty()
+                {
+                    drawer = f.visualize(drawer)?;
+                }
+            }
             Element::NonCounted(inner) => {
                 drawer.write(b"non_counted(")?;
                 drawer = inner.visualize(drawer)?;