feat: add continue_write() for concurrent worker cursor sharing

- Add continue_write() method to TrackerIterBuilder that creates WriteIter
  without resetting the write cursor (unlike write() which resets to 0)
- Make reset_write_cursor() public on PrefixTracker for manual cursor reset
- Add multi-threaded tests for continue_write() verifying no duplicate claims
- Update README.md with continue_write() documentation and examples
- Update INTEGRATION_GUIDE.md with Use Case 8 for concurrent claim workers
- Update API reference with new methods

Author: zvi-code

INTEGRATION_GUIDE.md

@@ -598,7 +598,59 @@ let removed = tracker.removed_count_since(&pre_workload);
 println!("Workload complete: +{} -{}", added, removed);
 ```
 
-### Use Case 8: Iterate Only Reference Set Members
+### Use Case 8: Concurrent Claim Workers with Shared Cursor
+
+**Scenario**: Multiple workers atomically claim unique IDs without coordination, using `continue_write()`.
+
+When workers independently create iterators via `write()`, each call resets the cursor to 0, causing duplicate claims. Use `continue_write()` to share cursor state across workers:
+
+```rust
+use std::sync::Arc;
+use std::thread;
+
+let tracker = Arc::new(tracker);
+let num_workers = 8;
+let claims_per_worker = 1000;
+
+// Reset cursor once before spawning workers
+tracker.reset_write_cursor();
+
+let handles: Vec<_> = (0..num_workers)
+    .map(|_| {
+        let t = tracker.clone();
+        thread::spawn(move || {
+            let mut claimed = Vec::with_capacity(claims_per_worker);
+            
+            // continue_write() does NOT reset cursor - shares state across workers
+            let mut iter = t.iter().continue_write();
+            
+            for _ in 0..claims_per_worker {
+                if let Some((id, _)) = iter.next() {
+                    // ID is atomically claimed and set in bitmap
+                    valkey.hset(format!("vec:{}", id), "embedding", random_vector());
+                    claimed.push(id);
+                }
+            }
+            claimed
+        })
+    })
+    .collect();
+
+// All claimed IDs are unique - no duplicates across workers
+let all_claimed: Vec<u64> = handles.into_iter()
+    .flat_map(|h| h.join().unwrap())
+    .collect();
+    
+println!("Claimed {} unique IDs", all_claimed.len());
+```
+
+**Key difference:**
+| Method | Cursor Behavior | Use Case |
+|--------|-----------------|----------|
+| `write()` | Resets cursor to 0 | Single iterator, fresh start |
+| `continue_write()` | Keeps current position | Multiple workers sharing cursor |
+
+### Use Case 9: Iterate Only Reference Set Members
 
 **Scenario**: Run queries only on vectors that exist in both tracker and reference set.
 
@@ -670,6 +722,9 @@ impl PrefixTracker {
     pub fn remove_range(&self, start: u64, end: u64) -> u64;
     pub fn clear(&self);
 
+    // === Cursor Control ===
+    pub fn reset_write_cursor(&self);             // Reset to 0 before spawning workers
+    
     // === Snapshot & Diff ===
     pub fn snapshot(&self) -> BitmapSnapshot;
     pub fn added_since(&self, snapshot: &BitmapSnapshot) -> Vec<u64>;
@@ -723,7 +778,13 @@ impl<'a> TrackerIterBuilder<'a> {
     // === Terminal Operations ===
     pub fn sequential(self) -> SequentialIter<'a>;
     pub fn random(self) -> RandomIter<'a>;
-    pub fn claim(self) -> ClaimIter<'a>;
+    
+    /// Build write iterator (resets cursor to 0).
+    pub fn write(self) -> WriteIter<'a>;
+    
+    /// Build write iterator (continues from current cursor position).
+    /// Use when multiple workers share cursor state.
+    pub fn continue_write(self) -> WriteIter<'a>;
 }
 ```
 

README.md

@@ -290,6 +290,49 @@ while let Some((id, _)) = writer.next() {
 // All IDs in `claimed` are now set and unique
 ```
 
+#### Concurrent Workers with `continue_write()`
+
+When multiple workers need to share cursor state across independently-created iterators,
+use `continue_write()` instead of `write()`:
+
+```rust
+use std::sync::Arc;
+use std::thread;
+
+let tracker = Arc::new(tracker);
+
+// Reset cursor once before spawning workers
+tracker.reset_write_cursor();
+
+let handles: Vec<_> = (0..8)
+    .map(|_| {
+        let t = tracker.clone();
+        thread::spawn(move || {
+            // continue_write() does NOT reset cursor - shares state across workers
+            let mut iter = t.iter().continue_write();
+            let mut claimed = Vec::new();
+            
+            for _ in 0..100 {
+                if let Some((id, _)) = iter.next() {
+                    claimed.push(id);
+                }
+            }
+            claimed
+        })
+    })
+    .collect();
+
+// All claimed IDs are unique - no duplicates across workers
+let all_claimed: Vec<u64> = handles.into_iter()
+    .flat_map(|h| h.join().unwrap())
+    .collect();
+```
+
+| Method | Cursor Behavior | Use Case |
+|--------|-----------------|----------|
+| `write()` | Resets cursor to 0 | Single iterator, fresh start |
+| `continue_write()` | Keeps current position | Multiple workers sharing cursor |
+
 ### Delete Iterator
 
 Exclusive iterator that clears IDs:

src/iterators.rs

@@ -296,6 +296,10 @@ impl<'a> TrackerIterBuilder<'a> {
     ///
     /// Multiple `WriteIter`s can run concurrently. Each call to `next()`
     /// atomically claims a unique ID.
+    ///
+    /// **Note:** This resets the write cursor to 0 before iteration begins.
+    /// For concurrent scenarios where multiple iterators should share cursor
+    /// position, use [`continue_write()`](Self::continue_write) instead.
     pub fn write(self) -> WriteIter<'a> {
         // Reset cursor at start of iteration
         self.tracker.reset_write_cursor();
@@ -310,6 +314,40 @@ impl<'a> TrackerIterBuilder<'a> {
         }
     }
 
+    /// Build a write iterator that continues from the current cursor position.
+    ///
+    /// Unlike [`write()`](Self::write), this does **not** reset the write cursor.
+    /// Use this when multiple workers need to share cursor state across
+    /// independently-created iterators.
+    ///
+    /// # Example: Concurrent workers
+    ///
+    /// ```
+    /// use keyspace_tracker::PrefixTracker;
+    ///
+    /// let tracker = PrefixTracker::new(100);
+    /// tracker.reset_write_cursor(); // Reset once at the start
+    ///
+    /// // Multiple workers can create iterators without resetting cursor
+    /// let mut iter1 = tracker.iter().continue_write();
+    /// let mut iter2 = tracker.iter().continue_write();
+    ///
+    /// // Each claim_next_id() atomically advances the shared cursor
+    /// let id1 = iter1.claim_next_id();
+    /// let id2 = iter2.claim_next_id();
+    /// assert_ne!(id1, id2); // Different IDs guaranteed
+    /// ```
+    pub fn continue_write(self) -> WriteIter<'a> {
+        let max_id = self.range.id_max.min(self.tracker.effective_max_id());
+
+        WriteIter {
+            tracker: self.tracker,
+            range: self.range,
+            filter: self.filter,
+            max_id,
+        }
+    }
+
     /// Build an exclusive delete iterator.
     ///
     /// Only one `DeleteIter` can exist per tracker at a time.
@@ -1710,4 +1748,87 @@ mod tests {
         let total: u64 = handles.into_iter().map(|h: thread::JoinHandle<u64>| h.join().unwrap()).sum();
         assert_eq!(total, 10000);
     }
+
+    #[test]
+    fn test_continue_write_multithreaded() {
+        use std::collections::HashSet;
+        use std::sync::Arc;
+        use std::thread;
+
+        let tracker = Arc::new(PrefixTracker::new(
+            TrackerConfig::simple("vec:").with_max_id(10000),
+        ));
+
+        // Reset cursor once before spawning workers
+        tracker.reset_write_cursor();
+
+        let num_workers = 8;
+        let claims_per_worker = 100;
+
+        let handles: Vec<_> = (0..num_workers)
+            .map(|_| {
+                let t = tracker.clone();
+                thread::spawn(move || {
+                    let mut claimed = Vec::with_capacity(claims_per_worker);
+                    let mut iter = t.iter().continue_write();
+
+                    for _ in 0..claims_per_worker {
+                        if let Some((id, _sub_id)) = iter.next() {
+                            claimed.push(id);
+                        }
+                    }
+                    claimed
+                })
+            })
+            .collect();
+
+        // Collect all claimed IDs
+        let all_claimed: Vec<u64> = handles
+            .into_iter()
+            .flat_map(|h| h.join().unwrap())
+            .collect();
+
+        // Verify no duplicates - each ID should be claimed exactly once
+        let unique: HashSet<_> = all_claimed.iter().collect();
+        assert_eq!(
+            unique.len(),
+            all_claimed.len(),
+            "Duplicate IDs claimed! Got {} claims but only {} unique",
+            all_claimed.len(),
+            unique.len()
+        );
+
+        // Should have claimed exactly num_workers * claims_per_worker IDs
+        assert_eq!(all_claimed.len(), num_workers * claims_per_worker);
+    }
+
+    #[test]
+    fn test_continue_write_vs_write_cursor_behavior() {
+        let tracker = PrefixTracker::new(TrackerConfig::simple("vec:").with_max_id(100));
+
+        // First write() resets cursor to 0
+        let mut iter1 = tracker.iter().write();
+        let (id1, _) = iter1.next().unwrap();
+        assert_eq!(id1, 0);
+
+        // Second write() also resets cursor to 0 - gets same ID!
+        let mut iter2 = tracker.iter().write();
+        let (id2, _) = iter2.next().unwrap();
+        assert_eq!(id2, 0, "write() should reset cursor");
+
+        // Now use continue_write() - manually reset first
+        tracker.reset_write_cursor();
+        let mut iter3 = tracker.iter().continue_write();
+        let (id3, _) = iter3.next().unwrap();
+        assert_eq!(id3, 0);
+
+        // continue_write() does NOT reset - continues from cursor
+        let mut iter4 = tracker.iter().continue_write();
+        let (id4, _) = iter4.next().unwrap();
+        assert_eq!(id4, 1, "continue_write() should NOT reset cursor");
+
+        let mut iter5 = tracker.iter().continue_write();
+        let (id5, _) = iter5.next().unwrap();
+        assert_eq!(id5, 2, "continue_write() should continue advancing");
+    }
 }

src/tracker.rs

@@ -564,8 +564,22 @@ impl PrefixTracker {
         &self.write_cursor
     }
 
-    /// Reset write cursor (call before starting iteration).
-    pub(crate) fn reset_write_cursor(&self) {
+    /// Reset the write cursor to position 0.
+    ///
+    /// Call this once before spawning concurrent workers that use
+    /// [`continue_write()`](crate::iterators::TrackerIterBuilder::continue_write).
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use keyspace_tracker::PrefixTracker;
+    ///
+    /// let tracker = PrefixTracker::new(100);
+    /// tracker.reset_write_cursor(); // Reset once
+    ///
+    /// // Spawn workers that call tracker.iter().continue_write()
+    /// ```
+    pub fn reset_write_cursor(&self) {
         self.write_cursor.store(0, Ordering::Release);
     }