# GrantPermissionToRole

## Permission Scope

role

## Overview

GrantPermissionToRole adds a permission key to a role's `permissions` array. The operation is idempotent — granting the same permission twice does not create duplicates or return an error.

When the permissions array changes, an executor recomputes effective permissions for all users assigned to the role.

## Business Rules

- Permission key must be a valid format
- Role must exist in the system
- Role must be in ACTIVE status
- Operation is idempotent (granting the same permission twice is not an error)
- Adds the permission key to the role's permissions array if not already present
- Triggers executor to recompute effective permissions for affected users

## Process Flow

```mermaid
flowchart TD
    A[Receive grant request] --> B{Permission key format valid?}
    B -->|No| C[Return error: INVALID_PERMISSION]
    B -->|Yes| D{Role exists?}
    D -->|No| E[Return error: ROLE_NOT_FOUND]
    D -->|Yes| F{Role is ACTIVE?}
    F -->|No| G[Return error: ROLE_NOT_ACTIVE]
    F -->|Yes| H{Permission already in array?}
    H -->|Yes| I[Return success - idempotent]
    H -->|No| J[Add permission to role's permissions array]
    J --> K[Return success]
```

## External Dependencies

- None

## Error Scenarios

- **INVALID_PERMISSION**: Permission key has an invalid format
- **ROLE_NOT_FOUND**: Specified role ID does not exist
- **ROLE_NOT_ACTIVE**: Role is not in ACTIVE status and cannot be used for this operation

## Test Cases

- throws when permission key format is invalid
- throws when role does not exist
- throws when role is INACTIVE
- returns success when permission already exists in array (idempotent)
- adds permission key to role's permissions array