Gross-Receipts & Excise Tax

Architecture

Key specifications

What it does for you

A developer that manages projects across several taxing jurisdictions owes a gross-receipts or excise tax in each one -- a state Business & Occupation tax, a city excise, a territorial general-excise tax -- and each carries its own classification rate, its own filing cadence (monthly, quarterly, annual), its own deductions, thresholds and due dates, and each rate can change mid-year. The filer prepares one worksheet per entity per jurisdiction per period and files it. The tax on that worksheet is a derived figure, and four failures hide inside it, none of which look wrong on the page. The base does not tie the ledger: a revenue line is omitted or a non-taxable back-out is overstated, and the tax is computed on a base nobody reconciled to the GL pull. The rate is the wrong rate: a classification rate changed mid-year and the worksheet applied last quarter's rate to this quarter's receipts, and the arithmetic is internally consistent and still wrong. A deduction or credit is misapplied: a standard deduction already exhausted is taken again, a below-threshold no-tax rule is claimed above the threshold, or a small-business credit is read off the wrong bracket. And the calendar has a hole: an entity-jurisdiction-period that should have a filing has none, a return was filed after its due date, or filed before anyone approved it. None of these are judgment calls. They are equalities and comparisons -- a base against the GL, a rate against the window that covers the period, a re-derived tax against the number filed, a filing against the calendar -- which a deterministic control settles better than a spreadsheet inherited by whoever prepares the returns this year. This engine audits the tax return; where a cost lands on a project is a separate engine's job, and this one explicitly declines to check it.

The seeded demo runs every control over every reconciliation file⁷. The CLI generates twenty-nine fictional reconciliation files -- one clean baseline and one carrying each of the twenty-eight planted defects -- then runs all twenty-seven 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.

A rate that was right last quarter is wrong for this period⁸. A boundary test sets a classification rate window to change mid-year and files a worksheet for a period inside the new window at the prior window's rate. eff_rate_matches_period looks up the rate whose window covers the period's start date and fails because the worksheet applied a rate no longer in force, even though the tax computed on it re-derives internally -- a rate right one quarter and stale the next is invisible in a column of consistent arithmetic.

The determination is recomputed, not read back⁹. A test flips a summarised tax-due figure to contradict its worksheet's receipts. rpt_summary_recomputes rebuilds the tax from the worksheet's gross, back-out and standard deduction through the shared kernel -- base, rate, credit and net -- and fails because the stated determination no longer matches the receipts, proving the rollup is recomputed rather than trusted.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: reconciliation 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 tax, and a cent off the re-derived figure is reported as a break.
• An amount 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 tax computation: the controls and the generator share the kernel in grt_engine.grt, so a re-derived tax cannot disagree with the data that produced it.
• 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, contacts a jurisdiction, remits a payment, chases a renewal, or writes to a source artifact. It reads the reconciliation file and stops.¹⁴
• It reads the seven artifacts the reconciliation process emits. It does not connect to a general-ledger system, a jurisdiction's e-file portal, a licensing authority or the underlying returns.¹⁵
• It is about whether the tax on the worksheet is the tax the receipts produce, not where a cost lands: cost allocation across projects is a separate engine's job, and this engine explicitly declines to check it.¹⁶
• It proves a worksheet's tax re-derives from the rate table it was given, not that the rate table states the correct statutory rates or that a receipt was classified into the right activity. That judgment is a reviewer's.¹⁷
• It takes the receipts at face value: it confirms the base ties the GL pull provided, not that the pull is complete against the books or that the return was accepted by the jurisdiction. All shipped data is fictional and every period is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.