feat: ordvec on-disk format (.ov* magics) with full back-compat for legacy .tv*

[Fieldnote-Echo]

What

Renames the four on-disk index magics from the turbovec-era TV* to the ordvec OV* family, without breaking the read contract:

type	extension	magic (written)	also loads (legacy)
Rank	.ovr	OVR1	TVR1
RankQuant	.ovrq	OVRQ	TVRQ
Bitmap	.ovbm	OVBM	TVBM
SignBitmap	.ovsb	OVSB	TVSB

Writers emit OV*; every loader accepts both OV* and legacy TV*. Any file the crate (or upstream turbovec) ever wrote still loads — only the write path changed.

Changes

• src/rank_io.rs — OV* magic constants (written) + TV* retained read-only; writers emit OV*; the four loaders and probe_index_metadata accept both.
• ordvec-ffi (C ABI) — the sniff-magic load dispatch accepts both OV* and TV* (functional: new files must load through the C/Go path). Probe path was already format-agnostic.
• tests/persistence_compat.rs — the byte-stable fixtures now pin OV*; new back-compat tests prove a legacy TV* file still loads for all four types.
• Parity sweep (docs/extensions only, no logic): ordvec-manifest (+ python bindings), ordvec-python docstrings + tests, ordvec-go test (primary fixture on OV*, one explicit legacy-TV* back-compat case), C header, fuzz targets, docs/*, README format line, SECURITY.md/THREAT_MODEL.md, the CONTRIBUTING.md stable-surface statement (reworded: the read contract is never broken), and .gitignore (adds *.ov*, keeps *.tv*).

Validation

cargo fmt --all --check; cargo clippy -D warnings (core / ffi / manifest); full test suites (core experimental + default, manifest 53, ffi); cargo check -p ordvec-python; RUSTDOCFLAGS=-D warnings cargo doc. The manifest crate is format-agnostic (opaque hashed artifacts), so its updates are extension-naming parity only.

Follow-ups (separate PRs)

• FastScan promotion (un-hide RankQuantFastscan) + its own OVFS/.ovfs persistence in this OV* convention.
• Full docs refresh.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0)

1. Stale TV* error labels ✓ Resolved 🐞 Bug ◔ Observability

Description

After expanding loaders/probes to accept both OV* and legacy TV* magics, multiple
parsing/validation calls still pass hard-coded "TVR1"/"TVRQ"/"TVBM"/"TVSB" labels, so
malformed OV* files can emit errors that incorrectly reference TV*. This is not a parsing
correctness bug, but it makes failures harder to interpret and can confuse support tooling that keys
off these messages.

Code

src/rank_io.rs[R526-533]

    let file_len = file.metadata()?.len();
    let mut f = BufReader::new(file);
    let magic = read_magic(&mut f, "TVR1")?;
-    if &magic != TVR_MAGIC {
-        return Err(invalid("not a TVR1 file: wrong magic"));
+    if &magic != OVR_MAGIC && &magic != TVR_MAGIC {
+        return Err(invalid("not an OVR1/TVR1 (Rank) file: wrong magic"));
    }
    read_version(&mut f, "TVR1")?;
    let dim = read_u32_le(&mut f, "TVR1", "dim")? as usize;

Evidence

probe_index_metadata and the per-type loaders now accept OV* magics, but the subsequent parsing
still uses TV* label strings for version/field reads and payload-length validation, so error
messages can refer to TV* even when the input file is OV*. The module-level docs also establish
that OV* is the current format, increasing the chance this mismatch confuses users.

src/rank_io.rs[3-10]
src/rank_io.rs[353-363]
src/rank_io.rs[519-540]
src/rank_io.rs[367-379]

Agent prompt

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

### Issue description
`rank_io` now accepts both the new `OV*` magics and legacy `TV*` magics, but most error-context labels are still hard-coded to `TV*` (e.g., `read_magic(&mut f, "TVR1")`, `read_version(..., "TVR1")`, `check_payload_matches_file(..., "TVR1", ...)`). This causes malformed/truncated `OV*` files to produce error strings that refer to `TV*`, which is misleading now that the crate’s “current” format is `OV*`.

### Issue Context
This was introduced/heightened by the PR’s back-compat change (accepting both magics) while keeping the old label strings used for structured error messages.

### Fix Focus Areas
- src/rank_io.rs[353-410]
- src/rank_io.rs[519-578]
- src/rank_io.rs[607-668]
- src/rank_io.rs[719-746]
- src/rank_io.rs[828-849]

### Suggested fix approach
- Option A (simplest): replace per-format labels with neutral labels like `"OVR1/TVR1"`, `"OVRQ/TVRQ"`, `"OVBM/TVBM"`, `"OVSB/TVSB"` everywhere they’re used for error context.
- Option B (more precise): after reading `magic`, derive the label dynamically (`"OVR1"` vs `"TVR1"`, etc.) and use that label for subsequent reads and `check_payload_matches_file` so error messages reflect the actual file magic.
- Update any tests that assert the old `TV*` label substrings accordingly.

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

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

PR Summary by Qodo

Rename persisted index magics to OV* with legacy TV* load compatibility
✨ Enhancement 🧪 Tests 📝 Documentation 🕐 40+ Minutes

Walkthroughs

Description

• Writers now emit .ov* files with OV* magics for all index types.
• Loaders and C ABI accept both OV* and legacy TV* magics.
• Refresh fixtures/docs/bindings to .ov* and add explicit legacy-load tests.

Diagram

graph TD
A["Index APIs"] --> B["rank_io writers"] --> C[(".ov* index files")]
C --> D{"Magic OV* or TV*?"} --> E["rank_io loaders"]
C --> F["ordvec-ffi magic sniff"] --> G["RankQuant/Bitmap load"]
subgraph Legend
  direction LR
  _m["Module/API"] ~~~ _f[("On-disk file")] ~~~ _d{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep TV* magics and only rename extensions to .ov*

• ➕ Avoids changing byte-level headers; fewer compatibility edge cases
• ➕ Reduces need for multi-magic acceptance logic
• ➖ On-disk header remains turbovec-branded; harder to distinguish ordvec-written files
• ➖ Does not achieve a clean ordvec format identity at the magic level

2. Introduce a v2 format version with new header fields (kind + magic)

• ➕ Creates room for future evolution (more kinds, richer metadata) without reusing magics
• ➕ Can make dispatch independent of file extension/magic family
• ➖ Larger migration surface: writers would produce v2 that older readers cannot load
• ➖ More code complexity and more fixtures to maintain than a magic rename

3. Extension-based dispatch in FFI (ignore magic sniffing)

• ➕ Simpler FFI detection logic
• ➕ No need to special-case multiple magics
• ➖ Breaks if users rename files or use non-standard paths
• ➖ Weaker corruption detection vs magic-first validation

Recommendation: The PR’s approach (new OV* write magics + dual-magic read support everywhere) is the best trade-off: it establishes a stable ordvec identity for newly written files while preserving the strongest compatibility guarantee (all historical files remain loadable). The alternatives either fail to fully rebrand the on-disk format, expand the migration surface (v2), or weaken correctness checks (extension-based dispatch).

File Changes

Enhancement (6)

lib.rs FFI load dispatch accepts both OVRQ/TVRQ and OVBM/TVBM +20/-16

FFI load dispatch accepts both OVRQ/TVRQ and OVBM/TVBM

• Updates error messages and doc comments to remove TV*-specific wording. Extends the magic-sniff dispatch in 'ordvec_index_load' to accept both current 'OV*' and legacy 'TV*' magics while preserving the ABI v1 restriction to RankQuant/Bitmap handles.

ordvec-ffi/src/lib.rs

---

bitmap.rs Bitmap persistence docs and errors updated for OVBM naming +7/-4

Bitmap persistence docs and errors updated for OVBM naming

• Updates 'write'/'load' doc comments to reflect '.ovbm' as the current format while explicitly accepting legacy '.tvbm'. Adjusts error messages to use 'OVBM' terminology (no logic change in these checks).

src/bitmap.rs

---

quant.rs RankQuant persistence docs/errors updated for OVRQ naming +13/-10

RankQuant persistence docs/errors updated for OVRQ naming

• Updates persistence doc comments to refer to '.ovrq' and clarifies legacy '.tvrq' acceptance. Updates multiple error message strings from 'TVRQ' to 'OVRQ' to match the new primary format identity.

src/quant.rs

---

rank.rs Rank persistence docs/errors updated for OVR1 naming +7/-4

Rank persistence docs/errors updated for OVR1 naming

• Updates 'write'/'load' docs to '.ovr' and documents that legacy '.tvr' files remain loadable. Adjusts overflow/payload mismatch error messages to use 'OVR1' naming.

src/rank.rs

---

rank_io.rs Switch writers to OV* magics and accept both OV*/TV* on load/probe +32/-21

Switch writers to OV* magics and accept both OV*/TV* on load/probe

• Introduces 'OVR1/OVRQ/OVBM/OVSB' constants as the new write-time magics while retaining 'TV*' constants for backward compatibility. Updates 'probe_index_metadata' and all four loaders to accept either magic family, and updates all writers to emit only 'OV*'.

src/rank_io.rs

---

sign_bitmap.rs SignBitmap persistence docs and errors updated for OVSB naming +8/-5

SignBitmap persistence docs and errors updated for OVSB naming

• Updates persistence doc comments to '.ovsb' and explicitly notes legacy '.tvsb' acceptance. Adjusts overflow/payload mismatch error message strings to use 'OVSB' naming.

src/sign_bitmap.rs

---

Tests (3)

c_link_smoke.rs FFI C link smoke test fixtures switched to OVRQ/.ovrq +2/-2

FFI C link smoke test fixtures switched to OVRQ/.ovrq

• Updates the handcrafted RankQuant fixture to start with 'OVRQ' rather than 'TVRQ'. Renames the fixture extension to '.ovrq' to match current writer behavior.

ordvec-ffi/tests/c_link_smoke.rs

---

ordvec_test.go Go binding tests: OV* default fixture + explicit legacy TVRQ test +36/-7

Go binding tests: OV* default fixture + explicit legacy TVRQ test

• Refactors RankQuant fixture generation to be parameterized by magic/extension, then defaults to 'OVRQ'/'.ovrq'. Adds a dedicated test confirming the C ABI still loads a legacy 'TVRQ' fixture.

ordvec-go/ordvec_test.go

---

persistence_compat.rs Pin byte-stable fixtures to OV* and add explicit legacy TV* load tests +99/-4

Pin byte-stable fixtures to OV* and add explicit legacy TV* load tests

• Updates the canonical byte-stability fixtures to begin with the 'OV*' magics. Adds four new tests that swap only the first 4 bytes to legacy 'TV*' magics and assert the public 'load' APIs still accept and parse them correctly.

tests/persistence_compat.rs

---

Documentation (12)

CONTRIBUTING.md Document persistence stability as 'load forever' across OV*/TV* +8/-4

Document persistence stability as 'load forever' across OV*/TV*

• Updates the stable-surface statement to reflect the new '.ov*' magics. Explicitly documents that loaders accept both '.ov*' and legacy '.tv*' formats, preserving the read contract.

CONTRIBUTING.md

---

README.md Update security section to reference .ov* formats and legacy loading +2/-1

Update security section to reference .ov* formats and legacy loading

• Renames persisted format extensions to '.ov*' and notes that legacy '.tv*' files still load. Keeps the same trust model text while aligning terminology with the new format naming.

README.md

---

SECURITY.md Align security notes with OV* magics while preserving legacy acceptance +3/-2

Align security notes with OV* magics while preserving legacy acceptance

• Updates the list of parsed file types to '.ov*' and adds an explicit note that legacy '.tv*' magics remain accepted. Reinforces fuzzing focus on deserialization paths.

SECURITY.md

---

THREAT_MODEL.md Update threat model references to OV* loaders and FFI support +3/-3

Update threat model references to OV* loaders and FFI support

• Updates deserialization boundary descriptions to reference '.ov*' loaders with legacy '.tv*' acceptance. Adjusts C ABI section wording to match '.ovrq'/'.ovbm' while noting legacy load support.

THREAT_MODEL.md

---

INDEX_PROVENANCE.md Rename persisted file extensions in provenance docs +1/-1

Rename persisted file extensions in provenance docs

• Updates the description of persisted artifacts from '.tv*' to '.ov*'. No behavioral or contract changes beyond terminology alignment.

docs/INDEX_PROVENANCE.md

---

PERSISTED_FORMAT.md Document OV* magics as current, with TV* accepted on load +23/-11

Document OV* magics as current, with TV* accepted on load

• Renames all format sections to '.ov*' and updates example paths accordingly. Adds explicit compatibility notes that loaders accept legacy 'TV*' magics while writers emit 'OV*'.

docs/PERSISTED_FORMAT.md

---

c-api.md Update C API docs to use .ovrq/.ovbm examples +3/-3

Update C API docs to use .ovrq/.ovbm examples

• Replaces '.tvrq'/'.tvbm' references with '.ovrq'/'.ovbm' in the C API documentation and sample code. Keeps the same API surface, just aligns the file naming guidance.

docs/c-api.md

---

compatibility-policy.md Refresh compatibility policy with OV* formats and legacy TV* support +8/-4

Refresh compatibility policy with OV* formats and legacy TV* support

• Updates the list of primitive index formats to the '.ov*'/'OV*' family. Adds a clear statement that legacy '.tv*'/'TV*' artifacts remain accepted, while writers stop emitting them.

docs/compatibility-policy.md

---

ordvec.h C header: document .ovrq/.ovbm loads with legacy support +5/-3

C header: document .ovrq/.ovbm loads with legacy support

• Updates public API comments to reference '.ovrq' and '.ovbm' as the primary persisted formats. Adds explicit note that legacy '.tvrq'/'.tvbm' files are also accepted.

ordvec-ffi/include/ordvec.h

---

README.md Manifest Python README uses .ovrq in examples +1/-1

Manifest Python README uses .ovrq in examples

• Updates example index file names from '.tvrq' to '.ovrq' to match the current persisted format naming. No behavior changes to the manifest tooling described.

ordvec-manifest-python/README.md

---

README.md Manifest CLI docs updated to .ovrq paths +7/-7

Manifest CLI docs updated to .ovrq paths

• Updates CLI examples and JSON output examples to reference '.ovrq' instead of '.tvrq'. This is a documentation parity change only.

ordvec-manifest/README.md

---

lib.rs Python bindings docstrings updated to .ov* with legacy-load notes +16/-12

Python bindings docstrings updated to .ov* with legacy-load notes

• Updates docstrings for write/load methods across Rank/RankQuant/Bitmap/SignBitmap to reference '.ov*' formats. Adds explicit notes that legacy '.tv*' files remain accepted by loaders.

ordvec-python/src/lib.rs

---

Other (13)

load_bitmap.rs Fuzz target docs: OVBM loader accepts legacy TVBM +3/-2

Fuzz target docs: OVBM loader accepts legacy TVBM

• Updates target documentation to reference '.ovbm'/'OVBM' as the primary format. Notes that the loader also accepts the legacy '.tvbm'/'TVBM' magic.

fuzz/fuzz_targets/load_bitmap.rs

---

load_rank.rs Fuzz target docs: OVR1 loader accepts legacy TVR1 +3/-2

Fuzz target docs: OVR1 loader accepts legacy TVR1

• Updates the target documentation to reference '.ovr'/'OVR1' as primary. Documents that legacy '.tvr'/'TVR1' is still accepted on load.

fuzz/fuzz_targets/load_rank.rs

---

load_rankquant.rs Fuzz target docs: OVRQ loader accepts legacy TVRQ +3/-2

Fuzz target docs: OVRQ loader accepts legacy TVRQ

• Renames the documented primary target format to '.ovrq'/'OVRQ'. Notes dual-magic support to preserve backward compatibility.

fuzz/fuzz_targets/load_rankquant.rs

---

load_sign_bitmap.rs Fuzz target docs: OVSB loader accepts legacy TVSB +4/-3

Fuzz target docs: OVSB loader accepts legacy TVSB

• Updates documentation references from '.tvsb' to '.ovsb' and notes that the legacy magic remains supported. Adjusts an internal comment to refer to '.ovsb' validation paths.

fuzz/fuzz_targets/load_sign_bitmap.rs

---

roundtrip_rankquant.rs Update roundtrip scratch filename to .ovrq +1/-1

Update roundtrip scratch filename to .ovrq

• Changes the temporary file extension used for round-trip persistence fuzzing from '.tvrq' to '.ovrq'. Maintains the same round-trip assertion behavior.

fuzz/fuzz_targets/roundtrip_rankquant.rs

---

scratch.rs Update fuzz scratch docs to reflect .ov* primary formats +3/-2

Update fuzz scratch docs to reflect .ov* primary formats

• Renames the documented set of loader fuzz targets to '.ov*' and notes legacy '.tv*' acceptance. No runtime logic changes.

fuzz/fuzz_targets/scratch.rs

---

test_manifest_bindings.py Manifest Python tests: fixtures now use OVRQ and .ovrq paths +4/-4

Manifest Python tests: fixtures now use OVRQ and .ovrq paths

• Updates the test helper that writes a minimal RankQuant artifact to use the 'OVRQ' magic. Renames fixture paths and manifest inputs to '.ovrq'.

ordvec-manifest-python/tests/test_manifest_bindings.py

---

manifest.rs Manifest tests renamed to .ov* fixture extensions +16/-16

Manifest tests renamed to .ov* fixture extensions

• Updates helper functions and hardcoded manifest paths to use '.ov*' extensions for all index kinds. Keeps the manifest verification behavior unchanged; this primarily maintains naming parity with current persisted artifacts.

ordvec-manifest/tests/manifest.rs

---

test_bitmap.py Python bitmap tests use .ovbm paths +3/-3

Python bitmap tests use .ovbm paths

• Renames round-trip and error-path fixtures from '.tvbm' to '.ovbm'. Updates a comment to refer to the '.ovbm' loader cap.

ordvec-python/tests/test_bitmap.py

---

test_rank.py Python rank tests use .ovr paths +2/-2

Python rank tests use .ovr paths

• Renames rank round-trip and missing-file fixtures from '.tvr' to '.ovr'. Keeps the same behavioral assertions.

ordvec-python/tests/test_rank.py

---

test_rank_quant.py Python RankQuant tests use .ovrq paths +2/-2

Python RankQuant tests use .ovrq paths

• Renames RankQuant round-trip and missing-file fixtures from '.tvrq' to '.ovrq'. Maintains the same parametrized bit-width coverage.

ordvec-python/tests/test_rank_quant.py

---

test_redteam_fuzz.py Red-team persistence tests renamed to .ov* artifacts +35/-35

Red-team persistence tests renamed to .ov* artifacts

• Updates numerous test file names used for corruption/truncation/forgery cases to '.ov*' extensions. Keeps the same security assertions (no OOM, reject trailing bytes, reject forged headers, etc.).

ordvec-python/tests/test_redteam_fuzz.py

---

test_sign_bitmap.py Python SignBitmap tests use .ovsb paths +3/-3

Python SignBitmap tests use .ovsb paths

• Renames SignBitmap round-trip and missing-file fixtures from '.tvsb' to '.ovsb'. Updates a comment to reference '.ovsb' encoding.

ordvec-python/tests/test_sign_bitmap.py

---

[gemini-code-assist]

Code Review

This pull request rebrands the on-disk persistence format from the legacy turbovec-era TV* magics and extensions (.tvr, .tvrq, .tvbm, .tvsb) to the new ordvec OV* formats (.ovr, .ovrq, .ovbm, .ovsb). The writers have been updated to emit the new formats, while the loaders across Rust, C FFI, Go, and Python bindings have been updated to support both the new and legacy magics to maintain backward compatibility. Relevant tests, fuzz targets, documentation, and manifest tools have also been updated. There are no review comments, and I have no additional feedback to provide.

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.

[Fieldnote-Echo]

Remediated in 6402aa0 (+ merged main = #237/#240):

• qodo (stale TV error labels)*: now that the loaders/probes accept both OV* and legacy TV* magics, every field-validation call and baked-in error message that still said TVR1/TVRQ/TVBM/TVSB is canonicalized to the OV* names — so a malformed OV* file no longer emits errors referencing TV*. The b"TV*" magic constants and the legacy-file test fixtures are unchanged (back-compat acceptance intact); the magic-mismatch messages keep their explicit OV*/TV* wording. Loader-validation assertions updated to match.
• CI (ffi header drift): regenerated ordvec-ffi/include/ordvec.h with cbindgen 0.29.3.

Verified: cbindgen --verify ok, fmt + clippy clean, full suite green.

[Fieldnote-Echo]

Follow-up in c0991a0: a stop-gate review caught two stale TV* references the first pass missed (they weren't in the "<MAGIC> quote-prefix form): the RankQuant probe+loader "unsupported TVRQ bits" error (TVRQ mid-string; the bits field is already read with the OVRQ label) → OVRQ, and the SignBitmap on-disk-format doc table magic = TVSB/"shorter than TVBM" → OVSB/OVBM. Remaining TV* are intentional (legacy module docs, dual-magic acceptance code + OV*/TV* mismatch messages, and back-compat test fixtures). Full suite green; ffi header unaffected.