### Install and Preview Changelog with git-cliff

Source: https://github.com/fieldnote-echo/ordvec/blob/main/CONTRIBUTING.md

Install git-cliff globally and preview the changelog for the next release based on unreleased commits.

```sh
cargo install git-cliff           # once
git cliff --unreleased --tag vX.Y.Z   # preview the next section
```

--------------------------------

### Install ordvec-manifest

Source: https://github.com/fieldnote-echo/ordvec/blob/main/ordvec-manifest-python/README.md

Install the ordvec-manifest package from PyPI using pip.

```bash
python -m pip install ordvec-manifest
```

--------------------------------

### Minimal ordvec C API Example

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/c-api.md

A complete C program demonstrating loading an index, retrieving its information, performing a search, and processing the results. Ensure the index file 'index.tvrq' exists and the necessary headers are included.

```c
#include <inttypes.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include "ordvec.h"

int main(void) {
    ordvec_index_t *index = NULL;
    ordvec_status_t st = ordvec_index_load("index.tvrq", 0, &index);
    if (st != ORDVEC_STATUS_OK) {
        fprintf(stderr, "load failed: %s\n", ordvec_last_error());
        return 1;
    }

    ordvec_index_info_t info;
    ordvec_index_info_init(&info);
    st = ordvec_index_info(index, &info);
    if (st != ORDVEC_STATUS_OK) {
        fprintf(stderr, "info failed: %s\n", ordvec_last_error());
        ordvec_index_free(index);
        return 1;
    }

    if (info.dim > SIZE_MAX / sizeof(float)) {
        fprintf(stderr, "index dimension is too large\n");
        ordvec_index_free(index);
        return 1;
    }

    float *query = calloc((size_t)info.dim, sizeof *query);
    if (query == NULL) {
        fprintf(stderr, "query allocation failed\n");
        ordvec_index_free(index);
        return 1;
    }

    ordvec_search_params_t params;
    ordvec_search_params_init(&params);
    params.query = query;
    params.dim = info.dim;
    params.k = 10;

    ordvec_hit_t hits[10];
    uint64_t returned = 0;
    ordvec_search_stats_t stats;
    ordvec_search_stats_init(&stats);

    st = ordvec_index_search(index, &params, hits, 10, &returned, &stats);
    if (st != ORDVEC_STATUS_OK) {
        fprintf(stderr, "search failed: %s\n", ordvec_last_error());
        free(query);
        ordvec_index_free(index);
        return 1;
    }

    for (uint64_t i = 0; i < returned; i++) {
        printf("row=%%" PRIu64 " id=%%" PRIu64 " score=%%f\n",
               hits[i].row_id,
               hits[i].id,
               hits[i].score);
    }

    free(query);
    ordvec_index_free(index);
    return 0;
}
```

--------------------------------

### Benchmarking Rank Modes with Custom Embeddings

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/RANK_MODES.md

Run the bench_rank example with your own .npy files for embeddings and queries to evaluate performance. Ensure your .npy files are 2-D little-endian float32 (<f4), C-order arrays.

```bash
cargo run --release --example bench_rank -- \
  --corpus-npy  /path/to/embeddings.npy \
  --queries-npy /path/to/queries.npy \
  --queries 200 --k 10
```

--------------------------------

### Run Specific Synthetic Stress Test Configuration

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/RANK_MODES.md

Executes the bench_rank example with explicit parameters for dimension, number of documents, queries, clusters, and latent dimension. This is used for the low-rank clustered synthetic stress test.

```bash
cargo run --release --example bench_rank -- \
  --dim 256 --n 30000 --queries 200 --clusters 200 --latent 64
```

--------------------------------

### Example Manifest JSON Structure

Source: https://github.com/fieldnote-echo/ordvec/blob/main/ordvec-manifest/README.md

This JSON structure represents a manifest file, detailing artifact information, auxiliary artifacts, and verification results. It includes fields for expected and observed SHA-256 hashes and sizes, as well as error and warning codes.

```json
{
  "ok": false,
  "checked_at": "2026-06-03T17:21:00Z",
  "manifest_id": "urn:uuid:11111111-1111-4111-8111-111111111111",
  "artifact": {
    "manifest_path": "index.tvrq",
    "observed_path": "index.tvrq",
    "canonical_path": "/srv/index/index.tvrq",
    "sha256": "1111111111111111111111111111111111111111111111111111111111111111",
    "size_bytes": 4096,
    "metadata": null
  },
  "auxiliary_artifacts": [
    {
      "name": "ordgrep.sidecar",
      "manifest_path": "ordgrep.sidecar.json",
      "resolved_path": "/srv/index/ordgrep.sidecar.json",
      "canonical_path": "/srv/index/ordgrep.sidecar.json",
      "expected_sha256": "2222222222222222222222222222222222222222222222222222222222222222",
      "expected_size_bytes": 128,
      "required": true,
      "state": "failed",
      "reason_code": "auxiliary_artifact_sha256_mismatch",
      "sha256": "3333333333333333333333333333333333333333333333333333333333333333",
      "size_bytes": 128
    },
    {
      "name": "required-model-card",
      "manifest_path": "model-card.json",
      "resolved_path": "/srv/index/model-card.json",
      "expected_sha256": "4444444444444444444444444444444444444444444444444444444444444444",
      "expected_size_bytes": 2048,
      "required": true,
      "state": "missing_required",
      "reason_code": "auxiliary_artifact_missing_required",
      "sha256": null,
      "size_bytes": null
    }
  ],
  "row_identity": {
    "kind": "row_id_identity",
    "manifest_path": null,
    "canonical_path": null,
    "sha256": null,
    "row_count": 1024,
    "validated_rows": 1024
  },
  "calibration": {
    "present": false,
    "schema_version": null,
    "profile_id": null,
    "calibrated_for_model": null,
    "ordinalization": null,
    "null_model": null,
    "profile_manifest_path": null,
    "profile_canonical_path": null,
    "profile_sha256": null,
    "profile_size_bytes": null
  },
  "attestation_shape_checks": [],
  "errors": [
    {
      "code": "auxiliary_artifact_sha256_mismatch",
      "message": "auxiliary artifact \"ordgrep.sidecar\" SHA-256 was 3333333333333333333333333333333333333333333333333333333333333333, manifest declares 2222222222222222222222222222222222222222222222222222222222222222"
    },
    {
      "code": "auxiliary_artifact_missing_required",
      "message": "required auxiliary artifact \"required-model-card\" is missing at /srv/index/model-card.json"
    }
  ],
  "warnings": [],
  "skipped_checks": []
}
```

--------------------------------

### Create and Verify Ordvec Manifest using CLI

Source: https://github.com/fieldnote-echo/ordvec/blob/main/ordvec-manifest/README.md

Demonstrates how to create a manifest file for an ordvec index and then verify it using the command-line interface. Use `--allow-path-escape` if artifacts are outside the manifest directory.

```sh
ordvec-manifest create \
  --index path/to/index.tvrq \
  --row-id-is-identity \
  --aux ordinaldb.ids=path/to/ids.bin \
  --embedding-model bge-small-en-v1.5 \
  --out path/to/index.manifest.json

ordvec-manifest verify --manifest path/to/index.manifest.json
```

--------------------------------

### Install ordvec Python Package

Source: https://github.com/fieldnote-echo/ordvec/blob/main/ordvec-python/README.md

Installs the ordvec Python package using pip. Ensure you have Python 3.10+ and numpy 2.2 or later.

```bash
pip install ordvec
```

--------------------------------

### Initialize and Search with RankQuant

Source: https://github.com/fieldnote-echo/ordvec/blob/main/ordvec-python/README.md

Demonstrates initializing a RankQuant object for ordinal vector quantization and performing an asymmetric search. This is recommended for scenarios where query vectors are full-precision floats and document vectors are bucketed.

```python
import numpy as np
import ordvec

q = ordvec.RankQuant(1024, 2)          # 1024-dim, 2 bits/coord
q.add(np.random.randn(10_000, 1024).astype(np.float32))
# asymmetric: full-precision float queries vs bucketed docs (recommended)
scores, ids = q.search_asymmetric(np.random.randn(8, 1024).astype(np.float32), k=10)
```

--------------------------------

### Run Experimental Tests

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/RANK_MODES.md

Enables and runs tests under the 'experimental' feature, which includes MultiBucket tests.

```bash
cargo test --features experimental
```

--------------------------------

### Example External Segment Entry (JSON)

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/PERSISTED_FORMAT.md

This JSON object represents metadata for an external segment, including file path, SHA256 hash, and detailed index metadata. It is used by host systems to cache segment descriptors.

```json
{
  "path": "segments/shard-0007/index.tvrq",
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "metadata": {
    "kind": "RankQuant",
    "format_version": 1,
    "dim": 1024,
    "vector_count": 1250000,
    "bytes_per_vec": 256,
    "params": { "bits": 2 },
    "file_size_bytes": 320000014
  }
}
```

--------------------------------

### Verify an Index Manifest

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/INDEX_PROVENANCE.md

Use this command to verify an index manifest file before loading. Ensure the manifest path is correct.

```sh
cargo run -p ordvec-manifest --features cli -- verify --manifest path/to/index.manifest.json
```

--------------------------------

### Build Native Library

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/c-api.md

Build the native ordvec-ffi library in release mode using Cargo.

```sh
cargo build -p ordvec-ffi --release
```

--------------------------------

### Verify a Manifest

Source: https://github.com/fieldnote-echo/ordvec/blob/main/ordvec-manifest-python/README.md

Verify an existing manifest file and check for errors. Raises a RuntimeError if the verification fails.

```python
import ordvec_manifest

report = ordvec_manifest.verify_manifest("index.manifest.json")
if not report["ok"]:
    raise RuntimeError(report["errors"])
```

--------------------------------

### Create and Push Signed Version Tag

Source: https://github.com/fieldnote-echo/ordvec/blob/main/RELEASING.md

Create a signed Git tag for the new version and push it to the origin. This action automatically triggers the release workflow.

```bash
git tag -s vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
```

--------------------------------

### Build and Test ordvec-go

Source: https://github.com/fieldnote-echo/ordvec/blob/main/ordvec-go/README.md

Commands to build the Rust library, run Go tests, and enable race detection and cgo checking.

```sh
cargo build -p ordvec-ffi --release
cd ordvec-go
go test ./...
go test -race ./...
GOEXPERIMENT=cgocheck2 go test ./...
```

--------------------------------

### Create a Manifest with Auxiliary Artifacts

Source: https://github.com/fieldnote-echo/ordvec/blob/main/ordvec-manifest-python/README.md

Create a new manifest file, specifying auxiliary artifacts with their names, paths, and whether they are required. This function is used for creating manifests with caller-owned sidecars.

```python
manifest = ordvec_manifest.create_manifest(
    "index.tvrq",
    "index.manifest.json",
    "bge-small-en-v1.5",
    row_id_is_identity=True,
    auxiliary_artifacts=[
        {"name": "ordinaldb.ids", "path": "ids.bin"},
        {"name": "optional.stats", "path": "stats.json", "required": False},
    ],
)
plan = ordvec_manifest.verify_for_load("index.manifest.json")
```

--------------------------------

### Run Release Environment Settings Audit

Source: https://github.com/fieldnote-echo/ordvec/blob/main/RELEASING.md

Execute a script to verify GitHub Environments and registry Trusted Publisher settings for the release process. This ensures correct reviewer assignments and tag patterns.

```bash
bash tests/release_environment_settings.sh
```

--------------------------------

### Run Integration Tests

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/RANK_MODES.md

Executes the integration test suite located in tests/index/. This suite covers rank, quant, bitmap, fastscan, and multi_bucket functionalities.

```bash
cargo test --test index
```

--------------------------------

### Benchmark with Public Corpus

Source: https://github.com/fieldnote-echo/ordvec/blob/main/benchmarks/rank_modes_results.txt

Run the benchmark using real public corpora by specifying paths to .npy files for the corpus and queries. This allows for evaluation on different datasets.

```bash
cargo run --release --example bench_rank -- \
    --corpus-npy /path/to/corpus.npy --queries-npy /path/to/queries.npy
```

--------------------------------

### Run Unit Tests

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/RANK_MODES.md

Executes the unit tests for the primitives in src/rank.rs. This includes tests for rank transform, partitioning, and round-trips.

```bash
cargo test --lib
```

--------------------------------

### Run Pre-Merge Checks

Source: https://github.com/fieldnote-echo/ordvec/blob/main/CONTRIBUTING.md

Execute the standard checks to ensure code quality and correctness before submitting a pull request. These commands mirror the CI environment.

```sh
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test                            # default surface
cargo test --features experimental
cargo test --no-default-features
cargo +1.89.0 build                   # MSRV
cargo build --locked
RUSTFLAGS="-D warnings" cargo build
cargo deny check                      # licenses / advisories / bans / sources
```

--------------------------------

### ordvec_index_info_init

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/c-api.md

Initializes an ordvec_index_info_t struct with default values. This should be called before passing the struct to ordvec_index_info.

```APIDOC
## ordvec_index_info_init

### Description
Initializes an ordvec_index_info_t struct with default values. This should be called before passing the struct to ordvec_index_info.

### Function Signature
void ordvec_index_info_init(ordvec_index_info_t *info)

### Parameters
- **info** (ordvec_index_info_t *) - Required - Pointer to the struct to initialize.
```

--------------------------------

### Initialize and Add Embeddings to RankQuant Index

Source: https://github.com/fieldnote-echo/ordvec/blob/main/README.md

Initialize a RankQuant index with specified dimensions and bits per coordinate. Add document embeddings to the index using a flat, row-major buffer.

```rust
use ordvec::RankQuant;

let dim = 1024;
let mut index = RankQuant::new(dim, 2);   // 2 bits/coord → 256 bytes/doc

// `add` takes a flat, row-major buffer of `dim * n_docs` f32s.
index.add(&doc_embeddings);               // &[f32], len = dim * n_docs
```

--------------------------------

### Run Benchmark with Custom Embeddings

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/RANK_MODES.md

Runs the benchmark against your own real embedding arrays. Requires specifying paths to corpus and queries NPY files, along with query count and k value.

```bash
cargo run --release --example bench_rank -- \
    --corpus-npy  /path/to/embeddings.npy \
    --queries-npy /path/to/queries.npy \
    --queries 200 --k 10
```

--------------------------------

### Load Ordvec Index after Verification (Controlled Storage)

Source: https://github.com/fieldnote-echo/ordvec/blob/main/ordvec-manifest/README.md

Illustrates the controlled-storage load pattern using the ordvec-manifest library. This pattern verifies the manifest and then loads the primary artifact, ensuring data integrity before use.

```rust
let plan = ordvec_manifest::verify_for_load(&manifest_path, options)?;
let _ordinaldb_ids = plan.require_auxiliary("ordinaldb.ids")?;
let index = ordvec::RankQuant::load(plan.artifact_path())?;
```

--------------------------------

### ordvec_search_params_init

Source: https://github.com/fieldnote-echo/ordvec/blob/main/docs/c-api.md

Initializes an ordvec_search_params_t struct with default values. This should be called before passing the struct to ordvec_index_search.

```APIDOC
## ordvec_search_params_init

### Description
Initializes an ordvec_search_params_t struct with default values. This should be called before passing the struct to ordvec_index_search.

### Function Signature
void ordvec_search_params_init(ordvec_search_params_t *params)

### Parameters
- **params** (ordvec_search_params_t *) - Required - Pointer to the struct to initialize.
```

--------------------------------

### Run AddressSanitizer Locally

Source: https://github.com/fieldnote-echo/ordvec/blob/main/CONTRIBUTING.md

Execute the core sanitizer check locally for native x86_64 targets. This helps detect memory errors and leaks.

```sh
RUSTFLAGS="-D warnings -Zsanitizer=address -C force-frame-pointers=yes" \
ASAN_OPTIONS="detect_leaks=0:halt_on_error=1:abort_on_error=1" \
cargo +nightly-2025-08-15 test -Z build-std \
  --target x86_64-unknown-linux-gnu \
  -p ordvec --lib --tests --all-features
```