# ListUsersByRole

## Overview

ListUsersByRole returns the current ACTIVE users assigned to a given role. PENDING and INACTIVE users are deliberately excluded so callers receive only the membership that can act on the system right now; deactivated users may have been intentionally suspended and re-assigning them work would defeat that suspension.

## Business Rules

- Accepts a `roleId` as input
- Returns users assigned to the role via UserRole join records whose `User.status = ACTIVE`
- Excludes users whose `User.status` is `PENDING` or `INACTIVE`
- Returns an empty array when the role exists but has no ACTIVE assignments — not an error
- The role must exist; a non-existent `roleId` returns an error

## Process Flow

```mermaid
flowchart TD
    A[Receive roleId] --> B{Role exists?}
    B -->|No| C[Return error: ROLE_NOT_FOUND]
    B -->|Yes| D[SELECT users via UserRole<br/>where roleId = input<br/>and User.status = ACTIVE]
    D --> E{Any users found?}
    E -->|Yes| F[Return user records]
    E -->|No| G[Return empty array]
```

## External Dependencies

- None

## Error Scenarios

- **ROLE_NOT_FOUND**: Specified role ID does not exist

## Test Cases

- returns all users currently assigned to the role with status ACTIVE
- excludes PENDING users from the result
- excludes INACTIVE users from the result
- returns an empty array when the role exists but has no ACTIVE assignments
- returns ROLE_NOT_FOUND when the role does not exist