The taxable basis · the number one real-money hazard
There is no such thing as taxable wages. There are several, and they differ.
This is the mistake that costs the most and shows the least. Different pre-tax deductions reduce different tax bases, and treating them as one number produces the wrong Social Security and Medicare withholding, and the wrong Boxes 3 and 5 on every W-2, and the wrong 941 for every quarter. One conceptual error, three wrong documents, discovered at year end when there is nothing cheap left to do about it.
The rules are not obscure. They are just easy to collapse into one field, and a single field is what most systems give you.
Four classes, four different answers
What actually reduces what.
A Section 125 cafeteria deduction, an HSA or an FSA reduces federal and state income tax and FICA and federal unemployment — the full pre-tax treatment. It is the only one of the four that reduces everything.
A 403(b) or 457(b) elective deferral reduces federal and state income tax but not FICA. That single exception is why Boxes 3 and 5 of the W-2 still include the deferral while Box 1 does not, and it is the most common place a one-number system goes wrong.
A 414(h)(2) employer pickup reduces federal income tax but not FICA, and the state treatment varies. The module encodes none of that as a default: the rules are documented in the source for a signer to read, and the signer supplies them. Set a pickup in the explorer below and watch the state row refuse rather than guess.
A post-tax deduction or a garnishment reduces nothing at all. It comes out of the net after every basis has already been computed, which is why it never appears as a row in the output below even though it is a real deduction from a real paycheck.
Change the mix
The same arithmetic, with the inputs in your hands.
One ordinary pay period of four thousand dollars gross. Choose a deduction mix and each authority’s basis is recomputed — in exact integer cents, by subtraction, with the identity the shipped module enforces: the basis equals gross minus what reduced it, and never falls below zero. Then set the exemption mask to unsigned and watch every basis refuse.
Every figure above is exact integer cents and every one of them is produced by subtraction only. There is no tax rate anywhere on this page, because this product ships none. Note the post-tax line has no row of its own: a post-tax deduction or a garnishment reduces nothing, so it changes no basis — which is exactly why treating deductions as one undifferentiated pool gets the year wrong.
What this is, said precisely, because the alternative is a demo that overclaims. This is not the shipped engine and it is not a call to it. It is the same subtraction restated inside the page renderer: it talks to no database, holds no clock and opens no socket, and it carries no tax rate, no bracket and no wage base. It is here because the argument above is much easier to believe when the numbers move. What it demonstrates faithfully is the SHAPE of the rule — that two authorities looking at one paycheck legitimately see two different figures, and that an unsigned mask produces no figure at all.
The check that runs on every basis
One identity, per authority, and it never floats.
Every basis the engine computes carries the same reconcile identity, and it is checked rather than assumed: the basis equals gross minus what reduced it, and it never falls below zero. Two properties fall out of that, and both matter more than they look.
The first is that the amount reduced is carried alongside the result rather than implied by it. A basis of three thousand five hundred dollars is not an answer on its own — the useful thing is that it is four thousand less five hundred, and that the five hundred is itemised by class. When a figure is queried nine months later, the difference between “the basis was 3,500” and “the basis was 3,500 because these two deductions reduced it and this one did not” is the difference between a conversation and an investigation.
The second is that the floor at zero is a floor, not a clamp that hides something. A basis cannot go negative, but the case that would have driven it negative is not silently absorbed — the same posture the net-pay engine takes, where a paycheck floors at zero and the over-deduction that caused it is raised as its own separate signal, because hitting the floor is precisely the case that needs a human to look at it.
And the mask itself is supplied and signed, never inferred. The module encodes none of the four rules above as a default. They are documented in the source for a signer to read, and the signer supplies them — which is why the unsigned setting in the explorer is not a failure mode bolted on afterwards, it is the ordinary state of the engine before somebody takes responsibility for the rules.
The refusal is the feature
An unsigned mask computes no basis. Not zero — none.
Set the mask to unsigned in the explorer above and every row holds with the reason attached. That is exactly what the shipped module does, and the distinction between none and zero is the whole argument. Zero is a number. A number looks like an answer, it flows into the next calculation, and it arrives on a stub looking plausible. A held reason cannot be mistaken for a result by anything downstream.
The same posture runs through the withholding side, which is a different module with the same discipline: if no table matches it is held for no table; if two effective windows overlap it is held as ambiguous rather than resolved by picking one, because an overlap is a data error and choosing arbitrarily is how a whole quarter gets computed against the wrong brackets; if a table is present but unsigned it is held pending sign-off, even though the rates might well be right, because nobody has said so on the record; and if a table is malformed it is held as invalid rather than half-applied. In every held case the downstream withholding is zero and the reason travels with it.
The honest cost of designing it this way, stated plainly rather than left for you to find: you need somebody who can sign for the tables. If you do not have that person, a full-service provider that maintains the tables for you is a better fit than we are, and we would tell you so on a call rather than sell you a registry you would leave empty.
Where the basis goes next
Four consumers, and each treats it differently.
A basis is an input to a calculation, not a calculation, and no money is attached to any figure on this page. But the reason to compute four of them independently is that four different things read them, and each reads a different one.
Federal income-tax withholding takes the federal basis into the Publication 15-T Worksheet 1A percentage method — annualize, apply the Step 4a and 4b adjustments and the filing-status standard adjustment, look up the tentative annual tax in the SUPPLIED bracket table, de-annualize, subtract the Step 3 credit, add the 4c extra amount. If that table is unsigned, the withholding is zero and the reason travels with it.
Social Security takes the FICA basis and caps it against year-to-date wages, so the same basis produces a different result in December than it did in March for a highly-paid employee. Medicare takes the same basis uncapped. And Additional Medicare takes it employee-only, with no employer match — because that is the law, and a symmetric implementation would have quietly over-charged the employer on every affected paycheck.
The W-2 reads them as three separate boxes, and this is where a one-number system finally shows itself. Box 1 excludes the pre-tax deferrals that Boxes 3 and 5 include, so Box 1 is at most Box 5 by construction — and Box 3 is additionally capped at the annual Social Security wage base while Box 5 is not. Those are three different figures derived from three different bases on the same wages.
The 941 reads the employer-side figures quarterly, and the year-end three-way reconcile then requires that the sum of the W-2s equals the W-3 equals the sum of the four 941s. If the bases were collapsed into one number at the start of the year, that identity fails at the end of it — and the reconcile blocks rather than absorbing the difference.
Why it is worth a page
The error only surfaces at year end, and by then it is in three documents.
Look at the default mix in the explorer: on one ordinary paycheck the federal basis and the FICA basis differ by three hundred dollars, purely because a 403(b) deferral reduces income tax and not FICA. A system that carries one “taxable wages” figure through the year gets Boxes 3 and 5 of the W-2 wrong by that difference, in every period, for every employee who defers.
And it stays invisible the whole time, because every individual number looks fine. The stub balances. The register foots. The quarterly totals agree with themselves. Nothing surfaces until the three-way reconcile at year end — the sum of the W-2s against the W-3 against the four 941s — and at that point the correction is not one edit, it is a year of periods.
That reconcile is one of the wired surfaces, and when the legs disagree it blocks and shows which leg is out rather than absorbing the difference into an adjustment and reporting success. It is described in full on the engines page. It proves a filing set agrees; it emits no form and transmits nothing.
Where to go next
The rest of this site.
Every page here is its own argument rather than a restatement of the home page. If you would rather ask a person, the address below reaches one.