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

numpy_vector_store-0.7.1/.github/actionlint.yaml

@@ -0,0 +1,4 @@
+# Blacksmith uses ephemeral runners registered through GitHub's self-hosted API.
+self-hosted-runner:
+  labels:
+    - blacksmith-4vcpu-ubuntu-2404

numpy_vector_store-0.7.1/.github/workflows/checks.yml

@@ -0,0 +1,233 @@
+name: Checks
+
+on:
+  workflow_call:
+    inputs:
+      release-tag:
+        description: Optional v-prefixed tag that must match the distributions
+        required: false
+        type: string
+        default: ""
+    outputs:
+      distributions-artifact-id:
+        description: Artifact ID for the verified wheel and source distribution
+        value: ${{ jobs.distributions.outputs.artifact-id }}
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: checks-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Lint, format, and type-check
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.13.7"
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install project dependencies
+        run: uv sync --locked --group dev
+
+      - name: Run Ruff lint checks
+        run: uv run --locked ruff check .
+
+      - name: Check Ruff formatting
+        run: uv run --locked ruff format --check .
+
+      - name: Run mypy
+        run: uv run --locked mypy src/ benchmarks/ tools/
+
+  tests:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.13.7"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install project dependencies
+        run: uv sync --locked --group dev
+
+      - name: Run tests
+        run: uv run --locked pytest
+
+  windows:
+    name: Test Windows on Python 3.13
+    runs-on: windows-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.13.7"
+          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: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.13.7"
+          python-version: "3.11"
+          enable-cache: true
+
+      - name: Run tests with the minimum NumPy version
+        run: >-
+          uv run
+          --isolated
+          --no-project
+          --python 3.11
+          --with-editable .
+          --with numpy==1.23.2
+          --with pytest==8.4.2
+          python -m pytest
+
+  distributions:
+    name: Build and test distributions
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+    outputs:
+      artifact-id: ${{ steps.upload.outputs.artifact-id }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.13.7"
+          python-version: "3.11"
+          enable-cache: true
+
+      - name: Build wheel and source distribution
+        run: uv build --out-dir dist
+
+      - name: Verify release versions
+        env:
+          RELEASE_TAG: ${{ inputs.release-tag }}
+        run: |
+          if [[ -n "$RELEASE_TAG" ]]; then
+            uv run --locked python tools/verify_release_version.py --tag "$RELEASE_TAG"
+          else
+            uv run --locked python tools/verify_release_version.py
+          fi
+
+      - name: Check distribution metadata
+        run: uvx --from twine==7.0.0 twine check --strict dist/*
+
+      - name: Test installed wheel
+        run: >-
+          uv run
+          --isolated
+          --no-project
+          --python 3.11
+          --with ./dist/*.whl
+          python tools/verify_installed_distribution.py
+
+      - name: Test installed source distribution
+        run: >-
+          uv run
+          --isolated
+          --no-project
+          --python 3.11
+          --with ./dist/*.tar.gz
+          python tools/verify_installed_distribution.py
+
+      - name: Upload verified distributions
+        id: upload
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: python-package-distributions-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 7
+          compression-level: 0

numpy_vector_store-0.7.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types:
+      - published
+
+concurrency:
+  group: publish-pypi
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate release
+    uses: ./.github/workflows/checks.yml
+    with:
+      release-tag: ${{ github.event.release.tag_name }}
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/numpy-vector-store
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          artifact-ids: ${{ needs.validate.outputs.distributions-artifact-id }}
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+        with:
+          packages-dir: dist/

numpy_vector_store-0.7.1/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,40 @@
+name: Publish to TestPyPI
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: publish-testpypi
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate release candidate
+    uses: ./.github/workflows/checks.yml
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/numpy-vector-store
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          artifact-ids: ${{ needs.validate.outputs.distributions-artifact-id }}
+          path: dist
+
+      - name: Publish package distributions to TestPyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+        with:
+          packages-dir: dist/
+          repository-url: https://test.pypi.org/legacy/

{numpy_vector_store-0.6.0 → numpy_vector_store-0.7.1}/.gitignore

@@ -153,6 +153,8 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/.venv-docs/
+/.cache/zensical/
 
 # mypy
 .mypy_cache/

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

@@ -1,10 +1,207 @@
+<!-- --8<-- [start:introduction] -->
+
 # Changelog
 
 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).
+[GitHub releases page](https://github.com/tvr-works/numpy-vector-store/releases).
+
+<!-- --8<-- [end:introduction] -->
+
+## 0.7.1 - 2026-11-13
+
+This patch release corrects two search edge cases without changing the public
+API, runtime requirements, or archive format. It also includes the documentation,
+package-presentation, and release-workflow improvements merged since 0.7.0.
+
+Most applications can upgrade without code changes or data migration. The
+observable corrections are that very small normalized Euclidean distances no
+longer collapse to zero, and valid row filters containing different integer
+types are accepted.
+
+### Search correctness
+
+- Accumulate normalized Euclidean squared differences in `float64` before
+  taking their square root. Previously, a small difference could be represented
+  in `float32` while its square was too small to represent, making a nonzero
+  distance appear to be zero.
+- Preserve nearest-row ordering, `top_k` selection, and zero-distance threshold
+  filtering for these cases, both with and without `within_rows`. Vector
+  storage remains `float32`; raw Euclidean, cosine, and dot-product calculation
+  paths are unchanged.
+- Accept mixed Python and NumPy integer row filters such as
+  `[0, np.uint64(1)]`. NumPy can infer a floating-point array for mixed signed
+  and unsigned integers; validation now retains the original values when that
+  conversion would erase their integer types.
+- Keep bulk validation for ordinary integer lists, tuples, and ranges, and
+  preserve the native NumPy integer-array fast path. Custom integer-index
+  objects continue to use the existing per-element validation fallback.
+- Continue rejecting booleans, floating-point indexes, malformed shapes,
+  duplicate rows, and out-of-range indexes. Validation remains independent of
+  whether the store is empty.
+
+### Documentation and package presentation
+
+- Add the searchable [documentation website](https://vectors.tvr.works/) with
+  getting-started, search/filtering, persistence, ownership, deployment,
+  performance, API-reference, and compatibility guidance.
+- Clarify the README's small-to-medium, in-process search positioning. Explain
+  deployment with an archive shipped alongside application code, where each
+  worker or replica loads its own in-memory store without a separate vector
+  database or shared-write coordination.
+- Update package project links to the existing repository's new
+  `tvr-works/numpy-vector-store` location and add the documentation URL.
+  Distribution and import names remain `numpy-vector-store` and
+  `numpy_vector_store`.
+- Keep documentation source, generated output, build tools, and the independent
+  docs environment out of the source distribution. Wheels remain package-only;
+  documentation tools add no runtime dependency.
+- Build the public reference and executable guide examples against an exact,
+  verified published wheel in a separate locked environment. Development
+  changes and release preparation no longer replace the released API reference.
+  Prepared changelog entries stay out of the public site until its edition is
+  advanced after publication.
+
+### Release validation and publishing
+
+- Build distributions once in the validation workflow, check their versions and
+  metadata, and smoke-test clean wheel and source-distribution installations.
+  The publishing job downloads that verified artifact by its immutable ID
+  rather than rebuilding it with publishing credentials available.
+- Pin the Hatchling build backend and publishing/validation tool revisions.
+  Retain the supported Python matrix, Windows coverage, and minimum-NumPy check.
+- Configure environment-bound Trusted Publishers for the organization-owned
+  repository and document post-upload provenance and installation checks.
+  Production cutover is confirmed only after an authorized upload passes those
+  checks; the new configuration is not treated as verified merely because it
+  is present.
+- Add independent documentation CI that checks the built site and runs rendered
+  examples. Pages publication requires successful docs CI for the exact source
+  commit, and branch previews are marked not to be indexed.
+
+### Upgrade notes
+
+- Continue supporting Python 3.11 through 3.14 and NumPy 1.23.2 or newer.
+- Keep the existing methods, arguments, result types, and input-error categories.
+- Continue reading and writing trusted format-version-1 archives without
+  conversion. Opaque metadata still uses pickle-backed object arrays; do not
+  open untrusted archives.
+- No new feature family, API removal, runtime dependency, or archive migration
+  is introduced. These are corrections within the existing 0.7 contract, not
+  the separate 1.0 stability declaration.
+
+<!-- --8<-- [start:published] -->
 
-## 0.6.0 - 2026-08-21
+## 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
@@ -431,3 +628,5 @@ intentionally break valid existing usage or change the `.npz` archive format.
 - Environments using NumPy 1.20 must upgrade to NumPy 1.21.3 or newer.
 - Inputs that previously produced `nan`, `inf`, or unreliable rankings now
   raise `ValueError` instead.
+
+<!-- --8<-- [end:published] -->

numpy_vector_store-0.7.1/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.