numpy-vector-store 0.5.0__tar.gz → 0.6.0__tar.gz

{numpy_vector_store-0.5.0 → numpy_vector_store-0.6.0}/CHANGELOG.md

@@ -4,6 +4,148 @@ This changelog records user-visible changes to NumPy Vector Store. Earlier
 release notes remain available on the
 [GitHub releases page](https://github.com/tvanreenen/numpy-vector-store/releases).
 
+## 0.6.0 - 2026-08-21
+
+This release makes the existing API's input and failure contracts predictable
+before 1.0. It closes cases where the same invalid call could behave
+differently on an empty and populated store, where Python booleans could act as
+row indexes or counts, and where loosely coerced configuration could change
+meaning after persistence. It also turns the project's performance claims and
+format-version-1 compatibility promise into reproducible regression evidence.
+
+Valid, documented 0.5 usage continues to work unchanged. Version 0.6 does not
+add a new feature family, archive format, runtime dependency, or public
+exception hierarchy.
+
+### API at a glance
+
+The complete workflow remains centered on `VectorStore` and `VectorHit`:
+
+```python
+store = VectorStore(dimensions=1536, normalize=True)
+store.add(vectors, metadata)
+
+hits = store.cosine_search(query, top_k=10)
+hits = store.dot_search(query, top_k=10, min_value=0.5)
+hits = store.euclidean_search(query, top_k=10, within_rows=row_indexes)
+
+row = store.get(0)
+store.clear()
+
+store.save("vectors.npz")
+store.save()
+
+loaded = VectorStore.open("vectors.npz")
+loaded.reload()
+```
+
+The ownership, amortized ingestion, deterministic tie ordering, explicit
+persistence lifecycle, and trusted-local-file boundary established in 0.5 are
+unchanged.
+
+### Predictable scalar inputs
+
+- Accept Python integers, NumPy integer scalars, and other values implementing
+  the standard integer-index protocol for `dimensions`, `top_k`, and
+  `get(index)`, then convert them to a Python `int`.
+- Reject Python and NumPy booleans where integer semantics are required.
+  `top_k=True` no longer means one, and `get(True)` no longer invokes NumPy
+  boolean indexing.
+- Continue requiring positive `dimensions` and `top_k` values. A valid integer
+  outside the stored row range still makes `get()` return `None`.
+- Accept Python and NumPy booleans for `normalize`, then retain a canonical
+  Python `bool` in memory and persistence.
+- Accept finite Python and NumPy integer or floating-point scalars for
+  `min_value` and `max_value`. Reject booleans, strings, complex values,
+  arrays, and non-finite thresholds before search.
+
+An inappropriate scalar type now raises `TypeError`, while a supported type
+with an invalid value raises `ValueError`. Row bounds continue using
+`IndexError` where row selectors require an existing row. Exact error wording
+remains explanatory rather than a compatibility guarantee.
+
+### Search checks independent of store state
+
+- Validate `within_rows` before returning an empty result. It must be a
+  one-dimensional sequence of unique integer row indexes, without booleans,
+  and every index must be within the current store.
+- Reject duplicate filtered indexes instead of returning the same stored row
+  more than once.
+- Apply the same zero-query rules before the empty-store shortcut. Cosine
+  search always requires a non-zero query. Dot-product and Euclidean searches
+  require one when the store normalizes vectors, while raw stores continue to
+  accept a zero query for those two metrics.
+- Keep selector validation vectorized for native NumPy integer arrays and avoid
+  changing process-global warning filters while validating Python sequences.
+
+These changes affect preconditions, not ranking. Valid 0.5 searches retain the
+same metric calculations, thresholds, deterministic tie handling, filtered-row
+semantics, and `VectorHit` results.
+
+### Persistence inputs and compatibility boundaries
+
+- Accept strings and string-returning path-like objects for `open()`,
+  `save(path)`, and bound archive paths. Reject an explicitly empty path with
+  `ValueError` and an inappropriate path type, including bytes paths, with
+  `TypeError`.
+- Keep `save()` with no argument distinct from `save("")`: omission means
+  "save to the current binding," while an empty string is an invalid path.
+- Preserve extension resolution. A path without `.npz` still resolves to the
+  same archive for saving, opening, and reloading.
+- Preserve owning exceptions at the persistence boundary. Filesystem failures
+  use the relevant `OSError` subclass, malformed archive schemas use
+  `ValueError`, and NumPy, pickle, or application metadata-loading failures are
+  not hidden inside a package-specific wrapper.
+
+Archive format version 1 is unchanged. The compatibility suite now includes an
+archive produced by the published 0.4.0 package on Python 3.11 with NumPy
+1.23.2 and verifies that the current reader recovers its configuration, vectors,
+and metadata. This is a forward-reading promise for the self-describing format,
+not support for older unversioned two-array archives or a promise that an old
+package can read an arbitrary future format. Persistence remains a trusted-file
+feature because opaque metadata uses NumPy's pickle-backed object arrays.
+
+### Reproducible performance evidence
+
+- Add repository benchmark commands for public exact search and ingestion.
+  Each command records the workload, seeded input digests, complete timing
+  samples, median, Python and NumPy versions, Git state, timer, thread-related
+  environment variables, and NumPy build configuration as JSON.
+- Measure prepared inputs and documented public operations rather than random
+  input generation. Search records complete query batches; ingestion records a
+  fresh store and every `add()` call.
+- Add structural regression checks for geometric capacity reuse, partial
+  top-k selection, and unfiltered access to the stored vector matrix without a
+  preliminary full-matrix copy.
+- Keep wall-clock limits out of shared CI, where runner load would make failures
+  noisy and machine-specific.
+
+The README now reports one aligned grid at 1,000, 10,000, and 100,000 rows for
+384, 1,536, and 3,072 dimensions, measured on a 24 GB Apple M4 Mac mini. It
+also makes the intended scale explicit: this project is for small-to-medium,
+in-process exact search. The 100,000-row measurements are an upper reference,
+not a target for indefinite scaling; routinely million-row workloads generally
+need an indexed or service-backed system.
+
+### Runtime compatibility and upgrade notes
+
+- Continue supporting Python 3.11 through 3.14 and NumPy 1.23.2 or newer.
+- Continue exercising every supported Python version in CI, including a
+  dedicated Python 3.11 job with the minimum NumPy version.
+- Keep the runtime wheel limited to the package. Benchmark tooling and its
+  guide are included in the source distribution without adding runtime
+  dependencies.
+- Require no archive conversion when upgrading from 0.5; format version 1 is
+  still the only supported archive format.
+
+Applications using documented 0.5 input types should not need code changes.
+Review call sites that pass booleans where integers are expected, fractional
+result counts, string or boolean thresholds, duplicate or malformed
+`within_rows` values, zero queries that were only attempted against empty
+stores, or explicitly empty persistence paths. Those accidentally accepted or
+state-dependent cases now fail at the public boundary with consistent standard
+exceptions.
+
 ## 0.5.0 - 2026-08-21
 
 This release gives `VectorStore` clear ownership of its configuration and row

{numpy_vector_store-0.5.0 → numpy_vector_store-0.6.0}/MIGRATION.md

@@ -177,6 +177,11 @@ contents, loads its rows, and binds its path. Applications no longer need to
 keep archive configuration separately or risk loading the same vectors with
 different semantics.
 
+Paths may be strings or string-valued `os.PathLike` objects such as
+`pathlib.Path`. Empty paths raise `ValueError`, while bytes and other non-path
+values raise `TypeError`. A `None` path is meaningful only for `save()`, where
+it reuses an existing binding.
+
 The generic parameter still describes application metadata. It can be kept
 when useful:
 
@@ -284,6 +289,17 @@ configuration safely.
 Metadata is stored in a pickle-backed NumPy object array. Archives remain
 trusted input and must not be opened from untrusted or unverifiable sources.
 
+Current releases retain forward-reading support for self-describing
+format-version-1 archives written by 0.4. The test suite keeps a binary fixture
+generated by the published 0.4.0 package on Python 3.11 and NumPy 1.23.2. This
+does not restore the unversioned reader or promise that an older release can
+read an arbitrary future format.
+
+Read and write failures retain the exception type owned by their source:
+filesystem `OSError` subclasses, schema `ValueError`, and NumPy, pickle, or
+application metadata-loading errors are not collapsed into a package-specific
+exception.
+
 Saves use same-directory temporary files and atomic replacement, but the
 library does not add file locking, coordinate concurrent writers, or promise
 power-loss durability across every operating system and filesystem.

{numpy_vector_store-0.5.0 → numpy_vector_store-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: numpy-vector-store
-Version: 0.5.0
+Version: 0.6.0
 Summary: A fast, lightweight, and zero-setup in-memory vector store powered by NumPy
 Project-URL: Homepage, https://github.com/tvanreenen/numpy-vector-store
 Project-URL: Repository, https://github.com/tvanreenen/numpy-vector-store
@@ -39,18 +39,59 @@ offers a simple alternative to heavyweight vector databases when you do not need
 network services, indexing infrastructure, ingestion pipelines, or domain-specific
 metadata filtering.
 
-## When/Where?
+## Performance
 
-Below are benchmark results for cosine similarity search to help you assess its
-suitability for your use case.
+`VectorStore` performs exact search over every selected row. The following
+measurements are reference points, not latency guarantees:
 
-| Embedding Type | Dimensions | ~5ms | ~25ms | ~100ms | ~500ms |
-|----------------|------------|------|--------|---------|---------|
-| **Sentence Transformers** | 384 | 1K vectors<br/>1.5MB | 10K vectors<br/>15MB | 100K vectors<br/>147MB | 500K vectors<br/>732MB |
-| **OpenAI Small** | 1536 | 500 vectors<br/>3MB | 5K vectors<br/>29MB | 25K vectors<br/>147MB | 100K vectors<br/>586MB |
-| **OpenAI Large** | 3072 | 200 vectors<br/>2MB | 2.5K vectors<br/>29MB | 5K vectors<br/>59MB | 25K vectors<br/>293MB |
+Each cell shows the median time per cosine query followed by the stored vector
+matrix size:
 
-*Benchmarks performed on Apple M2 hardware.*
+| Rows | 384 dimensions | 1,536 dimensions | 3,072 dimensions |
+|---:|---:|---:|---:|
+| 1,000 | 0.032 ms · 1.5 MB | 0.049 ms · 6.1 MB | 0.088 ms · 12.3 MB |
+| 10,000 | 0.286 ms · 15.4 MB | 1.065 ms · 61.4 MB | 2.122 ms · 122.9 MB |
+| 100,000 | 2.983 ms · 153.6 MB | 9.877 ms · 614.4 MB | 20.509 ms · 1.23 GB |
+
+These benchmarks intentionally stop at 100,000 rows. NumPy Vector Store is
+designed for small-to-medium, in-process exact search; 100,000 rows is an upper
+reference, not a promised limit or a target for continued scaling. The practical
+boundary depends on vector dimensions, metadata, available memory, and latency
+requirements. Workloads that routinely reach millions of vectors generally
+need an indexed or service-backed system.
+
+These are unfiltered `top_k=10` searches on a normalized store. Each row divides
+the median duration of seven measured 20-query trials by 20, after two discarded
+warmup trials. The vector matrix size excludes metadata, temporary search
+arrays, and Python process overhead.
+
+The measurements were taken from commit `4b23810` on a 24 GB Apple M4 Mac mini
+with macOS 26.6.1, CPython 3.13.5, NumPy 2.3.3, and Accelerate BLAS. Hardware,
+operating system activity, Python and NumPy versions, BLAS implementation, and
+thread settings can all change the result.
+
+The repository includes benchmark commands that emit the inputs, environment,
+raw samples, and median as JSON:
+
+```bash
+uv run python benchmarks/benchmark.py search \
+  --rows 10000 --dimensions 384 --queries 20 --top-k 10 \
+  --warmup 2 --repetitions 7 > /tmp/nvs-search.json
+
+uv run python benchmarks/benchmark.py ingest \
+  --rows 10000 --dimensions 384 --batch-size 1 \
+  --warmup 2 --repetitions 7 > /tmp/nvs-ingest.json
+```
+
+For the same 10,000-by-384 prepared input, repeated single-row ingestion had a
+median of 78.6 ms, or about 127,000 rows per second. Supplying 1,000 rows per
+`add()` call had a median of 6.63 ms, or about 1.51 million rows per second.
+Both measurements include construction of a fresh normalized store and every
+`add()` call, but exclude input generation.
+
+See [the benchmark guide](benchmarks/README.md) for the timed regions, complete
+options, output fields, and interpretation notes. The project keeps structural
+complexity checks in CI, but does not fail shared runners on wall-clock timing.
 
 ## Installation
 
@@ -93,6 +134,32 @@ Each payload can be a dict, dataclass, tuple, list, string, integer row ID, or
 another Python object that fits your application. Tuple and list payloads remain
 single row values rather than being interpreted as additional array dimensions.
 
+## Scalar inputs and errors
+
+`dimensions`, `top_k`, and the index passed to `get()` use integer semantics.
+Python integers and NumPy integer scalars are accepted and converted to Python
+`int`; booleans are rejected rather than being treated as zero or one.
+`dimensions` and `top_k` must be greater than zero. A valid integer outside the
+stored row range still makes `get()` return `None`.
+
+`normalize` accepts Python and NumPy booleans and is stored as a Python `bool`.
+Search thresholds such as `min_value` and `max_value` accept finite Python
+integer or floating-point values and NumPy integer or floating scalars.
+Booleans, strings, complex numbers, and arrays are not threshold scalars and are
+rejected.
+
+`within_rows` must be a one-dimensional sequence of unique integer row indexes.
+Python and NumPy integers are accepted; booleans and non-integer values are not.
+Malformed shapes and duplicate indexes raise `ValueError`, while an index
+outside the current store raises `IndexError`. These checks still run when the
+store is empty.
+
+For these scalar inputs, an inappropriate type raises `TypeError` and a
+supported type with an invalid value raises `ValueError`. Row selectors outside
+the store raise `IndexError`, and filesystem operations continue to raise the
+relevant `OSError` subclass. Error messages explain the failed argument, but
+their exact wording is not a compatibility guarantee.
+
 ## State ownership
 
 The store owns its configuration and row structure. `dimensions`, `normalize`,
@@ -169,6 +236,11 @@ search. Because cosine similarity is undefined for zero vectors,
 `cosine_search` raises an error when its selected rows include one; use
 `within_rows` to exclude zero rows when needed.
 
+Cosine search also requires a non-zero query. Dot-product and Euclidean searches
+require one when `normalize=True`, because they normalize the query before
+comparison. With `normalize=False`, both methods accept a zero query. These
+rules apply even when the store or `within_rows` selection is empty.
+
 ### Numerical inputs
 
 Stored vectors use `float32` to keep the store compact. Vectors and queries must
@@ -243,6 +315,10 @@ rows = [
 hits = store.cosine_search(query, top_k=10, within_rows=rows)
 ```
 
+Each stored row may appear at most once in `within_rows`; duplicate indexes are
+rejected rather than producing duplicate hits. An empty sequence returns no
+hits, but it does not bypass validation of the query or other search arguments.
+
 Searches without `within_rows` compute directly against the stored vector matrix
 and do not make a full copy of it. A filtered search gathers the selected rows
 into a temporary matrix, so its additional memory use scales with the number of
@@ -328,6 +404,12 @@ current in-memory vectors and metadata unchanged.
 The `.npz` suffix may be omitted. An extensionless path such as `"vectors"` is
 resolved to `"vectors.npz"` for saving, opening, and reloading.
 
+Persistence paths accept strings and string-valued `os.PathLike` objects such
+as `pathlib.Path`. Passing an empty path raises `ValueError`; passing `None`,
+bytes, or another non-path value to `open()` raises `TypeError`. For `save()`,
+`None` retains its established meaning: reuse the current binding, or raise
+`ValueError` if the store has not been bound yet.
+
 Raw-vector configuration is also restored from the archive:
 
 ```python
@@ -343,15 +425,27 @@ assert loaded.normalize is False
 ```
 
 Archives written by 0.4 use format version 1 and contain `format_version`,
-`dimensions`, `normalize`, `vectors`, and `metadata`. The stored configuration
-prevents an archive from being loaded with different dimensions or normalization
-semantics.
+`dimensions`, `normalize`, `vectors`, and `metadata`. The compatibility suite
+opens an archive generated by the published 0.4.0 package on the oldest
+supported Python and NumPy versions. The stored configuration prevents an
+archive from being loaded with different dimensions or normalization semantics.
+
+This is a forward-reading promise for self-describing format-version-1
+archives: current releases can open the recorded 0.4 fixture. It does not
+restore the unversioned two-array reader or guarantee that an older package can
+open files written by an arbitrary future archive format.
 
 Opening and reloading validate the complete schema, array dtypes and shapes, row
 counts, finite vector values, and zero-norm behavior before changing in-memory
 state. Opaque metadata values remain individual row payloads across persistence
 round trips.
 
+Persistence failures keep their owning exception type. Filesystem failures use
+the relevant `OSError` subclass, malformed schemas use `ValueError`, and NumPy,
+pickle, or application metadata-loading exceptions are not wrapped in a package
+exception. Exact message text remains explanatory rather than a compatibility
+guarantee.
+
 Each save writes a uniquely named temporary archive in the destination
 directory, closes it, and then replaces the destination with `os.replace`.
 Readers opening the destination path therefore see either the previous complete
@@ -364,7 +458,7 @@ writers can still replace one another, and the library does not promise that a
 successful save has reached durable hardware storage across every operating
 system or power failure.
 
-Version 0.5 reads only self-describing format version 1 archives. Unversioned
+Version 0.6 reads only self-describing format version 1 archives. Unversioned
 archives containing only `vectors` and `metadata` cannot be opened because they
 do not record dimensions or normalization semantics. Recreate those archives
 from source data, or convert them with NumPy Vector Store 0.4 before upgrading.
@@ -384,10 +478,10 @@ the API stabilizes. Changes are documented in the [changelog](CHANGELOG.md) and
 GitHub release notes. Deprecated APIs will keep warning for at least one point
 release before removal.
 
-Version 0.5 supports Python 3.11 through 3.14 and NumPy 1.23.2 or newer. These
+Version 0.6 supports Python 3.11 through 3.14 and NumPy 1.23.2 or newer. These
 versions are listed in the package metadata and exercised in CI, including a
 dedicated check against the minimum NumPy version. Python 3.10 remains supported
-by the 0.3 release series but is not supported by 0.4 or 0.5.
+by the 0.3 release series but is not supported by 0.4 or later.
 
 The project generally retains stable CPython versions until their upstream
 end-of-life, adds new versions after its dependencies and CI support them, and

{numpy_vector_store-0.5.0 → numpy_vector_store-0.6.0}/README.md

@@ -16,18 +16,59 @@ offers a simple alternative to heavyweight vector databases when you do not need
 network services, indexing infrastructure, ingestion pipelines, or domain-specific
 metadata filtering.
 
-## When/Where?
+## Performance
 
-Below are benchmark results for cosine similarity search to help you assess its
-suitability for your use case.
+`VectorStore` performs exact search over every selected row. The following
+measurements are reference points, not latency guarantees:
 
-| Embedding Type | Dimensions | ~5ms | ~25ms | ~100ms | ~500ms |
-|----------------|------------|------|--------|---------|---------|
-| **Sentence Transformers** | 384 | 1K vectors<br/>1.5MB | 10K vectors<br/>15MB | 100K vectors<br/>147MB | 500K vectors<br/>732MB |
-| **OpenAI Small** | 1536 | 500 vectors<br/>3MB | 5K vectors<br/>29MB | 25K vectors<br/>147MB | 100K vectors<br/>586MB |
-| **OpenAI Large** | 3072 | 200 vectors<br/>2MB | 2.5K vectors<br/>29MB | 5K vectors<br/>59MB | 25K vectors<br/>293MB |
+Each cell shows the median time per cosine query followed by the stored vector
+matrix size:
 
-*Benchmarks performed on Apple M2 hardware.*
+| Rows | 384 dimensions | 1,536 dimensions | 3,072 dimensions |
+|---:|---:|---:|---:|
+| 1,000 | 0.032 ms · 1.5 MB | 0.049 ms · 6.1 MB | 0.088 ms · 12.3 MB |
+| 10,000 | 0.286 ms · 15.4 MB | 1.065 ms · 61.4 MB | 2.122 ms · 122.9 MB |
+| 100,000 | 2.983 ms · 153.6 MB | 9.877 ms · 614.4 MB | 20.509 ms · 1.23 GB |
+
+These benchmarks intentionally stop at 100,000 rows. NumPy Vector Store is
+designed for small-to-medium, in-process exact search; 100,000 rows is an upper
+reference, not a promised limit or a target for continued scaling. The practical
+boundary depends on vector dimensions, metadata, available memory, and latency
+requirements. Workloads that routinely reach millions of vectors generally
+need an indexed or service-backed system.
+
+These are unfiltered `top_k=10` searches on a normalized store. Each row divides
+the median duration of seven measured 20-query trials by 20, after two discarded
+warmup trials. The vector matrix size excludes metadata, temporary search
+arrays, and Python process overhead.
+
+The measurements were taken from commit `4b23810` on a 24 GB Apple M4 Mac mini
+with macOS 26.6.1, CPython 3.13.5, NumPy 2.3.3, and Accelerate BLAS. Hardware,
+operating system activity, Python and NumPy versions, BLAS implementation, and
+thread settings can all change the result.
+
+The repository includes benchmark commands that emit the inputs, environment,
+raw samples, and median as JSON:
+
+```bash
+uv run python benchmarks/benchmark.py search \
+  --rows 10000 --dimensions 384 --queries 20 --top-k 10 \
+  --warmup 2 --repetitions 7 > /tmp/nvs-search.json
+
+uv run python benchmarks/benchmark.py ingest \
+  --rows 10000 --dimensions 384 --batch-size 1 \
+  --warmup 2 --repetitions 7 > /tmp/nvs-ingest.json
+```
+
+For the same 10,000-by-384 prepared input, repeated single-row ingestion had a
+median of 78.6 ms, or about 127,000 rows per second. Supplying 1,000 rows per
+`add()` call had a median of 6.63 ms, or about 1.51 million rows per second.
+Both measurements include construction of a fresh normalized store and every
+`add()` call, but exclude input generation.
+
+See [the benchmark guide](benchmarks/README.md) for the timed regions, complete
+options, output fields, and interpretation notes. The project keeps structural
+complexity checks in CI, but does not fail shared runners on wall-clock timing.
 
 ## Installation
 
@@ -70,6 +111,32 @@ Each payload can be a dict, dataclass, tuple, list, string, integer row ID, or
 another Python object that fits your application. Tuple and list payloads remain
 single row values rather than being interpreted as additional array dimensions.
 
+## Scalar inputs and errors
+
+`dimensions`, `top_k`, and the index passed to `get()` use integer semantics.
+Python integers and NumPy integer scalars are accepted and converted to Python
+`int`; booleans are rejected rather than being treated as zero or one.
+`dimensions` and `top_k` must be greater than zero. A valid integer outside the
+stored row range still makes `get()` return `None`.
+
+`normalize` accepts Python and NumPy booleans and is stored as a Python `bool`.
+Search thresholds such as `min_value` and `max_value` accept finite Python
+integer or floating-point values and NumPy integer or floating scalars.
+Booleans, strings, complex numbers, and arrays are not threshold scalars and are
+rejected.
+
+`within_rows` must be a one-dimensional sequence of unique integer row indexes.
+Python and NumPy integers are accepted; booleans and non-integer values are not.
+Malformed shapes and duplicate indexes raise `ValueError`, while an index
+outside the current store raises `IndexError`. These checks still run when the
+store is empty.
+
+For these scalar inputs, an inappropriate type raises `TypeError` and a
+supported type with an invalid value raises `ValueError`. Row selectors outside
+the store raise `IndexError`, and filesystem operations continue to raise the
+relevant `OSError` subclass. Error messages explain the failed argument, but
+their exact wording is not a compatibility guarantee.
+
 ## State ownership
 
 The store owns its configuration and row structure. `dimensions`, `normalize`,
@@ -146,6 +213,11 @@ search. Because cosine similarity is undefined for zero vectors,
 `cosine_search` raises an error when its selected rows include one; use
 `within_rows` to exclude zero rows when needed.
 
+Cosine search also requires a non-zero query. Dot-product and Euclidean searches
+require one when `normalize=True`, because they normalize the query before
+comparison. With `normalize=False`, both methods accept a zero query. These
+rules apply even when the store or `within_rows` selection is empty.
+
 ### Numerical inputs
 
 Stored vectors use `float32` to keep the store compact. Vectors and queries must
@@ -220,6 +292,10 @@ rows = [
 hits = store.cosine_search(query, top_k=10, within_rows=rows)
 ```
 
+Each stored row may appear at most once in `within_rows`; duplicate indexes are
+rejected rather than producing duplicate hits. An empty sequence returns no
+hits, but it does not bypass validation of the query or other search arguments.
+
 Searches without `within_rows` compute directly against the stored vector matrix
 and do not make a full copy of it. A filtered search gathers the selected rows
 into a temporary matrix, so its additional memory use scales with the number of
@@ -305,6 +381,12 @@ current in-memory vectors and metadata unchanged.
 The `.npz` suffix may be omitted. An extensionless path such as `"vectors"` is
 resolved to `"vectors.npz"` for saving, opening, and reloading.
 
+Persistence paths accept strings and string-valued `os.PathLike` objects such
+as `pathlib.Path`. Passing an empty path raises `ValueError`; passing `None`,
+bytes, or another non-path value to `open()` raises `TypeError`. For `save()`,
+`None` retains its established meaning: reuse the current binding, or raise
+`ValueError` if the store has not been bound yet.
+
 Raw-vector configuration is also restored from the archive:
 
 ```python
@@ -320,15 +402,27 @@ assert loaded.normalize is False
 ```
 
 Archives written by 0.4 use format version 1 and contain `format_version`,
-`dimensions`, `normalize`, `vectors`, and `metadata`. The stored configuration
-prevents an archive from being loaded with different dimensions or normalization
-semantics.
+`dimensions`, `normalize`, `vectors`, and `metadata`. The compatibility suite
+opens an archive generated by the published 0.4.0 package on the oldest
+supported Python and NumPy versions. The stored configuration prevents an
+archive from being loaded with different dimensions or normalization semantics.
+
+This is a forward-reading promise for self-describing format-version-1
+archives: current releases can open the recorded 0.4 fixture. It does not
+restore the unversioned two-array reader or guarantee that an older package can
+open files written by an arbitrary future archive format.
 
 Opening and reloading validate the complete schema, array dtypes and shapes, row
 counts, finite vector values, and zero-norm behavior before changing in-memory
 state. Opaque metadata values remain individual row payloads across persistence
 round trips.
 
+Persistence failures keep their owning exception type. Filesystem failures use
+the relevant `OSError` subclass, malformed schemas use `ValueError`, and NumPy,
+pickle, or application metadata-loading exceptions are not wrapped in a package
+exception. Exact message text remains explanatory rather than a compatibility
+guarantee.
+
 Each save writes a uniquely named temporary archive in the destination
 directory, closes it, and then replaces the destination with `os.replace`.
 Readers opening the destination path therefore see either the previous complete
@@ -341,7 +435,7 @@ writers can still replace one another, and the library does not promise that a
 successful save has reached durable hardware storage across every operating
 system or power failure.
 
-Version 0.5 reads only self-describing format version 1 archives. Unversioned
+Version 0.6 reads only self-describing format version 1 archives. Unversioned
 archives containing only `vectors` and `metadata` cannot be opened because they
 do not record dimensions or normalization semantics. Recreate those archives
 from source data, or convert them with NumPy Vector Store 0.4 before upgrading.
@@ -361,10 +455,10 @@ the API stabilizes. Changes are documented in the [changelog](CHANGELOG.md) and
 GitHub release notes. Deprecated APIs will keep warning for at least one point
 release before removal.
 
-Version 0.5 supports Python 3.11 through 3.14 and NumPy 1.23.2 or newer. These
+Version 0.6 supports Python 3.11 through 3.14 and NumPy 1.23.2 or newer. These
 versions are listed in the package metadata and exercised in CI, including a
 dedicated check against the minimum NumPy version. Python 3.10 remains supported
-by the 0.3 release series but is not supported by 0.4 or 0.5.
+by the 0.3 release series but is not supported by 0.4 or later.
 
 The project generally retains stable CPython versions until their upstream
 end-of-life, adds new versions after its dependencies and CI support them, and

{numpy_vector_store-0.5.0 → numpy_vector_store-0.6.0}/ROADMAP.md

@@ -36,10 +36,11 @@ compatibility contract and are exercised in CI. The project generally:
 - Drops a Python version only in a minor release and calls out the change in
   release notes.
 
-The 0.3 series supports Python 3.10 through 3.14. Version 0.4 supports Python
-3.11 through 3.14, using the minor-release boundary to remove Python 3.10 ahead
-of its upstream end-of-life in October 2026. NumPy 1.23.2 is the minimum for
-0.4 because it is the earliest NumPy release that supports Python 3.11.
+The 0.3 series supports Python 3.10 through 3.14. Versions 0.4 through 0.6
+support Python 3.11 through 3.14, using the 0.4 minor-release boundary to remove
+Python 3.10 ahead of its upstream end-of-life in October 2026. NumPy 1.23.2 is
+the minimum for 0.4 and later because it is the earliest NumPy release that
+supports Python 3.11.
 
 Supported NumPy versions are also part of the runtime contract. The declared
 minimum should be installable on the oldest supported Python version and should
@@ -393,17 +394,71 @@ State encapsulation and spare capacity do not change serialized data, so format
 version 1 remains sufficient. Broader validation and exception consistency stay
 in the 0.6 stabilization milestone.
 
-## 0.6.0: API stabilization
+## 0.6.0: Predictable input contracts and regression guarantees
 
-This release is intended to consolidate the earlier changes rather than add a
-new feature family.
-
-Planned direction:
+Status: complete
 
-- Make validation and exception behavior consistent across methods.
-- Add performance regression coverage for representative store sizes.
-- Exercise persistence upgrades and backwards compatibility.
-- Resolve known high- and medium-priority defects.
+Version 0.6 makes the existing API's accepted inputs, failures, performance
+expectations, and versioned-archive compatibility explicit before 1.0. Valid
+documented 0.5 calls remain supported. Inputs that were accepted only through
+Python truth-value coercion, NumPy indexing side effects, or row-count shortcuts
+may be rejected at this minor-release boundary.
+
+### Scalar configuration, counts, and indexes
+
+- Accept Python and NumPy integer scalars for `dimensions`, `top_k`, and
+  `get(index)`, then convert them to Python `int`.
+- Reject Python and NumPy booleans where integer semantics are required. This
+  prevents `top_k=True` from meaning one and prevents `get(True)` from invoking
+  NumPy boolean indexing instead of retrieving one row.
+- Require positive dimensions and result counts while keeping `get()`'s
+  established `None` result for a valid integer outside the stored row range.
+- Accept Python and NumPy booleans for `normalize`, then keep a canonical Python
+  `bool` so configuration cannot change meaning across persistence.
+- Accept finite Python and NumPy integer or floating scalar search thresholds,
+  excluding booleans, strings, complex numbers, and arrays.
+
+Wrong argument types raise `TypeError`, supported types with invalid values
+raise `ValueError`, and row selectors outside the store raise `IndexError`.
+Exact error wording is explanatory rather than a compatibility contract.
+
+### State-independent search preconditions
+
+- Validate `within_rows` shape, integer values, uniqueness, and bounds before an
+  empty store can return no hits.
+- Apply zero-query rules consistently: cosine always requires a non-zero query;
+  normalized dot and Euclidean searches also normalize their query; raw dot and
+  Euclidean searches continue accepting a zero query.
+- Reject duplicate filtered row indexes rather than returning the same stored
+  row more than once.
+
+### Versioned persistence compatibility
+
+- Distinguish an omitted path from an explicitly empty or incorrectly typed
+  path while preserving normal filesystem exception types.
+- Keep current releases able to open format-version-1 archives produced by 0.4
+  at the oldest supported Python and NumPy boundary.
+- Preserve schema and deserialization failure context without wrapping every
+  NumPy, pickle, or application exception in a package-specific error.
+
+This compatibility promise applies to self-describing format-version-1
+archives. It does not restore the unversioned two-array reader, removed 0.4
+entry points, or a guarantee that an older package can open files written by an
+arbitrary newer format.
+
+### Reproducible performance evidence
+
+- Add deterministic ingestion and search benchmark commands that record their
+  environment, input sizes, warmup, repetitions, and summary statistic.
+- Keep structural regression tests for capacity growth, partial top-k
+  selection, and avoidable full-matrix copies.
+- Keep wall-clock thresholds out of shared CI, where runner variance would make
+  failures noisy rather than diagnostic.
+
+Version 0.6 does not add update, delete, builder, streaming, async, locking, or
+metadata-query APIs. It does not introduce a validation dependency, public
+exception hierarchy, archive format version 2, or deep-copy policy for opaque
+metadata.
 
 ## 1.0.0: Stable contracts