Energy-Efficient Home Credit

Architecture

Key specifications

What it does for you

A homebuilder claims the IRC §45L energy-efficient home credit one dwelling unit at a time, and it has to prove, unit by unit, that each claimed unit clears two gates at once -- it closed (close-of-escrow) inside the fiscal-year window being filed, and it holds an energy certificate from a certified RESNET/HERS rater -- and then that every dollar stacked above that count was recomputed rather than typed. The gross credit is nothing more than the qualifying-unit count times the dated statutory per-unit amount, and the profit addback, the tax effect at the effective rate, the net benefit and the partner split are each arithmetic on that product. Three failures hide inside that, none of which look wrong on a footed worksheet. A unit is claimed that closed a year before the window opened, or after the statutory sunset that sits inside the window, or was never certified by a rater -- the computation still foots and the units underneath it do not qualify. The same dwelling is claimed in two successive period filings, each internally consistent, the overlap visible only across them. And the rollup -- the worksheet's gross credit, the report's certified-unit tie-out, the roll-forward identity, the net-benefit derivation or the partner allocation -- is stated on a number nobody recomputed from the unit register underneath it. None of these are judgment calls. They are equalities and comparisons -- a close date against a period window and a sunset with <=, a gross credit against units times the dated rate with exact ==, a stated total against its re-derivation -- which a deterministic control settles better than a spreadsheet inherited by whoever tracks the credit this year.

The seeded demo runs every control over every credit file⁷. The CLI generates twenty-eight fictional credit files -- one clean baseline and one carrying each of the twenty-seven planted defects -- then runs all twenty-six 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 two eligibility gates are genuinely independent⁸. The statutory sunset is seeded inside the fiscal-year window, so a unit can close in the period yet after the sunset. One defect file moves a unit's close date before the window opened and trips elig_close_in_period; another moves it past the sunset but inside the year and trips elig_within_sunset -- proving the two gates catch different failures, each checked with <= at its boundary.

The credit is recomputed, not read back⁹. A defect file adds a claimed unit to the register without re-deriving the worksheet, so the worksheet's qualifying-unit count no longer ties the register. roll_project_units rebuilds the count from the claimed register units and fails, proving the worksheet is recomputed from the dwellings beneath it rather than trusted as stated.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: credit files are parsed and never written back, so the engine cannot introduce the break it reports.
• Integer cents throughout, compared with exact ==; there is no tolerance band on a credit figure, and a cent off the re-derivation is reported as a break.
• A credit figure that should be integer cents 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 credit kernel: the controls and the generator share the kernel in energy_engine.credit, so a determination cannot disagree with the data that produced it.
• The two eligibility gates are independent: the sunset sits inside the fiscal-year window and each gate is checked with <= at its boundary, so a unit closing exactly on the sunset date is still eligible.
• 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, claims a credit, issues or requests a certificate, contacts a rater, or writes to a source artifact. It reads the credit file and stops.¹⁴
• It reads the six artifacts the credit record emits. It does not connect to a rating provider, a closing system, a general ledger or the underlying certificates.¹⁵
• It proves a unit clears the mechanical gates -- closed in period, within the sunset, certified with a named rater -- not that the unit genuinely meets the §45L energy-saving requirement or that its certificate is authentic. That judgment is a rater's and a reviewer's.¹⁶
• It re-derives the credit at the dated statutory per-unit amount and effective rate the file carries; it does not decide whether that rate or that effective tax rate is the correct one for the year and taxpayer.¹⁷
• It takes the closing and certification records at face value: it confirms the register and worksheet foot and reconcile, not that a closing actually occurred. All shipped data is fictional and the fiscal year is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.