docs/tests: pin concurrency contract across Python, C, and Go

[Fieldnote-Echo]

Summary

• Document the read-concurrent, mutation-exclusive concurrency contract in the README, Python package docs, C ABI docs, and Go package docs.
• Add deterministic Python coverage for repeated concurrent RankQuant.search_asymmetric calls against shared read-only inputs.
• Add a Go smoke test covering concurrent Search/Info calls racing with Close, including post-close ErrClosed behavior.

Deferred Follow-Up

Opened #113 for optional safe_copy=True input isolation for GIL-releasing Python methods. This PR does not add API, locking, lease/refcount, or input-copy behavior.

Validation

• cargo fmt --all --check
• cargo test
• cargo test -p ordvec-ffi
• cargo clippy --workspace --all-targets -- -D warnings
• cargo build -p ordvec-ffi --release
• go test ./...
• python -m maturin develop --manifest-path ordvec-python/Cargo.toml attempted on system Python; blocked because maturin is not installed there
• uv run --with maturin==1.13.3 --with pytest==9.0.3 --with numpy==2.4.6 ... to run maturin develop and pytest ordvec-python/tests in one temporary env
• GOTOOLCHAIN=go1.26.3 go test -race ./...

Note: the local /usr/bin/go reports go1.26.3-X:nodwarf5 and fails even a trivial race build (go test -race -run '^$' errors) with runtime/race: package testmain: cannot find package. For the race validation above, I forced the official upstream go1.26.3 toolchain through GOTOOLCHAIN=go1.26.3; the repo race tests then passed.

[gemini-code-assist]

Code Review

This pull request updates the documentation and adds tests to clarify and verify the concurrency model of ordvec across its Python, Go, and C APIs, establishing a read-concurrent, mutation-exclusive contract. In the Go test suite, a potential issue was identified where calling t.Fatalf on a Close failure could prematurely terminate the test while background worker goroutines are still running, which can be resolved by using t.Errorf instead.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Review Summary by Qodo

Document and test concurrency contract across Python, C, and Go

📝 Documentation 🧪 Tests

Walkthroughs

Description

• Document read-concurrent, mutation-exclusive concurrency contract across Python, C, and Go
• Add deterministic Python concurrent search test with ThreadPoolExecutor
• Add Go smoke test for concurrent Search/Info racing with Close
• Clarify input array mutation restrictions in all language bindings

Diagram

flowchart LR
  A["Concurrency Contract"] --> B["Python Docs"]
  A --> C["C ABI Docs"]
  A --> D["Go Package Docs"]
  A --> E["README"]
  B --> F["Python Test"]
  D --> G["Go Test"]
  F["Python Test"] -.-> H["ThreadPoolExecutor concurrent searches"]
  G["Go Test"] -.-> I["Concurrent Search/Info with Close"]

Loading

File Changes

1. ordvec-python/python/ordvec/__init__.py 📝 Documentation +9/-7

Clarify Python threading and GIL-release contract

• Clarified threading contract as read-concurrent, mutation-exclusive
• Added explicit mention that add releases GIL while mutating index
• Emphasized that mutable index operations must be treated as exclusive
• Maintained existing guidance on input array read-in-place behavior

ordvec-python/python/ordvec/init.py

---

2. ordvec-python/tests/test_rank_quant.py 🧪 Tests +21/-0

Add concurrent search determinism test

• Added ThreadPoolExecutor import for concurrent testing
• Added new test test_search_asymmetric_read_concurrent_results_match_baseline
• Test spawns 4 workers running 40 concurrent search operations
• Validates that concurrent searches return deterministic results matching baseline

ordvec-python/tests/test_rank_quant.py

---

3. ordvec-go/doc.go 📝 Documentation +9/-0

Add Go package documentation with concurrency contract

• New file documenting Go package concurrency contract
• Specifies concurrent Search and Info calls are allowed
• Documents Close serialization against Search and Info
• Clarifies ErrClosed behavior post-Close
• Notes that Search borrows caller-owned slices without copying

ordvec-go/doc.go

---

View more (3)

4. ordvec-go/ordvec_test.go 🧪 Tests +64/-0

Add Go concurrent Search/Info/Close race test

• Added imports for fmt and sync packages
• Added new test TestConcurrentSearchInfoAndClose
• Test spawns 8 workers performing 64 concurrent iterations
• Workers race Search and Info calls against Close operation
• Validates ErrClosed behavior and absence of panics or unexpected errors

ordvec-go/ordvec_test.go

---

5. README.md 📝 Documentation +15/-0

Add concurrency contract section to README

• Added new "Threading / concurrency" section
• Documented read-concurrent, mutation-exclusive concurrency model
• Specified Python GIL-release behavior and input mutation restrictions
• Documented C ABI concurrent search/info allowance
• Documented Go wrapper Close serialization and ErrClosed behavior

README.md

---

6. docs/c-api.md 📝 Documentation +8/-4

Expand C API threading documentation with buffer borrowing

• Expanded threading section with explicit concurrency details
• Clarified that concurrent ordvec_index_search and ordvec_index_info are allowed
• Added note that Search borrows caller-owned buffers in place
• Emphasized mutation exclusivity and ordvec_index_free serialization requirements
• Clarified undefined behavior for use-after-free and double-free

docs/c-api.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

[Copilot]

Pull request overview

This PR documents the read-concurrent, mutation-exclusive threading contract across user-facing docs and adds concurrency-focused tests for Python and Go bindings.

Changes:

• Adds concurrency/threading guidance to README, Python package docs, C ABI docs, and Go package docs.
• Adds Python coverage for concurrent RankQuant.search_asymmetric calls on shared read-only inputs.
• Adds a Go smoke test for concurrent Search/Info behavior around Close.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Adds top-level threading/concurrency contract summary.
ordvec-python/python/ordvec/__init__.py	Updates Python package threading docs.
ordvec-python/tests/test_rank_quant.py	Adds concurrent read-only search_asymmetric regression coverage.
ordvec-go/doc.go	Adds Go package documentation for concurrent use and Close.
ordvec-go/ordvec_test.go	Adds Go concurrency smoke test around Search, Info, and Close.
docs/c-api.md	Expands C ABI threading documentation for search/info/free and borrowed buffers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Fieldnote-Echo]

Rebased #114 onto current main after #163 merged and addressed the remaining active review threads in 8cc9ae2.

Changes:

• Python package threading docs now explicitly include search_asymmetric_subset and its caller-owned candidate array in the no-concurrent-mutation contract.
• Go TestConcurrentSearchInfoAndClose now waits for at least one successful pre-close Search and one successful pre-close Info before invoking Close, while still joining workers and accepting only nil/ErrClosed.
• The existing Close cleanup path uses t.Errorf and still reaches wg.Wait().

Validation:

• cargo fmt --all --check
• git diff --check
• cargo build -p ordvec-ffi --release
• GOCACHE=/tmp/ordvec-gocache GOMODCACHE=/tmp/ordvec-gomodcache go test ./... from ordvec-go/
• VIRTUAL_ENV=/home/ndspence/GitHub/ordvec/ordvec-python/.venv PATH=/home/ndspence/GitHub/ordvec/ordvec-python/.venv/bin:$PATH maturin develop -m ordvec-python/Cargo.toml
• VIRTUAL_ENV=/home/ndspence/GitHub/ordvec/ordvec-python/.venv PATH=/home/ndspence/GitHub/ordvec/ordvec-python/.venv/bin:$PATH python -m pytest ordvec-python/tests/test_rank_quant.py -k concurrent

The prior coverage failure on the pre-remediation run was an Intel SDE download 403 before tests ran (curl: (22) The requested URL returned error: 403).

[Fieldnote-Echo]

/agentic_review

[qodo-code-review]

Code Review by Qodo

Sorry, something went wrong

We weren't able to complete the code review on our side. Please try again