# ListPunchesByOccurredDate

## Overview

Lists all `TimeClockEvent`s on a given occurred date, raw and pre-day-breaker, paginated. Because a punch's `occurredAt` date is not the same as the workday it is later assigned to, this query is useful for investigating what physically happened on a calendar date before any day-breaker logic is applied.

## Business Rules

- Filters by the calendar date portion of `occurredAt`, not by any derived `workDate` (no day-breaker logic is applied at this layer)
- Returns raw events only; no pairing into blocks or workday assignment is performed
- Includes events across all Assignments and sources for that date
- Results are paginated

## Process Flow

```mermaid
flowchart TD
    A[Caller supplies occurredDate + pagination params] --> B{Valid date?}
    B -- No --> C[Return INVALID_QUERY_PARAMS]
    B -- Yes --> D[Look up TimeClockEvents whose occurredAt falls on occurredDate]
    D --> E[Return paginated page of raw events, pre-day-breaker]
```

## External Dependencies

- [time-tracking::TimeClockEvent](../model/TimeClockEvent.md) model — entity being queried

## Error Scenarios

- **INVALID_QUERY_PARAMS**: a required query parameter is missing or malformed

## Test Cases

- returns all events whose occurredAt falls on the given calendar date
- an overnight clock-out just after midnight is returned for the date it actually occurred on, not the prior workday
- returns an empty page when no events occurred on the given date
- returns events across multiple Assignments and sources for the same date
- returns INVALID_QUERY_PARAMS when occurredDate is malformed