# GetAnnualLeaveRegister

## Overview

Returns the annual paid-leave compliance register for one worker (ADR-009), derived entirely from the ledger — there is no stored register. It reports one row per STATUTORY `LeaveGrant`: the grant's date, amount, and expiration, the days actually taken against it, the derived remaining, and — for a grant of 10 or more days — the **5-day mandatory-acquisition obligation** (Labor Standards Act Article 39 ⑦): the grant-year deadline (`grantedDate` + 1 year), how many paid-leave days were taken within that window, and whether the duty is satisfied or the worker is at risk. See the [annual-leave-register feature](../feature/annual-leave-register.md) for the full compliance context.

## Business Rules

- One register row per STATUTORY `LeaveGrant` for the worker; a `leaveTypeKey` may be supplied to restrict the register to one leave type, otherwise all STATUTORY grants are included
- Non-STATUTORY grants (COMPENSATORY, MANUAL) are excluded — the register is the statutory annual-leave record
- "Taken" means an APPROVED `LeaveRequest`; PENDING / CANCEL_PENDING reservations are not yet taken, and REJECTED / CANCELLED never happened
- `takenDays` for a grant is the sum of APPROVED `LeaveConsumption` against it; `remainingDays` = `grantedDays` − `takenDays`, derived from the ledger and never read from a stored column (ADR-005)
- A grant of 10 or more days is `subjectToFiveDayDuty`, with a `fiveDayDeadline` of `grantedDate` + 1 year; a grant of fewer than 10 days is not subject and carries no deadline
- `fiveDayTakenDays` counts paid-leave days taken (APPROVED) anywhere in the grant year `[grantedDate, deadline]`, not only what drew from that specific grant
- The duty is met (`fiveDayDutyMet`) when a subject grant has `fiveDayTakenDays` ≥ 5; a subject grant that has not is `fiveDayAtRisk`

## Process Flow

```mermaid
flowchart TD
    A[Caller requests register for workerId + optional leaveTypeKey] --> B[Load STATUTORY grants for the worker]
    B --> C[Load APPROVED takings against those grants with their start dates]
    C --> D[Per grant: takenDays = approved consumption; remainingDays = granted - taken]
    D --> E{grantedDays >= 10?}
    E -- No --> F[Row without the 5-day duty]
    E -- Yes --> G[deadline = grantedDate + 1 year; fiveDayTakenDays = approved takings in the grant year]
    G --> H{fiveDayTakenDays >= 5?}
    H -- Yes --> I[Duty satisfied]
    H -- No --> J[At risk: report shortfall and deadline]
    F --> K[Return register rows]
    I --> K
    J --> K
```

## External Dependencies

- [leave-management::LeaveGrant](../model/LeaveGrant.md) model — the grant ledger the register rows are built from
- [leave-management::LeaveConsumption](../model/LeaveConsumption.md) model — the consumption ledger joined to compute taken days
- [leave-management::LeaveRequest](../model/LeaveRequest.md) model — supplies each taking's `startDate` and APPROVED status
- [workforce::Worker](../../../workforce/docs/model/Worker.md) model — referenced by `workerId`

## Error Scenarios

_None — the register is a read-only aggregate; an unknown worker simply yields an empty register._

## Test Cases

- returns one register row per STATUTORY grant with granted, taken, and remaining derived from the ledger
- non-STATUTORY grants are excluded from the register
- a grant of 10+ days is marked subject to the 5-day obligation with a grant-year deadline
- a grant of fewer than 10 days is not subject to the 5-day obligation
- a worker who has taken 5+ paid-leave days within the grant year is marked compliant
- a worker who has taken fewer than 5 within the grant year is flagged at-risk
- taken days are counted only from APPROVED requests
- a worker with no STATUTORY grants returns an empty register