docs: NATIVE-COMPATIBILITY.md checklist for linuxX64 bring-up

NATIVE-COMPATIBILITY.md

@@ -0,0 +1,147 @@
+# Совместимость с native (linuxX64) — чеклист
+
+Цель: `:standalone` собирается и запускается как `linuxX64` executable (и потенциально
+остальные нативные таргеты KMP). Текущее состояние — JVM-only executable на
+`runJvm`-таске.
+
+Формат: `- N. [ ]` — задача; `- N. [x]` — выполнена; `- N. [-]` — отменена/не нужна.
+Решения (что выбрали и почему) — курсивом внизу пункта.
+
+---
+
+## Блок 1. Подготовка (уже сделана или тривиальная)
+
+- 1. [x] **Замена `java.util.UUID` на KMP-stdlib (`kotlin.uuid.Uuid`).** Helper `Ids.new(prefix)` в `standalone/src/commonMain/.../persistence/Ids.kt`, три call-site (`ChatAgent`, `ChatConversation`, `SqliteWorkingMemoryStore`). Коммит `e816d8d`.
+- 2. [x] **HTTP-движок: `ktor-server-netty` → `ktor-server-cio`.** Netty — JVM-only; CIO — KMP (jvm + linuxX64 + ios/...). Каталог-эntry Netty оставлен в `libs.versions.toml` на случай отката. Коммит `e816d8d`.
+
+## Блок 2. Библиотеки litert-kmp (наши)
+
+- 3. [ ] **`litert-api`: добавить `linuxX64()` в `kotlin{}`.**
+  Сейчас только `androidTarget() + jvm()`. commonMain уже KMP-ready (только
+  `kotlinx-coroutines-core`). Объём: одна строка в `litert-api/build.gradle.kts`,
+  один `litert-api-linuxx64`-артефакт публикуется в Nexus.
+- 4. [ ] **`litert-openai`: добавить `linuxX64()` в `kotlin{}`.**
+  Та же история. commonMain deps (`ktor-client-core`, `ktor-client-cio`,
+  `kotlinx-serialization-json`) — все KMP с готовыми linuxX64-артефактами.
+  Объём: одна строка + проверить, что Android-only фичи (если есть) изолированы
+  в `androidMain` (сейчас модуль не имеет `androidMain`-специфичного кода).
+  *Каталог-запись `litert-openai-jvm` → переименовать в `litert-openai`*
+  (чтобы Linux-таргет подтягивал `-linuxx64`-вариант автоматически, не нужно
+  ручного `when target`).
+- 5. [-] **`litert-google`: linuxX64 — невозможно.** Upstream-блокер: Google
+  публикует `litertlm-android` (AAR с `.so`) и `litertlm-jvm` (fat-jar с `.so`
+  для linux/mac/win JVM), но НЕ нативного `litertlm-linuxx64`. Без правки
+  upstream LiteRT-LM KMP-враппер для linuxX64 не напишется. Варианты:
+  (a) выкинуть `litert-google` на linuxX64 (`backend=google` → отказ); (b)
+  альтернативный движок (llama.cpp через JNI/Kotlin/Native);
+  (c) upstream PR в `litertlm`. *Решение: (a) для v1 linuxX64 — упасть с
+  понятной ошибкой `LlmBackend.GOOGLE is not supported on this platform`
+  вместо reflection-fallback на JVM .so, который на linuxX64 не сработает бы.*
+
+## Блок 3. Наш `:server` модуль
+
+- 6. [ ] **Переписать `:server` с `kotlin("jvm")` на `kotlin("multiplatform")` с
+  `jvm() + linuxX64()`.** Текущий контракт `Route.agentikAgent(agent, path)` —
+  чистый Ktor Route, не зависит от engine. commonMain: Ktor core + SSE +
+  ContentNegotiation + kotlinx-serialization-json. jvmMain: текущее
+  содержимое. linuxX64Main: тот же commonMain + ktor-server-cio engine для
+  embedded-сервера, если `Main.kt` на linuxX64 будет поднимать сервер сам
+  (иначе — оставить сервер только в jvmMain/:standalone, а `:server`-маршруты
+  вызывать из native-обёртки). Объём: ~30 строк gradle + перенос imports.
+  *Решение: на linuxX64 `:server`-роуты вызываются тем же `Main.kt`-ом через
+  `embeddedServer(CIO, ...)` — engine-нейтральность уже заложена.*
+
+## Блок 4. Наш `:proto` модуль
+
+- 7. [ ] **`:proto`: заменить `kotlinx.datetime.Instant` на `kotlin.time.Instant`.**
+  Per Memory #3708 — typealias `kotlinx.datetime.Instant` deprecated в
+  kotlinx-datetime 0.8.0, нужно перейти на `kotlin.time.Instant`
+  (он же в commonMain). После: дропнуть `api(libs.kotlinx.datetime)` из
+  commonMain, и из `libs.versions.toml`. Объём: замена импорта + типов +
+  возможно `InstantSerializer` в `:server/src/main/.../Serialization.kt`.
+
+## Блок 5. SQLDelight — нативный драйвер
+
+- 8. [ ] **`sqlite-driver` (JVM/JDBC) → `native-driver` для linuxX64.**
+  В jvmMain: оставить `sqlite-driver` (JDBC over `java.sql.DriverManager`).
+  В linuxX64Main: добавить `native-driver` — KMP driver поверх cinterop
+  с `libsqlite3` (нужен `-lsqlite3` linker-флаг или `SQLiteBundle` из
+  `co.touchlab:sqliter` для бандлинга). Создать `SqliteStores`-
+  нейтральный интерфейс хранилищ (он уже есть в `commonMain`), разделить
+  `jvmMain/SqliteStores.kt` и `linuxX64Main/SqliteStoresNative.kt` —
+  оба реализуют один `commonMain`-интерфейс. Объём: ~150 строк
+  (новый `SqliteStoresNative.kt` + gradle wiring).
+  *Решение по бандлу: использовать `SQLiteBundle` из
+  `co.touchlab:sqliter` (KMP-обёртка, тянет свой libsqlite) — без
+  зависимости от системного libsqlite3, бинарь работает на любом linux.*
+- 9. [ ] **Тесты SQLite переписать на commonTest + `expect`/`actual` обёртку.**
+  `inMemory()`-открытие в `native-driver` использует другой API (нет
+  JDBC `:memory:`). Объём: один `expect fun openInMemory()` в commonMain +
+  два `actual` (JDBC `jdbc:sqlite::memory:` / native-driver нативный API).
+
+## Блок 6. Внешние либы (`a2a-server`, `agui-server`) — наши
+
+- 10. [ ] **`agui-server`: проверить KMP-готовность.** Per Memory #3561 — KMP
+  jvm+native. *Если по факту уже KMP — только подключить `linuxX64`-артефакт в `:standalone`; если JVM-only — пункт 11.*
+- 11. [ ] **`a2a-server`: JVM-only → KMP.** Per Memory #3561 — JVM-only
+  (client/server; shared уже KMP). Без native-таргета весь стек A2A
+  недоступен на linuxX64. Объём: переписать на `multiplatform`,
+  выделить engine-нейтральную маршрутизацию. *Альтернатива: на linuxX64
+  не подключать a2a-server вообще (только `:server`-фасад). Решение
+  отложено — зависит от того, нужен ли нативный MCP-юзер-кейс вообще
+  подключаться к A2A.*
+
+## Блок 7. `:standalone` — добавить native target
+
+- 12. [ ] **`standalone/build.gradle.kts`: добавить `linuxX64()` и
+  `linuxX64Main`/`linuxX64Test` source-sets.** В `linuxX64Main`:
+  `:server` (после п.6), `litert-openai` (после п.4), `litert-api`
+  (после п.3), `ktor-server-cio` (engine), `ktor-client-cio`,
+  `kotlin-sdk-client` (MCP — KMP, готов), `kotlinx-io` (KMP, готов).
+  Исключить `litert-google` (п.5) и `a2a-server` (п.11) из linuxX64Main.
+- 13. [ ] **`Main.kt`: разделить на `commonMain` (бизнес-логика: создание
+  ChatAgent, MCP, LlmConfig) + `jvmMain`/`linuxX64Main` (выбор engine,
+  embeddedServer).** embeddedServer(CIO, …) — один и тот же код на обеих
+  платформах, KMP-нейтрален. Главное отличие — `SqliteStores.open()` и
+  обработка GOOGLE-бэкенда на linuxX64 (fail-fast).
+
+## Блок 8. Тесты и CI
+
+- 14. [ ] **`linuxX64Test` source-set.** Покрыть те же 44 теста на
+  native: должен зелёный прогон через `./gradlew :standalone:linuxX64Test`.
+  SQLDelight-тесты на native требуют `libsqlite3`/`SQLiteBundle`
+  на машине (CI-linux предоставляет).
+- 15. [ ] **Smoke e2e на linuxX64.** Запустить
+  `./gradlew :standalone:runLinuxX64` локально, проверить
+  `POST /agentik/conversations` → 201, цикл с реальным LLM через OpenAI
+  backend; убедиться что LiteRT-LM GOOGLE не подключается (отказ с
+  понятной ошибкой).
+
+## Блок 9. Дистрибуция native-бинаря
+
+- 16. [ ] **`runLinuxX64`-таска через KMP binaries DSL.** После добавления
+  `linuxX64()` KMP генерирует её автоматически — нужно только убедиться
+  что `binaries { executable { mainClass.set("pw.binom.agentik.standalone.MainKt") } }`
+  работает для linuxX64 (по аналогии с уже настроенным `runJvm`).
+- 17. [ ] **Дистрибутив `.tar`/`.zip`/`AppImage/Docker`.** KMP
+  `assembleDist` для linuxX64 делает tar.gz/zip. Для прод-дистрибуции —
+  Docker-образ (`FROM gcr.io/distroless/cc`) или AppImage. Объём:
+  ~50 строк Dockerfile + GitHub Action.
+
+---
+
+## Что НЕ блокирует linuxX64 (закрыто или тривиально)
+
+- `kotlinx-coroutines-core` — KMP linuxX64 ✓
+- `kotlinx-serialization-json` — KMP linuxX64 ✓
+- `kotlinx-io` — KMP linuxX64 (используется в MCP stdio-transport) ✓
+- `kotlin-sdk-client` (MCP) — KMP full targets ✓
+- `ktor-server-core`, `ktor-server-sse`, `ktor-server-cio` — KMP linuxX64 ✓
+- `ktor-client-core`, `ktor-client-cio` — KMP linuxX64 ✓
+- `pw.binom.uuid` — **отсутствует** в проекте (используем `kotlin.uuid`) ✓
+
+## Жёсткие блокеры (не обойти без upstream-работы)
+
+- `litertlm-jvm` → нужен `litertlm-native` от Google (см. п.5)
+- `a2a-server` JVM-only (см. п.11) — нужно переписать или явно не подключать
+- `agui-server` KMP-готовность под вопросом (см. п.10)