Review payroll batch cutoffs and retries

Review exercise · TypeScript

Review brief

Nightmare60 min

A payroll worker pays hourly employees across time zones through an external provider. A run may be interrupted or partially rejected, but approved wages must be paid once under a stable identity without skipping employees or absorbing later timesheet edits.

Behavioral contract

A pay period is `[start local date, end local date)` in the payroll account's IANA time zone; classify instants by their local date across offset changes.
Run creation atomically snapshots employee order, approved timesheet versions, rates, and adjustments; execution reads only that immutable snapshot.
Unapproved timesheets never contribute to a payment, and each approved line is rounded to cents before lines are summed.
The provider idempotency key is the stable tuple `(payRunId, employeeId)` and is reused for every attempt.
Mark an employee paid only after provider acknowledgement; ambiguous or transient failures remain retryable with the same key.
A terminal provider rejection is recorded for that employee, transient failures remain pending, and either outcome allows later employees to run.
A checkpoint never advances past an employee whose durable state is still unknown and restarting does not skip unpaid work.

Review instructions

1Trace one run through daylight-saving boundaries, mutable source data, provider acknowledgement, partial failure, and restart.
2Prioritize no more than eight findings and combine checkpoint symptoms that share one recovery defect.

Learning objectives

• Freeze authoritative payroll inputs at run creation
• Place durable state around acknowledged external effects
• Preserve fair retry progress across employee failures

src/payroll-types.tsTypeScript

@@ -0,0 +1,48 @@

1+export interface PayPeriod {

2+ id: string;

3+ startDate: string;

4+ endDateExclusive: string;

5+ timeZone: string;

6+}

8+export interface TimesheetLine {

9+ id: string;

10+ employeeId: string;

11+ workedAt: string;

12+ minutes: number;

13+ hourlyRateCents: number;

14+ adjustmentCents: number;

15+ approved: boolean;

16+ version: number;

17+}

18+

19+export interface ProviderDelivery {

20+ acknowledgement: Promise<void>;

21+}

22+

23+export interface PayrollDependencies {

24+ employees: {

25+ listForRun(payRunId: string): Promise<string[]>;

26+ };

27+ timesheets: {

28+ listForEmployee(employeeId: string): Promise<TimesheetLine[]>;

29+ };

30+ provider: {

31+ startDisbursement(input: {

32+ employeeId: string;

33+ amountCents: number;

34+ idempotencyKey: string;

35+ }): Promise<ProviderDelivery>;

36+ };

37+ payRuns: {

38+ markPaid(payRunId: string, employeeId: string, amountCents: number): Promise<void>;

39+ recordFailure(payRunId: string, employeeId: string, message: string): Promise<void>;

40+ };

41+ checkpoint: {

42+ load(payRunId: string): Promise<number>;

43+ save(payRunId: string, nextEmployeeIndex: number): Promise<void>;

44+ };

45+ ids: {

46+ next(): string;

47+ };

48+}

Reference solution

The findings below are ordered by priority.

Findings

1. Pay-period boundaries are UTC instants and include the exclusive end

Location: src/payroll-cutoff.ts:3-8

The account time zone is ignored, midnight dates are forced to UTC, and the comparison uses <= for the exclusive end. Work near midnight or a daylight-saving transition can enter the wrong period, and an instant exactly at the next period boundary is paid twice.

Convert each work instant to its local calendar date in period.timeZone and compare dates using an inclusive start and exclusive end.

2. Execution reads mutable timesheets instead of a run snapshot

Location: src/payroll-job.ts:15-23

Only employee IDs are listed at run time; each attempt reloads current lines, rates, adjustments, approvals, and versions. Edits between employees or after a retry can change a supposedly fixed run and make the same pay-run identity produce a different amount.

Create and durably reference an immutable snapshot before execution, then read every employee and line exclusively from it.

3. Unapproved lines contribute to disbursements

Location: src/payroll-job.ts:22-24

The filter checks only the date. A submitted or rejected line inside the period is included in wages, bypassing the required approval boundary.

Snapshot only approved versions or explicitly filter on approval before computing each line amount.

4. Every retry receives a new provider identity

Location: src/payroll-job.ts:25-29

ids.next() changes on each attempt. If the provider accepted a payment but acknowledgement was lost, restarting can create a second disbursement that the provider cannot deduplicate.

Derive and persist the key from payRunId and employeeId, and reuse it for every ambiguous or explicit retry.

5. Employees are marked paid before provider acknowledgement

Location: src/payroll-job.ts:31-33

The durable paid transition precedes acknowledgement. A rejected delivery leaves the employee recorded as paid despite no confirmed provider effect, and a crash in this window makes recovery ambiguous in the wrong direction.

Keep the employee pending through acknowledgement and mark paid only afterward, using the stable key to tolerate ambiguous process failure.

6. Failure advances the checkpoint and aborts later employees

Location: src/payroll-job.ts:34-43

The catch records a generic failure, saves index + 1, and rethrows. A transiently failed employee is skipped on restart, while every later employee is delayed by that one error even though the contract requires per-employee progress.

Persist a per-employee terminal or retryable state, do not advance past unknown work, and continue processing later employees independently.

7. Provider failures receive no terminal or transient classification

Location: src/payroll-job.ts:34-39

All errors become the same message-only failure. The system cannot distinguish an invalid bank account that needs intervention from a timeout that must retain the stable retry path.

Classify provider outcomes explicitly and persist terminal versus retryable state before continuing the batch.

8. The test removes every hard payroll boundary

Location: src/payroll-job.test.ts:5-50

One approved UTC line, an immediate acknowledgement, one employee, and no restart cannot expose local cutoffs, source mutation, approval bypass, changing identities, pre-ack state, checkpoint skipping, or failure fairness.

Add transition-zone boundary tables and controlled provider promises, then restart a partially completed multi-employee run against changed source data.

Reasonable non-findings

Rounding each approved line before summing matches the explicit payroll rule.
Sequential employee processing is acceptable as long as one outcome does not block later durable progress.
The provider may deliver at least once after ambiguity; a stable key is the required deduplication mechanism.