fix(storage/p2): Document RocksDB read-your-writes limitation on upsert

Author: nekomoto911

crates/storage/db/src/implementation/rocksdb/cursor.rs

@@ -268,6 +268,18 @@ impl<K: TransactionKind, T: Table> DbCursorRO<T> for Cursor<K, T> {
 }
 
 impl<T: Table> DbCursorRW<T> for Cursor<RW, T> {
+    /// Insert or update a key-value pair in the database.
+    ///
+    /// # Read-Your-Writes Limitation (GRETH-014)
+    ///
+    /// Writes are buffered in a `WriteBatch` and are **not visible to subsequent
+    /// read operations** (`seek`, `current`, `get`) on the same cursor within the
+    /// same transaction. Reads always query the live RocksDB state, which does not
+    /// include uncommitted batch writes.
+    ///
+    /// Callers must not rely on read-your-writes semantics within a single cursor.
+    /// If you write a key and then immediately seek to it, you will observe the
+    /// **old value** (or "not found") until the batch is committed.
     fn upsert(&mut self, key: T::Key, value: &T::Value) -> Result<(), DatabaseError> {
         let cf_handle = get_cf_handle::<T>(&self.db)?;
         let encoded_key = key.encode();