refactor(message-log-api): split MessageStore into read-only and mutable interfaces

- Introduced `MutableMessageStore` for producers with an `append` operation, separate from read-only `MessageStore`. - Updated all consumers and implementations to use the appropriate interface (`read-only` for observers, `mutable` for producers). - Improves modularity and ensures compile-time guarantees against unintended write operations in the audit log.
2026-09-20 21:08:55 +03:00
parent 2cc1d923b3
commit bd65c29b48
11 changed files with 48 additions and 25 deletions
@@ -4,21 +4,27 @@ import kotlinx.coroutines.flow.Flow
 import kotlin.time.Instant

 /**
- * Append-only audit log сообщений.
+ * Append-only audit log сообщений — read-only представление.
 *
- * Только `append` и чтение. Никаких обновлений, никакого удаления
- * (кроме каскадного вместе с ConversationStore.delete).
+ * Producer-операция [MutableMessageStore.append] находится на
+ * [MutableMessageStore] — этот интерфейс только для чтения, чтобы
+ * consumer'ы физически не могли писать в audit log.
+ *
+ * Никаких обновлений, никакого удаления (кроме каскадного вместе
+ * с ConversationStore.delete).
 */
 interface MessageStore : AutoCloseable {

-    suspend fun append(record: MessageRecord)
-
    suspend fun list(conversationId: String, after: Instant, offset: Int, limit: Int): List<MessageRecord>

    suspend fun listAll(conversationId: String): List<MessageRecord>

+    /**
+     * Subscribe на события append'ов. Default — `emptyFlow()` для store'ов
+     * без live-уведомлений (например, SQLite без триггеров); impl'ы с
+     * in-memory notification (`:storage-inmemory`) override'ят.
+     */
    fun events(): Flow<MessageEvent> = kotlinx.coroutines.flow.emptyFlow()

    suspend fun tokenStats(conversationId: String): TokenStats
-}
-
+}
@@ -0,0 +1,17 @@
+package pw.binom.agentik.messageLog
+
+/**
+ * Mutable вариант [MessageStore] — добавляет producer-операцию [append].
+ *
+ * Этот интерфейс предназначен **только для producer'ов** (ChatAgent,
+ * ConversationLoop, ToolDispatcher, sub-agents, A2A-bridge).
+ * Consumer'ы (DebugRoutes, admin dashboards, parent agents) должны
+ * принимать **read-only** [MessageStore] — тогда невозможно случайно
+ * записать в audit log из observer'а.
+ *
+ * **Append семантика**: см. KDoc [MessageStore.append][MessageStore] —
+ * на этом интерфейсе (не дублируем).
+ */
+interface MutableMessageStore : MessageStore {
+    suspend fun append(record: MessageRecord)
+}