# iqdb-flat -- Engineering Directives
> Engineering standards and the definition of done for this project. Read alongside `REPS.md` (repository root, authoritative) and `dev/ROADMAP.md` (current phase). If anything here conflicts with `REPS.md`, `REPS.md` wins.
---
## 0. Philosophy
This library crate is built and maintained to a production standard and treated as a flagship piece of work. The full path is planned end to end, then built one verified step at a time. Cookie-cutter patterns are a starting point to improve on, not a finish line. Where the best available choice is unclear, it is settled before code is committed. "Good enough" is treated as a defect.
---
## 1. What this is
iqdb-flat is brute-force exact nearest-neighbor search: the simplest possible index and the ground truth for every recall benchmark. It is built to be fast enough to be a real choice for small datasets, not just a reference. It is the first and simplest consumer of the `Index` trait, so it doubles as the trait's design validation.
---
## 2. Scope and change control
Source, tests, benches, examples, docs, and build/CI configuration are all in scope for normal work. `REPS.md`, license files, and the lint configs (`clippy.toml`, `rustfmt.toml`) are stable and changed only deliberately. Work that falls outside the current phase is recorded in `dev/ROADMAP.md` with rationale before it is taken on.
---
## 3. Engineering law (non-negotiable)
- **Performance** -- peak performance is the baseline. Borrow over clone; avoid allocation on hot paths in steady state; inline small helpers. No "faster" claim ships without `criterion` numbers.
- **Concurrency** -- correctness under contention is proven, not assumed. Lock-free or shared-state paths carry `loom` model checks.
- **Correctness** -- the defining invariants (section 8) are covered by property-based tests, not only examples.
- **Security** -- all untrusted input is validated; every allocation is bounded; library code never panics on hostile input; parse and recovery paths are fuzzed.
- **Architecture** -- SOLID, KISS, YAGNI. One responsibility per unit. Trait seams are the extension points.
- **Cross-platform** -- Linux, macOS, and Windows are first-class and verified by the CI matrix.
- **Error handling** -- every fallible path returns `Result`; the domain error type is generated with `error-forge`; errors are never silently swallowed.
- **Production-ready** -- no commented-out code, no stray `println!`/`dbg!`; every public item carries rustdoc with a runnable example.
---
## 4. The tiered-API mandate
Tier 1 covers the entire common case in a handful of calls, with no builder and no generics to name. Tier 2 is the builder for tuning. Tier 3 is the trait seam for custom backends. Shipping only the advanced surface is a failure of the design, not a feature.
---
## 5. Testing
- Unit tests per module: happy path plus edge cases.
- Property-based tests (`proptest`) for every core invariant in section 8.
- `loom` model checks for every concurrent or lock-free path.
- Integration tests where I/O, persistence, or failure recovery matter.
- `criterion` benchmarks on hot paths, with tracked baselines; a regression over 5% blocks a release.
---
## 6. Documentation, versioning, release
`docs/API.md` stays current and the README leads with the Tier-1 surface. Strict SemVer; any on-disk or wire format is called out across 0.x and frozen at 1.0. The changelog follows Keep a Changelog 1.1.0. Error and config enums are `#[non_exhaustive]`. Documentation reads in a clear, human voice.
---
## 7. Definition of done (all true, or it is not done)
1. Compiles clean on Linux/macOS/Windows, on stable and MSRV.
2. `fmt`, `clippy -D warnings`, `test --all-features`, and `cargo doc -D warnings` are clean.
3. `cargo audit` and `cargo deny check` pass.
4. No `unwrap`/`expect`/`todo!`/`dbg!` in shipping code; `unsafe` only with a `// SAFETY:` note (target: zero `unsafe`).
5. A Tier-1 API exists and headlines the docs.
6. Property tests cover every section-8 invariant; `loom` covers every concurrent path.
7. Hot-path changes carry benchmarks; no regression over 5%.
8. Every public item is documented with an example; `docs/API.md`, README, and version metadata are updated.
9. Changes are recorded under `[Unreleased]` in the changelog.
---
## 8. Project-specific invariants
Stack: Rust edition 2024, MSRV 1.87. Errors via `error-forge`. Tests via `cargo test` + `criterion` + `loom` + `proptest`.
- Flat results are the correctness oracle: approximate indexes are validated against them via recall@k.
- If flat search cannot fit the `Index` trait cleanly, the trait is wrong and gets fixed, not worked around.
Per-phase exit criteria in `dev/ROADMAP.md` encode these; each guarantee has a property test before the phase that introduces it can close.
---
## 9. Integration points
- `iqdb-types`: vectors, ids, metadata
- `iqdb-distance`: the distance kernels
- `iqdb-index`: implements the `Index` trait
- `iqdb-eval`: uses it to generate ground truth
<sub>Copyright © 2026 <strong>James Gober</strong>.</sub>