feat(lxmf): persist received FIELD_AUDIO clips — Phase 0 receive plumbing

Stage 2 of docs/ROADMAP.md Phase 0. Adds the outbound audioField() builder
(flat [mode, bytes] per SPEC §5.9.3) + round-trip test, and persists
inbound audio clips:

- StoredMessage/MessageEntity gain a nullable audioMode column (Room v17,
  MIGRATION_16_17, additive); the clip bytes reuse the attachment-store
  columns, audioMode marks the row as a playable clip + records the codec.
- ReticulumEngine.withAudio() mirrors withFile(); wired into all three
  inbound paths (propagation / link / opportunistic).

No UI yet — a received clip currently renders as a file chip; the play
bubble + playback land next. No send path yet.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: thatSFguy

androidApp/src/main/kotlin/io/github/thatsfguy/reticulum/android/storage/Entities.kt

@@ -143,6 +143,10 @@ internal data class MessageEntity(
     val imageSize: Int? = null,
     val attachmentToken: String? = null,
     val attachmentSize: Int? = null,
+    // ---- v17 audio clip (FIELD_AUDIO, key 7) ----
+    // Mode byte (AudioMode.*) when this row is a playable audio clip; the
+    // bytes reuse the attachment-store columns above. Null otherwise.
+    val audioMode: Int? = null,
 )
 
 // ---- Reticulum Relay Chat (RRC) — experimental, gated by the

androidApp/src/main/kotlin/io/github/thatsfguy/reticulum/android/storage/Repositories.kt

@@ -399,13 +399,15 @@ private fun MessageEntity.toModel() = StoredMessage(
     messageId, replyToMessageId, reactionsJson, arrivedViaDest,
     attachmentName, attachmentBytes,
     imageToken, imageSize, attachmentToken, attachmentSize,
+    audioMode,
 )
 private fun StoredMessage.toEntity() = MessageEntity(
     id, contactHash, direction, content, title, timestamp, state, attempts,
     lastAttempt, lastError, rawPacket, packetHash, rssi, hopCount, imageBytes,
     messageId, replyToMessageId, reactionsJson, arrivedViaDest,
     attachmentName, attachmentBytes,
     imageToken, imageSize, attachmentToken, attachmentSize,
+    audioMode,
 )
 
 private fun encodeTelemetryJson(map: Map<String, String>): String =

androidApp/src/main/kotlin/io/github/thatsfguy/reticulum/android/storage/ReticulumDatabase.kt

@@ -17,7 +17,7 @@ import androidx.sqlite.db.SupportSQLiteDatabase
         RrcRoomEntity::class,
         RrcMessageEntity::class,
     ],
-    version = 16,
+    version = 17,
     exportSchema = true,
 )
 internal abstract class ReticulumDatabase : RoomDatabase() {
@@ -271,6 +271,18 @@ internal abstract class ReticulumDatabase : RoomDatabase() {
             }
         }
 
+        /**
+         * v17: LXMF `FIELD_AUDIO` (key 7) audio clips. Adds a single
+         * nullable `audioMode` column (the `AudioMode.*` codec byte) that
+         * marks a row as a playable clip; the clip bytes reuse the existing
+         * attachment-store columns. Purely additive, NULL for existing rows.
+         */
+        private val MIGRATION_16_17 = object : Migration(16, 17) {
+            override fun migrate(db: SupportSQLiteDatabase) {
+                db.execSQL("ALTER TABLE messages ADD COLUMN audioMode INTEGER")
+            }
+        }
+
         fun get(context: Context): ReticulumDatabase {
             return INSTANCE ?: synchronized(this) {
                 INSTANCE ?: Room.databaseBuilder(
@@ -289,6 +301,7 @@ internal abstract class ReticulumDatabase : RoomDatabase() {
                         MIGRATION_13_14,
                         MIGRATION_14_15,
                         MIGRATION_15_16,
+                        MIGRATION_16_17,
                     )
                     // Pre-v6 alpha installs are still wiped on schema
                     // mismatch. From v6 forward we add real migrations

shared/src/androidUnitTest/kotlin/io/github/thatsfguy/reticulum/engine/OutboundAudioFieldTest.kt

@@ -0,0 +1,42 @@
+package io.github.thatsfguy.reticulum.engine
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+/**
+ * [audioField] — outbound LXMF `FIELD_AUDIO` (key 7) builder. Wire shape
+ * is the flat `[mode_byte(int), audio_bytes]` (SPEC §5.9.3). Verified by
+ * round-tripping through [extractAudioField].
+ */
+class OutboundAudioFieldTest {
+
+    @Test
+    fun emitsFlatModeAndBytesUnderKey7() {
+        val bytes = byteArrayOf(1, 2, 3, 4)
+        val field = audioField(LxmfAudio(AudioMode.OPUS_OGG, bytes))
+        // Single entry, integer key 7.
+        assertEquals(setOf<Any?>(7), field.keys)
+        val value = field[7] as List<*>
+        // Flat [mode, bytes] — NOT a list of pairs (that's key 5).
+        assertEquals(2, value.size)
+        assertEquals(AudioMode.OPUS_OGG, value[0])
+        assertTrue((value[1] as ByteArray).contentEquals(bytes))
+    }
+
+    @Test
+    fun roundTripsThroughExtract() {
+        val bytes = ByteArray(64) { it.toByte() }
+        val decoded = extractAudioField(audioField(LxmfAudio(AudioMode.CODEC2_3200, bytes)))!!
+        assertEquals(AudioMode.CODEC2_3200, decoded.mode)
+        assertTrue(decoded.bytes.contentEquals(bytes))
+    }
+
+    @Test
+    fun notConfusedWithFileOrImageShape() {
+        // The flat audio shape must not parse as a file attachment (key 5,
+        // list-of-pairs) and vice-versa — they share neither key nor shape.
+        val field = audioField(LxmfAudio(AudioMode.OPUS_PTT, byteArrayOf(9)))
+        assertTrue(extractFileAttachments(field).isEmpty())
+    }
+}

shared/src/commonMain/kotlin/io/github/thatsfguy/reticulum/engine/ReticulumEngine.kt

@@ -223,6 +223,25 @@ internal fun extractAudioField(fields: Map<Any?, Any?>): LxmfAudio? {
     return LxmfAudio(mode, bytes)
 }
 
+/**
+ * Build the outbound LXMF `FIELD_AUDIO` (key 7) map entry for [audio].
+ * Wire shape (SPEC §5.9.3) is the flat `[mode_byte(int), audio_bytes]` —
+ * NOT a list of pairs (that's `FIELD_FILE_ATTACHMENTS` key 5). The mode is
+ * emitted as a Kotlin `Int` so msgpack encodes it as an integer, the form
+ * [extractAudioField] (and Sideband) expects. `internal` so the test
+ * source set can pin the round-trip against [extractAudioField].
+ */
+internal fun audioField(audio: LxmfAudio): Map<Any?, Any?> =
+    mapOf<Any?, Any?>(7 to listOf(audio.mode, audio.bytes))
+
+/** File-name extension for an audio clip of the given [AudioMode] byte —
+ *  used for the "save clip" suggested name. */
+internal fun audioExtension(mode: Int): String = when {
+    AudioMode.isOpus(mode) -> ".opus"
+    AudioMode.isCodec2(mode) -> ".c2"
+    else -> ".bin"
+}
+
 /** One decoded LXMF file attachment (`FIELD_FILE_ATTACHMENTS`, §5.9.7). */
 internal class LxmfFileAttachment(val name: String, val bytes: ByteArray)
 
@@ -535,6 +554,31 @@ class ReticulumEngine(
             copy(attachmentName = file.name, attachmentBytes = file.bytes)
     }
 
+    /**
+     * Off-row twin of [withFile] for a decoded `FIELD_AUDIO` clip (SPEC
+     * §5.9.3). The bytes reuse the attachment-store columns; [audioMode]
+     * marks the row as a playable clip and records the codec. A synthetic
+     * "clip.<ext>" name gives the save-as path something sensible. No-op
+     * when [audio] is null.
+     */
+    private suspend fun StoredMessage.withAudio(audio: LxmfAudio?): StoredMessage {
+        if (audio == null) return this
+        val name = "clip" + audioExtension(audio.mode)
+        val token = attachmentStore?.let { store ->
+            runCatching { store.put(audio.bytes) }
+                .onFailure {
+                    _events.tryEmit(EngineEvent.Log(
+                        "attachment store: audio put failed (${it::class.simpleName}) — keeping bytes on-row"
+                    ))
+                }
+                .getOrNull()
+        }
+        return if (token != null)
+            copy(attachmentName = name, attachmentToken = token, attachmentSize = audio.bytes.size, audioMode = audio.mode)
+        else
+            copy(attachmentName = name, attachmentBytes = audio.bytes, audioMode = audio.mode)
+    }
+
     /**
      * Delete the attachment-store files referenced by [messages] —
      * called from the message-delete paths so a cleared conversation
@@ -1954,6 +1998,7 @@ class ReticulumEngine(
                     // LXMF FIELD_FILE_ATTACHMENTS (key 5, SPEC §5.9.7) —
                     // keep the first file (Sideband sends one per message).
                     val propFile = extractFileAttachments(msg.fields).firstOrNull()
+                    val propAudio = extractAudioField(msg.fields)
                     val savedId = messageRepo.save(StoredMessage(
                         contactHash = sourceHashHex,
                         direction = "incoming",
@@ -1972,7 +2017,7 @@ class ReticulumEngine(
                         // via fwdsvc). Same fallback the link path
                         // uses when LINKIDENTIFY is absent.
                         arrivedViaDest = sourceHashHex,
-                    ).withImage(imageBytes).withFile(propFile))
+                    ).withImage(imageBytes).withFile(propFile).withAudio(propAudio))
                     _events.tryEmit(EngineEvent.MessageReceived(
                         messageId = savedId,
                         contactHash = sourceHashHex,
@@ -4031,6 +4076,7 @@ class ReticulumEngine(
         // LXMF FIELD_FILE_ATTACHMENTS (key 5, SPEC §5.9.7) — keep the
         // first file (Sideband sends one per message).
         val linkFile = extractFileAttachments(msg.fields).firstOrNull()
+        val linkAudio = extractAudioField(msg.fields)
         // v1.1.39 — uniform routing rule (fwdsvc maintainer's
         // simplification). arrivedViaDest = LINKIDENTIFY peer when
         // available, else the LXMF body's source_hash. Covers two
@@ -4074,7 +4120,7 @@ class ReticulumEngine(
             messageId = messageIdHex,
             replyToMessageId = replyToMessageId,
             arrivedViaDest = arrivedViaDest,
-        ).withImage(imageBytes).withFile(linkFile))
+        ).withImage(imageBytes).withFile(linkFile).withAudio(linkAudio))
         // Diagnostic only when the routing destination actually differs
         // from the conversation peer (i.e. a passthrough relay case via
         // LINKIDENTIFY). For fwdsvc rebroadcast and direct 1:1 chats
@@ -4672,6 +4718,7 @@ class ReticulumEngine(
         // LXMF FIELD_FILE_ATTACHMENTS (key 5, SPEC §5.9.7) — keep the
         // first file (Sideband sends one per message).
         val oppFile = extractFileAttachments(msg.fields).firstOrNull()
+        val oppAudio = extractAudioField(msg.fields)
         val savedId = messageRepo.save(StoredMessage(
             contactHash = sourceHashHex,
             direction = "incoming",
@@ -4706,7 +4753,7 @@ class ReticulumEngine(
             // equals the conversation peer, making the override a
             // harmless no-op).
             arrivedViaDest = sourceHashHex,
-        ).withImage(imageBytes).withFile(oppFile))
+        ).withImage(imageBytes).withFile(oppFile).withAudio(oppAudio))
         _events.tryEmit(EngineEvent.MessageReceived(
             messageId = savedId,
             contactHash = sourceHashHex,

shared/src/commonMain/kotlin/io/github/thatsfguy/reticulum/store/Models.kt

@@ -155,6 +155,12 @@ data class StoredMessage(
     val attachmentToken: String? = null,
     /** Byte length of the [attachmentToken] payload. */
     val attachmentSize: Int? = null,
+    /** LXMF `FIELD_AUDIO` mode byte (`AudioMode.*`, SPEC §5.9.3) when this
+     *  row is an audio clip; null otherwise. The clip bytes reuse the
+     *  attachment-store columns ([attachmentToken] / [attachmentName] /
+     *  [attachmentSize]); this field marks the row as a playable clip and
+     *  records which codec produced it. */
+    val audioMode: Int? = null,
 )
 
 interface IdentityRepository {