[codex] document ordvec C API

[Fieldnote-Echo]

Summary

• add docs/c-api.md covering build/link instructions, a full C example, search modes, status/error semantics, stats, row IDs, lifetimes, thread safety, and v1 exclusions
• link the C API docs from the README
• update the threat model for the C ABI and Go wrapper boundary, panic containment, local stats/no logging posture, and handle lifetime contract

Validation

• cargo fmt --all --check
• cbindgen ordvec-ffi --config ordvec-ffi/cbindgen.toml --output ordvec-ffi/include/ordvec.h --verify
• cargo test
• cargo test -p ordvec-ffi
• cargo clippy --all-targets -- -D warnings
• cargo clippy -p ordvec-ffi --all-targets -- -D warnings
• cargo build -p ordvec-ffi
• full stack also validated with GOCACHE=/tmp/go-build go test -count=1 ./... and GOCACHE=/tmp/go-build go test -race -count=1 ./... from ordvec-go

Stack base: PR #101 / codex/c-abi-ffi. Next PR in stack: codex/go-wrapper.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[gemini-code-assist]

Code Review

This pull request updates the documentation and threat model to support the new C ABI and Go FFI bindings, including a new C API guide with a minimal example. The review feedback points out a potential buffer over-read in the C example if the index dimension exceeds the stack-allocated query buffer size, and notes that the threat register table in THREAT_MODEL.md needs to be updated to match the newly added and renumbered threat IDs.

[qodo-code-review]

Review Summary by Qodo

Document ordvec C API with comprehensive guide and threat model updates

📝 Documentation

Walkthroughs

Description

• Add comprehensive C API documentation covering build, linking, and usage
• Document ABI contracts, search modes, stats, threading, and v1 exclusions
• Update threat model to cover C ABI and Go wrapper FFI boundaries
• Link C API docs from README and update status date

Diagram

flowchart LR
  A["C API Documentation"] --> B["Build & Link Instructions"]
  A --> C["Minimal Example Code"]
  A --> D["ABI Contracts & Semantics"]
  A --> E["Search Modes & Stats"]
  A --> F["Threading & V1 Exclusions"]
  G["Threat Model Updates"] --> H["C ABI Defenses"]
  G --> I["Go FFI Boundary"]
  G --> J["FFI Threat Scenarios"]
  K["README"] --> L["Link to C API Docs"]

Loading

File Changes

1. docs/c-api.md 📝 Documentation +159/-0

New comprehensive C API documentation guide

• New comprehensive C API documentation file with 159 lines
• Covers build/link instructions with concrete cargo build and cc examples
• Includes minimal working C example demonstrating index load, info, and search
• Documents ABI contracts including status codes, struct initialization, and pointer borrowing
 semantics
• Details search modes (full vs subset), stats fields, threading guarantees, and v1 exclusions

docs/c-api.md

---

2. README.md 📝 Documentation +2/-0

Link C API documentation from README

• Add new "C ABI" section linking to docs/c-api.md in documentation index
• Positioned between "Index-file trust model" and "Formal proof spine" sections

README.md

---

3. THREAT_MODEL.md 📝 Documentation +57/-11

Expand threat model for C ABI and Go wrapper boundaries

• Update status date from 2026-05-25 to 2026-05-28
• Expand scope to explicitly cover C ABI, Go wrapper, and PyO3/maturin Python bindings
• Update FFI boundary description to reference "C/Python FFI boundaries" instead of just "Python FFI
 boundary"
• Add new section 4.1 "C ABI defenses" documenting ordvec-ffi validation, panic handling, and Go
 wrapper synchronization
• Introduce three new C ABI threat scenarios: THREAT-FFI-001 (panic/invalid input), THREAT-FFI-002
 (handle lifetime misuse), THREAT-FFI-003 (telemetry side channel)
• Renumber existing Python FFI threats from THREAT-FFI-001/002 to THREAT-FFI-004/005
• Add two new rows to attack surface table for "C ABI" and "Go FFI" boundaries
• Update failure contract language to mention "typed status codes in C/Go" alongside panic and
 ValueError

THREAT_MODEL.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0)

1. Unsafe query buffer example 🐞 Bug ⛨ Security

Description

The C “Minimal Example” allocates a fixed 1024-float query buffer but sets params.dim from the
loaded index, so for info.dim > 1024 the subsequent ordvec_index_search will read past the end
of query (undefined behavior / potential memory disclosure/crash). This is especially risky
because it’s copy-paste starter code.

Code

docs/c-api.md[R48-53]

Evidence

The docs example hardcodes a 1024-element query buffer but uses the runtime index dimension for
params.dim. The FFI implementation then constructs a slice of length dim from params.query,
which will read past the allocation when dim > 1024.

docs/c-api.md[48-53]
ordvec-ffi/src/lib.rs[425-438]

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 minimal C example uses `float query[1024]` but sets `params.dim = info.dim`. If an index’s `dim` is greater than 1024, `ordvec_index_search` will read `dim` floats via the provided pointer, causing an out-of-bounds read.

### Issue Context
In `ordvec-ffi`, `ordvec_index_search`/`validate_search` creates a Rust slice from the raw `query` pointer using the index dimension, so it will read exactly `dim` elements.

### Fix Focus Areas
- docs/c-api.md[48-53]

### Proposed fix
Update the example to allocate the query buffer based on `info.dim` (e.g., `calloc((size_t)info.dim, sizeof(float))`), check for allocation failure, and `free(query)` before returning. Alternatively, if you want a stack example, explicitly assert/guard `info.dim <= 1024` before setting `params.dim`, and document that limitation.

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

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fe55297e8f

ℹ️ 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".

[Copilot]

Pull request overview

Adds first-party documentation for the ordvec-ffi C ABI and updates repository docs to reflect the new FFI surfaces (C ABI and planned Go wrapper boundary) in the threat model.

Changes:

• Introduces docs/c-api.md with build/link instructions, a C usage example, and ABI v1 contracts (search modes, error/status semantics, stats, threading, exclusions).
• Links the new C API documentation from README.md.
• Expands THREAT_MODEL.md FFI coverage to include the C ABI and Go wrapper boundary, with additional threat entries and mitigations.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
THREAT_MODEL.md	Updates threat model scope and adds an FFI threat section covering C ABI (and Go wrapper notes).
README.md	Adds a documentation link to the new C ABI docs.
docs/c-api.md	New C API documentation including a minimal C example and ABI v1 contract details.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Fieldnote-Echo]

Addressed the remaining bot findings for this PR:

• The C API example now allocates query from info.dim with overflow/allocation checks and frees it on every return path.
• The example uses <inttypes.h> and PRIu64 for uint64_t output.
• The threat register now includes THREAT-FFI-001 through THREAT-FFI-005 with the C ABI and Python FFI entries aligned.
• The C ABI pointer wording now says it checks nullness and caller-supplied lengths, not provenance.
• The panic-status docs clarify that no unwind crosses the ABI, while Rust's default panic hook may still write stderr diagnostics.

Validation run locally on the stacked branch: cargo fmt --all --check, cbindgen --verify, and the Rust/FFI/Go gates reported on the stack.