Release v3.0: Complete rewrite with benchmarks and paper updates

Major Changes:
- Migrated to C++23 for std::expected and concepts
- Implemented maph v3 with composable design (hashers, storage, table)
- Archived v1/v2 implementations to archive/ directory
- Fixed critical hash truncation bug (32-bit storage vs 64-bit comparison)

New Features:
- Comprehensive benchmark suite (latency, throughput, comparison)
- Memory-mapped storage with lock-free reads
- Hybrid hasher (perfect hash + FNV-1a with linear probing)
- Fixed 512-byte slots with cache-line alignment

Benchmarks (1M keys, 200-byte values):
- Median GET latency: 351ns (sub-microsecond)
- Throughput: 2.69M ops/sec single-threaded, 17.24M with 8 threads
- Near-linear scaling: 4.42× speedup on 4 cores (110% efficiency)
- 1.88× faster bulk inserts vs std::unordered_map

Paper Updates:
- Updated Tables I-V with real measured data
- Removed fictional benchmarks (SIMD, YCSB, case studies)
- Added honest comparison showing trade-offs vs std::unordered_map
- Fixed architecture description (removed incorrect 80/20 claim)
- Added complete experimental methodology section

Documentation:
- BENCHMARK_RESULTS.md with comprehensive analysis
- PAPER_CHANGES_SUMMARY.md tracking all revisions
- REFACTORING_SUMMARY.md documenting code cleanup

Build System:
- Updated CMakeLists.txt for C++23 and v3 only
- Added benchmark and test targets
- OpenMP support for future optimizations

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: queelius

CMakeLists.txt

@@ -1,8 +1,8 @@
 cmake_minimum_required(VERSION 3.14)
 project(maph VERSION 2.0.0 LANGUAGES CXX)
 
-# C++17 required
-set(CMAKE_CXX_STANDARD 17)
+# C++23 required for v3 (concepts, std::expected)
+set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 
@@ -22,45 +22,49 @@ else()
     message(STATUS "OpenMP not found - parallel optimizations will be disabled")
 endif()
 
-# Header-only library
+# Header-only library (v3)
 add_library(maph INTERFACE)
-target_include_directories(maph INTERFACE 
+target_include_directories(maph INTERFACE
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
     $<INSTALL_INTERFACE:include>
 )
+target_compile_features(maph INTERFACE cxx_std_23)  # v3 requires C++23 for std::expected
 
-# CLI executable
-add_executable(maph_cli src/maph_cli.cpp)
-target_link_libraries(maph_cli PRIVATE maph)
-target_include_directories(maph_cli PRIVATE include)
-set_target_properties(maph_cli PROPERTIES OUTPUT_NAME maph)
+# CLI executable (TODO: update to v3)
+# add_executable(maph_cli src/maph_cli.cpp)
+# target_link_libraries(maph_cli PRIVATE maph)
+# target_include_directories(maph_cli PRIVATE include)
+# set_target_properties(maph_cli PROPERTIES OUTPUT_NAME maph)
 
 # Installation
-install(TARGETS maph_cli DESTINATION bin)
-install(FILES include/maph.hpp DESTINATION include)
+# install(TARGETS maph_cli DESTINATION bin)
+install(DIRECTORY include/maph/v3 DESTINATION include/maph)
 
-# Tests
+# Tests (v3)
 option(BUILD_TESTS "Build tests" OFF)
 if(BUILD_TESTS)
     enable_testing()
     add_subdirectory(tests)
-    
-    # Benchmark executable
-    add_executable(bench_maph tests/bench_maph.cpp)
-    target_link_libraries(bench_maph PRIVATE maph pthread)
-    target_include_directories(bench_maph PRIVATE include)
+endif()
+
+# Benchmarks (v3)
+option(BUILD_BENCHMARKS "Build benchmarks" OFF)
+if(BUILD_BENCHMARKS)
+    add_subdirectory(benchmarks)
+endif()
 
-    # Link OpenMP if found
-    if(OpenMP_CXX_FOUND)
-        target_link_libraries(bench_maph PRIVATE OpenMP::OpenMP_CXX)
-    endif()
+# Examples (v3)
+option(BUILD_EXAMPLES "Build examples" OFF)
+if(BUILD_EXAMPLES)
+    # V3 demo
+    add_executable(v3_demo examples/v3_demo.cpp)
+    target_link_libraries(v3_demo PRIVATE maph)
+    target_include_directories(v3_demo PRIVATE include)
 
-    # Enable AVX2 if available
-    include(CheckCXXCompilerFlag)
-    CHECK_CXX_COMPILER_FLAG("-mavx2" COMPILER_SUPPORTS_AVX2)
-    if(COMPILER_SUPPORTS_AVX2)
-        target_compile_options(bench_maph PRIVATE -mavx2)
-    endif()
+    # V3 simple test
+    add_executable(v3_simple_test examples/v3_simple_test.cpp)
+    target_link_libraries(v3_simple_test PRIVATE maph)
+    target_include_directories(v3_simple_test PRIVATE include)
 endif()
 
 # Integrations

archive/README.md

@@ -0,0 +1,29 @@
+# Archived Files
+
+This directory contains obsolete implementations from v1 and v2 of maph.
+
+## What's Here
+
+- **include/**: Old header files (v1, v2, and intermediate versions)
+- **src/**: Old source files (v2 CLI, old perfect hash impl)
+- **tests/**: Old test files for previous versions
+- **integrations/**: Old integration code (v2 REST API)
+
+## Current Implementation
+
+The current implementation is **v3**, located at:
+- `include/maph/v3/` - All v3 headers
+- `tests/v3/` - All v3 tests  
+- `examples/v3_*.cpp` - V3 examples
+
+## Why Archived
+
+These files were replaced by the cleaner, more composable v3 architecture which:
+- Uses modern C++17 features (concepts, std::expected)
+- Has better separation of concerns
+- Provides composable components (storage, hashers, tables)
+- Supports both perfect and standard hashing elegantly
+
+## Restoration
+
+If you need any of these files, they're preserved here and in git history.