[codex] Close API parity gaps before release by Fieldnote-Echo · Pull Request #176 · Fieldnote-Echo/ordvec

Fieldnote-Echo · 2026-06-04T05:34:52Z

Summary

add Python Bitmap.search_subset(query, doc_ids, k) parity with Rust Bitmap::search_subset
add C ABI metadata-only probing via ordvec_index_probe(path, flags, info_out) backed by Rust probe_index_metadata()
add Go Probe(path) (Info, error) parity and test probe/load metadata equivalence
document C/Go probe-vs-load semantics plus ABI v1 UTF-8 path requirements in Rust docs, generated header, and C API docs
expose named Go capability constants and assert loaded index capability bits
align CI's pinned cbindgen version with the generated header banner

Tracking

Track metadata-only probe parity for C ABI and Go wrapper #175 is completed by this PR and closed

Validation

cbindgen ordvec-ffi --config ordvec-ffi/cbindgen.toml --output ordvec-ffi/include/ordvec.h --verify
cargo build -p ordvec-ffi
cargo test -p ordvec-ffi
cargo build -p ordvec-ffi --release
env GOCACHE=/tmp/ordvec-go-build go test -count=1 ./... 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_bitmap.py
cargo clippy -p ordvec-ffi --all-targets -- -D warnings
git diff --check

Stacked on #174.

Signed-off-by: Nelson Spence <nelson@projectnavi.ai>

Fieldnote-Echo · 2026-06-04T05:34:58Z

/agentic_review

qodo-code-review · 2026-06-04T05:35:03Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0)

1. ~~No C ABI probe entrypoint~~ ✓ Resolved 📎 Requirement gap ⛨ Security

Description

The C ABI still only exposes ordvec_index_load plus ordvec_index_info (which requires a loaded
handle), and the Go wrapper similarly only offers Load(path) followed by Index.Info(); neither
layer provides a metadata-only probe function. This fails the requirement for allocation-resistant
metadata inspection that can read on-disk index metadata without fully loading an index handle.

Code

ordvec-ffi/include/ordvec.h[R183-187]

+ * `path` must be a non-null, NUL-terminated, valid UTF-8 C string. `out`
+ * must be non-null and point to writable memory for one `ordvec_index_t *`.
 */
ordvec_status_t ordvec_index_load(const char *path, uint64_t flags, ordvec_index_t **out);

Evidence

PR Compliance requires a dedicated metadata-only probe API that returns index metadata without
calling ordvec_index_load. The exported C header shows only ordvec_index_load and
ordvec_index_info, and ordvec_index_info explicitly operates on a handle returned by
ordvec_index_load, meaning C metadata inspection still requires a full load. The Go wrapper
mirrors this flow by defining Load(path) that calls ordvec_index_load and then obtains Info
via ordvec_index_info on the loaded index, and it does not provide any Probe(path) (or
equivalent) function to inspect metadata without loading.

C ABI exposes a metadata-only probe entry point (parity with Rust metadata probing)
ordvec-ffi/include/ordvec.h[178-206]
ordvec-ffi/src/lib.rs[639-731]
ordvec-go/ordvec.go[179-201]
ordvec-go/ordvec.go[220-249]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
PR Compliance requires adding a metadata-only probe entry point to the C ABI and exposing an equivalent metadata-only probe API in the Go wrapper so callers can inspect on-disk index metadata without calling `ordvec_index_load` / loading a full index handle.

## Issue Context
Today, the C ABI surface in `ordvec.h` only allows metadata access via `ordvec_index_info`, which requires first obtaining an index handle via `ordvec_index_load`. The Go API currently exposes `Load(path)` which calls the C ABI `ordvec_index_load` and then reads metadata via `ordvec_index_info` on the loaded handle, with no `Probe(path)` API for metadata inspection without loading.

## Fix Focus Areas
- ordvec-ffi/include/ordvec.h[168-224]
- ordvec-ffi/src/lib.rs[639-731]
- ordvec-go/ordvec.go[179-250]
- ordvec-go/ordvec_test.go[1-140]
- docs/c-api.md[96-160]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. ~~C docs omit probe-vs-load~~ ✓ Resolved 📎 Requirement gap ⚙ Maintainability

Description

The C API documentation update adds UTF-8 requirements for ordvec_index_load but still does not
clarify probe-vs-load semantics for metadata inspection. This leaves the required documentation
distinction incomplete.

Code

docs/c-api.md[R119-124]

+`ordvec_index_load` takes a non-null, NUL-terminated, valid UTF-8 path string.
+Invalid UTF-8 paths return `ORDVEC_STATUS_BAD_ARGUMENT` in ABI v1.
+
Rows are internal row ordinals. ABI v1 has no external ID map:
`ordvec_hit_t.id` is always equal to `ordvec_hit_t.row_id` widened to
`uint64_t`.

Evidence

PR Compliance ID 4 requires documentation to clarify probe-vs-load semantics in addition to UTF-8
path expectations. The updated C API doc text only specifies UTF-8 behavior for ordvec_index_load
and provides no probe-vs-load guidance for metadata inspection workflows.

Documentation clarifies probe-vs-load semantics and UTF-8 path behavior
docs/c-api.md[96-124]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Docs must clearly distinguish metadata-only probing vs full index load semantics (what is read, what is not loaded, intended use) and cover UTF-8 path behavior for the relevant APIs.

## Issue Context
The current C API doc section under "ABI Contracts" documents UTF-8 path requirements for `ordvec_index_load`, but does not explain how a caller should do metadata-only inspection (or that it is not available in the C ABI) versus full loading.

## Fix Focus Areas
- docs/c-api.md[96-160]
- ordvec-ffi/include/ordvec.h[178-206]
- ordvec-go/ordvec.go[179-201]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

gemini-code-assist

Code Review

This pull request documents UTF-8 requirements for ordvec_index_load in the C API, introduces capability constants and corresponding tests in the Go bindings, and implements a new search_subset method for the Bitmap class in the Python bindings along with comprehensive tests. The feedback suggests renaming a shadowed variable ids in the Rust-Python binding code to improve readability and avoid confusion.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

codecov · 2026-06-04T05:36:27Z

Codecov Report

❌ Patch coverage is 88.88889% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
ordvec-python/src/lib.rs	88.88%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

qodo-code-review · 2026-06-04T14:41:04Z

Review Summary by Qodo

Close API parity gaps before release

✨ Enhancement 📝 Documentation

Walkthroughs

Description

• Add Python Bitmap.search_subset() method for querying document subsets
• Document UTF-8 path requirement in C API and Rust safety docs
• Expose named Go capability constants and validate loaded capabilities
• Update CI pinned cbindgen version from 0.29.2 to 0.29.3

Diagram

flowchart LR
  A["Python Bitmap API"] -->|"add search_subset method"| B["Subset Search Support"]
  C["C API Documentation"] -->|"clarify UTF-8 requirement"| D["Path Safety Docs"]
  E["Go Constants"] -->|"expose capability flags"| F["Capability Validation"]
  G["CI Configuration"] -->|"update cbindgen"| H["Header Generation"]

File Changes

1. ordvec-python/src/lib.rs ✨ Enhancement +27/-0

Add Python Bitmap subset search method

• Implement search_subset() method for Bitmap to query caller-supplied document ID subsets
• Support unsorted and duplicate doc IDs with independent scoring
• Validate doc IDs are within range and query vector dimensions match
• Return scores and IDs as PyArrays matching Rust core tie-breaking policy

ordvec-python/src/lib.rs

2. ordvec-python/tests/test_bitmap.py 🧪 Tests +61/-0

Add comprehensive search_subset tests

• Add test verifying search_subset() matches full search when candidates equal all documents
• Add test for unsorted duplicates and tie-breaking by row ID
• Add validation tests for doc ID bounds, types, and query vector dimensions
• Add test for strided int64 doc IDs and k-value capping

ordvec-python/tests/test_bitmap.py

3. ordvec-ffi/src/lib.rs 📝 Documentation +2/-2

Document UTF-8 path requirement in safety docs

• Update ordvec_index_load() safety documentation to specify valid UTF-8 requirement for path
• Clarify that path must be non-null, NUL-terminated, and valid UTF-8

ordvec-ffi/src/lib.rs

View more (5)

4. ordvec-ffi/include/ordvec.h 📝 Documentation +3/-3

Update generated header and path documentation
• Update generated header cbindgen version from 0.29.2 to 0.29.3
• Update ordvec_index_load() documentation to specify valid UTF-8 path requirement
ordvec-ffi/include/ordvec.h

5. docs/c-api.md 📝 Documentation +3/-0

Document C API UTF-8 path requirement

• Document that ordvec_index_load() requires valid UTF-8 path strings
• Specify that invalid UTF-8 paths return ORDVEC_STATUS_BAD_ARGUMENT in ABI v1

docs/c-api.md

6. ordvec-go/ordvec.go ✨ Enhancement +7/-0

Expose named Go capability constants

• Expose named capability constants: CapFullSearch, CapSubsetSearch, CapStats,
 CapIDEqualsRowID
• Map Go constants to underlying C capability flag values

ordvec-go/ordvec.go

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

Assert loaded index capability bits

• Add assertion to validate loaded RankQuant index has all expected capability bits set
• Check that info.Capabilities includes full search, subset search, stats, and ID-equals-row-ID
 flags

ordvec-go/ordvec_test.go

8. .github/workflows/ci.yml ⚙️ Configuration changes +1/-1

Update cbindgen version in CI
• Update pinned cbindgen version from 0.29.2 to 0.29.3 in CI workflow
.github/workflows/ci.yml

qodo-code-review · 2026-06-04T14:41:05Z

Code review by qodo was updated up to the latest commit 546792c

Signed-off-by: Nelson Spence <nelson@projectnavi.ai>

Fieldnote-Echo · 2026-06-04T14:49:33Z

Addressed the remaining review threads in 3321054.

What changed:

Renamed the Python Bitmap.search_subset returned ids binding to out_ids to avoid shadowing the borrowed candidate IDs.
Added C ABI metadata-only probing as ordvec_index_probe(path, flags, info_out), backed by core probe_index_metadata so it validates header/declared shape/payload byte count/exact file length without loading payload rows into a handle.
Added Go Probe(path) (Info, error) and a shared C-info conversion path so probed and loaded metadata stay aligned.
Documented probe-vs-load semantics and UTF-8 path behavior in docs/c-api.md and regenerated ordvec-ffi/include/ordvec.h.
Extended FFI unit coverage, linked C smoke coverage, and Go tests for probe/load metadata parity.

Validation:

cbindgen ordvec-ffi --config ordvec-ffi/cbindgen.toml --output ordvec-ffi/include/ordvec.h --verify
cargo build -p ordvec-ffi
cargo test -p ordvec-ffi
cargo build -p ordvec-ffi --release
env GOCACHE=/tmp/ordvec-go-build go test -count=1 ./... 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_bitmap.py
cargo clippy -p ordvec-ffi --all-targets -- -D warnings
git diff --check

Close API parity gaps before release

546792c

Signed-off-by: Nelson Spence <nelson@projectnavi.ai>

gemini-code-assist Bot reviewed Jun 4, 2026

View reviewed changes

Comment thread ordvec-python/src/lib.rs Outdated

qodo-code-review Bot reviewed Jun 4, 2026

View reviewed changes

Comment thread ordvec-ffi/include/ordvec.h

Fieldnote-Echo mentioned this pull request Jun 4, 2026

[codex] Harden release security gates #177

Open

Fieldnote-Echo marked this pull request as ready for review June 4, 2026 14:40

Fieldnote-Echo requested a review from project-navi-bot as a code owner June 4, 2026 14:40

Add metadata probe parity to FFI and Go

3321054

Signed-off-by: Nelson Spence <nelson@projectnavi.ai>

Fieldnote-Echo mentioned this pull request Jun 4, 2026

Track metadata-only probe parity for C ABI and Go wrapper #175

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[codex] Close API parity gaps before release#176

[codex] Close API parity gaps before release#176
Fieldnote-Echo wants to merge 2 commits into
codex/release-version-parityfrom
codex/api-parity-release-audit

Fieldnote-Echo commented Jun 4, 2026 •

edited

Loading

Uh oh!

Fieldnote-Echo commented Jun 4, 2026

Uh oh!

qodo-code-review Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

codecov Bot commented Jun 4, 2026

Uh oh!

Uh oh!

qodo-code-review Bot commented Jun 4, 2026

Uh oh!

qodo-code-review Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

Fieldnote-Echo commented Jun 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Fieldnote-Echo commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tracking

Validation

Uh oh!

Fieldnote-Echo commented Jun 4, 2026

Uh oh!

qodo-code-review Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

codecov Bot commented Jun 4, 2026

Codecov Report

Uh oh!

Uh oh!

qodo-code-review Bot commented Jun 4, 2026

Review Summary by Qodo

Walkthroughs

File Changes

Uh oh!

qodo-code-review Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Fieldnote-Echo commented Jun 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Fieldnote-Echo commented Jun 4, 2026 •

edited

Loading

qodo-code-review Bot commented Jun 4, 2026 •

edited

Loading

qodo-code-review Bot commented Jun 4, 2026 •

edited

Loading