# GetCompanyHolidayByDate

## Overview

GetCompanyHolidayByDate resolves the holiday fact for a specific `(calendarId, holidayDate)`. It is the lookup calculation uses to determine holiday classification and premium on a calculated date — scoped to the calendar resolved from the worker's effective `WorkRule.holidayCalendarId` — and scheduling uses to determine whether a date is a scheduled working day.

## Business Rules

- Resolves by the scoped business key — `(calendarId, holidayDate)` — not the surrogate id, since `holidayDate` is unique per `(calendarId, holidayDate)`
- Returns no result (not an error) when the date is not registered as a holiday **in the given calendar** — a date with no CompanyHoliday record for that calendar is an ordinary working day, even if the same date is a holiday in another calendar
- `holidayKind` (`STATUTORY` / `PRESCRIBED`) is the value calculation binds to for premium determination; it is never resolved via `name`
- `CompanyHoliday` is a plain dated fact, not effective-dated — the lookup always reflects the current, in-place-corrected state, with no `asOf` history to reconstruct

## Process Flow

```mermaid
flowchart TD
    A[Caller provides calendarId and a date] --> B[Look up CompanyHoliday by calendarId + holidayDate]
    B --> C{Registered as holiday in this calendar?}
    C -- Yes --> D[Return CompanyHoliday: holidayKind, name]
    C -- No --> E[Return null: ordinary working day]
    D --> F[Calculation applies holiday premium by holidayKind]
    D --> G[Scheduling treats date as non-scheduled]
```

## External Dependencies

- [time-tracking::CompanyHoliday](../model/CompanyHoliday.md) model — entity being queried
- [time-tracking::HolidayCalendar](../model/HolidayCalendar.md) model — `calendarId` scopes the lookup
- Consumed by time-tracking calculation (Reported → Calculated) to determine holiday classification and premium on the calculated date, scoped by the effective `WorkRule.holidayCalendarId`
- Consumed by scheduling to determine scheduled working-day status when building schedules and shifts

## Error Scenarios

- **VALIDATION_ERROR**: the supplied input is malformed, out of range, or references an unrecognized enum value

## Test Cases

- returns the CompanyHoliday when the date is registered as a holiday in the given calendar
- returns null when the date has no registered holiday in that calendar (ordinary working day), even if the same date is a holiday in another calendar
- calculation resolves holiday treatment via `getCompanyHolidayByDate` scoped to the effective `WorkRule.holidayCalendarId` and `holidayKind`, not via `name`
- a STATUTORY holiday resolved by `(calendarId, date)` triggers statutory holiday premium; a PRESCRIBED holiday does not
- returns VALIDATION_ERROR when calendarId or holidayDate is missing or malformed