Budget Encumbrance

The defect

You sign a $40k contract on the 3rd. Nothing is invoiced until the 30th. For twenty-seven days every budget report says you have $40k more room than you do — and every approval made in that window is made against a number that is wrong in the direction that approves things.

Each of those approvals is individually reasonable. A month of them breaches the budget.

The accounting name for the missing piece is an encumbrance: money that is spoken for but not yet spent. ERP and public-sector systems have modelled it for decades. Almost every in-house budget check does not, because "how much have we spent" reads like a settled question with one obvious answer.

Three quantities, never conflated

| quantity | meaning | |---|---| | invoiced | money that has left, or will on a known invoice | | committed | signed, ordered or approved — not yet invoiced | | pending | requested, awaiting approval. Not a claim on the budget yet | | consumed | invoiced + committed — the number decisions are made against | | worstCase | consumed + pending — what happens if everything in flight is approved |

invoiced is kept separate rather than replaced, so finance can still reconcile to the ledger.

  canApprove({ amountCents: 30_000_00, effectiveAt }, items, period, now);
  // { approved: false, reason: "would_exceed", shortfallCents: 10_000_00,
  //   detail: "…Remaining counts 8000000 in committed-but-uninvoiced spend,
  //            which an invoiced-only check misses" }

Pace, because position is comfortable exactly when it should not be

Half the month gone and 60% of budget spent looks fine by position and is 120% by pace. onPaceToBreach reports that while overBudget is still false.

It refuses to project before 10% of the period has elapsed. Two days in, one invoice extrapolates to a wild number, and a false "you will be 400% over" is how people learn to ignore the projection entirely.

Periods are half-open

[startsAt, endsAt) — the instant a period ends belongs to the next one. A closed range lets two consecutive periods both count the same item, which shows up as a budget that is mysteriously over by exactly one large invoice.

What it does not do

| not included | why | |---|---| | Storing budgets or spend | pure functions over records you already have | | Currency conversion | mixing currencies silently is worse than refusing; convert upstream | | Live spend limiting | spend-ceiling-limiter; this is period accounting | | Cloud cost attribution | cloud-cost-allocator |

All amounts are integer cents. There are no floats anywhere in this package, deliberately.