Expense Policy Engine: Currency, Trip Caps and Manager Exceptions

Expense Policy Engine: Currency, Trip Caps and Manager Exceptions

You've joined the Finance Platform team that owns the expense policy engine. Employees submit expenses (in any supported currency), the engine converts them to USD and checks them against company policy, and managers can occasionally approve an exception. Finance has reported a pair of wrong-by-a-few-cents bugs, and two policy features are queued behind them. All money is an integer: amounts are in the *minor unit* of their currency (cents, pence, whole yen) and totals are in USD cents.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh engine and returns one result per operation. Every operation is [name, *args]. Errors are returned as strings, never raised.

• Each error is returned as "error: <code>", e.g. "error: unknown category". An unknown operation name returns "error: unknown operation"; a wrong number of arguments returns "error: invalid arguments".
• invalid arguments means a wrong type or shape: ids, category and currency must be non-empty strings, date must look like YYYY-MM-DD (it is not checked against the calendar), has_receipt must be a boolean, trip_id must be null or a non-empty string. invalid amount means amount is not an integer > 0 (booleans are not integers here).
• Categories: meals, lodging, transport, supplies, other. Currencies: USD, EUR, GBP, CAD, JPY. A manager must be added before their reports. Ids are case-sensitive.
• A decision object is {"status": "approved" | "rejected", "usd_cents": int, "reasons": [str]}. reasons is empty for approved expenses. A rejected expense is still stored (it just does not count toward any total).
• submit_expense converts to USD cents, then runs every policy rule and lists all the reasons that apply, in the order rules run.

Conversion. usd_cents = round_half_up(amount * rate / 10000) using integer arithmetic only, where rate is:

So 100 EUR cents is 108.5 USD cents, which becomes 109.

Policy rules (existing).

An expense exactly at a limit or at the receipt threshold is fine.

Worked example

[["add_employee", "ada", "Ada Okafor", null],
 ["submit_expense", "e1", "ada", "meals", 4500, "USD", "2024-03-04", null, true],
 ["submit_expense", "e2", "ada", "supplies", 9000, "EUR", "2024-03-04", null, true],
 ["submit_expense", "e3", "ada", "meals", 9000, "USD", "2024-03-04", null, true],
 ["employee_total", "ada"]]

returns

[true,
 {"status": "approved", "usd_cents": 4500, "reasons": []},
 {"status": "approved", "usd_cents": 9765, "reasons": []},
 {"status": "rejected", "usd_cents": 9000, "reasons": ["over category limit"]},
 14265]

Part 1 — Fix the wrong-by-a-few-cents reports (FIN-388, FIN-402)

Goal: make conversion and the limit check follow the rules above.

Reports from Finance:

1. "Our EUR expenses come out a cent lower than the bank statement, so month-end totals never reconcile. It's always the small ones that are off."
2. "A 75.00."

Rules

1. Conversion rounds half up on the exact value (never down, never via floating point).
2. An expense is over the category limit only when its converted USD cents are strictly greater than the limit.

tests/test_fx.py::test_fractions_of_a_cent_round_half_up and tests/test_policy.py::test_expense_exactly_at_the_limit_is_allowed currently fail.

Part 2 — Per-trip daily caps (FIN-412)

Goal: employees on a business trip get a daily spending cap, so one lavish day is flagged even when each expense is individually within policy.

New behavior for open_trip and for submit_expense with a trip_id:

Rules

1. open_trip creates a trip owned by employee_id. start and end are dates, both days are part of the trip, and daily_cap is USD cents. Errors in order: invalid arguments (a bad id or date, end before start, or a daily_cap that is not an integer > 0), employee not found, trip exists.
2. submit_expense with a trip_id fails with trip not found if the trip does not exist or belongs to a different employee. An expense with trip_id of null is not affected by any trip rule.
3. New reason outside trip dates: the expense date is before start or after end.
4. New reason over daily cap: for an expense dated inside the trip, add its usd_cents to what is already approved on that same trip and day; if the sum is greater than daily_cap, the expense is over the cap. Only the converted USD value counts, rejected expenses do not count, and each date is capped separately.
5. lodging is exempt: a lodging expense is never over daily cap and does not count toward the day's total.
6. Reasons are listed in this order: receipt required, over category limit, outside trip dates, over daily cap. An expense outside the trip dates is never checked against the daily cap.
7. trip_total(trip_id) returns the USD cents of all approved expenses on the trip (lodging included), or error: trip not found.

Example

[["add_employee", "ada", "Ada Okafor", null],
 ["open_trip", "t1", "ada", "2024-03-04", "2024-03-06", 10000],
 ["submit_expense", "e1", "ada", "meals", 6000, "USD", "2024-03-04", "t1", true],
 ["submit_expense", "e2", "ada", "transport", 5000, "USD", "2024-03-04", "t1", true],
 ["submit_expense", "e3", "ada", "lodging", 25000, "USD", "2024-03-04", "t1", true],
 ["submit_expense", "e4", "ada", "meals", 1000, "USD", "2024-03-07", "t1", true],
 ["trip_total", "t1"]]

returns

[true, true,
 {"status": "approved", "usd_cents": 6000, "reasons": []},
 {"status": "rejected", "usd_cents": 5000, "reasons": ["over daily cap"]},
 {"status": "approved", "usd_cents": 25000, "reasons": []},
 {"status": "rejected", "usd_cents": 1000, "reasons": ["outside trip dates"]},
 31000]

Part 3 — Manager exceptions with an audit trail (FIN-431)

Goal: a manager can approve an expense that policy rejected, as long as the problem is something a manager is allowed to waive. Every exception must be visible to auditors.

Rules

1. approve_exception(approver_id, expense_id) turns a rejected expense into an approved one. Errors in order: employee not found (unknown approver), expense not found, not authorized, not rejected (the expense is already approved), not overridable.
2. The approver must be above the submitter in the management chain: the direct manager or any manager higher up. Peers, reports, the submitter themselves and unrelated managers get not authorized.
3. Only over category limit and over daily cap can be waived. If any of the expense's reasons is receipt required or outside trip dates, the result is not overridable (the expense stays rejected).
4. On success the expense becomes approved with its original usd_cents, and the result is {"status": "approved", "usd_cents": int, "exception_by": approver_id}. It now counts everywhere an approved expense counts: employee_total, trip_total, and the daily-cap total for later expenses on the same trip day. A second exception on the same expense is not rejected.
5. audit(employee_id) returns the exceptions for that employee (null means everyone), in the order they were approved, as objects {"expense_id", "employee_id", "approver_id", "usd_cents", "overrode": [reasons]} where overrode is the expense's reasons in the order they were reported. A non-null unknown employee_id is error: employee not found. Failed attempts are not recorded.
6. Parts 1 and 2 behavior must not change for expenses that never receive an exception.

Example

[["add_employee", "boss", "Priya Raman", null],
 ["add_employee", "ada", "Ada Okafor", "boss"],
 ["submit_expense", "e1", "ada", "meals", 9000, "USD", "2024-03-04", null, true],
 ["approve_exception", "ada", "e1"],
 ["approve_exception", "boss", "e1"],
 ["approve_exception", "boss", "e1"],
 ["employee_total", "ada"],
 ["audit", null]]

returns

[true, true,
 {"status": "rejected", "usd_cents": 9000, "reasons": ["over category limit"]},
 "error: not authorized",
 {"status": "approved", "usd_cents": 9000, "exception_by": "boss"},
 "error: not rejected",
 9000,
 [{"expense_id": "e1", "employee_id": "ada", "approver_id": "boss", "usd_cents": 9000, "overrode": ["over category limit"]}]]

Notes

• directory.py and validation.py are known-good.
• You may use the AI assistant freely. Later parts must not break earlier ones; the hidden tests re-check earlier behavior as well.
• Every part is graded by hidden tests. Aim to finish Parts 1 and 2 cleanly and make real progress on Part 3.