refactor: OrdVec ontology rebrand

[Fieldnote-Echo]

OrdVec ontology rebrand

Drops the redundant Index suffix so the public types read as members of the ordvec family, and flattens the module layout to match. Pre-release polish — done now (private, pre-0.2) so the published vocabulary is clean before the paper points people at it.

Public API

Before	After
ordvec::RankIndex	ordvec::Rank
ordvec::RankQuantIndex	ordvec::RankQuant
ordvec::BitmapIndex	ordvec::Bitmap
ordvec::SignBitmapIndex	ordvec::SignBitmap
ordvec::MultiBucketBitmapIndex (experimental)	ordvec::MultiBucketBitmap
ordvec::RankQuantFastscanIndex (doc-hidden)	ordvec::RankQuantFastscan

use ordvec::{Rank, RankQuant, Bitmap, SignBitmap};

Compatibility

Deprecated pub type *Index = *; aliases at the crate root — code importing the root names (use ordvec::RankIndex;) keeps compiling, with a deprecation warning pointing at the new name. Not preserved: the old ordvec::rank_index::* module path is removed by the flatten, so module-path imports (use ordvec::rank_index::RankQuantIndex;) must move to the crate-root names. That's an accepted pre-release break — the crate is unpublished (0.1.0 → 0.2.0), so there are no crates.io consumers, and the point of the rebrand is to retire that module path before the vocabulary is published. All internal code is on the new names, enforced: the -D warnings build fails on any internal use of a deprecated alias. tests/deprecated_aliases.rs proves the root aliases still resolve. (Validated: ordvec::RankIndex emits warning: use of deprecated type alias ordvec::RankIndex: renamed to Rank.)

Module layout

src/rank_index/ flattened into src/ — the Rank index type now lives in rank.rs beside the rank-math primitives (ordvec::rank module + ordvec::Rank type, the one defensible pair). tests/rank_index/ → tests/index/.

Deliberately unchanged

• Method names (search_asymmetric*, top_m_candidates*, new, add, load, write) — already legible.
• File magics (.tvr/.tvrq/.tvbm/.tvsb) — persistence formats, not branding; renaming would be pure compatibility harm.
• rank_io.rs kept (not renamed to io.rs): it's the persistence module, not an Index-branded type, and renaming would churn the fuzz/ targets referencing ordvec::rank_io::load_* for no ontology gain.

Verification

• RUSTFLAGS="-D warnings" cargo build (+ --features experimental), clippy --all-targets --all-features -- -D warnings, cargo fmt --all --check — all clean
• cargo test 80, --features experimental 87 (+ the alias smoke test); cargo +1.89.0 build (MSRV); cargo build --locked
• Grep gate: no *Index name survives in real src/ code (only the deprecated aliases, CHANGELOG note, smoke test, and historical docs/)
• Bumped to 0.2.0 + CHANGELOG

[qodo-code-review]

Review Summary by Qodo

Rebrand ordvec ontology: drop Index suffix and flatten module layout for 0.2.0

✨ Enhancement

Walkthroughs

Description

• **Ontology rebrand**: Removes redundant Index suffix from all public types for cleaner API
  vocabulary (RankIndex → Rank, RankQuantIndex → RankQuant, BitmapIndex → Bitmap,
  SignBitmapIndex → SignBitmap, MultiBucketBitmapIndex → MultiBucketBitmap,
  RankQuantFastscanIndex → RankQuantFastscan)
• **Module flattening**: Collapses src/rank_index/ into src/ root level, consolidating
  rank-cosine index logic into rank.rs alongside rank-math primitives; test structure reorganized
  from tests/rank_index/ to tests/index/
• **Backward compatibility**: Provides deprecated pub type *Index = *; aliases at crate root with
  deprecation warnings; internal code enforced to use new names via -D warnings build flag
• **Verification**: Includes new smoke test file tests/deprecated_aliases.rs proving old names
  still compile; all 80+ tests pass with experimental features
• **Version bump**: Incremented to 0.2.0 with comprehensive CHANGELOG entry documenting all
  breaking changes and migration path
• **Documentation updates**: README, RANK_MODES.md, and ALTERNATIVES_CONSIDERED.md updated to
  reflect new type names and module layout

Diagram

flowchart LR
  A["Old API<br/>RankIndex, RankQuantIndex<br/>BitmapIndex, SignBitmapIndex"] -->|"Rebrand"| B["New API<br/>Rank, RankQuant<br/>Bitmap, SignBitmap"]
  C["src/rank_index/<br/>submodules"] -->|"Flatten"| D["src/<br/>root level"]
  E["Deprecated aliases<br/>with warnings"] -->|"Backward compat"| F["External code<br/>keeps compiling"]
  B --> G["0.2.0 release"]
  D --> G
  F --> G

Loading

File Changes

1. examples/bench_rank.rs Refactoring +28/-28

Update benchmark example to use rebranded type names

• Updated all type names from *Index suffix to new names: RankIndex → Rank, RankQuantIndex →
 RankQuant, BitmapIndex → Bitmap, SignBitmapIndex → SignBitmap, RankQuantFastscanIndex →
 RankQuantFastscan
• Updated import paths from ordvec::rank_index::* to ordvec::* for the flattened module layout
• Updated documentation comments and string labels to reflect new type names

examples/bench_rank.rs

---

2. src/rank.rs ✨ Enhancement +262/-10

Add full-precision Rank index implementation to rank module

• Expanded module documentation to clarify the dual purpose: math primitives and the Rank index
 type
• Added full implementation of the Rank struct with new, add, search, search_asymmetric,
 len, is_empty, dim, bytes_per_vec, byte_size, swap_remove, write, and load methods
• Moved rank-cosine index logic from rank_index module into this file

src/rank.rs

---

3. src/sign_bitmap.rs Refactoring +21/-21

Rename SignBitmapIndex to SignBitmap

• Renamed SignBitmapIndex struct to SignBitmap throughout the file
• Updated documentation cross-references from BitmapIndex to Bitmap
• Updated internal comments referencing old module paths

src/sign_bitmap.rs

---

View more (25)

4. src/fastscan.rs Refactoring +22/-22

Rename RankQuantFastscanIndex to RankQuantFastscan

• Renamed RankQuantFastscanIndex struct to RankQuantFastscan
• Updated module documentation and cross-references to use new type names
• Changed import paths from super::* to crate::* for flattened module layout

src/fastscan.rs

---

5. tests/index/bitmap.rs Refactoring +16/-16

Update bitmap tests to use rebranded type names

• Renamed BitmapIndex to Bitmap and RankQuantIndex to RankQuant in all test code
• Updated file header comment to reflect new type names
• Updated all test function calls to use new type names

tests/index/bitmap.rs

---

6. tests/redteam_beta.rs Refactoring +16/-16

Update redteam_beta tests to use rebranded type names

• Renamed all index types: RankIndex → Rank, RankQuantIndex → RankQuant, SignBitmapIndex →
 SignBitmap
• Updated import paths from ordvec::rank_index::* to ordvec::*
• Updated documentation comments to reflect new names

tests/redteam_beta.rs

---

7. tests/redteam_alpha.rs Refactoring +17/-17

Update redteam_alpha tests to use rebranded type names

• Renamed BitmapIndex to Bitmap and MultiBucketBitmapIndex to MultiBucketBitmap
• Updated documentation comments and test descriptions to use new type names

tests/redteam_alpha.rs

---

8. src/rank_io.rs 📝 Documentation +14/-14

Update rank_io documentation to reference rebranded type names

• Updated documentation comments to reference new type names: Rank, RankQuant, Bitmap,
 SignBitmap
• Updated cross-references in function documentation from old names to new names

src/rank_io.rs

---

9. tests/index/fastscan.rs Refactoring +14/-14

Update fastscan tests to use rebranded type names

• Renamed RankQuantFastscanIndex to RankQuantFastscan and RankQuantIndex to RankQuant
• Updated file header comment to reflect new type names
• Updated all test code to use new type names

tests/index/fastscan.rs

---

10. src/quant.rs Refactoring +18/-22

Rename RankQuantIndex to RankQuant and flatten module paths

• Renamed RankQuantIndex struct to RankQuant
• Changed visibility modifiers from pub(super) to pub(crate) for struct fields
• Updated import paths from super::* to crate::* for flattened module layout
• Updated documentation comments to reference new type names

src/quant.rs

---

11. src/quant_kernels.rs Refactoring +10/-10

Update quant_kernels visibility and import paths

• Changed visibility modifiers from pub(super) to pub(crate) for kernel functions
• Updated import paths from super::* to crate::* for flattened module layout

src/quant_kernels.rs

---

12. src/lib.rs Refactoring +42/-14

Reorganize module structure and add deprecated aliases

• Reorganized module structure: moved rank_index submodules to crate root level
• Added new public exports for rebranded types: Rank, RankQuant, Bitmap, SignBitmap
• Added deprecated type aliases for backward compatibility: RankIndex, RankQuantIndex,
 BitmapIndex, SignBitmapIndex, MultiBucketBitmapIndex, RankQuantFastscanIndex
• Updated crate-level documentation to reference new type names

src/lib.rs

---

13. tests/index/main.rs Refactoring +16/-22

Update index tests main file for rebranded types

• Updated imports to use new type names: Rank, RankQuant, Bitmap, SignBitmap
• Renamed test module from index to rank to match new file structure
• Updated documentation comments to reference new module layout

tests/index/main.rs

---

14. src/util.rs Refactoring +6/-6

Update util module visibility to pub(crate)

• Changed visibility modifiers from pub(super) to pub(crate) for utility functions and types
• Updated documentation comments to reflect new visibility scope

src/util.rs

---

15. tests/index/rank.rs Refactoring +9/-9

Update rank tests to use rebranded Rank type

• Renamed RankIndex to Rank in all test code and imports
• Updated file header comment to reflect new type name
• Updated all test function calls to use new type name

tests/index/rank.rs

---

16. tests/index/quant.rs Refactoring +7/-7

Update quant tests to use rebranded RankQuant type

• Renamed RankQuantIndex to RankQuant in all test code and imports
• Updated file header comment to reflect new type name
• Updated all test function calls to use new type name

tests/index/quant.rs

---

17. src/bitmap.rs Refactoring +5/-5

Rename BitmapIndex to Bitmap and flatten module paths

• Renamed BitmapIndex struct to Bitmap
• Changed import paths from super::* to crate::* for flattened module layout
• Updated file header comment and documentation to reflect new type name

src/bitmap.rs

---

18. tests/index/multi_bucket.rs Refactoring +5/-5

Update multi_bucket tests to use rebranded type name

• Renamed MultiBucketBitmapIndex to MultiBucketBitmap in all test code and imports
• Updated file header comment to reflect new type name

tests/index/multi_bucket.rs

---

19. src/multi_bucket.rs Refactoring +4/-4

Rename MultiBucketBitmapIndex to MultiBucketBitmap

• Renamed MultiBucketBitmapIndex struct to MultiBucketBitmap
• Updated file header comment and documentation to reflect new type name

src/multi_bucket.rs

---

20. tests/redteam_delta.rs 📝 Documentation +1/-1

Update redteam_delta documentation reference

• Updated documentation comment to reference new RankQuant type name instead of RankQuantIndex

tests/redteam_delta.rs

---

21. tests/deprecated_aliases.rs 🧪 Tests +25/-0

Add smoke tests for deprecated type aliases

• New file with smoke tests confirming pre-0.2 *Index type aliases still compile
• Tests verify RankIndex, RankQuantIndex, BitmapIndex, SignBitmapIndex, and
 MultiBucketBitmapIndex are reachable
• Demonstrates backward compatibility for deprecated names

tests/deprecated_aliases.rs

---

22. docs/RANK_MODES.md 📝 Documentation +29/-29

Update documentation to reflect rebranded type names

• Updated all type name references from *Index suffix to new names throughout the documentation
• Updated module path references from rank_index to index
• Updated test file path references from tests/rank_index/ to tests/index/

docs/RANK_MODES.md

---

23. CHANGELOG.md 📝 Documentation +25/-0

Add 0.2.0 changelog entry for ontology rebrand

• Added new 0.2.0 release section documenting the ontology rebrand
• Listed all type renames and module reorganization changes
• Documented deprecated aliases for backward compatibility

CHANGELOG.md

---

24. Cargo.toml Configuration +3/-3

Bump version to 0.2.0

• Bumped version from 0.1.0 to 0.2.0
• Updated documentation comments to reference new type names

Cargo.toml

---

25. README.md 📝 Documentation +5/-5

Update README with rebranded ordvec type names

• Updated section heading from "Substrate families" to "Ordinal index family"
• Renamed all public type references to remove the Index suffix: RankIndex → Rank,
 RankQuantIndex → RankQuant, BitmapIndex → Bitmap, SignBitmapIndex → SignBitmap
• Maintained all descriptions and functionality details unchanged

README.md

---

26. docs/ALTERNATIVES_CONSIDERED.md 📝 Documentation +1/-1

Update experimental type name in alternatives documentation

• Updated reference to MultiBucketBitmapIndex type to MultiBucketBitmap to reflect the ontology
 rebrand
• Maintained all context and explanation around the experimental multi-bucket bitmap variant

docs/ALTERNATIVES_CONSIDERED.md

---

27. src/rank_index/index.rs Additional files +0/-246

...

src/rank_index/index.rs

---

28. src/rank_index/mod.rs Additional files +0/-79

...

src/rank_index/mod.rs

---

[qodo-code-review]

Code Review by Qodo

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

1. Missing index module ✓ Resolved 🐞 Bug ≡ Correctness

Description

CHANGELOG/docs state the module path is now ordvec::index, but the crate doesn’t define `pub mod
index, so use ordvec::index::…` will not compile. This makes the documented 0.2.0 API inconsistent
with the actual exported module layout.

Code

CHANGELOG.md[R25-26]

Evidence

The CHANGELOG and docs explicitly instruct users to use ordvec::index, but src/lib.rs shows only
crate-root re-exports and no pub mod index, so the documented path cannot resolve.

CHANGELOG.md[20-26]
docs/RANK_MODES.md[321-345]
tests/index/main.rs[14-16]
src/lib.rs[35-50]

Agent prompt

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

### Issue description
The PR documents a rename from `ordvec::rank_index` to `ordvec::index`, and docs reference `ordvec::index::search_asymmetric_byte_lut`, but `src/lib.rs` exports items only at the crate root and does not provide an `index` module.

### Issue Context
Users following the CHANGELOG/docs will write `use ordvec::index::…` and hit a compile error. This is especially likely because both the CHANGELOG and `docs/RANK_MODES.md` explicitly mention `ordvec::index`.

### Fix Focus Areas
- src/lib.rs[35-64]
- CHANGELOG.md[20-26]
- docs/RANK_MODES.md[321-345]
- tests/index/main.rs[14-16]

### Suggested fix
1. Add a `pub mod index { … }` wrapper in `src/lib.rs` that re-exports the intended public items, e.g.:
  - `pub use crate::{Rank, RankQuant, Bitmap, SignBitmap, search_asymmetric_byte_lut};`
  - include `MultiBucketBitmap` behind `experimental`
  - include `RankQuantFastscan` as `#[doc(hidden)]` if you want parity with the root.
2. Decide whether docs should prefer `ordvec::index::…` or crate-root `ordvec::…`, then make CHANGELOG/docs consistent with that choice.

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

---

2. Broken README anchor link ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

docs/RANK_MODES.md links to ../README.md#substrate-families, but the README header was renamed,
so that anchor no longer exists. This makes the two-stage-path cross-reference in the docs dead.

Code

README.md[13]

Evidence

README now contains the header ## Ordinal index family, while RANK_MODES still links to
#substrate-families, so the link target is gone.

README.md[13-22]
docs/RANK_MODES.md[69-79]

Agent prompt

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

### Issue description
The README section header was renamed, changing the markdown anchor, but `docs/RANK_MODES.md` still points at the old `#substrate-families` anchor.

### Issue Context
This breaks navigation for readers following the documentation link to the README section describing the index family.

### Fix Focus Areas
- README.md[13-23]
- docs/RANK_MODES.md[69-79]

### Suggested fix
Update `docs/RANK_MODES.md` to link to the new anchor (likely `../README.md#ordinal-index-family`), or reintroduce a compatible heading/anchor in README if you need to preserve the old link.

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

---

3. RankQuant fields overexposed 🐞 Bug ⚙ Maintainability

Description

RankQuant’s internal state (dim, bits, n_vectors, packed) was widened from pub(super) to
pub(crate), allowing any in-crate code to bypass invariants by mutating these fields directly.
This is an encapsulation regression for a public type and increases the chance of future
invariant-breaking changes.

Code

src/quant.rs[R40-46]

Evidence

RankQuant is re-exported as a public type from src/lib.rs, and its definition shows all core
invariants-carrying fields are pub(crate) rather than private.

src/quant.rs[40-46]
src/lib.rs[47-50]

Agent prompt

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

### Issue description
`RankQuant` is publicly exported, but its internal fields are now `pub(crate)`. This weakens encapsulation and makes it easier for other crate modules to accidentally construct invalid states (e.g., mismatched `packed` length vs `dim/bits/n_vectors`).

### Issue Context
With the old nested module layout, `pub(super)` limited access to the `rank_index` module; after flattening, `pub(crate)` exposes these fields to the entire crate. No public API requires direct field access.

### Fix Focus Areas
- src/quant.rs[40-46]
- src/lib.rs[47-50]

### Suggested fix
Make the fields private (remove `pub(crate)`), and keep access through existing methods (`dim()`, `len()`, `bytes_per_vec()`, etc.). If any internal caller truly needs raw access, prefer adding narrow internal helper methods instead of exposing the whole struct state.

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

---

[gemini-code-assist]

Code Review

This pull request rebrands the ordvec ontology by dropping the Index suffix from core types and renaming the rank_index module to index, while maintaining backward compatibility via deprecated aliases. The Rank struct now directly implements search logic. Feedback suggests optimizing the Spearman correlation calculation by precalculating centred ranks and adopting the more idiomatic copy_within for block moves in swap_remove.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e11f3af444

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".