feat(room-worker): actor-named, count-based membership system messages

Make create-channel / add-members / remove-member system messages
actor-named and count-based so the frontend can render clickable lists of
who was added/removed:

- members_added (add + create): "Alice added 2 people and 1 organization to
  the chatroom", with a single shared addedContent helper used by both flows;
  a lone individual (no orgs) still renders the named form. Payload lists are
  the resolved member set — req.Users for add, req.ResolvedUsers for create
  (channel-expanded individuals included, org members represented as orgs).
  An empty channel emits no members_added (room_created still fires).
- member_removed / member_left: actor-named removals
  ("Alice removed Bob from the chatroom"); wording "channel" -> "chatroom"
  across all membership messages.
- Empty individuals/orgs lists marshal as [] (not null) for the frontend.
- docs/client-api.md: document the members_added / member_removed /
  member_left sysMsgData payload schema.
- history-service: integration test asserting sysMsgData survives the
  load-history round-trip.

No pkg/model struct changes, no room-service/materialization changes, and no
new database reads.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WuJMTQH2mnUqKd6jhSg8HK

Author: claude

docs/client-api.md

@@ -2322,14 +2322,62 @@ Used by every history-service method that returns messages. Mirrors the Cassandr
 | `reactions` | map<emoji, [ReactionUser](#reactionuser)[]> | Optional. Omitted when absent; `{}` when present but empty. |
 | `deleted` | boolean | Optional. `true` for tombstoned messages. |
 | `type` | string | Optional. System-message type when set; regular messages omit it. Known values: `"room_created"`, `"members_added"`, `"member_removed"`, `"member_left"`, `"room_renamed"`, `"room_restricted"`. For all six, `msg` is populated with a server-rendered human-readable body and `sender.account` is the responsible actor (the requester for adds/removes-by-other / room-creates / renames / restricted changes, the leaving user for self-leave). |
-| `sysMsgData` | string | Optional. Base64-encoded raw JSON payload for system messages. |
+| `sysMsgData` | string | Optional. Base64-encoded JSON payload for system messages; shape depends on `type` (see [System-message `sysMsgData` payloads](#system-message-sysmsgdata-payloads)). |
 | `siteId` | string | Optional. The site that owns the message. |
 | `editedAt` | string | Optional. RFC 3339. Set after an edit. |
 | `updatedAt` | string | Optional. RFC 3339. Mirrors `editedAt` for edits, set on delete to record the deletion time. |
 | `threadRoomId` | string | Optional. The thread room ID when this is a thread message. |
 | `pinnedAt` | string | Optional. RFC 3339. With the `messages_by_room` `pinned_at` mirror, room-timeline history loads now return this on pinned rows too (previously only `pin.list` and point lookups carried it). |
 | `pinnedBy` | [MessageParticipant](#messageparticipant) | Optional. |
 
+##### System-message `sysMsgData` payloads
+
+`sysMsgData` is base64-encoded JSON whose shape depends on `type`.
+
+`members_added` (also emitted on room creation):
+
+| field | type | description |
+|-------|------|-------------|
+| `individuals` | string[] | Accounts of the individuals added (direct + channel-expanded; excludes organization members). Empty `[]`, never `null`. The "n people" count is `individuals.length`. |
+| `orgs` | string[] | Organization IDs added. Empty `[]`, never `null`. The "m organizations" count is `orgs.length`. |
+| `channels` | [ChannelRef](#channelref)[] | Source channels whose members were copied in (provenance; may be empty). |
+| `addedUsersCount` | number | Total members materialized by the operation, including organization-expanded members; may differ from `individuals.length`. |
+
+```json
+{ "individuals": ["alice", "bob"], "orgs": ["eng"], "channels": [], "addedUsersCount": 12 }
+```
+
+`member_removed`:
+
+| field | type | description |
+|-------|------|-------------|
+| `user` | [SysMsgUser](#sysmsguser) | Set when an individual was removed. |
+| `orgId` | string | Set when an organization was removed. |
+| `sectName` | string | Display name of the removed organization (set with `orgId`). |
+| `removedUsersCount` | number | Number of underlying accounts whose subscription was removed. |
+
+```json
+{ "user": { "account": "bob", "engName": "Bob", "chineseName": "鮑勃" }, "removedUsersCount": 1 }
+```
+
+`member_left` — `{ "user": SysMsgUser }` for the user who left:
+
+```json
+{ "user": { "account": "bob", "engName": "Bob", "chineseName": "鮑勃" } }
+```
+
+The displayed `msg` for `members_added` shows counts matching `individuals.length` / `orgs.length`, which clients may render as clickable lists.
+
+##### SysMsgUser
+
+A user referenced by a system-message payload.
+
+| field | type | description |
+|-------|------|-------------|
+| `account` | string | The user's account. |
+| `engName` | string | English display name; may be empty. |
+| `chineseName` | string | Chinese display name; may be empty. |
+
 ##### MessageParticipant
 
 The author/mention/pinner embedded in a message. Distinct from the event-actor
@@ -4683,7 +4731,7 @@ The canonical broadcast message (distinct from the history [Message schema](#mes
 | `threadParentMessageCreatedAt` | string | Optional. RFC 3339. |
 | `tshow` | boolean | Optional. Whether a thread reply is also shown in the parent room. |
 | `type` | string | Optional. System-message type when set. |
-| `sysMsgData` | string | Optional. Base64-encoded raw JSON payload for system messages. |
+| `sysMsgData` | string | Optional. Base64-encoded JSON payload for system messages; shape depends on `type` (see [System-message `sysMsgData` payloads](#system-message-sysmsgdata-payloads)). |
 | `quotedParentMessage` | [QuotedParentMessage](#quotedparentmessage) | Optional. |
 | `pinnedAt` | string | Optional. RFC 3339. |
 | `pinnedBy` | [Participant](#participant) | Optional. |

history-service/internal/cassrepo/messages_by_room_integration_test.go

@@ -4,6 +4,7 @@ package cassrepo
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"testing"
 	"time"
@@ -15,6 +16,7 @@ import (
 
 	"github.com/hmchangw/chat/history-service/internal/models"
 	"github.com/hmchangw/chat/pkg/atrest"
+	"github.com/hmchangw/chat/pkg/model"
 	cassmodel "github.com/hmchangw/chat/pkg/model/cassandra"
 	"github.com/hmchangw/chat/pkg/msgbucket"
 	"github.com/hmchangw/chat/pkg/testutil"
@@ -335,3 +337,71 @@ func TestGetMessages_DecryptErrorHaltsWalk(t *testing.T) {
 	assert.ErrorIs(t, walkErr, atrest.ErrPayloadMalformed,
 		"walk must halt on the day-1 malformed-nonce error; surfacing ErrAuthFailed means the walk continued past day1 and let day2 overwrite scanErr")
 }
+
+func TestGetMessagesBefore_SysMsgDataRoundTrips(t *testing.T) {
+	session := setupCassandra(t)
+	sizer := msgbucket.New(24 * time.Hour)
+	repo := NewRepository(session, sizer, 365, nil)
+	ctx := context.Background()
+
+	roomID := "room-sysmsg"
+	createdAt := time.Now().UTC().Truncate(time.Millisecond)
+	sender := models.Participant{ID: "u_a", Account: "alice"}
+
+	payload, err := json.Marshal(model.MembersAdded{Individuals: []string{"u1", "u2"}, Orgs: []string{"o1"}, AddedUsersCount: 3})
+	require.NoError(t, err)
+
+	require.NoError(t, session.Query(
+		`INSERT INTO messages_by_room (room_id, bucket, created_at, message_id, sender, msg, type, sys_msg_data) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+		roomID, sizer.Of(createdAt), createdAt, "m-sys", sender,
+		`"alice" added 2 people and 1 organization to the chatroom`,
+		model.MessageTypeMembersAdded, payload,
+	).Exec())
+
+	page, err := repo.GetMessagesBefore(ctx, roomID, createdAt.Add(time.Second), time.Time{}, PageRequest{PageSize: 10})
+	require.NoError(t, err)
+	require.Len(t, page.Data, 1)
+
+	got := page.Data[0]
+	assert.Equal(t, model.MessageTypeMembersAdded, got.Type)
+	require.NotEmpty(t, got.SysMsgData, "sysMsgData must survive the load-history round-trip")
+
+	var decoded model.MembersAdded
+	require.NoError(t, json.Unmarshal(got.SysMsgData, &decoded))
+	assert.Equal(t, []string{"u1", "u2"}, decoded.Individuals)
+	assert.Equal(t, []string{"o1"}, decoded.Orgs)
+	assert.Equal(t, 3, decoded.AddedUsersCount, "whole payload (not just the slices) must survive")
+}
+
+// An orgs-only add stores Individuals as []; it must survive as [] (non-nil),
+// not null, so the frontend can read .length without a guard.
+func TestGetMessagesBefore_SysMsgDataEmptySlice(t *testing.T) {
+	session := setupCassandra(t)
+	sizer := msgbucket.New(24 * time.Hour)
+	repo := NewRepository(session, sizer, 365, nil)
+	ctx := context.Background()
+
+	roomID := "room-sysmsg-empty"
+	createdAt := time.Now().UTC().Truncate(time.Millisecond)
+	sender := models.Participant{ID: "u_a", Account: "alice"}
+
+	payload, err := json.Marshal(model.MembersAdded{Individuals: []string{}, Orgs: []string{"o1"}})
+	require.NoError(t, err)
+
+	require.NoError(t, session.Query(
+		`INSERT INTO messages_by_room (room_id, bucket, created_at, message_id, sender, msg, type, sys_msg_data) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+		roomID, sizer.Of(createdAt), createdAt, "m-sys-empty", sender,
+		`"alice" added 1 organization to the chatroom`,
+		model.MessageTypeMembersAdded, payload,
+	).Exec())
+
+	page, err := repo.GetMessagesBefore(ctx, roomID, createdAt.Add(time.Second), time.Time{}, PageRequest{PageSize: 10})
+	require.NoError(t, err)
+	require.Len(t, page.Data, 1)
+
+	var decoded model.MembersAdded
+	require.NoError(t, json.Unmarshal(page.Data[0].SysMsgData, &decoded))
+	require.NotNil(t, decoded.Individuals, "empty individuals must survive as [] not null")
+	assert.Empty(t, decoded.Individuals)
+	assert.Equal(t, []string{"o1"}, decoded.Orgs)
+}

pkg/model/member.go

@@ -206,8 +206,9 @@ type MentionableSubscriptionsResponse struct {
 
 // CreateRoomRequest is the canonical event payload (X-Request-ID rides on the NATS header).
 // Users/Orgs/Channels are the literal client request; ResolvedUsers/ResolvedOrgs carry the
-// post-expansion (channel-ref-merged, requester-stripped, dedup'd) sets the worker uses for
-// member materialization. Sys-message payloads use the literal lists.
+// post-expansion (channel-ref-merged, requester-stripped, dedup'd) sets. The worker uses the
+// resolved sets for member materialization and the members_added sys-message; room_created
+// uses the literal lists.
 type CreateRoomRequest struct {
 	Name     string       `json:"name"     bson:"name"`
 	Users    []string     `json:"users"    bson:"users"`

room-worker/handler.go

@@ -449,7 +449,7 @@ func (h *Handler) processRemoveIndividual(ctx context.Context, req *model.Remove
 	if isSelfLeave {
 		content = formatLeft(&user.User)
 	} else {
-		content = formatRemovedUser(&user.User)
+		content = formatRemovedUser(requester, &user.User)
 	}
 	sysMsg := model.Message{
 		ID:          idgen.MessageIDFromRequestID(seed, "rmindiv"),
@@ -652,7 +652,7 @@ func (h *Handler) processRemoveOrg(ctx context.Context, req *model.RemoveMemberR
 		UserID:      requester.ID,
 		UserAccount: requester.Account,
 		Type:        model.MessageTypeMemberRemoved,
-		Content:     formatRemovedOrg(name, tcName, req.OrgID),
+		Content:     formatRemovedOrg(requester, name, tcName, req.OrgID),
 		SysMsgData:  sysMsgPayload,
 		CreatedAt:   now,
 	}
@@ -1042,8 +1042,8 @@ func (h *Handler) processAddMembers(ctx context.Context, data []byte) (err error
 	// (actualAccounts) or new org rows (req.Orgs). The org→individual upgrade
 	// path (only needIRM populated) writes the missing individual room_members
 	// row silently — no membership state changed for the room itself, so
-	// emitting an empty MemberAddEvent and a "added members to the channel"
-	// sys-msg with no actual members listed would mislead end users.
+	// emitting an empty MemberAddEvent and a members_added sys-msg with no
+	// actual members listed would mislead end users.
 	historySharedSince := historySharedSincePtr(req.History, req.Timestamp, req.RoomID)
 	if len(actualAccounts) > 0 || len(req.Orgs) > 0 {
 		memberAddEvt := model.MemberAddEvent{
@@ -1086,21 +1086,23 @@ func (h *Handler) processAddMembers(ctx context.Context, data []byte) (err error
 			}
 		}
 
+		// Individuals = req.Users (direct + channel individuals, already merged
+		// by room-service; org members ride in Orgs). Counts are list lengths.
 		membersAdded := model.MembersAdded{
-			Individuals:     actualAccounts,
-			Orgs:            req.Orgs,
+			Individuals:     nonNil(req.Users),
+			Orgs:            nonNil(req.Orgs),
 			Channels:        req.Channels,
 			AddedUsersCount: len(subs),
 		}
 		sysMsgData, _ := json.Marshal(membersAdded)
 		seed := messageDedupSeed(ctx, "processAddMembers", req.RoomID,
 			fmt.Sprintf("%s:%s:%d", req.RoomID, req.RequesterAccount, req.Timestamp))
-		// Single form only for direct 1-user adds; org-bearing adds always use multi.
-		content := formatAddedMulti(requester)
-		if len(subs) == 1 && len(req.Orgs) == 0 {
-			onlyUser := userMap[subs[0].User.Account]
-			content = formatAddedSingle(requester, &onlyUser)
-		}
+		content := addedContent(requester, req.Users, req.Orgs, func(a string) *model.User {
+			if u, ok := userMap[a]; ok {
+				return &u
+			}
+			return nil
+		})
 		sysMsg := model.Message{
 			ID:          idgen.MessageIDFromRequestID(seed, "addmembers"),
 			RoomID:      req.RoomID,
@@ -1503,7 +1505,7 @@ func (h *Handler) finishCreateRoom(ctx context.Context, req *model.CreateRoomReq
 
 	// Task 36: channel-only sys-messages
 	if room.Type == model.RoomTypeChannel {
-		if err := h.publishChannelSysMessages(ctx, req, room, requester, len(subs)-1, requestID, now); err != nil {
+		if err := h.publishChannelSysMessages(ctx, req, room, requester, userByAccount, len(subs)-1, requestID, now); err != nil {
 			return fmt.Errorf("publish sys messages: %w", err)
 		}
 	}
@@ -1589,7 +1591,7 @@ func (h *Handler) finishCreateRoom(ctx context.Context, req *model.CreateRoomReq
 	return nil
 }
 
-func (h *Handler) publishChannelSysMessages(ctx context.Context, req *model.CreateRoomRequest, room *model.Room, requester *model.User, addedUsersCount int, requestID string, now time.Time) error {
+func (h *Handler) publishChannelSysMessages(ctx context.Context, req *model.CreateRoomRequest, room *model.Room, requester *model.User, userByAccount map[string]*model.User, addedUsersCount int, requestID string, now time.Time) error {
 	acceptedAt := time.UnixMilli(req.Timestamp).UTC()
 
 	sysData1, err := json.Marshal(model.RoomCreated{
@@ -1616,22 +1618,32 @@ func (h *Handler) publishChannelSysMessages(ctx context.Context, req *model.Crea
 		return fmt.Errorf("publish room_created: %w", err)
 	}
 
+	// ResolvedUsers = resolved individuals, already creator-stripped and
+	// org-member-free by room-service; Orgs counted as orgs, not expanded.
+	if len(req.ResolvedUsers) == 0 && len(req.ResolvedOrgs) == 0 {
+		// Nothing added beyond the creator (e.g. an empty channel); room_created
+		// already fired, so do not emit a degenerate "added 0 people" message.
+		return nil
+	}
 	sysData2, err := json.Marshal(model.MembersAdded{
-		Individuals:     req.Users,
-		Orgs:            req.Orgs,
+		Individuals:     nonNil(req.ResolvedUsers),
+		Orgs:            nonNil(req.ResolvedOrgs),
 		Channels:        req.Channels,
 		AddedUsersCount: addedUsersCount,
 	})
 	if err != nil {
 		return fmt.Errorf("marshal members_added sys data: %w", err)
 	}
+	content := addedContent(requester, req.ResolvedUsers, req.ResolvedOrgs, func(a string) *model.User {
+		return userByAccount[a]
+	})
 	msg2 := model.Message{
 		ID:          idgen.MessageIDFromRequestID(requestID, "members_added"),
 		RoomID:      room.ID,
 		UserID:      requester.ID,
 		UserAccount: requester.Account,
 		Type:        model.MessageTypeMembersAdded,
-		Content:     formatAddedMulti(requester),
+		Content:     content,
 		SysMsgData:  sysData2,
 		CreatedAt:   acceptedAt.Add(time.Millisecond),
 	}