Configurable per-property tax by region tag + formula

[ParadauxIO]

What

Replaces the single hardcoded property-tax formula with a configurable formula that follows the Taxation Act, plus an optional tag-matched override mechanism for local governments.

Property tax is a single function of an owner's plot count, evaluated once per owner (not per property), rounded down to the nearest cent, with owners of 7 or fewer plots exempt — exactly as the Act specifies.

taxes.yml ships the Act's formula with overrides disabled:

exempt-plot-threshold: 7
rules: []
default-formula: "0.25 * 1.16^<plots> + 0.3 * <plots>^2 + 2.5 * <plots> - 25"

This reproduces the Act's published figures: ~$15.01/day at 8 plots, ~$149.86 at 20, ~$1,267 at 50.

Semantics

• default-formula is the federal tax: the owner's total daily tax as a function of <plots> (their freehold plot count). It is evaluated once on the federally-taxed plot count and floored to the cent; owners at/below exempt-plot-threshold plots pay nothing. exempt-uuids are also honoured.
• rules are optional local-government overrides (the Act's "unless otherwise provided by Local Governments where the plot is located" clause). A freehold region whose tags match a rule (first match, top-to-bottom) is taxed per-property by that rule and is excluded from the federal count. Rules ship empty, so by default the Act applies uniformly to every plot.
• <plots> = the owner's total freehold plot count. match.all — region must carry every listed tag; match.any — at least one; empty/omitted = no constraint. Case-insensitive; tag ids are the tag-ids from region-tags.yml.

How

• TaxFormula — recursive-descent evaluator over <plots>: + - * /, right-associative ^ (incl. a constant base raised to the variable, e.g. 1.16^<plots>), unary minus, parens, decimals. Compile-once / evaluate-many; throws on malformed input.
• TagMatch + TaxRule config records; TaxSettings carries rules, default-formula, exempt-plot-threshold. DEFAULT_FORMULA is the Act's formula.
• PropertyTaxPolicy.taxForOwner(plotTagSets, exemptThreshold) — partitions an owner's plots into federal (no matching rule) and overridden (matched); the federal formula is evaluated once on the federal count above the threshold, per-rule overrides are summed, the total is floored. Bad rule formulas are logged & dropped (that plot falls back to federal); an invalid default falls back to the built-in Act formula; non-finite/non-positive results clamp to zero.
• Backend — TitleHeldRegionTag entity + FreeholdContractMapper.selectTitleHeldRegionTags() (FreeholdContract → Contract → RealtyRegion LEFT JOIN RegionTag). No schema migration needed.
• PropertyTaxListener — enumerates regions, groups by owner, and emits one charge per owner from a single taxForOwner call.

Testing

• PropertyTaxPolicyTest — asserts the Act's behaviour: evaluated once per owner (and explicitly not the old N× value), the ≤7-plot exemption, floor rounding, the published figures ($15.01 @ 8, $149.86 @ 20), the local-override path, case-insensitive matching, bad-formula fallback, and invalid-default fallback.
• TaxFormulaTest — precedence, right-assoc power, and the Act's 1.16^<plots> exponential term + full default formula.
• Backend integration test for the new query (Testcontainers in CI).
• :realty-paper:test green.

Incidental

Fixes a pre-existing compile break in AbstractDatabaseTest — its RealtyBackendImpl name-resolver arg had drifted to an async (CompletableFuture) signature, which was blocking the entire realty-backend test source set.

🤖 Generated with Claude Code