Envelope Budgeting: Month Close, Splits and Overspending

Envelope Budgeting: Month Close, Splits and Overspending

You've joined the team behind a personal-budgeting app that uses envelope (zero-based) budgeting. Income lands in one pool called *ready to assign*; the user assigns it to envelopes such as groceries, rent and fun; purchases draw an envelope down; and at month end whatever is left rolls into the next month. Support has two open tickets about wrong month-end numbers, and product has two changes queued behind them. All amounts are integer cents.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh budget and returns one result per operation. Every operation is [name, month, ...args]. month is the "as of" month, a zero-padded "YYYY-MM" string. Errors are returned as strings, never raised.

The month clock. The first well-formed operation sets the open month. After that, every operation's month must be >= the open month, otherwise it returns "error: month in the past" and does nothing. If month is later than the open month, every month in between is closed first (one at a time, including months in which nothing happened), then the operation runs in month. This happens even if the operation itself then fails.

Figures per envelope per month. assigned is money moved in this month, activity is purchases minus refunds (so spending is negative), and available is last month's available + assigned + activity. When a month closes its figures, and the ready-to-assign it ended with, are recorded and never change again. A new month starts with assigned = 0 and activity = 0 for every envelope.

• assign moves money from ready-to-assign to the envelope; it needs amount <= ready, so the whole of ready-to-assign can be assigned.
• spend may take an envelope below zero ("overspent"); that is allowed.
• A report is {"month", "ready", "envelopes"} where envelopes is a list sorted by name of {"name", "assigned", "activity", "available"}. For the open month it is live; for a closed month it is the recorded figures (only envelopes that existed then). A month that is not the open month and was never closed (before the first operation, or in the future) returns month not found.
• Envelope names and transaction ids are non-empty, case-sensitive strings; otherwise invalid arguments. A valid amount is an integer > 0 (true/false are not amounts).
• Unknown operation names return "error: unknown operation". A wrong number of arguments, or a month (or report target) that is not a well-formed "YYYY-MM", returns "error: invalid arguments" and does not start or move the clock.
• Each error is returned as "error: <code>".
• Positive balances roll over unchanged. What happens to an *overspent* (negative) balance at month end is deliberately left open until Part 3; the starter carries it unchanged and nothing in Part 1 depends on it.

Worked example

[["create_envelope", "2025-01", "groceries"],
 ["income", "2025-01", 100000],
 ["assign", "2025-01", "groceries", 40000],
 ["spend", "2025-01", "t1", "groceries", 12500],
 ["report", "2025-01", "2025-01"]]

returns

[true, 100000, 40000, 27500,
 {"month": "2025-01", "ready": 60000,
  "envelopes": [{"name": "groceries", "assigned": 40000, "activity": -12500, "available": 27500}]}]

Part 1 — Fix the month-end numbers (BUD-311, BUD-327)

Goal: make rollover, month history and assigning follow the rules above.

Reports from users:

1. "After I got through November the app showed a nonsense month and my December and January numbers were gone." Rolling over a year-end seems fine in the unit tests, so look at every month.
2. "I opened last month's report after spending this month and the figures had changed."
3. "I have $10.00lefttoassignandtheappwo{n}^{\prime }tletmeputall$10.00 into one envelope."

Rules

1. A closed month's report is exactly what the month looked like when it closed, forever.
2. Closing months must work for every calendar month, including across year ends and multi-month jumps.
3. Assigning exactly the remaining ready-to-assign succeeds; one cent more fails with insufficient ready to assign and changes nothing.

tests/test_budget.py::test_all_of_ready_can_be_assigned currently fails; it is not the only defect.

Example (rolling over a year end)

[["create_envelope", "2025-11", "fun"],
 ["income", "2025-11", 30000],
 ["assign", "2025-11", "fun", 30000],
 ["spend", "2025-11", "t1", "fun", 4000],
 ["spend", "2025-12", "t2", "fun", 1000],
 ["report", "2026-01", "2025-11"],
 ["report", "2026-01", "2026-01"]]

returns true, 30000, 30000, 26000, 25000, then November's frozen report {"month": "2025-11", "ready": 0, "envelopes": [{"name": "fun", "assigned": 30000, "activity": -4000, "available": 26000}]} and January's live one {"month": "2026-01", "ready": 0, "envelopes": [{"name": "fun", "assigned": 0, "activity": 0, "available": 25000}]}.

Part 2 — Split purchases and refunds (BUD-340)

Goal: one receipt can draw from several envelopes, and a refund puts money back where it came from, even months later.

Rules

1. parts is a list of at least two [envelope, amount] pairs with distinct envelope names; anything else (wrong shape, one part, a repeated envelope) is invalid split. Then amounts are checked in list order (invalid amount), then envelopes in list order (envelope not found), then the id. A rejected split changes nothing and does not consume txn_id.
2. A successful split lowers activity and available of each part's envelope by its amount, exactly like one spend per part.
3. refund refers to a purchase (a spend or a split) by txn_id and to one envelope name that took part in it. Refunded amounts accumulate per (purchase, envelope): the total refunded for an envelope may reach, but not exceed, what that envelope paid in the purchase.
4. A refund raises activity and available of that envelope in the open month (the month of the refund operation). Closed months, including the purchase's month, are not touched, and ready-to-assign is not touched.
5. Purchases and refunds share one id namespace: refund_id must not equal any earlier txn_id or refund_id, and a new spend or split id must not equal an earlier refund id (all duplicate transaction). A refund id is not a purchase, so refunding it is transaction not found.
6. Everything from Part 1 keeps working.

Example

[["create_envelope", "2025-01", "groceries"],
 ["create_envelope", "2025-01", "household"],
 ["income", "2025-01", 100000],
 ["assign", "2025-01", "groceries", 50000],
 ["assign", "2025-01", "household", 20000],
 ["split", "2025-01", "t1", [["groceries", 8000], ["household", 3000]]],
 ["refund", "2025-02", "r1", "t1", "household", 3000],
 ["report", "2025-02", "2025-01"],
 ["report", "2025-02", "2025-02"]]

returns true, true, 100000, 50000, 20000, 11000, 20000, then January (unchanged by the refund): ready 30000, groceries 50000 / -8000 / 42000, household 20000 / -3000 / 17000 (assigned / activity / available), and February: ready 30000, groceries 0 / 0 / 42000, household 0 / 3000 / 20000.

Part 3 — Overspending is settled at month end; move money (BUD-352)

Goal: finance has decided that debt must not hide inside envelopes. When a month closes, any overspent envelope is reset to zero and the shortfall is paid out of ready-to-assign. This replaces the "carried unchanged" starter behaviour for negative balances; also add move.

Rules

1. When a month closes, first record it (its report still shows the negative available and the ready-to-assign it had before this step). Then, for every envelope whose available is below zero, add that (negative) amount to ready-to-assign and set the envelope's available to 0.
2. This happens once, at the close that ends the overspent month. If several months are closed in one jump, later months see envelopes already at zero.
3. Ready-to-assign can therefore become negative; this is the only way it can. While it is negative, assign fails with insufficient ready to assign (it needs amount <= ready), and income simply adds to it.
4. move takes amount from source to target in the open month: assigned and available of the source decrease and of the target increase by amount (so assigned can be negative), and ready-to-assign is not touched. The source needs available >= amount right now (insufficient envelope funds otherwise, so an overspent source can move nothing). Envelopes are checked source first, then target. A failed move changes nothing.
5. Refunds still land in the open month (Part 2), so a refund before month end shrinks the shortfall and a refund after it lands in an envelope that was reset to zero.
6. Everything from Parts 1 and 2 keeps working.

Example

[["create_envelope", "2025-01", "fun"],
 ["income", "2025-01", 10000],
 ["assign", "2025-01", "fun", 10000],
 ["spend", "2025-01", "t1", "fun", 12500],
 ["report", "2025-02", "2025-01"],
 ["report", "2025-02", "2025-02"],
 ["assign", "2025-02", "fun", 1],
 ["income", "2025-02", 4000],
 ["assign", "2025-02", "fun", 1500]]

returns true, 10000, 10000, -2500, then January: ready 0, fun 10000 / -12500 / -2500; then February: ready -2500, fun 0 / 0 / 0; then "error: insufficient ready to assign", 1500, 1500.