Franchise Tax Combined Apportionment

Architecture

Key specifications

What it does for you

A group of affiliated development companies files one combined franchise (margin) tax return each fiscal year in the fictional State of Marran. The return is not one entity's; it is the whole group's, apportioned to Marran by a single receipts factor, and preparing it means three things happen together. The combined group is redrawn -- last year's members, plus the affiliates that joined, minus the ones that left -- and every affiliate not included this year has to be enumerated with a reason, because an affiliate that quietly falls off the roster is revenue that leaves the combined base with nobody noticing. The margin is apportioned -- consolidated group revenue from the tax trial balance, reduced by the group's elected deduction, scaled by in-state receipts over everywhere receipts -- so a factor struck against a denominator that does not sum its rows is a tax computed on numbers nobody reconciled. And the tax itself is derived: margin times apportionment times rate, in that order, each step a place a figure can be carried forward instead of recomputed. None of the failures look wrong on the return. A member with no registration, a revenue line attributed outside the group, a line id used twice, a base that does not tie the trial balance, a margin that does not re-derive from the deduction, a summary that does not recompute from the workpapers -- each foots on its own face. They are also not judgment calls. They are set equalities and integer comparisons -- a roster against prior plus additions less removals, a total against the sum of its rows, a factor against in-state over everywhere floored to a basis point, a tax against the apportioned margin at the rate with exact == -- which a deterministic control settles better than a workbook inherited by whoever prepares the return this year.

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

An affiliate leaves the group and the roster still rebuilds⁸. In the baseline, AFF-04 is removed from the combined group and AFF-05 joins, so the stated roster must equal the prior four members plus the addition less the removal. One defect file adds a stray prior-year member without touching the stated list, and grp_roster_continuity fails with both the stated roster and the rebuilt one; another empties the excluded list, and grp_excluded_reconciled fails because the removal is no longer enumerated with a reason.

The determination is recomputed, not read back⁹. A defect file moves the summarised tax by one cent and moves the return total with it, so the rollup is internally consistent and only a recomputation can see the break. rpt_summary_recomputes rebuilds the tax from the trial-balance revenue, the elected deduction, the factor recomputed from the receipts rows and the rate, and fails against the stated figure -- proving the summary is derived from the workpapers rather than trusted as filed.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: combined-return 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 figure, and a cent off the re-derivation is reported as a break.
• A money field 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 margin kernel: the controls and the generator share the kernel in franchise_engine.franchise, so a re-derived tax cannot disagree with the data that produced it.
• The apportionment factor is recomputed from the receipts rows and floored to a basis point, bounded to [0.00%, 100.00%]; flooring can only understate the share the state may tax, never overstate it.
• Every registration-renewal test is measured to the as_of date carried in the file, never to the system clock, so the same file yields the same flags on any day.
• 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 tax, amends a workpaper, contacts a revenue authority, or writes to a source artifact. It reads the combined-return file and stops.¹⁴
• It reads the seven artifacts the combined return emits. It does not connect to a general ledger, a consolidation system, a registration registry or a filing portal.¹⁵
• It proves the roster rebuilds from the prior year plus additions less removals and that every exclusion is reconciled; it does not decide whether the group is correctly drawn under the state's combination and nexus rules. That judgment is a preparer's and a reviewer's.¹⁶
• It re-derives the tax at the elected deduction and the margin-tax rate the file carries, and apportions at the receipts factor those receipts produce; it does not decide whether that election, that rate, or the sourcing of a receipt to the filing state is correct.¹⁷
• It takes the trial balance and receipts records at face value: it confirms they foot, tie and re-derive, not that the revenue was earned or the receipts sourced as stated. All shipped data is fictional -- the combined group, the affiliates, the State of Marran and City of Kelder, the addresses and registrations are invented, and the fiscal year is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.