# iqdb-build v1.0.0 — Stable

**The surface is committed.** iqdb-build has been feature-complete since v0.4.0 and
API-frozen since v0.5.0; v1.0.0 is the stability commitment. The public API is now
locked under SemVer for the 1.x series — no breaking changes until 2.0. There is
no code change from 0.6.0: this release is the promise, made once the Definition
of Done held.

## What is iqdb-build?

The bulk-construction layer of the iQDB vector database. Loading a million vectors
into an index one `insert` at a time is slow; `iqdb-build` is the fast path. It is
**generic over** `iqdb_index::Index`, so the same builder constructs and merges a
flat, HNSW, or IVF index — or a backend of your own — without ever naming a
concrete type. It adds no error type and no data type of its own, and has zero
`unsafe`.

## The 1.x surface

Committed and frozen until 2.0 (`iqdb_types::IqdbError` is `#[non_exhaustive]`, so
new error variants remain non-breaking; only additive, non-breaking changes are
made within 1.x):

- **Tier 1 (free functions)** — `build`, `build_into`, `merge`.
- **Tier 2 (`IndexBuilder<I>`)** — `new`, `with_config`, `with_shards`,
  `on_progress`, `dim`, `metric`, `config`, `shards`, `build`, `build_parallel`,
  `build_merged`, and `Clone`.
- **Tier 3 (trait seam)** — the `Mergeable` trait (how a backend absorbs another
  instance of itself), on top of `iqdb_index::Index` / `IndexCore`.
- **Types** — `BuildItem`, `BuildProgress`, `VERSION`.

## Why 1.0 now

The Definition of Done (DIRECTIVES §7) is satisfied:

- Compiles clean on Linux, macOS, and Windows, on stable and the 1.87 MSRV.
- `fmt`, `clippy -D warnings`, `test --all-features`, and `cargo doc -D warnings`
  are clean; `cargo deny` passes.
- No `unwrap`/`expect`/`todo!`/`dbg!` in shipping code; **zero `unsafe`**.
- A Tier-1 API exists and headlines the docs.
- Property tests cover every core invariant (completeness, equivalence,
  additivity, duplicate rejection, parallel completeness, merge equivalence); a
  `loom` model check covers the one concurrent path (the progress counter).
- Hot paths carry criterion benchmarks (sequential vs parallel build).
- Every public item is documented with a runnable example; five end-to-end
  examples and a consumer-simulation soak test ship with the crate.

The builder was also verified against the real `iqdb-flat` and `iqdb-hnsw`
backends during development. That cross-crate integration now lives in `iqdb-eval`
/ the engine workspace — where all crates are present — rather than this
standalone crate's CI, the same split `iqdb-flat` uses for its recall oracle.

## Breaking changes

**None.** No code change from 0.6.0; this is the SemVer commitment.

## Verification

```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 deny check
```

Green across the CI matrix (Linux, macOS, Windows) on stable and the 1.87 MSRV.

## After 1.0

Additive, non-breaking only: integration into the `iqdb` engine's bulk-ingestion
path, further benchmarks, and any new convenience that does not change the frozen
surface.

## Installation

```toml
[dependencies]
iqdb-build = "1.0"
```

## Documentation

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

---

**Full diff:** [`v0.6.0...v1.0.0`](https://github.com/jamesgober/iqdb-build/compare/v0.6.0...v1.0.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/iqdb-build/blob/main/CHANGELOG.md).
