Filing Obligation Calendar

Architecture

Key specifications

What it does for you

A group of entities carries a filing obligation in every jurisdiction it touches, and someone has to prove, entity by entity and obligation by obligation, that each return or payment was filed or validly extended before its statutory deadline, that each fixed-amount voucher went out in the exact amount the statute prints, and that the status register ties to the filed evidence with nothing missing and nothing orphaned. A filing calendar is a matrix of dates that was correct the day someone typed it, and four failures hide inside that, none of which look wrong in a grid of dates. A due date is typed a day off, or an extension offset is keyed to the wrong form, and the whole register chases a deadline that is not the statutory one. An obligation is neither filed nor extended, its deadline slides past the review date, and it sits in the register looking like every other open row until it is a late-filing penalty; a return lodged a day after its applicable due date is late in exactly the same invisible way. A row is marked filed with a receipt number but no voucher was archived, or a voucher sits in the archive with no row that claims it, and the count of done no longer means what it says. The annual LLC tax is a statutory constant, and a voucher cut a cent off it is wrong on its face. None of these are judgment calls. They are equalities and comparisons -- a re-derived deadline against a stored one, a filed date against an applicable deadline with exact <=, a stated amount against the statutory constant, a stated status against its re-derivation -- which a deterministic control settles better than a spreadsheet inherited by whoever tracks filings this year. This is the calendar half of the tax story; preparing the return and computing the tax are separate jobs, and this engine takes the finished calendar and checks only that every deadline was met or validly deferred on time.

The seeded demo runs every control over every calendar file⁷. The CLI generates twenty-four fictional calendar files -- one clean baseline and one carrying each of the twenty-three planted defects -- then runs all twenty-two 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 deadline is met at the date, not a day past it⁸. A boundary test files a return one day before, exactly on, and one day after its applicable deadline. ext_filed_on_time fires only on the day-after case and stays silent at the deadline and before, because the comparison is exact <= -- a return filed on the applicable due date is on time and a day past it is late, and ext_applicable_overdue uses the same edge for an unfiled obligation whose deadline lands on the review date. There is no grace band.

The status is recomputed, not read back⁹. A test flips an obligation's stated status to contradict its register dates. rpt_status_recomputes rebuilds the status -- filed, filed-late, overdue, open or not-applicable -- from the obligation's own original and extended due dates and filed date, and fails because the stated determination no longer matches the register, proving the roll-up is recomputed rather than trusted.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: calendar files are parsed and never written back, so the engine cannot introduce the break it reports.
• Whole-month date arithmetic and exact comparison; a deadline is met at the date, not a day past it, and there is no grace band.
• Integer cents throughout, compared with exact equality; a fixed amount a cent off the statutory constant is reported as a break, not absorbed into a tolerance.
• 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 due-date predicate: the controls and the generator share the kernel in filing_engine.duedates, so a recomputed date or status 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 prepares a return, computes a tax, files anything, moves a payment, or writes to a source artifact. It reads the calendar file and stops.¹⁴
• It reads the seven artifacts the calendar process emits. It does not connect to a tax-preparation system, a filing agency, a payment rail or the underlying returns.¹⁵
• It is about whether the deadline was met or validly deferred, not what the return says or what the tax is: preparing the return and computing the tax are separate jobs.¹⁶
• It proves a stored due date re-derives from the statutory table, not that the table itself carries the right offsets or fixed amounts for a given form. That judgment is a reviewer's.¹⁷
• It takes the evidence at face value: it confirms a voucher or acceptance is on file and ties to a row, not that the filing is genuine or the deadline truly satisfied at the agency. All shipped data is fictional and the fiscal year is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.