# iqdb-build -- Roadmap
> Path from scaffold to a stable 1.0. Hard parts are front-loaded; each phase has hard exit criteria.
>
> **Anti-deferral rule:** no listed hard task moves to a later phase unless this file records the move and the reason.
---
## v0.1.0 -- Scaffold (DONE)
Compiles, CI green, structure correct, no domain logic.
- [x] Manifest, README, CHANGELOG, REPS, license, CI, lints in place.
- [x] API surface sketched in `docs/API.md`.
---
## v0.2.0 -- `IndexBuilder<I>` + sequential build/build_into (DONE)
`IndexBuilder<I>` plus the Tier-1 `build` / `build_into` free functions; the full
sequential construction path. `build_into` is bound on the object-safe
`IndexCore`, so it also serves `&mut dyn IndexCore`.
Exit criteria:
- [x] Every public item has rustdoc + a runnable example.
- [x] Core invariants property-tested (completeness, equivalence, additivity,
duplicate rejection).
---
## v0.3.0 -- rayon parallel construction + batching (DONE)
`IndexBuilder::build_parallel` splits the input into shards and constructs one
sub-index per shard on rayon's pool; `with_shards` / `shards` control the count.
rayon is a core dependency. Merging the shards into one index is deferred to 0.4
(per the split -> build-parallel -> merge design in DIRECTIVES §1).
Exit criteria:
- [x] New surface tested (completeness, clamping, id partitioning, single-shard
parity) and benchmarked (`build_parallel` criterion group vs the sequential
baseline).
---
## v0.4.0 -- index merging (`Mergeable`) + progress reporting + feature freeze (DONE)
The `Mergeable` trait (owned here, since `iqdb-index` is frozen at 1.0), the
`merge` free function, and `IndexBuilder::build_merged` for the full
split -> build-parallel -> merge pipeline. `on_progress` / `BuildProgress` report
shard completion.
Exit criteria:
- [x] No `todo!`/`unimplemented!`. Feature freeze declared (the public surface is
complete; remaining work is `loom` hardening + stabilization).
---
## v0.5.0 -- concurrent-build correctness + API freeze (DONE)
`loom` model check (`tests/loom_iqdb_build.rs`) over the only shared-state path in
parallel construction — the progress counter — proving exact counting under every
interleaving. The public API is frozen for the rest of the 0.x series and until
2.0 once 1.0 ships.
### Frozen public API (recorded here)
- `VERSION: &str`
- `BuildItem` (type alias for `(VectorId, Arc<[f32]>, Option<Metadata>)`)
- free fns: `build`, `build_into`, `merge`
- `IndexBuilder<I>`: `new`, `with_config`, `with_shards`, `on_progress`, `dim`,
`metric`, `config`, `shards`, `build`, `build_parallel`, `build_merged`; `Clone`
- `Mergeable` trait: `merge`
- `BuildProgress`: fields `shards_completed`, `shards_total`
Exit criteria:
- [x] Public API frozen (recorded above). `cargo audit` + `cargo deny` clean.
---
## v0.6.0 -- Alpha: entering the validation band (DONE)
The public API is unchanged from the 0.5.0 freeze; numbered 0.6.0 to align with
the family version line. The new surface is a self-contained end-to-end soak test
(`tests/consumer_simulation.rs`) that drives the whole public surface the way the
engine would.
**Cross-crate integration lives elsewhere.** Validating the builder against the
*real* `iqdb-flat` / `iqdb-hnsw` backends requires all crates present at once,
which the standalone repo's CI does not provide (siblings are neither checked out
nor published). That integration belongs in `iqdb-eval` / the engine workspace,
not in this crate's tests — the same split `iqdb-flat` records for its recall
oracle. (An earlier attempt to wire path dev-deps to the siblings broke CI and was
reverted.)
- [x] Self-contained consumer-simulation soak test; version aligned to the family.
---
## v1.0.0 -- Stable (DONE)
Released straight from the 0.6.0 alpha once the Definition of Done was met — the
0.7–0.9 beta/RC band was collapsed (the crate's own work was complete; the only
remaining activity, engine integration, lives downstream and does not gate this
crate's stability, the same way `iqdb-flat` reached 1.0).
- [x] Definition of Done (DIRECTIVES section 7) satisfied.
- [x] Public API frozen until 2.0 (frozen surface recorded under v0.5.0 above).
- [x] Release note written (`docs/release/v1.0.0.md`). Publish + tag: maintainer.
**Post-1.0 (additive, non-breaking only):** engine integration in `iqdb` /
`iqdb-eval`; the `iqdb-index`-side `Mergeable` if it ever migrates there; further
benchmarks.
---
## Out of scope for 1.0
- The indexes themselves -- generic over them.
- Distributed build coordination -- reserved phase.