# iqdb-flat v0.5.0 — Large-scan correctness + API freeze

**The surface is locked.** v0.4.0 made the index feature-complete; v0.5.0 commits
the public API for the 1.x series and pins flat's defining guarantee — that it is
the exact recall oracle — at scale. There is no new API here. What you build
against today keeps compiling through 1.0 and beyond; only additive,
non-breaking changes are made from this point.

## What is iqdb-flat?

The brute-force exact nearest-neighbour layer of the iQDB vector database. It
scans every stored vector, computes the true distance, and returns the top-`k` —
always correct, by construction. It is a real index for small corpora and the
**recall ground truth** every approximate index (HNSW, IVF) is measured against.

## What's in 0.5.0

### Large-scan correctness

flat's results are *defined* to be the oracle, so the oracle has to be right at
scale, not just in unit tests. `tests/large_scan.rs` adds:

- **Bit-for-bit equality at N = 20_000.** flat's top-`k` is asserted identical —
  ids, distances, and order — to an independent naive full scan. The vectors are
  small integers, so every Manhattan and DotProduct distance is an exact `f32`
  regardless of accumulation order; there is no roundoff to tolerate, so the
  match is exact rather than within-epsilon.
- **Full-scan permutation check.** A `k == N` search returns every id exactly
  once, in best-first order — the `swap_remove` / sequence-stamp storage
  invariants hold across 20k rows, not just the small churn tests.

### API freeze

The committed surface is recorded in [`dev/ROADMAP.md`](../../dev/ROADMAP.md)
(§ v0.5.0):

- `VERSION`, the `Hit` re-export, `FlatConfig`, and `FlatIndex`
  (`new_unconfigured`, `dim`, `metric`, `len`, `is_empty`).
- `impl Index for FlatIndex` (`type Config = FlatConfig`) and the full
  `IndexCore` implementation.
- The `parallel` feature is internal-only and does not change the surface.

Behavioural contracts are frozen alongside it: smaller-is-nearer ordering across
all five metrics, the stable insertion-order tiebreaker, no panics on any input,
and zero `unsafe`. `iqdb_types::IqdbError` is `#[non_exhaustive]`, so new error
variants remain non-breaking.

## Breaking changes

**None.** The public API is unchanged from v0.4.0; this release is the stability
commitment for the 1.x series.

## Verification

Clean across the CI matrix (Linux, macOS, Windows) on stable and the 1.87 MSRV,
default features and `--all-features`:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo audit
cargo deny check
```

## What's next

- **0.6.x → 0.9.x — alpha/beta/RC.** Integration against real approximate-index
  consumers (HNSW, IVF) using flat as the recall oracle, broader testing, final
  benchmarks, and documentation polish.
- **1.0.0 — stable**, once the Definition of Done holds and the API has proven
  itself against those consumers.
- A contiguous row-major storage layout remains a tracked post-freeze internal
  optimisation; it does not affect the frozen API.

## Installation

```toml
[dependencies]
iqdb-flat = "0.5"
```

## Documentation

- [README](https://github.com/jamesgober/iqdb-flat/blob/main/README.md)
- [API reference](https://github.com/jamesgober/iqdb-flat/blob/main/docs/API.md)
- [ROADMAP](https://github.com/jamesgober/iqdb-flat/blob/main/dev/ROADMAP.md)
- [Standards (REPS)](https://github.com/jamesgober/iqdb-flat/blob/main/REPS.md)
- [CHANGELOG](https://github.com/jamesgober/iqdb-flat/blob/main/CHANGELOG.md)

---

**Full diff:** [`v0.4.0...v0.5.0`](https://github.com/jamesgober/iqdb-flat/compare/v0.4.0...v0.5.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/iqdb-flat/blob/main/CHANGELOG.md).
