initial v2

.github/workflows/quality.yml

@@ -7,8 +7,11 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with: {python-version: "3.12"}
-      - run: pip install -e '.[dev,cli]'
-      - run: ruff check --select E9,F63,F7,F82 vecstream tests benchmarks/ann_benchmark.py
-      - run: mypy --follow-imports=skip vecstream/hnsw_index.py vecstream/vector_store.py vecstream/binary_store.py
+      - run: pip install numpy hypothesis mypy pytest ruff
+      - run: ruff check --select E,F,I,B vecstream tests benchmarks/ann_benchmark.py
+      - run: ruff format --check vecstream tests benchmarks/ann_benchmark.py
+      - run: mypy vecstream
       - run: pytest -q
-      - run: python benchmarks/ann_benchmark.py --vectors 500 --queries 10 --dim 32 --ef-search 10 20
+      - run: python -m benchmarks.ann_benchmark --experiment frontier --vectors 300 --queries 10 --dim 32 --ef-search 10 20
+      - run: python -m benchmarks.ann_benchmark --experiment insertion-order --vectors 300 --queries 10 --dim 32 --ef-search 20 --order-seeds 1 2
+      - run: python -m benchmarks.ann_benchmark --experiment deletion --vectors 300 --queries 10 --dim 32 --ef-search 20

.gitignore

@@ -1,63 +1,49 @@
-# Python
+# Python bytecode and native extensions
 __pycache__/
 *.py[cod]
-*$py.class
 *.so
+
+# Build output
 .Python
 build/
-develop-eggs/
 dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
 
-# Virtual Environment
-venv/
+# Virtual environments and local configuration
 .venv/
+venv/
 env/
 ENV/
 .env
 
-# IDE
-.idea/
-.vscode/
-*.swp
-*.swo
-.DS_Store
-
-# Testing
+# Test, type-check, and lint caches
 .coverage
 htmlcov/
+.hypothesis/
+.mypy_cache/
 .pytest_cache/
+.ruff_cache/
 .tox/
 
-# Project specific
-*.vec
-*.idx
+# Editors and operating systems
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# VecStream local stores
 *.db
-benchmarks/results/
-!benchmarks/results/
-benchmarks/results/*
-!benchmarks/results/smoke-1000x64-seed42.json
+*.idx
+*.vec
+.vecstream/
+vector_db/
+test_env/
+test_vectors/
 tests/data/
-.vecstream/ 
-.vscode
-vector_db
-test_vectors
-test_env
-.vscode
-vecstream/__pycache__/
 
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
+# Benchmark runs are generated by default. These three measured Stage Two
+# experiments are intentional, reviewable repository artifacts.
+benchmarks/results/*
+!benchmarks/results/frontier-1000x64.json
+!benchmarks/results/insertion-order-1000x64.json
+!benchmarks/results/deletion-1000x64.json

CHANGELOG.md

@@ -2,19 +2,21 @@
 
 All notable changes to VecStream will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
 ### Added
-- Nightly maintenance (#27)
+- Exact-search recall oracle and three reproducible ANN experiments.
+- Comprehensive HNSW invariant validation and property-based mutation tests.
+- Versioned, crash-safe vector checkpoints with explicit corruption errors.
 
-### Fixed
-- fix: create PR for changelog updates (#26)
+### Changed
+- Correct HNSW level generation, diversity selection, reciprocal pruning, and stable float32 normalization.
+- Reduced the supported architecture to `Collection`, `BinaryVectorStore`, and `HNSWIndex`.
 
-### Fixed
-- Fixed metadata filtering in HNSW search by increasing the number of candidates from 100 to 1000 to ensure enough matches are found after filtering
+### Removed
+- Legacy manager/query layers, JSON store, client/server, CLI, embedding dependencies, examples, and obsolete benchmark artifacts.
 
 ## [0.3.4] - 2024-03-30
 

README.md

@@ -15,7 +15,7 @@ The project is deliberately single-machine and small enough that the important a
 - generation-based local checkpoints without pickle
 - recovery to the previous complete checkpoint and explicit corruption errors
 - property tests for randomized graph mutations
-- a reproducible `ef_search` recall/latency benchmark
+- reproducible frontier, insertion-order, and deletion experiments
 
 ## Architecture
 
@@ -50,17 +50,21 @@ This is a committed smoke measurement, not a large-scale performance claim: 1,00
 
 | ef_search | recall@10 | p50 ms | p99 ms | QPS |
 |---:|---:|---:|---:|---:|
-| 10 | 0.758 | 0.538 | 1.092 | 1,731 |
-| 20 | 0.910 | 0.826 | 1.552 | 1,136 |
-| 40 | 0.988 | 1.241 | 2.298 | 753 |
-| 80 | 0.996 | 1.652 | 2.808 | 567 |
-| 160 | 1.000 | 1.907 | 2.694 | 505 |
+| 10 | 0.768 | 0.522 | 0.666 | 1,902 |
+| 20 | 0.908 | 0.746 | 0.857 | 1,327 |
+| 40 | 0.990 | 1.106 | 1.189 | 903 |
+| 80 | 0.996 | 1.475 | 1.652 | 674 |
+| 160 | 1.000 | 1.777 | 1.861 | 562 |
 
-Build time was 7.77 s (129 vectors/s). The result demonstrates the expected frontier: greater search effort recovers more exact neighbors while reducing throughput. Full raw output is in [`benchmarks/results/smoke-1000x64-seed42.json`](benchmarks/results/smoke-1000x64-seed42.json). Results are hardware- and dataset-specific.
+Build time was 7.37 s (136 vectors/s). The result demonstrates the expected frontier: greater search effort recovers more exact neighbors while reducing throughput. Full raw output is in [`benchmarks/results/frontier-1000x64.json`](benchmarks/results/frontier-1000x64.json). Results are hardware- and dataset-specific.
+
+At `ef_search=20`, five deterministic insertion orders produced recall@10 from 0.904 to 0.922 (mean 0.9116, population standard deviation 0.0061). This small experiment demonstrates topology sensitivity; it does not establish statistical significance. After cumulative physical deletion of 20%, recall was 0.916 versus a baseline of 0.908; rebuilding the remaining vectors raised it to 0.954. This dataset did not show monotonic deletion degradation, so none is claimed. The rebuild result still shows that an unrepaired graph and a fresh graph are measurably different. These files record the base Git revision and `working_tree_dirty=true`, because Stage Two measurements were produced before its changes were committed.
 
 ```bash
-python benchmarks/ann_benchmark.py --vectors 10000 --dim 128 --queries 100 \
-  --ef-search 10 20 40 80 160 --seed 42
+python -m benchmarks.ann_benchmark --experiment frontier --vectors 10000 \
+  --dim 128 --queries 100 --ef-search 10 20 40 80 160
+python -m benchmarks.ann_benchmark --experiment insertion-order --ef-search 20
+python -m benchmarks.ann_benchmark --experiment deletion --ef-search 20
 ```
 
 Use 100,000 vectors and dimensions 128/384/768 for full experiments; those runs are deliberately excluded from CI.
@@ -74,12 +78,14 @@ Each mutation writes an immutable `gen-*/` directory containing `manifest.json`,
 ```bash
 python -m venv .venv
 . .venv/bin/activate
-pip install -e '.[dev,cli]'
-ruff check vecstream tests benchmarks/ann_benchmark.py
+python -m pip install numpy hypothesis mypy pytest ruff
+ruff check --select E,F,I,B vecstream tests benchmarks/ann_benchmark.py
 mypy vecstream
 pytest -q
 ```
 
+VecStream is run directly from the repository and is not published as a Python package.
+
 See [HNSW design](docs/design.md), [limitations](docs/limitations.md), [performance notes](docs/performance.md), and the [repository audit](docs/audit.md).
 
 ## Scope and limitations

benchmarks/README.md

@@ -1,12 +1,16 @@
 # ANN benchmarks
 
-`ann_benchmark.py` measures VecStream HNSW results against vectorized exact cosine top-k. It reports environment and configuration, build throughput, recall@k, latency percentiles, and QPS while sweeping `ef_search`.
+`ann_benchmark.py` measures HNSW against vectorized exact cosine top-k. It provides three deliberately narrow experiments:
+
+- `frontier`: sweep `ef_search` and report recall/latency.
+- `insertion-order`: index one fixed dataset under independently seeded shuffles.
+- `deletion`: measure baseline, cumulative 5%/10%/20% physical deletion, and rebuild.
 
 ```bash
-python benchmarks/ann_benchmark.py --vectors 10000 --dim 128 --queries 100 \
-  --ef-search 10 20 40 80 160 --seed 42 --output run.json
+python -m benchmarks.ann_benchmark --experiment frontier --vectors 10000 \
+  --dim 128 --queries 100 --ef-search 10 20 40 80 160 --output run.json
+python -m benchmarks.ann_benchmark --experiment insertion-order --ef-search 20
+python -m benchmarks.ann_benchmark --experiment deletion --ef-search 20
 ```
 
-The committed `results/smoke-1000x64-seed42.json` is a small measured regression artifact. It must not be generalized to other hardware, dimensions, distributions, or dataset sizes. Full 10k/100k experiments are manual because this pure-Python implementation builds too slowly for routine CI at those sizes.
-
-Historical graph images in this directory predate the exact-recall harness and are retained only as project history; they are not evidence for current performance claims.
+Dataset, graph-level, insertion-order, and deletion RNG seeds are separate. Each JSON result records the Git revision, Python/NumPy versions, platform, architecture, configuration, and seeds. The three committed 1,000 × 64 results are small measured examples, not claims about other workloads. Full 10k/100k experiments remain manual.