refactor(storage): split MessageStore into :message-log-api
ci / JVM build + tests (push) Successful in 6m15s

Выделяет append-only message log в отдельный KMP-модуль.
Цель — разделить ДВЕ сущности по своей природе:

  :message-log-api  — append-only audit log (User/Assistant/ToolCall/
                       ToolResult/Error). Никаких update, только insert + read.
                       Это иммутабельная история диалога.

  :working-memory-api — mutable runtime context (compact, summary, WM order).
                          Live state. Compaction-логика.

Раньше оба жили в :message-store-api, что:
  - смешивало контракты: append-only audit vs mutable runtime;
  - делало невозможным лёгкого клиента который читает только audit log
    без WM-runtime зависимости;
  - затрудняло compaction-логике жить в одном модуле с audit-записью.

Миграция:
  - В :message-log-api переехали: Content, MessageRecord, MessageStore,
    MessageContext (с MessageOrigin), MessageEvent, TokenStats, TurnTokens,
    helpers (encode/decodeBodyPayload, MessageBodyPayload, BodyDecoded).
    Пакет pw.binom.agentik.messageLog.
  - В :message-store-api остались: ConversationStore, ConversationRecord,
    ReflectionStore, Ids, legacy events.EventStore (paginated replay).
    Пакет pw.binom.agentik.messageStore.
  - :working-memory-api: обновил deps (api → :message-log-api для Content/MessageContext).
  - 23 consumer-файла обновлены (FQN renames).
  - storage-sqlite/ksqlite: убраны недостижимые ветки Summary/System
    (эти synthetic records живут ТОЛЬКО в :working-memory-api, не попадают
    в audit log :message-log-api).

Файлы:
  + :message-log-api (5 файлов, ~280 строк)
  - :message-store-api (5 файлов, ~430 строк)
  ~ 23 файла обновлены

Совместимость схем не меняется. Все 5 storage impl'ов (3 backend × 5 store)
работают на тех же таблицах.
This commit is contained in:
2026-09-20 17:21:46 +03:00
parent a0b1209457
commit 15f3952eba
43 changed files with 406 additions and 605 deletions
@@ -1,29 +0,0 @@
package pw.binom.agentik.messageStore
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
/**
* Часть контента сообщения на уровне хранилища.
*
* Намеренно НЕ зависит от [pw.binom.agentik.proto.Content] — маппинг
* `:proto.Content ↔ Content` живёт в `Mapping.kt`. Структурно типы
* идентичны, но даёт возможность заменить transport-протокол без миграции
* таблиц.
*
* Image сериализуется в JSON через base64 (стандарт для kotlinx-serialization).
*/
@Serializable
sealed interface Content {
@Serializable
@SerialName("text")
data class Text(val body: String) : Content
@Serializable
@SerialName("image")
data class Image(val data: ByteArray, val mime: String) : Content {
override fun equals(other: Any?): Boolean =
this === other || (other is Image && mime == other.mime && data.contentEquals(other.data))
override fun hashCode(): Int = 31 * mime.hashCode() + data.contentHashCode()
}
}
@@ -1,40 +0,0 @@
package pw.binom.agentik.messageStore
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.JsonElement
/**
* Контекст инициации хода (кто/что и почему).
*
* Дубликат типа из `:proto` (`pw.binom.agentik.proto.MessageContext`):
* живёт в `:storage-core` чтобы не тащить `:proto` в слой хранения данных.
* Маппинг между ними — в `MessageRecord.toProto()` / `ProtoMessage.toStorage()`.
*
* Используется:
* - в `MessageRecord.UserMessage.context` — фиксируется в audit log;
* - в `WorkingMemoryEntry.User.context` — попадает в LLM-нагрузку
* как префикс к user-тексту (для не-USER origin'ов).
*
* Сериализация в `payload_json` (SQLite) — через kotlinx-serialization,
* формат snake_case для enum origin.
*/
@Serializable
enum class MessageOrigin {
@SerialName("user")
USER,
@SerialName("system")
SYSTEM,
@SerialName("event")
EVENT,
}
@Serializable
data class MessageContext(
val origin: MessageOrigin,
val description: String? = null,
val sourceId: String? = null,
val metadata: JsonElement? = null,
)
@@ -1,144 +0,0 @@
package pw.binom.agentik.messageStore
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlin.time.Instant
/**
* Token usage одного assistant turn'а: сколько токенов модель обработала
* на входе (system + history + tools + user message) и сколько сгенерировала
* (assistant text + tool calls + tool results, всё что LiteConversation
* добавила к истории за этот turn).
*
* `input` — снимок [LiteConversation.tokenCount] перед первым send() в turn'е
* (после подготовки user-сообщения). `output` — дельта после завершения turn'а
* (включая все tool loop итерации).
*
* Persisted в `message.payload_json` — никаких schema-миграций при добавлении
* полей. Optional: `null` для исторических сообщений или для бэкендов, не
* отдающих tokenCount (например off-line embedded LLM без контекст-счётчика).
*/
@Serializable
data class TurnTokens(
val input: Int,
val output: Int,
) {
val total: Int get() = input + output
init {
require(input >= 0) { "input tokens must be non-negative, got $input" }
require(output >= 0) { "output tokens must be non-negative, got $output" }
}
}
/**
* Запись в таблице `message` (append-only audit) и `working_memory` (mutable view).
*
* Использует sealed-иерархию: подтипы `User`/`Assistant`/`ToolCall`/`ToolResult`
* живут и там, и там. `Summary`/`System` — только в `working_memory`
* (синтетические строки, созданные при суммаризации или как system-prompt).
*
* Все подтипы несут [id] (UUID, стабильный между лайв-стримом Event и историей),
* [conversationId] и [createdAt].
*
* Поля, специфичные для подтипа, сериализуются в JSON в `payload_json`
* колонке SQLite — это даёт гибкость без миграций при добавлении полей.
*/
@Serializable
sealed interface MessageRecord {
val id: String
val conversationId: String
val createdAt: Instant
/** Подтип сообщения с телом из [Content]. */
@Serializable
sealed interface Body : MessageRecord {
val content: List<Content>
}
@Serializable
@SerialName("user")
data class UserMessage(
override val id: String,
override val conversationId: String,
override val content: List<Content>,
override val createdAt: Instant,
/**
* Контекст инициации хода: кто/что вызвал этот turn. `null` —
* обычное user-сообщение. См. [MessageContext].
*
* Persisted через `payload_json` SQLite (см. `Payload.kt`).
*/
val context: MessageContext? = null,
) : Body
@Serializable
@SerialName("assistant")
data class AssistantMessage(
override val id: String,
override val conversationId: String,
override val content: List<Content>,
override val createdAt: Instant,
/**
* Token usage этого turn'а: сколько input+output токенов обработала
* модель. Заполняется в [ChatConversation.runTurn] через
* `LiteConversation.tokenCount()` (до/после send).
*/
val tokens: TurnTokens? = null,
) : Body
@Serializable
@SerialName("tool_call")
data class ToolCall(
override val id: String,
override val conversationId: String,
val toolName: String,
val toolTitle: String?,
val toolArgsJson: String,
override val createdAt: Instant,
) : MessageRecord
@Serializable
@SerialName("tool_result")
data class ToolResult(
override val id: String,
override val conversationId: String,
val toolCallId: String,
val result: String?,
override val createdAt: Instant,
) : MessageRecord
/**
* Терминальная запись провалившегося хода. Только audit log
* (в working_memory не пишется — модель не должна видеть ошибки прошлых ходов).
*/
@Serializable
@SerialName("error")
data class Error(
override val id: String,
override val conversationId: String,
val message: String,
val code: String?,
override val createdAt: Instant,
) : MessageRecord
/** Синтетическое: суммаризация старого контекста. Только в working_memory. */
@Serializable
@SerialName("summary")
data class Summary(
override val id: String,
override val conversationId: String,
val text: String,
override val createdAt: Instant,
) : MessageRecord
/** Синтетическое: system-prompt, введённый при создании диалога. Только в working_memory. */
@Serializable
@SerialName("system")
data class System(
override val id: String,
override val conversationId: String,
val text: String,
override val createdAt: Instant,
) : MessageRecord
}
@@ -1,56 +0,0 @@
package pw.binom.agentik.messageStore
import kotlinx.coroutines.flow.Flow
import kotlin.time.Instant
/**
* Суммарная статистика токенов диалога — aggregate по всем assistant-сообщениям
* в audit log. Делит input/output и считает число assistant-ходов.
*
* Используется:
* - В startup banner'е агента (см. `Main.kt` → "conversation stats").
* - На HTTP фасаде `/agentik/conversations/{id}/stats` (если будет endpoint).
* - В клиентских дашбордах для оценки cost.
*/
data class TokenStats(
val turns: Int,
val inputTokens: Long,
val outputTokens: Long,
) {
val totalTokens: Long get() = inputTokens + outputTokens
}
/**
* Append-only audit log сообщений (`message` table).
*
* Только `insert` и чтение. Никаких обновлений, никакого удаления (кроме
* каскадного удаления вместе с [ConversationStore.delete]).
*/
interface MessageStore : AutoCloseable {
/** Добавить запись в audit log. `conversationId` берётся из [MessageRecord.conversationId]. */
suspend fun append(record: MessageRecord)
/**
* Страница audit-сообщений диалога после [after] (UTC), отсортированная
* по `createdAt ASC`. Для первоначальной загрузки передай `Instant.DISTANT_PAST`.
*/
suspend fun list(conversationId: String, after: Instant, offset: Int, limit: Int): List<MessageRecord>
/** Все сообщения диалога, отсортированные по `createdAt ASC` (для rebuild working memory). */
suspend fun listAll(conversationId: String): List<MessageRecord>
/** Лайв-стрим новых сообщений (для SSE-подписчиков). По умолчанию — пустой. */
fun events(): Flow<MessageEvent> = kotlinx.coroutines.flow.emptyFlow()
/**
* Суммарная token-статистика по диалогу: input/output/turns. Один проход
* по всем assistant-сообщениям. Дёшево (на практике < 1мс на SQLite).
*/
suspend fun tokenStats(conversationId: String): TokenStats
}
sealed interface MessageEvent {
val conversationId: String
data class Appended(override val conversationId: String, val record: MessageRecord) : MessageEvent
}
@@ -1,79 +0,0 @@
package pw.binom.agentik.messageStore
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.builtins.ListSerializer
import kotlinx.serialization.json.Json
/**
* JSON-формат для тел user/assistant сообщений: список [Content], опционально
* с [MessageContext] (для user — кто инициировал ход) и [TurnTokens]
* (для assistant — сколько токенов стоил этот turn).
*
* Encoded-формат:
* ```
* {"content": [ ...Content ], "context": {...MessageContext?}, "tokens": {...TurnTokens?}}
* ```
*
* Backward compat: при чтении старых строк, где payload был просто
* `[ ... ]` (без обёртки), парсер падает на wrapper-формат и fallback'ит
* к `ListSerializer<Content>` — такие строки возвращаются с `context = null`,
* `tokens = null`.
*/
private val bodyJson = Json {
ignoreUnknownKeys = true
encodeDefaults = true
explicitNulls = false
}
@Serializable
data class MessageBodyPayload(
val content: List<Content>,
@SerialName("context")
val context: MessageContext? = null,
/**
* Token usage для assistant (input + output). `null` для user-сообщений,
* для исторических assistant-сообщений без метрики и для бэкендов без
* tokenCount() (off-line модели).
*/
val tokens: TurnTokens? = null,
)
/**
* Сериализует тело user (или assistant) сообщения в JSON-строку для
* `payload_json` SQLite. Для user может нести [context] — кто инициировал ход;
* для assistant может нести [tokens] — token usage этого turn'а.
*/
fun encodeBodyPayload(
content: List<Content>,
context: MessageContext? = null,
tokens: TurnTokens? = null,
): String = bodyJson.encodeToString(
MessageBodyPayload.serializer(),
MessageBodyPayload(content = content, context = context, tokens = tokens),
)
/**
* Десериализует тело сообщения: возвращает тройку `(content, context, tokens)`.
* Контекст и токены — null если:
* - поля отсутствуют в новом формате;
* - payload в старом plain-array формате (миграция не нужна — fallback).
*/
fun decodeBodyPayload(json: String): BodyDecoded = readPayload(json)
data class BodyDecoded(
val content: List<Content>,
val context: MessageContext?,
val tokens: TurnTokens? = null,
)
private fun readPayload(json: String): BodyDecoded {
return try {
val p = bodyJson.decodeFromString(MessageBodyPayload.serializer(), json)
BodyDecoded(p.content, p.context, p.tokens)
} catch (e: kotlinx.serialization.SerializationException) {
// Старый формат: голый JSON-массив Content, без обёртки.
val arr = bodyJson.decodeFromString(ListSerializer(Content.serializer()), json)
BodyDecoded(arr, null, null)
}
}