OpenSpeak/openspec/changes/add-channel-management/channel.md

# Spec Delta: Channel Management

**Change ID:** `add-channel-management`
**Capability:** Channel Management
**Type:** NEW

## ADDED Requirements

### Channel Creation

#### Requirement: Users with permission shall create voice channels

**Description:** Authenticated users with `channels:create` permission can create new voice channels with unique names, descriptions, and access control settings.

**Priority:** Critical
**Status:** Proposed

**Scenarios:**

#### Scenario: User creates public channel
```
Given: User is authenticated with create permission
When: User requests CreateChannel with name "general" and is_public=true
Then: New channel created with unique ID
And: User set as channel owner
And: Channel marked as public
And: All other users can join
And: CreateChannel response includes channel details
```

#### Scenario: Duplicate channel name rejected
```
Given: Channel "general" already exists
When: User requests CreateChannel with name "general"
Then: Request rejected with AlreadyExists error
And: User must choose different name
```

#### Scenario: Invalid channel name rejected
```
Given: User requests channel with empty name
When: User sends CreateChannel request
Then: Request rejected with InvalidArgument error
And: Validation fails with clear error message
```

### Joining Channels

#### Requirement: Users shall join channels with permission verification

**Description:** Users can join public channels if authenticated. Private channels require owner approval or whitelist.

**Priority:** Critical
**Status:** Proposed

**Scenarios:**

#### Scenario: User joins public channel
```
Given: User is authenticated
And: "general" channel is public
When: User requests JoinChannel
Then: User added to channel members
And: UserJoined event broadcast to channel
And: Response includes channel members
And: User can now send/receive voice
```

#### Scenario: User joins private channel with permission
```
Given: User is whitelisted for private channel
When: User requests JoinChannel
Then: User added to channel
And: Access granted
```

#### Scenario: Unauthorized user denied private channel
```
Given: User not whitelisted for private channel
When: User requests JoinChannel
Then: Request rejected with PermissionDenied
And: User cannot join channel
```

#### Scenario: Channel at capacity
```
Given: Channel has max_users=5
And: 5 users already in channel
When: 6th user joins
Then: Request rejected with ResourceExhausted error
And: Error message: "Channel is full"
```

### Leaving Channels

#### Requirement: Users shall leave channels cleanly

**Description:** Users can leave channels at any time. Leaving stops voice streams and removes user from member list.

**Priority:** Critical
**Status:** Proposed

**Scenarios:**

#### Scenario: User leaves channel
```
Given: User is in "general" channel
When: User requests LeaveChannel
Then: User removed from channel members
And: UserLeft event broadcast to channel
And: Voice streams stopped
And: Cleanup completed
```

#### Scenario: User disconnects (implicit leave)
```
Given: User connected to channel
When: User connection is lost
Then: Server detects disconnection
And: User removed from channel after timeout
And: UserLeft event broadcast
```

### Channel Member Management

#### Requirement: Server shall track and provide channel member list

**Description:** At any time, can query active members of a channel including their presence status and mute state.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: Get channel member list
```
Given: Channel has 3 members
When: User requests ListMembers
Then: Response includes all 3 members
And: Each member includes: user_id, status, mute_state
And: List includes joining order (optional)
```

#### Scenario: Member presence updated
```
Given: User is in channel
When: User mutes microphone
Then: Server updates member mute state
And: UserMuteStateChanged event broadcast
And: Other members see user as muted
```

### Channel Access Control

#### Requirement: Channels shall enforce public/private access control

**Description:** Public channels allow any authenticated user to join. Private channels restrict membership.

**Priority:** Critical
**Status:** Proposed

**Details:**
- Public: Any authenticated user can join
- Private: Owner only, future whitelist support

**Scenarios:**

#### Scenario: Public channel visible and joinable
```
Given: Channel is marked is_public=true
When: Any authenticated user lists channels
Then: Channel appears in list
And: User can join without approval
```

#### Scenario: Private channel visibility
```
Given: Channel is marked is_public=false
When: Non-owner lists channels
Then: Private channel may not appear
Or: Channel appears but join is denied
```

### Channel Capacity

#### Requirement: Channels shall enforce user capacity limits

**Description:** Channels can have maximum concurrent users limit. Default is unlimited.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: Unlimited capacity (default)
```
Given: Channel created with max_users=0
When: 100 users try to join
Then: All 100 accepted and added to channel
And: No capacity limit enforced
```

#### Scenario: Limited capacity enforced
```
Given: Channel has max_users=10
And: 9 users already in channel
When: 10th user joins - succeeds
And: 11th user attempts join
Then: Request rejected with ResourceExhausted
```

### Channel Events

#### Requirement: Channel changes broadcast to members

**Description:** Events like user joining/leaving, channel updated, etc. broadcast to all channel members in real-time.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: User join event broadcast
```
Given: User A is in channel
When: User B joins channel
Then: User A receives UserJoinedEvent
And: Event includes new user info
And: Event includes timestamp
And: All channel members receive event
```

#### Scenario: Channel update event
```
Given: Channel members listening for events
When: Channel owner updates channel name
Then: All members receive ChannelUpdatedEvent
And: Event includes new channel state
```

## ACCEPTANCE CRITERIA

- [ ] Users can create channels with validation
- [ ] Public/private access control enforced
- [ ] Capacity limits enforced
- [ ] Users can join/leave channels
- [ ] Member list accurate and updatable
- [ ] Events broadcast to channel members
- [ ] Proper error messages for failures
- [ ] Unit test coverage >80%
- [ ] Integration tests pass

## TESTING STRATEGY

### Unit Tests
- Test channel creation with various inputs
- Test name validation and uniqueness
- Test capacity checking logic
- Test access control rules

### Integration Tests
- Test full join/leave flow
- Test events broadcast to multiple members
- Test concurrent joins
- Test private/public channel access

### Scenarios Tests
- 10+ users join same channel
- Channels reach capacity and reject
- Multiple channels with same name in different contexts