# `:vector-index-api` — общий интерфейс ANN-индекса

## Что это

Pure-API модуль: интерфейсы и data-классы, общие для любых бэкендов
ANN-поиска (approximate nearest neighbor). Никаких реализаций и
платформенных зависимостей — только контракт.

Используется как стабильный API-фасад между кодом, который хочет
искать по embeddings, и реализациями (JVector, ksqlite, sqlite-vec,
inmemory, ...). При замене бэкенда вызывающий код не меняется.

## Где используется

Реализации:

- `:vector-index-jvector` — JVM-only ANN поверх JVector (Datadog).
  RAM-only. Самый быстрый для больших датасетов.
- `:vector-index-ksqlite` — KMP brute-force cosine в SQLite. Подходит
  для ≤10K записей, имеет persistence "бесплатно".

## Что внутри

```kotlin
interface VectorIndexStore : AutoCloseable {
    val dimension: Int
    suspend fun getSize(): Long
    suspend fun search(embedding: FloatArray, limit: Int): List<VectorSearchResult>
}

interface MutableVectorIndexStore : VectorIndexStore {
    suspend fun add(id: String?, embedding: FloatArray, payload: String?): VectorIndex
    suspend fun delete(id: String): Boolean
    suspend fun clear(): Long
}

class VectorIndex(val id: String, val embedding: FloatArray, val payload: String?)
// equals/hashCode/toString переопределены руками (FloatArray не работает
// корректно в data class).

data class VectorSearchResult(val index: VectorIndex, val score: Float)

class VectorIndexAlreadyExistsException : Exception()
```

**Конвенции:**
- `id: String?` в `add()` — если `null`, реализация генерирует сама
  (формат на усмотрении реализации).
- `payload: String?` — opaque строка, реализация хранит как есть и не
  интерпретирует.
- `dimension` фиксируется на уровне индекса и проверяется при `add()` /
  `search()`.
- Все мутации и чтения — `suspend` для совместимости с нативной
  блокировкой в JNI/JVector и I/O в ksqlite.
- `search()` возвращает топ-K, отсортированный по убыванию score.
- `close()` обязателен (наследуется от `AutoCloseable`).

## Цели сборки

KMP (все 9): jvm + linuxX64/Arm64 + macosX64/Arm64 + iosX64/Arm64/
SimulatorArm64 + mingwX64. Pure-Kotlin stdlib + `kotlinx-coroutines-core`,
никаких нативных зависимостей — поэтому собирается везде.

## Текущий статус

API стабилизирован. Реализации покрывают JVM и KMP-without-Apple.

## Чего здесь НЕТ

- Никакой сериализации (`@Serializable`) — типы транспортируются
  через интерфейсы, не через JSON.
- Никаких auto-generated id правил — реализации решают сами.
- Никаких фильтров на `search()` — чистый ANN без predicate push-down
  (если нужен фильтр, делать на стороне вызывающего кода после `search`).