feat(threads): add phase 1 of the threads feature

Part of status-im/status-app#21257

Implements a first-class thread model for community chat channels. Threads are anchored to an existing parent message and inherit the channel's permissions and encryption. The feature is gated behind a `Threads` feature flag (off by default).

---

### Schema & protocol

- **`chat_message.proto`** — added optional `thread_id` field (field 21) to
  `ChatMessage`. Old clients silently ignore the field; new clients write to
  and read from it transparently.
- **`communities.proto`** — added `create_thread_all_members_enabled` boolean
  to `CommunityAdminSettings`, controlling who may start a new thread.
- **DB migrations**
  - `1764000001` — `ALTER TABLE user_messages ADD COLUMN thread_id TEXT` with
    indexes on `(local_chat_id, thread_id)` and `(thread_id)`.
  - `1764000002` — `CREATE TABLE threads (thread_id, chat_id,
    parent_message_id, name)` with an index on `(chat_id, name)`.

---

### Persistence (`protocol/message_persistence.go`)

- New `Thread` struct with JSON tags (`threadId`, `chatId`,
  `parentMessageId`, `name`).
- `SaveMessages` now auto-creates or updates thread metadata whenever a
  message with a non-empty `thread_id` is saved. If the parent message is
  not yet known the thread name is stored as an empty string; when the
  parent arrives, `updateThreadNameFromParentIfNeeded` back-fills the name.
- Thread name is normalised to a 40-character trimmed excerpt of the parent
  message text. Unknown/placeholder names are **empty string** — the client
  controls the display label.
- New persistence helpers: `UpsertThread`, `ThreadByID`, `ThreadsByChatID`,
  `MessagesByThreadID`, `threadNameFromParentByID`.

---

### Community & request layer

- `AllowsAllMembersToCreateThread()` helper on `Community`.
- `CreateCommunityRequest` / `EditCommunityRequest` now forward
  `CreateThreadAllMembersEnabled`.

---

### Messenger (`protocol/messenger.go`)

- `sendChatMessage` enforces the community thread-creation permission gate:
  only admins may start a new thread unless `AllowsAllMembersToCreateThread`
  is set.
- **`CreateThread(chatID, parentMessageID)`** — explicit thread creation API.
  Requires the parent message to already exist locally; returns
  `"parent message not found"` otherwise. Applies the same permission gate
  as `sendChatMessage`.
- **`ThreadsByChatID(chatID)`** — lists all threads for a channel.
- **`MessagesByThreadID(chatID, threadID, cursor, limit)`** — paginated
  thread message history.
- `addThreadsToResponse` enriches every `MessengerResponse` (send path and
  retrieve/signal path) with the thread metadata for any thread-tagged
  messages in the response.

---

### MessengerResponse (`protocol/messenger_response.go`)

- New private `threads map[string]*Thread` field.
- `AddThread` / `AddThreads` / `Threads()` accessors.
- `threads` included in `MarshalJSON` output (`"threads"` key), `IsEmpty`,
  and `Merge`.

---

### RPC API (`services/ext/api.go`)

Three new `PublicAPI` methods exposed over JSON-RPC under the `wakuext`
namespace:

| Method | Description |
|--------|-------------|
| `wakuext_createThread` | Create thread from an existing parent message |
| `wakuext_chatThreads` | List all threads for a chat |

`wakuext_sendChatMessage` now accepts an optional `threadId` field.

---

### Tests added

- `TestSaveMessagesCreatesThreadWithEmptyNameWhenParentMissing`
- `TestSaveMessagesUpdatesEmptyThreadNameWhenParentArrives`
- `TestMessagesByThreadID`
- `TestDeleteParentMessageKeepsThreadMetadata`
- `TestCreateThreadFromExistingParent`
- `TestCreateThreadFailsWhenParentMessageMissing`
- `TestMessengerResponseMergeThreads`
- `TestMessengerResponseMarshalJSONIncludesThreads`

---

### API reference

`cmd/status-backend/API_REFERENCE.md` updated with request/response examples
and error tables for all three new RPC methods.

Author: jrainville

cmd/status-backend/API_REFERENCE.md

@@ -319,10 +319,15 @@ Send a text message to a chat/channel.
 [{
   "chatId": "<chatId>",
   "text": "Hello!",
-  "contentType": 1
+  "contentType": 1,
+  "threadId": "<parentMessageId-optional>"
 }]
 ```
 
+- `threadId` is optional.
+- Use `threadId` to send a message into an existing thread.
+- If `threadId` points to a parent that is not yet known locally, the backend still creates thread metadata and backfills the name when the parent arrives.
+
 **Chat ID formats:**
 
 - **Community channel:** concatenation of community ID and chat UUID without separator:
@@ -346,6 +351,93 @@ Read message history for a chat.
 
 ---
 
+### wakuext_createThread
+
+Explicitly create a thread from an existing parent message. The parent message must already be stored locally (i.e. it was previously received or sent).
+
+For community chats, the caller must be a privileged member (admin/owner) unless the community has "create threads for all members" enabled.
+
+**Params:** `[chatId, parentMessageId]`
+- `chatId`: string — channel/chat identifier.
+- `parentMessageId`: string — ID of the message that becomes the thread root.
+
+**Result:**
+```json
+{
+  "threads": [
+    {
+      "threadId": "0x-parent-message-id",
+      "chatId": "0xcommunity...<chatUUID>",
+      "parentMessageId": "0x-parent-message-id",
+      "name": "First 40 chars of parent text (or empty)"
+    }
+  ]
+}
+```
+
+**Errors:**
+- `"threads feature is disabled"` — feature flag is off.
+- `"chatID and parentMessageID are required"` — missing params.
+- `"thread already exists for this message"` — thread already created for this parent.
+- `"parent message not found"` — parent message doesn't exist locally.
+- `"only admins can create threads in this community"` — permission denied.
+
+---
+
+### wakuext_chatThreads
+
+List threads for a chat.
+
+**Params:** `[chatId]`
+- `chatId`: string (communityId + chatUUID)
+
+**Result:**
+```json
+{
+  "threads": [
+    {
+      "threadId": "0x-parent-message-id",
+      "chatId": "0xcommunity...<chatUUID>",
+      "parentMessageId": "0x-parent-message-id",
+      "name": "Parent message text (or empty until known)"
+    }
+  ]
+}
+```
+
+Notes:
+- `name` may be empty when the parent message has not been persisted yet.
+- Unknown/placeholder names are intentionally client-defined; backend returns empty string until resolved.
+
+---
+
+### wakuext_threadMessages
+
+Read message history for a single thread.
+
+**Params:** `[chatId, threadId, cursor, limit]`
+- `chatId`: string (communityId + chatUUID)
+- `threadId`: string (thread identifier; currently parent message ID)
+- `cursor`: string (empty string for first page)
+- `limit`: number
+
+**Result:**
+```json
+{
+  "messages": [
+    {
+      "id": "0x...",
+      "chatId": "0xcommunity...<chatUUID>",
+      "threadId": "0x-parent-message-id",
+      "text": "reply text"
+    }
+  ],
+  "cursor": "<next-cursor-or-empty>"
+}
+```
+
+---
+
 ### wakuext_leaveCommunity
 
 Leave a community.

protocol/activity_center_persistence_test.go

@@ -152,7 +152,7 @@ func (s *ActivityCenterPersistenceTestSuite) Test_DeleteActivityCenterNotificati
 	err = p.SaveChat(*chat)
 	s.Require().NoError(err)
 
-	chatMessages, _, err := p.MessageByChatID(chat.ID, "", 2)
+	chatMessages, _, err := p.MessageByChatID(chat.ID, "", "", 2)
 	s.Require().NoError(err)
 	s.Require().Len(chatMessages, 2)
 
@@ -268,7 +268,7 @@ func (s *ActivityCenterPersistenceTestSuite) Test_DeleteActivityCenterNotificati
 	err = p.SaveChat(*chat)
 	s.Require().NoError(err)
 
-	chatMessages, _, err := p.MessageByChatID(chat.ID, "", 2)
+	chatMessages, _, err := p.MessageByChatID(chat.ID, "", "", 2)
 	s.Require().NoError(err)
 	s.Require().Len(chatMessages, 2)
 

protocol/common/feature_flags.go

@@ -14,4 +14,7 @@ type FeatureFlags struct {
 
 	// EnableMercuryoProvider indicates whether we should enable the Mercuryo provider in the Wallet
 	EnableMercuryoProvider bool
+
+	// Threads indicates whether thread-specific behavior is enabled.
+	Threads bool
 }

protocol/common/message.go

@@ -245,6 +245,7 @@ func (m *Message) MarshalJSON() ([]byte, error) {
 		BridgeMessage            *protobuf.BridgeMessage          `json:"bridgeMessage,omitempty"`
 		PaymentRequests          []*protobuf.PaymentRequest       `json:"paymentRequests,omitempty"`
 		PinnedBy                 string                           `json:"pinnedBy,omitempty"`
+		ThreadID                 string                           `json:"threadId,omitempty"`
 	}
 	item := MessageStructType{
 		ID:                       m.ID,
@@ -287,6 +288,7 @@ func (m *Message) MarshalJSON() ([]byte, error) {
 		ContactVerificationState: m.ContactVerificationState,
 		PaymentRequests:          m.PaymentRequests,
 		PinnedBy:                 m.PinnedBy,
+		ThreadID:                 m.GetThreadId(),
 	}
 
 	if sticker := m.GetSticker(); sticker != nil {
@@ -336,6 +338,7 @@ func (m *Message) UnmarshalJSON(data []byte) error {
 		EnsName            string                           `json:"ensName"`
 		DisplayName        string                           `json:"displayName"`
 		ChatID             string                           `json:"chatId"`
+		ThreadID           string                           `json:"threadId"`
 		Sticker            *protobuf.StickerMessage         `json:"sticker"`
 		AudioDurationMs    uint64                           `json:"audioDurationMs"`
 		ParsedText         json.RawMessage                  `json:"parsedText"`
@@ -383,6 +386,9 @@ func (m *Message) UnmarshalJSON(data []byte) error {
 	m.From = aux.From
 	m.Deleted = aux.Deleted
 	m.DeletedForMe = aux.DeletedForMe
+	if aux.ThreadID != "" {
+		m.ThreadId = &aux.ThreadID
+	}
 	return nil
 }
 

protocol/communities/community.go

@@ -140,7 +140,8 @@ func New(config Config, timesource common.TimeSource, encryptor DescriptionEncry
 }
 
 type CommunityAdminSettings struct {
-	PinMessageAllMembersEnabled bool `json:"pinMessageAllMembersEnabled"`
+	PinMessageAllMembersEnabled   bool `json:"pinMessageAllMembersEnabled"`
+	CreateThreadAllMembersEnabled bool `json:"createThreadAllMembersEnabled"`
 }
 
 type CommunityChat struct {
@@ -283,11 +284,13 @@ func (o *Community) MarshalPublicAPIJSON() ([]byte, error) {
 		}
 
 		communityItem.CommunityAdminSettings = CommunityAdminSettings{
-			PinMessageAllMembersEnabled: false,
+			PinMessageAllMembersEnabled:   false,
+			CreateThreadAllMembersEnabled: false,
 		}
 
 		if o.config.CommunityDescription.AdminSettings != nil {
 			communityItem.CommunityAdminSettings.PinMessageAllMembersEnabled = o.config.CommunityDescription.AdminSettings.PinMessageAllMembersEnabled
+			communityItem.CommunityAdminSettings.CreateThreadAllMembersEnabled = o.config.CommunityDescription.AdminSettings.CreateThreadAllMembersEnabled
 		}
 	}
 	return json.Marshal(communityItem)
@@ -444,11 +447,13 @@ func (o *Community) MarshalJSON() ([]byte, error) {
 		}
 
 		communityItem.CommunityAdminSettings = CommunityAdminSettings{
-			PinMessageAllMembersEnabled: false,
+			PinMessageAllMembersEnabled:   false,
+			CreateThreadAllMembersEnabled: false,
 		}
 
 		if o.config.CommunityDescription.AdminSettings != nil {
 			communityItem.CommunityAdminSettings.PinMessageAllMembersEnabled = o.config.CommunityDescription.AdminSettings.PinMessageAllMembersEnabled
+			communityItem.CommunityAdminSettings.CreateThreadAllMembersEnabled = o.config.CommunityDescription.AdminSettings.CreateThreadAllMembersEnabled
 		}
 	}
 	return json.Marshal(communityItem)
@@ -1164,6 +1169,7 @@ func (o *Community) Edit(description *protobuf.CommunityDescription) {
 	}
 	o.config.CommunityDescription.Permissions = description.Permissions
 	o.config.CommunityDescription.AdminSettings.PinMessageAllMembersEnabled = description.AdminSettings.PinMessageAllMembersEnabled
+	o.config.CommunityDescription.AdminSettings.CreateThreadAllMembersEnabled = description.AdminSettings.CreateThreadAllMembersEnabled
 }
 
 func (o *Community) EditPermissionAccess(permissionAccess protobuf.CommunityPermissions_Access) {
@@ -2396,6 +2402,10 @@ func (o *Community) AllowsAllMembersToPinMessage() bool {
 	return o.config.CommunityDescription.AdminSettings != nil && o.config.CommunityDescription.AdminSettings.PinMessageAllMembersEnabled
 }
 
+func (o *Community) AllowsAllMembersToCreateThread() bool {
+	return o.config.CommunityDescription.AdminSettings != nil && o.config.CommunityDescription.AdminSettings.CreateThreadAllMembersEnabled
+}
+
 func (o *Community) CreateDeepCopy() *Community {
 	return &Community{
 		encryptor: o.encryptor,

protocol/communities_messenger_token_permissions_test.go

@@ -502,7 +502,7 @@ func (s *MessengerCommunitiesTokenPermissionsSuite) TestBecomeMemberPermissions(
 	s.Require().Len(response.Messages(), 1)
 	s.Require().Equal(msg.Text, response.Messages()[0].Text)
 
-	bobMessages, _, err := s.bob.MessageByChatID(msg.ChatId, "", 10)
+	bobMessages, _, err := s.bob.MessageByChatID(msg.ChatId, "", "", 10)
 	s.Require().NoError(err)
 	s.Require().Len(bobMessages, 1)
 	s.Require().Equal(messages[0], bobMessages[0].Text)
@@ -591,12 +591,12 @@ func (s *MessengerCommunitiesTokenPermissionsSuite) TestBecomeMemberPermissions(
 		s.bob,
 		func(r *MessengerResponse) bool {
 			// Bob should have all 3 messages
-			bobMessages, _, err = s.bob.MessageByChatID(msg.ChatId, "", 10)
+			bobMessages, _, err = s.bob.MessageByChatID(msg.ChatId, "", "", 10)
 			return err == nil && len(bobMessages) == 3
 		},
 		"not all 3 messages received",
 	)
-	bobMessages, _, err = s.bob.MessageByChatID(msg.ChatId, "", 10)
+	bobMessages, _, err = s.bob.MessageByChatID(msg.ChatId, "", "", 10)
 	for _, m := range bobMessages {
 		fmt.Printf("ID: %s\n", m.ID)
 	}