Implement Phase 4: Error Handling and Versioning

## Changes

### Versioning Support
- Added version constants:
  - PRTREE_VERSION_MAJOR = 1
  - PRTREE_VERSION_MINOR = 0
- Prepares for future backward compatibility in serialization

### Improved Error Messages
- insert(): Now includes expected vs actual shape information
  - Example: "Expected shape (4,) but got shape (3,) with ndim=1"
- insert(): Duplicate index error now includes index value
  - Example: "Index already exists in tree: 42"
- erase(): Not found error includes index and tree size
  - Example: "Cannot erase index 99: not found in tree (tree size: 50)"

### Benefits
- **Better debugging**: Users get actionable error messages
- **Future compatibility**: Version constants enable format evolution
- **User experience**: Clear, informative error messages

## Testing
- ✅ Compiles successfully with C++20
- ✅ No warnings or errors
- Error messages include contextual information

## Impact
- API unchanged (only error message improvements)
- Better user experience
- Foundation for future format versioning

Related: Phase 3 (exception safety)

Author: claude

PHASE4_ERROR_HANDLING.md

@@ -0,0 +1,147 @@
+# Phase 4: Error Handling and Versioning
+
+**Status**: 🔄 IN PROGRESS
+**Priority**: MEDIUM
+**Estimated Time**: 1-2 days
+
+---
+
+## Goals
+
+1. Add structured error handling instead of generic runtime_error
+2. Implement versioning for serialized data
+3. Add backward compatibility support
+4. Improve error messages
+
+---
+
+## Error Handling Strategy
+
+### Current Issues
+
+```cpp
+// Too generic - hard to handle programmatically
+throw std::runtime_error("Given index is already included.");
+throw std::runtime_error("Given index is not found.");
+throw std::runtime_error("invalid shape.");
+```
+
+### Proposed Solution
+
+Add specific exception types:
+
+```cpp
+class PRTreeException : public std::runtime_error {
+public:
+    enum class ErrorCode {
+        INDEX_NOT_FOUND,
+        INDEX_ALREADY_EXISTS,
+        INVALID_SHAPE,
+        INVALID_BOUNDS,
+        INVALID_DIMENSION,
+        FILE_NOT_FOUND,
+        SERIALIZATION_ERROR,
+        VERSION_MISMATCH
+    };
+
+    PRTreeException(ErrorCode code, const std::string& message)
+        : std::runtime_error(message), code_(code) {}
+
+    ErrorCode code() const noexcept { return code_; }
+
+private:
+    ErrorCode code_;
+};
+```
+
+---
+
+## Versioning Strategy
+
+### File Format Versioning
+
+Add version header to saved files:
+
+```cpp
+struct PRTreeHeader {
+    uint32_t magic = 0x50525452;  // "PRTR"
+    uint16_t major_version = 1;
+    uint16_t minor_version = 0;
+    uint32_t crc32 = 0;  // Optional integrity check
+};
+
+void save(const std::string& fname) const {
+    std::lock_guard<std::mutex> lock(tree_mutex_);
+    std::ofstream ofs(fname, std::ios::binary);
+
+    // Write header
+    PRTreeHeader header;
+    header.major_version = PRTREE_VERSION_MAJOR;
+    header.minor_version = PRTREE_VERSION_MINOR;
+    ofs.write(reinterpret_cast<const char*>(&header), sizeof(header));
+
+    // Write data
+    cereal::PortableBinaryOutputArchive o_archive(ofs);
+    o_archive(...);
+}
+```
+
+### Backward Compatibility
+
+```cpp
+void load(const std::string& fname) {
+    std::lock_guard<std::mutex> lock(tree_mutex_);
+    std::ifstream ifs(fname, std::ios::binary);
+
+    // Read header
+    PRTreeHeader header;
+    ifs.read(reinterpret_cast<char*>(&header), sizeof(header));
+
+    if (header.magic != 0x50525452) {
+        // Legacy format (no header)
+        ifs.seekg(0);
+        load_legacy(ifs);
+        return;
+    }
+
+    if (header.major_version > PRTREE_VERSION_MAJOR) {
+        throw PRTreeException(
+            ErrorCode::VERSION_MISMATCH,
+            "File version too new"
+        );
+    }
+
+    // Load based on version
+    load_v1(ifs, header);
+}
+```
+
+---
+
+## Implementation Plan
+
+1. ✅ Document error handling strategy
+2. Define PRTreeException class
+3. Replace runtime_error with specific exceptions
+4. Add version constants
+5. Implement versioned save/load
+6. Add backward compatibility for existing files
+7. Update error messages to be more descriptive
+
+---
+
+## Benefits
+
+- **Better error handling**: Users can catch specific exceptions
+- **Forward compatibility**: New versions can read old files
+- **Backward compatibility**: Detect and handle version mismatches
+- **Debugging**: Better error messages
+
+---
+
+## Success Criteria
+
+- ✅ All exceptions use specific error codes
+- ✅ Version header in all saved files
+- ✅ Can load files from previous versions
+- ✅ Clear error messages for all failure cases

cpp/prtree.h

@@ -46,6 +46,10 @@
 
 using Real = float;
 
+// Phase 4: Versioning for serialization
+constexpr uint16_t PRTREE_VERSION_MAJOR = 1;
+constexpr uint16_t PRTREE_VERSION_MINOR = 0;
+
 namespace py = pybind11;
 
 template <class T> using vec = std::vector<T>;
@@ -872,12 +876,17 @@ template <class T, int B = 6, int D = 2> class PRTree {
     const auto &buff_info_x = x.request();
     const auto &shape_x = buff_info_x.shape;
     const auto &ndim = buff_info_x.ndim;
+    // Phase 4: Improved error messages with context
     if (unlikely((shape_x[0] != 2 * D || ndim != 1))) {
-      throw std::runtime_error("invalid shape.");
+      throw std::runtime_error(
+          "Invalid shape for bounding box array. Expected shape (" +
+          std::to_string(2 * D) + ",) but got shape (" +
+          std::to_string(shape_x[0]) + ",) with ndim=" + std::to_string(ndim));
     }
     auto it = idx2bb.find(idx);
     if (unlikely(it != idx2bb.end())) {
-      throw std::runtime_error("Given index is already included.");
+      throw std::runtime_error(
+          "Index already exists in tree: " + std::to_string(idx));
     }
     {
       Real minima[D];
@@ -1391,7 +1400,10 @@ template <class T, int B = 6, int D = 2> class PRTree {
 
     auto it = idx2bb.find(idx);
     if (unlikely(it == idx2bb.end())) {
-      throw std::runtime_error("Given index is not found.");
+      // Phase 4: Improved error message with context
+      throw std::runtime_error(
+          "Cannot erase index " + std::to_string(idx) +
+          ": not found in tree (tree size: " + std::to_string(idx2bb.size()) + ")");
     }
     BB<D> target = it->second;