feat: uuidv7 identifier generation (#11513)

Author: wmontwe

core/architecture/api/src/commonMain/kotlin/net/thunderbird/core/architecture/model/BaseUuidIdentifierFactory.kt

@@ -25,5 +25,5 @@ abstract class BaseUuidIdentifierFactory<T : BaseUuidIdentifier>(
 
     override fun of(raw: String): T = fromUuid(Uuid.parse(raw))
 
-    override fun create(): T = fromUuid(Uuid.random())
+    override fun create(): T = fromUuid(Uuid.generateV7())
 }

core/architecture/api/src/commonTest/kotlin/net/thunderbird/core/architecture/model/BaseUuidIdentifierFactoryTest.kt

@@ -30,14 +30,40 @@ class BaseUuidIdentifierFactoryTest {
     }
 
     @Test
-    fun `given create is called twice then returns different Ids`() {
+    fun `given create is called then returns UUIDv7 Id`() {
         // Arrange + Act
-        val id1 = TestIdFactory.create()
-        val id2 = TestIdFactory.create()
+        val id = TestIdFactory.create()
 
         // Assert
-        assertThat(id1).isNotEqualTo(id2)
-        assertThat(id1.toString()).isNotEqualTo(id2.toString())
+        id.value.toLongs { mostSignificantBits, leastSignificantBits ->
+            val version = (mostSignificantBits ushr 12) and 0x0F
+            val variant = leastSignificantBits ushr 62
+
+            assertThat(version).isEqualTo(7L)
+            assertThat(variant).isEqualTo(2L)
+        }
+    }
+
+    @Test
+    fun `given create is called repeatedly then returns ordered unique Ids`() {
+        // Arrange + Act
+        val ids = List(100) { TestIdFactory.create() }
+
+        // Assert
+        assertThat(ids).isEqualTo(ids.sorted())
+        assertThat(ids.toSet().size).isEqualTo(ids.size)
+    }
+
+    @Test
+    fun `given existing UUID when of is called then returns compatible Id`() {
+        // Arrange
+        val raw = "123e4567-e89b-42d3-a456-426655440000"
+
+        // Act
+        val id = TestIdFactory.of(raw)
+
+        // Assert
+        assertThat(id.value).isEqualTo(Uuid.parse(raw))
     }
 
     @Test

docs/engineering/rfcs/0009-uuidv7-identifier-migration.md

@@ -28,7 +28,8 @@ is stable for its lifetime. It needs its own decision, inventory, failure handli
 ### Ownership and module placement
 
 - `AccountId` remains in `feature:account:api`.
-- `FolderId`, `MessageId`, and `ThreadId` remain in the mail domain.
+- `FolderId` belongs to `feature:mail:folder:api`.
+- `MessageId`, `ThreadId`, and `AttachmentId` belong to `feature:mail:message:api`.
 - `BaseIdentifier`, `BaseUuidIdentifier`, `IdentifierFactory`, and `BaseUuidIdentifierFactory` remain in
   `core:architecture:api`.
 - No `core:types:api` module is introduced by this RFC.

docs/engineering/technical-designs/0003-global-database.md

@@ -40,16 +40,16 @@ database and are stable while that record exists, including across application r
 They are not protocol identifiers, portable-profile identifiers, or synchronization identifiers. In particular, an
 IMAP UID, a folder server ID, and an RFC 5322 `Message-ID` header must not be used as a global database identifier.
 
-|   Identifier   |         Owner         |                                                                                                                                            Meaning and boundary                                                                                                                                             |
-|----------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `AccountId`    | `feature:account:api` | The existing UUID-backed account identifier. Global-mail records retain its existing persisted value to establish account scope. Cutover neither replaces nor regenerates it. Account settings and profile runtime state remain outside the global mail database.                                           |
-| `FolderId`     | Mail domain           | Identifies one local folder record across all accounts. It replaces the legacy account-local folder number at repository boundaries.                                                                                                                                                                        |
-| `MessageId`    | Mail domain           | Identifies one local message record across all accounts. A message copied to another folder is a separate local record and therefore has a separate `MessageId`.                                                                                                                                            |
-| `ThreadId`     | Mail domain           | Identifies one account-scoped conversation, which can contain local message records from Inbox, Sent, Archive, and other folders. It is a durable conversation aggregate, not a legacy numeric thread-root key. Thread operations use `ThreadId`. Operations on an individual local record use `MessageId`. |
-| `AttachmentId` | Mail domain           | An opaque attachment-access URI or equivalent reference. It resolves unambiguously after cutover and is not a raw message-part primary key. Message-part keys stay internal unless a future focused attachment contract requires one.                                                                       |
-
-RFC 0009 owns the UUID representation and generation policy for `FolderId`, `MessageId`, and `ThreadId`. These types,
-along with `AccountId` and `AttachmentId`, are the only identifiers that cross the mail repository boundary for this
+|   Identifier   |           Owner            |                                                                                                                                            Meaning and boundary                                                                                                                                             |
+|----------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `AccountId`    | `feature:account:api`      | The existing UUID-backed account identifier. Global-mail records retain its existing persisted value to establish account scope. Cutover neither replaces nor regenerates it. Account settings and profile runtime state remain outside the global mail database.                                           |
+| `FolderId`     | `feature:mail:folder:api`  | Identifies one local folder record across all accounts. It replaces the legacy account-local folder number at repository boundaries.                                                                                                                                                                        |
+| `MessageId`    | `feature:mail:message:api` | Identifies one local message record across all accounts. A message copied to another folder is a separate local record and therefore has a separate `MessageId`.                                                                                                                                            |
+| `ThreadId`     | `feature:mail:message:api` | Identifies one account-scoped conversation, which can contain local message records from Inbox, Sent, Archive, and other folders. It is a durable conversation aggregate, not a legacy numeric thread-root key. Thread operations use `ThreadId`. Operations on an individual local record use `MessageId`. |
+| `AttachmentId` | `feature:mail:message:api` | Identifies one persisted attachment record across all accounts. It is distinct from attachment access URIs and internal message-part primary keys.                                                                                                                                                          |
+
+RFC 0009 owns the UUID representation and generation policy for `FolderId`, `MessageId`, `ThreadId`, and `AttachmentId`.
+These types, along with `AccountId`, are the only identifiers that cross the mail repository boundary for this
 design. Repository contracts never expose legacy numeric IDs or persistence keys.
 
 The thread builder uses the imported messages' threading headers across all folders of the same account. When a newly
@@ -71,7 +71,8 @@ For imported data, the migrator records an account-qualified source key before l
 | Folder          | `(AccountId, legacy folder id)`                     | `FolderId`               | folder extra values, message folder references, queued-command folder references                                  |
 | Message         | `(AccountId, legacy message id)`                    | `MessageId`              | outbox state, notifications, full-text mapping, message part root, thread message reference                       |
 | Thread          | `(AccountId, legacy folder id, legacy thread root)` | `ThreadId`               | rebuild cross-folder memberships from message threading headers and rewrite threaded-list and thread-cache values |
-| Message part    | `(AccountId, legacy message-part id)`               | internal only            | part root and parent references, message root-part reference, attachment-file lookup and URI resolution           |
+| Message part    | `(AccountId, legacy message-part id)`               | internal only            | part root and parent references, message root-part reference                                                      |
+| Attachment      | `(AccountId, legacy message-part id)`               | `AttachmentId`           | attachment-file lookup and access URI resolution                                                                  |
 | Pending command | `(AccountId, legacy command id)`                    | internal only            | command row identity and serialized folder references                                                             |
 
 The exact physical representation is internal, but it must enforce uniqueness of every source key and reject an import
@@ -103,7 +104,7 @@ failure state. A migration gate holds startup, sync, and other background mail w
 6. Establish the durable cutover state and switch repository bindings to the global implementation.
 7. Start post-cutover cleanup of all legacy database and attachment artifacts.
 
-The import writes folder and message identifier mappings before importing dependents. After all message records for an
+The import writes folder, message, and attachment identifier mappings before importing dependents. After all message records for an
 account are available, it builds cross-folder `ThreadId` memberships from their threading headers and records the
 legacy folder-local thread-root mappings before rewriting threaded-list and cache values. It then validates all
 rewritten relationships before the global database is published. It translates serialized pending-command folder

feature/account/api/src/commonTest/kotlin/net/thunderbird/feature/account/UnifiedAccountIdTest.kt

@@ -20,6 +20,13 @@ class UnifiedAccountIdTest {
         assertThat(UnifiedAccountId.isUnified).isTrue()
     }
 
+    @Test
+    fun `factory parses nil UUID as unified account id`() {
+        val accountId = AccountIdFactory.of("00000000-0000-0000-0000-000000000000")
+
+        assertThat(accountId).isEqualTo(UnifiedAccountId)
+    }
+
     @Test
     fun `isUnified returns false for non-unified account id`() {
         val nonUnifiedAccountId = AccountIdFactory.of("123e4567-e89b-12d3-a456-426614174000")

feature/mail/folder/api/build.gradle.kts

@@ -8,6 +8,7 @@ kotlin {
     }
     sourceSets {
         commonMain.dependencies {
+            api(projects.core.architecture.api)
             implementation(projects.core.common)
             implementation(projects.core.logging.api)
             implementation(projects.feature.account.api)

feature/mail/folder/api/src/commonMain/kotlin/net/thunderbird/feature/mail/folder/FolderId.kt

@@ -0,0 +1,13 @@
+package net.thunderbird.feature.mail.folder
+
+import kotlin.uuid.ExperimentalUuidApi
+import kotlin.uuid.Uuid
+import net.thunderbird.core.architecture.model.BaseUuidIdentifier
+
+/**
+ * Identifies a local folder record across all accounts.
+ */
+@OptIn(ExperimentalUuidApi::class)
+class FolderId(
+    value: Uuid,
+) : BaseUuidIdentifier(value)

feature/mail/folder/api/src/commonMain/kotlin/net/thunderbird/feature/mail/folder/FolderIdFactory.kt

@@ -0,0 +1,10 @@
+package net.thunderbird.feature.mail.folder
+
+import kotlin.uuid.ExperimentalUuidApi
+import net.thunderbird.core.architecture.model.BaseUuidIdentifierFactory
+
+/**
+ * Factory for creating [FolderId] values.
+ */
+@OptIn(ExperimentalUuidApi::class)
+object FolderIdFactory : BaseUuidIdentifierFactory<FolderId>(::FolderId)

feature/mail/folder/api/src/commonTest/kotlin/net/thunderbird/feature/mail/folder/FolderIdFactoryTest.kt

@@ -0,0 +1,35 @@
+package net.thunderbird.feature.mail.folder
+
+import assertk.assertThat
+import assertk.assertions.isEqualTo
+import kotlin.test.Test
+import kotlin.uuid.ExperimentalUuidApi
+import kotlin.uuid.Uuid
+
+@OptIn(ExperimentalUuidApi::class)
+class FolderIdFactoryTest {
+
+    @Test
+    fun `given existing UUID when of is called then returns compatible FolderId`() {
+        // Arrange
+        val raw = "123e4567-e89b-42d3-a456-426655440000"
+
+        // Act
+        val folderId = FolderIdFactory.of(raw)
+
+        // Assert
+        assertThat(folderId.value).isEqualTo(Uuid.parse(raw))
+    }
+
+    @Test
+    fun `given create is called then returns UUIDv7 FolderId`() {
+        // Arrange + Act
+        val folderId = FolderIdFactory.create()
+
+        // Assert
+        folderId.value.toLongs { mostSignificantBits, leastSignificantBits ->
+            assertThat((mostSignificantBits ushr 12) and 0x0F).isEqualTo(7L)
+            assertThat(leastSignificantBits ushr 62).isEqualTo(2L)
+        }
+    }
+}

feature/mail/message/api/build.gradle.kts

@@ -0,0 +1,14 @@
+plugins {
+    id(ThunderbirdPlugins.Library.kmp)
+}
+
+kotlin {
+    android {
+        namespace = "net.thunderbird.feature.mail.message"
+    }
+    sourceSets {
+        commonMain.dependencies {
+            api(projects.core.architecture.api)
+        }
+    }
+}