I built a small thing that estimates what a US pay raise actually lands in your pocket after federal tax, FICA, state tax, and inflation. The arithmetic is the boring part. The part that took three rewrites was deciding how to represent fifty states plus DC when you don't actually have clean data for all of them on day one.
This is a writeup of that one decision, because it generalizes well beyond taxes.
The problem isn't the math, it's the gaps
Federal brackets are easy. There's one set of numbers, the IRS publishes them, and progressive tax is a five-line loop:
function taxFromBrackets(taxable: number, brackets: Bracket[]): number {
