List Payroll Runs

The company's payroll runs — one per wage period — newest period first (CompanyMember read; the money is aggregate, no per-employee PII).

A run walks draft → calculated → approved → posted → paid → locked (plus reversed); run_kind separates a regular run from a correction/reversal, which are always separate runs, never in-place edits, and are linked by original_run_id / reversed_by_run_id. journal_entry_id is the wage entry it posted (null before posted), and the lifecycle stamps (calculated_at, approved_at, posted_at, paid_at, locked_at) say when each step happened.

Each row also carries employee_count, gross_total/net_total and the validation error_count/warning_count — a run with errors must not be approved. staleness is computed at read time: non-null means master data changed after the run was calculated (a retroactive correction), so the frozen figures no longer match; it is advisory, and its action says what to do.

Filters: status_filter narrows to one lifecycle state, year to runs whose period starts in that calendar year. No paging. Use GET …/payroll/runs/due for wage months that have no run yet.