Extract error handling to separate module

- Create src/error.rs with all error types and result types
- Move BPlusTreeError, result type aliases, and BTreeResultExt trait
- Update lib.rs to use error module with proper re-exports
- Remove problematic example file
- All tests pass (17 unit tests + 281 integration tests)

Phase 1 Step 1 of operation-based modularization complete.

Author: KentBeck

rust/MODULARIZATION_PLAN.md

@@ -0,0 +1,396 @@
+# BPlusTreeMap Modularization Plan
+
+## Overview
+
+The current `lib.rs` is 3,138 lines and contains multiple concerns mixed together. This plan breaks it into focused modules that group functionality that tends to change together and can be read end-to-end by humans.
+
+## Current Structure Analysis
+
+### Major Components Identified:
+
+1. **Error handling and type definitions** (~200 lines)
+2. **Core BPlusTreeMap struct and basic operations** (~800 lines)
+3. **LeafNode implementation** (~300 lines)
+4. **BranchNode implementation** (~300 lines)
+5. **Iterator implementations** (~400 lines)
+6. **Arena management helpers** (~200 lines)
+7. **Range query optimization** (~200 lines)
+8. **Tree validation and debugging** (~300 lines)
+9. **Tests** (~400 lines)
+
+## Proposed Module Structure
+
+### 1. `src/error.rs` - Error Handling & Types
+
+**Purpose**: All error types, result types, and error handling utilities
+**Size**: ~150 lines
+**Rationale**: Error handling changes together and is referenced throughout
+
+```rust
+// Contents:
+- BPlusTreeError enum and implementations
+- Result type aliases (BTreeResult, KeyResult, etc.)
+- BTreeResultExt trait
+- Error construction helpers
+```
+
+### 2. `src/types.rs` - Core Types & Constants
+
+**Purpose**: Fundamental types, constants, and small utility types
+**Size**: ~100 lines
+**Rationale**: Core types are stable and referenced everywhere
+
+```rust
+// Contents:
+- NodeId type and constants (NULL_NODE, ROOT_NODE)
+- NodeRef enum
+- SplitNodeData enum
+- InsertResult and RemoveResult enums
+- MIN_CAPACITY and other constants
+```
+
+### 3. `src/node/mod.rs` - Node Module Root
+
+**Purpose**: Module organization for node-related functionality
+**Size**: ~50 lines
+
+```rust
+// Contents:
+pub mod leaf;
+pub mod branch;
+pub mod operations;
+
+pub use leaf::LeafNode;
+pub use branch::BranchNode;
+```
+
+### 4. `src/node/leaf.rs` - Leaf Node Implementation
+
+**Purpose**: Complete LeafNode struct and all its operations
+**Size**: ~400 lines
+**Rationale**: Leaf operations change together (insert, delete, split, merge)
+
+```rust
+// Contents:
+- LeafNode struct definition
+- Construction methods
+- Get/insert/delete operations
+- Split and merge operations
+- Borrowing operations
+- Utility methods (is_full, is_underfull, etc.)
+```
+
+### 5. `src/node/branch.rs` - Branch Node Implementation
+
+**Purpose**: Complete BranchNode struct and all its operations
+**Size**: ~400 lines
+**Rationale**: Branch operations change together and mirror leaf operations
+
+```rust
+// Contents:
+- BranchNode struct definition
+- Construction methods
+- Child navigation operations
+- Insert/delete operations with child management
+- Split and merge operations
+- Rebalancing operations
+```
+
+### 6. `src/node/operations.rs` - Cross-Node Operations
+
+**Purpose**: Operations that work across both leaf and branch nodes
+**Size**: ~200 lines
+**Rationale**: Shared node operations and utilities
+
+```rust
+// Contents:
+- Node validation helpers
+- Cross-node borrowing operations
+- Node type conversion utilities
+- Common node operation patterns
+```
+
+### 7. `src/tree/mod.rs` - Tree Module Root
+
+**Purpose**: Module organization for tree-level functionality
+**Size**: ~50 lines
+
+```rust
+// Contents:
+pub mod core;
+pub mod operations;
+pub mod arena_helpers;
+
+pub use core::BPlusTreeMap;
+```
+
+### 8. `src/tree/core.rs` - Core Tree Structure
+
+**Purpose**: BPlusTreeMap struct definition and basic operations
+**Size**: ~300 lines
+**Rationale**: Core tree structure and fundamental operations
+
+```rust
+// Contents:
+- BPlusTreeMap struct definition
+- Constructor (new)
+- Basic get/insert/remove public API
+- Tree structure management (root handling)
+- Arena allocation wrappers
+```
+
+### 9. `src/tree/operations.rs` - Tree Operations Implementation
+
+**Purpose**: Complex tree operations and algorithms
+**Size**: ~600 lines
+**Rationale**: Tree algorithms change together and are complex
+
+```rust
+// Contents:
+- Recursive insert/delete/get implementations
+- Tree rebalancing logic
+- Root collapse/expansion
+- Tree traversal algorithms
+- Batch operations
+```
+
+### 10. `src/tree/arena_helpers.rs` - Arena Management
+
+**Purpose**: Arena allocation and management helpers
+**Size**: ~200 lines
+**Rationale**: Arena operations change together and are performance-critical
+
+```rust
+// Contents:
+- Arena allocation helpers
+- Node ID management
+- Arena statistics
+- Memory management utilities
+```
+
+### 11. `src/iterator/mod.rs` - Iterator Module Root
+
+**Purpose**: Module organization for all iterator types
+**Size**: ~50 lines
+
+```rust
+// Contents:
+pub mod item;
+pub mod range;
+pub mod key_value;
+
+pub use item::ItemIterator;
+pub use range::RangeIterator;
+// etc.
+```
+
+### 12. `src/iterator/item.rs` - Item Iterator
+
+**Purpose**: ItemIterator and FastItemIterator implementations
+**Size**: ~300 lines
+**Rationale**: Item iteration logic changes together
+
+```rust
+// Contents:
+- ItemIterator struct and implementation
+- FastItemIterator struct and implementation
+- Leaf traversal logic
+- Iterator state management
+```
+
+### 13. `src/iterator/range.rs` - Range Iterator
+
+**Purpose**: Range query iterator and optimization
+**Size**: ~300 lines
+**Rationale**: Range operations are complex and change together
+
+```rust
+// Contents:
+- RangeIterator struct and implementation
+- Range bounds resolution
+- Range start position finding
+- Range optimization helpers
+```
+
+### 14. `src/iterator/key_value.rs` - Key/Value Iterators
+
+**Purpose**: KeyIterator and ValueIterator implementations
+**Size**: ~100 lines
+**Rationale**: Simple wrapper iterators that change together
+
+```rust
+// Contents:
+- KeyIterator implementation
+- ValueIterator implementation
+- Iterator adapter utilities
+```
+
+### 15. `src/validation.rs` - Tree Validation & Debugging
+
+**Purpose**: Tree invariant checking and debugging utilities
+**Size**: ~400 lines
+**Rationale**: Validation logic changes together and is used for testing
+
+```rust
+// Contents:
+- Tree invariant checking
+- Detailed validation methods
+- Debug utilities
+- Test helpers
+- Integrity verification
+```
+
+### 16. `src/lib.rs` - Public API & Re-exports
+
+**Purpose**: Public API surface and module organization
+**Size**: ~200 lines
+**Rationale**: Clean public interface with comprehensive documentation
+
+```rust
+// Contents:
+- Module declarations
+- Public re-exports
+- Top-level documentation
+- Usage examples
+- Public API traits and implementations
+```
+
+## Module Dependencies
+
+```
+lib.rs
+├── error.rs (no dependencies)
+├── types.rs (depends on: error)
+├── node/
+│   ├── mod.rs
+│   ├── leaf.rs (depends on: error, types)
+│   ├── branch.rs (depends on: error, types, node/leaf)
+│   └── operations.rs (depends on: error, types, node/leaf, node/branch)
+├── tree/
+│   ├── mod.rs
+│   ├── core.rs (depends on: error, types, node/*)
+│   ├── operations.rs (depends on: error, types, node/*, tree/core)
+│   └── arena_helpers.rs (depends on: error, types, node/*)
+├── iterator/
+│   ├── mod.rs
+│   ├── item.rs (depends on: error, types, tree/core, node/leaf)
+│   ├── range.rs (depends on: error, types, tree/core, iterator/item)
+│   └── key_value.rs (depends on: iterator/item)
+└── validation.rs (depends on: all modules)
+```
+
+## Benefits of This Structure
+
+### 1. **Cohesion**: Related functionality grouped together
+
+- Node operations stay with node implementations
+- Iterator types are grouped but separated by complexity
+- Tree-level operations are separate from node-level operations
+
+### 2. **Human Readability**: Each module can be read end-to-end
+
+- `leaf.rs`: Complete leaf node story (~400 lines)
+- `branch.rs`: Complete branch node story (~400 lines)
+- `core.rs`: Core tree structure (~300 lines)
+- `operations.rs`: Tree algorithms (~600 lines)
+
+### 3. **Change Locality**: Things that change together are together
+
+- All leaf operations in one place
+- All iterator implementations grouped
+- All error handling centralized
+- All validation logic together
+
+### 4. **Clear Dependencies**: Well-defined module boundaries
+
+- Core types have no dependencies
+- Nodes depend only on types and errors
+- Tree depends on nodes
+- Iterators depend on tree
+- Validation depends on everything (for testing)
+
+### 5. **Testability**: Each module can be tested independently
+
+- Node operations can be unit tested
+- Tree operations can be integration tested
+- Iterators can be tested with mock trees
+- Validation provides comprehensive testing utilities
+
+## Migration Strategy
+
+### Phase 1: Extract Stable Components
+
+1. Create `error.rs` and `types.rs`
+2. Update imports throughout codebase
+3. Verify compilation
+
+### Phase 2: Extract Node Implementations
+
+1. Create `node/` module structure
+2. Move `LeafNode` to `node/leaf.rs`
+3. Move `BranchNode` to `node/branch.rs`
+4. Create `node/operations.rs` for shared functionality
+
+### Phase 3: Extract Tree Implementation
+
+1. Create `tree/` module structure
+2. Move core `BPlusTreeMap` to `tree/core.rs`
+3. Move complex algorithms to `tree/operations.rs`
+4. Move arena helpers to `tree/arena_helpers.rs`
+
+### Phase 4: Extract Iterators
+
+1. Create `iterator/` module structure
+2. Move each iterator type to its own file
+3. Organize by complexity and relationships
+
+### Phase 5: Extract Validation
+
+1. Move all validation logic to `validation.rs`
+2. Create comprehensive test utilities
+3. Update test imports
+
+### Phase 6: Clean Up Public API
+
+1. Organize `lib.rs` as clean public interface
+2. Add comprehensive module documentation
+3. Verify all public APIs are properly exposed
+
+## File Size Targets
+
+| Module                  | Target Lines | Current Estimate | Rationale                      |
+| ----------------------- | ------------ | ---------------- | ------------------------------ |
+| `error.rs`              | 150          | 200              | Error handling                 |
+| `types.rs`              | 100          | 100              | Core types                     |
+| `node/leaf.rs`          | 400          | 300              | Complete leaf implementation   |
+| `node/branch.rs`        | 400          | 300              | Complete branch implementation |
+| `node/operations.rs`    | 200          | 150              | Shared node operations         |
+| `tree/core.rs`          | 300          | 200              | Core tree structure            |
+| `tree/operations.rs`    | 600          | 800              | Tree algorithms                |
+| `tree/arena_helpers.rs` | 200          | 200              | Arena management               |
+| `iterator/item.rs`      | 300          | 250              | Item iteration                 |
+| `iterator/range.rs`     | 300          | 200              | Range iteration                |
+| `iterator/key_value.rs` | 100          | 50               | Simple iterators               |
+| `validation.rs`         | 400          | 300              | Validation and testing         |
+| `lib.rs`                | 200          | 150              | Public API                     |
+
+**Total**: ~3,650 lines (vs current 3,138 lines)
+
+The slight increase accounts for:
+
+- Module documentation
+- Clear separation boundaries
+- Some code duplication elimination
+- Better organization overhead
+
+## Success Criteria
+
+1. **No single module > 600 lines**
+2. **Each module readable end-to-end in 10-15 minutes**
+3. **Clear module responsibilities**
+4. **Minimal cross-module dependencies**
+5. **All tests pass after migration**
+6. **Public API unchanged**
+7. **Documentation improved**
+
+This modularization will make the codebase much more maintainable while preserving all existing functionality and improving code organization.