[codex] add ordvec C ABI crate

.github/workflows/ci.yml

@@ -61,6 +61,39 @@ jobs:
       - name: cargo clippy
         run: cargo clippy --all-targets --all-features -- -D warnings
 
+  # ----------------------------------------------------------------------
+  # C ABI crate. The root workspace intentionally keeps `default-members =
+  # ["."]`, so the FFI crate has an explicit CI lane for its Rust tests,
+  # clippy, and generated-header drift check.
+  # ----------------------------------------------------------------------
+  ffi:
+    name: ffi (tests + header drift)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
+        with:
+          egress-policy: audit
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable (2026-03-27)
+        with:
+          toolchain: stable
+          components: clippy
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+      - name: install cbindgen
+        env:
+          RUSTFLAGS: ""
+        run: cargo install cbindgen --version 0.29.2 --locked
+      - name: cbindgen --verify
+        run: cbindgen ordvec-ffi --config ordvec-ffi/cbindgen.toml --output ordvec-ffi/include/ordvec.h --verify
+      - name: cargo build -p ordvec-ffi
+        run: cargo build -p ordvec-ffi
+      - name: cargo test -p ordvec-ffi
+        run: cargo test -p ordvec-ffi
+      - name: cargo clippy -p ordvec-ffi
+        run: cargo clippy -p ordvec-ffi --all-targets -- -D warnings
+
   # ----------------------------------------------------------------------
   # Test matrix across the three GitHub-hosted OSes. Covers the default
   # surface, the experimental feature, the no-default-features build, and a

Cargo.toml

@@ -56,7 +56,7 @@ opt-level = 3
 # own CI job. The single workspace `Cargo.lock` gains pyo3/numpy + transitives.
 [workspace]
 resolver = "2"
-members = ["ordvec-python"]
+members = ["ordvec-python", "ordvec-ffi"]
 default-members = ["."]
 # fuzz/ is a cargo-fuzz crate built only via `cargo +nightly fuzz`. Keep it out of
 # the workspace so it stays a standalone crate (its own Cargo.lock) and `cargo fuzz`

ordvec-ffi/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "ordvec-ffi"
+version = "0.1.0"
+edition = "2021"
+publish = false
+license = "MIT OR Apache-2.0"
+
+[lib]
+name = "ordvec_ffi"
+crate-type = ["rlib", "cdylib", "staticlib"]
+
+[dependencies]
+ordvec = { path = ".." }
+

ordvec-ffi/cbindgen.toml

@@ -0,0 +1,15 @@
+language = "C"
+include_guard = "ORDVEC_H"
+pragma_once = true
+autogen_warning = "/* Generated by cbindgen. Do not edit by hand. */"
+include_version = true
+usize_is_size_t = false
+documentation = true
+style = "type"
+cpp_compat = true
+
+[export]
+exclude = ["IndexHandle", "LoadedIndex", "FfiError"]
+
+[parse]
+parse_deps = false

ordvec-ffi/include/ordvec.h

@@ -0,0 +1,229 @@
+#ifndef ORDVEC_H
+#define ORDVEC_H
+
+#pragma once
+
+/* Generated with cbindgen:0.29.2 */
+
+/* Generated by cbindgen. Do not edit by hand. */
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#define ORDVEC_ABI_VERSION 1
+
+#define ORDVEC_CAP_FULL_SEARCH (1 << 0)
+
+#define ORDVEC_CAP_SUBSET_SEARCH (1 << 1)
+
+/**
+ * Search statistics are supported. ABI v1 populates total time and
+ * search-space counters; granular timing and byte counters are reserved and
+ * remain zero until measured in a future ABI.
+ */
+#define ORDVEC_CAP_STATS (1 << 2)
+
+#define ORDVEC_CAP_ID_EQUALS_ROW_ID (1 << 3)
+
+#define ORDVEC_SEARCH_FLAG_NONE 0
+
+typedef struct ordvec_index_t ordvec_index_t;
+
+typedef uint32_t ordvec_status_t;
+
+typedef struct {
+  uint64_t struct_size;
+  uint32_t kind;
+  uint32_t format_version;
+  uint64_t dim;
+  uint32_t bit_width;
+  uint32_t n_top;
+  uint64_t vector_count;
+  uint64_t bytes_per_vec;
+  uint64_t source_file_size_bytes;
+  uint64_t capabilities;
+  uint64_t reserved[8];
+} ordvec_index_info_t;
+
+typedef struct {
+  uint64_t struct_size;
+  const float *query;
+  uint64_t dim;
+  uint64_t k;
+  const uint32_t *candidate_rows;
+  uint64_t candidate_count;
+  uint64_t flags;
+  uint64_t user_tag;
+  uint64_t reserved[8];
+} ordvec_search_params_t;
+
+/**
+ * Optional search statistics written when `stats_out` is non-null.
+ *
+ * ABI v1 counts candidate entries rather than unique rows. Duplicate subset
+ * candidates therefore increase both `candidate_count` and `vectors_scored`.
+ * `prepare_ns`, `score_ns`, `select_ns`, and `bytes_read` are reserved and
+ * currently written as zero.
+ */
+typedef struct {
+  uint64_t struct_size;
+  uint32_t abi_version;
+  uint32_t kind;
+  uint64_t dim;
+  uint32_t bit_width;
+  uint32_t n_top;
+  uint64_t k;
+  uint64_t user_tag;
+  uint64_t vector_count;
+  uint64_t candidate_count;
+  uint64_t returned_count;
+  uint64_t total_ns;
+  uint64_t prepare_ns;
+  uint64_t score_ns;
+  uint64_t select_ns;
+  uint64_t vectors_scored;
+  uint64_t bytes_read;
+  uint64_t reserved[8];
+} ordvec_search_stats_t;
+
+typedef struct {
+  uint64_t row_id;
+  uint64_t id;
+  float score;
+  uint32_t reserved;
+} ordvec_hit_t;
+
+typedef uint32_t ordvec_index_kind_t;
+
+#define ORDVEC_STATUS_OK 0
+
+#define ORDVEC_STATUS_NULL_POINTER 1
+
+#define ORDVEC_STATUS_BAD_ARGUMENT 2
+
+#define ORDVEC_STATUS_BAD_STRUCT_SIZE 3
+
+#define ORDVEC_STATUS_UNSUPPORTED_FORMAT 4
+
+#define ORDVEC_STATUS_CORRUPT_INDEX 5
+
+#define ORDVEC_STATUS_IO 6
+
+#define ORDVEC_STATUS_DIM_MISMATCH 7
+
+#define ORDVEC_STATUS_NONFINITE_QUERY 8
+
+#define ORDVEC_STATUS_ROW_ID_OUT_OF_RANGE 9
+
+#define ORDVEC_STATUS_BUFFER_TOO_SMALL 10
+
+#define ORDVEC_STATUS_UNSUPPORTED_OPERATION 11
+
+#define ORDVEC_STATUS_PANIC 12
+
+#define ORDVEC_STATUS_INTERNAL 13
+
+#define ORDVEC_INDEX_KIND_UNKNOWN 0
+
+#define ORDVEC_INDEX_KIND_RANK_QUANT 1
+
+#define ORDVEC_INDEX_KIND_BITMAP 2
+
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+uint32_t ordvec_abi_version(void);
+
+const char *ordvec_version_string(void);
+
+const char *ordvec_status_name(ordvec_status_t status);
+
+const char *ordvec_last_error(void);
+
+ordvec_status_t ordvec_init(void);
+
+/**
+ * Initialize an `ordvec_index_info_t` with ABI v1 defaults.
+ *
+ * # Safety
+ *
+ * If `info` is non-null, it must point to writable memory large enough for
+ * `ordvec_index_info_t`.
+ */
+void ordvec_index_info_init(ordvec_index_info_t *info);
+
+/**
+ * Initialize an `ordvec_search_params_t` with ABI v1 defaults.
+ *
+ * # Safety
+ *
+ * If `params` is non-null, it must point to writable memory large enough for
+ * `ordvec_search_params_t`.
+ */
+void ordvec_search_params_init(ordvec_search_params_t *params);
+
+/**
+ * Initialize an `ordvec_search_stats_t` with ABI v1 defaults.
+ *
+ * # Safety
+ *
+ * If `stats` is non-null, it must point to writable memory large enough for
+ * `ordvec_search_stats_t`.
+ */
+void ordvec_search_stats_init(ordvec_search_stats_t *stats);
+
+/**
+ * Load a `.tvrq` RankQuant or `.tvbm` Bitmap index.
+ *
+ * # Safety
+ *
+ * `path` must be a non-null, NUL-terminated 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);
+
+/**
+ * Copy metadata from a loaded index into `info_out`.
+ *
+ * # Safety
+ *
+ * `index` must be a live handle returned by `ordvec_index_load`. `info_out`
+ * must be non-null and point to writable memory for `ordvec_index_info_t`.
+ */
+ordvec_status_t ordvec_index_info(const ordvec_index_t *index, ordvec_index_info_t *info_out);
+
+/**
+ * Free a loaded index handle. `NULL` is accepted as a no-op.
+ *
+ * # Safety
+ *
+ * Non-null `index` must have been returned by `ordvec_index_load`, must not
+ * have been freed before, and must not race with any other call.
+ */
+void ordvec_index_free(ordvec_index_t *index);
+
+/**
+ * Run a synchronous single-query search.
+ *
+ * # Safety
+ *
+ * `index` must be a live handle returned by `ordvec_index_load`. All non-null
+ * pointers in `params`, `hits_out`, `returned_out`, and `stats_out` must be
+ * valid for the duration of the call according to the buffer sizes supplied by
+ * the caller. No pointer is retained after return.
+ */
+ordvec_status_t ordvec_index_search(const ordvec_index_t *index,
+                                    const ordvec_search_params_t *params,
+                                    ordvec_hit_t *hits_out,
+                                    uint64_t hits_capacity,
+                                    uint64_t *returned_out,
+                                    ordvec_search_stats_t *stats_out);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif  // __cplusplus
+
+#endif  /* ORDVEC_H */