# ListApprovalRequestsByTarget

## Overview

ListApprovalRequestsByTarget returns every `ApprovalRequest` ever created against a given `(targetEntityType, targetEntityId)` pair, terminal and non-terminal alike, ordered by creation time. It is the canonical history lookup for a target — for example "show me every approval ever requested for this product" — and is what allows the V1 rework substitute (cancel/reject + new request) to preserve the trail without mutating prior rows. The query also accepts an optional `status` filter for callers that want to narrow to a particular state.

## Business Rules

- Accepts `targetEntityType` (free string) and `targetEntityId` (UUID) as required inputs
- Accepts an optional `status` filter (one of `PENDING` | `APPROVED` | `REJECTED` | `REVISION_REQUESTED` | `CANCELLED` | `WITHDRAWN`); when omitted, every status is returned
- Accepts standard pagination inputs (`limit`, `offset`, `orderBy`, `orderDirection`); `limit` defaults to the framework `DEFAULT_PAGE_SIZE`
- Default ordering when no `orderBy` is supplied is `createdAt DESC` (most recent first) so list views render the latest request at the top
- Returns a paginated result `{ items, hasNextPage }`; an empty `items` array is not an error
- Returns terminal-state requests indefinitely (the module never hard-deletes requests)

## Process Flow

```mermaid
flowchart TD
    A[Receive targetEntityType, targetEntityId, optional status,<br/>plus optional pagination inputs] --> B[SELECT ApprovalRequest<br/>where targetEntityType matches<br/>and targetEntityId matches<br/>and status matches if supplied]
    B --> C[ORDER BY orderBy orderDirection<br/>default createdAt DESC]
    C --> D[LIMIT limit + 1 OFFSET offset]
    D --> E[Return paginated result &lcub; items, hasNextPage &rcub;]
```

## External Dependencies

- None

## Error Scenarios

- None — an empty result is not an error

## Test Cases

- returns all requests for a given target — terminal and non-terminal — when no status filter is supplied
- filters to a single status when the optional filter is supplied
- returns terminal requests indefinitely (no time-window cutoff)
- returns an empty array when the target has never had a request
- returns requests in createdAt DESC order so the most recent appears first
- includes both policy-mode and direct-mode requests in the result
