# Work and Pay Rules

## Overview

Work Rules is the **rule-engine core** (work rules) of work-rules. It maintains `WorkRule` — the complete, assignable rule combining rounding, break deduction, daily overtime threshold, night window, and premium-category pins — that is assigned, effective-dated, to an employment or worker (ADR-022). This is the UKG Work Rule model (issue #7): calculation is driven by composed configuration, so a law or policy change is absorbed by a new effective generation rather than by code (issue #13). (The `payPeriod` and `dayBreakerMinute` fields absorbed from the former PayRule were dropped in #39 as unused.)

## Business Purpose

- Externalize rounding / break / overtime / night / premium mechanics as composable, parameterized building blocks instead of embedding them in calculation code (ADR-015)
- WorkRule is the single assignable rule so a worker is simply *on* a rule from which every parameter derives
- Absorb legal changes (premium-rate revisions, overtime-cap reforms) by inserting a new effective-dated generation — no code change, no redeploy (issue #13, absorbing legal reforms under a flat-fee maintenance model)
- Keep calculation reproducible: the rule generation effective on the calculated date is always resolvable, so recomputation is deterministic (ADR-014)

## Process Flow

```mermaid
flowchart TD
    A[Define WorkRule: rounding, break, overtime, night, premium-category pins] --> B[Assign WorkRule to employment/worker, effective-dated]
    B --> C[Time-tracking resolves the WorkRule generation effective on the calculated date]
    C --> D[Apply WorkRule to ReportedTimeBlock]
    D --> E[Produce CalculatedTimeBlock with CalculationTag]
    A --> F{Law or policy change on date D}
    F -- Yes --> G[Close current generation at D minus 1, insert new generation effective D]
    G --> H[Recalculate affected dates; no code change]
```

## Scenario Patterns

- **Define building blocks**: create WorkRules for rounding, break deduction, the 480-minute daily overtime threshold, the 22:00–05:00 night window, and premium-category pins
- **Assign**: assign a WorkRule effective-dated to an employment
- **Law-change absorption**: a premium-category pin revision inserts a new WorkRule generation effective on the change date; prior periods keep the old configuration
- **Future-dated change**: a scheduled pin change with a future `effectiveStart` does not affect calculation until its start date
- **Retroactive correction**: inserting a past-dated generation triggers recomputation of the affected calculated time (ADR-014)
- **Managerial exemption**: a supervisory/managerial-staff population's WorkRule suppresses statutory overtime premium (paired with EligibilityRule)

## Test Cases

- assigning a WorkRule resolves exactly one in-force generation for a worker on a given date
- a premium-category pin change closes the prior generation and inserts a new one with no range overlap
- a future-dated pin change is not applied before its `effectiveStart`
- rounding is applied separately for clock-in, clock-out, and break per the configured unit and direction
- overtime begins at `dailyOvertimeThresholdMinutes` (e.g. 480) for a fixed-hours regime
- premium-category pins resolve by TimeEntryCode `category`/`key`, not by display name
- recomputing a period with the same reported input and same rule generation yields identical calculated output

## Reference Links

- Data-model design research (UKG Pay Rule / Work Rule building blocks, Reported→Calculated): https://github.com/tailor-sandbox/Omakase-ERP-attendance/issues/7
- Customization reality (configuration-layer absorbs law change, no code changes): https://github.com/tailor-sandbox/Omakase-ERP-attendance/issues/13
- Cautionary lesson: calculation must bind to semantic keys, not display-name strings: https://github.com/tailor-sandbox/Omakase-ERP-attendance/issues/14