The third enum variant that stopped my tax calculator from lying

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 { if ( taxable <= 0 ) return 0 ; let tax = 0 ; let prevCap = 0 ; for ( const { upTo , rate } of brackets ) { const band = Math . min ( taxable , upTo ) - prevCap ; if ( band <= 0 ) break ; tax += band * rate ; prevCap = upTo ; } return tax ; } State tax is the same loop with different numbers. The trouble is that "different numbers" hides a lot. Nine states don't tax wage income at all. A couple (New Hampshire, Tennessee) don't tax wages but have historically taxed other things, so you can't just lump them with Texas without a footnote. Some states publish 2026 figures early; others inflation-index their brackets and won't publish the new thresholds until mid-year. And when I started, I had verified numbers for about ten states and unverified-but-plausible numbers for the rest. That last category is the dangerous one. The easy move is to ship the plausible numbers and fix them later. The problem is that a wrong tax estimate doesn't look wrong. It looks like a number. Someone in Oregon types in their salary, sees a confident dollar figure, and has no way to know it was a placeholder I never got around to checking. Two variants felt like enough. It wasn't. My first model was the obvious one: type StateTax = | { kind : " none " ; code : string ; name : string ; note : string } | { kind : " taxed " ; code : string ; name : string ; brackets : ...; standardDeduction : ... }; This is clean and it compiles and it's a lie. It forces every state to be either "no tax" or "here are the exact brackets," which means the moment I add a state to the union, I'm implicitly claiming I've verified it. There's no way for the type to say this state taxes income, but I haven't confirmed the numbers yet. So either I block the entire feature until all 51 are done, or I quietly promote guesses to facts. The fix was a third variant whose only job is to represent honesty about the gap: /** Taxing state not yet data-verified — selectable, but calc returns 0 with a UI caveat. */ type PendingState = { kind : " pending " ; code : string ; name : string }; type StateTax = NoneState | PendingState | TaxedState ; pending means: yes, this state taxes wages, no, I will not pretend to know how much. The calculator returns 0 for it, and the UI renders a visible caveat instead of a clean dollar amount. It's selectable so the dropdown still lists every state, but it can't masquerade as a verified result. The calculation function gets to stay honest because the type makes the gap unrepresentable as a real value: function calcStateTax ( gross : number , status : FilingStatus , code : string | null ): number { if ( gross <= 0 || ! code ) return 0 ; const st = STATES_2026 [ code ]; if ( ! st || st . kind !== " taxed " ) return 0 ; // none AND pending both fall through here const taxable = Math . max ( 0 , gross - st . standardDeduction [ status ]); return taxFromBrackets ( taxable , st . brackets [ status ]); } The single line st.kind !== "taxed" is the whole point. There is exactly one branch that produces a state-tax number, and it's only reachable when the data has been verified. A pending state and a no-tax state both return 0, but they mean completely different things, and the UI is allowed to treat them differently because the variant carries that distinction. "Verified" needed a definition I could check later Once pending existed, I had to define what it took for a state to leave pending. Hand-wavy "I looked it up" doesn't survive contact with a tax year that changes under you. So every taxed state carries its own provenance: type TaxedState = { kind : " taxed " ; brackets : Record < Filing , Bracket [] > ; standardDeduction : Record < Filing , number > ; provenance : Provenance ; // where each number came from + a dated note }; The rule I held myself to: a state's numbers only graduate to taxed when they're cross-checked against two independent sources — the state's own Department of Revenue, and an outside table (I used the Tax Foundation's bracket data). Both agree, or it stays pending . The provenance.note records the date and any caveat, like "state inflation-indexes brackets and hasn't published 2026 thresholds, so rates are exact and thresholds are the latest complete schedule." That sounds like bureaucracy for a side project. But it's the difference between a number I can defend and a number I'm hopin