10,3891
Tests
the collected checks that pin this engine's behavior
ENGINE 15
SFS-E15-PPT · PROPERTY TAX CONTROLS · REV 2026-07-24 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Property Tax
Whose parcel is it now?
A homebuilder does not have one property tax bill; it has a parcel that keeps dividing. A project begins as a single parent parcel, is platted into dozens of lots, and then the lots close to buyers one at a time over many months -- and each closing moves exactly one parcel off the developer's books while the county tax roll keeps billing the account it always has. The bill is genuine, the payee is genuinely the county, the amount genuinely matches the notice; the only thing wrong is whose parcel it is, and that fact lives in a closing file the person approving the payment has never seen. On top of that, every jurisdiction runs its own calendar -- its own fiscal year, its own instalment count, its own penalty arithmetic -- so applying one county's habits to another's parcel is how a delinquency is found after the penalty has attached. This engine reads the eight artifacts a property tax cycle emits and runs twenty-six deterministic controls over them: is the roll file complete, does the register carry one live parcel for every lot the plat created, does each charge follow from the assessed value, do the instalments match this jurisdiction's own regime, did the tax follow the ownership through each closing, does the accrual stop at escrow and tie to the ledger, and does what was paid match what was actually owed. It never pays a county, never touches a payables run and never writes to a source artifact.
The failure mode here is not a wrong number; it is a right number billed to the wrong owner. A homebuilder's exposure drifts because the unit of taxation -- the parcel -- and the unit of ownership come apart continuously: a parent parcel is platted into lots, the lots close one at a time, and the roll keeps billing the account it always has. Every ordinary check waves the payment through, because nothing about the invoice is false except whose house it is for, and that fact lives in a closing file the approver never sees. The second failure mode is the calendar: a portfolio across state lines answers to regimes that share no due dates, no instalment count and no penalty arithmetic, so one county's habits applied to another's parcel surface as a delinquency only after the penalty has attached. No control hard-codes a due date or a rate -- each reads the profile for its own parcel's jurisdiction, so a fourth regime is a row, not a patch. The engine ships a planted-defect roll file for every registered control, so the benchmark is a command rather than a claim.
Architecture
functional block stack · static overviewSelect a layer
Seven control families run in registry order over each roll file. The first proves the others had something to read; the rest walk the parcel from the register, through its assessment and instalment calendar, across each closing, into the accrual, and out to what was actually paid.
Key specifications
at a glance85
Artifacts read
regime table, project and parcel registers, assessment history, instalments, closings, accrual, general ledger
What it does for you
plain termsA homebuilder's property tax exposure does not go wrong in the arithmetic on one bill; it goes wrong because the unit of taxation and the unit of ownership come apart, continuously, in a direction nobody is watching. A project starts as one parent parcel, is platted into dozens of lots, and the lots close to buyers one at a time over many months -- and each closing moves exactly one parcel off the developer's books while the county tax roll keeps billing the account it always has. The invoice is genuine, the payee is genuinely the county, the amount genuinely matches the notice; the only thing wrong is whose parcel it is, and that fact lives in a closing file the person approving the payment has never seen. Nothing in the payables cycle catches it. The second failure is the calendar: a developer across state lines answers to regimes that share no due dates, no instalment count and no penalty arithmetic, so applying one jurisdiction's habits to another's parcel is how a delinquency is found after the penalty has already attached. None of these are judgment calls. They are equalities -- a charge against a levy rate, a proration against the days actually held, a due date against a regime, a payment against the period it covers -- which is what a deterministic control settles better than a person approving one genuine-looking bill at a time.
The seeded demo runs every control over every roll file7. The CLI regenerates twenty-eight fictional roll files -- one clean baseline and twenty-seven each carrying a planted defect -- 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.
One closing date, two regimes, two different seller's shares8. A test closes two parcels on the same day in two jurisdictions whose fiscal years open six months apart, and asserts the seller's shares come out in different proportions of the year held -- the cheapest proof that nothing about the calendar is hard-coded, since a single date cannot produce two answers unless the regime, not the code, decides the fiscal year.
The roll kept billing a parcel that had already closed9. A test marks a post-escrow instalment paid on a parcel that closed months earlier; own_no_payment_after_escrow fires because the instalment's due period began after close of escrow, even though the payment is otherwise genuine -- the exact break a payables approver cannot see and a check spanning the closing file catches.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Seeded Roll Files. fictional property tax roll files enter the control registry
- Structural Precondition. is the roll file complete, and are the tax year and review date readable
- Parcel Register. is the register sound, and does it cover the whole plat
- Assessment. does the assessment foot and the charge follow from it
- Instalments. do the instalments match this jurisdiction's calendar
- Ownership & Closings. did the tax follow the ownership through each closing
- Accrual. does the accrual match the charge, stop at escrow and tie to the ledger
- Payment. does what was paid match what was actually owed
- Regime Table & Register. the jurisdiction profiles and parcel register every rule resolves against
- Verdict and Findings. every finding, with the reason it exists, ends at a person
Engineering
- Seeded Roll Files. generate_corpus writes one clean baseline plus twenty-seven planted-defect files, at least one built to trip each registered control, twenty-eight roll files in total. Only the regimes, the projects, the parcels' assessed values and the closings are stated; every annual charge, instalment split, due date, penalty, proration, monthly accrual and ledger balance is derived, so the relationships the engine tests are the same relationships that produced the data.
- Structural Precondition. One control. Fails a file missing any of the eight artifacts, carrying a duplicate, or naming an unreadable as_of or tax_year, so no downstream rule holds vacuously.
- Parcel Register. Five controls: unique parcel numbers, required fields, project mapping, a known regime, and one live parcel per lot the plat created.
- Assessment. Four controls: components tie the total, the charge re-derives from the levy rate, a sharp variance is surfaced for protest, and an exemption cites its authority.
- Instalments. Five controls: shares tie the annual charge, count and dates match the regime, penalty and interest re-derive, no duplicate sequence, and a paid instalment carries a receipt.
- Ownership & Closings. Six controls: the closing names a real parcel, status agrees with the closing file, no payment for a post-escrow period, both prorated shares sum to the charge and re-derive from days held, and a supplemental is recorded where the regime reassesses on transfer.
- Accrual. Four controls: monthly accruals foot to the annual charge, accrual stops at escrow, the total ties the general ledger, and capitalisation matches the project's stage.
- Payment. One control: paid equals the instalment plus any re-derived penalty and interest, at zero tolerance.
- Regime Table & Register. Each jurisdiction's fiscal-year opening, instalment count, due dates and penalty rates, and each parcel's status, jurisdiction and annual charge. The calendar, proration and ownership controls are all evaluated against these two authorities; no due date, instalment count or rate is hard-coded into a control.
- Verdict and Findings. Findings roll up per roll file: any FAIL is FAIL, FLAGs without FAILs are REVIEW, clean is PASS. The CLI exit code is the verdict, so a pipeline can gate on it, and reports carry no timestamps or absolute paths, which is what makes the committed report diffable.
Instruction set
every public command| Command | Operation | Output | Exit | Artifacts |
|---|---|---|---|---|
python run.py | regenerate the seeded fictional corpus, run all twenty-six controls over every roll file, write both reports | per-file verdicts and every actionable finding, then the overall verdict | non-zero for the bundled corpus, which carries a planted defect for every control by design | proptax_report.md, proptax_report.json, samples/ |
python -m proptax_engine samples | analyze an existing folder of roll files without regenerating it | per-file verdicts and findings | 0 PASS / 1 REVIEW / 2 FAIL / 3 usage | none unless --json or --md is passed |
python -m proptax_engine samples --generate --quiet | regenerate the corpus and print only the overall verdict | a single verdict line | 0 PASS / 1 REVIEW / 2 FAIL / 3 usage | samples/ |
python -m pytest | run the full test suite for this engine | 10389 passed | 0 when every test passes | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests10 | 10,389 tests collected live collection from the engine's test directory |
| Registered controls11 | 26 controls counted from the registry, not from documentation |
| Planted defects12 | 27 defect files every registered control has at least one file that trips it |
| Control coverage13 | 100 percent of controls with a planted defect no control ships without a file demonstrating it firing |
Control characteristics
engineeringPlain terms
The engine has no write path and therefore no autonomy to gate. It produces findings; a person decides whether a bill is paid.
Engineering
Deterministic envelope. seeded fictional inputs, read-only operation, offline default mode.
Demo gate. FAIL on the bundled corpus, by design -- it carries a planted defect for every registered control
| Severity | Verdict | Action |
|---|---|---|
| No findings above PASS | PASS | carry the mechanically clean roll into the documented property tax review |
| One or more FLAG, no FAIL | REVIEW | a human resolves each flag; an assessment worth protesting, a missing receipt, an exemption without authority and a capitalisation that disagrees with the project's stage all land here |
| One or more FAIL | FAIL | the roll does not clear until the failing control is resolved -- a payment for a post-escrow period, a proration that does not sum, a due date that is not the jurisdiction's |
- Read-only: roll files are parsed and never written back, so the engine cannot introduce the error it reports.
- Integer cents throughout, compared with exact equality; there is no tolerance band between a proration and the annual charge it must sum to, or between a re-derived penalty and the one on the notice.
- A value 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.
- Deterministic and byte-stable: the same roll file produces the same findings in the same order, made against the as_of carried in the file rather than the system clock, with no timestamps or absolute paths in any output.
- Absent evidence is never a passing control; a missing instalment schedule fails completeness rather than letting the calendar and payment controls pass unread.
Operating limits
what it refuses to do- The engine never pays a county, touches a payables run, or writes to a source artifact. It reports and stops.14
- It reads the eight artifacts a property tax cycle emits. It does not connect to a county assessor, a payables system or a general ledger.15
- It checks that a charge follows from the assessed value, not whether the assessment itself is fair or worth protesting. That judgment, and its deadline, are a reviewer's.16
- It reads each jurisdiction's regime as data and tests conformance to it; whether a profile correctly captures a real statute is a tax question the engine does not answer.17
- All shipped data is fictional -- the portfolio, the states, the counties, the parcels and every assessed value are invented, and the tax year is set in a fictional future. The corpus demonstrates the controls; it is not a record of any real parcel, closing or bill.18
See it run
control architecture
Integration
how to run itDistribution: public repository, MIT license.
Substantiation
- 1python -m pytest --collect-only -q -o addopts= (property-tax-automation/proptax_engine/tests)
- 2len(proptax_engine.engine.REGISTRY)
- 3distinct rule-id prefixes in proptax_engine.engine.REGISTRY
- 4samples/*.json after python run.py
- 5len(proptax_engine.model.DOC_TYPES)
- 6proptax_engine/tests/test_control_semantics.py::test_seller_share_is_re_derived_to_the_cent
- 7python run.py (property-tax-automation/); output re-run on demand
- 8proptax_engine/tests/test_control_semantics.py::test_the_same_closing_date_prorates_differently_by_regime
- 9proptax_engine/tests/test_control_semantics.py::test_paying_a_post_escrow_instalment_fails
- 10python -m pytest --collect-only -q -o addopts= (property-tax-automation/proptax_engine/tests)
- 11len(proptax_engine.engine.REGISTRY)
- 12len(proptax_engine.generate.DEFECTS)
- 13proptax_engine/tests/test_planted_defects.py::test_every_registered_rule_has_a_planted_defect
- 14property-tax-automation/README.md and proptax_engine/tests/test_readonly_and_determinism.py
- 15proptax_engine/model.py DOC_TYPES
- 16proptax_engine/engine.py check_asmt_variance_surfaced
- 17proptax_engine/engine.py check_inst_matches_regime_calendar
- 18proptax_engine/generate.py
Show us where the hours go.
One conversation: you describe the work that consumes your team's month; we tell you plainly what this engine can take over, what it can't, and what a scoped first phase would cost. Your people keep approval authority.
Book a free consultation