# Grey Queue State Machine

Sprint: SPRINT_20260118_018_Unknowns_queue_enhancement (UQ-005)

## State Diagram

```mermaid
stateDiagram-v2
    [*] --> Pending: Entry created

    Pending --> Processing: Start processing
    Pending --> UnderReview: Assign to reviewer
    Pending --> Expired: TTL exceeded
    Pending --> Dismissed: Manual dismissal

    Processing --> Retrying: Processing failed (retry)
    Processing --> UnderReview: Needs human review
    Processing --> Resolved: Successfully resolved
    Processing --> Failed: Max attempts exhausted

    Retrying --> Processing: Retry attempt
    Retrying --> Failed: Max attempts exhausted
    Retrying --> Expired: TTL exceeded

    UnderReview --> Escalated: Escalate to security
    UnderReview --> Resolved: Reviewer resolves
    UnderReview --> Rejected: Reviewer rejects
    UnderReview --> Pending: Unassign (reset)

    Escalated --> Resolved: Security resolves
    Escalated --> Rejected: Security rejects
    Escalated --> UnderReview: De-escalate

    Rejected --> Pending: Reopen
    Failed --> Pending: Reset for retry
    Dismissed --> Pending: Reopen

    Resolved --> [*]
    Expired --> [*]
```

## States

| State | Description | Entry Criteria | Exit Criteria |
|-------|-------------|----------------|---------------|
| **Pending** | Awaiting initial processing | Entry created | Processing started, assigned, expired, or dismissed |
| **Processing** | Actively being processed by automation | Processing started | Retry, human review, resolved, or failed |
| **Retrying** | Waiting for retry after failed attempt | Processing failed | Retry attempt, max attempts, or TTL |
| **UnderReview** | Assigned to human reviewer | Needs human decision | Escalated, resolved, rejected, or unassigned |
| **Escalated** | Promoted to security team | Reviewer escalates | Security team decision |
| **Resolved** | Evidence now sufficient (terminal) | Automated or manual resolution | N/A |
| **Rejected** | Invalid or not actionable | Reviewer/security rejects | Can be reopened |
| **Failed** | Exhausted all retries (terminal-ish) | Max attempts exceeded | Can be reset |
| **Expired** | TTL exceeded (terminal) | Time limit reached | N/A |
| **Dismissed** | Manually dismissed (terminal-ish) | Operator dismissal | Can be reopened |

## State Requirements

### UnderReview
- **Requires**: `assignee` field must be set
- **Triggers**: Assignment notification to reviewer
- **Validation**: Cannot transition without assignee

### Escalated  
- **Requires**: `escalation_reason` field
- **Triggers**: Notification to security team
- **Sets**: `escalated_at` timestamp

### Rejected
- **Records**: Reason and who rejected
- **Allows**: Reopening back to Pending

## Valid Transitions

```
Pending       → [Processing, UnderReview, Expired, Dismissed]
Processing    → [Retrying, UnderReview, Resolved, Failed]
Retrying      → [Processing, Failed, Expired]
UnderReview   → [Escalated, Resolved, Rejected, Pending]
Escalated     → [Resolved, Rejected, UnderReview]
Resolved      → []  (terminal)
Rejected      → [Pending]
Failed        → [Pending]
Expired       → []  (terminal)
Dismissed     → [Pending]
```

## Transition Audit

All transitions are recorded in `grey_queue_state_transitions` table:

| Column | Description |
|--------|-------------|
| `entry_id` | Grey queue entry reference |
| `from_state` | Previous state |
| `to_state` | New state |
| `transitioned_by` | User who triggered transition |
| `reason` | Optional reason for transition |
| `transitioned_at` | Timestamp |
| `metadata` | Additional context (JSONB) |

## API Endpoints

| Endpoint | Transition |
|----------|------------|
| `POST /api/grey-queue/{id}/assign` | → UnderReview |
| `POST /api/grey-queue/{id}/escalate` | → Escalated |
| `POST /api/grey-queue/{id}/reject` | → Rejected |
| `POST /api/grey-queue/{id}/reopen` | → Pending |
| `POST /api/grey-queue/{id}/resolve` | → Resolved |
| `POST /api/grey-queue/{id}/dismiss` | → Dismissed |
| `GET /api/grey-queue/{id}/transitions` | Get valid next states |

## Code Reference

- State enum: `src/Unknowns/__Libraries/StellaOps.Unknowns.Core/Models/GreyQueueEntry.cs`
- State machine: `GreyQueueStateMachine` class in same file
- Endpoints: `src/Unknowns/StellaOps.Unknowns.WebService/Endpoints/GreyQueueEndpoints.cs`
- Migration: `devops/database/migrations/V20260119_001__Add_UnderReview_Escalated_Rejected_States.sql`