PTO Ledger: Accruals, Leave and the Year-End Policy Change

PTO Ledger: Accruals, Leave and the Year-End Policy Change

You've joined the people-systems team that owns the paid-time-off ledger. It credits each employee time off every pay period, charges leave against the balance, and answers "how many hours do I have?" for the HR portal. Payroll's quarterly audit has found three discrepancies in the existing ledger, and Finance has two policy changes queued behind them. All durations are integer minutes (HR talks in hours; 8 hours is 480 minutes). Dates are YYYY-MM-DD strings.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh ledger and returns one result per operation. Every operation is [name, ...args]. Errors are returned as "error: <code>" strings, never raised. An unknown name returns "error: unknown operation"; a wrong number of arguments or an argument of the wrong type (strings where text is expected, integers where a count is expected; true/false are not integers) returns "error: invalid arguments". That check comes before any other. An operation that is not a non-empty list starting with a string is "error: invalid arguments" too.

The ledger has a clock. It starts at 2025-12-31 and only moves forward when you advance it. Nothing is ever back-dated: an employee is only credited for days the clock passes *after* they were entered, whatever their hire date says.

• A date is valid only if it is exactly YYYY-MM-DD and a real calendar day (2026-02-30 and 2026-2-3 are invalid). hire accepts any valid date, past or future. advance must not move the clock backwards (the same day is a no-op returning []).
• Days are processed one at a time. For each day D the clock passes, in this order: (1) year-end rollover (Part 2), (2) credits, (3) leave debits for requests starting on D. Within a step, ledger entries appear in history in the order they were posted.
• Pay periods start on the 1st and the 16th of every month. On each period start, every employee whose hire date is on or before that day is credited with the accrual rate of their tier (an accrual entry).
• Tenure tiers. Completed years of service on a day D is the number of work anniversaries on or before D (the *n*-th anniversary is the hire date plus *n* calendar years; a Feb 29 hire celebrates on Mar 1 in years that have no Feb 29). Under 2 years: tier 0 (200 min/period). 2 to 4: tier 1 (260). 5 or more: tier 2 (320). Because accrual only happens on period starts, a new tier takes effect on the first period start that is on or after the anniversary.
• Leave. request records a pending request for leave from start to end inclusive. part is "full" or "half"; a half-day request must have start == end. Checks: start and end must be valid dates with end >= start, start strictly after the clock, and start not before the employee's hire date, else invalid date; a part other than full/half, or a multi-day half, is invalid day part. A request costs nothing until it is approved.
• Cost is fixed at approve time: each *working day* in the range (Monday to Friday, not a company holiday at that moment) costs 480 minutes, a half day costs 240. A request with no working days fails no working days. Holidays added later never change an approved request's cost.
• The projection. Approval checks the *projected* balance at the leave's start. For an employee, the approved requests that have not started yet, together with the new one, are lined up in (start date, request id) order. Each request in that list is judged on current balance + credits the policy will post on days after the clock up to and including that request's start date - the costs of every request in the list up to and including it. If any of those values is below -960 (16 hours) the approval fails with limit exceeded and nothing changes; exactly -960 is allowed. The projection looks only at future *credits*; it does not know about holidays that have not been added yet.
• Debit. On its start date (after that day's credits) an approved request's stored cost is posted as a leave entry with a negative amount, and the request is marked as started.
• Cancel. A pending request becomes cancelled and returns 0. An approved request becomes cancelled; if its cost had already been debited, a restore entry for exactly the minutes that were debited is posted dated with the clock's current day and that amount is returned, otherwise 0 is returned and it simply stops counting against projections. Anything else is not cancellable.
• history entries are [date, kind, minutes] with kinds accrual, grant, leave (negative), restore and forfeit (negative).

Worked example

[["hire", "ana", "2021-01-02"],
 ["advance", "2026-01-16"],
 ["balance", "ana"],
 ["holiday", "2026-03-14"],
 ["holiday", "2026-03-16"],
 ["request", "r1", "ana", "2026-03-13", "2026-03-17", "full"],
 ["approve", "r1"],
 ["advance", "2026-03-13"],
 ["balance", "ana"],
 ["holiday", "2026-03-17"],
 ["cancel", "r1"],
 ["balance", "ana"]]

returns [true, [], 580, true, true, true, 960, [], 580, true, 960, 1540]. Ana's fifth anniversary is 2026-01-02, so the Jan 1 credit is still the tier-1 260 and every later one is 320. r1 covers Fri 13th to Tue 17th; the 14th is a Saturday and the 16th is a Monday holiday, so only Friday and Tuesday are working days: 960. The 17th becoming a holiday afterwards changes nothing about what was debited.

Part 1 — Payroll audit findings (HR-2217)

Goal: make accruals, leave costs and cancellations follow the rules above. The audit found:

1. "Two employees with the same hire date got different raises in accrual rate. One of them was moved to the next tier a few weeks before their anniversary."
2. "My leave over a long weekend was charged one day too little, and the company holiday fell on a *Saturday*."
3. "I cancelled a vacation after it was already deducted and was refunded a different number of hours than were deducted."

Find the causes yourself; tests/test_ledger.py has the matching failing tests. Hidden tests also cover the error order, the approval boundary (exactly -960), chained approvals in any order, and the cancel / holiday interactions.

Part 2 — Year-end carryover (HR-2240)

Goal: at the start of each new year, an employee may carry over only a capped balance; the rest is forfeited and reported.

Rules

1. Rollover happens on January 1, as step (1) of that day: before any credit or leave debit of January 1.
2. For each employee hired before that January 1 (in emp_id order, plain string comparison): the cap is CARRYOVER_CAPS[tier] where tier is the tier in effect on that January 1. If the balance is greater than the cap, post a forfeit entry dated January 1 for balance - cap. A balance at or below the cap, and any negative balance, is untouched (negative balances carry over as they are).
3. advance returns the forfeiture rows it produced, [year, emp_id, minutes], where year is the year that just ended, ordered by year and then by emp_id. If it crosses several new years, rows from all of them are returned. No forfeiture, no row.
4. A restore posted later is never forfeited retroactively; it just counts toward the next rollover.
5. The projection does not model forfeitures (it stays the optimistic sum described in Part 1).

Example (CARRYOVER_CAPS is 2400 / 2400 / 3600)

[["hire", "ana", "2015-01-05"], ["hire", "bo", "2025-06-10"],
 ["advance", "2026-12-31"], ["balance", "ana"], ["balance", "bo"],
 ["advance", "2027-01-01"], ["balance", "ana"], ["balance", "bo"]]

returns [true, true, [], 7680, 4800, [[2026, "ana", 4080], [2026, "bo", 2400]], 3920, 2600]. On January 1 ana (tier 2, cap 3600) is cut from 7680 to 3600 and then receives that day's 320; bo (tier 0, cap 2400) is cut from 4800 to 2400 and then receives 200.

Part 3 — Front-loaded grants (HR-2301)

Goal: Finance is replacing per-period accrual with front-loaded annual grants. Add ["set_policy", "front_loaded", effective_date] and make the ledger, the projection and the year-end rollover follow the new policy. Requests already approved for future dates must be re-checked.

set_policy rules

1. Errors in this order: invalid policy (the name is not exactly "front_loaded"), policy already set (only one switch is ever allowed), invalid date (not a valid date, not a period start, or not strictly after the clock).
2. From effective_date E on, period starts no longer accrue. Days before E are unchanged.
3. Grants (grant entries). With annual(tier) = FRONT_LOADED_ANNUAL[tier] and months(D) = 12 - D.month, plus one if D is the 1st of the month: a grant is annual(tier on D) * months(D) // 12 (integer division). A grant of 0 is not recorded. A grant is posted, as part of step (2) of day D, when

• D == E for every employee hired before E;
• D is January 1 of any year after E's year, for every employee hired before D;
• D is the hire date, for an employee whose hire date is E or later. Mid-year tier changes therefore do not change the grant until the next January 1. Rollover (Part 2) still runs first on January 1, so the forfeit is taken before the new grant is added.

1. The projection must include exactly the credits advance would post for that employee under whichever policy is in force, including grants dated on a hire date that is not a period start.
2. Re-validation. Immediately after a successful switch, for each employee in emp_id order, take their approved requests that have not started, in (start date, request id) order, and go through them once. Each is judged by the Part 1 projection rule against the *new* policy, counting only the requests that were kept earlier in this pass. A request that breaches -960 is revoked (status revoked, it never debits, it is not cancellable) and does not count for the ones after it; otherwise it is kept. Pending requests and requests that have already started are untouched. set_policy returns the ids of the revoked requests in the order they were revoked (employees in emp_id order, then evaluation order).

bulk_leave is for importing a leave plan. It is exactly the sequence, for i = 0..count-1, of request then approve with request id "<emp_id>-b<i+1>", start first_start + i * every_days (calendar days), end start + days - 1, part "full". A request or approval that would be an error is skipped (a request that fails to approve stays pending, as it would with individual operations). every_days, count and days must be at least 1 (invalid arguments otherwise); first_start is checked like a request's start (valid, after the clock, not before the hire date, else invalid date). Hidden tests import hundreds of leaves for one employee spread over decades.

Example

[["hire", "bo", "2025-06-10"], ["advance", "2026-06-01"],
 ["request", "r1", "bo", "2026-09-07", "2026-09-11", "full"], ["approve", "r1"],
 ["request", "r2", "bo", "2026-10-05", "2026-10-08", "full"], ["approve", "r2"],
 ["request", "r3", "bo", "2026-12-21", "2026-12-23", "full"], ["approve", "r3"],
 ["set_policy", "front_loaded", "2026-07-16"], ["status", "r3"]]

returns [true, [], true, 2400, true, 1920, true, 1440, ["r3"], "revoked"]: under accrual r3 fit exactly at -960; the front-loaded grant on 2026-07-16 is 4800 * 5 // 12 = 2000, 200 less than the 11 periods of accrual it replaces, so r3 now breaches the limit.

Notes

• You may use the AI assistant freely; you are expected to verify what it produces.
• Later parts must not break earlier ones; hidden tests re-check earlier behavior.
• dates.py helpers are shared: be careful which behavior you change.