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

{numpy_vector_store-0.5.0 → numpy_vector_store-0.7.0}/.github/workflows/checks.yml

@@ -22,10 +22,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.13"
 
@@ -46,7 +46,7 @@ jobs:
         run: uv run --locked ruff format --check .
 
       - name: Run mypy
-        run: uv run --locked mypy src/
+        run: uv run --locked mypy src/ benchmarks/ tools/
 
   tests:
     name: Test Python ${{ matrix.python-version }}
@@ -62,10 +62,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -82,16 +82,42 @@ jobs:
       - name: Run tests
         run: uv run --locked pytest
 
+  windows:
+    name: Test Windows on Python 3.13
+    runs-on: windows-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.32"
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install project dependencies
+        run: uv sync --locked --group dev
+
+      - name: Run tests
+        run: uv run --locked pytest
+
   minimum-numpy:
     name: Test minimum NumPy on Python 3.11
     runs-on: ubuntu-latest
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.11"
 

{numpy_vector_store-0.5.0 → numpy_vector_store-0.7.0}/.github/workflows/publish-pypi.yml

@@ -20,10 +20,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.12"
 
@@ -33,8 +33,13 @@ jobs:
       - name: Build distributions
         run: python -m build
 
+      - name: Verify release versions
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: python tools/verify_release_version.py --tag "$RELEASE_TAG"
+
       - name: Check distribution metadata
         run: python -m twine check dist/*
 
       - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

{numpy_vector_store-0.5.0 → numpy_vector_store-0.7.0}/.github/workflows/publish-testpypi.yml

@@ -18,10 +18,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: "3.12"
 
@@ -31,10 +31,13 @@ jobs:
       - name: Build distributions
         run: python -m build
 
+      - name: Verify distribution versions
+        run: python tools/verify_release_version.py
+
       - name: Check distribution metadata
         run: python -m twine check dist/*
 
       - name: Publish package distributions to TestPyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
         with:
           repository-url: https://test.pypi.org/legacy/

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

@@ -4,6 +4,257 @@ 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.7.0 - 2026-08-24
+
+This release closes the remaining public contract gaps found during the 1.0
+readiness audit. It rejects two forms of lossy NumPy coercion, makes a bound
+archive path stable for the lifetime of its store, and publishes the API and
+compatibility policy intended for 1.x. It also adds release checks that enforce
+the package version and distribution metadata before publication.
+
+Valid, documented 0.6 usage continues to work. Version 0.7 does not add a new
+feature family, remove a documented API, change search ranking, add a runtime
+dependency, or change archive format version 1.
+
+### Public API and 1.x compatibility policy
+
+The supported package-level imports are now explicit:
+
+```python
+from numpy_vector_store import VectorHit, VectorStore, __version__
+```
+
+- Add a [public API and compatibility policy](COMPATIBILITY.md) that names the
+  supported `VectorStore` methods and properties, `VectorHit` fields, return
+  types, ownership behavior, exception classes, and persistence guarantees.
+- Distinguish the supported top-level interface from private helpers, submodule
+  layout, subclass hooks, exact error wording, allocation details, and internal
+  algorithms.
+- Define the 1.x semantic-versioning, deprecation, removal, Python and NumPy
+  support, and archive-compatibility policies before those promises become
+  long-term commitments in 1.0.
+- Keep `VectorHit` as an immutable result record whose equality and hashability
+  follow its three values. Opaque metadata retains its own comparison and
+  hashing behavior; a hit containing a dictionary remains unhashable.
+
+The API itself remains centered on `VectorStore`, `VectorHit`, three explicit
+metric methods, typed opaque metadata, and the create/open/save/reload
+persistence lifecycle.
+
+### Lossless numeric input handling
+
+- Reject Python row-selector sequences containing a Python or NumPy Boolean,
+  including mixed values such as `[0, True]`, before NumPy can coerce the
+  Boolean to row zero or one.
+- Preserve the vectorized validation path for native NumPy integer selectors,
+  along with the existing shape, uniqueness, and bounds rules.
+- Reject complex vector batches passed to `add()` and complex queries passed to
+  every metric method before conversion to `float32` can discard their
+  imaginary components. This includes complex dtypes whose current values have
+  a zero imaginary part.
+- Apply complex-query validation before empty-store and empty-filter shortcuts,
+  so the accepted query contract does not depend on current store state.
+
+These inputs were accepted only through implicit NumPy conversion. Calls that
+deliberately used Boolean row indexes or complex vectors now raise `TypeError`;
+real-valued integer and floating-point inputs keep their existing behavior.
+
+### Stable archive bindings
+
+- Anchor a relative path to the current working directory when `save(path)` or
+  `VectorStore.open(path)` first binds it.
+- Return that anchored absolute path from `file_path` and keep later `save()` and
+  `reload()` calls pointed at the same archive if the process changes working
+  directory.
+- Preserve extensionless `.npz` resolution and lexical path behavior. Anchoring
+  does not resolve `..` components or dereference symlinks, so ordinary
+  filesystem replacement semantics remain intact.
+- Keep Save As transactional: a new binding becomes visible only after the new
+  archive has been written successfully.
+
+Format version 1 is unchanged, and no archive conversion is required. Code that
+compares `file_path` with a relative path should compare against its anchored
+absolute form. Code that intentionally changed directories to redirect a later
+pathless save should pass the new destination explicitly to `save(path)`.
+
+### Distribution and release safeguards
+
+- Publish the MIT license as an SPDX expression and include `LICENSE` in both
+  the wheel and source distribution.
+- Declare the existing `py.typed` marker through the `Typing :: Typed`
+  classifier and identify 0.7 as the project's beta adoption cycle before 1.0.
+- Verify that the source `__version__`, GitHub release tag, wheel metadata, and
+  source-distribution metadata agree before publishing to PyPI. The verifier
+  also requires exactly one wheel and one source distribution so stale build
+  output cannot be uploaded accidentally.
+- Pin remote GitHub Actions to immutable commits while retaining readable
+  release comments beside each pin.
+- Run the complete test suite on Windows with Python 3.13 in addition to the
+  supported Python 3.11 through 3.14 matrix on Linux and the Python 3.11 minimum
+  NumPy check.
+- Add regression coverage for unexpected archive fields, nonpositive persisted
+  dimensions, malformed persisted array shapes, and platform-specific
+  filesystem exception and permission behavior.
+
+The release verifier and benchmark tools remain outside the runtime wheel and
+add no package dependency.
+
+### Runtime compatibility and upgrade notes
+
+- Continue supporting Python 3.11 through 3.14 and NumPy 1.23.2 or newer.
+- Continue reading and writing self-describing format-version-1 archives,
+  including archives created by the published 0.4 package.
+- Continue treating persistence as a trusted-file feature because opaque
+  metadata uses pickle-backed NumPy object arrays.
+- Require no data migration when upgrading from 0.6.
+
+Most applications can upgrade without code changes. Review only code that used
+Boolean row selectors, supplied complex vectors or queries, compared a bound
+`file_path` with a relative path, or relied on a later working-directory change
+to redirect a bound store.
+
+## 0.6.0 - 2026-08-22
+
+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.7.0/COMPATIBILITY.md

@@ -0,0 +1,145 @@
+# Public API and compatibility policy
+
+NumPy Vector Store 0.7 publishes the contract intended for 1.0 so applications
+can evaluate it before the project makes a long-term stability commitment. The
+package remains pre-1.0 until the 0.7 API has completed a normal release cycle.
+
+This policy separates the small supported interface from implementation details
+that may continue to improve during 1.x.
+
+## Supported public API
+
+Import supported names from the top-level package:
+
+```python
+from numpy_vector_store import VectorHit, VectorStore, __version__
+```
+
+These are the package-level public names declared by `numpy_vector_store.__all__`:
+
+- `VectorStore`, including its constructor, `len(store)`, and the documented
+  methods and properties below.
+- `VectorHit`, including its read-only `index`, `value`, and `metadata` fields.
+- `__version__`, the installed package version as a string.
+
+The supported `VectorStore` surface is:
+
+| Area | Public interface |
+|---|---|
+| Create | `VectorStore(dimensions, *, normalize=True)` |
+| Inspect configuration | `dimensions`, `normalize`, `file_path` |
+| Inspect rows | `vectors`, `metadata`, `len(store)` |
+| Change rows | `add(vectors, metadata)`, `clear()` |
+| Retrieve one row | `get(index)` |
+| Search | `cosine_search(...)`, `dot_search(...)`, `euclidean_search(...)` |
+| Persist | `VectorStore.open(path)`, `save(path)`, `save()`, `reload()` |
+
+The public contract includes documented signatures, accepted input categories,
+return types, public type annotations, state and ownership behavior, search
+ordering, and exception classes. The `VectorStore` generic parameter describes
+its metadata payload type and flows through row retrieval and search results.
+The contract also includes the documented `float32` vector representation and
+format-version-1 archive schema. Exact exception messages are explanatory text,
+not identifiers for application logic.
+
+Importing from `numpy_vector_store.vector_store` may work, but the submodule
+layout is an implementation detail. Applications should use top-level imports.
+Names beginning with a single underscore, private object state, spare-capacity
+layout, and internal calculation steps are not public API.
+
+`VectorStore` is not designed as a subclass extension framework. Subclassing is
+not prohibited, but overriding methods or depending on private helpers and state
+is outside the compatibility promise. Prefer composition when application code
+needs behavior around a store.
+
+## `VectorHit` and opaque metadata
+
+`VectorHit` is an immutable result record. Its fields cannot be reassigned, but
+the `metadata` value remains the same opaque application object held by the
+store. A mutable metadata payload can still be changed through that object.
+
+Equality and hashability follow the values stored in the three fields. There is
+no package-specific metadata comparison or hashing policy. In particular:
+
+- A hit containing a dictionary or another unhashable payload is unhashable.
+- A metadata type with non-Boolean equality, such as a NumPy array, can make
+  whole-hit equality return a non-Boolean value or raise when converted to a
+  truth value.
+- A metadata type with application-defined equality keeps those semantics.
+
+Use `hit.index` or an immutable application identifier inside `hit.metadata`
+when code needs a stable key. Do not assume every possible metadata payload
+makes the complete `VectorHit` suitable for a set, dictionary key, or Boolean
+equality assertion.
+
+## Semantic versioning after 1.0
+
+Starting with 1.0, release numbers follow
+[Semantic Versioning 2.0.0](https://semver.org/) and communicate changes to the
+documented public API:
+
+- Patch releases contain backward-compatible defect fixes, documentation
+  corrections, and internal improvements. A patch may correct behavior that
+  contradicts the documented contract, and the release notes will identify the
+  affected case.
+- Minor releases add backward-compatible functionality and may deprecate public
+  API. They do not remove or incompatibly change documented public API.
+- Major releases may remove deprecated API or make other incompatible public
+  contract changes.
+
+A public API deprecation will appear in the documentation and changelog and
+will emit a warning where a runtime warning is practical. Removal waits for a
+later major release and will have at least one minor release of prior
+deprecation.
+
+Exact error wording, object representations, private names, submodule layout,
+internal algorithms, allocation strategy, benchmark timings, and undocumented
+side effects may change in any release. Changes to these details must still
+preserve the documented results and ownership rules.
+
+## Archive compatibility
+
+Archive format versions are independent of package versions. Format version 1
+is the stable persistence contract for 1.x:
+
+- Every 1.x release will continue reading and writing valid format-version-1
+  archives.
+- A mandatory replacement for format version 1 requires a major package
+  release and a documented migration path.
+- A new archive format may appear during 1.x only as an explicit opt-in while
+  format-version-1 read and write support remains available.
+- An older reader is not expected to understand an arbitrary newer archive
+  format. Compatibility is a newer-reader promise, not a future-format promise
+  for already published code.
+
+Unversioned archives containing only `vectors` and `metadata` remain outside
+this contract because they do not record dimensions or normalization semantics.
+
+Format compatibility does not make every Python metadata object portable.
+Opaque metadata uses pickle-backed NumPy object arrays and may depend on the
+same application classes, import paths, and compatible dependencies being
+available when it is opened. Archives must come from a trusted source. The
+library does not treat untrusted pickle data as safe input.
+
+## Python and NumPy support
+
+The Python versions listed in package metadata are tested in CI. The declared
+minimum NumPy version is tested with the oldest supported Python version.
+
+Support for a Python or NumPy version may be removed in a minor release after
+its relevant upstream support window or ecosystem compatibility makes continued
+testing impractical. Such a change will be made in package metadata and called
+out in the changelog and release notes. Dropping a runtime version does not
+remove callable API from applications running on a supported interpreter.
+
+## Performance expectations
+
+Search results, metric definitions, threshold behavior, deterministic tie
+ordering, and filtered-row semantics are public behavior. The implementation
+may change how it produces those results.
+
+Published benchmark measurements are reference evidence, not latency or memory
+guarantees. Hardware, NumPy, BLAS, process load, vector shape, and metadata all
+affect observed performance. Structural regressions such as repeated full-store
+copies during ordinary ingestion or unnecessary unfiltered search copies remain
+covered by tests rather than fixed wall-clock promises.

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

@@ -71,10 +71,11 @@ payload objects by reference.
 Row retrieval deliberately treats vectors and metadata differently:
 
 ```python
-vector, payload = store.get(0)
-
-vector[0] = 10.0           # Independent copy; the store is unchanged.
-payload["reviewed"] = True  # Shared application metadata object.
+row = store.get(0)
+if row is not None:
+    vector, payload = row
+    vector[0] = 10.0           # Independent copy; the store is unchanged.
+    payload["reviewed"] = True  # Shared application metadata object.
 ```
 
 Vectors have one uniform NumPy representation, so copying a single row gives
@@ -177,6 +178,15 @@ 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. A relative path is anchored to the current
+working directory when `save(path)` or `open(path)` binds it. The public
+`file_path` is therefore absolute, and later working-directory changes do not
+redirect pathless saves or reloads. Symlinks and `..` components are not
+canonicalized.
+
 The generic parameter still describes application metadata. It can be kept
 when useful:
 
@@ -284,6 +294,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.