Design an Extensible Tax Policy Engine

Problem Statement

Payroll platforms must accurately calculate income taxes across varying jurisdictions, filing statuses, and changing legislative years. Previous years' payroll runs must remain 100% reproducible for auditing purposes, even as new tax rules are introduced.

Design and implement an extensible, in-memory Tax Policy Engine that:

1. Registers Versioned Policies: Identifies policies by a unique key consisting of (tax_type, jurisdiction, tax_year, filing_status).
2. Supports Multiple Calculation Strategies:
   • Progressive Tax: Applies a standard deduction to gross income, then evaluates taxable income across incremental tax brackets (e.g., 10% on the first $10,000, 12% on amounts above $10,000 up to $40,000).
   • Flat Rate Tax: Applies a constant percentage to gross income with no deduction.
3. Financial Precision: Prevents floating-point drift by computing values in integer cents or exact Decimal types, rounding to two decimal places using standard half-up rounding (ROUND_HALF_UP).
4. Reproducibility: Guarantees that passing an older tax year always evaluates using that year's specific policy without being overwritten by newer updates.

Interface

Implement the following classes and engine interface:

from decimal import Decimal
from typing import List, Tuple, Optional

class TaxBracket:
    def __init__(self, upper_limit: Optional[Decimal], rate: Decimal):
        # upper_limit: upper threshold of taxable income for this bracket (None if no cap)
        # rate: tax rate as a decimal (e.g., Decimal("0.10") for 10%)
        self.upper_limit = upper_limit
        self.rate = rate

class TaxPolicyEngine:
    def register_policy(self, policy: 'BaseTaxPolicy') -> None:
        """Registers or updates a policy definition."""
        pass

    def calculate_tax(
        self,
        tax_type: str,
        jurisdiction: str,
        filing_status: str,
        tax_year: int,
        gross_income: Decimal
    ) -> Decimal:
        """Calculates total tax due rounded to two decimal places."""
        pass

Examples

Example 1: Progressive Bracket Policy

• Policy: tax_year=2023, filing_status="single", deduction=Decimal("5000.00")
  • Bracket 1: Up to 10000.00 at 0.10
  • Bracket 2: Over 10000.00 at 0.20
• Input: gross_income = Decimal("25000.00")
• Taxable Income: 25000 - 5000 = 20000
• Computation: (10000 * 0.10) + (10000 * 0.20) = 1000 + 2000 = 3000.00
• Output: Decimal("3000.00")

Example 2: Flat Rate Policy

• Policy: tax_year=2024, tax_type="local_transit", rate=Decimal("0.015")
• Input: gross_income = Decimal("80000.00")
• Output: Decimal("1200.00")

Constraints and Edge Cases

• gross_income >= 0. If gross_income <= deduction, taxable income is 0.00 and tax is 0.00.
• Raise a KeyError or specific domain exception if no policy matches the requested tuple.
• Handle brackets that extend infinitely (upper_limit=None).