# iqdb-build v0.5.0 — Concurrent-build correctness & API freeze

**The surface is settled.** v0.4.0 made `iqdb-build` feature-complete; v0.5.0
proves the one concurrent path correct under `loom` and freezes the public API.
From here to 1.0 the work is integration against real consumers and
stabilization — no new surface.

## What is iqdb-build?

The bulk-construction layer of the iQDB vector database — generic over
`iqdb_index::Index`, so the same builder constructs and merges flat, HNSW, IVF, or
custom backends. It splits input into shards, builds them in parallel, and merges
them back into one index.

## What's new in 0.5.0

- **`loom` model check.** `build_parallel` builds each shard in isolation — the
  shards share nothing — so the sole cross-thread interaction is the
  `AtomicUsize` that counts shard completions and drives the `on_progress`
  callback. rayon's pool cannot be driven by `loom`, so `tests/loom_iqdb_build.rs`
  models that counting discipline directly with `loom`'s threads and atomics and
  exhaustively checks every interleaving: the final count is exact, and each
  completion is reported exactly once — no repeats, no gaps. The test compiles
  only under `--cfg loom` (the dedicated CI job).
- **`cfg(loom)` registered** in `[lints.rust]` so the gated test never trips
  `unexpected_cfgs` under `-D warnings`.
- **Public API frozen.** The complete, frozen surface is recorded in
  `dev/ROADMAP.md`.

## The frozen surface

- `VERSION`
- `BuildItem`
- free functions: `build`, `build_into`, `merge`
- `IndexBuilder<I>`: `new`, `with_config`, `with_shards`, `on_progress`, `dim`,
  `metric`, `config`, `shards`, `build`, `build_parallel`, `build_merged`, `Clone`
- `Mergeable` (with `merge`)
- `BuildProgress` (`shards_completed`, `shards_total`)

## Concurrency model

The crate has exactly one shared-mutable path — the shard-completion counter —
and zero `unsafe`. The `loom` check covers that path exhaustively; the shards
themselves are independent, so there is nothing else to model.

## Breaking changes

None. Purely additive over 0.4.0 (a test and a lint registration).

## 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
RUSTFLAGS="--cfg loom" cargo test --test loom_iqdb_build   # the model check
cargo deny check
```

Tested across the CI matrix (Linux, macOS, Windows) on stable and the 1.87 MSRV,
plus the dedicated `loom` job.

## What's next

- **0.6 → 0.7** — integrate against the real index backends (`iqdb-flat`,
  `iqdb-hnsw`, `iqdb-ivf`) and `iqdb`; MINOR-compatible additions only.
- **0.8 (beta)** — bug fixes, broader testing, final benchmarks.
- **0.9 (rc)** — critical fixes and doc polish.
- **1.0.0** — stable; API frozen until 2.0.

## Installation

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

## 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)

---

**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/iqdb-build/blob/main/CHANGELOG.md).
