Non-Resident Withholding & 1042-S

Architecture

Key specifications

What it does for you

A US withholding agent that pays cross-border interest, dividends, royalties or rent to foreign recipients has to withhold Chapter 3 tax at the right rate, support every reduced rate with a valid Form W-8, deposit what it withheld, and reconcile the annual Form 1042 to the 1042-S slips it transmits. A withholding determination is a snapshot of a payee's status on the day a payment went out, and it goes stale -- or was wrong to begin with -- in ways nobody watches. Four failures hide inside a folder of withholding workpapers, and none of them look wrong. The rate is reduced without support: a treaty rate is applied while the W-8 behind it is missing or expired past its three-year term. The classification is off: a US payee is withheld on, an accrued-but-unpaid coupon is treated as paid, a non-participating FFI is given treaty relief the FATCA override bars it from, or a contingent coupon is coded as exempt portfolio interest. The deposit drifts from the liability, or the return is filed after its due date. And the return does not tie to the slips: the Form 1042 total gross or total tax is stated on a number nobody rebuilt from the 1042-S slips underneath it, or a reportable payee has no slip at all. None of these are judgment calls. They are equalities and comparisons -- an applied rate against the determination the kernel rebuilds with exact ==, a tax against rate times gross, a deposit and a 1042 total against the slips, a W-8 term against the review date with <= -- which a deterministic control settles better than a spreadsheet inherited by whoever tracks the withholding this year.

The seeded demo runs every control over every withholding file⁷. The CLI generates thirty fictional withholding files -- one clean baseline and one carrying each of the twenty-nine planted defects -- then runs all twenty-eight controls over each. The clean file returns PASS with no flags; every defect file returns REVIEW or FAIL and names the control it tripped along with the reason that control exists.

The order of precedence does not commute⁸. A payee is seeded as both a treaty claimant and a non-participating FFI. The FATCA override must win: the payment is withheld at the statutory 30%, not the treaty rate. One defect file hands that payee a treaty-reduced 15% and trips exm_fatca_override, while another removes the W-8 behind a genuine treaty reduction and trips exm_w8_present_for_treaty -- proving the two exemption branches catch different failures at the edge boundary the kernel encodes.

The rate is recomputed, not read back⁹. A defect file under-rates a treaty payee, leaving a stated rate that no longer matches the determination. wh_rate_recomputes rebuilds the rate from the payee's status through the shared kernel -- FATCA, then portfolio, then treaty behind a valid W-8, then statutory -- and fails, proving the rate is recomputed from the evidence rather than trusted as stated.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: withholding files are parsed and never written back, so the engine cannot introduce the break it reports.
• Integer cents and basis points throughout, compared with exact ==; there is no tolerance band on a rate, a tax or a total, and a cent off the re-derivation is reported as a break.
• A figure that should be integer cents or basis points but is not produces an AMOUNT_INVALID finding contained to the one row it was read on, rather than being coerced into the number the engine is meant to audit.
• One withholding kernel: the controls and the generator share the determination in withholding_engine.withholding, so a rate cannot disagree with the data that produced it.
• The order of precedence is encoded once: FATCA override, then portfolio-interest exemption on non-contingent interest, then a treaty rate behind a valid W-8, then the statutory default -- so a non-participating FFI that also holds a treaty claim is withheld at statutory.
• Every expiry and renewal test is measured to the as_of review date carried in the file, never the system clock, and the W-8 expiry gate is <= so a form lapsing on the review date is already unsupported.
• Deterministic and byte-stable: same inputs produce the same findings in the same order, with no timestamps or absolute paths in any output.
• Absent evidence is never a passing control; a missing artifact fails completeness rather than letting the controls that read it pass unread.

Operating limits

• The engine never files a return, remits a deposit, issues or requests a W-8, contacts a payee, or writes to a source artifact. It reads the withholding file and stops.¹⁴
• It reads the eight artifacts the withholding record emits. It does not connect to a payment system, a general ledger, the IRS, or the underlying Forms W-8.¹⁵
• It proves a rate clears the mechanical determination -- FATCA override, portfolio exemption, treaty behind a valid unexpired W-8, statutory default -- not that a payee's stated Chapter 3/4 status is genuinely correct or that a W-8 is authentic. That judgment is a reviewer's.¹⁶
• It re-derives each rate at the treaty and statutory rates the file carries; it does not decide whether the treaty rate table or the statutory 30% default is the correct one for the year and taxpayer.¹⁷
• It takes the payment and deposit records at face value: it confirms the registers foot, tie and reconcile, not that a payment or deposit actually occurred. All shipped data is fictional and the reporting period is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.